Main Content

Organize Mask Initialization and Callbacks in a MATLAB File

You can organize mask initialization and mask callback code in a separate MATLAB® class file. By using a separate MATLAB file you can:

  • Organize all mask callbacks and initialization code in a single MATLAB file.

  • Use code debugging capabilities such as breakpoints in MATLAB Editor.

  • Reduce the memory footprint of the masks since the callbacks are stored in a MAT file instead of in the memory.

  • Edit the mask callback code using either Mask Editor or MATLAB Editor.

Explore the Model

This example model implements the equation y = u*gain + bias through mask initialization and callbacks. There are three mask parameters, gain, bias, and EnableBias. The value of EnableBias is set by selecting or clearing the Enable Bias check box. In the mask initialization section, the value of EnableBias is retrieved from the mask workspace, if it is not selected, then the value of bias is set to 0. In the mask parameter callback section, if EnableBias is selected, then the property MaskEnables of all the parameters are set to on, otherwise the MaskEnables property of all parameters are set to on except Enable Bias parameter. In the mask control callback section, you can set the MaskEnables property for all parameters to on clicking the Reset Visibility button.

 open_system("slexMaskCallbackFileExample.slx");

Author Mask Callback Code in MATLAB File

You can organize mask initialization and callback code in a single MATLAB file. 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 is mask_cb_file_example. The MATLAB file must be created in the MATLAB path.

Write Mask Initialization Code

In this example, the mask initialization code sets the biasValue to 0 if the parameter EnableBias is cleared.

To view the mask initialization written for this example, right-click Masked Block Using a Mask Callback File. > In the context menu, click Mask > Edit Mask. On the Code tab, the mask_cb_file_example file contains the initialization and callback code for the model.

The mask initialization function should be in the following format:

  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 mark workspce set() API.
               maskWorkspace.set('biasValue',0);
           end
       end
  • The method 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 struct with these properties:

BlockHandle: Handle of the block.

MaskObject: Mask object of the masked block.

MaskWorkspace: Use this property to access the mask workspace:

maskWorkspace = maskInitContext.MaskWorkspace;

Note: The properties of the input argument of the initialization function are case sensitive.

  • Use set and get methods along with the maskworkspace property to set and retrieve the values of MaskWorkspace variables.

Write Mask Parameter Callback Code

In this example, the parameter callback code is written to enable the parameters on selecting or clearing the Enable Bias.

  function EnableBias(callbackContext)
           % Block Handle of this block
           blkHandle = callbackContext.BlockHandle;
           % Parameter object for 'EnableBias'.
           parameterObj = callbackContext.ParameterObject;
           disp('EnableBias callback triggered');
           % Set the 'MaskEnables' property for each parameters
           if strcmp(get_param(blkHandle,'EnableBias'),'on')
               set_param(blkHandle,'MaskEnables',{'on','on','on'});
           else
               set_param(blkHandle,'MaskEnables',{'on','on','off'});
           end
       end
  • The function name of the parameter callback must be same as the parameter name.

  • Input argument to the mask parameter callback function is a struct with these properties.

BlockHandle: Block handle of the block.

MaskObject: Mask object of the masked block or the dialog control object of the dialog control.

  • Use set_param and get_param to set and retrieve the values of parameters.

Write Mask Dialog Control Callback

In this example, the dialog control callback code is written to enable all the mask parameters on clicking the ResetVisibility button in the mask dialog control.

The control callback code should be in the following format:

  function ResetVisibility(callbackContext)
           % Block Handle of this block
           blkHandle = callbackContext.BlockHandle;
           % Dialog Control object for 'ResetVisibility'.
           resetButtonObj = callbackContext.DialogControlObject;
           disp('ResetVisibility button callback triggered');
           % Reset mask enables.
           set_param(blkHandle,'MaskEnables',{'on','on','on'});
       end
  • The function name of the control callback must be same as the name of the property set by the dialog box 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.

  • Use set_param and get_param to set and retrieve the values of parameters.

Migrate Existing Callback Code to MATLAB File

You can migrate existing callback code to MATLAB file. The template of the code is migrated but 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 set and get methods.

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.

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 you do not want to migrate. Save the mask to save the callback file.

Note: If you do not wish to store the mask callback in a separate MATLAB file and if you want to store the mask callback in the mask object, go to Mask Editor, click Code > Switch Callback Mode > select Mask.

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