Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Uicontrol Properties

Describe user interface control (uicontrol) properties

Modifying Properties

You can set and query graphics object properties in two ways:

  • The Property Inspector is an interactive tool that enables you to see and change object property values. The Property inspector is available from GUIDE, or use the inspect function at the command line.

  • The set and get commands enable you to set and query the values of properties

To change the default value of properties see Setting Default Property Values. You can also set default uicontrol properties on the root and figure levels:

set(0,'DefaultUicontrolProperty',PropertyValue...)
set(gcf,'DefaultUicontrolProperty',PropertyValue...)

where Property is the name of the uicontrol property whose default value you want to set and PropertyValue is the value you are specifying as the default. Use set and get to access uicontrol properties.

For information on using these uicontrols within GUIDE, the MATLAB® GUI development environment, see Programming GUI Components in the MATLAB Creating GUIs documentation.

Uicontrol Properties

This section lists all properties useful to uicontrol objects along with valid values and descriptions of their use. Curly braces {} enclose default values.

Property

Purpose

BackgroundColor

Object background color

BeingDeleted

This object is being deleted

BusyAction

Callback routine interruption

ButtonDownFcn

Button-press callback routine

Callback

Control action

CData

Truecolor image displayed on the control

Children

Uicontrol objects have no children

CreateFcn

Callback routine executed during object creation

DeleteFcn

Callback routine executed during object deletion

Enable

Enable or disable the uicontrol

Extent

position rectangle (read only)

FontAngle

Character slant

FontName

Font family

FontSize

Font size

FontUnits

Font size units

FontWeight

Weight of text characters

ForegroundColor

Color of text

HandleVisibility

Whether handle is accessible from command line and GUIs

HorizontalAlignment

Alignment of label string

Interruptible

Callback routine interruption mode

KeyPressFcn

Key press callback routine

ListboxTop

Index of top-most string displayed in list box

Max

Maximum value (depends on uicontrol object)

Min

Minimum value (depends on uicontrol object)

Parent

Uicontrol object's parent

Position

Size and location of uicontrol object

SliderStep

Slider step size

String

Uicontrol object label, also list box and pop-up menu items

Style

Type of uicontrol object

Tag

User-specified object identifier

TooltipString

Content of object's tooltip

Type

Class of graphics object

UIContextMenu

Uicontextmenu object associated with the uicontrol

Units

Units to interpret position vector

UserData

User-specified data

Value

Current value of uicontrol object

Visible

Uicontrol visibility

BackgroundColor

ColorSpec

Object background color. The color used to fill the uicontrol rectangle. Specify a color using a three-element RGB vector or one of the MATLAB predefined names. The default color is determined by system settings. See ColorSpec for more information on specifying color.

    Note:   Platform look and feel for a GUI element can override change requests from MATLAB. It is possible your system will not honor a request to change the background color.

BeingDeleted

on | {off} (read-only)

This object is being deleted. Mechanism to determine if objects are in the process of being deleted. MATLAB sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property). It remains set to on while the delete function executes, after which the object no longer exists.

For example, an object's delete function calls other functions that act on a number of different objects. If a function does not need to perform an action on an about-be-deleted object, it can check the object's BeingDeleted property before acting.

BusyAction

cancel | {queue}

Callback queuing

Determines how MATLAB handles the execution of interrupting callbacks.

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. The BusyAction property of the interrupting callback determines how MATLAB handles its execution. When the BusyAction property is set to:

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

  • 'cancel' — Discards the interrupting callback as MATLAB finishes execution.

For information about how the Interruptible property of the callback controls whether other callbacks can interrupt the running callback, see the Interruptible property description.

ButtonDownFcn

string or function handle (GUIDE sets this property)

Button-press callback routine. A callback routine that can execute when you press a mouse button while the pointer is on or near a uicontrol. Specifically:

  • If the uicontrol's Enable property is set to on, the ButtonDownFcn callback executes when you click the right or left mouse button in a 5-pixel border around the uicontrol or when you click the right mouse button on the control itself.

  • If the uicontrol's Enable property is set to inactive or off, the ButtonDownFcn executes when you click the right or left mouse button in the 5-pixel border or on the control itself.

This is useful for implementing actions to interactively modify control object properties, such as size and position, when they are clicked on (using selectmoveresize, for example).

Define this routine as a string that is a valid MATLAB expression or the name of a code file. The expression executes in the MATLAB workspace.

To add a ButtonDownFcn callback in GUIDE, select View Callbacks from the Layout Editor View menu, then select ButtonDownFcn. GUIDE sets this property to the appropriate string and adds the callback to the code file the next time you save the GUI. Alternatively, you can set this property to the string %automatic. The next time you save the GUI, GUIDE sets this property to the appropriate string and adds the callback to the code file.

Use the Callback property to specify the callback routine that executes when you activate the enabled uicontrol (e.g., click a push button).

Callback

string or function handle (GUIDE sets this property)

Control action. A function that executes whenever you activate the uicontrol object (e.g., when you click on a push button or move a slider). Define this function as a string that is a valid MATLAB expression or the name of a code file. The expression executes in the MATLAB workspace.

See Callbacks for Specific Components for examples of callback functions for each style of component.

CData

matrix

Truecolor image displayed on control. A three-dimensional matrix of RGB values that defines a truecolor image displayed on a control, which must be a push button or toggle button. Each value must be between 0.0 and 1.0. Setting CData on a radio button or checkbox will replace the default CData on these controls. The control will continue to work as expected, but its state is not reflected by its appearance when clicked.

For push buttons and toggle buttons, CData overlaps the String. In the case of radio buttons and checkboxes, CData takes precedence over String and, depending on its size, it can displace the text.

Setting CData to [] restores the default CData for radio buttons and checkboxes.

Children

matrix

The empty matrix; uicontrol objects have no children.

Clipping

{on} | off

This property has no effect on uicontrol objects.

CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB creates a uicontrol object. MATLAB sets all property values for the uicontrol before executing the CreateFcn callback so these values are available to the callback. Within the function, use gcbo to get the handle of the uicontrol being created.

Setting this property on an existing uicontrol object has no effect.

You can define a default CreateFcn callback for all new uicontrols. This default applies unless you override it by specifying a different CreateFcn callback when you call uicontrol. For example, the code

set(0,'DefaultUicontrolCreateFcn','set(gcbo,...
    ''BackgroundColor'',''white'')')

creates a default CreateFcn callback that runs whenever you create a new uicontrol. It sets the default background color of all new uicontrols.

To override this default and create a uicontrol whose BackgroundColor is set to a different value, call uicontrol with code similar to

hpt = uicontrol(...,'CreateFcn','set(gcbo,...
''BackgroundColor'',''blue'')')

    Note   To override a default CreateFcn callback you must provide a new callback and not just provide different values for the specified properties. This is because the CreateFcn callback runs after the property values are set, and can override property values you have set explicitly in the uicontrol call. In the example above, if instead of redefining the CreateFcn property for this uicontrol, you had explicitly set BackgroundColor to blue, the default CreateFcn callback would have set BackgroundColor back to the default, i.e., white.

Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. The act of copying the uicontrol object fires the CreateFcn repeatedly, which raises a series of error messages after exceeding the root object's RecursionLimit property.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

DeleteFcn

string or function handle

Delete uicontrol callback routine. A callback routine that executes when you delete the uicontrol object (e.g., when you issue a delete command or clear the figure containing the uicontrol). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine.

The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

Enable

{on} | inactive | off

Enable or disable the uicontrol. This property controls how uicontrols respond to mouse button clicks, including which callback routines execute.

  • on – The uicontrol is operational (the default).

  • inactive – The uicontrol is not operational, but looks the same as when Enable is on.

  • off – The uicontrol is not operational and its image (set by the Cdata property) is grayed out.

When you left-click on a uicontrol whose Enable property is on, MATLAB performs these actions in this order:

  1. Sets the figure SelectionType property.

  2. Executes the uicontrol Callback routine, if any. (Static text components do not use callbacks.)

  3. Does not set the figure CurrentPoint property and does not execute either the uicontrol ButtonDownFcn or the figure WindowButtonDownFcn callback.

Single-clicking or double-clicking an enabled uicontrol with the left mouse button sets the figure SelectionType property to normal, unless the uicontrol Style is listbox. For list boxes, double-clicking sets the figure SelectionType property to open on the second of the two clicks, enabling the list box callback to detect a set of multiple choices.

When you left-click on a uicontrol whose Enable property is off or inactive, or when you right-click a uicontrol whose Enable property has any value, MATLAB performs these actions in this order:

  1. Sets the figure SelectionType property.

  2. Sets the figure CurrentPoint property.

  3. Executes the figure WindowButtonDownFcn callback, if provided.

  4. Executes the uicontrol ButtonDownFcn callback, if provided.

Extent

position rectangle (read only)

Size of uicontrol character string. A four-element vector that defines the size and position of the character string used to label the uicontrol. It has the form:

[0,0,width,height]

The first two elements are always zero. width and height are the dimensions of the rectangle. All measurements are in units specified by the Units property.

Since the Extent property is defined in the same units as the uicontrol itself, you can use this property to determine proper sizing for the uicontrol with regard to its label. Do this by

  • Defining the String property and selecting the font using the relevant properties.

  • Getting the value of the Extent property.

  • Defining the width and height of the Position property to be somewhat larger than the width and height of the Extent.

For multiline strings, the Extent rectangle encompasses all the lines of text. For single line strings, the height element of the Extent property returned always indicates the height of a single line, and its width element always indicates the width of the longest line, even if the string wraps when displayed on the control. Edit boxes are considered multiline if Max - Min > 1.

FontAngle

{normal} | italic | oblique

Character slant. MATLAB uses this property to select a font from those available on your particular system. Setting this property to italic or oblique selects a slanted version of the font, when it is available on your system.

FontName

string

Font family. The name of the font in which to display the String. To display and print properly, this must be a font that your system supports. The default font is system dependent.

    Note:   MATLAB GUIs do not support the Marlett and Symbol font families.

To use a fixed-width font that looks good in any locale (and displays properly in Japan, where multibyte character sets are used), set FontName to the string FixedWidth (this string value is case sensitive):

set(uicontrol_handle, 'FontName', 'FixedWidth')

This parameter value eliminates the need to hard code the name of a fixed-width font, which may not display text properly on systems that do not use ASCII character encoding (such as in Japan). A properly written MATLAB application that needs to use a fixed-width font should set FontName to FixedWidth and rely on the root FixedWidthFontName property to be set correctly in the end user's environment.

End users can adapt a MATLAB application to different locales or personal environments by setting the root FixedWidthFontName property to the appropriate value for that locale from startup.m. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

    Tip   To determine what fonts exist on your system (which can differ from the GUI user's system), use the uisetfont GUI to select a font and return its name and other characteristics in a MATLAB structure.

FontSize

size in FontUnits

Font size. A number specifying the size of the font in which to display the String, in units determined by the FontUnits property. The default point size is system dependent.

FontUnits

{points} | normalized | inches |
centimeters | pixels

Font size units. This property determines the units used by the FontSize property. Normalized units interpret FontSize as a fraction of the height of the uicontrol. When you resize the uicontrol, MATLAB modifies the screen FontSize accordingly. pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).

FontWeight

light | {normal} | demi | bold

Weight of text characters. MATLAB uses this property to select a font from those available on your particular system. Setting this property to bold causes MATLAB to use a bold version of the font, when it is available on your system.

ForegroundColor

ColorSpec

Color of text. This property determines the color of the text defined for the String property (the uicontrol label). Specify a color using a three-element RGB vector or one of the MATLAB predefined names. The default text color is black. See ColorSpec for more information on specifying color.

    Note:   If you change the ForegroundColor for a uicontrol listbox, MATLAB uses that color for all listbox items except selected listbox items. For selected items MATLAB uses a color that ensures good contrast between the text of selected items and the color that indicates a selection.

HandleVisibility

{on} | callback | off

Control access to object's handle. This property determines when an object's handle is visible in its parent's list of children. When a handle is not visible in its parent's list of children, it is not returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. Neither is the handle visible in the parent figure's CurrentObject property. Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

  • Handles are always visible when HandleVisibility is on.

  • Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.

  • Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.

You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings. This does not affect the values of the HandleVisibility properties.

    Note   Radio buttons and toggle buttons that are managed by a uibuttongroup should not be accessed outside the button group. Set the HandleVisibility of such radio buttons and toggle buttons to off to prevent inadvertent access.

HitTest

{on} | off

Selectable by mouse click. This property has no effect on uicontrol objects.

    Note:   Use of the uicontrol HitTest property is not recommended. This property might be removed in a future release.

HorizontalAlignment

left | {center} | right

Horizontal alignment of label string. This property determines the justification of the text defined for the String property (the uicontrol label):

  • left — Text is left justified with respect to the uicontrol.

  • center — Text is centered with respect to the uicontrol.

  • right — Text is right justified with respect to the uicontrol.

The contents of edit and text uicontrols are always vertically aligned to the top of the rectangle.

    Note:   On Microsoft® Windows® systems, although this property can be specified on all uicontrols, it affects only edit and text uicontrols.

Interruptible

off | {on}

Callback routine interruption

Controls whether MATLAB can interrupt an object's callback function when subsequent callbacks attempt to interrupt it.

For user interface objects, the Interruptible property affects the callbacks for these properties only:

  • ButtonDownFcn

  • KeyPressFcn

  • KeyReleaseFcn

  • WindowButtonDownFcn

  • WindowButtonMotionFcn

  • WindowButtonUpFcn

  • WindowKeyPressFcn

  • WindowKeyReleaseFcn

  • WindowScrollWheelFcn

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. MATLAB handles both callbacks based on the Interruptible property of the object of the running callback.

When the Interruptible property is set to:

  • 'off', MATLAB finishes execution of the running callback without any interruptions

  • 'on', these conditions apply:

    • If there is a drawnow, figure, getframe, waitfor, or pause command in the running callback, then MATLAB executes the interrupting callbacks which are already in the queue and returns to finish execution of the current callback.

    • If one of the above functions is not in the running callback, then MATLAB finishes execution of the current callback without any interruption.

The BusyAction property of the object of interrupting callback determines whether the callback should be ignored or should be put in the queue.

Setting the Interruptible property to on (default), allows a callback from other user interface objects to interrupt callback functions originating from this object.

    Note:   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 may be changed as another callback is executed.

After the function that interrupts a callback completes, the callback resumes execution where it halted when interrupted. For more information, see Control Callback Execution and Interruption.

    Note:   If the interrupting callback is a DeleteFcnor CreateFcn callback, or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement. An object's ButtonDownFcn or Callback routine is processed according to the rules described previously in this section.

KeyPressFcn

string or function handle

Key press callback function. A callback routine invoked by a key press when the callback's uicontrol object has focus. Focus is denoted by a border or a dotted border, respectively, in UNIX® and Microsoft Windows. If no uicontrol has focus, the figure's key press callback function, if any, is invoked. KeyPressFcn can be a function handle, the name of a code file, or any legal MATLAB expression.

If the specified value is the name of a code file, the callback routine can query the figure's CurrentCharacter property to determine what particular key was pressed and thereby limit the callback execution to specific keys.

If the specified value is a function handle, the callback routine can retrieve information about the key that was pressed from its event data structure argument.

Event Data Structure Field

Description

Examples:

a

=

Shift

Shift/a

Character

Character interpretation of the key that was pressed.

'a'

'='

''

'A'

Modifier

Current modifier, such as 'control', or an empty cell array if there is no modifier

{1x0 cell}

{1x0 cell}

{'shift'}

{'shift'}

Key

Name of the key that was pressed.

'a'

'equal'

'shift'

'a'

See Function Handle Callbacks for information on how to use function handles to define the callback function.

ListboxTop

scalar

Index of top-most string displayed in list box. This property applies only to the listbox style of uicontrol. It specifies which string appears in the top-most position in a list box that is not large enough to display all list entries. ListboxTop is an index into the array of strings defined by the String property and must have a value between 1 and the number of strings. Noninteger values are fixed to the next lowest integer.

Max

scalar

Maximum value. This property specifies the largest value allowed for the Value property. Different styles of uicontrols interpret Max differently:

  • Check boxes – Max is the setting of the Value property while the check box is selected.

  • Editable text – The Value property does not apply. If Max - Min > 1, then editable text boxes accept multiline input. If Max - Min <= 1, then editable text boxes accept only single line input. The absolute values of Max and Min have no effect on the number of lines an edit box can contain; a multiline edit box can contain any number of lines.

  • List boxes – If Max - Min > 1, then list boxes allow multiple item selection. If Max - Min <= 1, then list boxes do not allow multiple item selection. When they do, Value can be a vector of indices.

  • Radio buttons – Max is the setting of the Value property when the radio button is selected.

  • Sliders – Max is the maximum slider value and must be greater than the Min property. The default is 1.

  • Toggle buttons – Max is the value of the Value property when the toggle button is selected. The default is 1.

  • Pop-up menus, push buttons, and static text do not use the Max property.

Min

scalar

Minimum value. This property specifies the smallest value allowed for the Value property. Different styles of uicontrols interpret Min differently:

  • Check boxes – Min is the setting of the Value property while the check box is not selected.

  • Editable text – The Value property does not apply. If Max - Min > 1, then editable text boxes accept multiline input. If Max - Min <= 1, then editable text boxes accept only single line input. The absolute values of Max and Min have no effect on the number of lines an edit box can contain; a multiline edit box can contain any number of lines.

  • List boxes – If Max - Min > 1, then list boxes allow multiple item selection. If Max - Min <= 1, then list boxes allow only single item selection. When they do, Value can be a vector of indices.

  • Radio buttons – Min is the setting of the Value property when the radio button is not selected.

  • Sliders – Min is the minimum slider value and must be less than Max. The default is 0.

  • Toggle buttons – Min is the value of the Value property when the toggle button is not selected. The default is 0.

  • Pop-up menus, push buttons, and static text do not use the Min property.

Parent

handle

Uicontrol parent. The handle of the uicontrol's parent object. You can move a uicontrol object to another figure, uipanel, or uibuttongroup by setting this property to the handle of the new parent.

Position

position rectangle

Size and location of uicontrol. The rectangle defined by this property specifies the size and location of the control within the parent figure window, uipanel, or uibuttongroup. Specify Position as

[left bottom width height]

left and bottom are the distance from the lower-left corner of the parent object to the lower-left corner of the uicontrol object. width and height are the dimensions of the uicontrol rectangle. All measurements are in units specified by the Units property.

On Microsoft Windows systems, the height of pop-up menus is automatically determined by the size of the font. The value you specify for the height of the Position property has no effect.

The width and height values determine the orientation of sliders. If width is greater than height, then the slider is oriented horizontally, If height is greater than width, then the slider is oriented vertically.

    Note:   The height of a pop-up menu is determined by the font size. The height you set in the position vector is ignored. The height element of the position vector is not changed.

    On Mac platforms, the height of a horizontal slider is constrained. If the height you set in the position vector exceeds this constraint, the displayed height of the slider is the maximum allowed. The height element of the position vector is not changed.

Selected

on | {off}

Is object selected. When this property is on, MATLAB displays selection handles if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.

    Note:   Use of the uicontrol Selected property is not recommended. This property might be removed in a future release.

SelectionHighlight

{on} | off

Object highlight when selected. When the Selected property is on, MATLAB indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is off, MATLAB does not draw the handles.

    Note:   Use of the uicontrol SelectionHighlight property is not recommended. This property might be removed in a future release.

SliderStep

[minor_step major_step]

Slider step size, a two-element vector of positive values that indicates the size of the major and minor steps as a percent change in slider value. Both steps should be greater than 1e-6, and minor_step should be less than or equal to major_step. The slider Value changes up or down by minor_step when you click the arrow button, and up or down by major_step when you click the slider trough, also called the channel.

The actual step size is a function of the specified SliderStep and the total slider range (Max - Min). The default, [0.01 0.10], provides a 1 percent change for clicks on the arrow button and a 10 percent change for clicks in the trough.

For example, if you create the following slider,

uicontrol('Style','slider','Min',1,'Max',7,...
          'Value',2,'SliderStep',[0.1 0.6])

clicking an arrow button moves the thumb indicator toward it by minor_step*(max-min):

0.1*(7-1)
ans =
     0.6000

Clicking the trough moves the thumb indicator toward the mouse pointer by major_step*(max-min):

0.6*(7-1)
ans =
     3.6000

If clicking moves the slider to a value outside the range, the thumb indicator moves only to the Max or Min value.

As major_step increases, the slider thumb indicator grows longer. When major_step is 1, the thumb is half as long as the trough. When major_step is greater than 1, the thumb continues to grow, slowly approaching the full length of the trough.

See also the Max, Min, and Value properties.

String

string

Uicontrol label, list box items, pop-up menu choices.

For check boxes, editable text, push buttons, radio buttons, static text, and toggle buttons, the text displayed on the object. For list boxes and pop-up menus, the set of entries or items displayed in the object.

    Note   If you specify a numerical value for String, MATLAB converts it to char but the result may not be what you expect. If you have numerical data, you should first convert it to a string, e.g., using num2str, before assigning it to the String property.

For uicontrol objects that display only one line of text (check box, push button, radio button, toggle button), if the string value is specified as a cell array of strings or padded string matrix, only the first string of a cell array or of a padded string matrix is displayed; the rest are ignored. Vertical slash ('|') characters are not interpreted as line breaks and instead show up in the text displayed in the uicontrol.

For multiple line editable text or static text controls, line breaks occur between each row of the string matrix, and each cell of a cell array of strings. Vertical slash ('|') characters and \n characters are not interpreted as line breaks, and instead show up in the text displayed in the uicontrol. Text in edit text and static text boxes is always vertically top-aligned. For editable text, the String property value is set to the string entered by the user when the control loses focus. The String property for static text can only be set programmatically (or when authoring a GUI in GUIDE).

To place multiple items on a list box or pop-up menu, you can specify the items in any of the formats shown in the following table.

String Property FormatExample
Cell array of strings{'one' 'two' 'three'}
Padded string column matrix['one  ';'two  ';'three']
String vector using vertical slash (|) as a line separator['one|two|three']

If you specify a component width that is too small to accommodate one or more of the specified strings, MATLAB truncates those strings with an ellipsis. Use the Value property to set the index of the initial item selected.

For check boxes, push buttons, radio buttons, toggle buttons, and the selected item in popup menus, when the specified text is clipped because it is too long for the uicontrol, an ellipsis (...) is appended to the text in the active GUI to indicate that it has been clipped.

For push buttons and toggle buttons, CData overlaps the String. In the case of radio buttons and checkboxes, CData takes precedence over String and, depending on its size, can displace the text.

    Reserved Words   There are three reserved words: default, remove, factory (case sensitive). If you want to use one of these reserved words in the String property, you must precede it with a backslash ('\') character. For example,

     h = uicontrol('Style','edit','String','\default');
Style

{pushbutton} | togglebutton | radiobutton | checkbox | edit | text | slider | frame | listbox | popupmenu

Style of uicontrol object to create. The Style property specifies the kind of uicontrol to create. See the uicontrol Description section for information on each type.

Tag

string (GUIDE sets this property)

User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.

TooltipString

string

Content of tooltip for object. The TooltipString property specifies the text of the tooltip associated with the uicontrol. When the user moves the mouse pointer over the control and leaves it there, the tooltip is displayed.

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 value. For example:

h = uicontrol('Style','pushbutton');
s = sprintf('Button tooltip line 1\nButton tooltip line 2');
set(h,'TooltipString',s)
Type

string (read only)

Class of graphics object. For uicontrol objects, Type is always the string 'uicontrol'.

UIContextMenu

handle

Associate a context menu with uicontrol. Assign this property the handle of a uicontextmenu object. MATLAB displays the context menu whenever you right-click over the uicontrol. Use the uicontextmenu function to create the context menu.

Units

{pixels} | normalized | inches | centimeters | points | characters (GUIDE default: normalized)

Units of measurement. MATLAB uses these units to interpret the Extent and Position properties. All units are measured from the lower-left corner of the parent object.

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

  • pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).

  • Character units are characters using the default system font; the width of one character is the width of the letter x, the height of one character is the distance between the baselines of two lines of text.

If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.

UserData

matrix

User-specified data. Any data you want to associate with the uicontrol object. MATLAB does not use this data, but you can access it using set and get.

Value

scalar or vector

Current value of uicontrol. The uicontrol style determines the possible values this property can have:

  • Check boxes set Value to Max when they are on (when selected) and Min when off (not selected).

  • List boxes set Value to a vector of indices corresponding to the selected list entries, where 1 corresponds to the first item in the list.

  • Pop-up menus set Value to the index of the item selected, where 1 corresponds to the first item in the menu. The Examples section shows how to use the Value property to determine which item has been selected.

  • Radio buttons set Value to Max when they are on (when selected) and Min when off (not selected).

  • Sliders set Value to the number indicated by the slider bar.

  • Toggle buttons set Value to Max when they are down (selected) and Min when up (not selected).

  • Editable text, push buttons, and static text do not set this property.

Set the Value property either interactively with the mouse or through a call to the set function. The display reflects changes made to Value.

Visible

{on} | off

Uicontrol visibility. By default, all uicontrols are visible. When set to off, the uicontrol is not visible, but still exists and you can query and set its properties.

    Note   Setting Visible to off for uicontrols that are not displayed initially in the GUI, can result in faster startup time for the GUI.

Was this topic helpful?