Main Content

Control Masks Programmatically

Open Live Script

Simulink® defines a set of parameters that help in setting and editing masks. To set and edit a mask from the MATLAB® command line, you can use Simulink.Mask and Simulink.MaskParameter class methods. You can also use the get_param and set_param functions to set and edit masks. However, since these functions use delimiters that do not support Unicode® (Non-English) characters it is recommended that you use methods of the Simulink.Mask and Simulink.MaskParameter class methods to control masks.

Use Simulink.Mask and Simulink.MaskParameter

Use methods of Simulink.Mask and Simulink.MaskParameter classes to perform the following mask operations:

  • Create, copy, and delete masks

  • Create, edit, and delete mask parameters

  • Determine the block that owns the mask

  • Get workspace variables defined for a mask

  • In this example the Simulink.Mask.create method is used to create a block mask:

new_system('mask_example');
add_block('built-in/subsystem','mask_example/subsystem');
save_system;
open_system('mask_example');
maskObj = Simulink.Mask.create(gcb);

In this example, the mask object is assigned to variable maskObj using the get method:

maskObj = Simulink.Mask.get(gcb);
maskObj
maskObj = 
  Mask with properties:

                         Type: ''
                  Description: ''
                         Help: ''
               Initialization: ''
               SelfModifiable: 'off'
                    ImageFile: ''
                      Display: ''
                    IconFrame: 'on'
                   IconOpaque: 'opaque'
         RunInitForIconRedraw: 'analyze'
                   IconRotate: 'none'
                   PortRotate: 'default'
                    IconUnits: 'autoscale'
                   Parameters: [0×0 Simulink.MaskParameter]
              PortIdentifiers: [0×0 Simulink.Mask.PortIdentifier]
         ParameterConstraints: [0×0 Simulink.Mask.Constraints]
    CrossParameterConstraints: [0×0 Simulink.Mask.CrossParameterConstraints]
              PortConstraints: [0×0 Simulink.Mask.PortConstraint]
                     BaseMask: [0×0 Simulink.Mask]

For examples of other mask operations, like creating and editing mask parameters and copying and deleting masks, see Simulink.Mask and Simulink.MaskParameter.

Use get_param and set_param

The set_param and get_param functions have parameters for setting and controlling the mask. You can use these functions to set the mask of any block in the model or library based on a value passed from the MATLAB command line:

set_param(gcb,'MaskStyleString','edit,edit',...
'MaskVariables','maskparameter1=@1;maskparameter2=&2;',...
'MaskPromptString','Mask Parameter 1:|Mask Parameter 2:',...
'MaskValues',{'1','2'});
get_param(gcb,'MaskStyleString');
set_param(gcb,'MaskStyles',{'edit','edit'},'MaskVariables',...
'maskparameter1=@1;maskparameter2=&2;','MaskPrompts',...
{'Mask Parameter 1:','Mask Parameter 2:'},...
'MaskValueString','1|2'); 
get_param(gcb,'MaskStyles');

where

  • | separates individual character vector values for the mask parameters.

  • @ indicates that the parameter field is evaluated.

  • & indicates that the parameter field is not evaluated but assigned as a character vector.

Note

  • When you use get_param to get the Value of a mask parameter, Simulink returns the value that was last applied using the mask dialog. Values that you have entered into the mask dialog box but not applied are not reflected when you use the get_param command.

  • To specify the value of a mask parameter programmatically, it is recommended to use set_param command on the mask parameter instead of using set_param on MaskValues.

To control the mask properties programmatically for a release before R2014a, see Mask Parameters.

Restrictions Using set_param and Mask Object APIs on Linked Blocks

Simulink imposes certain constraints while modifying the mask parameters using set_param and mask object APIs on linked blocks. On a non-self-modifiable linked block, you can change the properties of a mask parameter such as Value, Visible, and Enable. On a self-modifiable linked block, you can change few other properties in addition to Value, Visible, and Enable.

Programmatically Create Mask Parameters and Dialogs

This example shows how to create this simple mask dialog, add controls to the dialog, and change the properties of the controls.

Step 1: Create the mask for a block you selected in the model.

Step 2: To customize the dialog and to use tabs instead of the default group, remove the Parameters group box.

maskObj.removeDialogControl('ParameterGroupVar');
open_system('mask_example/subsystem');

Simulink preserves the child dialog controls–the two check boxes in this example–even when you delete the ParametersGroupVar group surrounding them. These controls are parameters that cannot be deleted using dialog control methods.

You can delete parameters using methods such as Simulink.Mask.removeAllParameters, which belongs to the Simulink.Mask class.

Step 3: Create a tab container and get its handle.

tabgroup = maskObj.addDialogControl('tabcontainer','tabgroup');

Step 4: Create tabs within this tab container.

tab1 = tabgroup.addDialogControl('tab','tab1');
tab1.Prompt = 'First';
maskObj.addParameter('Type','checkbox','Prompt','Option 1',...
  'Name','option1','Container','tab1');
maskObj.addParameter('Type','checkbox','Prompt','Option 2',...
  'Name','option2','Container','tab1');
tab2 = tabgroup.addDialogControl('tab', 'tab2');
tab2.Prompt = 'Second';
tab3 = tabgroup.addDialogControl('tab','tab3');
tab3.Prompt = 'Third (invisible)';

Make the third tab invisible.

tab3.Visible = 'off';
tab3
tab3 = 
  Tab with properties:

              Name: 'tab3'
            Prompt: 'Third (invisible)'
           Enabled: 'on'
           Visible: 'off'
      AlignPrompts: 'off'
    DialogControls: [0×0 Simulink.dialog.Control]

You can change the location and other properties of the parameters on the dialog by using the Simulink.dialog.Control commands.

For example, to change the dialog layout options, consider a Gain block with a Popup parameter named Parameter2 added. To set the dialog layout options of the parameter, you can use an instance of Simulink.dialog.parameter.Popup class. The following code shows how to set the prompt location in dialog layout:

add_block('built-in/gain','mask_example/gain2');
maskobj = Simulink.Mask.create(gcb);
set_param(gcb,'MaskStyleString','popup',...
'MaskVariables','maskparameter2=&2;',...
'MaskPromptString','Mask Parameter 2:');
a = Simulink.Mask.get('mask_example/gain2');
d = a.Parameters(1).DialogControl;
d
d = 
  Popup with properties:

                 Name: 'Parameter1'
       PromptLocation: 'left'
                  Row: 'new'
    HorizontalStretch: 'on'
              Tooltip: ''

Now, to set the PromptLocationproperty, use the command:

d.PromptLocation = 'left';

This sets the PromptLocationas 'left'. The available values are 'left' and 'top'. The output confirms the change of the PromptLocationproperty value to left:

d
d = 
  Popup with properties:

                 Name: 'Parameter1'
       PromptLocation: 'left'
                  Row: 'new'
    HorizontalStretch: 'on'
              Tooltip: ''


save_system;

For more information on dialog controls and their properties, see Simulink.dialog.Control.

Related Topics