Introduction to Mask Initialization and Parameter Callback Code

Mask initialization code and parameter callback code enable you to programmatically control the block mask. Mask initialization code configures the block, modifies the contents of your subsystem dynamically, and sets the parameters of child blocks within the subsystem. For each masked block, Simulink^® creates a unique instance of a MATLAB workspace, known as the mask workspace. This mask workspace stores the evaluated values of the mask parameters. Simulink executes the mask initialization code within the context of this mask workspace.

Mask parameter callback code dynamically shows or hides the parameters based on the values of other parameters, or dynamically changes a popup option. This simplifies the mask dialog box by presenting only relevant options to the user. Mask parameter callbacks execute in a temporary workspace. To learn how to specify mask initialization and parameter callback code, see Author Mask Initialization and Callbacks.

Mask Editor showing parameter callback code in the Code tab.

Mask Initialization Code

When to Author Mask Initialization Code?

Author mask initialization code when you want to:

Dynamically change the subsystem contents structurally. For more information see Allow Masked Subsystems Inside a Masked Subsystem Reference to Self-Modify.
Change the value of child block parameters based on the value of the mask dialog parameters. Use the set_param function in the mask initialization code instead of <parameter>.value. To use the value of a parent block in a child block, promote parameters from the child block to the parent block's mask dialog box instead of using set_param.
Define a new variable in the mask initialization code that is computed from existing parameters in the mask. Avoid updating existing parameters by the mask by using mask initialization code due to loss of tunability. If you need to update an existing parameter on the mask then follow the steps described in Tune Mask Enumeration Parameters - Popup and Radio Button.

When to Avoid Authoring Mask Initialization Code

Using mask initialization code is not appropriate in all situations:

Do not use mask initialization code to verify and validate the mask parameter values. Use mask constraints. For more information, see Constraints.
Do not modify the mask icon using mask drawing commands in the mask initialization section. Use mask display for changing the mask icon. Alternatively, use the Graphical Icon Editor to create SVG icons for masked blocks. For more information, see Create and Edit Block Mask Icon.

When does Mask Initialization Code Execute?

Initialization commands for all masked blocks in a model run to bring the block to the desired state. If there is a change in the value of the block parameter, initialization commands execute to bring the block and its nested blocks in the desired state. Initialization code executes in these scenarios:

Updating the diagram, simulating the model, or generating code. If the mask workspace is up to date, to optimize performance, Simulink does not execute the mask initialization code.
Changing the value of a parameter using set_param and clicking Apply in the mask dialog box.
Making any change to the mask definition, including saving mask from Mask Editor.
In scenarios where the icon drawing depends on initialization code. Simulink does not execute initialization code for masked blocks that do not have icon drawing commands while loading the model.
Note
Use the Run Initialization property in the Mask Editor Icon pane to execute the initialization code.
Simulink executes not only the initialization commands of the visible masked blocks but their parent block as well.
For self-modifying library blocks, the mask initialization code executes only when Simulink instantiates or loads the block for the first time. In this case, the Allow library block to modify its contents parameter must be enabled.

When you load a model into memory without displaying the model graphically, initialization commands are not executed for the masked blocks except for library blocks with self-modifiable masks. See Load a Model and load_system for information about loading a model without displaying it.

The order of execution of initialization code during model update is model InitFcn, block InitFcn, and then block mask initialization.

Rules for Mask Initialization Code

Mask initialization code must follow these rules:

Do not use initialization code to create dynamic mask dialog boxes whose appearance or control settings change depending on changes made to other control settings. Instead, use mask callbacks. For more information, see Dynamic Mask Dialog Box.
For a nested masked subsystem, do not use set_param on a parent block from a child block. The child block mask and the parent block mask can both initialize the same parameter of the block leading to unexpected behavior. For more information, see Unsafe Mask Callback Error.
Do not use set_param code on parameters that reside in another masked subsystem that you are initializing. When you try to set parameters of blocks in child-level masked subsystems, you can trigger unresolved symbol errors. This happens if child-level masked subsystems reference symbols defined by parent-level masked subsystems.
For example, a masked subsystem A contains a masked subsystem B which contains Gain block C, whose Gain parameter references a variable defined by B. Subsystem A has initialization code that contains this command:
```
set_param([gcb '/B/C'], 'SampleTime', '-1');
```
Simulating or updating a model containing A causes an unresolved symbol error.
Do not use mask initialization code to create data objects. Data objects are objects of these classes:
- Simulink.Parameter and subclasses
- Simulink.Signal and subclasses
Do not add initialization code to a masked block that results in the block deleting itself.
When you reference a block, or copy a block into a model, the mask dialog box displays the specified default values. Do not use mask initialization code to change mask parameter default values in a library block or any other block.
Do not use mask initialization code to comment or uncomment a block.
Avoid unconditionally modifying the contents of a subsystem from the mask initialization code. Such unconditional modification does not work properly when using model reference.
Avoid using clear commands for clearing variables in mask initialization code.
Do not modify parameters at model level such as StartTime and SolverJacobianMethodControl in mask initialization code , because these parameters cannot be modified once simulation starts.
Avoid checking simulation status to run a specific code snippet.
Do not re-evaluate the parameters using slresolve. All the parameters are evaluated and are available in the mask workspace.
Do not set the mask parameters of the block in the initialization code. Simulink gets the new value of the mask parameters in subsequent mask workspace update.

Mask Parameter Callback Code

A mask parameter callback executes specific MATLAB code in response to a change in mask parameter value.

Callbacks can control the visibility, enablement, and interactivity of parameters in the mask dialog, allowing for a more responsive and user-friendly interface. Mask callbacks can automate tasks such as updating display labels, setting block properties, or initializing states when a parameter is changed.

When to Author Parameter Callback Code?

Author parameter callback code when you want to:

Update a dependent parameter automatically. For example, if you have a parameter area that depends on another parameter length, use callback code to recalculate and set area when length changes.
Change the appearance or visibility of mask parameters based on the value of another parameter.
Perform initialization or configuration tasks when a parameter changes.

When Does Mask Callback Code Execute?

Simulink executes the callback code for a parameter when the value of the parameter changes. Mask parameter callback code is executed in a temporary workspace. Callback code in a nested subsystem executes sequentially. When you open the mask dialog box, the callback code of the top mask dialog box executes first.

Parameter callback code is executed in these scenarios:

Modifying a parameter value in the mask dialog box or by using set_param, and then changing cursor location or, clicking Apply. For example, when you press the Tab key or click into another field in the dialog box after changing the parameter value, the callbcak code executes.
Opening the model with Edit Time Warnings and Errors enabled in the Diagnostics pane of the Configuration Parameters dialog box.
Closing a mask dialog box without saving the changes. The callback code for each parameters is executed sequentially to revert to its initial state.
Performing a model update, if the callback code has never run previously.
Opening the Property Inspector and selecting a masked block.

Rules for Parameter Callback Code

Mask parameter callback commands must adhere to the following rules:

Do not modify the structure of the subsystem by using parameter callback code. Use mask initialization code instead.
Do not change the type of a mask parameter.