Documentation Center

  • Trial Software
  • Product Updates

Create Menus for Programmatic GUIs

Add Menu Bar Menus

Use the uimenu function to add a menu bar menu to your GUI. A syntax for uimenu is

mh = uimenu(parent,'PropertyName',PropertyValue,...)

Where mh is the handle of the resulting menu or menu item. See the uimenu reference page for other valid syntaxes.

These topics discuss use of the MATLAB® standard menu bar menus and describe commonly used menu properties and offer some simple examples.

Display Standard Menu Bar Menus

Displaying the standard menu bar menus is optional.

If you use the standard menu bar menus, any menus you create are added to it. If you choose not to display the standard menu bar menus, the menu bar contains only the menus that you create. If you display no standard menus and you create no menus, the menu bar itself does not display.

Use the figure MenuBar property to display or hide the MATLAB standard menu bar shown in the preceding figure. Set MenuBar to figure (the default) to display the standard menus. Set MenuBar to none to hide them.

set(fh,'MenuBar','figure');  % Display standard menu bar menus.
set(fh,'MenuBar','none');    % Hide standard menu bar menus.

In these statements, fh is the handle of the figure.

Commonly Used Properties

The most commonly used properties needed to describe a menu bar menu are shown in the following table.

Property

Values

Description

Accelerator

Alphabetic character

Keyboard equivalent. Available for menu items that do not have submenus.

Checked

off, on. Default is off.

Menu check indicator

Enable

on, off. Default is on.

Controls whether a menu item can be selected. When set to off, the menu label appears dimmed.

HandleVisibility

on, off. Default is on.

Determines if an object's handle is visible in its parent's list of children. For menus, set HandleVisibility to off to protect menus from operations not intended for them.

Label

String

Menu label.

To display the & character in a label, use two & characters in the string.

The words remove, default, and factory (case sensitive) are reserved. To use one of these as a label, prepend a backslash (\) to the string. For example, \remove yields remove.

Position

Scalar. Default is 1.

Position of a menu item in the menu.

Separator

off, on. Default is off.

Separator line mode

For a complete list of properties and for more information about the properties listed in the table, see the Uimenu Properties documentation.

How Menus Affect Figure Docking

When you customize the menu bar or toolbar, you can display the GUI's docking controls or not by setting DockControls appropriately, as long as the figure's WindowStyle does not conflict with that setting. You might not need menus for your GUI, but if you want the user to be able to dock or undock the GUI, it must contain a menu bar or a toolbar. This is because docking is controlled by the docking icon, a small curved arrow near the upper-right corner of the menu bar or the toolbar, as the following illustration shows.

Figure windows with a standard menu bar also have a Desktop menu from which the user can dock and undock them.

To display the docking arrow and the Desktop > Dock Figure menu item, the figure property DockControls must be set to 'on'. You can set it in the Property Inspector. In addition, the MenuBar and/or ToolBar figure properties must be set to 'on' to display docking controls.

The WindowStyle figure property also affects docking behavior. The default is 'normal', but if you change it to 'docked', then the following applies:

  • The GUI opens docked in the desktop when you run it.

  • The DockControls property is set to 'on' and cannot be turned off until WindowStyle is no longer set to 'docked'.

  • If you undock a GUI created with WindowStyle 'docked', it will have not have a docking arrow unless the figure displays a menu bar or a toolbar (either standard or customized). When it has no docking arrow, users can undock it from the desktop, but will be unable to redock it there.

To summarize, you can display docking controls with the DockControls property as long as it is not in conflict with the figure's WindowStyle property.

    Note:   GUIs that are modal dialogs (figures with WindowStyle 'modal') cannot have menu bars, toolbars, or docking controls.

For more information, see the DockControls, MenuBar, ToolBar, and WindowStyle property descriptions on the figure properties reference page.

Menu Bar Menu

The following statements create a menu bar menu with two menu items.

mh = uimenu(fh,'Label','My menu');
eh1 = uimenu(mh,'Label','Item 1');
eh2 = uimenu(mh,'Label','Item 2','Checked','on');

fh is the handle of the parent figure.

mh is the handle of the parent menu.

The Label property specifies the text that appears in the menu.

The Checked property specifies that this item is displayed with a check next to it when the menu is created.

If your GUI displays the standard menu bar, the new menu is added to it.

If your GUI does not display the standard menu bar, MATLAB software creates a menu bar if none exists and then adds the menu to it.

The following statement adds a separator line preceding the second menu item.

set(eh2,'Separator','on');

The following statements add two menu subitems to Item 1, assign each subitem a keyboard accelerator, and disable the first subitem.

seh1 = uimenu(eh1,'Label','Choice 1','Accelerator','C',...
              'Enable','off');
seh2 = uimenu(eh1,'Label','Choice 2','Accelerator','H');

The Accelerator property adds keyboard accelerators to the menu items. Some accelerators may be used for other purposes on your system and other actions may result.

The Enable property disables the first subitem Choice 1 so a user cannot select it when the menu is first created. The item appears dimmed.

    Note   After you have created all menu items, set their HandleVisibility properties off by executing the following statements:

    menuhandles = findall(figurehandle,'type','uimenu');
    set(menuhandles,'HandleVisibility','off')

See the section, Menu Item, for information about programming menu items.

Add Context Menus to a Programmatic GUI

Context menus appear when the user right-clicks on a figure or GUI component. Follow these steps to add a context menu to your GUI:

  1. Create the context menu object using the uicontextmenu function.

  2. Add menu items to the context menu using the uimenu function.

  3. Associate the context menu with a graphics object using the object's UIContextMenu property.

Subsequent topics describe commonly used context menu properties and explain each of these steps:

Commonly Used Properties

The most commonly used properties needed to describe a context menu object are shown in the following table. These properties apply only to the menu object and not to the individual menu items.

Property

Values

Description

HandleVisibility

on, off. Default is on.

Determines if an object's handle is visible in its parent's list of children. For menus, set HandleVisibility to off to protect menus from operations not intended for them.

Parent

Figure handle

Handle of the context menu's parent figure.

Position

2-element vector: [distance from left, distance from bottom]. Default is [0 0].

Distances from the bottom left corner of the parent figure to the top left corner of the context menu. This property is used only when you programmatically set the context menu Visible property to on.

Visible

off, on. Default is off

  • Indicates whether the context menu is currently displayed. While the context menu is displayed, the property value is on; when the context menu is not displayed, its value is off.

  • Setting the value to on forces the posting of the context menu. Setting to off forces the context menu to be removed. The Position property determines the location where the context menu is displayed.

For a complete list of properties and for more information about the properties listed in the table, see the Uicontextmenu Properties reference page.

Create the Context Menu Object

Use the uicontextmenu function to create a context menu object. The syntax is

handle = uicontextmenu('PropertyName',PropertyValue,...)

The parent of a context menu must always be a figure. Use the context menu Parent property to specify its parent. If you do not specify Parent, the parent is the current figure as specified by the root CurrentFigure property.

The following code creates a figure and a context menu whose parent is the figure.

fh = figure('Position',[300 300 400 225]);
cmenu = uicontextmenu('Parent',fh,'Position',[10 215]);

At this point, the figure is visible, but not the menu.

Add Menu Items to the Context Menu

Use the uimenu function to add items to the context menu. The items appear on the menu in the order in which you add them. The following code adds three items to the context menu created above.

mh1 = uimenu(cmenu,'Label','Item 1');
mh2 = uimenu(cmenu,'Label','Item 2');
mh3 = uimenu(cmenu,'Label','Item 3');

If you could see the context menu, it would look like this:

You can use any applicable Uimenu Properties such as Checked or Separator when you define context menu items. See the uimenu reference page and Add Menu Bar Menus for information about using uimenu to create menu items. Note that context menus do not have an Accelerator property.

    Note   After you have created the context menu and all its items, set their HandleVisibility properties to off by executing the following statements:

    cmenuhandles = findall(figurehandle,'type','uicontextmenu');
    set(cmenuhandles,'HandleVisibility','off')
    menuitemhandles = findall(cmenuhandles,'type','uimenu');
    set(menuitemhandles,'HandleVisibility','off')

Associate the Context Menu with Graphics Objects

You can associate a context menu with the figure itself and with all components that have a UIContextMenu property. This includes axes, panel, button group, all user interface controls (uicontrols).

The following code adds a panel and an axes to the figure. The panel contains a single push button.

ph = uipanel('Parent',fh,'Units','pixels',...
            'Position',[20 40 150 150]);
bh1 = uicontrol(ph,'String','Button 1',...
            'Position',[20 20 60 40]);
ah = axes('Parent',fh,'Units','pixels',...
            'Position',[220 40 150 150]);

This code associates the context menu with the figure and with the axes by setting the UIContextMenu property of the figure and the axes to the handle cmenu of the context menu.

set(fh,'UIContextMenu',cmenu);   % Figure
set(ah,'UIContextMenu',cmenu);   % Axes

Right-click on the figure or on the axes. The context menu appears with its upper-left corner at the location you clicked. Right-click on the panel or its push button. The context menu does not appear.

Force Display of the Context Menu

If you set the context menu Visible property on, the context menu is displayed at the location specified by the Position property, without the user taking any action. In this example, the context menu Position property is [10 215].

set(cmenu,'Visible','on');

The context menu is displayed 10 pixels from the left of the figure and 215 pixels from the bottom.

If you set the context menu Visible property to off, or if the user clicks the GUI outside the context menu, the context menu disappears.

Was this topic helpful?