Add Items to Model Editor Menus

About Adding Items

You can add commands and submenus to these menu locations for the Simulink® Editor and Stateflow® Editor:

  • The end of top-level menus

  • The menu bar

  • The beginning or end of a context menu

To add an item to an editor menu:

  • For each item, create a function, called a schema function, that defines the item (see Define Menu Items).

  • Register the menu customizations with the Simulink customization manager at startup, e.g., in an sl_customization.m file on the MATLAB® path (see Register Menu Customizations).

  • Create callback functions that implement the commands triggered by the items that you add to the menus.

Code for Adding Menu Items

The following sl_customization.m file adds four items to the Simulink Editor’s Tools menu.

function sl_customization(cm)

  %% Register custom menu function.
  cm.addCustomMenuFcn('Simulink:ToolsMenu', @getMyMenuItems);
end

%% Define the custom menu function.
function schemaFcns = getMyMenuItems(callbackInfo) 
  schemaFcns = {@getItem1, ...
               @getItem2, ...
               {@getItem3,3}, ... %% Pass 3 as user data to getItem3.
               @getItem4}; 
end

%% Define the schema function for first menu item.
function schema = getItem1(callbackInfo)
  schema = sl_action_schema;
  schema.label = 'Item One';
  schema.userdata = 'item one';	
  schema.callback = @myCallback1; 
end

function myCallback1(callbackInfo)
  disp(['Callback for item ' callbackInfo.userdata ' was called']);
end

function schema = getItem2(callbackInfo)
  % Make a submenu label 'Item Two' with     
  % the menu item above three times.      
  schema = sl_container_schema;
  schema.label = 'Item Two';     
	schema.childrenFcns = {@getItem1, @getItem1, @getItem1};
end 

function schema = getItem3(callbackInfo)
  % Create a menu item whose label is
  % 'Item Three: 3', with the 3 being passed
  % from getMyItems above.

  schema = sl_action_schema;
  schema.label = ['Item Three: ' num2str(callbackInfo.userdata)];
end

function myToggleCallback(callbackInfo)
    if strcmp(get_param(gcs, 'ScreenColor'), 'red') == 0
        set_param(gcs, 'ScreenColor', 'red');
    else
        set_param(gcs, 'ScreenColor', 'white');
    end
end

%% Define the schema function for a toggle menu item.
function schema = getItem4(callbackInfo)
  schema = sl_toggle_schema;
  schema.label = 'Red Screen';
  if strcmp(get_param(gcs, 'ScreenColor'), 'red') == 1
    schema.checked = 'checked';
  else
    schema.checked = 'unchecked';
  end
  schema.callback = @myToggleCallback; 
end

Define Menu Items

You define a menu item by creating a function that returns an object, called a schema object, that specifies the information needed to create the menu item. The menu item that you define may trigger a custom action or display a custom submenu. See the following sections for more information.

Defining Menu Items That Trigger Custom Commands

To define an item that triggers a custom command, your schema function must accept a callback info object (see Callback Info Object) and create and return an action schema object (see Action Schema Object) that specifies the item's label and a function, called a callback, to be invoked when the user selects the item. For example, the following schema function defines a menu item that displays a message when selected by the user.

function schema = getItem1(callbackInfo) 

  %% Create an instance of an action schema.
  schema = sl_action_schema;

  
%% Specify the menu item's label.
  schema.label = 'My Item 1';
  schema.userdata = 'item1';
  %% Specify the menu item's callback function.
  schema.callback = @myCallback1;

end

function myCallback1(callbackInfo)
  disp(['Callback for item ' callbackInfo.userdata
        ' was called']); 
end 

Action Schema Object.  This object specifies information about menu items that trigger commands that you define, including the label that appears on the menu item and the function to be invoked when the user selects the menu item. Use the function sl_action_schema to create instances of this object in your schema functions. Its properties include:

  • tag

    Optional character vector that identifies this action, for example, so that it can be referenced by a filter function.

  • label

    Character vector specifying the label that appears on a menu item that triggers this action.

  • state

    Property that specifies the state of this action. Valid values are 'Enabled' (the default), 'Disabled', and 'Hidden'.

  • statustip

    Character vector specifying text to appear in the editor's status bar when the user selects the menu item that triggers this action.

  • userdata

    Data that you specify. May be of any type.

  • accelerator

    Character vector specifying a Ctrl and key combination to use to trigger this action. You can add a keyboard shortcut only for custom menu items that appear on menu bar menus and cannot redefine accelerators that come with the Simulink Editor. For example, Ctrl+D is an accelerator for Update Diagram in the Simulink Editor, so you cannot redefine it.

    To specify this value, use the form 'Ctrl+K', where K is the shortcut key. For example, use 'Ctrl+Alt+T' for an accelerator invoked by holding down Ctrl and Alt and pressing T.

  • callback

    Character vector specifying a MATLAB expression to be evaluated or a handle to a function to be invoked when a user selects the menu item that triggers this action. This function must accept one argument: a callback info object.

  • autoDisableWhen

    Property that controls when a menu item is automatically disabled.

    SettingWhen Menu Items Are Disabled
    'Locked'

    (default) When the active editor is locked or when the model is busy

    'Busy'

    Only if the model is busy

    'Never'

    Never

Toggle Schema Object.  This object specifies information about a menu item that toggles some object on or off. Use the function sl_toggle_schema to create instances of this object in your schema functions. Its properties include:

  • tag

    Optional character vector that identifies this toggle action, for example, so that it can be referenced by a filter function.

  • label

    Character vector specifying the label that appears on a menu item that triggers this toggle action.

  • checked

    Specify whether the menu item displays a check mark. Valid values are 'unchecked' (default) and 'checked'

  • state

    State of this toggle action, specified as 'Enabled' (default), 'Disabled', and 'Hidden'.

  • statustip

    Character vector specifying text to appear in the editor's status bar when the user selects the menu item that triggers this toggle action.

  • userdata

    Data that you specify. May be of any type.

  • accelerator

    Character vector specifying a Ctrl and key combination to use to trigger this action. You can add a keyboard shortcut only for custom menu items that appear on menu bar menus and cannot redefine accelerators that come with the Simulink Editor. For example, Ctrl+D is an accelerator for Update Diagram in the Simulink Editor, so you cannot redefine it.

    To specify this value, use the form 'Ctrl+K', where K is the shortcut key. For example, use 'Ctrl+Alt+T' for an accelerator invoked by holding down Ctrl and Alt and pressing T.

  • callback

    Character vector specifying a MATLAB expression to be evaluated or a handle to a function to be invoked when a user selects the menu item that triggers this action. This function must accept one argument: a callback info object.

  • autoDisableWhen

    Property that controls when a menu item is automatically disabled.

    SettingWhen Menu Items Are Disabled
    'Locked'

    (default) When the active editor is locked or when the model is busy

    'Busy'

    Only if the model is busy

    'Never'

    Never

Defining Custom Submenus

To define a submenu, create a schema function that accepts a callback info object and returns a container schema object (see Container Schema Object) that specifies the schemas that define the items on the submenu. For example, the following schema function defines a submenu that contains three instances of the menu item defined in the example in Defining Menu Items That Trigger Custom Commands.

function schema = getItem2( callbackInfo )
    schema = sl_container_schema;
    schema.label = 'Item Two';
    schema.childrenFcns = {@getItem1, @getItem1, @getItem1};
end

Container Schema Object.  A container schema object specifies a submenu’s label and its contents. Use the function sl_container_schema to create instances of this object in your schema functions. Properties of the object include

  • tag

    Optional character vector that identifies this submenu.

  • label

    Character vector specifying the submenu’s label.

  • state

    Character vector that specifies the state of this submenu. Valid values are 'Enabled' (the default), 'Disabled', and 'Hidden'.

  • statustip

    Character vector specifying text to appear in the editor's status bar when the user selects this submenu.

  • childrenFcns

    Cell array that specifies the contents of the submenu. Each entry in the cell array can be

    • A pointer to a schema function that defines an item on the submenu (see Define Menu Items)

    • A two-element cell array whose first element is a pointer to a schema function that defines an item entry and whose second element is data to be inserted as user data in the callback info object (see Callback Info Object) passed to the schema function

    • 'separator', which causes a separator to appear between the item defined by the preceding entry in the cell array and the item defined in the following entry. The case is ignored for this entry (for example, 'SEPARATOR' and 'Separator' are both valid entries). A separator is also suppressed if it appears at the beginning or end of the submenu and separators that would appear successively are combined into a single separator (for example, as a result of an item being hidden).

    For example, the following cell array specifies two submenu entries:

    {@getItem1, 'separator', {@getItem2, 1}}

    In this example, a 1 is passed to getItem2 via a callback info object.

  • generateFcn

    Pointer to a function that returns a cell array defining the contents of the submenu. The cell array must have the same format as that specified for the container schema objects childrenFcns property.

    Note

    The generateFcn property takes precedence over the childrenFcns property. If you set both, the childrenFcns property is ignored and the cell array returned by the generateFcn is used to create the submenu.

  • userdata

    Data of any type that is passed to generateFcn.

  • autoDisableWhen

    Property that controls when a menu item is automatically disabled.

    SettingWhen Menu Items Are Disabled
    'Locked'

    (default) When the active editor is locked or when the model is busy

    'Busy'

    Only if the model is busy

    'Never'

    Never

Register Menu Customizations

You must register custom items to be included on a Simulink menu with the customization manager. Use the sl_customization.m file for a Simulink installation (see Registering Customizations) to perform this task. In particular, for each menu that you want to customize, your system's sl_customization function must invoke the customization manager's addCustomMenuFcn method. Each invocation should pass the tag of the menu (see Menu Tags) to be customized and a custom menu function that specifies the items to be added to the menu (see Creating the Custom Menu Function) . For example, the following sl_customization function adds custom items to the Simulink Tools menu.

function sl_customization(cm)
  %% Register custom menu function.
  cm.addCustomMenuFcn('Simulink:ToolsMenu', @getMyItems);

Creating the Custom Menu Function

The custom menu function returns a cell array of schema functions that define custom items that you want to appear on the model editor menus (see Define Menu Items ). The custom menu function returns a cell array similar to that returned by the generateFcn function.

Your custom menu function should accept a callback info object (see Callback Info Object) and return a cell array that lists the schema functions. Each element of the cell array can be either a handle to a schema function or a two-element cell array whose first element is a handle to a schema function and whose second element is user-defined data to be passed to the schema function. For example, the following custom menu function returns a cell array that lists three schema functions.

function schemas = getMyItems(callbackInfo)
  schemas = {@getItem1, ...
            @getItem2, ...
            {@getItem3,3} }; % Pass 3 as userdata to getItem3.
end

Callback Info Object

Instances of these objects are passed to menu customization functions. Methods and properties of these objects include:

  • uiObject

    Method to get the handle to the owner of the menu for which this is the callback. The owner can be the Simulink Editor or the Stateflow Editor.

  • model

    Method to get the handle to the model being displayed in the editor window.

  • userdata

    User data property. The value of this property can be any type of data.

Debugging Custom Menu Callbacks

On systems using the Microsoft® Windows® operating system, selecting a custom menu item whose callback contains a breakpoint can cause the mouse to become unresponsive or the menu to remain open and on top of other windows. To fix these problems, use the MATLAB code debugger keyboard commands to continue execution of the callback.

Menu Tags

A menu tag identifies a Simulink Editor or the Stateflow Editor menu bar or menu. You need to know a menu's tag to add custom items to it (see Register Menu Customizations). You can configure the editor to display all (see Displaying Menu Tags) but these tags.

TagWhat it adds
Simulink tags
Simulink:MenuBarMenu to Simulink Editor's menu bar
Simulink:PreContextMenuItem to the beginning of Simulink Editor's context menu
Simulink:ContextMenuItem to the end of Simulink Editor's context menu
Simulink:FileMenuItem near the end of the Simulink Editor's File menu, but before the Exit MATLAB item
Simulink:EditMenuItem to the end of the Simulink Editor's Edit menu
Simulink:ViewMenuItem to the end of the Simulink Editor's View menu
Simulink:DisplayMenuItem to the end of the Simulink Editor's Display menu
Simulink:DiagramMenuItem to the end of the Simulink Editor's Diagram menu
Simulink:SimulationMenuItem to the end of the Simulink Editor's Simulation menu
Simulink:AnalysisMenuItem to the end of the Simulink Editor's Analysis menu
Simulink:CodeMenuItem to the end of the Simulink Editor's Code menu
Simulink:ToolsMenuItem to the end of the Simulink Editor's Tools menu
Simulink:HelpMenuItem to the end of Simulink Editor's Help menu
Stateflow tags
Stateflow:MenuBarMenu to Stateflow Editor's menu bar
Stateflow:PreContextMenuItem to the beginning of Stateflow Editor's context menu.
Stateflow:ContextMenuItems to the end of Stateflow Editor's context menu.
Stateflow:FileMenuItem near the end of the Stateflow Editor's File menu, but before the Exit MATLAB item
Stateflow:EditMenuItem to the end of Stateflow Editor's Edit menu
Stateflow:ViewMenuItem to the end of the Stateflow Editor's View menu
Stateflow:DisplayMenuItem to the end of the Stateflow Editor's Display menu
Stateflow:ChartMenuItem to the end of the Stateflow Editor's Chart menu
Stateflow:SimulationMenuItem to the end of the Stateflow Editor's Simulation menu
Stateflow:AnalysisMenuItem to the end of the Stateflow Editor's Analysis menu
Stateflow:CodeMenuItem to the end of the Stateflow Editor's Code menu
Stateflow:ToolsMenuItem to the end of the Stateflow Editor's Tools menu
Stateflow:HelpMenuItem to the end of the Stateflow Editor's Help menu

Displaying Menu Tags

You can configure the Simulink and Stateflow software to display the tag for a menu item next to the item's label, allowing you to determine at a glance the tag for a menu. The Simulink:TagName customizations appear only if the current editor is the Simulink Editor. The Stateflow:TagName customizations appear only if the current editor is the Stateflow Editor.

To configure the editor to display menu tags, at the MATLAB command line, set the customization manager's showWidgetIdAsToolTip property to true. For example:

cm = sl_customization_manager;
cm.showWidgetIdAsToolTip=true;

The tag of each menu item appears next to the item's label on the menu:

To turn off tag display, enter the following command at the command line:

cm.showWidgetIdAsToolTip=false;

Note

Some menu items may not work while menu tag display is enabled. To ensure that all items work, turn off menu tag display before using the menus.

Simulink and Stateflow Editor Menu Customization

Use the same general procedures to customize Stateflow Editor menus as you use for Simulink Editor. The addition of custom menu functions to the ends of top-level menus depends on the active editor:

  • Menus bound to Simulink:FileMenu only appear when the Simulink Editor is active.

  • Menus bound to Stateflow:FileMenu only appear when the Stateflow Editor is active.

  • To have a menu to appear in both of the editors, call addCustomMenuFcn twice, once for each tag. Check that the code works in both editors.

Related Topics