GNU Octave: UI Elements

Next: GUI Utility Functions, Previous: Progress Bar, Up: GUI Development [Contents][Index]

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

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

  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 = uibuttongroup (property, value, …)
: hui = uibuttongroup (parent, property, value, …)
: uibuttongroup (h)

  Create a uibuttongroup object and return a handle to it.

  uibuttongroups are used to create group uicontrols.

  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.

  Uibuttongroup properties are 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 ]);

  See also: figure, uipanel.

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

  Uicontextmenu properties are 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 = uicontrol (property, value, …)
: hui = uicontrol (parent, property, value, …)
: uicontrol (h)

  Create a uicontrol object and return a handle to it.

  uicontrols are 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.

  Uicontrol properties are documented at Uicontrol Properties.

  Control of the type of uicontrol created is through the use of 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]);

  See also: figure, uipanel.

: hui = uipanel (property, value, …)
: hui = uipanel (parent, "property, value, …)

  Create a uipanel object and return a handle to it.

  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.

  Uipanel properties are documented at Uipanel Properties.

  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 = uipushtool (property, value, …)
: hui = uipushtool (parent, property, value, …)

  Create a uipushtool object and return a handle to it.

  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 an uipushtools is created on the parent uitoolbar.

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

  Uipushtool properties are documented at Uipushtool Properties.

  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 (property, value, …)
: hui = uitoggletool (parent, property, value, …)

  Create a uitoggletool object and return a handle to it.

  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.

  Uitoggletool properties are documented at Uitoggletool Properties.

  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.

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

  Create a uitoolbar object and return a handle to it. 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.

  Uitoolbar properties are documented at Uitoolbar Properties.

  Examples:

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

  See also: figure, uitoggletool, uipushtool.

Next: GUI Utility Functions, Previous: Progress Bar, Up: GUI Development [Contents][Index]