ContextMenu Properties

Control context menu appearance and behavior

A context menu is a menu that appears when you right-click a graphics object or UI component. Use the uicontextmenu function to create a context menu and set properties. By changing property values, you can modify the appearance and behavior of a context menu. Use dot notation to refer to a specific context menu object and property. You can parent a context menu to a figure created with either the uifigure or figure function.

fig = uifigure;
cm = uicontextmenu(fig);
m = uimenu(cm,'Text','Go To File');
fig.ContextMenu = cm;

Callbacks

ContextMenuOpeningFcn — Context menu opening callback function

'' (default) | function handle | cell array | character vector

Context menu opening callback function, specified as one of these values:

• A function handle.

• A 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.

• A character vector containing a valid MATLAB^® expression (not recommended). MATLAB evaluates this expression in the base workspace.

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

CreateFcn — Creation function

'' (default) | function handle | cell array | character vector

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

• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Write Callbacks in App Designer.

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

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

If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

DeleteFcn — Deletion function

'' (default) | function handle | cell array | character vector

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

• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Write Callbacks in App Designer.

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being deleted using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Callback Execution Control

Interruptible — Callback interruption

'on' (default) | on/off logical value

Callback interruption, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

This 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 (if one exists). The Interruptible property of the object owning the running callback determines if interruption is allowed.

• A value of 'on' allows other callbacks to interrupt the object's callbacks. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, uifigure, getframe, waitfor, or pause command.

  • If the running callback contains one of those commands, then MATLAB stops the execution of the callback at that 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 those commands, then MATLAB finishes executing the callback without interruption.

• A value of 'off' blocks all interruption attempts. The BusyAction property of the object owning the interrupting callback determines if the interrupting callback is discarded or put into a queue.

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.

• Timer objects execute according to schedule regardless of the Interruptible property value.

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

BusyAction — Callback queuing

'queue' (default) | 'cancel'

Callback queuing, specified as 'queue' 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.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue. These are possible values of the BusyAction property:

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

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

BeingDeleted — Deletion status

on/off logical value

This property is read-only.

Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState.

MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

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

Parent/Child

Parent — Parent object

Figure object

Parent object, specified as a Figure object created with either the uifigure or figure function. If a parent figure is not specified, then MATLAB calls the figure function to create one that serves as the parent.

You can move a ContextMenu object to a different figure by setting this property to the target Figure object.

Children — Context menu children

empty GraphicsPlaceholder array (default) | vector of Menu objects

Context menu children, returned as an empty GraphicsPlaceholder or a vector of Menu objects.

You cannot add or remove children using the Children property. Use this property to view the list of children or to reorder the child menu items. The order of the children in this array reflects the reverse-order of how the menu items appear in an opened context menu.

For example, this code creates three context menus. When you open the context menu in the running app, Menu1 appears as the first menu option.

fig = uifigure;
cm = uicontextmenu(fig);
m1 = uimenu(cm,'Text','Menu1');
m2 = uimenu(cm,'Text','Menu2');
m3 = uimenu(cm,'Text','Menu3');
fig.ContextMenu = cm;

cm.Children returns a list of the menu items in the reverse order.

cm.Children

ans = 

  3×1 Menu array:

  Menu    (Menu3)
  Menu    (Menu2)
  Menu    (Menu1)

Objects with the HandleVisibility property set to 'off' are not listed in the Children property.

To add a child to this list, set the Parent property of another Menu object to this ContextMenu object.

HandleVisibility — Visibility of object handle

'on' (default) | 'callback' | 'off'

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

This property controls the visibility of the object in its parent's list of children. When an object is not visible in its parent's list of children, it is not returned by functions that obtain objects by searching the object hierarchy or querying 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. Objects are valid even if they are not visible. If you can access an object, you can set and get its properties, and pass it to any function that operates on objects.

HandleVisibility Value	Description
'on'	The object handle is always visible.
'callback'	The object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but allows callback functions to access it.
'off'	The object handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

Identifiers

Type — Type of graphics object

'uicontextmenu'

This property is read-only.

Type of graphics object, returned as 'uicontextmenu'.

Tag — Object identifier

'' (default) | character vector | string scalar

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

UserData — User data

[] (default) | array

User data, specified as any array. Specifying UserData can be useful for sharing data within apps. See Share Data Among Callbacks for more information.

Compatibility Considerations

Callback property of ContextMenu objects is not recommended

Not recommended starting in R2020a

Starting in R2020a, using the Callback property of a ContextMenu object is not recommended. Use the ContextMenuOpeningFcn property of the ContextMenu object instead. The property values are the same.

There are no plans to remove support for the Callback property of ContextMenu objects at this time. However, this property no longer appears in the list returned by calling the get function on a ContextMenu object.

Visible and Position properties of ContextMenu objects are not recommended

Not recommended starting in R2020a

Starting in R2020a, using the Visible and Position properties to configure a context menu to open at a specific location is not recommended. In apps created with the uifigure function, use the open function instead.

There are no plans to remove support for the Visible and Position properties of ContextMenu objects at this time. However, these properties no longer appear in the list returned by calling the get function on a ContextMenu object.