UIControl Properties
Control appearance and behavior of user interface control
User interface controls are components such as buttons and sliders that users
can interact with. The uicontrol
function creates a user interface
control and sets any required properties before displaying it. By changing property
values, you can modify the appearance and behavior of user interface controls. Use dot
notation to refer to a specific object and property.
Note
Creating UIControl
objects is not supported in App Designer or
in apps created using the uifigure
function. Instead, for a
list of available components in these contexts, see App Building Components.
For example, this code creates a button, stores the UIControl
object as b
, and then sets the Position
property
using dot notation.
f = figure; b = uicontrol(f,'Style','pushbutton'); b.Position = [100 100 50 20];
Type of Control
Style
— Style of UIControl
'pushbutton'
(default) | 'togglebutton'
| 'checkbox'
| 'radiobutton'
| ...
Style of UIControl
, specified as a value from the
following table.
Style Value | Description |
---|---|
'pushbutton' | Button that appears to depress until you release the mouse button. |
'togglebutton' | Button that can have two states: up or depressed. The state of the toggle button changes every time you click it. |
'checkbox' | Check box that can have two states: checked or unchecked. The state changes when the user clicks and releases the mouse button over it. |
'radiobutton' | Button that can have two states: selected or deselected. Radio buttons are intended to be mutually exclusive within a group of related radio buttons. |
'edit' | Editable text field. |
'text' | Static text field. |
'slider' | Button that the user pushes along a horizontal or vertical bar. The position of the button indicates a value within a specified range. |
'listbox' | List of items from which the user can select one or more items. Unlike pop-up menus, list boxes do not expand when clicked. |
'popupmenu' | Isolated menu that expands to display a list of choices when you click it. When it is collapsed, the menu shows the current choice. |
Value
— Current value
number
Current value, specified as a number. The Value
property is useful in querying or modifying the status of certain
uicontrols:
Style of uicontrol | Description of Value Property |
---|---|
'togglebutton' |
|
'checkbox' |
|
'radiobutton' |
|
'slider' | Value property equals the
corresponding slider value. |
'listbox' | Value property equals an array
index corresponding to the selected item in the list
box. A value of 1 corresponds to the
first item in the list. |
'popupmenu' | Value property equals an array
index corresponding to the selected item in the pop-up
menu. A value of 1 corresponds to the
first item in the pop-up menu. |
Max
— Maximum value
1
(default) | number
Maximum value, specified as a number. The Max
property affects the presentation of certain uicontrols:
Style of uicontrol | Description of Value Property |
---|---|
'togglebutton' | When the toggle button is depressed, the
Value property changes to the
value of the Max property. |
'checkbox' | When the check box is checked, the
Value property changes to the
value of the Max property. |
'radiobutton' | When the radio button is selected, the
Value property changes to the
value of the Max property. |
'edit' | The edit text box accepts multiple lines of
input when The absolute values of
|
'slider' | The Max property value is the
maximum slider value, which must be greater than the
Min property value. |
'listbox' | The Max property value helps
determine whether the user can select multiple items in
the list box simultaneously. If Max
– Min > 1, then the user can
select multiple items simultaneously. Otherwise, the
user cannot select multiple items simultaneously. If you
set the Max and
Min properties to allow
multiple selections, then the Value
property value can be a vector of indices. |
Min
— Minimum value
0
(default) | number
Minimum value, specified as a number. The Min
property affects the presentation of certain uicontrols:
Style of uicontrol | Description of Value Property |
---|---|
'togglebutton' | When the toggle button is raised, the
Value property changes to the
value of the Min property. |
'checkbox' | When the check box is unchecked, the
Value property changes to the
value of the Min property. |
'radiobutton' | When the radio button is deselected, the
Value property changes to the
value of the Min property. |
'edit' | The edit text box accepts multiple lines of
input when The absolute values of
|
'slider' | The Min property value is the
minimum slider value, which must be less than the
Max property value. |
'listbox' | The Max property value helps
determine whether the user can select multiple items in
the list box simultaneously. If Max
– Min > 1, then the user can
select multiple items simultaneously. Otherwise, the
user cannot select multiple items simultaneously. If you
set the Max and
Min properties to allow
multiple selections, then the Value
property value can be a vector of indices. |
SliderStep
— Slider step size
[0.01 0.10]
(default) | [minorstep majorstep]
Slider step size, specified as the array, [minorstep
majorstep]
. This property controls the magnitude of the slider
value change when the user clicks the arrow buttons or the slider trough
(slider channel):
minorstep
is the fraction of the slider range by which theValue
property increases or decreases when the user clicks one of the arrow buttons.majorstep
is the fraction of the slider range by which theValue
property increases or decreases when the user clicks the slider trough.
When the value of majorstep
is greater than 1, the
slider fraction is no greater than 100%.
Both minorstep
and majorstep
must be
greater than 1e-6
, and minorstep
must
be less than or equal to majorstep
.
As majorstep
increases, the slider thumb indicator
grows longer. When majorstep
is equal to
1
, the thumb indicator is half as long as the trough.
The thumb indicator is larger for majorstep
values
greater than 1
.
Example
This slider has a range of Max
–
Min
= 1
. The slider
Value
property changes by 1% when the user
presses an arrow button. It changes by 10% when the user clicks in the
trough.
s = uicontrol('Style','Slider','Min',0,'Max',1,'SliderStep',[0.01 0.10]);
ListboxTop
— Index of top item in list box
1
(default) | integer value
Index of top item in list box, specified as an integer value. This
property applies only to the listbox style of UIControl
.
This property specifies which item appears in the top-most position in a
list box that is not large enough to display all list entries. The
ListboxTop
value is an index into the array of you
specify as the String
property value. The
ListboxTop
value must be between
1
and the number of elements in the array. Noninteger
values are fixed to the next lowest integer.
Note
The String
and Value
properties might override the value of the
ListboxTop
property regardless of the
ListboxTop
value you specify. The
ListboxTop
value can change depending on the
value of other UIControl
properties. For example,
explicitly setting the Value
property scrolls the
list to that value.
For the most reliable results, query or modify the
ListboxTop
property after MATLAB® finishes drawing the user interface control on the
screen.
Text and Styling
String
— Text to display
character vector | cell array of character vectors | string array | categorical array | ...
Text to display, specified as a character vector, cell array of character
vectors, string array, categorical array, or pipe-delimited row vector. The
Style
property dictates the array format you can use.
Style Property | Supported Array Formats | Examples |
---|---|---|
'pushbutton' | Character vector Cell array of character vectors String array Categorical array |
|
'togglebutton' | ||
'checkbox' | ||
'radiobutton' | ||
'edit' | ||
'text' | ||
'listbox' | Character vector Cell array of character vectors String array Categorical array Pipe-delimited row vector |
|
'popupmenu' |
Note
If you specify a cell array or categorical array for a push button, toggle button, check box, or radio button, MATLAB displays only the first element in the array.
ForegroundColor
— Text color
[0 0 0]
(default) | RGB triplet | hexadecimal color code | 'r'
| 'g'
| 'b'
| ...
Text color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]
; for example,[0.4 0.6 0.7]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" | |
"green" | "g" | [0 1 0] | "#00FF00" | |
"blue" | "b" | [0 0 1] | "#0000FF" | |
"cyan"
| "c" | [0 1 1] | "#00FFFF" | |
"magenta" | "m" | [1 0 1] | "#FF00FF" | |
"yellow" | "y" | [1 1 0] | "#FFFF00" | |
"black" | "k" | [0 0 0] | "#000000" | |
"white" | "w" | [1 1 1] | "#FFFFFF" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
Note
If you change the value of ForegroundColor
for a
listbox, then MATLAB uses that color for all listbox items, except for the
currently selected listbox item. For selected items, MATLAB uses a color that ensures good contrast between the text
of selected items and the selection color.
Example: [0 0 1]
Example: 'b'
Example: 'blue'
Data Types: double
| char
BackgroundColor
— Background color
[.94 .94 .94]
(default) | RGB triplet | hexadecimal color code | 'r'
| 'g'
| 'b'
| ...
Background color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.
RGB triplets and hexadecimal color codes are useful for specifying custom colors.
An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range
[0,1]
; for example,[0.4 0.6 0.7]
.A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (
#
) followed by three or six hexadecimal digits, which can range from0
toF
. The values are not case sensitive. Thus, the color codes"#FF8800"
,"#ff8800"
,"#F80"
, and"#f80"
are equivalent.
Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.
Color Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" | |
"green" | "g" | [0 1 0] | "#00FF00" | |
"blue" | "b" | [0 0 1] | "#0000FF" | |
"cyan"
| "c" | [0 1 1] | "#00FFFF" | |
"magenta" | "m" | [1 0 1] | "#FF00FF" | |
"yellow" | "y" | [1 1 0] | "#FFFF00" | |
"black" | "k" | [0 0 0] | "#000000" | |
"white" | "w" | [1 1 1] | "#FFFFFF" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
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
and1.0
uint8
values between0
and255
Push buttons and toggle buttons are the only UIControl
objects that fully support CData
. If you specify the
CData
property for a radio button or check box, the
image might overlap with the text. Also, specifying an image for radio
button or check box disables the ability to show when they are selected or
deselected.
Data Types: double
| uint8
Font
FontName
— Font name
system supported font name | 'FixedWidth'
Font name, specified as a system supported font name or
'FixedWidth'
. The default font depends on the specific operating
system and locale.
To use a fixed-width font that looks good in any locale,
specify 'FixedWidth'
. The actual fixed-width font used depends on the
FixedWidthFontName
property of
the root object. Changing the FixedWidthFontName
property causes an
immediate update of the display to use the new font.
Example: 'Arial'
FontSize
— Font size
positive number
Font size, specified as a positive number. The FontUnits
property
specifies the units. The default size is system-dependent.
Example: 12
Example: 12.5
FontWeight
— Font weight
'normal'
(default) | 'bold'
Font weight, specified as a value from the following table.
'normal'
— Default weight as defined by the particular font'bold'
— Thicker character outlines than normal
MATLAB uses the FontWeight
property
to select a font from those available on your system. Not all fonts
have a bold font weight. Therefore, specifying a bold font weight
still can result in the normal font weight.
Note
The 'light'
and 'demi'
font weight
values have been removed in R2014b. If you specify either of these values, the
result is a normal font weight.
FontAngle
— Font angle
'normal'
(default) | 'italic'
Font angle, specified as 'normal'
or 'italic'
.
MATLAB uses this property to select a font from those available on your system.
Setting this property to 'italic'
selects a slanted version of the
font, if it is available on your system.
Note
The 'oblique'
value has been removed. Use
'italic'
instead.
FontUnits
— Font units
'points'
(default) | 'normalized'
| 'inches'
| 'centimeters'
| 'pixels'
Font units, specified as one of the values from this table.
Units Value | Description |
---|---|
'points' | Points. One point is 1/72nd of an inch. |
'normalized' | Normalized values for specifying the font size as a fraction of the height. When you resize a UI component, MATLAB scales the displayed font to maintain that fraction. |
'inches' | Inches. |
'centimeters' | Centimeters. |
'pixels' | Pixels. Starting in R2015b, distances in pixels are independent of your system resolution on Windows® and Macintosh systems:
On Linux® systems, the size of a pixel is determined by your system resolution. |
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 of user interface control
'on'
(default) | 'off'
| 'inactive'
Operational state of user interface control, specified as
'on'
, 'off'
, or
'inactive'
. The Enable
property
controls whether or not the user interface control responds to user
interaction. These are the possible values:
'on'
– The user interface control is operational.'off'
– The user interface control is not operational and appears grayed-out.'inactive'
– The user interface control is not operational, but it has the same appearance as whenEnable
is set to'on'
.
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
.
ContextMenu
— Context menu
empty GraphicsPlaceholder
array (default) | ContextMenu
object
Context menu, specified as a ContextMenu
object created using the uicontextmenu
function. Use this property to display a context menu when
you right-click on a component.
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.
Selected
— Selection state (not recommended)
'off'
(default) | on/off logical value
Note
The behavior of the Selected
property changed in R2014b,
and it is not recommended. It no longer has any effect on objects of this type.
This property might be removed in a future release.
SelectionHighlight
— Display of selection handles (not recommended)
'on'
(default) | on/off logical value
Note
The behavior of the SelectionHighlight
property changed in R2014b, and it is not recommended. It no
longer has any effect on objects of this type. This property
might be removed in a future release.
Position
Position
— Location and size
[left bottom width height]
Location and size, specified as a four-element vector of the form
[left bottom width height]
. This table describes each
element in the vector.
Element | Description |
---|---|
left | Distance from the inner left edge of the parent container to the outer left edge of the user interface control |
bottom | Distance from the inner bottom edge of the parent container to the outer bottom edge of the user interface control |
width | Distance between the right and left outer edges of the user interface control |
height | Distance between the top and bottom outer edges of the user interface control |
All measurements are in units specified by the
Units
property.
Note
The Position
values are relative to the
parent container’s drawable area. The
drawable area is the area inside the borders of the container and
does not include the area occupied by the title. If the parent container
is a figure, then the drawable area also excludes the menu bar and
tool bar.
Modify One Value in the Position Vector
You can combine dot notation and array indexing when you want to
change one value in the Position
vector. For
example, this code changes the width of the user interface control to
52
:
b = uicontrol; b.Position(3) = 52; b.Position
ans = 20 20 52 20
InnerPosition
— Location and size
[left bottom width height]
Location and size, specified as a four-element vector of the form [left
bottom width height]
. All measurements are in units specified by the
Units
property.
This property value is identical to the Position
and
OuterPosition
property values.
OuterPosition
— Location and size
[left bottom width height]
Location and size, specified as a four-element vector of the form [left
bottom width height]
. All measurements are in units specified by the
Units
property.
This property value is identical to the Position
and
InnerPosition
property values.
Extent
— Size of enclosing rectangle
four-element row vector
This property is read-only.
Size of enclosing rectangle, returned as a four-element row vector. The
first two elements of the vector are always zero. The third and fourth
elements are the width and height of the rectangle, respectively. All
measurements are in units specified by the Units
property.
MATLAB determines the size of the rectangle based on the size of the
String
property value and the font characteristics.
To adjust the width and height to accommodate the size of the
String
value, set the Position
width and height values to be slightly larger than the
Extent
width and height values.
For a String
value that is a single line of text, the
height element of the Extent
property indicates the
height of a single line. The width element indicates the width of the
longest line, even if the text wraps when displayed on the control. For
multiple lines of text, the Extent
rectangle
encompasses all lines of text. Editable text fields are considered multiline
if Max
– Min
>
1
.
Units
— Units of measurement
'pixels'
(default) | 'normalized'
| 'inches'
| 'centimeters'
| 'points'
| 'characters'
Units of measurement, specified as one of the values from this table.
Units Value | Description |
---|---|
'pixels' (default) | Pixels. Starting in R2015b, distances in pixels are independent of your system resolution on Windows and Macintosh systems:
On Linux systems, the size of a pixel is determined by your system resolution. |
'normalized' | These units are normalized with respect to the parent container.
The lower-left corner of the container maps to
(0,0) and the upper-right corner maps to
(1,1) . |
'inches' | Inches. |
'centimeters' | Centimeters. |
'points' | Points. One point equals 1/72nd of an inch. |
'characters' | These units are based on the default uicontrol font of the graphics root object:
To access the default uicontrol font, use
|
MATLAB measures all units from the lower left corner of the parent object.
This property affects the Position
property.
If you change the Units
property, consider returning
its value to the default value after completing your computation to
avoid affecting other functions that assume the default value.
The order in which you specify the Units
and Position
properties
has these effects:
If you specify the
Units
before thePosition
property, then MATLAB setsPosition
using the units you specify.If you specify the
Units
property after thePosition
property, MATLAB sets the position using the defaultUnits
. Then, MATLAB converts thePosition
value to the equivalent value in the units you specify.
HorizontalAlignment
— Alignment of uicontrol text
'center'
(default) | 'left'
| 'right'
Alignment of the uicontrol text, specified as 'center'
,
'left'
, or 'right'
. This property
determines the justification of the String
property
text.
The HorizontalAlignment
property affects only
'text'
and 'edit'
styles of
uicontrols.
Callbacks
Callback
— Primary callback function
''
(default) | function handle | cell array | character vector
Primary callback 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.
This function executes in response to user interaction, such as push
button clicks, slider movements, or check box selections. This function can
execute only when the Enable
property of the
UIControl
object is set to
'on'
.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Specify a Callback Function.
Data Types: function_handle
| cell
| char
ButtonDownFcn
— Button-press callback function
''
(default) | function handle | cell array | character vector
Button-press callback 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 ButtonDownFcn
callback is a function that executes when the user
clicks a mouse button on a UI component. The callback executes in the following situations:
The user right-clicks the UI component, and the
Enable
property is set to'on'
.The user right-clicks or left-clicks the UI component, and the
Enable
property is set to'off'
or'inactive'
.
KeyPressFcn
— Key press callback function
''
(default) | function handle | cell array | character vector
Key press callback 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 callback function executes when the UIControl
object
has focus and the user presses a key. If you do not define a function for this property,
MATLAB passes key presses to the parent figure. Repeated key presses retain the
focus of the UIControl
object, and the function
executes with each key press. If the user presses multiple keys at approximately the
same time, MATLAB detects the key press for the last key pressed.
If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.
Property | Description | Examples: | |||
---|---|---|---|---|---|
a | = | Shift | Shift-a | ||
Character | The character that displays as a result of pressing a key or keys. The character can be empty or unprintable. | 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of one or more modifier keys that are being pressed (such as, Ctrl, Alt, Shift). | {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key being pressed, identified by the (lowercase) label on the key, or a text description. | 'a' | 'equal' | 'shift' | 'a' |
Source | The object that has focus when the user presses the key. | UIControl object | UIControl object | UIControl object | UIControl object |
EventName | The action that caused the callback function to execute. | 'KeyPress' | 'KeyPress' | 'KeyPress' | 'KeyPress' |
Pressing modifier keys affects the callback data in the following ways:
Modifier keys can affect the
Character
property, but do not change theKey
property.Certain keys, and keys modified with Ctrl, put unprintable characters in the
Character
property.Ctrl, Alt, Shift, and several other keys, do not generate
Character
property data.
You also can query the CurrentCharacter
property
of the figure to determine which character the user pressed.
KeyReleaseFcn
— Key-release callback function
''
(default) | function handle | cell array | character vector
Key-release callback 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 callback function executes when the UIControl
object
has focus and the user releases a key.
If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.
Property | Description | Examples: | |||
---|---|---|---|---|---|
a | = | Shift | Shift-a | ||
Character | Character interpretation of the key that was released. | 'a' | '=' | '' | 'A' |
Modifier | Current modifier, such as | {1x0 cell} | {1x0 cell} | {1x0 cell} | {1x0 cell} |
Key | Name of the key that was released, identified by the lowercase label on the key, or a text description. | 'a' | 'equal' | 'shift' | 'a' |
Source | The object that has focus when the user presses the key. | UIControl object | UIControl object | UIControl object | UIControl
object |
EventName | The action that caused the callback function to execute. | 'ase' | 'ase' | 'ase' | 'ase' |
Pressing modifier keys affects the callback data in the following ways:
Modifier keys can affect the
Character
property, but do not change theKey
property.Certain keys, and keys modified with Ctrl, put unprintable characters in the
Character
property.Ctrl, Alt, Shift, and several other keys, do not generate
Character
property data.
You also can query the CurrentCharacter
property
of the figure to determine which character the user pressed.
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
'on'
(default) | on/off logical value
Ability to become current object,
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'
— Sets the current object to theUIControl
when the user clicks the component in the running app. Both theCurrentObject
property of theFigure
and thegco
function return theUIControl
as the current object.'off'
— Sets the current object to be the closest ancestor of theUIControl
whoseHitTest
is'on'
when the user clicks the component in the running app.
Parent/Child
Parent
— Parent object
Figure
| Panel
| ButtonGroup
| Tab
Parent object, specified as a Figure
, Panel
,
ButtonGroup
, or Tab
object. Use this property
to specify the parent container when creating a UI component or to move an existing UI
component to a different parent container.
Children
— UIControl
children
empty array
UIControl
children, returned as an empty array.
UIControl
objects have no children. Setting this property has
no effect.
HandleVisibility
— Visibility of UIControl
handle
'on'
(default) | 'callback'
| 'off'
Visibility of UIControl
handle, specified as
'on'
, 'callback'
, or 'off'
.
This property controls the visibility of the UIControl
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 Value | Description |
---|---|
'on' | The UIControl handle is
always visible. |
'callback' | The UIControl 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 UIControl
at the command-line, but allows callback functions to access
it. |
'off' | The UIControl 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.
Note
Do not try to access radio buttons and toggle buttons that are managed by a
uibuttongroup
outside of the
button group. Set the HandleVisibility
of those radio
buttons and toggle buttons to 'off'
to prevent accidental
access.
Identifiers
Type
— Type of graphics object
'uicontrol'
This property is read-only.
Type of graphics object, returned as
'uicontrol'
.
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.
Version History
Introduced before R2006aR2020a: UIContextMenu
property is not recommended
Starting in R2020a, using the UIContextMenu
property to assign a
context menu to a graphics object or UI component is not recommended. Use the
ContextMenu
property instead. The property values are the
same.
There are no plans to remove support for the UIContextMenu
property at this time. However, the UIContextMenu
property no
longer appears in the list returned by calling the get
function on a
graphics object or UI component.
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)