UI Elements (GNU Octave (version 8.4.0))

### 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.

: `h =` uifigure `()` ¶
: `h =` uifigure `("property", value, …)` ¶

  Create a new figure window for applications.

  Multiple property-value pairs may be specified for the figure object, but they must occur in pairs.

  The return value h is a graphics handle to the created figure object.

  Programming Note: The full list of properties is documented at Figure Properties. This function differs from `figure` in that the created figure is optimized for application development, rather than plotting. This means features such as menubars and toolbars are turned off.

  See also: uipanel, uibuttongroup.

: `hui =` uipanel `()` ¶
: `hui =` uipanel `(property, value, …)` ¶
: `hui =` uipanel `(parent)` ¶
: `hui =` uipanel `(parent, property, value, …)` ¶

  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 `()` ¶
: `hui =` uibuttongroup `(property, value, …)` ¶
: `hui =` uibuttongroup `(parent)` ¶
: `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 `()` ¶
: `hui =` uicontrol `(property, value, …)` ¶
: `hui =` uicontrol `(parent)` ¶
: `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, together with CTRL, to execute this menu entry (e.g., `"x"` for CTRL+x).

  `"checked"`

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

  `"enable"`

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

  `"foregroundcolor"`

    A color value for the text of the menu entry.

  `"menuselectedfcn"`

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

  `"position"`

    A scalar value containing the relative menu position. The first position has value 1 and will be either the left or top depending on the orientation of the uimenu.

  `"separator"`

    Can be set `"on"` or `"off"`. If enabled, a separator line is drawn above the current position. This property is ignored for top-level entries.

  `"text"`

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

  The full list of properties is documented at Uimenu Properties.

  Examples:

      f = uimenu ("text", "&File", "accelerator", "f");
      e = uimenu ("text", "&Edit", "accelerator", "e");
      uimenu (f, "text", "Close", "accelerator", "q", ...
                 "menuselectedfcn", "close (gcf)");
      uimenu (e, "text", "Toggle &Grid", "accelerator", "g", ...
                 "menuselectedfcn", "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.

: `hui =` uitoolbar `()` ¶
: `hui =` uitoolbar `(property, value, …)` ¶
: `hui =` uitoolbar `(parent)` ¶
: `hui =` uitoolbar `(parent, property, value, …)` ¶

  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.

: `hui =` uipushtool `()` ¶
: `hui =` uipushtool `(property, value, …)` ¶
: `hui =` uipushtool `(parent)` ¶
: `hui =` uipushtool `(parent, property, value, …)` ¶

  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.

: `hui =` uitoggletool `()` ¶
: `hui =` uitoggletool `(property, value, …)` ¶
: `hui =` uitoggletool `(parent)` ¶
: `hui =` uitoggletool `(parent, property, value, …)` ¶

  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.