GUI Development
***************

Octave is principally a batch or command-line language.  However, it does offer some features for constructing graphical interfaces that interact with users.

The GUI elements available are I/O dialogs, a progress bar, and UI elements for plot windows.  For example, rather than hardcoding a filename for output results a script can open a dialog box and allow the user to choose a file. Similarly, if a calculation is expected to take a long time a script can display a progress bar.  The various UI elements can be used to fully customize the plot window with menubars, toolbars, context menus, pushbuttons, sliders, etc.

Several utility functions make it possible to store private data for use with a GUI which will not pollute the user's variable space.

Finally, a program written in Octave might want to have long term storage of preferences or state variables.  This can be done with user-defined preferences.

I/O Dialogs
===========

Simple dialog menus are available for choosing directories or files.  They return a string variable which can then be used with any command requiring a filename.

 -- DIRNAME =: uigetdir ()
 -- DIRNAME =: uigetdir (INIT_PATH)
 -- DIRNAME =: uigetdir (INIT_PATH, DIALOG_NAME)
     Open a GUI dialog for selecting a directory.

     If INIT_PATH is not given the current working directory is used.

     DIALOG_NAME may be used to customize the dialog title.

     The output DIRNAME is a character string with the name of the selected directory.  However, if the Cancel button is clicked the output is of type double with the value 0. uigetfile, uiputfile

 -- [FNAME, FPATH, FLTIDX] =: uigetfile ()
 -- [...] =: uigetfile (FLT)
 -- [...] =: uigetfile (FLT, DIALOG_NAME)
 -- [...] =: uigetfile (FLT, DIALOG_NAME, DEFAULT_FILE)
 -- [...] =: uigetfile (..., "Position", [PX PY])
 -- [...] =: uigetfile (..., "MultiSelect", MODE)

     Open a GUI dialog for selecting a file and return the filename FNAME, the path to this file FPATH, and the filter index FLTIDX.

     FLT contains a (list of) file filter string(s) in one of the following formats:

     "/path/to/filename.ext"
          If a filename is given then the file extension is extracted and used as filter.  In addition, the path is selected as current path in the dialog and the filename is selected as default file. Example: uigetfile ("myfun.m")

     A single file extension "*.ext"
          Example: uigetfile ("*.ext")

     A 2-column cell array
          containing a file extension in the first column and a brief description in the second column. Example: uigetfile ({"*.ext", "My Description";"*.xyz", "XYZ-Format"})

          The filter string can also contain a semicolon separated list of filter extensions. Example: uigetfile ({"*.gif;*.png;*.jpg", "Supported Picture Formats"})

     A directory name or path name
          If the folder name of path name contains a trailing file separator, the contents of that folder will be displayed.  If no trailing file separator is present the parent directory is listed.  The substring to the right of the rightmost file separator (if any) will be interpreted as a file or directory name and if that file or directory exists it will be highlighted. If the path name or directory name is entirely or partly nonexistent, the current working directory will be displayed. No filter will be active.

     DIALOG_NAME can be used to customize the dialog title.

     If DEFAULT_FILE is given then it will be selected in the GUI dialog. If, in addition, a path is given it is also used as current path.

     The screen position of the GUI dialog can be set using the "Position" key and a 2-element vector containing the pixel coordinates.  Two or more files can be selected when setting the "MultiSelect" key to "on".  In that case FNAME is a cell array containing the files.

     The outputs FNAME and FPATH are strings returning the chosen name and path, respectively.  However, if the Cancel button is clicked the outputs are of type double with a value of 0. FLTIDX is the index in the list of filter extensions FLT that was selected.

     uiputfile, uigetdir

 -- [FNAME, FPATH, FLTIDX] =: uiputfile ()
 -- [FNAME, FPATH, FLTIDX] =: uiputfile (FLT)
 -- [FNAME, FPATH, FLTIDX] =: uiputfile (FLT, DIALOG_NAME)
 -- [FNAME, FPATH, FLTIDX] =: uiputfile (FLT, DIALOG_NAME, DEFAULT_FILE)
     Open a GUI dialog for selecting a file.

     FLT contains a (list of) file filter string(s) in one of the following formats:

     "/path/to/filename.ext"
          If a filename is given the file extension is extracted and used as filter. In addition the path is selected as current path in the dialog and the filename is selected as default file.  Example: uiputfile ("myfun.m")

     "*.ext"
          A single file extension. Example: uiputfile ("*.ext")

     {"*.ext", "My Description"}
          A 2-column cell array containing the file extension in the 1st column and a brief description in the 2nd column. Example: uiputfile ({"*.ext","My Description";"*.xyz", "XYZ-Format"})

     The filter string can also contain a semicolon separated list of filter extensions. Example: uiputfile ({"*.gif;*.png;*.jpg", "Supported Picture Formats"})

     DIALOG_NAME can be used to customize the dialog title. If DEFAULT_FILE is given it is preselected in the GUI dialog. If, in addition, a path is given it is also used as current path.

     FNAME and FPATH return the chosen name and path, respectively. FLTIDX is the index in the list of filter extensions FLT that was selected.

     uigetfile, uigetdir

Additionally, there are dialog boxes for displaying help messages, warnings, or errors, and for getting text input from the user.

 -- errordlg: ()
 -- errordlg: (MSG)
 -- errordlg: (MSG, TITLE)
 -- errordlg: (MSG, TITLE, OPT)
 -- H =: errordlg (...)
     Display an error dialog box with error message MSG and caption TITLE.

     The default error message is "This is the default error string." and the default caption is "Error Dialog".

     The error message may have multiple lines separated by newline characters ("\n"), or it may be a cellstr array with one element for each line.

     The third optional argument OPT controls the behavior of the dialog. See msgbox for details.

     The return value H is a handle to the figure object used for building the dialog.

     Examples:

          errordlg ("Some fancy error occurred.");
          errordlg ("Some fancy error\nwith two lines.");
          errordlg ({"Some fancy error", "with two lines."});
          errordlg ("Some fancy error occurred.", "Fancy caption");

     helpdlg, warndlg, msgbox, inputdlg, listdlg, questdlg

 -- helpdlg: ()
 -- helpdlg: (MSG)
 -- helpdlg: (MSG, TITLE)
 -- H =: helpdlg (...)
     Display a help dialog box with help message MSG and caption TITLE.

     The default help message is "This is the default help string." and the default caption is "Help Dialog".

     The help message may have multiple lines separated by newline characters ("\n"), or it may be a cellstr array with one element for each line.

     The return value H is a handle to the figure object used for building the dialog.

     Examples:

          helpdlg ("Some helpful text for the user.");
          helpdlg ("Some helpful text\nwith two lines.");
          helpdlg ({"Some helpful text", "with two lines."});
          helpdlg ("Some helpful text for the user.", "Fancy caption");

     errordlg, warndlg, msgbox, inputdlg, listdlg, questdlg

 -- CSTR =: inputdlg (PROMPT)
 -- CSTR =: inputdlg (PROMPT, TITLE)
 -- CSTR =: inputdlg (PROMPT, TITLE, ROWSCOLS)
 -- CSTR =: inputdlg (PROMPT, TITLE, ROWSCOLS, DEFAULTS)
 -- CSTR =: inputdlg (PROMPT, TITLE, ROWSCOLS, DEFAULTS, OPTIONS)
     Return user input from a multi-textfield dialog box in a cell array of strings, or an empty cell array if the dialog is closed by the Cancel button.

     Inputs:

     prompt
          A cell array with strings labeling each text field.  This input is required.

     title
          String to use for the caption of the dialog.  The default is "Input Dialog".

     rowscols
          Specifies the size of the text fields and can take three forms:

           1. a scalar value which defines the number of rows used for each text field.

           2. a vector which defines the individual number of rows used for each text field.

           3. a matrix which defines the individual number of rows and columns used for each text field.  In the matrix each row describes a single text field. The first column specifies the number of input rows to use and the second column specifies the text field width.

     defaults
          A list of default values to place in each text field.  It must be a cell array of strings with the same size as PROMPT.

     options
          Not supported, only for MATLAB compatibility.

     Example:

          prompt = {"Width", "Height", "Depth"};
          defaults = {"1.10", "2.20", "3.30"};
          rowscols = [1,10; 2,20; 3,30];
          dims = inputdlg (prompt, "Enter Box Dimensions", ...
                           rowscols, defaults);

     errordlg, helpdlg, listdlg, msgbox, questdlg, warndlg

 -- [SEL, OK] =: listdlg (KEY, VALUE, ...)
     Return user inputs from a list dialog box in a vector of selection indices (SEL) and a flag indicating how the user closed the dialog box (OK).

     The indices in SEL are 1-based.

     The value of OK is 1 if the user closed the box with the OK button, otherwise it is 0 and SEL is empty.

     Input arguments are specified in form of KEY, VALUE pairs. The "ListString" argument pair must be specified.

     Valid KEY and VALUE pairs are:

     "ListString"
          a cell array of strings specifying the items to list in the dialog.

     "SelectionMode"
          can be either "Single" (only one item may be selected at a time) or "Multiple" (default).

     "ListSize"
          a two-element vector [WIDTH, HEIGHT] specifying the size of the list field in pixels.  The default is [160, 300].

     "InitialValue"
          a vector containing 1-based indices of elements which will be pre-selected when the list dialog is first displayed. The default is 1 (first item).

     "Name"
          a string to be used as the dialog caption.  Default is "".

     "PromptString"
          a cell array of strings to be displayed above the list of items. Default is {}.

     "OKString"
          a string used to label the OK button.  Default is "OK".

     "CancelString"
          a string used to label the Cancel button.  Default is "Cancel".

     Example:

          my_options = {"An item", "another", "yet another"};
          [sel, ok] = listdlg ("ListString", my_options,
                               "SelectionMode", "Multiple");
          if (ok == 1)
            disp ("You selected:");
            for i = 1:numel (sel)
              disp (sprintf ("\t%s", my_options{sel(i)}));
            endfor
          else
            disp ("You cancelled.");
          endif

     menu, errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg

 -- H =: msgbox (MSG)
 -- H =: msgbox (MSG, TITLE)
 -- H =: msgbox (MSG, TITLE, ICON)
 -- H =: msgbox (MSG, TITLE, "custom", CDATA)
 -- H =: msgbox (MSG, TITLE, "custom", CDATA, COLORMAP)
 -- H =: msgbox (..., OPT)
     Display MSG using a message dialog box.

     The message may have multiple lines separated by newline characters ("\n"), or it may be a cellstr array with one element for each line.

     The optional input TITLE (character string) can be used to decorate the dialog caption.

     The optional argument ICON selects a dialog icon. It can be one of "none" (default), "error", "help", "warn", or "custom".  The latter must be followed by an image array CDATA, and for indexed images the associated colormap.

     The final optional argument OPT controls the behavior of the dialog. If OPT is a string, it may be one of

     "non-modal" (default)
          The dialog is normal.

     "modal"
          If any dialogs already exist with the same title, the most recent is reused and all others are closed.  The dialog is displayed "modal" which means it prevents users from interacting with any other GUI element until the dialog has been closed.

     "replace"
          If any dialogs already exist with the same title, the most recent is reused and all others are closed.  The resulting dialog is set "non-modal".

     If OPT is a structure, it must contain fields "WindowStyle" and "Interpreter":

     "WindowStyle"
          The value must be "non-modal", "modal", or "replace".  See above.

     "Interpreter"
          Controls the "interpreter" property of the text object used for displaying the message.  The value must be "tex" (default), "none", or "latex".

     The return value H is a handle to the figure object used for building the dialog.

     Examples:

          msgbox ("Some message for the user.");
          msgbox ("Some message\nwith two lines.");
          msgbox ({"Some message", "with two lines."});
          msgbox ("Some message for the user.", "Fancy caption");

          ## A message dialog box with error icon
          msgbox ("Some message for the user.", "Fancy caption", "error");

     errordlg, helpdlg, inputdlg, listdlg, questdlg, warndlg

 -- BTN =: questdlg (MSG)
 -- BTN =: questdlg (MSG, TITLE)
 -- BTN =: questdlg (MSG, TITLE, DEFAULT)
 -- BTN =: questdlg (MSG, TITLE, BTN1, BTN2, DEFAULT)
 -- BTN =: questdlg (MSG, TITLE, BTN1, BTN2, BTN3, DEFAULT)
     Display MSG using a question dialog box and return the caption of the activated button.

     The message may have multiple lines separated by newline characters ("\n"), or it may be a cellstr array with one element for each line.

     The optional TITLE (character string) can be used to specify the dialog caption.  It defaults to "Question Dialog".

     The dialog may contain two or three buttons which will all close the dialog.

     The string DEFAULT identifies the default button, which is activated by pressing the ENTER key.  It must match one of the strings given in BTN1, BTN2, or BTN3.

     If only MSG and TITLE are specified, three buttons with the default captions "Yes", "No", and "Cancel" are used.

     If only two button captions, BTN1 and BTN2, are specified the dialog will have only these two buttons.

     Examples:

          btn = questdlg ("Close Octave?", "Some fancy title", ...
                          "Yes", "No", "No");
          if (strcmp (btn, "Yes"))
            exit ();
          endif

     errordlg, helpdlg, inputdlg, listdlg, msgbox, warndlg

 -- warndlg: ()
 -- warndlg: (MSG)
 -- warndlg: (MSG, TITLE)
 -- warndlg: (MSG, TITLE, OPT)
 -- H =: warndlg (...)
     Display a warning dialog box with warning message MSG and caption TITLE.

     The default warning message is "This is the default warning string." and the default caption is "Warning Dialog".

     The warning message may have multiple lines separated by newline characters ("\n"), or it may be a cellstr array with one element for each line.

     The third optional argument OPT controls the behavior of the dialog. See msgbox for details.

     The return value H is a handle to the figure object used for building the dialog.

     Examples:

          warndlg ("Some warning text for the user.");
          warndlg ("Some warning text\nwith two lines.");
          warndlg ({"Some warning text", "with two lines."});
          warndlg ("Some warning text for the user.", "Fancy caption");

     errordlg, helpdlg, msgbox, inputdlg, listdlg, questdlg

 --  : uisetfont ()
 --  : uisetfont (H)
 --  : uisetfont (FONTSTRUCT)
 --  : uisetfont (..., TITLE)
 -- FONTSTRUCT =: uisetfont (...)
     Open a font selection dialog.

     If the first argument is a handle to a text, axes, or uicontrol object, pressing the OK button will change the font properties of the object.

     The first argument may also be a structure with fields FontName, FontWeight, FontAngle, FontUnits, and FontSize, indicating the initially selected font.

     The title of the dialog window can be changed using the last argument TITLE.

     If an output argument FONTSTRUCT is requested, the selected font structure is returned.  Otherwise, the font information is displayed onscreen.

     text, axes, uicontrol

For creating new dialog types, there is a dialog function.

 -- H =: dialog ()
 -- H =: dialog ("PROPERTY", VALUE, ...)

     Create an empty modal dialog window to which other uicontrols can be added.

     The dialog box is a figure object with properties as recommended for a dialog box.

     The default properties differing from a figure are:

     buttondownfcn
          if isempty (allchild(gcbf)), close (gcbf), endif

     colormap
          []

     color
          defaultuicontrolbackgroundcolor

     dockcontrols
          off

     handlevisibility
          callback

     integerhandle
          off

     inverthardcopy
          off

     menubar
          none

     numbertitle
          off

     paperpositionmode
          auto

     resize
          off

     windowstyle
          modal

     Multiple property-value pairs may be specified for the dialog object, but they must appear in pairs.  The full list of properties is documented at Figure Properties.

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

     Example:

          ## create an empty dialog window titled "Dialog Example"
          h = dialog ("name", "Dialog Example");

          ## create a button (default style)
          b = uicontrol (h, "string", "OK",
                            "position", [10 10 150 40],
                            "callback", "delete (gcf)");

          ## wait for dialog to resume or close
          uiwait (h);

     errordlg, msgbox, questdlg, warndlg, figure, uiwait

Progress Bar
============

 -- H =: waitbar (FRAC)
 -- H =: waitbar (FRAC, MSG)
 -- H =: waitbar (..., "createcancelbtn", FCN, ...)
 -- H =: waitbar (..., PROP, VAL, ...)
 -- waitbar: (FRAC)
 -- waitbar: (FRAC, H)
 -- waitbar: (FRAC, H, MSG)
     Return a handle H to a new progress indicator ("waitbar") object.

     The waitbar is filled to fraction FRAC which must be in the range [0, 1].

     The optional message MSG is centered and displayed above the waitbar.

     A cancel button can be added to the bottom of the waitbar using the "createcancelbtn" property of waitbar figures.  The action to be executed when the user presses the button is specified using a string or function handle FCN.

     The appearance of the waitbar figure window can be configured by passing PROP/VAL pairs to the function.  The full list of properties is documented at Figure Properties.

     When called with a single input the current waitbar, if it exists, is updated to the new value FRAC.  If there are multiple outstanding waitbars they can be updated individually by passing the handle H of the specific waitbar to modify.

     delete

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]);

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

     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)");

     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);

     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);

     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);

     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);

     figure, uitoolbar, uipushtool

GUI Utility Functions
=====================

These functions do not implement a GUI element but are useful when developing programs that do.  The functions uiwait, uiresume, and waitfor are only available with the qt or fltk toolkits.

 -- DATA =: guidata (H)
 -- guidata: (H, DATA)
     Query or set user-custom GUI data.

     The GUI data is stored in the figure handle H.  If H is not a figure handle then it's parent figure will be used for storage.

     DATA must be a single object which means it is usually preferable for it to be a data container such as a cell array or struct so that additional data items can be added easily.

     getappdata, setappdata, get, set, getpref, setpref

 -- HDATA =: guihandles (H)
 -- HDATA =: guihandles
     Return a structure of object handles for the figure associated with handle H.

     If no handle is specified the current figure returned by gcf is used.

     The fieldname for each entry of HDATA is taken from the "tag" property of the graphic object.  If the tag is empty then the handle is not returned.  If there are multiple graphic objects with the same tag then the entry in HDATA will be a vector of handles.  guihandles includes all possible handles, including those for which "HandleVisibility" is "off". guidata, findobj, findall, allchild

 -- have_window_system: ()
     Return true if a window system is available (X11, Windows, or Apple OS X) and false otherwise. isguirunning

 -- isguirunning: ()
     Return true if Octave is running in GUI mode and false otherwise. have_window_system

 -- movegui:
 -- movegui: (H)
 -- movegui: (POS)
 -- movegui: (H, POS)
 -- movegui: (H, EVENT)
 -- movegui: (H, EVENT, POS)
     Move a figure specified by figure handle H to a position on the screen defined by POS.

     H is a figure handle, or a handle to a graphics object.  In the latter case, its parent figure will be used.  If unspecified, H will be set to the handle of the relevant figure if a callback is being executed (gcbf), otherwise it will be set to the handle of the current figure (gcf).

     POS is either a two-value numeric vector or a string.  If POS is numeric then it must be of the form [h, v] specifying the horizontal and vertical offsets of the figure with respect to the screen.  A positive value indicates the offset between the left (or bottom for the vertical component) of the screen, and the left (or bottom) of the figure.  A negative value indicates the offset between the right (or top) of the screen and the right (or top) of the figure.

     Possible values for POS as a string are

     north
          Top center of the screen.

     south
          Bottom center of the screen.

     east
          Right center of the screen.

     west
          Left center of the screen.

     northeast
          Top right of the screen.

     northwest
          Top left of the screen.

     southeast
          Bottom right of the screen.

     southwest
          Bottom left of the screen.

     center
          Center of the screen.

     onscreen (default)
          The figure will be minimally moved to be entirely visible on the screen, with a 30 pixel extra padding from the sides of the screen.  This is the default value if none is provided.

     EVENT contains event data that will be ignored.  This construct facilitates a call to movegui from a callback.

 -- openvar: (NAME)
     Open the variable NAME in the graphical Variable Editor.

 -- uiwait:
 -- uiwait: (H)
 -- uiwait: (H, TIMEOUT)
     Suspend program execution until the figure with handle H is deleted or uiresume is called.

     When no figure handle is specified this function uses the current figure. If the figure handle is invalid or there is no current figure, this functions returns immediately.

     When specified, TIMEOUT defines the number of seconds to wait for the figure deletion or the uiresume call.  The timeout value must be at least 1.  If a smaller value is specified, a warning is issued and a timeout value of 1 is used instead.  If a non-integer value is specified, it is truncated towards 0.  If TIMEOUT is not specified, the program execution is suspended indefinitely. uiresume, waitfor

 -- uiresume: (H)
     Resume program execution suspended with uiwait.

     The handle H must be the same as the on specified in uiwait. If the handle is invalid or there is no uiwait call pending for the figure with handle H, this function does nothing. uiwait

 -- waitfor: (H)
 -- waitfor: (H, PROP)
 -- waitfor: (H, PROP, VALUE)
 -- waitfor: (..., "timeout", TIMEOUT)
     Suspend the execution of the current program until a condition is satisfied on the graphics handle H.

     While the program is suspended graphics events are still processed normally, allowing callbacks to modify the state of graphics objects.  This function is reentrant and can be called from a callback, while another waitfor call is pending at the top-level.

     In the first form, program execution is suspended until the graphics object H is destroyed.  If the graphics handle is invalid or if H is the root graphics handle and no property PROP was provided, the function returns immediately.

     In the second form, execution is suspended until the graphics object is destroyed or the property named PROP is modified.  If the graphics handle is invalid or the property does not exist, the function returns immediately.

     In the third form, execution is suspended until the graphics object is destroyed or the property named PROP is set to VALUE.  The function isequal is used to compare property values.  If the graphics handle is invalid, the property does not exist or the property is already set to VALUE, the function returns immediately.

     An optional timeout can be specified using the property "timeout". This timeout value is the number of seconds to wait for the condition to be true.  TIMEOUT must be at least 1.  If a smaller value is specified, a warning is issued and a value of 1 is used instead.  If the timeout value is not an integer, it is truncated towards 0.

     To define a condition on a property named "timeout", use the string '\timeout' instead.

     In all cases, typing CTRL-C stops program execution immediately. waitforbuttonpress, isequal

User-Defined Preferences
========================

 -- VAL =: getpref ("GROUP", "PREF")
 -- VAL =: getpref ("GROUP", "PREF", DEFAULT)
 -- {VAL1, VAL2, ...} =: getpref ("GROUP", {"PREF1", "PREF2", ...})
 -- PREFSTRUCT =: getpref ("GROUP")
 -- PREFSTRUCT =: getpref ()
     Return the preference value corresponding to the named preference PREF in the preference group GROUP.

     The named preference group must be a string.

     If PREF does not exist in GROUP and DEFAULT is specified, create the preference with value DEFAULT and return DEFAULT.

     The preference PREF may be a string or cell array of strings.  If it is a cell array of strings then a cell array of preferences is returned.

     The corresponding default value DEFAULT may be any Octave value, .e.g., double, struct, cell array, object, etc.  Or, if PREF is a cell array of strings then DEFAULT must be a cell array of values with the same size as PREF.

     If neither PREF nor DEFAULT are specified, return a structure of preferences for the preference group GROUP.

     If no arguments are specified, return a structure containing all groups of preferences and their values. addpref, setpref, ispref, rmpref

 -- setpref: ("GROUP", "PREF", VAL)
 -- setpref: ("GROUP", {"PREF1", "PREF2", ...}, {VAL1, VAL2, ...})
     Set the preference PREF to the given VAL in the named preference group GROUP.

     The named preference group must be a string.

     The preference PREF may be a string or a cell array of strings.

     The corresponding value VAL may be any Octave value, .e.g., double, struct, cell array, object, etc.  Or, if PREF is a cell array of strings then VAL must be a cell array of values with the same size as PREF.

     If the named preference or group does not exist, it is added. addpref, getpref, ispref, rmpref

 -- addpref: ("GROUP", "PREF", VAL)
 -- addpref: ("GROUP", {"PREF1", "PREF2", ...}, {VAL1, VAL2, ...})
     Add the preference PREF and associated value VAL to the named preference group GROUP.

     The named preference group must be a string.

     The preference PREF may be a string or a cell array of strings.  An error will be issued if the preference already exists.

     The corresponding value VAL may be any Octave value, .e.g., double, struct, cell array, object, etc.  Or, if PREF is a cell array of strings then VAL must be a cell array of values with the same size as PREF. setpref, getpref, ispref, rmpref

 -- rmpref: ("GROUP", "PREF")
 -- rmpref: ("GROUP", {"PREF1", "PREF2", ...})
 -- rmpref: ("GROUP")
     Remove the named preference PREF from the preference group GROUP.

     The named preference group must be a string.

     The preference PREF may be a string or cell array of strings.

     If PREF is not specified, remove the preference group GROUP.

     It is an error to remove a nonexistent preference or group. addpref, ispref, setpref, getpref

 -- ispref: ("GROUP", "PREF")
 -- ispref: ("GROUP", {"PREF1", "PREF2", ...})
 -- ispref: ("GROUP")
     Return true if the named preference PREF exists in the preference group GROUP.

     The named preference group must be a string.

     The preference PREF may be a string or a cell array of strings.

     If PREF is not specified, return true if the preference group GROUP exists. getpref, addpref, setpref, rmpref

 -- prefdir:
 -- prefdir: (1)
 -- DIR =: prefdir
     Return the directory that holds the preferences for Octave.

     Examples:

     Display the preferences directory

          prefdir

     Change to the preferences folder

          cd (prefdir)

     If called with an argument, the preferences directory is created if it doesn't already exist. getpref, setpref, addpref, rmpref, ispref

 -- preferences:
     Display the GUI preferences dialog window for Octave.

Octave Workspace Windows
========================

The functions below make windows that are a part of Octave's own GUI interface visible, and move the keyboard focus to the selected window.  Their utility lies in the ability to call these functions from a script and highlight a window without using a mouse for selection.

 -- commandhistory: ()
     Show the GUI command history window and give it the keyboard focus. commandwindow, filebrowser, workspace

 -- commandwindow: ()
     Show the GUI command window and give it the keyboard focus. commandhistory, filebrowser, workspace

 -- filebrowser: ()
     Show the GUI file browser window and give it the keyboard focus. commandwindow, commandhistory, workspace

 -- workspace: ()
     Show the GUI workspace window and give it the keyboard focus. commandwindow, commandhistory, filebrowser