Документация

Проверьте настройки с помощью функций

Можно наложить определенные ограничения на значения параметров, задав функцию валидации для параметра или группы. Функция валидации принимает потенциальное значение параметра в качестве аргумента и выдает ошибку, если значение не соответствует определенному требованию.

MATLAB^® задает несколько функций валидации.

Чтобы задать функцию валидации при создании заводских настроек, используйте 'ValidationFcn' Аргумент пары "имя-значение" и задайте указатель на функцию. Например, добавьте настройку MyLogicalSetting на myfactorysettings и задайте, что его значение должно быть логическим скаляром.

addSetting(s.myfactorysettings,'MyLogicalSetting','ValidationFcn', ...
    @matlab.settings.mustBeLogicalScalar);

Попробуйте задать значение MyLogicalSetting к нелогическому значению. Как и ожидалось, MATLAB выдает ошибку.

s.myfactorysettings.MyLogicalSetting.PersonalValue = 10

Error setting "MyLogicalSetting" in group "myfactorysettings": Value must be logical or convertible to logical.

Можно также задать функцию валидации для всей группы заводских параметров. Если задано, функция используется для проверки значений всех заводских настроек в группе, которые не задают свои собственные функции валидации. Это включает настройки в подгруппах, если подгруппа или настройки не задают свои собственные функции валидации. Например, создайте группу настроек mylogicalsettings и задайте функцию валидации matlab.settings.mustBeLogicalScalar.

addGroup(s.myfactorysettings,'mylogicalsettings','ValidationFcn', ...
    @matlab.settings.mustBeLogicalScalar);

Создайте настройку MyLogicalSetting в рамках mylogicalsettings и попробуйте задать нелогическое значение параметра. Как и ожидалось, MATLAB выдает ошибку.

addSetting(s.myfactorysettings.mylogicalsettings,'MyLogicalSetting')
s.myfactorysettings.mylogicalsettings.PersonalValue = 10;

Error setting 'MyLogicalSetting' in group 'mysettings': Value must be logical or convertible to logical.

Определите пользовательские функции валидации

Можно также создать собственные функции валидации для проверки заводских настроек на свойства, которые не охвачены функциями валидации MATLAB. Функции валидации являются обычными функциями MATLAB, которые предназначены для проверки значений настроек. Они должны удовлетворять этим условиям:

Поместите функции валидации в путь MATLAB, чтобы сделать их доступными.

Например, создайте функцию, чтобы проверить, является ли значение параметра четным числом.

function evenNumberValidationFcn(x)
    errorMsg = 'Value must be an even number.';
    iseven = isnumeric(x) && mod(x, 2) == 0;
    assert(iseven,errorMsg);
end

Добавьте эту функцию валидации к новому параметру.

addSetting(s.mysettings,'MyEvenNumberSetting','ValidationFcn',@evenNumberValidationFcn);

Установите значение MyEvenNumberSetting на нечетное число. Как и ожидалось, MATLAB выдает ошибку.

s.mysettings.MyEvenNumberSetting.PersonalValue = 1;

Unable to validate settings data. Error using evenNumberValidationFcn (line 4)
Value must be an even number.

Можно также создать пользовательские функции валидации, чтобы использовать функции валидации MATLAB, которые требуют нескольких входов, таких как mustBeGreaterThan, mustBeLessThan, mustBeGreaterThanOrEqual, mustBeLessThanOrEqual, и mustBeMember. Для примера эта функция проверяет, что значение параметра является одним из четырех цветов.

function colorValidationFcn(val) 
    mustBeMember(val, ['Black' 'Blue' 'Yellow' 'Green']); 
end

Для получения дополнительной информации о добавлении функции валидации к заводским настройкам или группе заводских параметров, см. addSetting и addGroup.

Измените дерево заводских настроек

Функция создания дерева заводских настроек создает дерево настроек для последней версии тулбокса. Чтобы обновить дерево заводских настроек для последней версии тулбокса, измените команды создания дерева заводских настроек.

Например, предположим, что в версии 2 от mytoolboxнеобходимо переименовать параметры MyFontSize и MyFontColor на FontSize и FontColor. Измените имена настроек в createMyToolboxFactoryTree.mlx.

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'FontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

Журнал изменений в дереве

Создайте функцию без входов, чтобы сохранить инструкции по обновлению личных настроек из предыдущей версии тулбокса. Включите файл с кодом тулбокса, когда вы упакуете и распределите тулбокс. Запись изменений в дерево заводских параметров гарантирует, что пользователи тулбокса, обновляющиеся до новой версии, не имеют проблем несовместимости с существующими параметрами тулбокса. Изменения, которые могут привести к проблемам несовместимости в обратном направлении, включают переименование, перемещение и удаление заводских параметров тулбокса или группы параметров. Вам не нужно записывать сложение новых настроек в дерево заводских настроек.

В функции добавьте объект upgrader файла настроек для каждой версии тулбокса, который содержит изменения в дереве заводских параметров. Используйте move и remove функций для записи отдельных изменений. Для примера - функция createMyToolboxSettingsFileUpgraders.mlx регистрирует изменения в MyFontSize и MyFontColor для версии 2 от mytoolbox.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2');
    move(upgraders,"mytoolbox.font.MyFontSize","mytoolbox.font.FontSize");
    move(upgraders,"mytoolbox.font.MyFontColor","mytoolbox.font.FontColor"); 

end

Не изменяйте записанные инструкции по обновлению в функции обновления дерева настроек после упаковки и распространения тулбокса среди пользователей. Инструкции по изменению могут иметь неожиданные результаты. Если вы вносите дополнительные изменения в дерево настроек, запишите изменения, добавив их к существующим инструкциям или создав новый образец upgrader.

Для примера этот код записей изменения для версии 2 и версии 3 от mytoolbox.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2');
    move(upgraders,"mytoolbox.font.MyFontSize","mytoolbox.font.FontSize");
    move(upgraders,"mytoolbox.font.MyFontColor","mytoolbox.font.FontColor"); 

    upgraders(2) = matlab.settings.SettingsFileUpgrader('Version3');
    remove(upgraders(2),"mytoolbox.font.FontName"); 
end

Изменение файла JSON заводских настроек

В порядок, чтобы MATLAB знал, какую функцию использовать для обновления дерева настроек фабрики тулбокса, укажите функцию обновления дерева настроек в файле заводских настроек (settingsInfo.json). Для примера, в settingsInfo.json для mytoolbox, задайте createMyToolboxSettingsFileUpgrader как функцию обновления дерева настроек.

{
"ToolboxGroupName" : "mytoolbox",
"Hidden" : false,
"CreateTreeFcn" : "createMyToolboxFactoryTree",
"CreateUpgradersFcn" : "createMyToolboxSettingsFileUpgraders"
}

Включите файлы createMyToolboxFactoryTree.mlx, createMyToolboxSettingsFileUpgraders.mlx, и settingsInfo.json когда вы упаковываете и распределяете mytoolbox. Поместите settingsInfo.json в тулбоксе resources папка.

Просмотр результатов обновления дерева личных настроек

После обновления личных параметров тулбокса можно проверить результаты, чтобы убедиться, что обновление произошло правильно. Чтобы изучить результаты обновления, используйте matlab.settings.loadSettingsCompatibilityResults функция.

Чтобы убедиться, что обновление происходит правильно, исследуйте результаты обновления перед распространением тулбокса. Для примера проверьте результаты обновления версии 2 от mytoolbox перед распределением тулбокса.

Результаты обновления можно также изучить после установки новой версии тулбокса. Этот подход полезен, например, если вы помогаете пользователю тулбокса устранить проблемы с настройками тулбокса после обновления.

Например, предположим, что у вас есть версия 1 от mytoolbox установить и установить личные значения для нескольких настроек. После установки 2 от mytoolboxпроверьте результаты обновления, чтобы убедиться, что ваши личные параметры перемещены правильно.