Uitoggletool Properties

Control uitoggletool appearance and behavior

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

t = uitoggletool;
sep = t.Separator;
t.Separator = 'on';

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

Appearance

expand all

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

Uitoggletool visibility, specified as 'on' or 'off'. When the Visible property is set to 'off', the uitoggletool 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 uitoggletool.

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

Optional image to display on the uitoggletool, 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

StateToggle button state'off' (default) | 'on'

Toggle button state, specified as 'off' or 'on'. When this property value is 'on', the toggle button appears in the down (depressed) position. When this property value is 'off', the toggle button appears in the up position. Changing the state causes the appropriate OnCallback or OffCallback function to execute.

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

Callback function that executes when a user clicks the uitoggletool, 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.

This callback function executes after the OnCallback function or OffCallback function executes (depending on the state of the button).

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

OnCallbackCallback to execute when user turns on toggle button'' (default) | function handle | cell array | string

Callback to execute when user turns on the toggle button, 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

OffCallbackCallback to execute when user turns off the toggle button'' (default) | function handle | cell array | string

Callback to execute when user turns off toggle button, 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 uitoggletool'on' (default) | 'off'

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

  • 'on' – The uitoggletool is operational.

  • 'off' – The uitoggletool 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'
  1. The OnCallback or OffCallback function execute, depending on the current state of the uitoggletool.

  2. The uitoggletool's ClickedCallback function executes.

The uitoggletool is not operational. No callback executes.

'off'

The uitoggletool is not operational. No callback executes.

The uitoggletool is not operational. No callback executes.

TooltipStringTooltip textstring

Content of uitoggletool tooltip, specified as a string. When the user moves the mouse pointer over the uitoggletool and leaves it there, the tooltip displays.

Example: 'Some string'

UIContextMenuContext menuempty GraphicsPlaceholder array (default) | uicontextmenu handle

This property has no effect on uitoggletools.

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

Creation and Deletion Control

expand all

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

This property is read only.

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

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

CreateFcnUitoggletool creation functionfunction handle | cell array | string

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

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

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUitoggletool deletion functionfunction handle | cell array | string

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUitoggletool identifier'' (default) | string

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

Example: 'toggletool1'

Data Types: char

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

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

This property is read only.

Type of graphics object, returned as 'uitoggletool'.

Parent/Child

expand all

ParentUitoggletool parentuitoolbar

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

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

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

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