addSetting

Add new factory setting

Syntax

s = addSetting(parentgroup,name)

s = addSetting(___,Name,Value)

Description

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

s = addSetting(___,Name,Value) specifies the factory setting properties using one or more name-value pair arguments. For example, 'Hidden',false creates a factory setting that is visible in the factory settings tree. Specify name-value pairs after all other input arguments.

Examples

Add New Factory Setting

Create the root factory group for the toolbox mytoolbox and then add a new setting to the tree.

Create the root factory group mytoolbox.

myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
    'Hidden',false);

Add the setting FontSize and give it a default value.

fontSizeSetting = addSetting(myToolboxFactoryTree,'FontSize','FactoryValue',11,'Hidden',false);

Add Factory 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 root factory group mytoolbox.

myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
    'Hidden',false);

Add the setting FontSize and specify the validation function numericValidationFcn. MATLAB^® throws an error whenever the setting is set to a nonnumeric value.

addSetting(myToolboxFactoryTree,'FontSize','FactoryValue',11,'Hidden',false, ...
    'ValidationFcn',@numericValidationFcn);

Input Arguments

parentgroup — Parent factory group

FactoryGroup object

Parent factory group to add the setting to, specified as a FactoryGroup object. Use the matlab.settings.FactoryGroup.createToolboxGroup function to create the root factory group object.

Example: addSetting(s.mytoolbox,'newSetting')

name — Name of factory setting to add

character vector | string

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

Example: addGroup(parentGroup,'newSetting')

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addSetting(parentGroup,'newGroup','Hidden',false) creates a visible factory group.

FactoryValue — Factory value of setting

MATLAB data

Factory 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. You must specify either a factory value or a factory value function for the setting, but not both.

FactoryValueFcn — Function to set the setting factory value

function handle

Function to set the setting factory value, specified as a function handle. The factory value of the setting is set to the output of the specified function.

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

You can specify either a factory value or a factory value function for the setting, but not both.

Hidden — Hidden state

true (default) | false

Hidden state, specified as true or false.

When set to true, the factory setting does not display in the Command Window or as part of tab completion, although it remains 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 set.

ValidationFcn — Function to validate setting value

function handle

Function to validate a setting value, specified as a function handle. When specified, the function validates the value of the factory 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.

Version History

Introduced in R2019b