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

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

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

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

Регистрация изменений в дереве

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

В функции добавьте объект обновления файла настроек для каждой версии панели инструментов, содержащей изменения в дереве параметров фабрики. Используйте 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

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

Например, этот код записывает изменения для версии 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Проверьте результаты обновления, чтобы убедиться, что ваши личные настройки перемещены правильно.