Customize System Block Dialog Box Programmatically

You can customize the dialog box for a MATLAB System block by adding properties and methods in the corresponding System object™. You can add tabs, organized properties into groups and sections, add block descriptions, simulation type control, and add custom buttons.

Note

From R2022b, use the Mask Editor to design a MATLAB System dialog box. You can also migrate existing dialog box customizations to the Mask Editor. This capability eliminates the need to develop or maintain the getPropertyGroupsImpl method in a System object file. For more information, see Customize MATLAB System Icon and Dialog Box Using Mask Editor.

Define Block Dialog Tabs, Sections, and Order of Properties

This example customizes the block dialog box for the MultipleGroupsWithTabs MATLAB System block by specifying property display names and modifying the getPropertyGroupImpl method.

Change Property Label

To change the property label that appears on the dialog box, add comments before each property in this format %PropertyName Block Dialog Label with no space between the comment and the property name. For example, to display the StartValue property as Start Value, specify:

%StartValue Start Value
StartValue = 0

The MultipleGroupsWithTabs System object™ in this example relabels each property for display in the MATLAB System block dialog.

Organize Dialog Box

The MutlitpleGroupsWithTabs System object class defines a getPropertyGroupsImpl method. Inside the getPropertyGroupsImpl method, this example defines two tabs (section groups) and three parameter groupings (sections).

classdef MultipleGroupsWithTabs < matlab.System
    % MultipleGroupsWithTabs Customize block dialog with multiple tabs and parameter groups.
    
    % Public, tunable properties
    properties
        %StartValue Start Value
        StartValue = 0
        
        %EndValue End Value
        EndValue = 10
        
        Threshold = 1
        
        %BlockLimit Limit
        BlockLimit = 55
    end
    % Public Nontunable 
    properties(Nontunable)
        %IC1 First initial condition
        IC1 = 0
        
        %IC2 Second initial condition
        IC2 = 10
        
        %IC3 Third initial condition
        IC3 = 100

        %UseThreshold Use threshold
        UseThreshold (1,1) logical = true
    end
    
    methods (Static, Access = protected)
        function groups = getPropertyGroupsImpl
            % Section to always display above any tabs.
            alwaysSection = matlab.system.display.Section(...
                'Title','','PropertyList',{'BlockLimit'});
           
            % Group with no sections
            initTab = matlab.system.display.SectionGroup(...
                'Title','Initial conditions', ...
                'PropertyList',{'IC1','IC2','IC3'});
            
            % Section for the value parameters
            valueSection = matlab.system.display.Section(...
                'Title','Value parameters',...
                'PropertyList',{'StartValue','EndValue'});
            
            % Section for the threshold parameters
            thresholdSection = matlab.system.display.Section(...
                'Title','Threshold parameters',...
                'PropertyList',{'Threshold','UseThreshold'});
            
            % Group with two sections: the valueSection and thresholdSection sections
            mainTab = matlab.system.display.SectionGroup(...
                'Title','Main', ...
                'Sections',[valueSection,thresholdSection]);
            
            % Return an array with the group-less section, the group with
            % two sections, and the group with no sections.
            groups = [alwaysSection,mainTab,initTab];
        end
    end
end

Resulting Dialog Box

load_system('ShowSystemBlockDialog')
open_system('ShowSystemBlockDialog/MATLAB System')

Define Property Sections

This example customizes the block dialog box for a MATLAB System block by specifying property display names and modifying the getPropertyGroupImpl method. This customization is demonstrated with the System object™ AddPropertySections.

Change Property Labels

To change the property label that appears on the dialog box, add comments before each property in this format %PropertyName Block Dialog Label with no space between the percent sign and the property name. For example, to display the UseAlpha property as Use alpha, specify:

%UseAlpha Use alpha
UseAlpha = 0

The AddPropertySections System object included with this example relabels properties for display in the MATLAB System block dialog.

Organize Dialog Box

To organize the properties on the dialog box, the AddPropertySections System object class defines a getPropertyGroupsImpl method. Inside the getPropertyGroupsImpl method, this example defines two sections, each with two properties.

classdef AddPropertySections < matlab.System
    % AddPropertySections Customized dialog with two parameter sections
    
    % Public, tunable properties
    properties
        
        %NumberOfShapes Number of shapes
        NumberOfShapes = 10
        
        Alpha = 0.75
    end
 
    % Public, nontunable properties
    properties(Nontunable)
        Coloring (1, 1) {mustBeMember(Coloring,["red","blue","green"])} = "red"

        %UseAlpha Use alpha
        UseAlpha (1,1) logical = false
    end
    
    methods (Static, Access = protected)
        function groups = getPropertyGroupsImpl           
            % Section for the value parameters
            valueSection = matlab.system.display.Section(...
                'Title','Shape parameters',...
                'PropertyList',{'NumberOfShapes','Coloring'});
            
            % Section for the threshold parameters
            shadingSection = matlab.system.display.Section(...
                'Title','Shading parameters',...
                'PropertyList',{'UseAlpha','Alpha'});
            
            % Return an array with the two sections.
            groups = [valueSection, shadingSection];
        end
    end
end

Resulting Dialog Box

load_system('CustomSystemBlockDialog')
open_system('CustomSystemBlockDialog/MATLAB System')

Add Header Description

Add a header panel to a MATLAB System block by adding the getHeaderImpl method to your System object.

Use getHeaderImpl to specify a panel title and text for the MyCounter System object. If you do not specify the getHeaderImpl, the block does not display any title or text for the panel.

As for all Impl methods, set the getHeaderImpl method access to protected because the method is only called internally.

methods (Static, Access = protected)
   function header = getHeaderImpl
      header = matlab.system.display.Header('MyCounter',...
        'Title','My Enhanced Counter');
   end
end

 Complete Class Definition

 classdef MyCounter < matlab.System
  
   % MyCounter Count values
     
    properties
       Threshold = 1
    end
    properties (DiscreteState)
       Count
    end
 
    methods (Static, Access = protected)
      function header = getHeaderImpl
         header = matlab.system.display.Header('MyCounter',...
           'Title','My Enhanced Counter',...
           'Text', 'This counter is an enhanced version.');
      end
    end

    methods (Access = protected)
       function setupImpl(obj,u)
          obj.Count = 0;
       end
       function y = stepImpl(obj,u)
          if (u > obj.Threshold)
             obj.Count = obj.Count + 1;
          end
          y = obj.Count;
       end
       function resetImpl(obj)
          obj.Count = 0;
       end
    end
end

Control Simulation Type in MATLAB System Block

Specify a simulation type and whether the Simulate using parameter appears on the Simulink^® MATLAB System block dialog box. The simulation options are 'Code generation' and 'Interpreted mode'.

If you do not include the getSimulateUsingImpl method in your class definition file, the System object allows both simulation modes and defaults to 'Code generation'. If you do not include the showSimulateUsingImpl method, the Simulate using parameter appears on the block dialog box.

You must set the getSimulateUsingImpl and showSimulateUsingImpl methods to static and the access for these methods to protected.

Use getSimulateUsingImpl to specify that only interpreted execution is allowed for the System object.

methods(Static,Access = protected)
   function simMode = getSimulateUsingImpl
       simMode = 'Interpreted execution';
    end
end

 Complete Class Definition

classdef PlotRamp < matlab.System
  % Display a button to launch a plot figure.
        
  properties (Nontunable)
    RampLimit = 10;
  end
    
  methods(Static, Access=protected)
    function group = getPropertyGroupsImpl
      group = matlab.system.display.Section(mfilename('class'));
      group.Actions = matlab.system.display.Action(@(~,obj)...
            visualize(obj),'Label','Visualize');
    end

    function simMode = getSimulateUsingImpl
      simMode = 'Interpreted execution';
    end
  end
    
  methods
    function obj = ActionDemo(varargin)
      setProperties(obj,nargin,varargin{:});
    end
        
    function visualize(obj)
      figure;
      d = 1:obj.RampLimit;
      plot(d);
    end
   methods(Static,Access = protected)
   end
  end
end

The resulting dialog box with the Simulate using parameter:

Add Custom Button to MATLAB System Block

Add a button to the MATLAB System block dialog box. This button opens a figure that plots a ramp function.

Use matlab.system.display.Action to define the MATLAB^® function or code associated with a button in the MATLAB System block dialog box. The example also shows how to set button options and use an actionData object input to store a figure handle. This part of the code example uses the same figure when the button is clicked multiple times, rather than opening a new figure for each button click.

methods(Static,Access = protected)
  function group = getPropertyGroupsImpl
    group = matlab.system.display.Section(mfilename('class'));
    group.Actions = matlab.system.display.Action(@(actionData,obj)...
       visualize(obj,actionData),'Label','Visualize');
  end
end
    
methods
  function obj = ActionDemo(varargin)
    setProperties(obj,nargin,varargin{:});
  end
        
  function visualize(obj,actionData)
    f = actionData.UserData;
    if isempty(f) || ~ishandle(f)
      f = figure;
      actionData.UserData = f;
    else
      figure(f); % Make figure current
    end
        
    d = 1:obj.RampLimit;
    plot(d);
  end
end

 Complete Class Definition File for Dialog Button

Define a property group and a second tab in the class definition file.

classdef PlotRamp < matlab.System
  % Display a button to launch a plot figure.
        
  properties (Nontunable)
    RampLimit = 10;
  end
    
  methods(Static,Access = protected)
    function group = getPropertyGroupsImpl
      group = matlab.system.display.Section(mfilename('class'));
      group.Actions = matlab.system.display.Action(@(actionData,obj)...
        visualize(obj,actionData),'Label','Visualize');
    end
  end
    
  methods
    function obj = ActionDemo(varargin)
      setProperties(obj,nargin,varargin{:});
    end
        
    function visualize(obj,actionData)
      f = actionData.UserData;
      if isempty(f) || ~ishandle(f)
        f = figure;
        actionData.UserData = f;
      else
        figure(f); % Make figure current
      end
        
      d = 1:obj.RampLimit;
      plot(d);
    end
  end
end

The resulting dialog box with the Visualize button: