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.

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 directory.

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 subsystem_example to implement the capabilities shown in the masking_example.

Back to Top

Opening the Mask Editor

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

• Select the block.

• Choose Mask BlockType from the Edit menu or the block's context menu.

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 block that is already masked, as described in Changing a Block Mask. Click Apply to make changes within the model, or OK to make changes within the model and close the editor. To permanently save changes, you must save the model itself. 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 a masked block's standard icon 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 code that you supply to draw the mask icon.

Use the Mask Editor's Icon & Ports pane to specify the icon for a masked block. This pane is always selected by default when you open the editor. The previous figure shows its initial appearance. See the Icon & Ports Pane reference for information about all Icon & Ports pane capabilities. This section gives an example of their use.

To specify the contents of a mask icon, enter one or more of the commands described in Mask Icon Drawing Commands in the Drawing Commands pane. You must use only these commands to draw a mask icon. An error occurs if a command not listed in Mask Icon Drawing Commands appears in the Drawing Commands pane. The drawing commands can access all variables defined in the mask workspace. To see examples of drawing command syntax, use the pulldown in the Examples of drawing commands pane.

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

1. Type the following command into the Drawing Commands pane:

   plot([0 1],[0 m]+(m<0))

2. Under Icon Options, set Units to Normalized.

   The Icon pane now looks like this:

   

3. Click Apply.

This plot command plots a line from (0,0) to (1,m). If the slope of the line is negative, the line is shifted up by 1 to keep it within the visible drawing area of the block. Setting Icon Units to Normalized tells Simulink to draw the icon in a frame whose bottom-left corner is (0,0) and whose top-right corner is (1,1).

If Simulink cannot evaluate all commands in the 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:

The pulldowns under Icon Options allow you to specify the icon frame visibility, icon transparency, drawing context, icon rotation, and port rotation. See the Icon & Ports Pane reference for information about these and all other Icon & Ports pane capabilities.

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: an edit box, a pop-up, or a checkbox. 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 thus 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 dialogs (middle).

When you set 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. Thus in the Mask Workspace above, m = Slope = 5, and b = Intercept = 2.

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: Gain = m = Slope = 5, and Constant value = b = Intercept = 2.

If no mask existed, and hence no mask workspace, but the subsystem itself was unchanged, Simulink would perform the same hierarchical search seeking a value for m and b, and the search for each value would have to succeed before simulation could begin. Thus 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:

See the Parameters Pane reference for information about all Parameters pane capabilities. This section gives an example of their use.

The parameters pane defines both the individual mask parameters and the organization of the Mask parameters dialog box. For each mask parameter, a row exists in the Parameters pane Dialog parameters table. 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 dialog box.

• Evaluate — Whether the value of the mask parameter is used literally or evaluated

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

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

Parameters appear in the Mask Parameters dialog box in the same order that the corresponding parameter definitions appear 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:

   

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.

   

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:

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

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 masked block's Mask Parameters dialog box. When Simulink displays a masked block's Mask Parameters dialog box, it suffixes (mask) to the mask type. No newlines can appear in the text.

Mask description — Summary text that describe the block's purpose or function. The description appears in the masked block's dialog box under the mask type. Newlines and multiple blanks can appear for formatting.

Mask help — Provides additional information that appears when the user clicks the Help button on the mask 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's Documentation pane to specify the Mask type, Mask description, and Mask Help for a masked block:

See the Documentation Pane reference for information about all Documentation pane capabilities. This section gives an example of their use.

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:

The Mask type and Mask description now show the specified text. Simulink suffixes (mask) to the Mask type to indicate that the dialog box shows a mask rather than a native block dialog. To see the Mask Help, click the Help button. The Help text appears in the Online Help browser:

The full capabilities of MATLAB Online Help are available after you access the browser by clicking Help in a Mask Parameters dialog box.

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

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([0 1],[0 m]+(m<0)), 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