Understanding Mask Code Execution

Specifying Mask Initialization

Drawing Commands Execution

Simulink executes the drawing commands in the Drawing Commands pane in the sequence in which the commands appear whenever you:

• Load the model

• Run or update the block diagram

• Apply any changes made in the Mask Parameters dialog box by clicking Apply or OK.

• Apply any changes made in the Mask Editor by clicking Apply or OK

• Make changes to the block diagram that affect the appearance of the block, such as rotating the block

• Copy the masked block within the same model or between different models

See Understanding Mask Code Execution for information about the execution order of different types of code in a block mask.

Mask Editor Initialization Pane

• A masked subsystem's initialization code can refer only to variables in its local workspace.

When the block is referenced within or copied into a model, the specified default values appear on the block's Mask Parameters dialog box. You cannot use mask initialization code to change mask parameter default values in a library block or any other block.

The Initialization pane enables you to specify initialization commands (see ).

This example demonstrates how to create an improved icon for the mx + b sample masked subsystem discussed earlier in this section. First you must enter the following initialization commands to define the data that enables the drawing command to produce an accurate icon regardless of the shape of the block:

pos = get_param(gcb, 'Position');
width = pos(3) - pos(1); height = pos(4) - pos(2);
x = [0, width];
if (m >= 0), y = [0, (m*width)]; end
if (m < 0),  y = [height, (height + (m*width))]; end

The drawing command that generates this icon is plot(x,y).

Use the Mask Editor Initialization pane to specify block mask initialization commands:

Reference information about the Initialization pane appears in XREF.

Dialog variables

The Initialization pane includes the following controls.

Use the Mask Editor Initialization pane to enter MATLAB commands that initialize a masked block:

The Dialog variables list displays the names of the variables associated with the subsystem's mask parameters, i.e., the parameters defined in the Parameters pane. You can copy the name of a parameter from this list and paste it into the adjacent Initialization commands field, using the Simulink keyboard copy and paste commands. You can also use the list to change the names of mask parameter variables. To change a name, double-click the name in the list. An edit field containing the existing name appears. Edit the existing name and press Enter or click outside the edit field to confirm your changes.

Initialization commands

Enter the initialization commands in this field. You can enter any valid MATLAB expression, consisting of MATLAB functions and scripts, operators, and variables defined in the mask workspace. Initialization commands cannot access base workspace variables. Terminate initialization commands with a semicolon to avoid echoing results to the Command Window. For information on debugging initialization commands, see .

Summary of Initialization Command Execution

When you open a model, initialization commands execute for all masked blocks that are visible because they reside at the top level of the model or in an open subsystem. Initialization commands for masked blocks that are not initially visible execute when you open the subsystem or model that contains the blocks.

When you load a model into memory without displaying the model graphically, no initialization commands initially run for any masked blocks. See Loading a Model and load_system for information about loading a model without displaying it.

Initialization commands for all masked blocks in a model run when you:

• Update the diagram

• Start simulation

• Start code generation.

Initialization commands for an individual masked block run when you:

• Change any of the parameters that define the mask, such as MaskDisplay and MaskInitialization, by using the Mask Editor or set_param.

• Change the appearance of the masked block, for example by resizing or rotating the block.

• Change the value of a mask parameter by using the block dialog or set_param.

• Copy the masked block within the same model or between different models.

Initialization Command Limitations

Mask initialization commands must observe the following rules:

• Do not use initialization code to create dynamic mask dialogs, i.e., dialogs whose appearance or control settings change depending on changes made to other control settings. Instead, use the mask callbacks provided specifically for this purpose (see for more information).

• Avoid prefacing variable names in initialization commands with L_ and M_ to prevent undesirable results. These specific prefixes are reserved for use with internal variable names.

• Avoid using set_param commands to set parameters of blocks residing in masked subsystems that reside in the masked subsystem being initialized. Trying to set parameters of blocks in lower-level masked subsystems can trigger unresolvable symbol errors if lower-level masked subsystems reference symbols defined by higher-level masked subsystems. Suppose, for example, a masked subsystem A contains masked subsystem B, which contains Gain block C, whose Gain parameter references a variable defined by B. Suppose also that subsystem A's initialization code contains the command

  set_param([gcb '/B/C'], 'SampleTime', '-1');

  Simulating or updating a model containing A causes an unresolvable symbol error.

Back to Top

Callback

Enter the MATLAB code that you want the Simulink software to execute when a user applies a change to the selected parameter, i.e., selects the Apply or OK button on the Mask Parameters dialog box. You can use such callbacks to create dynamic dialogs, i.e., dialogs whose appearance changes, depending on changes to control settings made by the user, e.g., enabling an edit field when a user checks a check box (see more information).

Note   Callbacks are not intended to be used to alter the contents of a masked subsystem. Altering a masked subsystem's contents in a callback, for example by adding or deleting blocks or changing block parameter values, can trigger errors during model update or simulation. If you need to modify the contents of a masked subsystem, use the mask's initialization code to perform the modifications (see ).

The callback can create and reference variables only in the block's base workspace. If the callback needs the value of a mask parameter, it can use get_param to obtain the value, e.g.,

if str2num(get_param(gcb, 'g'))<0
	error('Gain is negative.')
end

The Simulink software executes the callback commands when you

• Open the Mask Parameters dialog box. Callback commands execute top down, starting with the top mask dialog parameter

• Modify a parameter value in the Mask Parameters dialog box then change the cursor's focus, i.e., press the Tab key or click into another field in the dialog

  Note   The callback commands are not executed when the parameter value is modified using the set_param command.

• Modify the parameter value, either in the Mask Parameters dialog box or via a call to set_param, than apply the change by clicking Apply or OK. Any mask initialization commands execute after the callback commands. (See .)

• Hover over the masked block to see the block's data tip, when the data tip contains parameter names and values. The callback executes again when the block data tip disappears.

  Note   The callback commands do not execute if the Mask Parameters dialog box is open when the block data tip appears.

For information on debugging dialog callbacks, see .

Back to Top

Mask Initialization Code

The initialization code is MATLAB code that you specify and that the Simulink software runs to initialize the masked subsystem at critical times, such as model loading and the start of a simulation run (see ). You can use the initialization code to set the initial values of the masked subsystem's mask parameters.

Back to Top

Debugging Masks that Use M-Code

You can use MATLAB tools to debug mask initialization commands and dialog callbacks in the Mask Editor or the MATLAB Editor/Debugger.

You can debug initialization commands and parameter callbacks entered directly into the Mask Editor in these ways:

• Remove the terminating semicolon from a command to echo its results to the MATLAB Command Window.

• Place a keyboard commands in the code to stop execution and give control to the keyboard.

You can debug initialization commands and parameter callbacks written in M-files using the MATLAB Editor/Debugger in the same way that you would with any other M-file. When debugging M-file initialization commands, you can view the contents of the mask workspace. When debugging M-file parameter callbacks, you can access only the block's base workspace. If you need the value of a mask parameter, use the get_param command.

You cannot debug icon drawing commands using the MATLAB Editor/Debugger. Use the syntax examples provided in the Mask Editor's Icon pane to help solve errors in the icon drawing commands.

Back to Top

Controlling Masks Programmatically

Creating Dynamic Mask Dialog Boxes

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit