Documentation

Mask Editor Overview

A mask is a custom user interface for a block that hides the block's contents, making it appear to the user as an atomic block with its own icon and parameter dialog box.

The Mask Editor dialog box helps you create and customize the block mask. The Mask Editor dialog box opens when you create or edit a mask. You can access the Mask Editor dialog box by any of these options:

To create mask,

  • Click Diagram > Mask > Create Mask.

  • Right-click the block and select Mask > Create Mask.

To edit mask,

  • Click Diagram > Mask > Edit Mask.

  • Right-click the block and select Mask > Edit Mask.

    Note:   You can also use the keyboard shortcut CTRL + M to open Mask Editor.

The Mask Editor dialog box contains a set of tabbed panes, each of which enables you define a feature of the mask. These tabs are:

Icon & Ports Pane

The Icon & Ports pane helps you to create a block icon that contains descriptive text, state equations, image, and graphics.

The Icon & Ports pane is divided into these sections:

  • Options: Provides a list of different controls that can be applied on the mask icon.

  • Preview: Displays the preview of the block mask icon.

  • Icon drawing commands: Enables you to draw mask icon by using MATLAB code.

Options

Options available in the left pane are a list of controls that allow you to specify attributes on the mask icon. These options are,

Block frame.  The block frame is the rectangle that encloses the block. You can choose to show or hide the frame by setting the Block Frame parameter to Visible or Invisible. The default is to make the block frame visible. For example, this figure shows visible and invisible block frames for an AND gate block.

Icon transparency.  The icon transparency can be set to Opaque, Opaque with ports, or Transparent, based on whether you want to hide or show what is underneath the icon. The default option Opaque hides information such as port labels. The block frame is displayed for a transparent icon, and hidden for the opaque icon.

For a subsystem block, if you set the icon transparency to Opaque with ports the port labels are visible.

    Note:   If you set the icon transparency to Transparent, Simulink® does not hide the block frame even if you set the Block Frame property to Invisible.

Icon units.  This option controls the coordinate system used by the drawing commands. It applies only to the plot and text drawing commands. You can select from among these choices: Autoscale, Normalized, and Pixel.

  • Autoscale scales the icon to fit the block frame. When the block is re-sized, the icon is also re-sized. For example, this figure shows the icon drawn using these vectors:

    X = [0 2 3 4 9]; Y = [4 6 3 5 8];
    

    The lower-left corner of the block frame is (0,3) and the upper-right corner is (9,8). The range of the x-axis is 9 (from 0 to 9), while the range of the y-axis is 5 (from 3 to 8).

  • Normalized draws the icon within a block frame whose bottom-left corner is (0,0) and whose top-right corner is (1,1). Only X and Y values between 0 and 1 appear. When the block is re-sized, the icon is also re-sized. For example, this figure shows the icon drawn using these vectors:

    X = [.0 .2 .3 .4 .9]; Y = [.4 .6 .3 .5 .8];
    

  • Pixel draws the icon with X and Y values expressed in pixels. The icon is not automatically re-sized when the block is re-sized. To force the icon to re-size with the block, define the drawing commands in terms of the block size.

Icon rotation.  When the block is rotated or flipped, you can choose whether to rotate or flip the icon or to have it remain fixed in its original orientation. The default is not to rotate the icon. The icon rotation is consistent with block port rotation. This figure shows the results of choosing Fixed and Rotates icon rotation when the AND gate block is rotated.

Port rotation.  This option enables you to you specify a port rotation type for the masked block. The choices are:

  • default

    Ports are reordered after a clockwise rotation to maintain a left-to-right port numbering order for ports along the top and bottom of the block and a top-to-bottom port numbering order for ports along the left and right sides of the block.

  • physical

    Ports rotate with the block without being reordered after a clockwise rotation.

The default rotation option is appropriate for control systems and other modeling applications where block diagrams typically have a top-down and left-right orientation. It simplifies editing of diagrams, by minimizing the need to reconnect blocks after rotations to preserve the standard orientation.

Similarly, the physical rotation option is appropriate for electronic, mechanical, hydraulic, and other modeling applications where blocks represent physical components and lines represent physical connections. The physical rotation option more closely models the behavior of the devices represented (that is, the ports rotate with the block as they would on a physical device). In addition, the option avoids introducing line crossings as the result of rotations, making diagrams easier to read.

For example, the following figure shows two diagrams representing the same transistor circuit. In one, the masked blocks representing transistors use default rotation and in the other, physical rotation.

Both diagrams avoid line crossings that make diagrams harder to read. The next figure shows the diagrams after a single clockwise rotation.

    Note:   The rotation introduces a line crossing the diagram that uses default rotation but not in the diagram that uses physical rotation. Also that there is no way to edit the diagram with default rotation to remove the line crossing. See Flip or Rotate a Block for more information.

Preview

This section displays the preview of block mask icon. Block mask preview is available only if the mask contains an icon drawing.

When you add an icon drawing command and click Apply, the preview image refreshes and is displayed in the Preview section of Icon & Ports pane.

Icon drawing commands

The Icon drawing commands text box available in the center pane enables you to add code to draw the block icon. You can use the list of commands mentioned in the Mask icon drawing commands tables to draw a block icon.

Mask icon drawing commands

Drawing CommandDescriptionSyntax ExamplePreview
color

Change drawing color of subsequent mask icon drawing commands

color('red'); port_label('output',1,'Text')
disp

Display text on the masked icon.

disp('Gain')
dpoly

Display transfer function on masked icon

dpoly([0 0 1], [1 2 1], 'z')
droots

Display transfer function on masked icon

droots([-1], [-2 -3], 4)
fprintf

Display variable text centered on masked icon

fprintf('Sum = %d', 7)
image

Display RGB image on masked icon

    Note:   To add mask icon from the user interface, click Mask > Add Mask Icon in the context menu.

image('b747.jpg')
patch

Draw color patch of specified shape on masked icon

patch([0 10 20 30 30 0], [10 30 20 25 10 10],[1 0 0])
plot

Draw graph connecting series of points on masked icon

plot([10 20 30 40], [10 20 10 15])
port_label

Draw port label on masked icon

port_label('output', 1, 'xy')
text

Display text at specific location on masked icon

    Note:   You must select Pixels in the Icon units box.

text(5,10, 'Gain')

    Note:   Simulink does not support mask drawing commands within anonymous functions.

The drawing commands execute in the same sequence as they are added in the Icon drawing commands text box. Drawing commands have access to all variables in the mask workspace. If any drawing command cannot successfully execute, the block icon displays question masks .

The drawing commands execute after the block is drawn in these cases:

  • Changes are made and applied in the mask dialog box.

  • Changes are made in the Mask Editor.

  • Changes are done to the block diagram that affects the block appearance, such as rotating the block.

Parameters & Dialog Pane

The Parameters & Dialog pane enables you to design mask dialog boxes using the dialog controls in the Parameters, Display, and Action palettes.

The Parameters & Dialog pane divided into these sections:

Parameter & Dialog Pane

SectionSection DescriptionSub-SectionSub-Section Description
ControlsControls are elements in a mask dialog box that users can interact with to add or manipulate data.ParameterParameters are user inputs that take part in simulation. The Parameters palette has a set of parameter dialog controls that you can add to a mask dialog box.
DisplayControls on the Display palette allow you to group dialog controls in the mask dialog box and display text and images
ActionAction controls allow you to perform some actions in the mask dialog box. For example, you can click a hyperlink or a button in the mask dialog box.
Dialog boxYou can click or drag and drop dialog controls from the palettes to the Dialog box to create a mask dialog box.NANA
Property editorThe Property editor allows you to view and set the properties for the Parameters, Display, and Action controls.PropertiesDefines basic information on all dialog controls, such as Name, Value, Prompt, and Type.
AttributesDefines how a mask dialog control is interpreted. Attributes are related only to parameters.
DialogDefines how dialog controls are displayed in the mask dialog box.
LayoutDefines how dialog controls are laid out on the mask dialog box.

Controls

The controls section is sub divided into Parameters, Display, and Action sections. The Controls Table lists out the different controls and their description.

Controls Table

ControlsDescription

Parameters

Edit

Allows you to enter a parameter value by typing it into the field.

Check box

Accepts a Boolean value.

Popup

Allows you to select a parameter value from a list of possible values.

Radio button

Allows you to select a parameter value from a list of possible values. All options for a radio button are displayed on the mask dialog.

Slider

Allows you to slide to values within a range defined by minimum and maximum values. You can type a number or a variable name as value for the slider.

You can also control the slider range dynamically. For more information, see slexMaskParameterOptionsExample.

Dial

Allows you to dial to values within a range defined by minimum and maximum values. You can type a number or a variable name as value for the dial.

You can also control the dial range dynamically. For more information, see slexMaskParameterOptionsExample.

Spinbox

Allows you to spin through values within a range defined by minimum and maximum values. You can specify a step size for the values.

DataTypeStr

Enables you to specify a data type for a mask parameter. For more details, see DataTypeStr Parameter.

Min

Specifies a minimum value for the parameter.

Max

Specifies a maximum value for the parameter. If you add a Max parameter after a Min parameter, it appears in the same row in the mask dialog box.

Promote parameter

Allows you to selectively promote block parameters from underlying blocks to the mask. Click the Type options field to open the Promoted Parameter Selector dialog box. In this dialog box, you can select the block parameters that you want to promote. Click OK to close it.

Promote all

Allows you to promote all underlying block parameters to the mask. When you promote all parameters, the promote operation deletes parameters that have been promoted previously.

Display

Panel

Container to group of dialog controls. You use a Panel for logical grouping of dialog controls.

Group box

Container to group other dialog controls and containers in the mask dialog box.

Tab

Tab to group dialog controls in the mask dialog box. A tab is contained within a tab container. A tab container can have multiple tabs.

CollapsiblePanel

Container to group dialog controls similar to Panel. You can choose to expand or collapse the CollapsiblePanel dialog controls.

For more information, see Dialog Layout Options

Text

Text displayed in the mask dialog box.

Image

Image displayed in the mask dialog box.

Action

Hyperlink

Hyperlink text displayed on the mask dialog box.

Button

Button controls on the mask dialog box. You can program button for specific actions. You can also add an image on a button controls. For more information, see slexMaskParameterOptionsExample.

Dialog box

You can build a hierarchy of dialog controls by dragging them from a Controls section to the Dialog box. You can also click the palettes on the Controls section to add the required control to the Dialog box. You can add a maximum of 32 levels of hierarchy in the Dialog box.

The Dialog box displays three fields: Type, Prompt, and Name.

  • The Type field shows the type of the dialog control and cannot be edited. It also displays a sequence number for parameter dialog controls.

  • The Prompt field shows the prompt text for the dialog control.

  • The Name field is auto-populated and uniquely identifies the dialog controls. You can choose to add a different value (valid MATLAB name) in the Name field.

The Parameter controls are displayed in light blue background whereas the Display and Action controls are displayed in white background on the Dialog box.

You can move a dialog control in the hierarchy, you can copy and paste a dialog control, you can also delete a node. For more information, see Dialog Control Operations.

Property editor

The Property editor allows you to view and set the properties for Parameter, Display, and Action dialog controls. The Property editor for Parameter is shown below:

You can set the following properties for Parameter, Action, and Display dialog controls. For more information, see the Property editor table.

Property editor

PropertyDescription
Properties

Name

Uniquely identifies the dialog control in the mask dialog box. The Name property must be set for all dialog controls.

Value

Value of the Parameter dialog control. The Value property applies only to the Parameter dialog controls.

Prompt

Label text that identifies the parameters in a mask dialog box. The Prompt property applies to all dialog controls except Panel and Image dialog control.

Type

Type of the dialog control. You can change the Type field only for the Parameter dialog controls.

Expand

Allows you to specify if the collapsible panel dialog control is expanded or collapsed, by default.

Type options

The Type options property allows you to set specific Parameter properties. The Type options property applies to the Popup, Radio button, DataTypeStr, and Promoted parameters.

File path

You can add an image to a mask using the Image dialog control. You can also display an image on a Button dialog control. In either case, provide the path to the image in the File path property that is enabled for these two dialog controls. For the Button dialog control, specify an empty character vector for the Prompt property in order for the image to be displayed.

Word wrap

The Word wrap property enables word wrapping for long text. The Word wrap property applies only for Text dialog control.

Maximum and Minimum

The Maximum and Minimum properties enable you to specify a range for controls like Spinbox, Slider, and Dial.

Step size

Allows you to specify a step size for the values. This property applies only for Spinbox dialog control.

Attributes

Evaluate

Simulink uses the value of a mask parameter as you type it in the mask dialog box, or it can evaluate what you specify and use as the result of the evaluation. Select the Evaluate option for a parameter to specify parameter evaluation (the default). Clear the option to suppress evaluation.

Tunable

By default, you can change a mask parameter value during simulation. To prohibit changing of parameter value during simulation, clear the Tunable option. If the masked parameter does not support parameter tuning, Simulink ignores the Tunable option setting of a mask parameter. Such parameters are then disabled on the Mask Editor. We can specify the type of parameter where tunable is disabled. For information about parameter tuning and the blocks that support it, see Tune and Experiment with Block Parameter Values.

Read only

Indicates that the parameter cannot be modified.

Hidden

Indicates that the parameter must not be displayed in the mask dialog box.

Never save

Indicates that the parameter value never gets saved in the model file.

Dialog box

Enable

By default Enable is selected. If you clear this option, the selected control becomes unavailable for edit. Masked block users cannot set the value of the parameter.

Visible

The selected control appears in the mask dialog box only if this option is selected.

Callback

MATLAB code that you want Simulink to execute when a user applies a change to the selected control. Simulink uses the base workspace to execute the callback code.

Layout

Item location

Allows you to set the location for the dialog control to appear in the current row or a new row.

Prompt location

Allows you to set the prompt location for the dialog control on either the top or to the left of the dialog control.

You cannot set the Prompt location property for Check box, Dial, DataTypeStr, Collapsible Panel and Radiobutton.

Orientation

Allows you to specify horizontal or vertical orientation for sliders and radio buttons.

Horizontal Stretch

If this option is selected, the controls on the mask dialog box stretch horizontally when you resize the mask dialog box. By default, Horizontal Stretch check box is selected.

For more information, see Horizontal Stretch Property.

Initialization Pane

The Initialization pane allows you to add MATLAB commands that initialize the masked block.

When you open a model, Simulink locates the visible masked blocks that reside at the top level of the model or in an open subsystem. Simulink only executes the initialization commands for these visible masked blocks 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.

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

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

  • Update the diagram

  • Start simulation

  • Start code generation

  • Click Apply on the dialog box

Initialization commands for an individual masked block run when you:

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

  • Rotate or flip the masked block, if the icon depends on the initialization commands.

  • Cause the icon to be drawn or redrawn, and the icon drawing depends on initialization code.

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

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

The Initialization pane contains the controls described in this section.

Dialog variables

The Dialog variables list displays the names of the dialog controls and associated mask parameters, which are defined in the Parameters & Dialog pane. You can also use the list to change the names of mask parameters. To change a name, double-click the name in the list. An edit field containing the existing name appears. Edit the existing name and click 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 run in the mask workspace, not the base workspace.

Allow library block to modify its contents

This check box is enabled only if the masked subsystem resides in a library. Checking this option allows the block's initialization code to modify the contents of the masked subsystem by adding or deleting blocks and setting the parameters of those blocks. Otherwise, an error is generated when a masked library block tries to modify its contents in any way.

Rules for Initialization commands

Following rules apply for mask initialization commands:

  • Do not use initialization code to create mask 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.

  • Avoid prefacing variable names in initialization commands with MaskParam_L_ and MaskParam_M_. 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. See Set Up Nested Masked Block Parameters for details.

Documentation Pane

The Documentation pane enables you to define or modify the type, description, and help text for a masked block.

Type

The mask type is a block classification that appears in the mask dialog box and on all Mask Editor panes for the block. When Simulink displays a mask dialog box, it suffixes (mask) to the mask type. To define the mask type, enter it in the Type field. The text can contain any valid MATLAB character, but cannot contain line breaks.

Description

The mask description is summary help text that describe the block's purpose or function. By default, the mask description is displayed below the mask type in the mask dialog box. To define the mask description, enter it in the Description field. The text can contain any legal MATLAB character. Simulink automatically wraps long lines. You can force line breaks by using the Enter key.

Help

The Online Help for a masked block provides information in addition to that provided by the Type and Description fields. This information appears in a separate window when the masked block user clicks the Help button on the mask dialog box. To define the mask help, type one of these in the Help field:

  • URL specification

  • web or eval command

  • Literal or HTML text

Provide an URL.  If the first line of the Mask help field is an URL, Simulink passes the URL to your default web browser. The URL can begin with http:, www:, file:, ftp:, or mailto:. Examples:

http://www.mathworks.com
file:///c:/mydir/helpdoc.html

Once the browser is active, MATLAB and Simulink have no further control over its actions.

Provide a web Command.  If the first line of the Mask help field is a web command, Simulink passes the command to MATLAB, which displays the specified file in the MATLAB Online Help browser. Example:

web([docroot '/MyBlockDoc/' get_param(gcb,'MaskType') '.html'])

See the MATLAB web command documentation for details. A web command used for mask help cannot return values.

Provide an eval Command.  If the first line of the Mask help field is an eval command, Simulink passes the command to MATLAB, which performs the specified evaluation. Example:

eval('!Word My_Spec.doc')

See MATLAB eval command documentation for details. An eval command used for mask help cannot return values.

Provide Literal or HTML Text.  If the first line of the Mask help field is not an URL, or a web or eval command, Simulink displays the text in the MATLAB Online Help browser under a heading that is the value of the Mask type field. The text can contain any legal MATLAB character, line breaks, and any standard HTML tag, including tags like img that display images.

Simulink first copies the text to a temporary folder, then displays the text using the web command. If you want the text to display an image, you can provide a URL path to the image file, or you can place the image file in the temporary folder. Use tempdir to find the temporary folder that Simulink uses for your system.

Additional Options

Following buttons appear on the Mask Editor:

  • The Preview button applies the changes you made, and opens the mask dialog box.

  • The OK button applies the mask settings and closes the Mask Editor.

  • The Cancel button closes the Mask Editor without applying any changes you made to the mask.

  • The Help button displays online information about the Mask Editor.

  • The Apply button applies the mask settings and leaves the Mask Editor open.

  • The Unmask button deletes the mask and closes the Mask Editor. To create the mask again, select the block and choose Mask > Create Mask.

More About

Was this topic helpful?