Documentation

Uimenu Properties

Control uimenu appearance and behavior

A uimenu is a menu in a figure's menu bar. The uimenu function adds a menu to a figure or adds a submenu to an existing menu and sets any required properties. By changing uimenu property values, you can modify certain aspects of its appearance and behavior.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

m = uimenu;
color = m.ForegroundColor;
m.ForegroundColor = [0 0 1];

If you are using an earlier release, use the get and set functions to query and set properties.

Appearance

expand all

VisibleUimenu visibility'on' (default) | 'off'

Uimenu visibility, specified as 'on' or 'off'. When the Visible property is set to 'off', the uimenu is not visible, but you can query and set its properties.

LabelMenu labelstring

Menu label, specified as a string. This property specifies the text that appears on the menu (or submenu).

Example: 'Update'

Data Types: char

CheckedMenu check indicator'off' (default) | 'on'

Menu check indicator, specified as 'off' or 'on'. 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 show the state of menu items that enable or disable functionality in your application.

SeparatorSeparator line mode'off' (default) | 'on'

Separator line mode, specified as 'off' or 'on'. Setting this property to 'on' draws a dividing line above the uimenu.

ForegroundColorUimenu text color[0 0 0] (default) | RGB triplet | short name | long name

Uimenu text color, specified as an RGB triplet, short name, or long name from the table below.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

Data Types: double | char

Location and Size

expand all

PositionRelative menu positionscalar integer value

Relative menu position, specified as a scalar integer value. The value of Position property indicates placement on the menu bar or within a menu. Top-level menus appear 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 appear from top to bottom according to the value of their Position property, with 1 representing the top-most position.

Data Types: double

Interactive Control

expand all

CallbackCallback function that executes when user selects the uimenu'' (default) | function handle | cell array | string

Callback function that executes when user selects the uimenu, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB® expression. MATLAB evaluates this expression in the base workspace.

    Note:   Do not use a uimenu callback to dynamically change menu items. Deleting, adding, and replacing menu items in a callback can result in a blank menu on some platforms. You can hide, show, and disable menu items in a callback to achieve the same effect. To fully repopulate menu items, delete and create them outside the callback.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell

EnableOperational state of uimenu'on' (default) | 'off'

Operational state of uimenu, specified as 'on' or 'off'. This property controls whether the user can select a menu item. When the value is 'off', the menu label appears dimmed, indicating that the user cannot select it.

AcceleratorKeyboard equivalentcharacter

Keyboard equivalent, specified as a character. This property defines a keyboard equivalent character for selecting the menu item. Specifying an Accelerator value allows users to select the menu item by pressing a character and another key, instead of selecting the menu item with the mouse. The key sequence is platform specific:

  • For Windows®, the sequence is Ctrl+Accelerator. Windows reserves these keys for default menu items: a, c, v, and x

  • For Macintosh systems, the sequence is Command+Accelerator. Apple reserves these keys for default menu items: a, c, v, and x.

  • For Linux® systems, the sequence is Ctrl+Accelerator. Linux systems reserve these keys for default menu items: o, p, s, and w. Like the other platforms, many Linux applications also use a, c, v, and x.

Accelerated menu items do not have to be displayed for the accelerator key to work. However, some restrictions apply:

  • You can define the Accelerator property for only menu items that do not have submenus menus.

  • Accelerators work only for menu items that execute a callback function.

  • The figure must be in focus when entering the accelerator key sequence.

To remove an Accelerator value, set the Accelerator property to an empty string, ''.

Example: 'f'

Callback Execution Control

expand all

BusyActionCallback queuing'queue' (default) | 'cancel'

Callback queuing specified as 'queue' (default) or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property of the source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these values:

  • 'queue' — Put the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Do not execute the interrupting callback.

Whenever MATLAB invokes a callback, that callback always attempts to interrupt an executing callback. The Interruptible property of the object whose callback is running determines if interruption is allowed. If Interruptible is set to:

  • on — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • off — The BusyAction property (of the object owning the executing callback) determines if MATLAB enqueues or ignores the interrupting callback.

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a uimenu callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

    Note:   Callback interruption and execution behave differently in these situations:

    • If the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

    • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

    • MATLAB does not save the state of properties or the display when an interruption occurs. For example, the handle returned by the gca or gcf command might change when another callback executes.

HitTestAbility to become current object'on' (default) | 'off'

This property has no effect on the uimenu.

Creation and Deletion Control

expand all

BeingDeletedDeletion status of uimenu'off' (default) | 'on'

This property is read only.

Deletion status of uimenu, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the uimenu begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the uimenu no longer exists.

Check the value of the BeingDeleted property to verify that the uimenu is not about to be deleted before querying or modifying it.

CreateFcnUimenu creation functionfunction handle | cell array | string

Uimenu creation function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This property specifies a callback function to execute when MATLAB creates the uimenu. MATLAB initializes all uimenu property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Use the gcbo function in your CreateFcn code to get the handle to the uimenu that is being created.

Setting the CreateFcn property on an existing uimenu has no effect.

    Note:   Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. Copying the uimenu object causes the CreateFcn callback to execute repeatedly.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUimenu deletion functionfunction handle | cell array | string

Uimenu deletion function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the uimenu (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uimenu. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your DeleteFcn code to get the handle to the uimenu that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUimenu identifier'' (default) | string

Uimenu identifier, specified as a string. You can specify a unique Tag value to serve as an identifier for the uimenu. When you need access to the uimenu elsewhere in your code, you can use the findobj function to search for the uimenu based on the Tag value.

Example: 'menu1'

Data Types: char

UserDataData to associate with the uimenu objectempty array (default) | array

Data to associate with the uimenu object, specified as any array. Specifying UserData can be useful for sharing data values within and across GUIs you create. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

TypeType of graphics object'uimenu'

This property is read only.

Type of graphics object, returned as 'uimenu'.

Parent/Child

expand all

ParentUimenu parentfigure | uicontextmenu | uimenu

This property is read only.

Uimenu parent, specified as a figure, uicontextmenu, or another uimenu object. You can move a uimenu to a different figure, or move it under a different uimenu by setting this property to the target figure, uicontextmenu, or uimenu object.

ChildrenChildren of uimenuempty GraphicsPlaceholder array (default) | 1-D array of component objects

This property is read only.

Children of uimenu, returned as an empty GraphicsPlaceholder or a 1-D array of UI component objects. The children of uimenus are other uimenus that function as submenus.

You cannot add or remove children using the Children property of the uimenu. Use this property to view the list of children or to reorder the children. The order of the children in this array reflects the order of the displayed menu items.

To add a child to this list, set the Parent property of the child component to the uimenu handle.

Objects with the HandleVisibility property set to 'off' do not list in the uimenu's Children property.

HandleVisibilityVisibility of Uimenu handle'on' (default) | 'callback' | 'off'

Visibility of Uimenu handle, specified as 'on', 'callback', or 'off'.

This property controls the visibility of the uimenu handle in its parent's list of children. When a handle is not visible in its parent's list of children, it is not returned by functions that obtain handles by searching the object hierarchy or querying handle properties. These functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close. The HandleVisibility property also controls the visibility of the object's handle in the parent figure's CurrentObject property. Handles are still valid even if they are not visible. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

HandleVisibility ValueDescription
'on'The uimenu handle is always visible.
'callback'The uimenu handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This protects the GUI from command-line users, while allowing callback routines to have complete access.
'off'The uimenu handle is invisible at all times. This option might be useful when a callback routine invokes a function that might potentially damage the GUI (such as a function that evaluates user-typed strings). You can set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

Set the graphics root ShowHiddenHandles property to 'on' to make all handles visible, regardless of their HandleVisibility value. This setting has no effect on their HandleVisibility values.

See Also

More About

Was this topic helpful?