ToggleTool Properties

Control appearance and behavior of toggle tool

The properties listed here are valid for ToggleTool objects in GUIDE or in apps created with the figure function.

Toggle tools 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 property values, you can modify certain aspects of its appearance and behavior. Use dot notation to refer to a specific object and property.

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

Button Appearance

State — Toggle 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.

CData — Optional icon

3-D array of truecolor RGB values

Optional icon, 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

Separator — Separator 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 a tool in the tool bar.

Interactivity

Visible — Component visibility

'on' (default) | 'off'

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

Enable — Operational state of tool

'on' (default) | 'off'

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

• 'on' – The tool is operational.

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

The value of the Enable property and the type of button click determine the response.

Enable Value	Response to Left-Click	Response to Right-Click
'on'	The OnCallback or OffCallback function execute, depending on the current state of the tool. The ClickedCallback function executes.	The tool is not operational. No callback executes.
'off'	The tool is not operational. No callback executes.	The tool is not operational. No callback executes.

Tooltip — Tooltip

character vector | string scalar | categorical array

Tooltip, specified as a character vector, string scalar, or categorical array. Use this property to display a message when the user hovers the pointer over the component at run time. The tooltip does not display when the component is disabled. If you specify this property as a categorical array, MATLAB^® uses the values in the array, not the full set of categories.

To create multiple lines of text, use the sprintf function to insert newline characters ('\n') in your text. For example:

txt = sprintf('Line 1\nLine 2');

Then set the Tooltip property to the value returned by sprintf.

UIContextMenu — Context menu (not recommended)

empty GraphicsPlaceholder array (default) | uicontextmenu handle

This property has no effect on ToggleTool objects.

TooltipString — Tooltip (not recommended)

character vector | string scalar | categorical array

Tooltip, specified as a character vector, string scalar, or categorical array. The tooltip displays when the user hovers the mouse pointer over the component in the app. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

Note

The TooltipString property is not recommended starting in R2018b. Use the Tooltip property instead.

Callbacks

ClickedCallback — Tool clicked callback

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

Tool clicked callback, 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.

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 character vectors, see How to Specify Callback Property Values.

Data Types: function_handle | cell | char

OnCallback — Callback to execute when user turns on toggle button

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

Callback to execute when user turns on the toggle button, 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 callback functions as function handles, cell arrays, or character vectors, see How to Specify Callback Property Values.

Data Types: function_handle | cell | char

OffCallback — Callback to execute when user turns off the toggle button

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

Callback to execute when user turns off toggle button, 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 callback functions as function handles, cell arrays, or character vectors, see How to Specify Callback Property Values.

Data Types: function_handle | cell | char

CreateFcn — Component creation function

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

Component creation 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.

This property specifies a callback function to execute when MATLAB creates the component. MATLAB initializes all component 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 component object that is being created.

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

DeleteFcn — Component deletion function

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

Component deletion 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.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the component (for example, when the user closes the window). MATLAB executes the DeleteFcn callback before destroying the properties of the component object. 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 component object that is being deleted.

Callback Execution Control

Interruptible — Callback 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 (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, 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.

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

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

See Interrupt Callback Execution for an example that shows how the Interruptible and BusyAction properties affect the behavior of a program.

BusyAction — Callback 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 interrupting callback) determines if MATLAB enqueues or ignores the interrupting callback.

See Interrupt Callback Execution for an example that shows how the BusyAction and Interruptible properties affect the behavior of a program.

BeingDeleted — Deletion status

'off' | 'on'

This property is read-only.

Deletion status, returned as 'off' or 'on'. 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.

HitTest — Ability to become current object (not recommended)

'on' (default) | 'off'

This property has no effect on ToggleTool objects.

Parent/Child

Parent — Parent object

Toolbar object

Parent object, specified as a Toolbar object. Use this property to specify the parent tool bar when creating a tool or to move an existing tool to a different tool bar.

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

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.

Identifiers

Type — Type of graphics object

'uitoggletool'

This property is read-only.

Type of graphics object, returned as 'uitoggletool'.

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.