# uicontrol

## Purpose

Create user interface control object.

## Synopsis

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

## Description

`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 `uicontro`l 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.

    ## See Also

        uimenu

    (c) Copyright 1994 by The MathWorks, Inc.