Documentation

Uitoolbar Properties

Control uitoolbar appearance and behavior

A uitoolbar is a tool bar containing buttons at the top of a figure window. The uitoolbar function creates a tool bar in a figure and sets any required properties before displaying it. By changing uitoolbar 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 = uitoolbar;
isvisible = t.Visible;
t.Visible = 'off';

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

Appearance

expand all

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

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

Interactive Control

expand all

UIContextMenuContext menuempty GraphicsPlaceholder array (default) | uicontextmenu handle

This property has no effect on uitoolbars.

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

Creation and Deletion Control

expand all

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

This property is read only.

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

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

CreateFcnUitoolbar creation functionfunction handle | cell array | string

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

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

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUitoolbar deletion functionfunction handle | cell array | string

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUitoolbar identifier'' (default) | string

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

Example: 'toolbar1'

Data Types: char

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

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

This property is read only.

Type of graphics object, returned as 'uitoolbar'.

Parent/Child

expand all

ParentUitoolbar parentfigure

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

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

Children of uitoolbar, returned as an empty GraphicsPlaceholder or a 1-D array of component objects. The children of uitoolbars are uipushtools and uitoggletools.

You cannot add or remove children using the Children property of the uitoolbar. 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 components displayed in the Uitoolbar.

To add a child to this list, set the Parent property of the child component to the uitoolbar handle.

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

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

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

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