uicontrol

Synopsis

uicontrol('PropertyName',PropertyValue,...)
h = uicontrol(...)

uicontrol('PropertyName',PropertyValue,...) is a uicontrol object creation function that accepts property name/property value pairs as input arguments. These properties are described under "Object Properties." You can also set and query property values after creating the object by using the set and get functions.

uicontrols, or user interface controls, are useful in implementing graphical user interfaces. When selected, most uicontrol objects perform a predefined action. MATLAB supports seven styles of uicontrols, each of which is suited for a different purpose:

Push buttons

Check boxes

Popup menus

Radio buttons

Sliders

Editable text

Frames
Push buttons are analogous to the buttons on a telephone - they generate an action with each press, but do not remain in a pressed state. To activate a push button, press and release the mouse button on the object. Push buttons are useful when the action you want to perform is not related to any other action executable by the user interface (for example, a Quit button).

Check boxes also generate an action when pressed, but remain in a pressed state until pressed a second time. These objects are useful when providing the user with a number of independent choices, each toggling between two states. To activate a check box, press and release the mouse button on the object. The state of the objects is indicated on the display.

Popup menus display a list of choices when you press them. When not activated, they display a single button with text indicating their current setting. Popup menus are useful when you want to provide users with a number of mutually exclusive choices, but do not want to take up the amount of space that a series of radio buttons require.

Radio buttons are similar to check boxes, but are intended to be mutually exclusive (i.e., only one is in a pressed state at any given time). To activate a radio button, press and release the mouse button on the object. The state of the objects is indicated on the display. Note that your code must implement the mutually exclusive behavior of radio buttons.

Sliders are intended to accept numeric input by allowing the user to move a sliding bar (by pressing the mouse button and dragging the mouse over the bar) within a rectangle. The location of the bar indicates a numeric value that is selected by releasing the mouse button. You can set the minimum, maximum, and initial values of the slider.

Editable text are boxes containing editable text. After typing in the desired text, press Control-Return or move the pointer off the object to execute its Callback. Use editable text when you want to input text.

Frames are boxes that enclose regions of a figure window. Frames can make a user interface easier to understand by grouping related controls.

These objects are children of figures and are therefore independent of axes.

h = uicontrol(...) returns the handle of a uicontrol object.

Object Properties

This section lists property names along with the type of values each accepts.

BackGroundColor: Object color.

A three-element RGB vector or one of MATLAB's predefined names, specifying the color used to fill the rectangle defined by the control. The default color is light gray. See the ColorSpec reference page for more information on specifying color.

ButtonDownFcn: Callback string, object selection.

Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the eval function to execute the specified function. Initially the empty matrix.

CallBack: Control action.

Any legal MATLAB expression, including the name of an M-file or function. When you activate the uicontrol object, the string is passed to the eval function to execute the Callback.

Children: Children of uicontrol.

Always the empty matrix; uicontrol objects have no children.

Clipping: Clipping mode.

on (Default.) Any portion of the control outside the axes rectangle is not displayed.

off The control is not clipped.

ForeGroundColor: Text color.

A three-element RGB vector or one of MATLAB's predefined names, specifying the color of the text on the uicontrol. The default text color is black. See the ColorSpec reference page for more information on specifying color.

HorizontalAlignment: Horizontal alignment of label string.

left Text is left-justified with respect to the uicontrol.

center (Default.) Text is centered with respect to the uicontrol.

right Text is right-justified with respect to the uicontrol.

Interruptible: Callback interruptibility.

yes The control callbacks (ButtonDownFcn and Callback) are interruptible by other callbacks.

no (Default.) The control callbacks are not interruptible.

Max: Maximum value.

The largest value allowed for the Value property. For radio buttons and check boxes, which operate as on/off switches, this represents the setting of Value while the uicontrol is in the on position. For popup menus, this property specifies the maximum number of choices you can define on the menu. For sliders, this property is the largest value you can select. The default maximum is 1.

Min: Minimum value.

The smallest value allowed for the Value property. For radio buttons and check boxes, which operate as on/off switches, this represents the setting of Value while the uicontrol is in the off position. For sliders, this property is the minimum value that you can select. The default minimum is 0.

Parent: Handle of the uicontrol's parent object.

A read-only property that contains the handle of the uicontrol's parent object. The parent of a uicontrol object is the figure in which it is displayed.

Position: Size and location of uicontrol.

A four-element read-only vector, [left,bottom,width,height], that defines the size and position of the uicontrol. left and bottom are the distance from the lower-left corner of the figure window to the lower-left corner of the uicontrol object. width and height are the dimensions of the control rectangle. All measurements are in units specified by the Units property.

String: uicontrol label.

A string specifying the label on push buttons, radio buttons, check boxes, and popup menus. For multiple items on a popup menu or multiple lines on an editable text object, enter a string, then |, then the next string, and so on. Place quotes around the entire list of strings (not each individual string). For editable text, this property is set to the string typed in by the user.

Style: Type of uicontrol object.

pushbutton (Default.) Push button.

radio Radio button.

checkbox Check box.

slider Slider.

edit Editable text.

popup Popup menu.

Type: Type of graphics object.

A read-only string; always 'uicontrol' for a uicontrol object.

Units: Unit of measurement for screen display.

pixels (Default.) Screen pixels.

normalized Normalized coordinates, where the lower-left corner of the figure maps to (0,0) and the upper-right corner to (1.0,1.0).

inches Inches.

cent Centimeters.

points Points. Each point is equivalent to 1/72 of an inch.

This property affects the Position properties. All units are measured from the lower-left corner of the figure window. 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: User-specified data.

Any matrix you want to associate with the uicontrol object. The object does not use this data, but you can retrieve it using the get command.

Value: Current value of control.

Scalar. Legal values depend on the type of control:

Radio buttons and check boxes set Value to Max (usually 1) when they are on (when the button is pressed) and Min (usually 0) when off (not pressed)

Sliders set Value to the number indicated by the slider bar, relative to the range established by Min and Max.

Popup menus set Value to the index of the item selected. The "Examples" section shows how to use the Value property to determine which item has been selected.

Push buttons and editable text objects 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: uicontrol visibility.

on (Default.) uicontrol is visible on the screen.

off uicontrol is not visible on the screen.

Examples

The following statement creates a push button that clears the current axes when pressed:

h = uicontrol('Style','Pushbutton','Position',...
    [20 150 100 70], 'Callback','cla','String','Clear');

You can create a uicontrol object that changes figure colormaps by specifying a popup menu and supplying an M-file as the object's Callback:

hpop = uicontrol('Style','Popup','String',...
       'hsv| hot|cool|gray','Position',[20 320 100 50],...
       'Callback','setmap')

This call to uicontrol defines four individual choices in the menu: hsv, hot, cool, and gray. You specify these choices with the String property, separating each with the "|" character.

The Callback, in this case setmap, is the name of an M-file that defines a more complicated set of instructions than a single MATLAB command:

val = get(hpop,'Value');
if val == 1
    colormap(hsv)
elseif val == 2
    colormap(hot)
elseif val == 3
    colormap(cool)
elseif val == 4
    colormap(gray)
end

The Value property contains a number that indicates which choice you selected. The choices are numbered sequentially from one to four. The setmap M-file can get and then test the contents of the Value property to determine what action to take.

uicontrol

Purpose

Synopsis

Description

Object Properties

Examples

See Also