MATLAB Function Reference |
You can set and query graphics object properties in two ways:
inspect
function at the command line.
set
and get
functions enable you to set and query the values of properties.
You can set default Uipushtool properties by typing:
Where h can be the root handle (0), a figure handle, a uitoolbar handle, or a uipushtool handle. PropertyName
is the name of the Uipushtool 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.
Uipushtool Properties
This section lists all properties useful to uipushtool
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 control. |
ClickedCallback |
Control action. |
CreateFcn |
Callback routine executed during object creation. |
DeleteFcn |
Delete uipushtool callback routine. |
Enable |
Enable or disable the uipushtool. |
HandleVisibility |
Control access to object's handle. |
Interruptible |
Callback routine interruption mode. |
Parent |
Handle of uipushtool's parent. |
Separator |
Separator line mode |
Tag |
User-specified object label. |
TooltipString |
Content of object's tooltip. |
Type |
Object class. |
UserData |
User specified data. |
Visible |
Uipushtool 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 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 routine interruption. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, the callback associated with the new event uses the value of BusyAction
to decide whether or not to attempt to interrupt the executing callback.
cancel
, the event is discarded and the second callback does not execute.
queue
, and the Interruptible
property of the first callback is on
, the second callback is added to the event queue and executes in its turn after the first callback finishes execution.
Note
If the interrupting callback is a DeleteFcn or 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. See the Interruptible property for information about controlling a callback's interruptibility.
|
CData
3-dimensional array
Truecolor image displayed on control. 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. The largest image that fits on the push tool is 20-by-20. If the array is larger, only the center 20-by-20 part of the array is used.
ClickedCallback
string or function handle
Control action. A routine that executes when the uipushtool's Enable
property is set to on
, and you press a mouse button while the pointer is on the push tool itself or in a 5-pixel wide border around it.
CreateFcn
string or function handle
Callback routine executed during object creation. The specified function executes when MATLAB creates a uipushtool object. MATLAB sets all property values for the uipushtool before executing the CreateFcn
callback so these values are available to the callback. Within the function, use gcbo
to get the handle of the push tool being created.
Setting this property on an existing uipushtool object has no effect.
You can define a default CreateFcn
callback for all new uipushtools. This default applies unless you override it by specifying a different CreateFcn
callback when you call uipushtool
. For example, the code
imga(:,:,1) = rand(20); imga(:,:,2) = rand(20); imga(:,:,3) = rand(20); set(0,'DefaultUipushtoolCreateFcn','set(gcbo,''Cdata'',imga)'
creates a default CreateFcn
callback that runs whenever you create a new push tool. It sets the default image imga
on the push tool.
To override this default and create a push tool whose Cdata
property is set to a different image, call uipushtool
with code similar to
a = [.05:.05:0.95]; imgb(:,:,1) = repmat(a,19,1)'; imgb(:,:,2) = repmat(a,19,1); imgb(:,:,3) = repmat(flipdim(a,2),19,1); hpt = uipushtool(...,'CreateFcn','set(gcbo,''CData'',imgb)',...)
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 uipushtool object (e.g., when you call the delete
function or cause the figure containing the uipushtool 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 uipushtool. This property controls how uipushtools respond to mouse button clicks, including which callback routines execute.
on
- The uipushtool is operational (the default).
off
- The uipushtool is not operational and its image (set by the Cdata
property) is grayed out.
When you left-click on a uipushtool whose Enable
property is on
, MATLAB performs these actions in this order:
SelectionType
property.
ClickedCallback
routine.
CurrentPoint
property and does not execute the figure's WindowButtonDownFcn
callback.
When you left-click on a uipushtool whose Enable
property is off
, or when you right-click a uipushtool whose Enable
property has any value, MATLAB performs these actions in this order:
SelectionType
property.
CurrentPoint
property.
WindowButtonDownFcn
callback.
ClickedCallback
routine.
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.
HandleVisibility
is on
.
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.
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.
Interruptible
{on} | off
Callback routine interruption mode. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. MATLAB processes the callbacks according to these factors:
Interruptible
property of the object whose callback is executing
drawnow
, figure
, getframe
, pause
, or waitfor
statements
BusyAction
property of the object whose callback is waiting to execute
If the Interruptible
property of the object whose callback is executing is on
(the default), the callback can be interrupted. Whenever the callback calls one of the drawnow
, figure
, getframe
, pause
, or waitfor
functions, the function processes any events in the event queue, including the waiting callback, before performing its defined task.
If the Interruptible
property of the object whose callback is executing is off
, the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction
property of the object whose callback is waiting to execute determines what happens to the callback.
Parent
handle
Uipushtool parent. The handle of the uipushtool's parent toolbar. You can move a uipushtool 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 the left of the uipushtool.
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 'Copy'
.
TooltipString
string
Content of tooltip for object. The TooltipString
property specifies the text of the tooltip associated with the uipushtool. When the user moves the mouse pointer over the control and leaves it there, the tooltip is displayed.
Type
string
(read-only)
Object class. This property identifies the kind of graphics object. For uipushtool objects, Type
is always the string 'uipushtool'
.
UserData
array
User specified data. You can specify UserData
as any array you want to associate with the uipushtool object. The object does not use this data, but you can access it using the set
and get
functions.
Visible
{on} | off
Uipushtool visibility. By default, all uipushtools are visible. When set to off
, the uipushtool is not visible, but still exists and you can query and set its properties.
uipushtool | uiputfile |
© 1994-2005 The MathWorks, Inc.