Simulink®

Adding Items to Model Editor Menus

About Adding Items to the Model Editor Menus

You can add commands and submenus to the end of the Simulink^® model editor menus. Adding an item to the end of a Model Editor menu entails performing the following tasks:

• For each item, create a function, called a schema function, that defines the item (see Defining 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 Registering Menu Customizations).

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

Back to Top

Code Example

The following sl_customization.m file adds four items to the 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

Back to Top

Defining 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'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';

  %% 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 string that identifies this action, for example, so that it can be referenced by a filter function.

• label

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

• state

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

• statustip

  String 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

  String specifying a keyboard shortcut that a user may use to trigger this action. The string must be of the form 'Ctrl+K', where K is the shortcut key. For example, 'Ctrl+T' specifies that the user may invoke this action by holding down the Ctrl key and pressing the T key.

• callback

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

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 string that identifies this toggle action, for example, so that it can be referenced by a filter function.

• label

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

• checked

  This property must be set to one of the following values:

  'checked'	Menu item displays a check mark.
  'unchecked'	Menu item does not display a check mark.

• state

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

• statustip

  String 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

  String specifying a keyboard shortcut that a user may use to trigger this action. The string must be of the form 'Ctrl+K', where K is the shortcut key. For example, 'Ctrl+T' specifies that the user may invoke this action by holding down the Ctrl key and pressing the T key.

• callback

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

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 string that identifies this submenu.

• label

  String specifying the submenu's label.

• state

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

• statustip

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

• userdata

  Data that you specify. May be of any type.

• 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 Defining 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. This case is ignored for this entry, e.g., 'SEPARATOR' and 'Separator' are valid entries. A separator is also suppresses if it would appear at the beginning or end of the submenu and combines separators that would appear successively (e.g., as a result of an item being hidden) into a single separator.

  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.

Back to Top

Registering 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 (see Customization Manager). Each invocation should pass the tag of the menu (see About 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 list of schema functions that define custom items that you want to appear on the model editor menus (see Defining Menu Items ).

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

Back to Top

Callback Info Object

Instances of these objects are passed to menu customization functions. Properties of these objects include

• uiObject

  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

  Handle to the model being displayed in the editor window.

• userdata

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

Back to Top

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 M-file debugger's keyboard commands to continue execution of the callback.

Back to Top

About Menu Tags

A menu tag is a string that identifies a Simulink Model Editor or Stateflow Chart Editor menu bar or menu. You need to know a menu's tag to add custom items to it (see Registering Menu Customizations). You can configure the editor to display all (see Displaying Menu Tags) but the following tags:

Displaying Menu Tags

You can configure the Simulink software (and the Stateflow product) 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. To configure the editor to display menu tags, set the customization manager's showWidgetIdAsToolTip property to true, e.g., by entering the following commands at the command line:

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.

Back to Top

Customizing the Simulink® User Interface

Disabling and Hiding Model Editor Menu Items