Control Masks Programmatically

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:

 maskObj = Simulink.Mask.create(gcb);

 maskObj =  
      Simulink.Mask handle
      Package: Simulink
      Properties:
                    Type: ''
             Description: ''
                    Help: ''
          Initialization: ''
          SelfModifiable: 'off'
                 Display: ''
               IconFrame: 'on'
              IconOpaque: 'on'
    RunInitForIconRedraw: 'off'
              IconRotate: 'none'
              PortRotate: 'default'
               IconUnits: 'autoscale'
              Parameters: []
  Methods, Events, Superclasses

In this example the mask object is assigned to variable maskObj using the Simulink.Mask.get method:

maskObj = Simulink.Mask.get(gcb)

maskObj =  
    Simulink.Mask handle
    Package: Simulink
    Properties:
                    Type: ''
             Description: ''
                    Help: ''
          Initialization: ''
          SelfModifiable: 'off'
                 Display: ''
               IconFrame: 'on'
              IconOpaque: 'on'
    RunInitForIconRedraw: 'off'
              IconRotate: 'none'
              PortRotate: 'default'
               IconUnits: 'autoscale'
              Parameters: [1x1 Simulink.MaskParameter]
     Methods, Events, Superclasses

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.

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.

Create the mask for a block you selected in the model.
```
maskobj = Simulink.Mask.create(gcb);
```
To customize the dialog and to use tabs instead of the default group, remove the Parameters group box.
```
maskobj.removeDialogControl('ParameterGroupVar');
```
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 removeAllParameters, which belongs to the Simulink.Mask class.

Create a tab container and get its handle.

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

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 = 

  Tab with properties:

              Name: 'tab3'
            Prompt: 'Third (invisible)'
           Enabled: 'on'
           Visible: 'on'
    DialogControls: []

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:

a = Simulink.Mask.get('testmodel/Gain');
d = a.Parameters(2).DialogControl;

This lists all the properties of the popup parameter 'Parameter2':

d = 

  Popup with properties:

                 Name: 'Parameter2'
       PromptLocation: 'top'
                  Row: 'new'
    HorizontalStretch: 'on'
              Tooltip: 'Test'

Now, to set the PromptLocation property, use the command:

d.PromptLocation = 'left'

This sets the PromptLocation as 'left'. The available values are 'left' and 'top'. The output confirms the change of the PromptLocation property value toleft:

d = 

  Popup with properties:

                 Name: 'Parameter2'
       PromptLocation: 'left'
                  Row: 'new'
    HorizontalStretch: 'on'
              Tooltip: 'Test'

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

Documentation