Controlling Masks Programmatically

The Simulink software defines a set of masked block parameters that define the current state of the masked block's dialog. You can use the Mask Editor to inspect and set many of these parameters. The Simulink get_param and set_param commands also let you inspect and set mask dialog parameters. The set_param command allows you to set parameters and hence change a dialog's appearance while the dialog is open. This in turn allows you to create dynamic masked dialogs.

For example, you can use the set_param command in mask callback functions to be invoked when a user changes the values of user-defined parameters. The callback functions in turn can use set_param commands to change the values of the masked dialog's predefined parameters and hence its state, for example, to hide, show, enable, or disable a user-defined parameter control.

Use the 'mask' option of the open_system command to open a block's Mask Parameters dialog box at the MATLAB command line or in an M program.

You can use get_param and set_param to access this mask parameter.

You can customize every feature of the Mask Parameters dialog box, including which parameters appear on the dialog box, the order in which they appear, parameter prompts, the controls used to edit the parameters, and the parameter callbacks (code used to process parameter values entered by the user).

However, changing the mask parameter value with set_param does not change the value of the underlying block variable. You cannot use get_param or set_param to access the value of the underlying variable, because it is hidden by the mask.

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.

Predefined Masked Dialog Parameters

The following predefined parameters are associated with masked dialogs.

MaskCallbacks

The value of this parameter is a cell array of strings that specify callback expressions for the dialog's user-defined parameter controls. The first cell defines the callback for the first parameter's control, the second for the second parameter control, etc. The callbacks can be any valid MATLAB expressions, including expressions that invoke M-file commands. This means that you can implement complex callbacks as M-files.

You can use either the Mask Editor or the MATLAB command line to specify mask callbacks. To use the Mask Editor to enter a callback for a parameter, enter the callback in the Callback field for the parameter.

The easiest way to set callbacks for a mask dialog at the MATLAB command is to first select the corresponding masked dialog in a model or library window and then to issue a set_param command at the MATLAB command line. For example, the following code

set_param(gcb,'MaskCallbacks',{'parm1_callback', '',... 
'parm3_callback'});

defines callbacks for the first and third parameters of the masked dialog for the currently selected block. To save the callback settings, save the model or library containing the masked block.

MaskDescription

The value of this parameter is a string specifying the description of this block. You can change a masked block's description dynamically by setting this parameter in a mask callback.

MaskDisplay

The value of this parameter is string that specifies the drawing commands for the block's icon.

MaskEnables

The value of this parameter is a cell array of strings that define the enabled state of the user-defined parameter controls for this dialog. The first cell defines the enabled state of the control for the first parameter, the second for the second parameter, etc. A value of 'on' indicates that the corresponding control is enabled for user input; a value of 'off' indicates that the control is disabled.

You can enable or disable user input dynamically by setting this parameter in a callback. For example, the following command in a callback

set_param(gcb,'MaskEnables',{'on','on','off'});

would disable the third control of the currently open masked block's dialog. Disabled controls are colored gray to indicate visually that they are disabled.

MaskInitialization

The value of this parameter is string that specifies the initialization commands for the mask workspace.

MaskPrompts

The value of this parameter is a cell array of strings that specify prompts for user-defined parameters. The first cell defines the prompt for the first parameter, the second for the second parameter, etc.

MaskType

The value of this parameter is the mask type of the block associated with this dialog.

MaskValues

The value of this parameter is a cell array of strings that specify the values of user-defined parameters for this dialog. The first cell defines the value for the first parameter, the second for the second parameter, etc.

MaskVisibilities

The value of this parameter is a cell array of strings that specify the visibility of the user-defined parameter controls for this dialog. The first cell defines the visibility of the control for the first parameter, the second for the second parameter, etc. A value of 'on' indicates that the corresponding control is visible; a value of 'off' indicates that the control is hidden.

You can hide or show user-defined parameter controls dynamically by setting this parameter in the callback for a control. For example, the following command in a callback

set_param(gcb,'MaskVisibilities',{'on','off','on'});

would hide the control for the currently selected block's second user-defined mask parameter. The Simulink software expands or shrinks a dialog to show or hide a control, respectively.

Note   For a full list of predefined masked block parameters see the Mask Parameters reference page.

Back to Top

Notes on Mask Parameter Storage

1. The MaskPromptString parameter stores the Prompt field values for all mask dialog box parameters as a string, with individual values separated by vertical bars (|), for example:

   "Slope:|Intercept:"
   

2. The MaskStyleString parameter stores the Type field values for all mask dialog box parameters as a string, with individual values separated by commas. The Popup strings values appear after the popup type, as shown in this example:

   "edit,checkbox,popup(red|blue|green)"
   

3. The MaskValueString parameter stores the values of all mask dialog box parameters as a string, with individual values separated by a vertical bar (|). The order of the values is the same as the order in which the parameters appear on the dialog box, for example:

   "2|5"
   

4. The MaskVariables parameter stores the Variable field values for all mask dialog box parameters as a string, with individual assignments separated by semicolons. A sequence number indicates the prompt that is associated with a variable. A special character preceding the sequence number indicates whether the parameter value is evaluated or used literally. An at-sign (@) indicates evaluation; an ampersand (&) indicates literal usage. For example:

   "a=@1;b=&2;"

   This string defines two Variable field values:

   • The value entered in the first parameter field is evaluated in the MATLAB workspace, and the result is assigned to variable a in the mask workspace.

   • The value entered in the second parameter field is not evaluated, but is assigned literally to variable b in the mask workspace.

Back to Top

Calculating Values Used Under the Mask

Understanding Mask Code Execution

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