addGroup

Add new settings group

Syntax

s = addGroup(parentgroup,name)

s = addGroup(___,Name,Value)

Description

s = addGroup(parentgroup,name) adds a new settings group to the specified parent settings group, and returns a SettingsGroup object containing the new settings group. By default, settings groups are not hidden, which means that they display in the parent settings group.

s = addGroup(___,Name,Value) specifies settings group properties using one or more name-value pair arguments. For example, 'Hidden',true adds a hidden settings group. Specify name-value pairs after all other input arguments.

Examples

Add Settings Group

Use the settings function to access the root of the settings tree and then create the settings group mysettings.

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

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

Add Hidden Settings Group

Use the settings function to access the root of the settings tree and then create the hidden settings group myhiddensettings. Notice that the new group does not appear when you display the parent settings group.

s = settings;
addGroup(s,'myhiddensettings','Hidden',true);
s

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

Although myhiddensettings does not appear in the settings tree, it is accessible. For instance, create the settings group myveryhiddensettings inside myhiddensettings.

addGroup(s.myhiddensettings,'myveryhiddensettings');
s.myhiddensettings

s = 
  SettingsGroup 'matlab.myhiddensettings' with properties:
    myveryhiddensettings: [1×1 SettingsGroup]

Validate Settings in Group

Create a settings group and specify a default validation function. This function validates the values of all settings within the group that do not have their own validation functions defined.

First, create a validation function numericValidationFcn that throws an error when the input is not numeric.

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

Use the settings function to access the root of the settings tree and then create the settings group mynumericsettings. Specify the validation function numericValidationFcn.

s = settings;
newNumericGroup = addGroup(s,'mynumericsettings','ValidationFcn',@numericValidationFcn);

Now, test whether the validation function works. Create the setting MyNonNumericSetting within the mynumericsettings group and set the value of the setting to a non-numeric value. As expected, MATLAB^® throws an error.

addSetting(newvalidatedGroup,'MyNonNumericSetting','PersonalValue','Hello')

Error using matlab.settings.SettingsGroup/addSettingHelper
Unable to validate settings data. Error using numericValidationFcn (line 3)
Value must be numeric.

Error in matlab.settings.SettingsGroup/addSetting (line 74)
    out = obj.addSettingHelper(results,defaultsUsed);

Error in matlab.settings.SettingsGroup/addSetting (line 74)
    out = obj.addSettingHelper(results,defaultsUsed);

Input Arguments

parentgroup — Parent settings group

SettingsGroup object

Parent settings group to add the group to, specified as a SettingsGroup object. Use the settings function to access the root settings group object and all the available settings groups.

name — Name of settings group to add

character vector | string scalar

Name of settings group to add, specified as a character vector or string scalar. If name already exists in the specified parent settings group, MATLAB throws an error.

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: addGroup(parentgroup,'myGroup','Hidden',true) adds a new hidden settings group to the specified parent settings group.

Hidden — Hidden state

false (default) | true

Hidden state, specified as true or false.

When set to true, the settings groups and settings within the group do not display, although they remain accessible.

ValidationFcn — Function to validate settings in group

function handle

Function to validate settings in the group, specified as a function handle. When specified, the function is used to validate the values of all settings within the group that do not have their own validation functions defined.

The function handle must be associated with a function that accepts the potential setting value as an input argument, has no output arguments, and throws an error if the validation fails.

The function handle must point to a function on the MATLAB path. Anonymous or nested function handles are not supported.