35.3 UI Elements

The ui* series of functions work best with the qt graphics toolkit, although some functionality is available with the fltk toolkit. There is no support for the gnuplot toolkit.

: uipanel (property, value, …)

: uipanel (parent, property, value, …)

: hui = uipanel (…)

Create a uipanel object.

uipanels are used as containers to group other uicontrol objects.

If parent is omitted then a uipanel for the current figure is created. If no figure is available, a new figure is created first.

If parent is given then a uipanel relative to parent is created.

Any provided property value pairs will override the default values of the created uipanel object.

The full list of properties is documented at Uipanel Properties.

The optional return value hui is a graphics handle to the created uipanel object.

Examples:

## create figure and panel on it
f = figure;
p = uipanel ("title", "Panel Title", "position", [.25 .25 .5 .5]);

## add two buttons to the panel
b1 = uicontrol ("parent", p, "string", "A Button", ...
                "position", [18 10 150 36]);
b2 = uicontrol ("parent", p, "string", "Another Button", ...
                "position",[18 60 150 36]);

See also: figure, uicontrol.

: hui = uibuttongroup (property, value, …)

: hui = uibuttongroup (parent, property, value, …)

: uibuttongroup (h)

Create a uibuttongroup object and return a handle to it.

A uibuttongroup is used to group uicontrol objects.

If parent is omitted then a uibuttongroup for the current figure is created. If no figure is available, a new figure is created first.

If parent is given then a uibuttongroup relative to parent is created.

Any provided property value pairs will override the default values of the created uibuttongroup object.

The full list of properties is documented at Uibuttongroup Properties.

Examples:

## Create figure and panel on it
f = figure;
## Create a button group
gp = uibuttongroup (f, "Position", [ 0 0.5 1 1])
## Create a buttons in the group
b1 = uicontrol (gp, "style", "radiobutton", ...
                "string", "Choice 1", ...
                "Position", [ 10 150 100 50 ]);
b2 = uicontrol (gp, "style", "radiobutton", ...
                "string", "Choice 2", ...
                "Position", [ 10 50 100 30 ]);
## Create a button not in the group
b3 = uicontrol (f, "style", "radiobutton", ...
                "string", "Not in the group", ...
                "Position", [ 10 50 100 50 ]);

When called with a single argument h which is a handle to an existing uibuttongroup object, switch the focus to the specified uibuttongroup. This functionality is not currently implemented.

See also: figure, uipanel.

: hui = uicontrol (property, value, …)

: hui = uicontrol (parent, property, value, …)

: uicontrol (h)

Create a uicontrol object and return a handle to it.

A uicontrol object is used to create simple interactive controls such as push buttons, checkboxes, edit and list controls.

If parent is omitted then a uicontrol for the current figure is created. If no figure is available, a new figure is created first.

If parent is given then a uicontrol relative to parent is created.

Any provided property value pairs will override the default values of the created uicontrol object.

The full list of properties is documented at Uicontrol Properties.

The type of uicontrol created is specified by the style property. If no style property is provided, a push button will be created.

Valid styles for uicontrol are:

"checkbox"

Create a checkbox control that allows user on/off selection.

"edit"

Create an edit control that allows user input of single or multiple lines of text.

"listbox"

Create a listbox control that displays a list of items and allows user selection of single or multiple items.

"popupmenu"

Create a popupmenu control that displays a list of options that can be selected when the user clicks on the control.

"pushbutton"

Create a push button control that allows user to press to cause an action.

"radiobutton"

Create a radio button control intended to be used for mutually exclusive input in a group of radiobutton controls.

"slider"

Create a slider control that allows user selection from a range of values by sliding knob on the control.

"text"

Create a static text control to display single or multiple lines of text.

"togglebutton"

Create a toggle button control that appears like a push button but allows the user to select between two states.

Examples:

## Create figure and panel on it
f = figure;
## Create a button (default style)
b1 = uicontrol (f, "string", "A Button", ...
                   "position", [10 10 150 40]);
## Create an edit control
e1 = uicontrol (f, "style", "edit", "string", "editable text", ...
                   "position", [10 60 300 40]);
## Create a checkbox
c1 = uicontrol (f, "style", "checkbox", "string", "a checkbox", ...
                   "position", [10 120 150 40]);

When called with a single argument h which is a handle to an existing uicontrol object, switch the keyboard focus to the specified uicontrol. As a result, the uicontrol object will receive keyboard events that can be processed using the "keypressfcn" callback.

See also: figure, uipanel.

: hui = uitable (property, value, …)

: hui = uitable (parent, property, value, …)

Create a uitable object and return a handle to it.

A uitable object is used to show tables of data in a figure window.

If parent is omitted then a uitable for the current figure is created. If no figure is available, a new figure is created first.

If parent is given then a uitable relative to parent is created.

Any provided property value pairs will override the default values of the created uitable object.

The full list of properties is documented at Uitable Properties.

Examples:

## Create figure and place a table on it
f = figure ();
m = magic (8);
t = uitable (f, "Data", m, "ColumnWidth", { 40 });


## Create a table with labeled rows and columns
f = figure ();
d = reshape (1:9, [3, 3]);
row_names = { "Row1", "Row2", "Row3" };
col_names = { "Col1", "Col2", "Col3" };
t = uitable (f, "Data", d, ...
             "RowName", row_names, "ColumnName", col_names);

p = get (t, "Position");
e = get (t, "Extent");
p(3:4) = e(3:4);
set (t, "Position", p);


## Long demo with callbacks
function uitable_demo ()
  f = figure ("Name", "uitable Demo", "Menu", "none", ...
              "Position", [10 10 1000 680]);

  ## A basic example
  d = { "char"   , "A string";
        "double" , 12.3456789;
        "complex", 1+2i;
        "bool"   , true;
        "single" , single (12.3456789);
        "int8"   , int8 (-128);
        "uint8"  , uint8 (128);
        "int16"  , int16 (-32768);
        "uint16" , uint16 (32768);
        "int32"  , int32 (-2147483648);
        "uint32" , uint32 (2147483648);
        "int64"  , int64 (-2147483649);
        "uint64" , uint64 (2147843649)};

  popup_options = {"A", "B", "C", "D", "E"};

  columnformat_options = { "[]", "char", "pop-up", "numeric", ...
                           "short", "short e", "short eng", ...
                           "short g", "long", "long e", ...
                           "long eng", "long g", "bank", "+", ...
                           "rat", "logical"};
  columnformat_values = columnformat_options;
  columnformat_values{1} = "";
  columnformat_values{3} = popup_options;

  default_data = repmat (d(:,2), 1, columns (columnformat_options));
  b_add = uicontrol (f, "Position", [285 630 600 50], ...
            "UserData", [rows(d), 1], ...
            "Style", "pushbutton", ...
            "String", "Set data at selected point to selected datatype");

  l_type_table = uicontrol (f, "Position", [ 0 603 120 25 ], ...
      "String", "Datatype Table:", ...
      "Style", "text");
  t_type_table = uitable (f, "Position", [ 0 530 1000 70 ], ...
      "Data", transpose (d(:, 2)), ...
      "ColumnName", transpose (d(:, 1)), ...
      "RowName", "Value", ...
      "CellSelectionCallback", ...
           @(x, y) set (b_add, "UserData", y.Indices ));

  l_point_table = uicontrol (f, "Position", [ 0 640 60 25 ], ...
      "String", "Point:", ...
      "Style", "text");
  t_point_table = uitable (f, "Position", [ 80 630 160 42 ], ...
      "RowName", [], ...
      "ColumnName", {"x", "y"}, ...
      "Data", [ 1, 1 ], ...
      "ColumnEditable", true);

  l_editable_table = uicontrol (f, "Position", [ 0 502 200 25 ], ...
      "Style", "text", ...
      "String", "Set Data Columns Editable:");
  t_editable_table = ...
    uitable (f, "Position", [ 0 434 1000 65 ], ...
                "Data", repmat (false, 1, columns (default_data)), ...
                "ColumnEditable", true);

  l_format_table = uicontrol (f, "Position", [ 0 406 200 25 ], ...
      "Style", "text", ...
      "String", "Set Data Column Format:");
  t_format_table = ...
    uitable (f, "Position", [ 0 338 1000 65 ], ...
                "Data", columnformat_options, ...
                "ColumnEditable", true, ...
                "ColumnFormat", arrayfun (@(x) {columnformat_options}, ...
                                          1:columns (columnformat_options)));

  l_data_table = uicontrol (f, "Style", "text", ...
                               "String", "Data:", ...
                               "Position", [ 0 310 60 25 ]);
  t_data_table = uitable (f, "Position", [ 0 15 1000 290 ], ...
      "Data", default_data, ...
      "ColumnFormat", columnformat_values);

  set (t_format_table, ...
       "CellEditCallback", ...
       @(x, y) update_column_format (y.NewData, y.Indices, ...
                                      t_data_table, popup_options));
  set (t_point_table, "CellEditCallback", ...
       @(x, y) validate_point_table (x, y, t_data_table));
  set (t_editable_table, "CellEditCallback", ...
       @(x,y) set (t_data_table, ...
                    "ColumnEditable", get (t_editable_table, "Data")));
  set (b_add, ...
       "Callback", @(x, y) update_data (b_add, t_point_table, ...
                                         t_type_table, t_data_table));
  set (t_data_table, "CellSelectionCallback", ...
       @(x, y) update_point_table (y.Indices, t_point_table));
endfunction

function validate_point_table (h, dat, t_data_table)
  if (! (dat.NewData > 0 && ...
    dat.NewData < size (get (t_data_table, "Data"), dat.Indices(1, 1)) + 1))

    d = get (h, "Data");
    d(dat.Indices) = 1;
    set (h, "Data", d);
  endif
endfunction


function update_column_format (format, indices, t_data_table, ...
                               popup_options)
  cf = get (t_data_table, "ColumnFormat");
  if (strcmp (format, "[]"))
    format = "";
  elseif (strcmp (format, "pop-up"))
    format = popup_options;
  endif
  cf{indices(1,2)} = format;
  set (t_data_table, "ColumnFormat", cf);
endfunction


function update_point_table (indices, t_point_table)
  if (isempty (indices))
    indices = [1, 1];
  endif
  set (t_point_table, "Data", indices(1,:));
endfunction


function update_data (b_add, t_point_table, t_type_table, ...
                      t_data_table)
  indices = get (b_add, "UserData");
  if (isempty (indices))
    indices = [1, 1];
  endif
  d = get (t_data_table, "Data");
  t_type_table_data = get (t_type_table, "Data");
  p = get (t_point_table, "Data");
  d(p(1,2), p(1,1)) = t_type_table_data(indices(1,2));
  set (t_data_table, "Data", d);
endfunction

See also: figure, uicontrol.

: hui = uimenu (property, value, …)

: hui = uimenu (h, property, value, …)

Create a uimenu object and return a handle to it.

If h is omitted then a top-level menu for the current figure is created. If h is given then a submenu relative to h is created.

uimenu objects have the following specific properties:

"accelerator"

A string containing the key combination together with CTRL to execute this menu entry (e.g., "x" for CTRL+x).

"callback"

Is the function called when this menu entry is executed. It can be either a function string (e.g., "myfun"), a function handle (e.g., @myfun) or a cell array containing the function handle and arguments for the callback function (e.g., {@myfun, arg1, arg2}).

"checked"

Can be set "on" or "off". Sets a mark at this menu entry.

"enable"

Can be set "on" or "off". If disabled the menu entry cannot be selected and it is grayed out.

"foregroundcolor"

A color value setting the text color for this menu entry.

"label"

A string containing the label for this menu entry. A "&"-symbol can be used to mark the "accelerator" character (e.g., "E&xit")

"position"

An scalar value containing the relative menu position. The entry with the lowest value is at the first position starting from left or top.

"separator"

Can be set "on" or "off". If enabled it draws a separator line above the current position. It is ignored for top level entries.

The full list of properties is documented at Uimenu Properties.

Examples:

f = uimenu ("label", "&File", "accelerator", "f");
e = uimenu ("label", "&Edit", "accelerator", "e");
uimenu (f, "label", "Close", "accelerator", "q", ...
           "callback", "close (gcf)");
uimenu (e, "label", "Toggle &Grid", "accelerator", "g", ...
           "callback", "grid (gca)");

See also: figure.

: hui = uicontextmenu (property, value, …)

: hui = uicontextmenu (h, property, value, …)

Create a uicontextmenu object and return a handle to it.

If h is omitted then a uicontextmenu for the current figure is created. If no figure is available, a new figure is created first.

If h is given then a uicontextmenu relative to h is created.

Any provided property value pairs will override the default values of the created uicontextmenu object.

The full list of properties is documented at Uicontextmenu Properties.

Examples:

## create figure and uicontextmenu
f = figure ();
c = uicontextmenu (f);

## create menus in the context menu
m1 = uimenu ("parent", c, "label", "Menu item 1", ...
             "callback", "disp('menu item 1')");
m2 = uimenu ("parent", c, "label", "Menu item 2", ...
             "callback", "disp('menu item 2')");

## set the context menu for the figure
set (f, "uicontextmenu", c);

See also: figure, uimenu.

: uitoolbar (property, value, …)

: uitoolbar (parent, property, value, …)

: hui = uitoolbar (…)

Create a uitoolbar object. A uitoolbar displays uitoggletool and uipushtool buttons.

If parent is omitted then a uitoolbar for the current figure is created. If no figure is available, a new figure is created first.

If parent is given then a uitoolbar relative to parent is created.

Any provided property value pairs will override the default values of the created uitoolbar object.

The full list of properties is documented at Uitoolbar Properties.

The optional return value hui is a graphics handle to the created uitoolbar object.

Examples:

% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);

See also: figure, uitoggletool, uipushtool.

: uipushtool (property, value, …)

: uipushtool (parent, property, value, …)

: hui = uipushtool (…)

Create a uipushtool object.

uipushtools are buttons that appear on a figure toolbar. The button is created with a border that is shown when the user hovers over the button. An image can be set using the cdata property.

If parent is omitted then a uipushtool for the current figure is created. If no figure is available, a new figure is created first. If a figure is available, but does not contain a uitoolbar, a uitoolbar will be created.

If parent is given then a uipushtool is created on the parent uitoolbar.

Any provided property value pairs will override the default values of the created uipushtool object.

The full list of properties is documented at Uipushtool Properties.

The optional return value hui is a graphics handle to the created uipushtool object.

Examples:

% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add pushtool button to toolbar
b = uipushtool (t, "cdata", img);

See also: figure, uitoolbar, uitoggletool.

: uitoggletool (property, value, …)

: uitoggletool (parent, property, value, …)

: hui = uitoggletool (…)

Create a uitoggletool object.

uitoggletool are togglebuttons that appear on a figure toolbar. The button is created with a border that is shown when the user hovers over the button. An image can be set using the cdata property.

If parent is omitted then a uitoggletool for the current figure is created. If no figure is available, a new figure is created first. If a figure is available, but does not contain a uitoolbar, a uitoolbar will be created.

If parent is given then a uitoggletool is created on the parent uitoolbar.

Any provided property value pairs will override the default values of the created uitoggletool object.

The full list of properties is documented at Uitoggletool Properties.

The optional return value hui is a graphics handle to the created uitoggletool object.

Examples:

% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add uitoggletool button to toolbar
b = uitoggletool (t, "cdata", img);

See also: figure, uitoolbar, uipushtool.