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.

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');

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.

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.

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

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

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

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

function colorValidationFcn(val) 
    mustBeMember(val, ['Black' 'Blue' 'Yellow' 'Green']); 
end