# uicontrol

create a Graphic User Interface object

## Calling Sequence

                h = uicontrol(PropertyName,PropertyValue,...)
                h = uicontrol(parent,PropertyName,PropertyValue,...)
                h = uicontrol(uich)

## Description

This routine creates an object in a figure.

If the handle of the figure is given (as the first parameter), the uicontrol is created in this figure. If no handle is given, the uicontrol is created in the current figure (which may be obtained with a call to `gcf()`). If there is no current figure, then one is created before the creation of the uicontrol.

Then when the control is created, the properties given as parameters are set with the corresponding values. It is equivalent to create the uicontrol, and then set its properties with the `set()` command. Nevertheless, it generally more efficient to set the properties in the call to `uicontrol()`. Scilab and all the graphic objects communicate through the property mechanism. Thus, to create adapted uicontrol, one has to know the use of the property fields.

`h = uicontrol(PropertyName, PropertyValue,...)` creates an uicontrol and assigns the specified properties and values to it. It assigns the default values to any properties you do not specify. The default uicontrol style is a "Pushbutton". The default parent is the current figure. See the Properties section for information about these and other properties.

`h = uicontrol(parent, PropertyName, PropertyValue,...)` creates a uicontrol in the object specified by the handle, parent. If you also specify a different value for the Parent property, the value of the Parent property takes precedence. parent is the handle of a figure.

`h = uicontrol(uich)` gives focus to the uicontrol specified by uich.

All available properties and their description are given in the uicontrol properties help page.

Uicontrols rendering and properties display can be customized using Console properties.

## Available styles

The available styles are listed below. The `style` of an `uicontrol` must be set at creation using the `"Style"` property and can not be changed once the `uicontrol` is created.

- Checkbox: a button with two states (Used for multiple independent choices).

- Edit: an editable string zone.

- Frame: a container for other uicontrols.

- Image: a component where a specified image is displayed.

- Layer: a container for `frame` style uicontrols enbaling to switch between them programmatically using the `value` property.

- Listbox: a control representing a list of items that can be scrolled. The items can be selected with the mouse.

- Popupmenu: a button which make a menu appear when clicked.

- Pushbutton: (default style) a rectangular button generally used to run a callback.

- Radiobutton: a button with two states. RadioButtons are intended to be mutually exclusive.

  Your code must implement mutually exclusive behavior if you do not use groups (See `GroupName` property in uicontrol properties).

- Slider: a scale control, that is a slider used to set values between in range with the mouse.

- Spinner: a component which enables the user to select/edit a value between bounds with a fixed step.

- Tab: a container for `frame` style uicontrols enabling to switch between them by cliking on a tab with a given title and/or icon.

  The font related properties set on the frame will be used for the tab label.

- Table: an editable table.

- Text: a text control (generally static).

## Examples

    f=figure();
    // create a figure
    h=uicontrol(f,'style','listbox', ...
     'position', [10 10 150 160]);
    // create a listbox
    set(h, 'string', "item 1|item 2|item3");
    // fill the list
    set(h, 'value', [1 3]);
    // select item 1 and 3 in the list
    close(f);
    // close the figure

uicontrol function can be overloaded

    // create a mlist
    mymlist = mlist(['objid','A','B'],[],[]);

    // overload set / get for objid
    function result = %objid_uicontrol(varargin)
      // res = uicontrol(mymlist,'A');
      obj_tmp   = varargin(1);
      field_tmp = varargin(2);
      mprintf('uicontrol on an object of type %s, field = %s\n', typeof(obj_tmp), field_tmp);
      result = %t;
    endfunction

    res = uicontrol(mymlist,'property');

Pushbuttons or Text can have LaTeX or MathML label

    // LaTeX
    f=figure();
    h=uicontrol(f,"style","pushbutton","string","$x^2$");
    // MathML
    hh=uicontrol(f,"style","pushbutton","string","<msup><mi>x</mi><mn>2</mn></msup>");
    hh.Position = h.Position + [50, 0, 0, 0];
    // Text
    h=uicontrol(f,"Style","text","string","$\Gamma(s)=\int_0^\infty t^{s-1}\mathrm{e}^{-t}\,\mathrm{d}t$");
    // If it is too little
    h.fontsize=20

    // Include an editable table into a figure:
    // Building a table of data:
    params = [" " "Country" "Population [Mh]" "Temp.[Â°C]" ];
    towns = ["Mexico" "Paris" "Tokyo" "Singapour"]';
    country = ["Mexico" "France" "Japan" "Singapour"]';
    pop  = string([22.41 11.77 33.41 4.24]');
    temp = string([26 19 22 17]');
    table = [params; [ towns country pop temp ]]

    f = gcf();
    clf
    as = f.axes_size;  // [width height]
    ut = uicontrol("style","table",..
                   "string",table,..
                   "position",[5 as(2)-100 300 87],.. // => @top left corner of figure
                   "tooltipstring","Data from majors towns")

    // Modify by hand some values in the table. Then get them back from the ui:
    matrix(ut.string,size(table))

## See Also

- uicontrol_properties
- figure
- set
- get
- uimenu
- LaTeX and MathML

## History

5.5.0

New styles added:

- Tab
- Spinner
- Layer

Uicontrols rendering is now based on operating system look and feel (See console properties).

Uicontrols handles display is now limited to properties used by Java rendering (See console properties).