Organize Mask Initialization and Callbacks in a MATLAB File

Open Model

You can organize mask initialization and mask callback code in a separate MATLAB® class file. By using a separate MATLAB 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 .m file instead of in 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 enabled, then the value of bias is set to 0. In the mask parameter callback section, if EnableBias is enabled, then the property Enabled of all the parameters are set to on. Otherwise the Enabled property of all parameters are set to on except Enable Bias parameter. In the mask control callback section, you can set the Enabled 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. 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 MATLAB file must be located 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 mask workspace 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. See Simulink.Mask for more information on mask object properties and its data types.

MaskWorkspace: Use this property to access the mask workspace:

maskWorkspace = maskInitContext.MaskWorkspace;

  • Use set and get methods along with the MaskWorkspace property to set and retrieve the values of MaskWorkspace variables. See getWorkspace for more information on how to get and set the mask parameters and variables from the mask workspace.

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

Write Mask Parameter Callback Code

In this example, the parameter callback code enables or disables the Bias parameter in the mask dialog box on enabling or disabling the Enable Bias.

  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

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

ParameterObject: Parameter object of the masked block. Refer getParameter for more information on the properties of the parameter and its data type.

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

  • 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 a MATLAB file. A classdef wrapper is created and mask functions are converted to member functions. 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 without migrating the code. Save the mask to save the callback file.

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.

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. You can also choose to rename a callback file using the Save As option.

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.

See Also