Create Custom Settings

Settings provide a way to programmatically store, access, and modify data for the current session or across multiple sessions. By default, MATLAB^® and other MathWorks^® products include settings that can be used to access and modify the appearance and behavior of tools. For example, MATLAB includes settings that enable you to programmatically change the font for certain code tools.

You can create custom settings to store and access your own data across sessions. For example, you can create settings to store the location of an important folder on your system or to keep track of the number of times a file is run.

Add and Remove Settings Groups

Settings are organized into groups. Grouping settings makes it easier to find a specific setting and also provides additional context as to what the setting is used for. For instance, the matlab.editor settings group contains all of the settings specific to the MATLAB Editor. Settings groups are organized into larger groups, forming a tree. At the top of the tree is the root settings group object.

Settings tree hierarchy. At the top of the tree is the root node with two child nodes, matlab and another node labeled with three dots. The matlab node has three child nodes: general, editor, and another node labeled with three dots.

To add a new settings group, use the addGroup function. For example, create the settings group mysettings under the root settings group object.

s = settings;
addGroup(s,'mysettings');
s

s = 
  SettingsGroup with properties:
                   matlab: [1×1 SettingsGroup]
               mysettings: [1×1 SettingsGroup]
    mldrivetripwireaccess: [1×1 SettingsGroup]

To create a hidden settings group that does not appear in the settings hierarchy, for example when you display the parent settings group, specify the 'Hidden' name-value pair. Hidden settings groups do not appear in the parent settings group but can be accessed programmatically. For example, create the settings group myhiddensettings inside mysettings. Notice that myhiddensettings does not display in mysettings.

addGroup(s.mysettings,'myhiddensettings','Hidden',true);
s.mysettings

ans = 
  SettingsGroup 'mysettings' with no properties.

To remove a settings group, use the removeGroup function. For example, remove myhiddensettings.

removeGroup(s,'myhiddensettings');

Add and Remove Settings

To add a new setting, use the addSetting function. For example, add the setting MyWorkAddress to the mysettings settings group.

s = settings;
addGroup(s,'mysettings');
addSetting(s.mysettings,'MyWorkAddress');

Note

Adding settings directly to the root settings group is not supported.

Once you have created a setting, you can give it a value. A setting has several different value types that let you set the value for just the current session or across multiple sessions for an individual user. For more information about these types of values, see Access and Modify Settings.

To specify a value for the setting, set its personal or temporary value. You cannot specify the factory value for a custom setting. For example, specify a personal value for MyWorkAddress.

s.mysettings.MyWorkAddress.PersonalValue = '3 Apple Hill Drive';

You then can use the setting value programmatically in your code.

fprintf('I work at %s.\n', s.mysettings.MyWorkAddress.ActiveValue)

I work at 3 Apple Hill Drive.

To add a hidden setting, use the 'Hidden' name-value pair argument. Hidden settings do not display in the settings hierarchy, for example when you display the parent settings group, but are accessible programmatically. For example, add the hidden setting MyHiddenWorkAddress to the mysettings settings group and set its personal value.

addSetting(s.mysettings,'MyHiddenWorkAddress','Hidden',true, ...
'PersonalValue','1 Lakeside Campus Drive');

You also can add read-only settings using the 'ReadOnly' name-value pair argument. Once you create a read-only setting, you cannot change its temporary or personal value. Therefore, you must specify the personal value for the setting when you add it. For example, add the read-only setting MyBirthDate to the mysettings settings group with a specified personal value.

mydate = datetime('6/1/1990','InputFormat','MM/dd/uuuu');
addSetting(s.mysettings,'MyBirthDate','ReadOnly',true,'PersonalValue',mydate);

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 useful validation functions that can be used to validate settings. This table lists these functions, their meanings, and the MATLAB functions they use.

Name	Meaning	Functions Called on Inputs
`matlab.settings.mustBeStringScalar(A)`	`A` must be a string scalar.	`isStringScalar`
`matlab.settings.mustBeLogicalScalar(A)`	`A` must be a logical scalar.	`islogical`, `isscalar`
`matlab.settings.mustBeNumericScalar(A)`	`A` must be a numeric scalar.	`isnumeric`, `isscalar`
`matlab.settings.mustBeIntegerScalar(A)`	`A` must be an integer scalar.	`isinteger`, `isscalar`
`mustBePositive(A)`	`A > 0`	`gt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonpositive(A)`	`A <= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeFinite(A)`	`A` has no `NaN` and no `Inf` elements.	`isfinite`
`mustBeNonNan(A)`	`A` has no `NaN` elements.	`isnan`
`mustBeNonnegative(A)`	`A >= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNegative(A)`	`A < 0`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonzero(A)`	`A ~= 0`	`eq`, `isnumeric`, `islogical`
`mustBeNonempty(A)`	`A` is not empty.	`isempty`
`mustBeNonsparse(A)`	`A` has no sparse elements.	`issparse`
`mustBeNumeric(A)`	`A` is numeric.	`isnumeric`
`mustBeNumericOrLogical(A)`	`A` is numeric or logical.	`isnumeric`, `islogical`
`mustBeReal(A)`	`A` has no imaginary part.	`isreal`
`mustBeInteger(A)`	`A == floor(A)`	`isreal`, `isfinite`, `floor`, `isnumeric`, `islogical`

To specify a validation function when creating a setting, use the 'ValidationFcn' name-value pair argument and specify the function handle. For example, add the setting MyLogicalSetting to the mysettings settings group and specify that its value must be a logical scalar.

s = settings;
addGroup(s,'mysettings');
addSetting(s.mysettings,'MyLogicalSetting','ValidationFcn',@matlab.settings.mustBeLogicalScalar);

Try setting the value of MyLogicalSetting to a non-logical value. MATLAB returns an error.

s.mysettings.MyLogicalSetting.PersonalValue = 10;

Error setting 'MyLogicalSetting' in group 'mysettings': 
Value must be logical or convertible to logical.

You also can specify a validation function for an entire settings group. When specified, the validation function is used to validate the values of all settings within the group that do not have their own validation functions defined. For example, create the settings group mylogicalsettings and specify the validation function matlab.settings.mustBeLogicalScalar.

addGroup(s.mysettings,'mylogicalsettings','ValidationFcn',@matlab.settings.mustBeLogicalScalar);

Create the setting MyLogicalSetting within the mylogicalsettings group and try setting the value of the setting to a non-logical value. MATLAB returns an error.

addSetting(s.mysettings.mylogicalsettings,'MyLogicalSetting');
s.mysettings.mylogicalsettings.PersonalValue = 10;

Error setting 'MyLogicalSetting' in group 'mysettings': 
Value must be logical or convertible to logical.

Define Custom Validation Functions

You also can create your own validation functions. These can check for properties that are not covered by the MATLAB validation functions. Validation functions are ordinary MATLAB functions that are designed for the purpose of validating settings values. They must:

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 numeric.

function numericValidationFcn(x)
    errorMsg = 'Value must be numeric.'; 
    assert(isnumeric(x),errorMsg);
end

Add the validation function to a new setting.

s = settings;
addGroup(s,'mysettings');
addSetting(s.mysettings,'MyNumericSetting','ValidationFcn',@numericValidationFcn);

Set the value of MyNumericSetting to a non-numeric value. MATLAB returns an error.

s.mysettings.MyNumericSetting.PersonalValue = 'Hello';

Unable to validate settings data. Error using myvalidationFcn (line 3)
Value must be numeric.

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 setting or settings group, see addSetting and addGroup.