Uipushtool Properties

Control uipushtool appearance and behavior

Uipushtools are push buttons that appear on the tool bar at the top of the a figure. The uipushtool function creates a push button on a tool bar and sets any required properties before displaying it. By changing uipushtool 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:

p = uipushtool;
sep = p.Separator;
p.Separator = 'on';

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

Appearance

expand all

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

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

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

Separator line mode, specified as 'off' or 'on'. Setting this property to 'on' draws a dividing line to left of the uipushtool.

CDataOptional image to display on uipushtool3-D array of truecolor RGB values

Optional image to display on the uipushtool, specified as a 3-D array of truecolor RGB values. The values in the array can be:

  • Double-precision values between 0.0 and 1.0

  • uint8 values between 0 and 255

The length of the array's first and second dimensions must be less than or equal to 16. Otherwise, it might be clipped or distorted when it displays.

Data Types: double | uint8

Interactive Control

expand all

ClickedCallbackCallback function that executes when user clicks uipushtool'' (default) | function handle | cell array | string

Callback function that executes when a user clicks the uipushtool, 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 callback functions as function handles, cell arrays, or strings, see How to Specify Callback Property Values.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

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

Operational state of uipushtool, specified as 'on' or 'off'. The Enable property controls whether the uipushtool responds to button clicks. The are two possible values:

  • 'on' – The uipushtool is operational.

  • 'off' – The uipushtool is not operational and appears grayed out.

The value of the Enable property and the type of button click determine how the GUI responds.

Enable ValueResponse to Left-ClickResponse to Right-Click
'on'

The uipushtool's ClickedCallback function executes.

The uipushtool is not operational. No callback executes.

'off'

The uipushtool is not operational. No callback executes.

The uipushtool is not operational. No callback executes.

TooltipStringTooltip textstring

Tooltip text, specified as a string. When the user hovers the mouse pointer over the uipushtool and leaves it there, the tooltip appears.

Example: 'Some string'

UIContextMenuContext menuempty GraphicsPlaceholder array (default) | uicontextmenu handle

This property has no effect on uipushtools.

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

Creation and Deletion Control

expand all

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

This property is read only.

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

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

CreateFcnUipushtool creation functionfunction handle | cell array | string

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

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

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUipushtool deletion functionfunction handle | cell array | string

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUipushtool identifier'' (default) | string

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

Example: 'pushtool1'

Data Types: char

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

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

This property is read only.

Type of graphics object, returned as 'uipushtool'.

Parent/Child

expand all

ParentUipushtool parentuitoolbar

Uipushtool parent, specified as a uitoolbar. You can move a uipushtool to a different uitoolbar by setting this property to the handle of the target uitoolbar.

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

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

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