matlab.system.display.Action Class

Namespace: matlab.system.display
Superclasses: uint16

Create custom button in Block Parameters dialog box for MATLAB System block

Description

Use the matlab.system.display.Action class to implement a custom button in the Block Parameters dialog box for a MATLAB System block. The button can invoke a System object™ method or run any other MATLAB^® code.

For example, you could implement a button that creates a figure. The figure the button creates is decoupled from the block and the block dialog box such that changes to the block do not sync to the figure after the figure is created.

Define the matlab.system.display.Action class within the getPropertyGroupsImpl method in the class definition file. You can define multiple custom buttons by defining separate instances of the matlab.system.display.Action class in your class definition file.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

actionButton = matlab.system.display.Action(act) creates a button in the dialog box of a MATLAB System block and sets the property for the instance of the Action class that defines the button to act.

actionButton = matlab.system.display.Action(act,Name,Value) creates a button in the dialog box of a MATLAB System block with properties of the Action class that defines the button defined using one or more name-value arguments.

Properties

ActionCalledFcn — Code to execute when button is pressed

function handle | MATLAB command

Code to execute when button is pressed, specified as a function handle or a MATLAB command.

When you specify the button action as a function handle, the function signature must have these positional input arguments:

• An instance of the matlab.system.display.ActionData class

  The ActionData class is the callback object for a display action. Use the UserData property to store persistent data, such as a figure handle.

• A System object instance

Attributes:

GetAccess	public
SetAccess	public

Data Types: function_handle

Label — Text to display on button

'' (default) | string | character vector

Text to display on button, specified as a string or a character vector. By default, the button label is an empty character vector ('').

Example: 'Visualize'

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Description — Text to display in button tooltip

'' (default) | string | character vector

Text to display in button tooltip, specified as a string or a character vector. By default, the button tooltip text is an empty character vector ('').

Example: 'Visualize data in a figure window'

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Placement — Location of button within property group

'last' (default) | 'first' | string | character vector

Location of button within property group, specified as one of these options:

• 'last' — The button appears last within the property group on its own row.

• 'first' — The button appears first within the property group on its own row.

• A string or a character vector that defines the name of a property in the property group — The button appears on its own row above the specified property.

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Alignment — Alignment of button within row

'left' (default) | 'right'

Alignment of button within row, specified as 'left' or 'right'.

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Examples

Create Button in Block Parameters Dialog Box for MATLAB System Block

This example shows method definitions you can include in the class definition to implement a custom button in the Block Parameters dialog box for a MATLAB System block. The button in this example plots a ramp in a figure window using the values of other parameters specified using the Block Parameters dialog box for the block.

Create the button and specify the action when the button is pressed inside the getPropertyGroupImpl method definition.

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
end

In another part of the class definition file, define the functions the button calls when pressed. This example code results in functionality that opens a new figure window each time you press the button.

methods
  function obj = PlotRamp(varargin)
    setProperties(obj,nargin,varargin{:});
  end
        
  function visualize(obj)
    figure;
    d = 1:obj.RampLimit;
    plot(d);
  end
end

When the definition of the System object for the MATLAB System block includes this code, the Block Parameters dialog box for the MATLAB System block has a button labeled Visualize.

To open the same figure window each time the button is pressed instead of opening a new figure window with each press, use code like this instead.

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

Version History

Introduced in R2015a