Создайте заводские настройки для тулбоксов

Если вы создаете тулбокс, который работает с продуктами MathWorks®, можно добавить настройки в тулбокс, которые позволяют пользователям настроить внешний вид и поведение тулбокса после установки. Например, можно добавить установку, которая позволяет пользователю изменять размер шрифта в тулбоксе.

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

Создание заводских настроек для тулбоксов включает эти шаги:

  1. Создайте дерево заводских настроек.

  2. Создайте заводские настройки файл JSON.

  3. Протестируйте дерево заводских настроек.

Создайте дерево заводских настроек

Первый шаг к созданию заводских настроек для тулбокса должен создать дерево заводских настроек. Используйте matlab.settings.FactoryGroup.createToolboxGroup функция, чтобы создать корневую группу заводских настроек для тулбокса. Например, создайте корневую группу фабрики для тулбокса mytoolbox. По умолчанию группы фабрики скрыты, что означает, что они не отображаются в родительской группе настроек. Задайте 'Hidden' пара "имя-значение" со значением false так, чтобы группа отобразилась в дереве заводских настроек, или, когда отображено в Командном окне или как часть заполнения клавишей Tab.

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

Если корневая группа фабрики тулбокса создается, создайте дерево заводских настроек путем добавления заводских настроек и групп заводских настроек к корню. Чтобы добавить новую группу заводских настроек, используйте addGroup функция. Задайте 'Hidden' пара "имя-значение" со значением false создать видимую группу фабрики. Например, добавьте font группа фабрики как видимая группа, чтобы сохранить параметры шрифта для вашего тулбокса.

toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
toolboxFontGroup = 
  FactoryGroup with properties:

             Name: "font"
    ValidationFcn: []
          Hidden: 0

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

addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false)
ans = 

  FactorySetting with properties:

               Name: "FontSize"
       FactoryValue: 11
    FactoryValueFcn: []
      ValidationFcn: []
             Hidden: 0
           ReadOnly: 0

Также можно добавить настройки только для чтения с помощью 'ReadOnly' аргумент пары "имя-значение". Добавьте настройки только для чтения, чтобы препятствовать тому, чтобы пользователи тулбокса изменили значения настроек.

Поместите все команды создания дерева заводских настроек в функции без входных параметров. Включайте функцию со своим кодом тулбокса, когда вы группируете и распределите тулбокс. Например, функциональный createMyToolboxFactoryTree.mlx создает дерево заводских настроек для тулбокса mytoolbox и добавляет группу фабрики font и две заводских настройки, MyFontSize и MyFontColor, к дереву.

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

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'MyFontSize','FactoryValue',11,'Hidden',false)    
    addSetting(toolboxFontGroup,'MyFontColor','FactoryValue','Black', ...
        'Hidden',false);
end

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

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

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

Имя

Значение

Функции, обращенные входные параметры

matlab.settings.mustBeStringScalarA

A должен быть строковый скаляр.

isStringScalar

matlab.settings.mustBeLogicalScalarA

A должен быть логический скаляр.

islogical, isscalar

matlab.settings.mustBeNumericScalarA

A должен быть числовой скаляр.

isnumeric, isscalar

matlab.settings.mustBeIntegerScalarA

A должен быть целочисленный скаляр.

isinteger, isscalar

mustBePositiveA

A > 0

gt, isreal, isnumeric, islogical

mustBeNonpositiveA

A <= 0

ge, isreal, isnumeric, islogical

mustBeFiniteA

A не имеет никакого NaN и никакой Inf элементы.

isfinite

mustBeNonNanA

A не имеет никакого NaN элементы.

isnan

mustBeNonnegativeA

A >= 0

ge, isreal, isnumeric, islogical

mustBeNegativeA

A < 0

lt, isreal, isnumeric, islogical

mustBeNonzeroA

A ~= 0

eq, isnumeric, islogical

mustBeNonemptyA

A не пусто.

isempty

mustBeNonsparseA

A не имеет никаких разреженных элементов.

issparse

mustBeNumericA

A isnumeric.

isnumeric

mustBeNumericOrLogicalA

A является числовым или логическим.

isnumeric, islogical

mustBeRealA

A не имеет никакой мнимой части.

isreal

mustBeIntegerA

A == floor(A)

isreal, isfinite, floor, isnumeric, islogical

Чтобы задать функцию валидации при создании заводской настройки, используйте '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.

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

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

settingsInfo.json должен следовать за этим шаблоном. ToolboxGroupName и CreateTreeFcn элементы требуются.

{
"ToolboxGroupName" : "toolbox root factory group name",
"Hidden" : "hidden state of toolbox root factory group",
"CreateTreeFcn" : "toolbox factory tree creation function", 
"CreateUpgradersFcn" : "toolbox factory tree upgrade function"
}

Примечание

Значения для ToolboxGroupName и Hidden должен совпадать с корневым названием группы фабрики тулбокса и скрытым состоянием.

Например, создайте settingsInfo.json файл для mytoolbox. Задайте mytoolbox как корневое название группы настроек, false как скрытое состояние и createMyToolboxFactoryTree как функция создания дерева настроек.

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

Протестируйте дерево заводских настроек

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

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

Примечание

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

Например, чтобы протестировать дерево заводских настроек на mytoolbox:

matlab.settings.reloadFactoryFile('mytoolbox');
s = settings;
s.mytoolbox.font.MyFontSize
ans = 
  Setting 'mytoolbox.font.MyFontSize' with properties:
       ActiveValue: 11
    TemporaryValue: <no value>
     PersonalValue: <no value>
      FactoryValue: 11

Примечание

  • matlab.settings.reloadFactoryFile функция предназначается для отладки целей только и не должна быть включена в поставляющийся код тулбокса.

  • Необходимо воссоздать любые переменные, которые ссылаются на заданный тулбокс после вызова matlab.settings.reloadFactoryFile. Например, если вы создаете переменную a = s.mytoolbox и затем вызовите matlab.settings.reloadFactoryFile, необходимо воссоздать a получить доступ к обновленным настройкам для mytoolbox.

Обеспечьте обратную совместимость через версии тулбокса

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

Чтобы гарантировать обратную совместимость при создании модификаций к дереву заводских настроек, выполните эти шаги:

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

  2. Регистрируйте изменения в дереве.

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

  4. Исследуйте персональные результаты обновления дерева настроек.

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

Предупреждение

Изменения в функции создания дерева заводских настроек могут влиять на сохраненные личностные и временные ценности настроек для рассматриваемого тулбокса. Чтобы избежать потери данных, поддержите свой файл настроек тулбокса прежде, чем внести любые изменения или прежде, чем обновить ваш тулбокс. Файл настроек тулбокса, toolboxname.mlsettings, расположен в вашей папке настроек. Чтобы видеть полный путь для папки настроек, введите prefdir в командном окне MATLAB.

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

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

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

Примечание

Команды в функции создания дерева заводских настроек представляют последнее дерево настроек версии тулбокса.

Например, предположите это в версии 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 после изменения settingsInfo.json файл.

Исследуйте персональные результаты обновления дерева настроек

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

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

  1. Перезагрузите дерево заводских настроек для mytoolbox.

    matlab.settings.reloadFactoryFile('mytoolbox');
  2. Используйте settings функционируйте, чтобы получить доступ к корню дерева настроек и проверить что личностная ценность для FontSize установка была правильно отодвинута от MyFontSize установка. Доступ к вашим настройкам тулбокса инициировал персональный процесс обновления настроек.

    s = settings;
    s.mytoolbox.font.FontSize
    ans = 
      Setting 'mytoolbox.font.FontSize' with properties:
           ActiveValue: 15
        TemporaryValue: <no value>
         PersonalValue: 15
          FactoryValue: 11
  3. Запуститесь matlab.settings.loadSettingsCompatibilityResults функция, чтобы получить обновление заканчивается для версии 2 из mytoolbox. Проверьте, что нет никаких исключений перед валидацией.

    matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2')
    ans = 
      ReleaseCompatibilityResults with properties:
                   VersionLabel: "Version2"
        PreValidationExceptions: [0×0 matlab.settings.ReleaseCompatibilityException]
                        Results: [1×1 matlab.settings.VersionResults]
  4. Доступ к Results свойство определить количество выполняемых операций обновления.

    upgradeResults.Results
    ans = 
      VersionResults with properties:
          VersionLabel: "Version2"
        VersionChanges: [1×2 matlab.settings.OperationResult]
  5. Проверяйте состояние каждой операции обновления, чтобы гарантировать, что они выполнялись успешно.

    upgradeResults.Results.VersionChanges.Status
    ans = 
        "Succeeded"
    
    ans = 
        "Succeeded"
    

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

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

  1. Используйте settings функционируйте, чтобы получить доступ к корню дерева настроек и ваших настроек тулбокса. Доступ к вашим настройкам тулбокса инициировал персональный процесс обновления установки.

    s = settings;
    s.mytoolbox
    ans = 
      SettingsGroup 'mytoolbox' with properties:
        font: [1×1 SettingsGroup]

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

    upgradeResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
    upgradeResults.Results.VersionChanges.Status
    ans = 
        "Succeeded"
    
    ans = 
        "Succeeded"
    

Примечание

  • После выполнения matlab.settings.reloadFactoryFile и matlab.settings.loadSettingsCompatibilityResults функции, удалите журнал результатов прежде, чем запустить функции снова. Удаление журнала гарантирует, что правильные результаты обновления всегда загружаются. Журнал расположен в папке настроек в toolboxname папка.

  • matlab.settings.reloadFactoryFile и matlab.settings.loadSettingsCompatibilityResults функции предназначаются для отладки целей только и не должны быть включены в поставляющийся код тулбокса.

Прислушайтесь к изменениям в настройках тулбокса

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

Например, создайте прослушиватель настроек для mytoolbox.font.FontSize установка.

s = settings;
settingListener = addlistener(s.mytoolbox.font,'FontSize','PostSet', ...
    @(src,evnt)disp('Font size changed'));

Установите значение FontSize установка на 12. Установка значения инициировала PostSet событие на установке.

s.mytoolbox.font.FontSize.PersonalValue = 12;
Font size changed

Смотрите также

| |

Похожие темы

Для просмотра документации необходимо авторизоваться на сайте