| Simulink® | |
| On this page… |
|---|
Note The Mask Editor requires that MATLAB start with Java enabled. This means you cannot use the Mask Editor if you start the MATLAB product with the -nojvm option. |
To create a subsystem mask, select the subsystem block icon and then select Mask Subsystem from the Edit menu of the model window containing the subsystem's block.
To create a mask on a built-in block, see Masking a Built-in Block.
To edit an existing mask, select the block's icon and then select Edit Mask from the Edit menu of the model window containing the subsystem's block.
A Mask Editor like the following appears in either case.
The Mask Editor contains a set of tabbed panes, each of which enables you to define a feature of the mask:
The Icon pane enables you to define the block icon (see Icon Pane).
The Parameters pane enables you to define and describe mask dialog box parameter prompts and name the variables associated with the parameters (see Parameters Pane).
The Initialization pane enables you to specify initialization commands (see Initialization Pane).
The Documentation pane enables you to define the mask type and specify the block description and the block help (see Documentation Pane).
Five buttons appear along the bottom of the Mask Editor:
The Unmask button deactivates the mask and closes the Mask Editor. While the model is still active, the mask information is still retained so that you can reactivate it. To reactivate the mask, select the block and choose Mask Subsystem. The Mask Editor opens, displaying the previous settings. When you close the model, the inactive mask information is discarded. If you want the mask information after this, you will need to recreate it the next time you open the model.
The OK button applies the mask settings on all panes and closes the Mask Editor.
The Cancel button closes the Mask Editor without applying any changes made since you last clicked the Apply button.
The Apply button creates or changes the mask using the information that appears on all masking panes. The Mask Editor remains open.
To see the system under the mask without unmasking it, select the Subsystem block, then select Look Under Mask from the Edit menu. This command opens the subsystem. The block's mask is not affected.
The Mask Editor's Icon pane enables you to create icons that can contain descriptive text, state equations, images, and graphics.
The Icon pane contains the following controls.
This field allows you to enter commands that draw the block's icon. A set of commands is provided that can display text, one or more plots, or show a transfer function (see Mask Icon Drawing Commands). You must use only these commands to draw your icon. The drawing commands are executed in the order in which they appear in this field. Drawing commands have access to all variables in the mask workspace. If the drawing commands cannot be successfully executed, the icon displays three question marks.
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).
The drawing commands are executed when you:
Load the model
Run or update the block diagram
Apply any changes made in the mask parameter dialog box, either by clicking Apply or OK.
Apply any changes made in the Mask Editor, either 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
This panel illustrates the usage of the various icon drawing commands supported by the Simulink product. To determine the syntax of a command, select the command from the Command list. An example of the selected command is displayed at the bottom of the panel and the icon produced by the command to the right of the list.
These controls allow you to specify the following attributes of the block icon.
Frame. The icon frame is the rectangle that encloses the block. You can choose to show or hide the frame by setting the Frame parameter to Visible or Invisible. The default is to make the icon frame visible. For example, this figure shows visible and invisible icon frames for an AND gate block.
Transparency. The icon can be set to Opaque or Transparent, either hiding or showing what is underneath the icon. Opaque, the default, covers information the Simulink software draws, such as port labels. This figure shows opaque and transparent icons for an AND gate block. Notice the text on the transparent 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.
Units. This option controls the coordinate system used by the drawing commands. It applies only to 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 resized, the icon is also resized. 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 resized, the icon is also resized. 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 resized when the block is resized. To force the icon to resize with the block, define the drawing commands in terms of the block size.
The Parameters pane allows you to create and modify masked subsystem parameters (mask parameters, for short) that determine the behavior of the masked subsystem.
The Parameters pane contains the following elements:
The Dialog parameters panel allows you to select and change the major properties of the mask's parameters (see Dialog Parameters Panel).
The Options for selected parameter panel allows you to set additional options for the parameter selected in the Dialog parameters panel.
The buttons on the left side of the Parameters pane allow you to add, delete, and change the order of appearance of parameters on the mask's parameter dialog box (see Dialog Parameters Panel).
Lists the mask's parameters in tabular form. Each row displays the major attributes of one of the mask's parameters.
Prompt. Text that identifies the parameter on a masked subsystem's dialog box.
Variable. Name of the variable that stores the parameter's value in the mask's workspace (see Mask Workspace). You can use this variable as the value of parameters of blocks inside the masked subsystem, thereby allowing the user to set the parameters via the mask dialog box.
Note The set_param and get_param commands are insensitive to case differences in mask variable names. For example, suppose a model named MyModel contains a masked subsystem named A that defines a mask variable named Volume. Then, the following line of code returns the value of the Volume parameter. get_param(MyModel/A, 'voLUME') However, case does matter when using a mask variable as the value of a block parameter inside the masked subsystem. For example, suppose a Gain block inside the masked subsystem A specifies VOLUME as the value of its Gain parameter. This variable name does not resolve in the masked subsystem's workspace, as it contains a mask variable named Volume. If the base workspace does not contain a variable named VOLUME, simulating MyModel produces an error. |
Type. Type of control used to edit the value of this parameter. The control appears on the mask's parameter dialog box following the parameter prompt. The button that follows the type name in the Parameters pane pops up a list of supported commands (see Control Types). To change the current control type, select another type from the list.
Evaluate. If checked, this option causes the Simulink software to evaluate the expression entered by the user before it is assigned to the variable. Otherwise, the expression itself is treated as a string value and is assigned to the variable. For example, if the user enters the expression gain in an edit field and the Evaluate option is checked, gain is evaluated and the resultis assigned to the variable. Otherwise, the string 'gain' is assigned to the variable. See Check Box Control and Pop-Up Control for information on how this option affects evaluation of the parameters.
If you need both the string entered and the evaluated value, clear the Evaluate option. To get the value of a base workspace variable entered as the literal value of the mask parameter, use the MATLAB evalin command in the mask initialization code. For example, suppose the user enters the string 'gain' as the literal value of the mask parameter k where gain is the name of a base workspace variable. To obtain the value of the base workspace variable, use the following command in the mask's initialization code:
value = evalin('base', k)
Tunable. Selecting this option allows a user to change the value of the mask parameter while a simulation is running.
Note This setting is ignored if the block being masked is a source block, i.e., the block has outputs but no input ports. In such a case, even if this option is selected, you cannot tune the parameter while a simulation is running. See Changing Source Block Parameters During Simulation for more information. |
This panel allows you to set additional options for the parameter selected in the Dialog parameters table.
Show parameter. The selected parameter appears on the masked block's parameter dialog box only if this option is checked (the default).
Enable parameter. Clearing this option grays the selected parameter's prompt and disables its edit control. This means that the user cannot set the value of the parameter.
Popups. This field is enabled only if the edit control for the selected parameter is a pop-up. Enter the values of the pop-up control in this field, each on a separate line.
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 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 Creating Dynamic Mask Parameter Dialog Boxes 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 Initialization Pane). |
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.')
endThe Simulink software executes the callback commands when you
Open the mask parameter dialog box. Callback commands execute top down, starting with the top mask dialog parameter
Modify a parameter value in the mask parameter dialog box then change the cursor's focus, i.e., press the Tab key or click into another field in the dialog
Modify the parameter value, either in the mask parameter 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 Initialization Pane.)
Cancel any applied changes made in the mask dialog box by clicking Cancel.
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.
For information on debugging dialog callbacks, see Debugging Masks.
The following sections explain the purpose of the buttons that appear on the Parameters pane in the order of their appearance from the top of the pane.
Add Button. Adds a parameter to the mask's parameter list. The newly created parameter appears in the adjacent Dialog parameters table.
Delete Button. Deletes the parameter currently selected in the Dialog parameters table.
Up Button. Moves the currently selected parameter up one row in the Dialog parameters table. Dialog parameters appear in the mask's parameter dialog box (see Mask Parameter Dialog Box) in the same order in which they appear in the Dialog parameters table. This button (and the next) thus allows you to determine the order in which parameters appear on the dialog box.
Down Button. Moves the currently selected parameter down one row in the Dialog parameters table and hence down one position on the mask's parameter dialog box.
You can choose how parameter values are entered or selected. You can create three styles of controls: edit fields, check boxes, and pop-up controls. For example, this figure shows the parameter area of a mask dialog box that uses all three styles of controls (with the pop-up control open).
An edit field enables the user to enter a parameter value by typing it into a field. This figure shows how the prompt for the sample edit control was defined.
The value of the variable associated with the parameter is determined by the Evaluate option.
| Evaluate | Value |
|---|---|
On | The result of evaluating the expression entered in the field |
Off | The actual string entered in the field |
A check box enables the user to choose between two alternatives by selecting or deselecting a check box. This figure shows how the sample check box control is defined.
The value of the variable associated with the parameter depends on whether the Evaluate option is selected.
| Control State | Evaluated Value | Literal Value |
|---|---|---|
Selected | 1 | 'on' |
Unselected | 0 | 'off' |
A pop-up enables the user to choose a parameter value from a list of possible values. Specify the values in the Popups field on the Options for selected parameter pane (see Popups). The following example shows a pop-up parameter.
The value of the variable associated with the parameter (Color) depends on the item selected from the pop-up list and whether the Evaluate option is checked (on).
| Evaluate | Value |
|---|---|
| On | Index of the value selected from the list, starting with 1. For example, if the third item is selected, the parameter value is 3. |
| Off | String that is the value selected. If the third item is selected, the parameter value is 'green'. |
The Initialization pane allows you to enter MATLAB commands that initialize the masked subsystem.
The initialization commands are executed when you
Load the model
Start a simulation or update the model's block diagram
Make changes to the block diagram that affect the appearance of the block, such as rotating the block
Copy the masked subsystem within the same model or between different models
Apply any changes to the block's dialog that affect the block's appearance or behavior, such as changing the value of a mask parameter on which the block's icon drawing code depends.
The Initialization pane includes the following controls.
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.
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 Debugging Masks.
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, i.e., it lets the code add or delete blocks and set the parameters of those blocks. Otherwise, an error is generated when a masked library block tries to modify its contents in any way. To set this option at the MATLAB prompt, select the self-modifying block and enter the following command.
set_param(gcb, 'MaskSelfModifiable', 'on');
Then save the block.
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 Creating Dynamic Mask Parameter Dialog Boxes 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.
The Documentation pane enables you to define or modify the type, description, and help text for a masked block.
This figure shows how fields on the Documentation pane correspond to the mx + b sample mask block's dialog box.
The mask type is a block classification used only for purposes of documentation. It appears in the block's dialog box and on all Mask Editor panes for the block. You can choose any name you want for the mask type. When the Simulink product creates the block's dialog box, it adds "(mask)" after the mask type to differentiate masked blocks from built-in blocks.
The block description is informative text that appears in the block's dialog box in the frame under the mask type. If you are designing a system for others to use, this is a good place to describe the block's purpose or function.
Long lines of text are automatically wrapped. You can force line breaks by using the Enter or Return key.
You can provide help text that is displayed when the Help button is clicked on the masked block's dialog box. If you create models for others to use, this is a good place to explain how the block works and how to enter its parameters.
You can include user-written documentation for a masked block's help. You can specify any of the following for the masked block help text:
URL specification (a string starting with http:, www, file:, ftp:, or mailto:)
HTML-tagged text to be displayed in a Web browser
The first line of the masked block help text is examined. If a URL specification is detected, for example,
http://www.mathworks.com
or
file:///c:/mydir/helpdoc.html
the specified file is displayed in the browser. If a web command is detected, for example,
web([docroot '/My Blockset Doc/' get_param(gcb,'MaskType')... '.html'])
or an eval command, for example,
eval('!Word My_Spec.doc')
the specified command is executed. Otherwise, the contents of the Block Help field is displayed, which can include HTML tags, in the browser.
Note, if you enter HTML-tagged text, the Simulink software copies that text into a temporary directory and displays it from that temporary directory. If you want to include an image (for example, with the img tag) with that text, you need to place the image file in that temporary directory. (You can use tempdir to find the temporary directory for your system.) Alternatively, you can save the HTML-tagged text into an HTML file (such as hello.html) in the current directory and display that file directly (for example, web('hello.html', '-helpbrowser')). This method enables you to place referenced image files in the same directory as the HTML file.
| Masking a Block | Linking Mask Parameters to Block Parameters | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |