Create Factory Settings for Toolboxes
If you create a toolbox that works with MathWorks® products, you can add settings to the toolbox that enable users to customize the appearance and behavior of the toolbox after installation. For example, you can add a setting that allows a user to change the font size in your toolbox. After installing your toolbox, users can either use the factory values or specify their own personal or temporary values.
You can create factory settings for toolboxes using these steps:
Create the factory settings tree.
Create the factory settings JSON file.
Test the factory settings tree.
Create Factory Settings Tree
The first step to creating factory settings for a toolbox is to create the factory
settings tree. Use the matlab.settings.FactoryGroup.createToolboxGroup
function to create
the root factory settings group for a toolbox. For example, create the root factory
group for the toolbox mytoolbox
. By default, factory groups are
hidden, which means that they do not display in the parent settings group. Specify
the Hidden
name-value argument as false
so
that the group is visible in the factory settings tree, either when displayed in the
Command Window or as part of tab completion.
myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup("mytoolbox",Hidden=false);
Once the toolbox root factory group is created, create the factory settings tree
by adding factory settings and factory settings groups to the root. To add a new
factory settings group, use the addGroup
function. Specify the Hidden
name-value
argument as false
to create a visible factory group. For example,
add the font
factory group as a visible group to store the font
settings for your toolbox.
toolboxFontGroup = addGroup(myToolboxFactoryTree,"font",Hidden=false)
toolboxFontGroup = FactoryGroup with properties: Name: "font" ValidationFcn: [] Hidden: 0
To add a new factory setting, use the addSetting
function. For example, add FontSize
as
a visible factory setting in the font
factory group. Specify a
factory value for the setting. This value ships with the toolbox.
addSetting(toolboxFontGroup,"FontSize",FactoryValue=11,Hidden=false)
ans = FactorySetting with properties: Name: "FontSize" FactoryValue: 11 FactoryValueFcn: [] ValidationFcn: [] Hidden: 0 ReadOnly: 0
You also can add read-only settings using the ReadOnly
name-value argument. Add read-only settings to prevent toolbox users from changing
the settings values.
Place all the factory settings tree creation commands in a function with no
inputs. Include the function file with your toolbox code when you package and
distribute the toolbox. For example, the function
createMyToolboxFactoryTree
creates the factory settings tree
for the toolbox mytoolbox
and adds the factory group
font
and two factory settings, MyFontSize
and MyFontColor
, to the tree.
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
Create Factory Settings JSON File
To specify the function that creates the factory settings tree for the toolbox,
create a JSON file named settingsInfo.json
. Include the file in
the toolbox resources
folder when you package and distribute the
toolbox.
settingsInfo.json
must follow this template. The
ToolboxGroupName
and CreateTreeFcn
elements are required.
{ "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" }
Note
The values for ToolboxGroupName
and
Hidden
must match the toolbox root factory group name and
hidden state.
For example, create the settingsInfo.json
file for
mytoolbox
. Specify the root settings group name as
mytoolbox
, the hidden state as false
, and
the settings tree creation function as
createMyToolboxFactoryTree
.
{ "ToolboxGroupName" : "mytoolbox", "Hidden" : false, "CreateTreeFcn" : "createMyToolboxFactoryTree" }
Test Factory Settings Tree
After creating the settings tree creation function and the
settingsInfo.json
file for your toolbox, you can test the
settings tree before packaging and distributing the toolbox to verify that the
settings are working as expected.
Note
You must add the toolbox folder that contains the settings tree creation
function and the toolbox resources
folder to the MATLAB® path.
To test the tree, use the matlab.settings.reloadFactoryFile
function to load your toolbox factory settings. The settings
function gives MATLAB access to the root of the settings tree and your toolbox factory
settings tree underneath it.
For example, test the factory settings tree for
mytoolbox
.
matlab.settings.reloadFactoryFile("mytoolbox");
s = settings;
s.mytoolbox.font.myFontSize.PersonalValue = 15;
s.mytoolbox.font.MyFontSize
ans = Setting 'mytoolbox.font.MyFontSize' with properties: ActiveValue: 15 TemporaryValue: <no value> PersonalValue: 15 InstallationValue: <no value> FactoryValue: 11
Note
The
matlab.settings.reloadFactoryFile
function is meant for debugging purposes only. Do not include the function in shipping toolbox code.You must re-create any variables that reference the specified toolbox after calling
matlab.settings.reloadFactoryFile
. For example, if you create the variablea = s.mytoolbox
and then callmatlab.settings.reloadFactoryFile
, you must re-createa
to access the updated settings formytoolbox
.
Validate Settings Using Functions
You can impose specific restrictions on settings values by specifying a validation function for a setting or group. A validation function accepts a potential setting value as an argument and throws an error if the value does not meet a specific requirement.
MATLAB defines several validation functions that you can use to validate settings.
Name | Meaning | Functions Called on Inputs |
---|---|---|
| ||
| ||
| ||
| ||
| ||
| ||
|
| |
|
| |
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
| |
|
To specify a validation function when creating a factory setting, use the
ValidationFcn
name-value argument and specify the function
handle. For example, add the setting MyLogicalSetting
to the
mytoolbox
group and specify that its value must be a logical
scalar.
addSetting(s.mytoolbox,"MyLogicalSetting",ValidationFcn= ... @matlab.settings.mustBeLogicalScalar);
Try setting the value of MyLogicalSetting
to a nonlogical
value. As expected, MATLAB throws an error.
s.mytoolbox.MyLogicalSetting.PersonalValue = 10
Error setting 'MyLogicalSetting' in group 'mytoolbox': Value must be logical or convertible to logical.
You also can specify a validation function for an entire factory settings group.
When specified, the function validates the values of all factory settings within the
group that do not specify their own validation functions. The specified function
also validates settings in subgroups, as long as the subgroup or settings do not
specify their own validation functions. For example, create the settings group
mylogicalsettings
and specify the validation function
matlab.settings.mustBeLogicalScalar
.
addGroup(s.mytoolbox,"mylogicalsettings",ValidationFcn= ... @matlab.settings.mustBeLogicalScalar);
Create the setting MyLogicalSetting
within the
mylogicalsettings
group and try setting its value to a
nonlogical value. As expected, MATLAB throws an error.
addSetting(s.mytoolbox.mylogicalsettings,"MyLogicalSetting")
s.mytoolbox.mylogicalsettings.MyLogicalSetting.PersonalValue = 10;
Error setting 'MyLogicalSetting' in group 'mytoolbox.mylogicalsettings': Value must be logical or convertible to logical.
Define Custom Validation Functions
You can create your own validation functions to check factory settings for characteristics that are not covered by the MATLAB validation functions. Validation functions are ordinary MATLAB functions that are designed for validating the values of settings. They must satisfy these conditions:
Accept the potential setting value as an input argument.
Have no output arguments.
Throw an error if the validation fails.
Place validation functions on the MATLAB path to make them available.
For example, create a function to validate whether the value of a setting is an even number.
function evenNumberValidationFcn(x) errorMsg = "Value must be an even number."; iseven = isnumeric(x) && mod(x,2) == 0; assert(iseven,errorMsg); end
Add this validation function to a new setting.
addSetting(s.mytoolbox,"MyEvenNumberSetting",ValidationFcn=@evenNumberValidationFcn);
Set the value of MyEvenNumberSetting
to an odd number. As
expected, MATLAB throws an error.
s.mytoolbox.MyEvenNumberSetting.PersonalValue = 1;
Unable to validate settings data. Error using assert Value must be an even number.
You also can create custom validation functions to make use of MATLAB validation functions that require multiple inputs, such as
mustBeGreaterThan
, mustBeLessThan
, mustBeGreaterThanOrEqual
,
mustBeLessThanOrEqual
, and
mustBeMember
. For example, this
function validates that the value of a setting is one of four colors.
function colorValidationFcn(val) mustBeMember(val,["Black" "Blue" "Yellow" "Green"]); end
For more information about adding a validation function to a factory setting
or factory settings group, see addSetting
and addGroup
.
Ensure Backward Compatibility Across Toolbox Versions
To create a new version of your toolbox that includes modifications to the factory settings tree, you can take steps to ensure that any personal settings configured in a previously installed version of the toolbox are properly moved to the upgraded factory settings tree.
To ensure backward compatibility when making modifications to the factory settings tree, follow these steps:
Modify the factory settings tree.
Log changes to the tree.
Modify the factory settings JSON file.
Examine personal settings tree upgrade results.
Modifications that can cause backward incompatibility issues include renaming, moving, and removing toolbox factory settings or settings groups. If you are adding new settings to the factory settings tree, then you do not need to follow these steps.
Caution
Changes to the factory settings tree creation function can affect the saved
personal and temporary values of settings for the toolbox. To save a copy of the
values of your settings, back up your toolbox settings file before making any
changes or before upgrading your toolbox. The toolbox settings file,
, is
located in your settings folder. To see the full path for the settings folder,
enter toolboxname
.mlsettingsprefdir
in the MATLAB Command Window.
If you experience unexpected changes to a toolbox settings tree after an upgrade, you can restore the tree by replacing the toolbox settings file with the backup that you created.
Modify Factory Settings Tree
To update the factory settings tree for the latest toolbox version, modify the factory settings tree creation functions.
Note
The commands in the factory settings tree creation function represent the latest toolbox version settings tree.
For example, suppose that in version 2
of
mytoolbox
, you want to rename the settings
MyFontSize
and MyFontColor
to
FontSize
and FontColor
. Change the
settings names in createMyToolboxFactoryTree
.
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
Log Changes to Tree
Create a function with no inputs to store the instructions for upgrading the personal settings from a previous version of the toolbox. Include the file with your toolbox code when you package and distribute the toolbox. Logging changes to the factory settings tree supports backward compatibility for a toolbox with modified settings.
In the function, add a settings file upgrader object for each version of the
toolbox that contains changes to the factory settings tree. Use the move
and remove
functions to log individual changes. For example, the
function createMyToolboxSettingsFileUpgraders
logs the
changes to MyFontSize
and MyFontColor
for
version 2
of 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
Do not modify logged upgrade instructions in the settings tree upgrade function after packaging and distributing the toolbox to your users. Modifying instructions can have unexpected results. If you make additional changes to the settings tree, log the changes by appending them to the existing instructions or by creating a new upgrader instance.
For example, this code logs changes for version 2
and
version 3
of
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
Modify Factory Settings JSON File
To specify the function that upgrades the factory settings tree for the
toolbox, add the settings tree upgrade function to the factory settings file
(settingsInfo.json
). For example, in
settingsInfo.json
for mytoolbox
,
specify the settings tree upgrade function as
createMyToolboxSettingsFileUpgraders
.
{ "ToolboxGroupName" : "mytoolbox", "Hidden" : false, "CreateTreeFcn" : "createMyToolboxFactoryTree", "CreateUpgradersFcn" : "createMyToolboxSettingsFileUpgraders" }
Note
You must restart MATLAB after changing the settingsInfo.json
file.
Examine Personal Settings Tree Upgrade Results
After upgrading the personal settings of a toolbox, you can examine the upgrade results to verify that the upgrade occurred as intended. Be sure to examine the upgrade results before distributing the toolbox.
For example, examine the upgrade results for version 2
of
mytoolbox
before distributing the toolbox.
Reload the factory settings tree for
mytoolbox
.matlab.settings.reloadFactoryFile("mytoolbox");
Use the
settings
function to access the root of the settings tree and verify that the personal value for theFontSize
setting was moved over from theMyFontSize
setting as intended. Accessing your toolbox settings triggers the personal settings upgrade process.s = settings; s.mytoolbox.font.FontSize
ans = Setting 'mytoolbox.font.FontSize' with properties: ActiveValue: 15 TemporaryValue: <no value> PersonalValue: 15 InstallationValue: <no value> FactoryValue: 11
Run the
matlab.settings.loadSettingsCompatibilityResults
function to get the upgrade results for version2
ofmytoolbox
. Verify that there are no prevalidation exceptions.upgradeResults = matlab.settings.loadSettingsCompatibilityResults("mytoolbox","Version2")
upgradeResults = ReleaseCompatibilityResults with properties: VersionLabel: "Version2" PreValidationExceptions: [0×0 matlab.settings.ReleaseCompatibilityException] Results: [1×1 matlab.settings.VersionResults]
Access the
Results
property to determine the number of upgrade operations performed.upgradeResults.Results
ans = VersionResults with properties: VersionLabel: "Version2" VersionChanges: [1×2 matlab.settings.OperationResult]
Check the status of each upgrade operation.
upgradeResults.Results.VersionChanges.Status
ans = "Succeeded" ans = "Succeeded"
You also can examine upgrade results after you have installed a new version of a toolbox. This approach is useful, for example, if you are helping a toolbox user troubleshoot their toolbox settings after an upgrade.
For example, suppose that you have version 1
of
mytoolbox
installed and have set personal values for
several settings. After installing version 2
of
mytoolbox
, examine the upgrade results to ensure that
your personal settings moved over as expected.
Use the
settings
function to access the root of the settings tree and your toolbox settings. Accessing your toolbox settings triggers the personal settings upgrade process.s = settings; s.mytoolbox
ans = SettingsGroup 'mytoolbox' with properties: font: [1×1 SettingsGroup]
Run the
matlab.settings.loadSettingsCompatibilityResults
function to get the upgrade results. Check the status of each upgrade operation.upgradeResults = matlab.settings.loadSettingsCompatibilityResults("mytoolbox","Version2"); upgradeResults.Results.VersionChanges.Status
ans = "Succeeded" ans = "Succeeded"
Note
After running the
matlab.settings.reloadFactoryFile
andmatlab.settings.loadSettingsCompatibilityResults
functions, delete the log of results before running the functions again. Deleting the log allows MATLAB to load the latest upgrade results.. The log is located in the settings folder, in the
folder.toolboxname
The
matlab.settings.reloadFactoryFile
andmatlab.settings.loadSettingsCompatibilityResults
functions are meant for debugging purposes only. Do not include the functions in shipping toolbox code.
Listen for Changes to Toolbox Settings
If you add settings to your toolbox for toolbox users to modify, you can create
settings listeners to detect when a setting value changes so that your toolbox can
react to the change. To create a setting listener, use the addlistener
function.
For example, create a setting listener for the
mytoolbox.font.FontSize
setting.
s = settings; settingListener = addlistener(s.mytoolbox.font,"FontSize","PostSet", ... @(src,evnt)disp("Font size changed"));
Set the value of the FontSize
setting to 12
.
Setting the value triggers the PostSet
event on the
setting.
s.mytoolbox.font.FontSize.PersonalValue = 12;
Font size changed
See Also
matlab.settings.reloadFactoryFile
| matlab.settings.loadSettingsCompatibilityResults
| matlab.settings.FactoryGroup.createToolboxGroup