MATLAB Function Reference

Uimenu Properties

You can set and query graphics object properties in two ways:

• The Property Editor is an interactive tool that enables you to see and change object property values.
• The set and get commands enable you to set and query the values of properties

To change the default value of properties see Setting Default Property Values.

Uimenu Properties

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

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. Use set and get to access uimenu properties.

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 Microsoft Windows systems, the sequence is Ctrl-Accelerator. These keys are reserved for default menu items: c, v, and x.
• For UNIX systems, the sequence is Ctrl-Accelerator. These keys are reserved for default menu items: o, p, s, and w.

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.

Callback routine interruption. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. The first callback can be interrupted only at a drawnow, figure, getframe, pause, or waitfor command; if the callback does not contain any of these commands, it cannot be interrupted.

If the Interruptible property of the object whose callback is executing is off (the default value is on), the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction property of the object whose callback is waiting to execute determines what happens to the callback:

• If the value is queue, the callback is added to the event queue and executes after the first callback finishes execution.
• If the value is cancel, the event is discarded and the callback is not executed.

Note    If the interrupting callback is a DeleteFcn or CreateFcn callback or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement.

The button down function has no effect on uimenu objects.

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

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. Also, this property does not display the check mark on top level menus or submenus, although you can change the value of the property for these menus.

Note the following platform differences:

• On UNIX, the check mark is not displayed on submenus that have submenus.
• On Windows, the check mark is displayed on submenus, whether or not they have submenus.

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 has no effect on uimenu objects.

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.

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 is more simply queried using gcbo.

Enable or disable the uimenu. This property controls whether a menu item can be selected. When not enabled (set to off), the menu Label appears dimmed, indicating the user cannot select it.

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 the MATLAB predefined names. The default text color is black. See ColorSpec for more information on specifying color.

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. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box).

Handles are always visible when HandleVisibility is on.

Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provide a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.

Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.

When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes 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.

You can set the root ShowHiddenHandles property to on to 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.

Selectable by mouse click. This property has no effect on uimenu objects.

Callback routine interruption mode. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. MATLAB processes the callbacks according to these factors:

• The Interruptible property of the object whose callback is executing
• Whether the executing callback contains drawnow, figure, getframe, pause, or waitfor statements
• The BusyAction property of the object whose callback is waiting to execute

If the Interruptible property of the object whose callback is executing is on (the default), the callback can be interrupted. The callback interrupts execution at the next drawnow, figure, getframe, pause, or waitfor statement, and processes the events in the event queue, which includes the waiting callback.

If the Interruptible property of the object whose callback is executing is off, the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction property of the object whose callback is waiting to execute determines what happens to the callback.

Note    If the interrupting callback is a DeleteFcn or CreateFcn callback or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement. A figure's WindowButtonDownFcn callback routine, or an object's ButtonDownFcn or Callback routine are processed according to the rules described above.

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. To display the "&" character in a label, use two "&" characters in the string:

`O&pen selection' yields Open selection

`Save && Go' yields Save & Go

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.

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.

This property is not used for uimenu objects.

This property is not used for uimenu objects.

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

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.

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

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.

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.

uimenu

uint8, uint16, uint32, uint64