Main Content

UIControl Properties

Control appearance and behavior of user interface control

expand all in page

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

expand all

Style of UIControl, specified as a value from the following table.

Style ValueDescription
'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.

Current value, specified as a number. The Value property is useful in querying or modifying the status of certain uicontrols:

Style of uicontrolDescription of Value Property
'togglebutton'

  • Raised: Value property equals the value of the Min property.

  • Depressed: Value property equals the value of the Max property.

'checkbox'

  • Unchecked: Value property changes to the value of the Min property.

  • Checked: Value property changes to the value of the Max property.

'radiobutton'

  • Deselected: Value property changes to the value of the Min property.

  • Selected: Value property changes to the value of the Max property.

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

Maximum value, specified as a number. The Max property affects the presentation of certain uicontrols:

Style of uicontrolDescription 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 Max – Min > 1. Otherwise, the edit text box accepts a single line of input.

The absolute values of Max and Min have no effect on the number of possible lines. As long as the difference is greater than 1, the edit box can contain any number of lines.

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

Minimum value, specified as a number. The Min property affects the presentation of certain uicontrols:

Style of uicontrolDescription 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 Max – Min > 1. Otherwise, the edit text box accepts a single line of input.

The absolute values of Max and Min have no effect on the number of possible lines. As long as the difference is greater than 1, the edit box can contain any number of lines.

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

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 the Value property increases or decreases when the user clicks one of the arrow buttons.

  • majorstep is the fraction of the slider range by which the Value 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]);

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

expand all

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 PropertySupported Array FormatsExamples
'pushbutton'

Character vector


Cell array of character vectors


String array


Categorical array

'Option 1'


{'Option 1'}


"Option 1"


categorical({'Option 1'})

'togglebutton'
'checkbox'
'radiobutton'
'edit'
'text'
'listbox'

Character vector


Cell array of character vectors


String array


Categorical array


Pipe-delimited row vector

'One'


{'One','Two','Three'}


["One" "Two" "Three"]


categorical({'one','two','three'})


'One|Two|Three'

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

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 from 0 to F. 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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

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 from 0 to F. 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

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 and 1.0

  • uint8 values between 0 and 255

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

expand all

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'

Font size, specified as a positive number. The FontUnits property specifies the units. The default size is system-dependent.

Example: 12

Example: 12.5

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.

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.

Font units, specified as one of the values from this table.

Units ValueDescription
'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 Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux® systems, the size of a pixel is determined by your system resolution.

Interactivity

expand all

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.

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 when Enable is set to 'on'.

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.

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.

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.

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.

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

expand all

Location and size, specified as a four-element vector of the form [left bottom width height]. This table describes each element in the vector.

ElementDescription
leftDistance from the inner left edge of the parent container to the outer left edge of the user interface control
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the user interface control
widthDistance between the right and left outer edges of the user interface control
heightDistance 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

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.

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.

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 of measurement, specified as one of the values from this table.

Units ValueDescription
'pixels' (default)

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

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:

  • Character width = width of the letter x.

  • Character height = distance between the baselines of two lines of text.

To access the default uicontrol font, use get(groot,'defaultuicontrolFontName') or set(groot,'defaultuicontrolFontName').

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 the Position property, then MATLAB sets Position using the units you specify.

  • If you specify the Units property after the Position property, MATLAB sets the position using the default Units. Then, MATLAB converts the Position value to the equivalent value in the units you specify.

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

expand all

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

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

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

CharacterThe character that displays as a result of pressing a key or keys. The character can be empty or unprintable.'a''=''''A'
ModifierA 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'}
KeyThe key being pressed, identified by the (lowercase) label on the key, or a text description.'a''equal''shift''a'
SourceThe object that has focus when the user presses the key.UIControl objectUIControl objectUIControl objectUIControl object
EventNameThe 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 the Key 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.

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 'control', or an empty cell array if there is no modifier.

{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'
SourceThe object that has focus when the user presses the key.UIControl objectUIControl objectUIControl objectUIControl object
EventNameThe 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 the Key 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.

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.

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

expand all

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

  • A value of 'off' blocks all interruption attempts. The BusyAction 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, 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.

  • Timer objects execute according to schedule regardless of the Interruptible 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 or gcf 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.

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

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.

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 the UIControl when the user clicks the component in the running app. Both the CurrentObject property of the Figure and the gco function return the UIControl as the current object.

  • 'off' — Sets the current object to be the closest ancestor of the UIControl whose HitTest is 'on' when the user clicks the component in the running app.

Parent/Child

expand all

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.

UIControl children, returned as an empty array. UIControl objects have no children. Setting this property has no effect.

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 ValueDescription
'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

expand all

This property is read-only.

Type of graphics object, returned as 'uicontrol'.

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.

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 R2006a

expand all

See Also

Topics