主要内容

为工具箱创建出厂设置

如果您创建了一个使用MathWorks的工具箱®下载188bet金宝搏产品时，您可以将“设置”添加到工具箱中，使用户能够自定义安装后工具箱的外观和行为。例如，您可以添加允许用户更改工具箱中的字体大小的设置。

属性来创建出厂设置，以添加包含工具箱附带的出厂值的设置matlab.settings.FactoryGroup.createToolboxGroup函数。安装工具箱后，用户可以使用工厂值，也可以指定自己的个人值或临时值。

为工具箱创建出厂设置包括以下步骤:

  1. 创建出厂设置树。

  2. 创建工厂设置JSON文件。

  3. 测试出厂设置树。

创建出厂设置树

为工具箱创建出厂设置的第一步是创建出厂设置树。使用matlab.settings.FactoryGroup.createToolboxGroup函数为工具箱创建根出厂设置组。例如，为工具箱创建根工厂组mytoolbox．默认情况下，工厂组是隐藏的，这意味着它们不会显示在父设置组中。指定“隐藏”值为的名称-值对假这样组在出厂设置树中可见，无论是在命令窗口中显示还是作为制表符补全的一部分。

myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup(“mytoolbox”，“隐藏”、假);

创建工具箱根工厂组之后，通过将工厂设置和工厂设置组添加到根来创建工厂设置树。若要添加新的出厂设置组，请使用addGroup函数。指定“隐藏”值为的名称-值对假创建一个可见的工厂组。例如，添加字体工厂组作为一个可见组来存储工具箱的字体设置。

toolboxFontGroup = addGroup(myToolboxFactoryTree，“字体”，“隐藏”假)
toolboxFontGroup = FactoryGroup with properties: Name: "font" ValidationFcn:[]隐藏:0

若要添加新的出厂设置，请使用addSetting函数。例如，添加字形大小作为一个可见的工厂设置字体工厂。为设置指定一个出厂值。此值随工具箱一起提供。

addSetting (toolboxFontGroup“字形大小”，“FactoryValue”11“隐藏”假)
ans = FactorySetting with properties: Name: "FontSize" FactoryValue: 11 FactoryValueFcn: [] ValidationFcn: [] Hidden: 0 ReadOnly: 0

属性添加只读设置“只读”名称-值对参数。添加只读设置以防止工具箱用户更改设置值。

将所有的工厂设置树创建命令放在一个没有输入的函数中。在打包和分发工具箱时，将该函数包含在工具箱代码中。例如，函数createMyToolboxFactoryTree.mlx为工具箱创建出厂设置树mytoolbox并添加工厂组字体和两个出厂设置，MyFontSize和MyFontColor，到树。

函数myToolboxFactoryTree = creatatemytoolboxfactorytree ()“mytoolbox”，.．.“隐藏”、假);toolboxFontGroup = addGroup(myToolboxFactoryTree，“字体”，“隐藏”假)addSetting (toolboxFontGroup“MyFontSize”，“FactoryValue”11“隐藏”假)addSetting (toolboxFontGroup“MyFontColor”，“FactoryValue”，“黑”，.．.“隐藏”、假);结束

使用函数验证设置

通过为设置或组指定验证函数，可以对设置值施加特定的限制。验证函数接受潜在的设置值作为参数，如果该值不满足特定要求，则抛出错误。

MATLAB®定义几个验证函数。

名字

意义

在输入上调用的函数

matlab.settings.mustBeStringScalar(一)

一个必须为字符串标量。

isStringScalar

matlab.settings.mustBeLogicalScalar(一)

一个必须为逻辑标量。

islogical，isscalar

matlab.settings.mustBeNumericScalar(一)

一个必须为数值标量。

isnumeric，isscalar

matlab.settings.mustBeIntegerScalar(一)

一个必须为整数标量。

isinteger，isscalar

mustBePositive(一)

一个> 0

gt，伊斯雷尔，isnumeric，islogical

mustBeNonpositive(一)

A <= 0

通用电气，伊斯雷尔，isnumeric，islogical

mustBeFinite(一)

一个没有南也没有正元素。

isfinite

mustBeNonNan(一)

一个没有南元素。

isnan

mustBeNonnegative(一)

A >= 0

通用电气，伊斯雷尔，isnumeric，islogical

mustBeNegative(一)

A < 0

lt，伊斯雷尔，isnumeric，islogical

mustBeNonzero(一)

A ~= 0

情商，isnumeric，islogical

mustBeNonempty(一)

一个不是空的。

isempty

mustBeNonsparse(一)

一个没有稀疏元素。

issparse

mustBeNumeric(一)

一个是数字。

isnumeric

mustBeNumericOrLogical(一)

一个是数字的或逻辑的。

isnumeric，islogical

mustBeReal(一)

一个没有虚部。

伊斯雷尔

mustBeInteger(一)

A ==楼层(A)

伊斯雷尔，isfinite，地板上，isnumeric，islogical

若要在创建出厂设置时指定验证函数，请使用“ValidationFcn”参数，并指定函数句柄。例如，添加设置MyLogicalSetting到myfactorysettings组，并指定其值必须是逻辑标量。

addSetting (s.myfactorysettings“MyLogicalSetting”，“ValidationFcn”，.．.@matlab.settings.mustBeLogicalScalar);

尝试设置的值MyLogicalSetting一个非逻辑的值。正如预期的那样，MATLAB抛出一个错误。

s.myfactorysettings.MyLogicalSetting.PersonalValue = 10
在“myfactorysettings”组中设置“MyLogicalSetting”错误:值必须为logical或可转换为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;
在“mysettings”组中设置“MyLogicalSetting”错误:值必须为logical或可转换为logical。

定义自定义验证函数

您还可以创建自己的验证函数，以检查MATLAB验证函数未覆盖的属性的出厂设置。验证函数是为验证设置值而设计的普通MATLAB函数。它们必须满足以下条件:

  • 接受潜在的设置值作为输入参数。

  • 没有输出参数。

  • 如果验证失败，则抛出错误。

将验证函数放置在MATLAB路径上，使其可用。

例如，创建一个函数来验证设置值是否为偶数。

函数evenNumberValidationFcn(x) errorMsg =“数值必须是偶数。”;Iseven = isnumeric(x) && mod(x, 2) == 0;断言(iseven errorMsg);结束

将此验证功能添加到新设置中。

addSetting (s.mysettings“MyEvenNumberSetting”，“ValidationFcn”, @evenNumberValidationFcn);

设置的值MyEvenNumberSetting变成一个奇数。正如预期的那样，MATLAB抛出一个错误。

s.mysettings.MyEvenNumberSetting.PersonalValue = 1;
无法验证设置数据。使用evenNumberValidationFcn错误(第4行)Value必须是偶数。

您还可以创建自定义验证函数，以使用需要多个输入的MATLAB验证函数，例如mustBeGreaterThan，mustBeLessThan，mustBeGreaterThanOrEqual，mustBeLessThanOrEqual,mustBeMember．例如，此函数验证设置值是否为四种颜色之一。

函数colorValidationFcn(val) mustBeMember(val， [“黑”“蓝”“黄色”“绿色”]);结束

有关将验证函数添加到出厂设置或出厂设置组的详细信息，请参见addSetting和addGroup．

创建出厂设置JSON文件

为了让MATLAB知道使用什么函数来创建出厂设置树，创建一个名为settingsInfo.json．将该文件包含在工具箱中资源文件夹，当您打包和分发工具箱。

settingsInfo.json必须遵循此模板。的ToolboxGroupName和CreateTreeFcn元素是必需的。

{"ToolboxGroupName": "工具箱根工厂组名称"， "隐藏":"工具箱根工厂组的隐藏状态"， "CreateTreeFcn": "工具箱工厂树创建函数， "CreateUpgradersFcn": "工具箱工厂树升级功能"}

请注意

的值ToolboxGroupName和隐藏的必须与工具箱根工厂组名称和隐藏状态匹配。

例如，创建settingsInfo.json文件mytoolbox．指定mytoolbox作为根设置组名，假作为隐藏状态，和createMyToolboxFactoryTree作为设置树的创建功能。

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

测试出厂设置树

创建后的设置树创建函数和settingsInfo.json文件，您可以在打包和分发工具箱之前测试“设置”树，以确保“设置”按预期工作。

要测试树，将包含设置树创建函数的工具箱文件夹和工具箱资源文件夹添加到MATLAB路径中。然后，使用matlab.settings.reloadFactoryFile函数加载工具箱出厂设置和设置函数。这使MATLAB可以访问设置树的根和下面的工具箱工厂设置树。

请注意

为了避免意想不到的结果，必须将包含设置树创建函数的工具箱文件夹和工具箱资源文件夹添加到MATLAB路径中。

例如，测试出厂设置树mytoolbox：

matlab.settings.reloadFactoryFile (“mytoolbox”）;S =设置;s.mytoolbox.font.MyFontSize
ans =设置“mytoolbox.font”。MyFontSize' with properties: ActiveValue: 11 TemporaryValue:  PersonalValue:  InstallationValue:  FactoryValue: 11

请注意

  • 的matlab.settings.reloadFactoryFile函数仅用于调试目的，不应包含在工具箱代码中。

  • 调用后，必须重新创建引用指定工具箱的任何变量matlab.settings.reloadFactoryFile．例如，如果您创建了变量A = s.mytoolbox然后调用matlab.settings.reloadFactoryFile，你必须重新创造一个以访问已更新的设置mytoolbox．

确保工具箱版本之间的向后兼容性

若要创建包含对出厂设置树的修改的工具箱的新版本，可以采取步骤确保在以前安装的工具箱版本中配置的任何个人设置都正确地移动到升级后的出厂设置树。

为了确保修改出厂设置树时的向后兼容性，请遵循以下步骤:

  1. 修改出厂配置树。

  2. 记录对树的更改。

  3. 修改出厂设置JSON文件。

  4. 检查个人设置树升级结果。

可能导致向后不兼容问题的修改包括重命名、移动和删除工具箱工厂设置或设置组。如果要向出厂设置树添加新设置，则不需要执行这些步骤。

警告

对工厂设置树创建功能的更改可能会影响有关工具箱的已保存的个人设置值和临时设置值。为避免数据丢失，请在进行任何更改或升级工具箱之前备份工具箱设置文件。工具箱设置文件，toolboxname.mlsettings，位于首选项文件夹中。要查看首选项文件夹的完整路径，请键入prefdir在MATLAB命令窗口中。

如果在升级后遇到工具箱设置树的意外更改，可以通过将工具箱设置文件替换为您创建的备份来恢复该树。

修改出厂设置树

工厂设置树创建函数为最新的工具箱版本创建设置树。若要更新最新工具箱版本的出厂设置树，请修改出厂设置树创建命令。

请注意

工厂设置树创建函数中的命令代表最新的工具箱版本设置树。

例如，假设在版本中2的mytoolbox，则需要重命名“设置”MyFontSize和MyFontColor来字形大小和FontColor．中的设置名称createMyToolboxFactoryTree.mlx．

函数myToolboxFactoryTree = creatatemytoolboxfactorytree ()“mytoolbox”，.．.“隐藏”、假);toolboxFontGroup = addGroup(myToolboxFactoryTree，“字体”，“隐藏”假)addSetting (toolboxFontGroup“字形大小”，“FactoryValue”11“隐藏”假的,.．.“ValidationFcn”@matlab.settings.mustBeNumericScalar) addSetting (toolboxFontGroup“FontColor”，“FactoryValue”，“黑”，.．.“隐藏”假的,“ValidationFcn”, @matlab.settings.mustBeStringScalar);结束

记录树的更改

创建一个不带输入的函数，用于存储从以前版本的工具箱升级个人设置的指令。在打包和分发工具箱时，将该文件包含在工具箱代码中。记录对出厂设置树的更改可确保工具箱用户升级到新版本时不会出现与其现有工具箱设置向后不兼容的问题。可能导致向后不兼容问题的修改包括重命名、移动和删除工具箱出厂设置或设置组。您不需要记录添加到出厂设置树的新设置。

在函数中，为包含对出厂设置树更改的工具箱的每个版本添加设置文件升级器对象。使用移动和删除函数来记录单个更改。例如，函数createMyToolboxSettingsFileUpgraders.mlx将更改记录为MyFontSize和MyFontColor版本2的mytoolbox．

函数upgraders = createytoolboxsettingsfileupgraders () upgraders = matlab.settings.SettingsFileUpgrader(“Version2”）;移动(升级,“mytoolbox.font.MyFontSize”，“mytoolbox.font.FontSize”）;移动(升级,“mytoolbox.font.MyFontColor”，“mytoolbox.font.FontColor”）;结束

打包分发工具箱给用户后，请勿修改设置树升级功能中已记录的升级说明。修改指令可能会产生意想不到的结果。如果您对设置树进行了额外的更改，请通过将更改附加到现有指令或创建新的升级程序实例来记录更改。

例如，这段代码记录版本的更改2和版本3.的mytoolbox．

函数upgraders = createytoolboxsettingsfileupgraders () upgraders = matlab.settings.SettingsFileUpgrader(“Version2”）;移动(升级,“mytoolbox.font.MyFontSize”，“mytoolbox.font.FontSize”）;移动(升级,“mytoolbox.font.MyFontColor”，“mytoolbox.font.FontColor”）;upupers (2) = matlab.settings. settingsfileupuper (“Version3”）;remove(升级(2),“mytoolbox.font.FontName”）;结束

修改出厂设置JSON文件

为了让MATLAB知道使用什么函数来升级工具箱出厂设置树，请在出厂设置文件中指定设置树升级函数(settingsInfo.json)．例如，在settingsInfo.json为mytoolbox,指定createMyToolboxSettingsFileUpgrader作为设置树的升级功能。

{"ToolboxGroupName": "mytoolbox"， "Hidden": false， "CreateTreeFcn": " createatemytoolboxfactorytree "， "CreateUpgradersFcn": " createatemytoolboxsettingsfileupgraders "}

包括文件createMyToolboxFactoryTree.mlx，createMyToolboxSettingsFileUpgraders.mlx,settingsInfo.json当你包装和分发时mytoolbox．把settingsInfo.json在工具箱里资源文件夹中。

请注意

修改后必须重新启动MATLABsettingsInfo.json文件。

检查个人设置树升级结果

升级工具箱的个人设置后，您可以检查结果以确保正确地进行了升级。若要检查升级结果，请使用matlab.settings.loadSettingsCompatibilityResults函数。

为确保正确地进行升级，请在分发工具箱之前检查升级结果。例如，检查版本的升级结果2的mytoolbox在分发工具箱之前。

  1. 重新加载的出厂设置树mytoolbox．

    matlab.settings.reloadFactoryFile (“mytoolbox”）;

  2. 使用设置函数访问“设置”树的根并验证字形大小设置已从MyFontSize设置。访问工具箱设置将触发个人设置升级过程。

    S =设置;s.mytoolbox.font.FontSize
    ans =设置“mytoolbox.font”。字形大小' with properties: ActiveValue: 15 TemporaryValue:  PersonalValue: 15 InstallationValue:  FactoryValue: 11

  3. 运行matlab.settings.loadSettingsCompatibilityResults函数获取版本的升级结果2的mytoolbox．验证是否存在预验证异常。

    matlab.settings.loadSettingsCompatibilityResults (“mytoolbox”，“Version2”）
    ans = ReleaseCompatibilityResults with properties: VersionLabel: "Version2" PreValidationExceptions: [0×0 matlab.settings. settings.]release asecompatibilityexception] Results: [1×1 matlab.settings.VersionResults]

  4. 访问结果属性确定执行升级操作的次数。

    upgradeResults。结果
    ans = VersionResults with properties: VersionLabel: "Version2" VersionChanges: [1×2 matlab.settings.OperationResult]

  5. 检查每个升级操作的状态，以确保成功执行。

    upgradeResults.Results.VersionChanges.Status
    ans = "成功" ans = "成功"

您还可以在安装工具箱的新版本之后检查升级结果。例如，如果您正在帮助工具箱用户在升级后对其工具箱设置进行故障排除，则此方法非常有用。

例如，假设您有版本1的mytoolbox已安装并已设置个人值的几个设置。安装版本后2的mytoolbox，检查升级结果，以确保您的个人设置已正确移动。

  1. 使用设置函数访问“设置”树的根和工具箱设置。访问工具箱设置将触发个人设置升级过程。

    S =设置;s.mytoolbox
    ans = SettingsGroup 'mytoolbox'属性:font: [1×1 SettingsGroup]

  2. 运行matlab.settings.loadSettingsCompatibilityResults函数获取升级结果。检查所执行的每个升级操作的状态，以确保成功执行。

    upgradeResults = matlab.settings.loadSettingsCompatibilityResults(“mytoolbox”，“Version2”）;upgradeResults.Results.VersionChanges.Status
    ans = "成功" ans = "成功"

请注意

  • 运行matlab.settings.reloadFactoryFile和matlab.settings.loadSettingsCompatibilityResults函数，在再次运行函数之前删除结果日志。删除日志可以确保始终加载正确的升级结果。日志位于首选项文件夹中toolboxname文件夹中。

  • 的matlab.settings.reloadFactoryFile和matlab.settings.loadSettingsCompatibilityResults函数仅用于调试目的，不应包含在工具箱代码中。

监听工具箱设置的更改

如果向工具箱中添加设置以供工具箱用户修改，则可以创建设置侦听器来检测设置值何时发生变化，以便工具箱能够对更改作出反应。要创建设置侦听器，请使用addlistener函数。

属性的设置侦听器mytoolbox.font.FontSize设置。

S =设置;settingListener = addlistener(s.mytoolbox.font，“字形大小”，“PostSet”，.．.@ (src, evnt) disp (“字体大小改变了”));

的值字形大小设置为12．设置该值会触发PostSet事件。

s.mytoolbox.font.FontSize.PersonalValue = 12;
字体大小改变

另请参阅

||

相关的话题