Uicontextmenu Properties - Describe context menu properties

Modifying Properties

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

• The Property Inspector is an interactive tool that enables you to see and change object property values. The Property inspector is available from GUIDE, or use the inspect function at the command line.

• The set and get functions enable you to set and query the values of properties.

For more information about changing the default value of a property see Setting Default Property Values. For an example, see the CreateFcn property.

Uicontextmenu Properties

This section lists all properties useful to uicontextmenu objects along with valid values and descriptions of their use. Curly braces {} enclose default values.

BeingDeleted

on | {off} (read-only)

This object is being deleted. Mechanism to determine if objects are in the process of being deleted. MATLAB sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property). It remains set to on while the delete function executes, after which the object no longer exists.

For example, an object's delete function calls other functions that act on a number of different objects. If a function does not need to perform an action on an about-be-deleted object, it can check the object's BeingDeleted property before acting.

BusyAction

cancel | {queue}

Callback queuing

Determines how MATLAB handles the execution of interrupting callbacks.

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. The BusyAction property of the interrupting callback determines how MATLAB handles its execution. When the BusyAction property is set to:

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

• 'cancel' — Discards the interrupting callback as MATLAB finishes execution.

For information about how the Interruptible property of the callback controls whether other callbacks can interrupt the running callback, see the Interruptible property description.

Callback

string

Control action. A routine that executes whenever you right-click an object for which a context menu is defined. The routine executes immediately before the context menu is posted. Define this routine as a string that is a valid MATLAB expression or the name of a code file. The expression executes in the MATLAB workspace.

Children

matrix

The uimenu items defined for the uicontextmenu.

CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB creates a uicontextmenu object. MATLAB sets all property values for the uicontextmenu before executing the CreateFcn callback so these values are available to the callback. Within the function, use gcbo to get the handle of the uicontextmenu being created.

Setting this property on an existing uicontextmenu object has no effect.

You can define a default CreateFcn callback for all new uicontextmenus. This default applies unless you override it by specifying a different CreateFcn callback when you call uicontextmenu. For example, the code

set(0,'DefaultUicontextmenuCreateFcn','set(gcbo,...
    ''Visible'',''on'')')

creates a default CreateFcn callback that runs whenever you create a new context menu. It sets the default Visible property of a context menu.

To override this default and create a context menu whose Visible property is set to a different value, call uicontextmenu with code similar to

hpt = uicontextmenu(...,'CreateFcn','set(gcbo,...
''Visible'',''off'')')

Note   To override a default CreateFcn callback you must provide a new callback and not just provide different values for the specified properties. This is because the CreateFcn callback runs after the property values are set, and can override property values you have set explicitly in the uicontextmenu call. In the example above, if instead of redefining the CreateFcn property for this uicontextmenu, you had explicitly set Visible to off, the default CreateFcn callback would have set Visible back to the default, i.e., on.

Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. The act of copying the uicontrol object fires the CreateFcn repeatedly, which raises a series of error messages after exceeding the root object's RecursionLimit property.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

DeleteFcn

string or function handle

Delete uicontextmenu callback routine. A callback routine that executes when you delete the uicontextmenu object (for example, when you issue a delete command or clear the figure containing the uicontextmenu). 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 you can query using gcbo.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

HandleVisibility

{on} | callback | off

Control access to object's handle. This property determines when an object's handle is visible 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. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. Neither is the handle visible in the parent figure's CurrentObject property. 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.

• 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 provides 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 might 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.

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.

Interruptible

off | {on}

Callback routine interruption

Controls whether MATLAB can interrupt an object's callback function when subsequent callbacks attempt to interrupt it.

For user interface objects, the Interruptible property affects the callbacks for these properties only:

• ButtonDownFcn

• KeyPressFcn

• KeyReleaseFcn

• WindowButtonDownFcn

• WindowButtonMotionFcn

• WindowButtonUpFcn

• WindowKeyPressFcn

• WindowKeyReleaseFcn

• WindowScrollWheelFcn

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. MATLAB handles both callbacks based on the Interruptible property of the object of the running callback.

When the Interruptible property is set to:

• 'off', MATLAB finishes execution of the running callback without any interruptions

• 'on', these conditions apply:

  • If there is a drawnow, figure, getframe, waitfor, or pause command in the running callback, then MATLAB executes the interrupting callbacks which are already in the queue and returns to finish execution of the current callback.

  • If one of the above functions is not in the running callback, then MATLAB finishes execution of the current callback without any interruption.

The BusyAction property of the object of interrupting callback determines whether the callback should be ignored or should be put in the queue.

Setting the Interruptible property to on (default), allows a callback from other user interface objects to interrupt callback functions originating from this object.

Note   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 may be changed as another callback is executed.

After the function that interrupts a callback completes, the callback resumes execution where it halted when interrupted. For more information, see Control Callback Execution and Interruption.

Note   If the interrupting callback is a DeleteFcnor 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. An object's ButtonDownFcn or Callback routine is processed according to the rules described previously in this section.

Parent

handle

Uicontextmenu's parent. The handle of the uicontextmenu's parent object, which must be a figure.

Position

vector

Uicontextmenu's position. A two-element vector that defines the location of a context menu posted by setting the Visible property value to on. Specify Position as

[x y]

where vector elements represent the horizontal and vertical distances in pixels from the bottom left corner of the figure window, panel, or button group to the top left corner of the context menu.

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

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

UserData

matrix

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

Visible

on | {off}

Uicontextmenu visibility. The Visible property can be used in two ways:

• Its value indicates whether the context menu is currently posted. While the context menu is posted, the property value is on; when the context menu is not posted, its value is off.

• Its value can be set to on to force the posting of the context menu. Similarly, setting the value to off forces the context menu to be removed. When used in this way, the Position property determines the location of the posted context menu.

See Also

uicontextmenu