Creating Menus :: Laying Out a GUIDE GUI (MATLAB®)

MATLAB^®

Creating Menus

On this page…
Menus for the Menu Bar Context Menus

On this page…

You can use GUIDE to give GUIs menu bars with pull-down menus as well as context menus that you attach to components. You can create both types of menus using the Menu Editor. Access the Menu Editor from the Tools menu or click the Menu Editor button .

menu editor

Note In general, programming conventions described for components in Programming a GUIDE GUI also apply to menu items. See Menu Item and Updating a Menu Item Check for information about programming and basic examples.

Menus for the Menu Bar

When you create a drop-down menu, GUIDE adds its title to the GUI menu bar. You then can create menu items for that menu. Each menu item can have a cascading menu, also known as a submenu, and these items can have cascading menus, and so on.

How Menus Affect Figure Docking

By default, when you create a GUI with GUIDE, it does not create a menu bar for that GUI. 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, use the Property Inspector to set the figure property DockControls to 'on'. You must also set the MenuBar and/or ToolBar figure properties 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.

However, when you provide your own menu bar or toolbar using GUIDE, it can display the docking arrow if you want the GUI to be dockable. See the following sections and Creating Toolbars for details.

Note GUIs that are modal dialogs (figures with WindowStyle set to '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, or select the figure background in GUIDE right-click these property names in the Property Inspector.

Adding Standard Menus to the Menu Bar

The figure MenuBar property controls whether your GUI displays the MATLAB standard menus on the menu bar. GUIDE initially sets the value of MenuBar to none. If you want your GUI to display the MATLAB standard menus, use the Property Inspector to set MenuBar to figure.

If the value of MenuBar is none, GUIDE automatically adds a menu bar that displays only the menus you create.
If the value of MenuBar is figure, the GUI displays the MATLAB standard menus and GUIDE adds the menus you create to the right side of the menu bar.

In either case, you can enable users of your GUI to dock and undock it using its docking arrow by setting the figure's DockControls property to 'on'.

Creating a Menu

Start a new menu by clicking the New Menu button in the toolbar. A menu title, Untitled 1, appears in the left pane of the dialog box.
Click the menu title to display a selection of menu properties in the right pane.
Fill in the Label and Tag fields for the menu. For example, set Label to File and set Tag to file_menu. Click outside the field for the change to take effect.
Label is a string that specifies the text label for the menu item. 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 labels, prepend a backslash (\) to the string. For example, \remove yields remove.
Tag is a string that is an identifier for the menu object. It is used in the code to identify the menu item and must be unique in the GUI.

Adding Items to a Menu

Use the New Menu Item tool to create menu items that are displayed in the drop-down menu.

Add an Open menu item under File, by selecting File then clicking the New Menu Item button in the toolbar. A temporary numbered menu item label, Untitled, appears.
Fill in the Label and Tag fields for the new menu item. For example, set Label to Open and set Tag to menu_file_open. Click outside the field for the change to take effect.

You can also

Choose an alphabetic keyboard accelerator for the menu item with the Accelerator pop-up menu. In combination with Ctrl, this is the keyboard equivalent for a menu item that does not have a child menu. Note that some accelerators may be used for other purposes on your system and that other actions may result.
Display a separator above the menu item by checking Separator above this item.
Display a check next to the menu item when the menu is first opened by checking Check mark this item. A check indicates the current state of the menu item. See the example in Adding Items to the Context Menu.
Enable this item when the menu is first opened by checking Enable this item. This allows the user to select this item when the menu is first opened. If you uncheck this option, the menu item appears dimmed when the menu is first opened, and the user cannot select it.
Specify a string for the routine, i.e., the Callback, that performs the action associated with the menu item. If you have not yet saved the GUI, the default value is %automatic. When you save the GUI, and if you have not changed this field, GUIDE automatically sets the value using a combination of the Tag field and the GUI filename. See Menu Item for more information about specifying this field and for programming menu items.
The View button displays the callback, if there is one, in an editor. If you have not yet saved the GUI, GUIDE prompts you to save it.
Open the Property Inspector, where you can change all menu properties, by clicking the More options button. For detailed information about the properties, see Uimenu Properties in the MATLAB documentation.

Note In general, programming conventions described for components in Programming a GUIDE GUI also apply to menu items. See Menu Item and Updating a Menu Item Check for programming information and basic examples.

Additional Drop-Down Menus

To create additional drop-down menus, use the New Menu button in the same way you did to create the File menu. For example, the following figure also shows an Edit drop-down menu.

Cascading Menus

To create a cascading menu, select the menu item that will be the title for the cascading menu, then click the New Menu Item button. In the example below, Copy is a cascading menu.

menu editor used to create a cascading menu

Note See Menu Item for information about programming menu items.

The following Menu Editor illustration shows three menus defined for the figure menu bar.

menu editor showing three menu types

When you run the GUI, the menu titles appear in the menu bar.

GUI with menu titles shown in menu bar

Context Menus

A context menu is displayed when a user right-clicks the object for which the menu is defined. The Menu Editor enables you to define context menus and associate them with objects in the layout. The process has three steps:

Note See Menus for the Menu Bar for information about defining menus in general. See Menu Item for information about defining callback subfunctions for your menus.

Creating the Parent Menu

All items in a context menu are children of a menu that is not displayed on the figure menu bar. To define the parent menu:

Select the Menu Editor's Context Menus tab and select the New Context Menu button from the toolbar.
Select the menu and specify the Tag field to identify the context menu (axes_context_menu in this example).

Adding Items to the Context Menu

Use the New Menu Item button to create menu items that are displayed in the context menu.

Add a Blue background color menu item to the menu by selecting axes_context_menu and clicking the New Menu Item tool. A temporary numbered menu item label, Untitled, appears.
Fill in the Label and Tag fields for the new menu item. For example, set Label to Blue background color and set Tag to blue_background. Click outside the field for the change to take effect.

You can also

Display a separator above the menu item by checking Separator above this item.
Display a check next to the menu item when the menu is first opened by checking Check mark this item. A check indicates the current state of the menu item. See the example in Adding Items to the Context Menu. See Updating a Menu Item Check for a code example.
Enable this item when the menu is first opened by checking Enable this item. This allows the user to select this item when the menu is first opened. If you uncheck this option, the menu item appears dimmed when the menu is first opened, and the user cannot select it.
Specify a Callback for the menu that performs the action associated with the menu item. If you have not yet saved the GUI, the default value is %automatic. When you save the GUI, and if you have not changed this field, GUIDE automatically creates a callback in the M-file using a combination of the Tag field and the GUI filename. The callback's name does not display in the Callback field of the Menu Editor, but selecting the menu item does trigger it.
You can also type an unquoted string into the Callback field to serve as a callback. It can be any valid MATLAB expression or command. For example, the string
```
set(gca, 'Color', 'y')
```
sets the current axes background color to yellow. However, the preferred approach to performing this operation is to place the callback in the GUI M-file. This avoids the use of gca, which is not always reliable when several figures or axes exist. Here is the M-file version of this callback:
```
function axesyellow_Callback(hObject, eventdata, handles)
% hObject    handle to axesyellow (see GCBO)
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)
set(handles.axes1,'Color','y')
```
This code sets the background color of the GUI axes with Tag axes1 no matter to what object the context menu is attached to.
If you enter a callback string in the Menu Editor, it overrides the callback for the item in the M-file, if any has been saved. If you delete a string you have entered in the Callback field, the M-file's callback for the item is executed when GUI runs and the item is selected.
See Menu Item for more information about specifying this field and for programming menu items. For another example of programming context menus in GUIDE, see GUI to Interactively Explore Data in a Table.
The View button displays the callback, if there is one, in an editor. If you have not yet saved the GUI, GUIDE prompts you to save it.
Open the Property Inspector, where you can change all menu properties except callbacks, by clicking the More options button. For detailed information about these properties, see Uicontextmenu Properties in the MATLAB documentation.

Associating the Context Menu with an Object

In the Layout Editor, select the object for which you are defining the context menu.
Use the Property Inspector to set this object's UIContextMenu property to the name of the desired context menu.

The following figure shows the UIContextMenu property for the axes object with Tag property axes1.

property inspector menu

In the GUI M-file, complete the callback subfunction for each item in the context menu. Each callback executes when a user selects the associated context menu item. See Menu Item for information on defining the syntax.

Setting Tab Order

Creating Toolbars