MATLAB Functions

Create menus on a Figure window

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

Description

uimenu creates a hierarchy of menus and submenus that display in the Figure window's menu bar.

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

creates a menu in the current Figure's menu bar using the values of the specified properties.

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

creates a submenu of the parent menu specified by parent. If parent refers to a Figure instead of another Uimenu object, MATLAB creates a new menu on the referenced Figure's menubar.

Remarks

MATLAB adds the new menu to the existing menu bar. Each menu choice can itself be a menu that displays its submenu when selected.

uimenu accepts property name/property value pairs, structures, and cell arrays as input arguments. The Uimenu Callback property defines the action taken when you activate the menu. The "Uimenu Properties" section describes these properties. uimenu optionally returns the handle to the created Uimenu object.

Uimenus only appear in Figures whose WindowStyle is normal. If a Figure containing Uimenu children is changed to WindowStyle modal, the Uimenu children will still exist, and be contained in the Children list of the Figure, but will not be displayed until the WindowStyle reverts to normal.

The value of the Figure MenuBar property affects the location of Uimenu children of the Figure on the menubar. When MenuBar is none, Uimenus are the only items on the Figure menubar. When MenuBar is figure, a set of built-in menus precedes the Uimenus on the menubar (but MATLAB controls those built-in menus, and their handles can not be obtained by the user).

You can set and query property values after creating the menu using set and get.

Examples

This example creates a menu labeled Workspace whose choices allow users to create a new Figure window, save workspace variables, and exit out of MATLAB. In addition, it defines an accelerator key for the quit option.

f = uimenu('Label','Workspace');
    uimenu(f,'Label','New Figure','Callback','figure');
    uimenu(f,'Label','Save','Callback','save');
    uimenu(f,'Label','Quit','Callback','exit',...
           'Separator','on', 'Accelerator', 'Q');

Object Hierarchy

Setting Default Properties

You can set default Uimenu properties on the Figure and Root levels:

set(0,'DefaultUimenuPropertyName',PropertyValue...)
set(gcf,'DefaultUimenuPropertyName',PropertyValue...)
set(menu_handle,'DefaultUimenuProperty',PropertyValue...)

Where PropertyName is the name of the Uimenu property and PropertyValue is the value you are specifying.

Object Properties

This section lists property names along with the type of values each accepts. Curly braces { } enclose default values.

Accelerator character

Keyboard equivalent. A character specifying the keyboard equivalent for the menu item. This allows users to select a particular menu choice by pressing the specified character in conjunction with another key, instead of selecting the menu item with the mouse. The key sequence is platform specific:

For X-Windows and MS-Windows systems, the sequence is Control-Accelerator.
For Macintosh systems, the sequence is Command-Accelerator.

You can define an accelerator only for menu items that do not have children menus. Accelerators work only for menu items that directly execute a callback routine, not items that bring up other menus.

Note that the menu item does not have to be displayed (e.g., a submenu) for the accelerator key to work. However, the window focus must be in the Figure when the key sequence is entered.

BackgroundColor (obsolete)

The background color of menu items is determined by the system.

BusyAction cancel | {queue}

Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routes always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are:

cancel - discard the event that attempted to execute a second callback routine.
queue - queue the event that attempted to execute a second callback routine until the current callback finishes.

ButtonDownFcn string

The button down function is not used for Uimenus.

Callback string

Menu action. A callback routine that executes whenever you select the menu. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.

A menu with children (submenus) executes its callback routine before displaying the submenus. A menu without children executes its callback routine when you release the mouse button (i.e., on the button up event).

Checked on | {off}

Menu check indicator. Setting this property to on places a check mark next to the corresponding menu item. Setting it to off removes the check mark. You can use this feature to create menus that indicate the state of a particular option. Note that there is no formal mechanism for indicating that an unchecked menu item will become checked when selected.

Children vector of handles

Handles of submenus. A vector containing the handles of all children of the Uimenu object. The children objects of Uimenus are other Uimenus, which function as submenus. You can use this property to re-order the menus.

Clipping {on} | off

Clipping has no effect on Uimenus.

CreateFcn string

Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a Uimenu object. You must define this property as a default value for Uimenus. For example, the statement,

set(0,'DefaultUimenuCreateFcn','set(gcf,''IntegerHandle'',''off''')

defines a default value on the Root level that sets the Figure IntegerHandle property to off whenever you create a Uimenu object. Setting this property on an existing Uimenu object has no effect. MATLAB executes this routine after setting all property values for the Uimenu.

The handle of the object whose CreateFcn is being executed is accessible only through the Root CallbackObject property, which can be queried using gcbo.

DeleteFcn string

Delete Uimenu callback routine. A callback routine that executes when you delete the Uimenu object (e.g., when you issue a delete command or cause the Figure containing the Uimenu to reset). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine.

The handle of the object whose DeleteFcn is being executed is accessible only through the Root CallbackObject property, which can be queried using gcbo.

Enable {on} | off

Enable or disable the Uimenu. This property controls the selectability of a menu item. When not enabled (set to off), the menu Label appears dimmed, indicating you cannot select it.

ForegroundColor ColorSpec X-Windows only

Color of menu label string. This property determines color of the text defined for the Label property. Specify a color using a three-element RGB vector or one of MATLAB's predefined names. The default text color is black. See the ColorSpec reference page for more information on specifying color.

HandleVisibility {on} | callback | off

Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. Handles are always visible when HandleVisibility is on. When HandleVisibility is callback, handles are visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line - a useful way to protect GUIs from command-line users, while permitting their callbacks complete access to their own handles. Setting HandleVisibility to off makes handles invisible at all times - which is occasionally necessary when a callback needs to invoke a function that might potentially damage the UI, and so wants to temporarily hide its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it can not be returned by any functions which obtain handles by searching the object hierarchy or querying handle properties, including get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, Figures do not appear in the Root's CurrentFigure property, objects do not appear in the Root's CallbackObject property or in the Figure's CurrentObject property, and Axes do not appear in their parent's CurrentAxes property.

The Root ShowHiddenHandles property can be set to on to temporarily make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties).

Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles. This property is useful for preventing command-line users from accidently drawing into or deleting a Figure that contains only user interface devices (such as a dialog box).

Interruptible {on} | off

Callback routine interruption mode. The Interruptible property controls whether a Uimenu callback routine can be interrupted by subsequently invoked callback routines. By default (off), a callback routine executes to completion before another can begin. Only the Callback Uimenu property is affected by the Interruptible property.

Label string

Menu label. A string specifying the text label on the menu item. You can specify a mnemonic using the "&" character. Whatever character follows the "&" in the string appears underlined and selects the menu item when you type that character while the menu is visible. The "&" character is not displayed. On Macintosh systems, MATLAB ignores (and does not print) the "&" character. To display the "&" character in a label, use two "&" characters in the string:

`O&pen selection' yeilds Open selection

`Save && Go' yeilds Save & Go

Parent handle

Uimenu's parent. The handle of the Uimenu's parent object. The parent of a Uimenu object is the Figure on whose menu bar it displays, or the Uimenu of which it is a submenu. You can move a Uimenu object to another Figure by setting this property to the handle of the new parent.

Position scalar

Relative menu position. The value of Position indicates placement on the menu bar or within a menu. Top-level menus are placed from left to right on the menu bar according to the value of their Position property, with 1 representing the left-most position. The individual items within a given menu are placed from top to bottom according to the value of their Position property, with 1 representing the top-most position.

Selected on | {off}

This property is not useful for Uimenus.

SelectionHighlight on | off

This property is not useful for Uimenus.

Separator on | {off}

Separator line mode. Setting this property to on draws a dividing line above the menu item.

Tag string

User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.

Type string (read only)

Class of graphics object. For Uimenu objects, Type is always the string 'uimenu'.

UserData matrix

User-specified data. Any matrix you want to associate with the Uimenu object. MATLAB does not use this data, but you can access it using the set and get commands.

Visible {on} | off

Uimenu visibility. By default, all Uimenus are visible. When set to off, the Uimenu is not visible, but still exists and you can query and set its properties.