Add Items to Model Editor Menus

You can add commands and submenus to context menus for the Simulink^® Editor and Stateflow^® Editor. Menu bar customization will be removed in a future release. To customize the Simulink Toolstrip, use custom tabs. For more information on custom tabs, see Create Custom Simulink Toolstrip Tabs. To convert an existing toolbar menu into a toolstrip tab, use slConvertCustomMenus.

To add an item to a 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 bottom of the context menu that appears when you right-click the Simulink Editor canvas.

function sl_customization(cm)

  %% Register custom menu function.
  cm.addCustomMenuFcn('Simulink:ContextMenu', @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
Defining Custom Submenus

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 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 label.
  schema.label = 'My Item 1';
  schema.userdata = 'item1';

  %% Specify the menu item 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:

Property	Description
`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'`(default) – The action appears in the menu and can be selected `'Disabled'`– The action appears in the menu but cannot be selected `'Hidden'`– The action does not appear in the menu
`statustip`	Character vector specifying text to appear in the editor status bar when the user selects the menu item that triggers this action.
`userdata`	Data that you specify, which can 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 (to be removed) 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. `'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:

Property	Description
`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`	Property that specifies the state of this toggle action. Valid values are: `'Enabled'`(default) – The action appears in the menu and can be selected `'Disabled'`– The action appears in the menu but cannot be selected `'Hidden'`– The action does not appear in the menu
`statustip`	Character vector specifying text to appear in the editor status bar when the user selects the menu item that triggers this toggle action.
`userdata`	Data that you specify, which can 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 (to be removed) 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. `'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 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:

Property	Description
`tag`	Optional character vector that identifies this submenu.
`label`	Character vector specifying the submenu label.
`state`	Character vector that specifies the state of this submenu. Valid values are `'Enabled'` (default), `'Disabled'`, and `'Hidden'`.
`statustip`	Character vector specifying text to appear in the editor 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, this 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. 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. `'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 Register Customizations with Simulink) to perform this task. In particular, for each menu that you want to customize, your system sl_customization function must invoke the customization manager 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:

Method or Property	Description
`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 menu, a Stateflow Editor menu, or a context menu. You need to know the tag for a menu to add custom items to it (see Register Menu Customizations).

Tag	What It Adds
Simulink tags
`Simulink:MenuBar` (to be removed)	Menu to the Simulink Editor menu bar
`Simulink:PreContextMenu`	Item to the beginning of a Simulink Editor context menu
`Simulink:ContextMenu`	Item to the end of a Simulink Editor context menu
`Simulink:FileMenu` (to be removed)	Item to the end of a Simulink Editor File menu
`Simulink:EditMenu` (to be removed)	Item to the end of a Simulink Editor Edit menu
`Simulink:ViewMenu` (to be removed)	Item to the end of a Simulink Editor View menu
`Simulink:DisplayMenu` (to be removed)	Item to the end of a Simulink Editor Display menu
`Simulink:DiagramMenu` (to be removed)	Item to the end of a Simulink Editor Diagram menu
`Simulink:SimulationMenu` (to be removed)	Item to the end of a Simulink Editor Simulation menu
`Simulink:AnalysisMenu` (to be removed)	Item to the end of a Simulink Editor Analysis menu
`Simulink:CodeMenu` (to be removed)	Item to the end of a Simulink Editor Code menu
`Simulink:ToolsMenu` (to be removed)	Item to the end of a Simulink Editor Tools menu
`Simulink:HelpMenu` (to be removed)	Item to the end of a Simulink Editor Help menu
Stateflow tags
`Stateflow:MenuBar` (to be removed)	Menu to the Stateflow Editor menu bar
`Stateflow:PreContextMenu`	Item to the beginning of a Stateflow Editor context menu.
`Stateflow:ContextMenu`	Items to the end of a Stateflow Editor context menu.
`Stateflow:FileMenu` (to be removed)	Item to the end of a Stateflow Editor File menu
`Stateflow:EditMenu` (to be removed)	Item to the end of a Stateflow Editor Edit menu
`Stateflow:ViewMenu` (to be removed)	Item to the end of a Stateflow Editor View menu
`Stateflow:DisplayMenu` (to be removed)	Item to the end of a Stateflow Editor Display menu
`Stateflow:ChartMenu` (to be removed)	Item to the end of a Stateflow Editor Chart menu
`Stateflow:SimulationMenu` (to be removed)	Item to the end of a Stateflow Editor Simulation menu
`Stateflow:AnalysisMenu` (to be removed)	Item to the end of a Stateflow Editor Analysis menu
`Stateflow:CodeMenu` (to be removed)	Item to the end of a Stateflow Editor Code menu
`Stateflow:ToolsMenu` (to be removed)	Item to the end of a Stateflow Editor Tools menu
`Stateflow:HelpMenu` (to be removed)	Item to the end of a Stateflow Editor Help menu

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.