PushTool
Push tool UI component
Description
A push tool UI component is a button in a toolbar that responds when an app user
presses it. Use the PushTool
object to modify the appearance and behavior of
a push tool after you create it.
Creation
Create a push tool in a figure using the uipushtool
function.
Properties
Push Tool
Icon
— Icon source or file
''
(default) | character vector | string scalar | m
-by-n
-by-3 truecolor image array
Icon source or file, specified as a character vector, string scalar, or an
m
-by-n
-by-3 truecolor image array. If you
specify a character vector or string scalar, it can be an image file name on the
MATLAB® path or a full path to an image file. If you plan to share your app with
others, put the image file on the MATLAB path to facilitate app packaging. Supported image formats include JPEG,
PNG, GIF, and SVG.
If you specify an m
-by-n
-by-3 array, it is
interpreted as a truecolor image array. For more information about truecolor image
arrays, see Working with Image Types in MATLAB.
If the image you specify is larger than 16-by-16 pixels, then the Icon
property scales the image down so that the entire image fits within the tool. If the image you specify is smaller than 16-by-16 pixels, it is not scaled up to fit the available space.
The Icon
property is supported only in App Designer and
uifigure
-based apps. If the Icon
and
CData
properties are both set, then the
CData
property is ignored.
Example: 'icon.png'
specifies an image file on the MATLAB path.
Example: 'C:\Documents\icon.png'
specifies a full path to an image file.
CData
— Image array
[]
(default) | m
-by-n
-by-3 truecolor image array
Image array, specified as an m
-by-n
-by-3
truecolor image array. The values in the array can be:
Double-precision values between
0.0
and1.0
uint8
values between0
and255
To prevent the image from appearing clipped or distorted, specify an array with
m
and n
less than or equal to 16. If the image
is clipped, then only the center 16-by-16 part of the array is used.
Note
For App Designer and uifigure
-based apps, use the
Icon
property to specify push and toggle tool icons
instead.
Separator
— Separator line mode
'off'
(default) | on/off logical value
Separator line mode, specified as 'off'
or 'on'
, or as
numeric or logical 0
(false
) or 1
(true
). A value of
'on'
is equivalent to
true
, and
'off'
is equivalent to
false
. Thus, you can use the
value of this property as a logical value. The value is stored
as an on/off logical value of type matlab.lang.OnOffSwitchState
.
Setting this property to 'on'
draws a dividing line
to the left of a tool in the toolbar.
Interactivity
Visible
— State of visibility
'on'
(default) | on/off logical value
State of visibility, specified as 'on'
or 'off'
,
or as numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
'on'
— Display the object.'off'
— Hide the object without deleting it. You still can access the properties of an invisible UI component.
To make your app start faster, set the Visible
property to
'off'
for all UI components that do not need to appear at
startup.
Enable
— Operational state
'on'
(default) | on/off logical value
Operational state, specified as 'on'
or 'off'
,
or as numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
If you set this property to
'on'
, the app user can interact with the component.If you set this property to
'off'
, the component appears dimmed, indicating that the app user cannot interact with it, and that it will not trigger a callback.
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 you hover over the component in the running app. The tooltip does not appear 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.
In figures created with the uifigure
function, push tools and toggle
tools support multiline tooltips. To create a multiline tooltip, 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
.
In figures created with the figure
function, push tools and
toggle tools do not support multiline tooltips.
ContextMenu
— Context menu
empty GraphicsPlaceholder
array (default) | ContextMenu
object
Setting this property has no effect on objects of this type.
TooltipString
— Tooltip (not recommended)
character vector | string scalar | categorical array
Tooltip, specified as a character vector, string scalar, or categorical array. The tooltip appears when you hover 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.
For more information about specifying callback functions as function handles, cell arrays, or character vectors, see Specify a Callback Function.
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 Specify a Callback Function.
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 Specify a Callback Function.
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) | on/off logical values
Callback interruption, specified as 'on'
or 'off'
, or as
numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
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 adrawnow
,figure
,getframe
,waitfor
, orpause
.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. TheBusyAction
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
, orSizeChangedFcn
callback, then the interruption occurs regardless of theInterruptible
property value.If the running callback is currently executing the
waitfor
function, then the interruption occurs regardless of theInterruptible
property value.Timer
objects execute according to schedule regardless of theInterruptible
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
orgcf
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
— TheBusyAction
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
on/off logical value
This property is read-only.
Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState
.
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) | on/off logical value
This property has no effect on objects of this type.
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 in its parent's list of children. When an
object is not visible in its parent's list of children, it is not returned by functions
that obtain objects by searching the object hierarchy or querying 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.
Objects are 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. |
Identifiers
Type
— Type of graphics object
'uipushtool'
This property is read-only.
Type of graphics object, returned as 'uipushtool'
.
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.
Examples
Create Push Tool in UI Figure Toolbar
Create a UI figure by calling the uifigure
function. Create a
toolbar in the UI figure.
fig = uifigure; tb = uitoolbar(fig);
Add a push tool to the toolbar. The push tool displays the default icon.
pt = uipushtool(tb);
Add an icon to the push tool by setting the Icon
property value
to the image file greencircleicon.gif
.
pt.Icon = fullfile(matlabroot,'toolbox','matlab','icons','greencircleicon.gif');
Create Color Picker Push Tool in UI Figure Toolbar
Create a push tool that opens the uisetcolor
dialog box when you click it. Change the background color of the UI figure to the color
selected from the color picker.
First, create a program file called colorPickerPushTool.m
. Within
the program file:
Create a UI figure.
Create a toolbar in the UI figure.
Create a push tool in the toolbar.
Add an appropriate icon to the push tool by setting the
Icon
property value to the full file path topaintbrush.gif
.Create a tooltip for the push tool.
Set the
ClickedCallback
property to a function handle that references a callback function calledcolorToolClicked
.Create a callback function called
colorToolClicked
. In it, call theuisetcolor
function so that a color picker dialog opens when you click the push tool in the toolbar. Set the default color of the color picker to be the color of the UI figure and specify the title of the color picker as'Select UI Figure Color'
. Make the UI figure the current figure so that it displays on top of all other figures.
function colorPickerPushTool fig = uifigure('Position',[350 500 400 300]); tb = uitoolbar(fig); pt = uipushtool(tb); pt.Icon = fullfile(matlabroot,'toolbox','matlab','icons','paintbrush.gif'); pt.Tooltip = 'Change UI Figure Color'; pt.ClickedCallback = @colorToolClicked; function colorToolClicked(src,event) c = uisetcolor(fig,'Select UI Figure Color'); figure(fig) end end
Run colorPickerPushTool
. Click the push tool to open the color
picker. Then, select a color to change the background color of the UI figure.
colorPickerPushTool
Version History
Introduced before R2006aR2020b: Specify custom icons
In apps created in App Designer and uifigure
-based apps, to add a
custom icon to a push tool, set the Icon
property. You can specify the
Icon
property as an image file or an
m
-by-n
-by-3 truecolor array.
The Icon
property is recommended over the
CData
property.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)