Creating a Block Mask

Introduction

This section describes techniques for masking any type of block. The techniques are the same whether you mask a Subsystem block, Model block, or S-Function block. The masked block can optionally be included in a user-defined library, as described in Masks on Blocks in User Libraries. When you mask a Model block, one special consideration applies, as described in Masking a Model Block. Masking an S-Function block requires no special provisions. Masking built-in blocks requires some additional steps described in Masking Blocks and Promoting Parameters.

In practice, most masks are subsystem masks, because Model blocks and S-Function blocks already provide a high degree of encapsulation. For simplicity, the instructions and examples in this section refer specifically to a subsystem, and the mask does not dynamically change its dialog box or the subsystem under the mask. Instructions for masks that make dynamic changes begin in Roadmap for Dynamic Masks, which assumes that you understand everything in this section.

This section demonstrates only some of the capabilities of the Mask Editor. See Simulink Mask Editor for complete reference information. The section assumes that you know the definitions in Mask Terminology and are familiar with the Masked Subsystem Example.

This section illustrates the described operations by constructing the mask described in Masked Subsystem Example. You can read the section and apply the operations to your own model, or you can use the section as a tutorial, as follows:

1. Open the unmasked source model by clicking subsystem_example or executing:

   run([docroot '/toolbox/simulink/ug/examples/masking/subsystem_example.mdl'])

2. Save the model in a writable working folder.

3. Optionally open the completed example by clicking masking_example or executing:

   run([docroot '/toolbox/simulink/ug/examples/masking/masking_example.mdl'])

4. Execute the instructions in this section on the copy you made of subsystem_example to implement the capabilities in masking_example.

Back to Top

Opening the Mask Editor

The Simulink Mask Editor provides all of the capabilities necessary for masking a block. To invoke the editor on an unmasked block:

• Select the Subsystem block.

• From the Edit menu or the context menu of the block, choose Mask Subsystem.

The Mask Editor opens:

You can define mask components in any order, as long as the final result is correct. You can also open the Mask Editor on a block that is already masked, as described in Changing a Block Mask.

Applying Changes

Click Apply to make changes within the model, or OK to make changes within the model and close the editor. Save the model to permanently save the changes. If you close the model without saving it, all unsaved Mask Editor changes are lost.

Back to Top

Defining a Mask Icon

A mask icon replaces the standard icon for a masked block when the masked block appears in a model. Mask icons can contain descriptive text, graphics, images, state equations, one or more plots, or a transfer function. Simulink uses the commands and variables that you supply to draw the mask icon.

Use the Mask Editor Icon & Ports pane to specify the icon for a masked block. This pane is always selected by default when you open the Mask Editor. See the Icon & Ports Pane reference for information about all Icon & Ports pane capabilities. This section gives an example of their use.

To define a mask icon, enter:

• Any variables necessary for drawing the icon

• Commands to draw the icon

Variables

For model efficiency, use the Icon & Ports pane to run MATLAB code and to define variables used by the mask icon drawing commands. Simulink executes the MATLAB code in the Icon & Ports pane only when the block icon needs to be drawn. If you include variables used by mask icon drawing commands in the Initialization pane, Simulink evaluates the variables as part of simulation and code generation. For details, see Understanding Mask Code Execution.

Drawing Commands

To draw an icon, enter one or more of the commands described in Mask Icon Drawing Commands in the Icon Drawing commands text box. Use only these commands to draw a mask icon. To see examples of drawing command syntax, use the pull-down list in the Examples of drawing commands pane.

The drawing commands can access all variables defined in the mask workspace.

You can include MATLAB comments at the end of a drawing command or on their own line, as in the following examples:

image(imread('engine.jpg'))   % Use engine icon for subsystem

% Use engine icon for subsystem
image(imread('engine.jpg')) 

If any drawing command cannot successfully execute, the icon displays three question marks.

Example of Defining a Mask Icon

This example illustrates how to define a mask icon that is accurate, regardless of the shape of the block.

The mask icon in masking_example displays a line that reflects the slope of the line modeled in the masked subsystem. To define this icon in your copy of subsystem_example.mdl:

1. Type the following command into the Icon Drawing commands pane:

   pos = get_param(gcb, 'Position');
   width = pos(3) - pos(1);
   x = [0, width];
   y = m*x + b;
   plot(x,y)

2. Under Options, set Icon Units to Pixels.

   The pull-down lists under Options allow you to specify the icon frame visibility, icon transparency, drawing context, icon rotation, and port rotation.

   The Icon & Ports pane now looks like this:

   

3. Click Apply.

If Simulink cannot evaluate all commands in the Icon Drawing commands pane to obtain a displayable result, the content of the icon is three question marks. In masking_example, three question marks appear at this point because the variable m has not yet been defined:

Back to Top

Defining Mask Initialization

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

The masked subsystem initialization code can refer only to variables in its local workspace.

When you reference the block within, or copy the block into, a model, the Mask Parameters dialog box displays the specified default values. You cannot use mask initialization code to change mask parameter default values in a library block or any other block.

Mask Editor Initialization Pane

Use the Mask Editor Initialization pane to enter MATLAB commands that initialize a masked block. Reference information about the Initialization pane appears in Initialization Pane.

The Initialization pane has two sections:

• Dialog variables list

• Initialization commands edit area

Dialog variables

The Dialog variables list displays the names of the variables associated with the mask parameters of the subsystem (that is, 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 MATLAB Command Window.

For information on debugging initialization commands, see Initialization Command Limitations and Debugging Masks That Use MATLAB Code.

Initialization Command Limitations

Mask initialization commands must observe the following rules:

• Do not use initialization code to create dynamic mask dialog boxes (that is, dialog boxes whose appearance or control settings change depending on changes made to other control settings). Instead, use the mask callbacks that are specifically for this purpose. For more information, see Creating Dynamic Mask Dialog Boxes.

• Avoid using set_param commands on blocks residing in another masked subsystem that you are initializing. 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 has initialization code that contains the following command:

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

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

Back to Top

Understanding Mask Parameters

Mask parameters provide the connection between the Mask Parameters dialog box and the underlying block. Each mask parameter appears in the Mask Parameters dialog box as a control, such as an edit box, a pop-up control, a check box, or a data type control. Setting the value of this control sets the value of an associated mask parameter that is defined in the mask workspace. The underlying block specifies that parameter as the value of one or more block parameters, and accesses the value of the corresponding control in the Mask Parameters dialog box. The next figure illustrates this relationship for the masking_example.

In this figure, the Mask Parameters dialog box (top) contains edit-box controls for two parameters: Slope, which is associated with the mask workspace variable m, and Intercept, which is associated with the mask workspace variable b. In the subsystem (bottom), the Gain block named Slope specifies its Gain parameter as m, and the Constant block named Intercept specifies its Constant value parameter as b, as shown in the two Block Parameters dialog boxes (middle).

When the user of the masked block sets the values of Slope and Intercept in the Mask Parameters dialog box, Simulink automatically assigns the mask parameter values to the corresponding mask workspace variables, m and b, respectively. For example, as shown in the diagram above, when the masked block user sets the Slope parameter in the Mask Parameters dialog box to 5, Simulink sets the m variable in the mask workspace to 5. The Gain block uses 5 as its Gain parameter value, because the Gain parameter in the Gain block has a value of m.

Before simulation begins, Simulink tries to resolve the Gain block's Gain parameter m and the Constant block's Constant Value parameter b to numeric values by searching up the workspace hierarchy, as described in Resolving Symbols. Because a mask exists, Simulink searches the mask workspace first. There it finds m and b defined, so it successfully resolves the two block parameters. For example, the Slope parameter in the Mask Parameters dialog box is defined in the Mask Editor to be m, and the Gain parameter in the Gain block is also defined to be m.

If no mask exists (and therefore, no mask workspace), but the subsystem itself does not change, Simulink performs the same hierarchical search seeking a value for m and b, and the search for each value must succeed before simulation can begin. Therefore, the existence of a mask affects hierarchical search only by providing a mask workspace that Simulink searches first.

Back to Top

Defining Mask Parameters

Be sure you have read Understanding Mask Parameters before reading this section. Use the Mask Editor Parameters pane to specify block mask parameters.

For reference information about all Parameters pane capabilities, see the Parameters Pane. This section gives an example of their use.

Parameters appear in the Mask Parameters dialog box in the same order that you define the corresponding parameter definitions in the Dialog parameters table. To define the mask parameters used in the masking_example:

1. Click the Add button at the upper left of the Parameters pane to create a new parameter:

   

   Tip   To promote underlying block parameters to the mask, use the Promote buttons. See Masking Blocks and Promoting Parameters.

2. Edit the Prompt field to specify Slope and the Variable field to specify m:

   

3. Click Add to create a second parameter, and specify its Prompt as Intercept and its Variable as b.

   

4. Click Apply to save the parameter definitions.

Double-click the masked subsystem to see the current Mask Parameters dialog box:

The variables m and b now exist in the mask workspace. The GUI parameters in the Mask Parameters dialog box are mapped to the corresponding workspace variables. By default, these variables are of type double and have a default value of 0. The mask icon now shows an initial Slope of 0:

The Mask Editor parameters pane defines both the individual mask parameters and the organization of the Mask Parameters dialog box. For each mask parameter, a row exists Dialog parameters table on the Parameters pane . The fields in this row are:

• Prompt — A prompt that represents the parameter in the Mask Parameters dialog box

• Variable — A variable in the mask workspace that corresponds to the mask parameter

• Type — The type of control that represents the mask parameter in the Mask Parameters dialog box

• Evaluate — Whether Simulink uses the value of the mask parameter literally, or evaluates it

• Tunable — Whether the parameter is editable (tunable) while simulation is running

• Tab name — The name of the tab, if any, on which the control appears in the mask dialog box

See the Parameters Pane reference for information about all Parameters pane capabilities.

Mask Parameters Dialog Box Callback Code

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

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 Initialization Pane).

The callback can create and reference variables only in the base workspace of the block. If the callback needs the value of a mask parameter, it can use get_param to obtain the value. For example:

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

For information on debugging dialog box callbacks, see Debugging Masks That Use MATLAB Code.

Back to Top

Defining Mask Documentation

A block mask can display three types of documentation. They are all optional, but in practice essentially all masks provide them.

Mask type — A name that appears at the top of the Mask Parameters dialog box. When Simulink displays the Mask Parameters dialog box, it adds (mask) to the mask type. You cannot use newlines in the text.

Mask description — Summary text that describe the purpose of the masked block. The description appears in the Mask Parameters dialog box under the mask type. You can use newlines and multiple blanks for formatting.

Mask help — Provides additional information that appears when the user clicks the Help button on the Mask Parameters dialog box. The text can be:

• Plain text. Use newlines and multiple blanks for formatting.

• HTML text and graphics. Any standard HTML tag can appear.

• A URL that points to information, which can be text or HTML.

• A web or eval command that returns text or HTML to display.

Use the Mask Editor Documentation pane to specify the Mask type, Mask description, and Mask Help for a masked block:

For information about all Documentation pane capabilities, see the Documentation Pane reference.

To specify mask documentation, enter text in the three fields of the Documentation pane. To define the masking_example documentation:

1. Enter the text shown below in the Mask type, Mask description, and Mask help fields:

   

2. Click Apply.

The Mask Parameters dialog box closes if it is open. Double-click the masked subsystem to open the dialog box:

In the Mask Parameters dialog box, the mask type and description now show the text that you entered in the Documentation pane. Simulink adds (mask) to the Mask type to indicate that the dialog box shows a mask rather than a native block dialog box. To see the mask help, click the Help button. The help text appears in the MATLAB Help browser:

You can use the full capabilities of the MATLAB Help browser for the help that you access from a Mask Parameters dialog box.

Back to Top

Using a Block Mask

Once you have completed the operations described above, click OK to apply any final changes to the mask and close the Mask Editor. If you want to save the mask for later examination, save the model. If you close a model without saving it, all unsaved Mask Editor changes are lost.

You can now use the masked Subsystem block mx + b exactly as you could if it were an instance of a built-in block whose capabilities are those of the subsystem and whose interface is that of the mask:

1. Double-click the masked block mx + b.

   The Mask Parameters dialog box opens:

   

2. Change the parameter values so that Slope = 5 and Intercept = 2.

3. Click Apply.

   The Mask Parameters dialog box and the mask icon now look like this:

   

   

When you click Apply, Simulink assigns the value of Slope to the mask workspace parameter m, and the value of Intercept to the mask workspace parameter b, as described in Understanding Mask Parameters. The blocks in the subsystem that reference m and b will use those values during simulation. The mask icon now reflects Slope = 5 via the drawing command plot(x,y), as described in Defining a Mask Icon. The mask documentation is as defined in Defining Mask Documentation.

Back to Top

Mask Terminology

Masking a Model Block

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