Uicontextmenu Properties

Control uicontextmenu appearance and behavior

A uicontextmenu is a context menu that appears when the user right-clicks on a graphics object or UI component. The uicontextmenu function creates a context menu and sets any required properties. By changing uicontextmenu 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:

c = uicontextmenu;
pos = c.Position;
c.Position = [20 20];

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

Appearance

expand all

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

Uicontextmenu visibility, specified as 'on' or 'off'. You can use the Visible property in one of two ways:

  • Query the value to find out if the context menu is currently posted. The context menu is posted while the Visible property value is set to 'on'.

  • Set the Visible property to 'on' to make the context menu to appear. Set this property to 'off' to make the context menu to disappear.

Location and Size

expand all

PositionUicontextmenu location[left bottom]

Uicontextmenu location, specified as the vector, [left bottom]. This table describes each element in the vector.

ElementDescription
leftDistance from the inner left edge of the figure to the left edge of the uicontextmenu
bottomDistance from the inner bottom edge of the figure to the top edge of the uicontextmenu

The Position property defines the location of a context menu when its Visible property is set to 'on'.

Data Types: double

Interactive Control

expand all

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

Callback function that executes when user selects the uicontextmenu, 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.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

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

Creation and Deletion Control

expand all

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

This property is read only.

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

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

CreateFcnUicontextmenu creation functionfunction handle | cell array | string

Uicontextmenu 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 uicontextmenu. MATLAB initializes all uicontextmenu 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 uicontextmenu that is being created.

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

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUicontextmenu deletion functionfunction handle | cell array | string

Uicontextmenu 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 uicontextmenu (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uicontextmenu. 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 uicontextmenu that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUicontextmenu identifier'' (default) | string

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

Example: 'contextmenu1'

Data Types: char

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

Data to associate with the uicontextmenu 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'uicontextmenu'

This property is read only.

Type of graphics object, returned as 'uicontextmenu'.

Parent/Child

expand all

ParentUicontextmenu parentfigure

Uicontextmenu parent, specified as a figure. You can move a uicontextmenu to a different figure by setting this property to the handle of the target figure.

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

This property is read only.

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

You cannot add or remove children using the Children property of the uicontextmenu. 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 uicontextmenu handle.

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

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

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

This property controls the visibility of the uicontextmenu 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 uicontextmenu handle is always visible.
'callback'The uicontextmenu 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 uicontextmenu 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.

Was this topic helpful?