Documentation Center

  • Trial Software
  • Product Updates

Uitoggletool Properties

Describe toggle tool properties

Modifying Properties

You can set and query graphics object properties in two ways:

  • The Property Inspector is an interactive tool that enables you to see and change object property values. The Property inspector is available from GUIDE, or use the inspect function at the command line.

  • The set and get functions enable you to set and query the values of properties.

You can set default Uitoggletool properties by typing:

set(h,'DefaultUitoggletoolPropertyName',PropertyValue...)

Where h can be the root handle (0), a figure handle, a uitoolbar handle, or a uitoggletool handle. PropertyName is the name of the Uitoggletool property and PropertyValue is the value you specify as the default for that property.

For more information about changing the default value of a property see Setting Default Property Values.

Properties

This section lists all properties useful to uitoggletool objects along with valid values and a descriptions of their use. Curly braces { } enclose default values.

Property

Purpose

BeingDeleted

This object is being deleted.

BusyAction

Callback routine interruption.

CData

Truecolor image displayed on the toggle tool.

ClickedCallback

Control action independent of the toggle tool position.

CreateFcn

Callback routine executed during object creation.

DeleteFcn

Callback routine executed during object deletion.

Enable

Enable or disable the uitoggletool.

HandleVisibility

Control access to object's handle.

Interruptible

Callback routine interruption mode.

OffCallback

Control action when toggle tool is set to the off position.

OnCallback

Control action when toggle tool is set to the on position.

Parent

Handle of uitoggletool's parent toolbar.

Separator

Separator line mode.

State

Uitoggletool state.

Tag

User-specified object label.

TooltipString

Content of object's tooltip.

Type

Object class.

UIContextMenu

Uicontextmenu object associated with the uitoggletool

UserData

User specified data.

Visible

Uitoggletool visibility.

BeingDeleted

on | {off} (read only)

This object is being deleted. The BeingDeleted property provides a mechanism that you can use to determine if objects are in the process of being deleted. MATLAB® software sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property) It remains set to on while the delete function executes, after which the object no longer exists.

For example, some functions may not need to perform actions on objects that are being deleted, and therefore, can check the object's BeingDeleted property before acting.

BusyAction

cancel | {queue}

Callback queuing

Determines how MATLAB handles the execution of interrupting callbacks.

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. The BusyAction property of the interrupting callback determines how MATLAB handles its execution. When the BusyAction property is set to:

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

  • 'cancel' — Discards the interrupting callback as MATLAB finishes execution.

For information about how the Interruptible property of the callback controls whether other callbacks can interrupt the running callback, see the Interruptible property description.

CData

3-dimensional array

Truecolor image displayed on control as its icon. An n-by-m-by-3 array of RGB values that defines a truecolor image displayed on either a push button or toggle button. Each value must be between 0.0 and 1.0. If your CData array is larger than 16 in the first or second dimension, it can be clipped or result in other undesirable effects. If the array is clipped, only the center 16-by-16 part of the array is used.

ClickedCallback

string or function handle

Control action independent of the toggle tool position. A routine that executes after either the OnCallback routine or OffCallback routine runs to completion. The uitoggletool Enable property must be set to on.

CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB creates a uitoggletool object. MATLAB sets all property values for the uitoggletool before executing the CreateFcn callback so these values are available to the callback. Within the function, use gcbo to get the handle of the toggle tool being created.

Setting this property on an existing uitoggletool object has no effect.

You can define a default CreateFcn callback for all new uitoggletools. This default applies unless you override it by specifying a different CreateFcn callback when you call uitoggletool. For example, the statement,

set(0,'DefaultUitoggletoolCreateFcn',...
    'set(gcbo,''Enable'',''off'')'

creates a default CreateFcn callback that runs whenever you create a new toggle tool. It sets the toggle tool Enable property to off.

To override this default and create a toggle tool whose Enable property is set to on, you could call uitoggletool with code similar to

htt = uitoggletool(...,'CreateFcn',...
                   'set(gcbo,''Enable'',''on'')',...)

    Note   To override a default CreateFcn callback you must provide a new callback and not just provide different values for the specified properties. This is because the CreateFcn callback runs after the property values are set, and can override property values you have set explicitly in the uitoggletool call. In the example above, if instead of redefining the CreateFcn property for this toggle tool, you had explicitly set Enable to on, the default CreateFcn callback would have set CData back to off.

Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. The act of copying the uicontrol object fires the CreateFcn repeatedly, which raises a series of error messages after exceeding the root object's RecursionLimit property.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

DeleteFcn

string or function handle

Callback routine executed during object deletion. A callback routine that executes when you delete the uitoggletool object (e.g., when you call the delete function or cause the figure containing the uitoggletool to reset). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine.

The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

Enable

{on} | off

Enable or disable the uitoggletool. This property controls how uitoggletools respond to mouse button clicks, including which callback routines execute.

  • on – The uitoggletool is operational (the default).

  • off – The uitoggletool is not operational and its icon (set by the Cdata property) is grayed out.

When you left-click on a uitoggletool whose Enable property is on, MATLAB performs these actions in this order:

  1. Executes the toggle tool OnCallback or OffCallback routine, depending on its current state, and its ClickedCallback routine.

  2. Does not set the figure CurrentPoint property and does not execute the figure's WindowButtonDownFcn callback.

  3. Does not set the figure SelectionType property.

When you left-click a uitoggletool whose Enable property is off, or when you right-click a uitoggletool whose Enable property has any value, no action is reported, no callback executes, and neither the SelectionType nor CurrentPoint figure properties are modified.

HandleVisibility

{on} | callback | off

Control access to object's handle. This property determines when an object's handle is visible 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. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. Neither is the handle visible in the parent figure's CurrentObject property. Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

  • Handles are always visible when HandleVisibility is on.

  • Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.

  • Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.

You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings. This does not affect the values of the HandleVisibility properties.

HitTest

{on} | off

Selectable by mouse click. This property has no effect on uitoggletool objects.

    Note:   Use of the uitoggletool HitTest property is not recommended. This property might be removed in a future release.

Interruptible

off | {on}

Callback routine interruption

Controls whether MATLAB can interrupt an object's callback function when subsequent callbacks attempt to interrupt it.

For user interface objects, the Interruptible property affects the callbacks for these properties only:

  • ButtonDownFcn

  • KeyPressFcn

  • KeyReleaseFcn

  • WindowButtonDownFcn

  • WindowButtonMotionFcn

  • WindowButtonUpFcn

  • WindowKeyPressFcn

  • WindowKeyReleaseFcn

  • WindowScrollWheelFcn

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. MATLAB handles both callbacks based on the Interruptible property of the object of the running callback.

When the Interruptible property is set to:

  • 'off', MATLAB finishes execution of the running callback without any interruptions

  • 'on', these conditions apply:

    • If there is a drawnow, figure, getframe, waitfor, or pause command in the running callback, then MATLAB executes the interrupting callbacks which are already in the queue and returns to finish execution of the current callback.

    • If one of the above functions is not in the running callback, then MATLAB finishes execution of the current callback without any interruption.

The BusyAction property of the object of interrupting callback determines whether the callback should be ignored or should be put in the queue.

Setting the Interruptible property to on (default), allows a callback from other user interface objects to interrupt callback functions originating from this object.

    Note:   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 may be changed as another callback is executed.

After the function that interrupts a callback completes, the callback resumes execution where it halted when interrupted. For more information, see Control Callback Execution and Interruption.

    Note:   If the interrupting callback is a DeleteFcnor CreateFcn callback, or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement. An object's ButtonDownFcn or Callback routine is processed according to the rules described previously in this section.

OffCallback

string or function handle

Control action. A routine that executes if the uitoggletool's Enable property is set to on, and either

  • The toggle tool State is set to off.

  • The toggle tool is set to the off position by pressing a mouse button while the pointer is on the toggle tool itself or in a 5-pixel wide border around it.

The ClickedCallback routine, if there is one, runs after the OffCallback routine runs to completion.

OnCallback

string or function handle

Control action. A routine that executes if the uitoggletool's Enable property is set to on, and either

  • The toggle tool State is set to on.

  • The toggle tool is set to the on position by pressing a mouse button while the pointer is on the toggle tool itself or in a 5-pixel wide border around it.

The ClickedCallback routine, if there is one, runs after the OffCallback routine runs to completion.

Parent

handle

Uitoggletool parent. The handle of the uitoggletool's parent toolbar. You can move a uitoggletool object to another toolbar by setting this property to the handle of the new parent.

Separator

on | {off}

Separator line mode. Setting this property to on draws a dividing line to left of the uitoggletool.

State

on | {off}

Uitoggletool state. When the state is on, the toggle tool appears in the down, or pressed, position. When the state is off, it appears in the up position. Changing the state causes the appropriate OnCallback or OffCallback routine to run.

Tag

string

User-specified object identifier. The Tag property provides a means to identify graphics objects with a user-specified label. You can define Tag as any string.

With the findobj function, you can locate an object with a given Tag property value. This saves you from defining object handles as global variables. For example, this function call returns the handles of all children (of the specified toolbars) that have the Tag value 'Bold'.

h = findobj(uitoolbarhandles, 'Tag', 'Bold')
TooltipString

string

Content of tooltip for object. The TooltipString property specifies the text of the tooltip associated with the uitoggletool. When the user moves the mouse pointer over the control and leaves it there, the tooltip is displayed.

To create a tooltip that has more than one line of text, use sprintf to generate a string containing newline (\n) characters and then set the TooltipString to that value. For example:

h = uitoggletool;
s = sprintf('Toggletool tooltip line 1\nToggletool tooltip line 2');
set(h,'TooltipString',s)
Type

string (read-only)

Object class. This property identifies the kind of graphics object. For uitoggletool objects, Type is always the string 'uitoggletool'.

UIContextMenu

handle

Associate a context menu with uicontrol. This property has no effect on uitoggletool objects.

UserData

array

User specified data. You can specify UserData as any array you want to associate with the uitoggletool object. The object does not use this data, but you can access it using the set and get functions.

Visible

{on} | off

Uitoggletool visibility. By default, all uitoggletools are visible. When set to off, the uitoggletool is not visible, but still exists and you can query and set its properties.

Was this topic helpful?