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

Подтвердите настройки Используя функции

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

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