addSetting

Add new setting

Syntax

s = addSetting(parentgroup,name)

s = addSetting(___,Name,Value)

Description

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

s = addSetting(___,Name,Value) specifies setting properties using one or more name-value pair arguments. For example, 'PersonalValue',10 adds a new setting with a personal value of 10. Specify name-value pairs after all other input arguments.

Examples

Add New Setting

Create a settings group and add a new setting to the group. Then, use the value of the setting in your code.

Create the settings group mysettings.

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

Add the setting MyWorkAddress to mysettings and give it a value.

addSetting(s.mysettings,'MyWorkAddress');
s.mysettings.MyWorkAddress.PersonalValue = '3 Apple Hill Drive';
s.mysettings.MyWorkAddress

ans = 
  Setting 'mysettings.MyWorkAddress' with properties:
       ActiveValue: '3 Apple Hill Drive'
    TemporaryValue: <no value>
     PersonalValue: '3 Apple Hill Drive'
      FactoryValue: <no value>

Display the value of the setting.

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

I work at 3 Apple Hill Drive.

Add Hidden Setting

Use the settings function to access the root of the settings tree. Then, create a settings group, add a new hidden setting to the group, and use the value of the setting in your code.

Create the hidden settings group myhiddensettings.

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

Add the setting MyHiddenWorkAddress to myhiddensettings and give it a value. Notice that the new setting does not appear when you display the parent settings group.

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

ans = 
  SettingsGroup 'myhiddensettings' with no properties.

Display the value of the hidden setting.

fprintf("I work at %s.\n", newHiddenGroup.MyHiddenWorkAddress.ActiveValue)

I work at 1 Lakeside Campus Drive.

Add Setting with Validation Function

Create a setting and specify a function to validate its value.

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

Create the settings group mysettings.

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

Add the setting MyNumericSetting to mysettings and specify the validation function numericValidationFcn.

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

Now, test whether the validation function works. Set the value of MyNumericSetting to a non-numeric value. As expected, MATLAB^® throws an error.

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

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

Input Arguments

parentgroup — Parent settings group

SettingsGroup object

Parent settings group to add setting 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 setting to add

character vector | string scalar

Name of setting to add, specified as a character vector or string scalar. If name already exists in the specified 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: addSetting(a,'mySetting','PersonalValue',10,'Hidden',true) adds a new hidden setting with a personal value of 10 to the specified parent settings group.

PersonalValue — Personal value of setting

MATLAB data

Personal value of setting, specified as MATLAB data of any type except for handle types. Data containers such as cell arrays, structs, and objects that include handles are also not supported. This argument is required when creating read-only settings.

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.

ReadOnly — Read-only state

false (default) | true

Read-only state, specified as true or false. When true, the personal or temporary value of the setting cannot be changed. The PersonalValue argument is required when creating read-only settings.

ValidationFcn — Function to validate setting

function handle

Function to validate setting, specified as a function handle. When specified, the function is used to validate the value of the setting.

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.