Main Content

Control Masks Programmatically

Open Live Script

Simulink® defines a set of APIs 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

Create block mask on a model using Simulink.Mask.create method:

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

                         Type: ''
                  Description: ''
                         Help: ''
               Initialization: ''
               SelfModifiable: 'off'
                 BlockDVGIcon: ''
                      Display: ''
       SaveImageFileWithModel: 'off'
                    IconFrame: 'on'
                   IconOpaque: 'opaque'
         RunInitForIconRedraw: 'analyze'
                   IconRotate: 'none'
                   PortRotate: 'default'
                    IconUnits: 'autoscale'
    SaveCallbackFileWithModel: 'off'
                 CallbackFile: ''
         ParameterConstraints: [0x0 Simulink.Mask.Constraints]
              PortConstraints: [0x0 Simulink.Mask.PortConstraint]
                   Parameters: [0x0 Simulink.MaskParameter]
              PortIdentifiers: [0x0 Simulink.Mask.PortIdentifier]
    CrossParameterConstraints: [0x0 Simulink.Mask.CrossParameterConstraints]
         CrossPortConstraints: [0x0 Simulink.Mask.CrossPortConstraint]
                     BaseMask: [0x0 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.

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. In this example, two mask edit parameters maskparameter1 and maskparameter2 are created.

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

  • MaskStyle and MaskStyleString defines the type of the mask parameter.

  • MaskVariables defines the name of the mask parameter.

  • MaskPromptString defines the prompt of the mask parameter.

  • MaskValues and MaskValueString assigns default values to the mask parameter.

  • | 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.

Limitations 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.

Create Mask Parameters and Dialogs

This example shows how to create a simple mask dialog with mask checkbox parameters and tab containers. It also shows how to change the properties of the controls.

Step 1: Create mask on the block.

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 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.

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: [0x0 Simulink.dialog.Control]

You can create and insert mask parameters at a specific index using the method insertParameter. You can also change the location and other properties of the parameters on the dialog by using 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: 'top'
                  Row: 'new'
    HorizontalStretch: 'on'
              Tooltip: ''

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 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