Main Content

Get Started with Mask Initialization and Callback Code

Mask initialization enables you to define or modify parameters for the masked block. These parameters can be used within the block diagram to configure the behavior of the underlying subsystem. During the initialization phase, any code or scripts associated with the mask are executed. This can include setting up variables, running MATLAB code, or initializing states that are necessary for the subsystem to function correctly.

Mask initialization can include checks to ensure that the parameters provided by the user are valid. This helps prevent simulation errors and ensures that the subsystem operates within the expected parameters.

Mask initialization can be used to dynamically show or hide parameters based on other parameter values. This can simplify the interface by only presenting relevant options to the user.

When you have a masked block that is used in multiple models, mask initialization ensures that all instances of the block start with the same configuration, promoting consistency and reducing the chance of errors.

When to Author Mask Initialization Code?

Author mask initialization code when you want to:

  • Create new parameter or update an existing parameter in the mask based on the value of mask dialog parameters. This new parameter can be used as the value of child block parameters.

  • Modify the value of mask dialog parameters.

  • Change the subsystem contents structurally or change the value of the child block parameters based on the value of the mask dialog parameters. Use set_param command to do this.

When does Mask Initialization Code Execute?

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

  • Change the mask parameter value and update the diagram or simulate or generate code.

  • Change the value of the parameter and click Apply on mask dialog.

  • Change the value of a parameter using set_param which in turn changes the parameter in the mask dialog. Mask initialization code is executed when Simulink® detects any change in the parameter value.

  • Save the mask using Save Mask in Mask Editor.

  • Rotate or flip the masked block or draw, or redraw block icon in scenarios where the icon drawing depends on initialization code. The initialization code executes only when the Run Initialization property in the Mask Editor Icon pane is set.

When you open a model, Simulink locates visible masked blocks that reside at the top level of the model or in an open subsystem.

Simulink only executes the initialization commands of these visible masked blocks as well as their parent block if they meet either of the following conditions:

  • The masked block has icon drawing commands.

    Note

    Simulink does not initialize masked blocks that do not have icon drawing commands, even if they have initialization commands during model load.

  • The masked subsystem belongs to a library and has the Allow library block to modify its contents parameter enabled.

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

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

Note

The non-tunable parameters of a masked block are not evaluated if the model is already compiled (initialized).

Mask Initialization Best Practices

Mask initialization commands must adhere to the following rules:

  • Do not use initialization code to create dynamic mask dialog boxes (Dialog boxes whose appearance or control settings change depending on changes made to other control settings). Instead, use the mask callbacks. For more information, see Dynamic Mask Dialog Box.

  • Do not use initialization code to add or delete blocks during loading the model.

  • For 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 both could be initializing the same parameter of the block leading to unexpected behavior. For more information, see Unsafe Mask Callback Error.

  • Do not use set_param commands on blocks that reside in another masked subsystem that you are initializing. Trying to set parameters of blocks in child level masked subsystems can trigger unresolved symbol errors if child level masked subsystems reference symbols defined by parent level masked subsystems.

    Suppose, 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. Suppose also that 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 delete the same masked block.

  • 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 section, as these parameters cannot be modified once simulation starts.

Mask Callback Code

In Simulink, a mask callback is a function, or a script associated with a masked block that is executed in response to certain actions or events.

Mask callbacks can be used to update other parameters dynamically based on the changes made to one parameter. This helps in maintaining parameter relationships and dependencies.

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.

Callbacks provide a way to interact with the MATLAB workspace, allowing you to read and write variables to and from the mask parameters. Mask callbacks can be used to execute code at specific points in the simulation process, such as before simulation starts or after it ends, to set up or clean up resources.

When does Mask Callback Code Execute?

Mask parameter callback codes are executed in a temporary workspace and not in the base workspace. If you need a variable created in the callback to be available later (not during callback processing), you must explicitly assign those variables to the base workspace.

Simulink executes the callback commands when there is a change in the value of the parameter. Parameter callbacks are executed in the following scenarios:

  • Open mask dialog box and callback commands execute sequentially, starting with the top mask dialog box.

  • Modify a parameter value in the mask dialog box and then change the mouse or cursor location or, press Apply. For example, you press the Tab key or click into another field in the dialog box after changing the parameter value.

  • Modify the parameter value by using the set_param command.

  • Open the model with Edit Time Warnings and Errors in Diagnostics enabled.

  • If you close a mask dialog box without saving the changes, the Callback command for parameters is executed sequentially.

  • If the callbacks have not run even once then they will run as part of model update.

Note

  • Buttons on mask dialog box are disabled when the callback code associated with the button is being executed.

  • Callback commands do not execute if the mask dialog box is open when the block tool tip appears.

Related Topics