Uicontrol Properties

Control uicontrol appearance and behavior

Uicontrols are interface components, such as buttons and sliders, that users can interact with. The uicontrol function creates an interface component and sets any required properties before displaying it. By changing uicontrol property values, you can modify certain aspects of its appearance and behavior.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

b = uicontrol('Style','pushbutton');
pos = b.Position;
b.Position = [100 100 50 20];

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

Appearance

expand all

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

Uicontrol visibility, specified as 'on' or 'off'. When Visible is 'off', the uicontrol is not visible, but you can query and set its properties.

To make your GUI start faster, set the Visible property of all uicontrols that are not initially displayed to 'off'.

BackgroundColorUicontrol background color[.94 .94 .94] (default) | RGB triplet | short name | long name

Uicontrol background color, specified as an RGB triplet, short name, or long name. The color you specify fills the area bounded by the uicontrol.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

    Note:   Some operating systems override the BackgroundColor value.

Data Types: double | char

ForegroundColorUicontrol text color[0 0 0] (default) | RGB triplet | short name | long name

Uicontrol text color, specified as an RGB triplet, short name, or long name from the table below.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

    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

CDataOptional image to display on uicontrol3-D array of truecolor RGB values

Optional image to display on the uicontrol, 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 uicontrols that fully support CData. If you specify the CData property for a radio button or check box, the image might overlap with the text string. Also, specifying an image for radio button or check box disables the ability to show when they are selected or deselected.

Example: zeros(16,16,3)

Example: uint8(zeros(16,16,3))

Data Types: double | uint8

Location and Size

expand all

Position Location and size of uicontrol[left bottom width height]

Location and size of the uicontrol relative to the parent, specified as the vector, [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 uicontrol
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the uicontrol
widthDistance between the right and left outer edges of the uicontrol
heightDistance between the top and bottom outer edges of the uicontrol

All measurements are in units specified by the Units property.

    Note:   If the parent of the uicontrol is a figure, then the Position values are relative to the figure's drawable area. The drawable area of a figure is the area inside the window borders, excluding 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 Postion vector. For example, this code changes the width of the uicontrol to 52:

b = uicontrol;
b.Position(3) = 52;
b.Position
ans =

    20    20    52    20

Data Types: double

UnitsUnits of measurement'pixels' (default) | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

Units of measurement, specified as 'pixels', 'normalized', 'inches', 'centimeters', 'points', or 'characters'.

MATLAB uses these units to interpret the location and size values of the Position property:

  • The size of a uicontrol specified in pixel units depends on the system display settings and resolution.

  • Normalized units map the lower left corner of the parent container to (0,0) and the upper right corner to (1.0,1.0).

  • Inches, centimeters, and points are absolute units. 1 point = 1/72 inch.

  • Character units are determined by the default system font. Each character unit is the width of the letter x. The height of each character unit is the distance between the baselines of two lines of text.

MATLAB measures all units from the lower left corner of the parent object.

If you change the value of the Units property, it is good practice to return it to its default value after completing your computation to avoid affecting other functions that assume the Units property is set to 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 units you specify.

ExtentSize of uicontrol rectanglefour-element row vector

This property is read only.

Size of uicontrol 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 containing the uicontrol, 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 of the uicontrol 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 single line strings, 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 string wraps when displayed on the control. For multiline strings, the Extent rectangle encompasses all lines of text. Editable text fields are considered multiline if MaxMin > 1.

When the uicontrol Units property is 'normalized', the Extent values are measured relative to the figure, regardless of whether the uicontrol is contained in (parented to) a uipanel.

Font Style

expand all

FontNameFont for displaying uicontrol text'Helvetica' (default) | string

Font for displaying the uicontrol text, specified as a string. This property specifies the name of the font to use to display the text specified in the uicontrol 'String' property.

To use a fixed-width font, set the FontName property to the string, 'FixedWidth'. This setting instructs MATLAB to use the value of the root FixedWidthFontName property, which you can set in the startup.m file.

Ror more information about the startup.m file, seeSpecifying Startup Options in MATLAB Startup File.

Example: 'Arial'

FontSizeFont size for uicontrol textpositive number

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

Example: 12

Example: 12.5

Data Types: double

FontUnitsUnits of font size for uicontrol text'points' (default) | 'normalized' | 'inches' | 'centimeters' | 'pixels'

Units of font size for the uicontrol text, specified as 'points', 'normalized', 'inches', 'centimeters', or 'pixels'.

If you set this property to 'normalized', then MATLAB interprets the font size as a fraction of the uicontrol height. When you resize the uicontrol, MATLAB scales the displayed font to maintain that fraction.

The other FontUnits options (pixels, inches, centimeters, and points) are absolute units. 1 point = 1/72 inch.

FontWeightFont weight for uicontrol text'normal' (default) | 'bold'

Font weight for the uicontrol text, specified as a value from the table below.

FontWeight ValueDescription
'normal'Normal font weight
'bold'Heavy font weight

Not all fonts support all font weights. Therefore, if you specify an unsupported value for the FontWeight property, the result might appear the same as the default.

    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.

FontAngleCharacter slant of uicontrol text'normal' (default) | 'italic'

Character slant of uicontrol text, 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.

Text

expand all

StringText to displaystring | cell array of char values | pipe-delimited row vector | padded column matrix

Text to display, specified as a string, cell array, a pipe-delimited row vector, or a padded column matrix. The uicontrol Style property value determines the array format you can use.

Style Property ValueSupported Array FormatsExamples
'checkbox'
  • String

  • Cell array of char values

'Item 1'
{'Item 1'}
'edit'
  • String

  • Cell array of char values

'Default text'
{'Default text'}
'pushbutton'
  • String

  • Cell array of char values

'Evaluate'
{'Evaluate'}
'radiobutton'
  • String

  • Cell array of char values

'Round to nearest integer'
{'Round to nearest integer'}
'text'
  • String

  • Cell array of char values

'Enter values'
{'Enter values'}
'togglebutton'
  • String

  • Cell array of char values

'Activate'
{'Activate'}
'listbox'
  • String

  • Cell array of char values

  • Pipe-delimited row vector

  • Padded column matrix

'Red'
{'Red','Blue','Orange'}
'Red|Blue|Orange'
['Red   ';'Blue  ';'Orange']
'popupmenu'
  • String

  • Cell array of char values

  • Pipe-delimited row vector

  • Padded column matrix

'Red'
{'Red','Blue','Orange'}
'Red|Blue|Orange'
['Red   ';'Blue  ';'Orange']

    Note:   Some important characteristics of the String property:

    • If you specify a cell array for a check box, push button, radio button, or toggle button, then MATLAB displays only the first element in the cell array.

    • If you programmatically replace the string of an 'edit' style of uicontrol, the cursor moves to the beginning of the text.

    • If you want to specify a Unicode® character, pass the Unicode decimal code to the char function. For example, ['Multiples of ' char(960)] displays as Multiples of π.

Data Types: char

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

Interactive Control

expand all

CallbackCallback function that executes when user interacts with uicontrol'' (default) | function handle | cell array | string

Uicontrol action, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

This is a function that makes the uicontrol respond to user inputs, such as push button clicks, slider movements, or check box selections.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

ButtonDownFcnButton-press callback function'' (default) | function handle | cell array | string

Button-press callback function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The ButtonDownFcn callback is a function that executes when the user clicks a mouse button on the uicontrol. The callback executes in the following situations:

  • The user right-clicks the uicontrol, and the uicontrol Enable property is set to 'on'.

  • The end user right-clicks or left-clicks the Uicontrol, and the uicontrol Enable property is set to 'off' or 'inactive'.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

KeyPressFcnKey press callback function'' (default) | function handle | cell array | string

Key press callback function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This 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, 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 descriptive string.'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.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

KeyReleaseFcnKey-release callback function'' (default) | function handle | cell array | string

Key-release callback function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This 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'. This value is always an empty cell array for aseFcn callbacks.

{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 descriptive string.

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

EnableOperational state of uicontrol'on' (default) | 'off' | 'inactive'

Operational state of the uicontrol, specified as 'on', 'off', or 'inactive'. The Enable property controls whether the uicontrol responds to button clicks. These are the possible values:

  • 'on' – The uicontrol is operational.

  • 'off' – The uicontrol is not operational and appears grayed-out.

  • 'inactive' – The uicontrol is not operational, but it has the same appearance as when Enable is set to 'on'.

The value of the Enable property and the type of button click determine how the GUI responds.

Enable ValueResponse to Left-ClickResponse to Right-Click
'on'The uicontrol's Callback function executes.
  1. The figure's WindowButtonDownFcn callback executes.

  2. The uicontrol's ButtonDownFcn callback executes.

'off' or 'inactive'
  1. The figure's WindowButtonDownFcn callback executes.

  2. The uicontrol's ButtonDownFcn callback executes.

  1. The figure's WindowButtonDownFcn callback executes.

  2. The uicontrol's ButtonDownFcn callback executes.

TooltipStringTooltip textstring

Tooltip text, specified as a string. When the user hovers the mouse pointer over the uicontrol and leaves it there, the tooltip displays. If you want to create a tooltip that has more than one line of text, use sprintf to generate a string containing newline (\n) characters and then set the TooltipString to that string.

Specify TooltipString Containing Two Lines

b = uicontrol;
s = sprintf('Tooltip line 1\nTooltip line 2');
b.TooltipString = s;

UIContextMenuUicontrol context menuempty GraphicsPlaceholder array (default) | uicontextmenu object

Uicontrol context menu, specified as a uicontextmenu object. Use this property to display a context menu when the user right-clicks on the uicontrol. Create the context menu using the uicontextmenu function.

SelectedSelection status of uicontrol'off' (default) | 'on'

    Note:   The behavior of the Selected property changed in R2014b, and it is not recommended. It no longer has any effect on uicontrols. This property might be removed in a future release.

SelectionHighlightAbility to highlight selection handles'on' (default) | 'off'

    Note:   The behavior of the SelectionHighlight property changed in R2014b, and it is not recommended. It no longer has any effect on uicontrols. This property might be removed in a future release.

Callback Execution Control

expand all

BusyActionCallback queuing'queue' (default) | 'cancel'

Callback queuing specified as 'queue' (default) or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property of the source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these values:

  • 'queue' — Put the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Do not execute the interrupting callback.

Whenever MATLAB invokes a callback, that callback always attempts to interrupt an executing callback. The Interruptible property of the object whose callback is running determines if interruption is allowed. If Interruptible is set to:

  • on — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • off — The BusyAction property (of the object owning the executing callback) determines if MATLAB enqueues or ignores the interrupting callback.

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a uicontrol callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

    Note:   Callback interruption and execution behave differently in these situations:

    • If the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

    • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

    • MATLAB does not save the state of properties or the display when an interruption occurs. For example, the handle returned by the gca or gcf command might change when another callback executes.

HitTestAbility to become current object'on' (default) | 'off'

This property has no effect on the uicontrol.

Creation and Deletion Control

expand all

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

This property is read only.

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

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

CreateFcnUicontrol creation functionfunction handle | cell array | string

Uicontrol creation function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This property specifies a callback function to execute when MATLAB creates the uicontrol. MATLAB initializes all uicontrol property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Use the gcbo function in your CreateFcn code to get the handle to the uicontrol that is being created.

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

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

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUicontrol deletion functionfunction handle | cell array | string

Uicontrol deletion function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the uicontrol (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uicontrol. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your DeleteFcn code to get the handle to the uicontrol that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUicontrol identifier'' (default) | string

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

Example: 'pushbutton1'

Data Types: char

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

Data to associate with the uicontrol object, specified as any array. Specifying UserData can be useful for sharing data values within and across GUIs you create. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

TypeType of graphics object'uicontrol'

This property is read only.

Type of graphics object, returned as 'uicontrol'.

Parent/Child

expand all

ParentUicontrol parentfigure | uipanel | uibuttongroup | uitab

Uicontrol parent, specified as a figure, uipanel, uibuttongroup, or uitab. You can move a uicontrol to a different figure, uipanel, uibuttongroup, or uitab by setting this property to the handle of the target figure, uipanel, uibuttgroup, or uitab.

ChildrenChildren of uicontrolempty array

Children of uicontrol, returned as an empty array. Uicontrol objects have no children. Setting this property has no effect.

HandleVisibilityVisibility 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 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 protects the GUI from command-line users, while allowing callback routines to have complete access.
'off'The uicontrol handle is invisible at all times. This option might be useful when a callback routine invokes a function that might potentially damage the GUI (such as a function that evaluates user-typed strings). You can set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

Set the graphics root ShowHiddenHandles property to 'on' to make all handles visible, regardless of their HandleVisibility value. This setting has no effect on their HandleVisibility values.

    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.

Type of Control

expand all

StyleStyle of uicontrol'pushbutton' (default) | string

Style of uicontrol, specified as a string from the following table. See Specifying the Uicontrol Style for more details about each style.

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.

ValueCurrent value of uicontrolnumber

Current value of uicontrol, specified as a number. The uicontrol Style property determines the role of the Value property.

Style of uicontrolDescription of Value Property
'pushbutton'Push buttons do not use this 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.

'edit'Editable text components do not use this property.
'text'Static text components do not use this 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.

MaxMaximum value of uicontrol1 (default) | number

Maximum value of uicontrol, specified as a number. The uicontrol Style property determines the role of the Max property:

Style of uicontrolDescription of Value Property
'pushbutton'Push buttons do not use this 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'Editable text components do not use this property.
'text'Static text components do not use this property.
'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 MaxMin > 1, then the user can select multiple items simultaneously. If MaxMin ≤ 1, then 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.
'popupmenu'Pop-up menus do not use this property.

MinMinimum value of uicontrol0 (default) | number

Minimim value of uicontrol, specified as a number. The uicontrol Style property determines the role of the Min property:

Style of uicontrolDescription of Value Property
'pushbutton'Push buttons do not use this 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'Editable text components do not use this property.
'text'Static text components do not use this property.
'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 MaxMin > 1, then the user can select multiple items simultaneously. If MaxMin ≤ 1, then 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.
'popupmenu'Pop-up menus do not use this property.

SliderStepSlider 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 keys or the slider trough (slider channel):

  • The slider Value property increases or decreases by the value of minorstep when the user presses an arrow key.

  • The slider Value property increases or decreases by the value of majorstep when the user clicks the slider trough.

Both minorstep and majorstep must be greater than 1e-6, and minorstep must be less than or equal to minorstep.

The actual step size depends on the SliderStep value and the slider range (MaxMin). For example, a slider having SliderStep value of [0.01 0.10], Max value of 1, and Min of 0 provides a 1% change when the user presses an arrow key and a 10% change when the user clicks in the trough.

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 size is larger for majorstep values greater than 1.

Example: [.5 1]

ListboxTopIndex of top item in list box1 (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 string 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 strings you specify as the String property value. The ListboxTop value must be between 1 and the number of strings 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 causes the GUI to scroll to that value.

    For the most reliable results, query or modify the ListboxTop property after MATLAB finishes drawing the uicontrol on the screen.

Example: 3

Data Types: double

Was this topic helpful?