Author Mask Initialization and Callbacks

You can write MATLAB^® code in the code pane of the Mask Editor for mask initialization and callbacks. Mask initialization code enables you to modify the behavior of a block during block evaluation state. You can initialize the mask or update the mask parameters of a block or its child block. For example, you may want to create a new parameter based on the state of an existing block parameter and use this new parameter in the child block.

Parameter callbacks and dialog control callbacks helps you to achieve different behaviors for the block. The callback section typically consists of the actions to be performed on changing the value of a parameter. For example, you may want to disable an edit parameter on clicking the checkbox parameter on the mask dialog or you may want to populate a popup parameter with different option on clicking the checkbox parameter on the mask dialog box.

Structure of the MATLAB class file

By using a separate MATLAB class file you can:

Use code debugging capabilities such as breakpoints in MATLAB Editor.
Reduce the memory footprint of the masks since the callbacks are stored in a MATLAB class file instead of in memory.
Edit the mask callback code using either Mask Editor or MATLAB Editor.

You can author mask callback code and save it in a separate MATLAB class file or you can save the callback within the mask itself.

To author a mask callback code on a masked block:

Open Mask Editor and click Code pane.
Click New in the toolstrip and enter the Callback File Name to create a new MATLAB class file. The default mode of authoring mask callbacks is using the MATLAB class file.
Click Browse to load an existing MATLAB class file. The MATLAB class file is created with a .m extension. The name of the callback file and the name of the class that the function belongs to must be the same. For example, if the name of the callback file is mask_cb_file_example then the name of the class file must be mask_cb_file_example. The mask callback file must be located in the MATLAB path.

Alternatively, if you want to save callbacks in mask, select Switch Callback Mode and click Mask.

How to Author Mask Initialization Code?

Mask initialization code in Simulink^® refers to the code that is executed when a masked block is initialized during the simulation or when the model is loaded. Mask Initialization code enables you to set initial parameter values or configure the block's behavior. The mask initialization function in the mask callback file must be in the following format:

The method in the callback file that executes the mask initialization code must be Static.
Mask initialization function must be named as MaskInitialization.
Input argument to the mask initialization function is a context structure with these properties:
- BlockHandle: Handle of the block.
- MaskObject: Mask object of the masked block. To know more about mask object, see Control Masks Programmatically
- MaskWorkspace: Use this property to access the mask workspace. Simulink associates a workspace with each masked block. Simulink stores the evaluated values of the block's mask parameters in the workspace as well as any variables created by the block's mask initialization code.
  maskWorkspace = maskInitContext.MaskWorkspace;
  - Use the set function to create or update a mask workspace variable. For example, maskWorkspace.set('biasValue',0);. If biasValue is a mask workspace variable then its value will be set to 0, otherwise a new variable biasValue is created in mask workspace and its value will be set to 0.
  - Use the get function to get the value of a mask workspace variable. For example, enableBiasValue = maskWorkspace.get('EnableBias');. The value of EnableBias is retrieved from the mask workspace.
Note
The properties of the input argument of the initialization function are case sensitive.

 function MaskInitialization(maskInitContext)
     blkHandle = maskInitContext.BlockHandle;       % Block Handle of this block
     maskObj = maskInitContext.MaskObject;          % Mask object of this masked block
     maskWorkspace = maskInitContext.MaskWorkspace; % Use this to work with mask workspace
     disp('Mask initialization triggered');
     % Get value of 'EnableBias' parameter using mask workspace get() API.
     enableBiasValue = maskWorkspace.get('EnableBias');
      if ~enableBiasValue
       % Set 'BiasValue' parameter value to 0 using mask workspace set() API.
       maskWorkspace.set('biasValue',0);
      end
 end

How to Author Mask Parameter Callback Code?

Parameter callback code in Simulink refers to the code that is executed when a parameter value of a masked block is changed. It allows you to perform custom actions based on parameter changes. Parameter callback code in mask callback file must be in the following format:

The function name of the parameter callback must be same as the parameter name.

Input argument to the mask parameter callback function is a context structure with these properties.

BlockHandle: Block handle of the block.

ParameterObject: Parameter object of a mask dialog parameter. The ParameterObject contains the properties of the specific parameter. For example, the edit parameter object looks like

  MaskParameter with properties:

              Type: 'edit'
       TypeOptions: {0×1 cell}
              Name: 'speed'
            Prompt: ''
             Value: '0'
    ConstraintName: ''
          Evaluate: 'on'
           Tunable: 'on'
         NeverSave: 'off'
            Hidden: 'off'
          ReadOnly: 'off'
           Enabled: 'on'
           Visible: 'on'
       ShowTooltip: 'on'
          Callback: ''
             Alias: ''
      VariableName: ''
     DialogControl: [1×1 Simulink.dialog.parameter.Edit]

Note

Parameter callback code does not have access to mask workspace.

 function EnableBias(callbackContext)
     blkHandle = callbackContext.BlockHandle; % Block Handle of this block
     maskObj = Simulink.Mask.get(blkHandle);
     parameterObj = callbackContext.ParameterObject; % Parameter object for 'EnableBias'.
     disp('EnableBias callback triggered');
     % Set the 'Enabled' property for each parameter
      if strcmp(get_param(blkHandle,'EnableBias'),'on')
         maskObj.getParameter('gainValue').Enabled = 'on';
         maskObj.getParameter('biasValue').Enabled = 'on';
         maskObj.getParameter('EnableBias').Enabled = 'on';
      else
         maskObj.getParameter('gainValue').Enabled = 'on';
         maskObj.getParameter('EnableBias').Enabled = 'on';
         maskObj.getParameter('biasValue').Enabled = 'off';
      end
  end

Write Mask Dialog Control Callback

The dialog control callback in Simulink refers to the code that is executed when a specific action or event occurs on a dialog control element of a masked block. It allows you to customize the behavior of the dialog controls and perform actions based on user interactions. The dialog control callback must be in the following format:

The function name for the control callback must be same as the name of the dialog control.
Input argument to the mask control callback function is a struct with these properties.
- BlockHandle: Block handle of the block.
- DialogControlObject: Dialog control object of the dialog control. The DialogControlObject contains the properties of the specific dialog control. For example, the button object looks like
  Button with properties: Name: 'Enable' Prompt: '' Callback: '' FilePath: '' Row: 'new' Enabled: 'on' Visible: 'on' HorizontalStretch: 'on' Tooltip: ''

function ResetVisibility(callbackContext)
    blkHandle = callbackContext.BlockHandle; % Block Handle of this block
    maskObj = Simulink.Mask.get(blkHandle);
    resetButtonObj = callbackContext.DialogControlObject; % Dialog Control object for 'ResetVisibility'.
    disp('ResetVisibility button callback triggered');
    % Reset mask enables.
    maskObj.getParameter('gainValue').Enabled = 'on';
    maskObj.getParameter('biasValue').Enabled = 'on';
    maskObj.getParameter('EnableBias').Enabled = 'on';
 end

Migrate Existing Callback Code to MATLAB File

You can migrate existing callback code stored in mask to a MATLAB class file. Inspect the mask initialization code and make corrections before executing it. For example, you must modify the code to create, modify, or retrieve the values of parameters or variables from the mask workspace in the mask initialization section using the mask workspace methods set and get.

To migrate the existing callback code, right-click the masked block, from the context menu select Mask > Edit Mask. In the Code tab, click Switch Callback Mode and select Callback File.

migrate existing callback code to .m file

In the dialog box, click Yes to migrate the existing callback and save. Click No, to save mask callbacks in a separate MATLAB file and without migrating the code. Save the mask to save the callback file.

Prompt confirming the migration

Note

If you want to store the mask callback in the mask object rather than in a separate MATLAB file, go to Mask Editor, click Code > Switch Callback Mode > select Mask.

Create or Update Mask Workspace Variables

After migrating the existing mask callback to the MATLAB class file mode, you will have to inspect the mask initialization code and make corrections before executing it. For example, you must modify the code to set and get values of variables from the mask workspace in the mask initialization section using the mask workspace methods set and get.

Use the set function to create or update a mask workspace variable. For example, maskWorkspace.set('biasValue',0);. If biasValue is a mask workspace variable then its value will be set to 0, otherwise a new variable biasValue is created in mask workspace and its value will be set to 0.
Use the get function to get the value of a mask workspace variable. For example, enableBiasValue = maskWorkspace.get('EnableBias');. The value of EnableBias is retrieved from the mask workspace.

Save Callback File with the Model

You can also package the callback file along with the model. Use the option Save callback file with model in the toolstrip. You must also save the model to package the callback file along with the model.

Note

To edit the callback file saved with the model, you must load the model. Use the Open option in the toolstrip to open the callback file in MATLAB editor.