@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 2012-2025 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node GUI Development
@chapter 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.

@menu
* I/O Dialogs::
* Progress Bar::
* UI Elements::
* GUI Utility Functions::
* User-Defined Preferences::
* Octave Workspace Windows::
@end menu

@node I/O Dialogs
@section 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.

@cindex dialog, displaying a dialog for selecting directories
@c uigetdir scripts/gui/uigetdir.m
@anchor{XREFuigetdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{dirname} =} uigetdir ()
@deftypefnx {} {@var{dirname} =} uigetdir (@var{init_path})
@deftypefnx {} {@var{dirname} =} uigetdir (@var{init_path}, @var{dialog_name})
Open a GUI dialog for selecting a directory.

If @var{init_path} is not given the current working directory is used.

@var{dialog_name} may be used to customize the dialog title.

The output @var{dirname} is a character string with the name of the selected
directory.  However, if the @samp{Cancel} button is clicked the output is of
type double with the value @code{0}.
@xseealso{@ref{XREFuigetfile,,uigetfile}, @ref{XREFuiputfile,,uiputfile}}
@end deftypefn


@cindex dialog, displaying a dialog for selecting files
@c uigetfile scripts/gui/uigetfile.m
@anchor{XREFuigetfile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uigetfile ()
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt})
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name})
@deftypefnx {} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name}, @var{default_file})
@deftypefnx {} {[@dots{}] =} uigetfile (@dots{}, "MultiSelect", @var{mode})

Open a GUI dialog for selecting a file and return the filename @var{fname},
the path to this file @var{fpath}, and the filter index @var{fltidx}.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/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: @code{uigetfile ("myfcn.m")}

@item A single file extension @qcode{"*.ext"}
Example: @code{uigetfile ("*.ext")}

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

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

@item 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.
@end table

@var{dialog_name} can be used to customize the dialog title.

If @var{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.

Two or more files can be selected when setting the @qcode{"MultiSelect"} key
to @qcode{"on"}.  In that case, @var{fname} is a cell array containing the
files.

The outputs @var{fname} and @var{fpath} are strings returning the chosen
name and path, respectively.  However, if the @samp{Cancel} button is
clicked the outputs are of type double with a value of @code{0}.
@var{fltidx} is the index in the list of filter extensions @var{flt} that
was selected.

@xseealso{@ref{XREFuiputfile,,uiputfile}, @ref{XREFuigetdir,,uigetdir}}
@end deftypefn


@cindex dialog, displaying a dialog for storing files
@c uiputfile scripts/gui/uiputfile.m
@anchor{XREFuiputfile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile ()
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt})
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name})
@deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name}, @var{default_file})
Open a GUI dialog for selecting a file.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/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:
@code{uiputfile ("myfcn.m")}

@item @qcode{"*.ext"}
A single file extension.
Example: @code{uiputfile ("*.ext")}

@item @code{@{"*.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:
@code{uiputfile (@{"*.ext","My Description";"*.xyz", "XYZ-Format"@})}
@end table

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

@var{dialog_name} can be used to customize the dialog title.
If @var{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.

@var{fname} and @var{fpath} return the chosen name and path, respectively.
@var{fltidx} is the index in the list of filter extensions @var{flt} that
was selected.

@xseealso{@ref{XREFuigetfile,,uigetfile}, @ref{XREFuigetdir,,uigetdir}}
@end deftypefn


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

@cindex dialog, displaying an error dialog
@c errordlg scripts/gui/errordlg.m
@anchor{XREFerrordlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} errordlg ()
@deftypefnx {} {} errordlg (@var{msg})
@deftypefnx {} {} errordlg (@var{msg}, @var{title})
@deftypefnx {} {} errordlg (@var{msg}, @var{title}, @var{opt})
@deftypefnx {} {@var{h} =} errordlg (@dots{})
Display an error dialog box with error message @var{msg} and caption
@var{title}.

The default error message is @qcode{"This is the default error string.@:"}
and the default caption is @qcode{"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 @var{opt} controls the behavior of the dialog.
For details, @pxref{XREFmsgbox,,@code{msgbox}}.

The return value @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
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");
@end group
@end example

@xseealso{@ref{XREFhelpdlg,,helpdlg}, @ref{XREFwarndlg,,warndlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFquestdlg,,questdlg}}
@end deftypefn


@cindex dialog, displaying a help dialog
@c helpdlg scripts/gui/helpdlg.m
@anchor{XREFhelpdlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} helpdlg ()
@deftypefnx {} {} helpdlg (@var{msg})
@deftypefnx {} {} helpdlg (@var{msg}, @var{title})
@deftypefnx {} {@var{h} =} helpdlg (@dots{})
Display a help dialog box with help message @var{msg} and caption
@var{title}.

The default help message is @qcode{"This is the default help string.@:"}
and the default caption is @qcode{"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 @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
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");
@end group
@end example

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFwarndlg,,warndlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFquestdlg,,questdlg}}
@end deftypefn


@cindex dialog, displaying an input dialog
@c inputdlg scripts/gui/inputdlg.m
@anchor{XREFinputdlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{cstr} =} inputdlg (@var{prompt})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
@deftypefnx {} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults}, @var{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:

@table @var
@item prompt
A cell array with strings labeling each text field.  This input is required.

@item title
String to use for the caption of the dialog.  The default is
@qcode{"Input Dialog"}.

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

@enumerate
@item a scalar value which defines the number of rows used for each text
field.

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

@item 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.
@end enumerate

@item 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 @var{prompt}.

@item options
Not supported, only for @sc{matlab} compatibility.
@end table

Example:

@example
@group
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);
@end group
@end example

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFhelpdlg,,helpdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFquestdlg,,questdlg}, @ref{XREFwarndlg,,warndlg}}
@end deftypefn


@cindex dialog, displaying a list dialog
@c listdlg scripts/gui/listdlg.m
@anchor{XREFlistdlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{sel}, @var{ok}] =} listdlg (@var{key}, @var{value}, @dots{})
Return user inputs from a list dialog box in a vector of selection indices
(@var{sel}) and a flag indicating how the user closed the dialog box
(@var{ok}).

The indices in @var{sel} are 1-based.

The value of @var{ok} is 1 if the user closed the box with the OK button,
otherwise it is 0 and @var{sel} is empty.

Input arguments are specified in form of @var{key}, @var{value} pairs.
The @qcode{"ListString"} argument pair @strong{must} be specified.

Valid @var{key} and @var{value} pairs are:

@table @asis
@item @qcode{"ListString"}
a cell array of strings specifying the items to list in the dialog.

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

@item @qcode{"ListSize"}
a two-element vector @code{[@var{width}, @var{height}]} specifying the size
of the list field in pixels.  The default is [160, 300].

@item @qcode{"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).

@item @qcode{"Name"}
a string to be used as the dialog caption.  Default is "".

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

@item @qcode{"OKString"}
a string used to label the OK button.  Default is @qcode{"OK"}.

@item @qcode{"CancelString"}
a string used to label the Cancel button.  Default is @qcode{"Cancel"}.
@end table

Example:

@example
@group
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
@end group
@end example

@xseealso{@ref{XREFmenu,,menu}, @ref{XREFerrordlg,,errordlg}, @ref{XREFhelpdlg,,helpdlg}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFquestdlg,,questdlg}, @ref{XREFwarndlg,,warndlg}}
@end deftypefn


@cindex dialog, displaying a message dialog
@c msgbox scripts/gui/msgbox.m
@anchor{XREFmsgbox}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} msgbox (@var{msg})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, @var{icon})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, "custom", @var{cdata})
@deftypefnx {} {@var{h} =} msgbox (@var{msg}, @var{title}, "custom", @var{cdata}, @var{colormap})
@deftypefnx {} {@var{h} =} msgbox (@dots{}, @var{opt})
Display @var{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 @var{title} (character string) can be used to decorate
the dialog caption.

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

The final optional argument @var{opt} controls the behavior of the dialog.
If @var{opt} is a string, it may be one of

@table @asis
@item @qcode{"non-modal"} (default)
The dialog is normal.

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

@item @qcode{"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 @qcode{"non-modal"}.
@end table

If @var{opt} is a structure, it must contain fields @qcode{"WindowStyle"}
and @qcode{"Interpreter"}:

@table @asis
@item @qcode{"WindowStyle"}
The value must be @qcode{"non-modal"}, @qcode{"modal"}, or
@qcode{"replace"}.  See above.

@item @qcode{"Interpreter"}
Controls the @qcode{"interpreter"} property of the text object used for
displaying the message.  The value must be @qcode{"tex"} (default),
@qcode{"none"}, or @qcode{"latex"}.
@end table

The return value @var{h} is a handle to the figure object used for building
the dialog.

Examples:

@example
@group
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");
@end group
@end example

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFhelpdlg,,helpdlg}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFquestdlg,,questdlg}, @ref{XREFwarndlg,,warndlg}}
@end deftypefn


@cindex dialog, displaying a question dialog
@c questdlg scripts/gui/questdlg.m
@anchor{XREFquestdlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{btn} =} questdlg (@var{msg})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{default})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{default})
@deftypefnx {} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
Display @var{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 @var{title} (character string) can be used to specify the
dialog caption.  It defaults to @qcode{"Question Dialog"}.

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

The string @var{default} identifies the default button, which is activated
by pressing the @key{ENTER} key.  It must match one of the strings given
in @var{btn1}, @var{btn2}, or @var{btn3}.

If only @var{msg} and @var{title} are specified, three buttons with the
default captions @qcode{"Yes"}, @qcode{"No"}, and @qcode{"Cancel"} are used.

If only two button captions, @var{btn1} and @var{btn2}, are specified the
dialog will have only these two buttons.

Examples:

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

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFhelpdlg,,helpdlg}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFwarndlg,,warndlg}}
@end deftypefn


@cindex dialog, displaying a warning dialog
@c warndlg scripts/gui/warndlg.m
@anchor{XREFwarndlg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} warndlg ()
@deftypefnx {} {} warndlg (@var{msg})
@deftypefnx {} {} warndlg (@var{msg}, @var{title})
@deftypefnx {} {} warndlg (@var{msg}, @var{title}, @var{opt})
@deftypefnx {} {@var{h} =} warndlg (@dots{})
Display a warning dialog box with warning message @var{msg} and caption
@var{title}.

The default warning message is
@qcode{"This is the default warning string.@:"} and the default caption is
@qcode{"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 @var{opt} controls the behavior of the dialog.
For details, @pxref{XREFmsgbox,,@code{msgbox}}.

The return value @var{h} is a handle to the figure object used for
building the dialog.

Examples:

@example
@group
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");
@end group
@end example

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFhelpdlg,,helpdlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFinputdlg,,inputdlg}, @ref{XREFlistdlg,,listdlg}, @ref{XREFquestdlg,,questdlg}}
@end deftypefn


@cindex dialog, displaying a font selection dialog
@c uisetfont scripts/gui/uisetfont.m
@anchor{XREFuisetfont}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} { } uisetfont ()
@deftypefnx {} { } uisetfont (@var{h})
@deftypefnx {} { } uisetfont (@var{fontstruct})
@deftypefnx {} { } uisetfont (@dots{}, @var{title})
@deftypefnx {} {@var{fontstruct} =} uisetfont (@dots{})
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 @code{FontName},
@code{FontWeight}, @code{FontAngle}, @code{FontUnits}, and @code{FontSize},
indicating the initially selected font.

The title of the dialog window can be specified by using the last argument
@var{title}.

If an output argument @var{fontstruct} is requested, the selected font
structure is returned.  Otherwise, the font information is displayed
onscreen.

Programming Note: On systems that don't use FontConfig natively (all but
Linux), the font cache is built when Octave is installed.  You will need to
run @code{system ("fc-cache -fv")} manually after installing new fonts.

@xseealso{@ref{XREFlistfonts,,listfonts}, @ref{XREFtext,,text}, @ref{XREFaxes,,axes}, @ref{XREFuicontrol,,uicontrol}}
@end deftypefn


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

@cindex dialog, displaying a modal dialog
@c dialog scripts/gui/dialog.m
@anchor{XREFdialog}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} dialog ()
@deftypefnx {} {@var{h} =} dialog ("@var{property}", @var{value}, @dots{})

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:

@table @asis
@item buttondownfcn
@code{if isempty (allchild(gcbf)), close (gcbf), endif}

@item colormap
[]

@item color
defaultuicontrolbackgroundcolor

@item dockcontrols
off

@item handlevisibility
callback

@item integerhandle
off

@item inverthardcopy
off

@item menubar
none

@item numbertitle
off

@item paperpositionmode
auto

@item resize
off

@item windowstyle
modal

@end table


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
@ref{Figure Properties}.

The return value @var{h} is a graphics handle to the created figure.

Example:

@example
@group
## 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);
@end group
@end example

@xseealso{@ref{XREFerrordlg,,errordlg}, @ref{XREFmsgbox,,msgbox}, @ref{XREFquestdlg,,questdlg}, @ref{XREFwarndlg,,warndlg}, @ref{XREFfigure,,figure}, @ref{XREFuiwait,,uiwait}}
@end deftypefn


@node Progress Bar
@section Progress Bar
@cindex Progress Bar

@c waitbar scripts/gui/waitbar.m
@anchor{XREFwaitbar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} waitbar (@var{frac})
@deftypefnx {} {@var{h} =} waitbar (@var{frac}, @var{msg})
@deftypefnx {} {@var{h} =} waitbar (@dots{}, "createcancelbtn", @var{fcn}, @dots{})
@deftypefnx {} {@var{h} =} waitbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {} {} waitbar (@var{frac})
@deftypefnx {} {} waitbar (@var{frac}, @var{h})
@deftypefnx {} {} waitbar (@var{frac}, @var{h}, @var{msg})
Return a handle @var{h} to a new progress indicator ("waitbar") object.

The waitbar is filled to fraction @var{frac} which must be in the range
[0, 1].

The optional message @var{msg} is centered and displayed above the waitbar.

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

The appearance of the waitbar figure window can be configured by passing
@var{prop}/@var{val} pairs to the function.  The full list of properties is
documented at @ref{Figure Properties}.

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

@xseealso{@ref{XREFdelete,,delete}}
@end deftypefn


@node UI Elements
@section UI Elements

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

@c uifigure scripts/gui/uifigure.m
@anchor{XREFuifigure}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{h} =} uifigure ()
@deftypefnx {} {@var{h} =} uifigure ("@var{property}", @var{value}, @dots{})
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 @var{h} is a graphics handle to the created figure object.

Programming Note: The full list of properties is documented at
@ref{Figure Properties}.  This function differs from @code{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.
This is not perfect replacement for the @sc{matlab} uifigure object as the
properties @qcode{"AutoResizeChildren"}, @qcode{"Icon"}, and
@qcode{"Scrollable"} are not implemented.
@xseealso{@ref{XREFuipanel,,uipanel}, @ref{XREFuibuttongroup,,uibuttongroup}}
@end deftypefn


@c uipanel scripts/gui/uipanel.m
@anchor{XREFuipanel}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uipanel ()
@deftypefnx {} {@var{hui} =} uipanel (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uipanel (@var{parent})
@deftypefnx {} {@var{hui} =} uipanel (@var{parent}, @var{property}, @var{value}, @dots{})

Create a uipanel object.

uipanels are used as containers to group other uicontrol objects.

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

If @var{parent} is given then a uipanel relative to @var{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 @ref{Uipanel Properties}.

The optional return value @var{hui} is a graphics handle to the created
uipanel object.

Examples:

@example
@group
## 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]);

@end group
@end example
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuicontrol,,uicontrol}}
@end deftypefn


@c uibuttongroup scripts/gui/uibuttongroup.m
@anchor{XREFuibuttongroup}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uibuttongroup ()
@deftypefnx {} {@var{hui} =} uibuttongroup (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uibuttongroup (@var{parent})
@deftypefnx {} {@var{hui} =} uibuttongroup (@var{parent}, @var{property}, @var{value}, @dots{})
@c FIXME: 3rd form is not documented by Matlab nor implemented in Octave.
@c        Should it be removed?  (1/9/2022).
@deftypefnx {} {} uibuttongroup (@var{h})

Create a uibuttongroup object and return a handle to it.

A uibuttongroup is used to group uicontrol objects.

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

If @var{parent} is given then a uibuttongroup relative to @var{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 @ref{Uibuttongroup Properties}.

Examples:

@example
@group
## 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 ]);
@end group
@end example

When called with a single argument @var{h} which is a handle to an existing
uibuttongroup object, switch the focus to the specified uibuttongroup.  This
functionality is not currently implemented.
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuipanel,,uipanel}}
@end deftypefn


@c uicontrol scripts/gui/uicontrol.m
@anchor{XREFuicontrol}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uicontrol ()
@deftypefnx {} {@var{hui} =} uicontrol (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uicontrol (@var{parent})
@deftypefnx {} {@var{hui} =} uicontrol (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {} {} uicontrol (@var{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 @var{parent} is omitted then a uicontrol for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uicontrol relative to @var{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 @ref{Uicontrol Properties}.

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

Valid styles for uicontrol are:

@table @asis
@item @qcode{"checkbox"}
Create a checkbox control that allows user on/off selection.

@item @qcode{"edit"}
Create an edit control that allows user input of single or multiple lines
of text.

@item @qcode{"listbox"}
Create a listbox control that displays a list of items and allows user
selection of single or multiple items.

@item @qcode{"popupmenu"}
Create a popupmenu control that displays a list of options that can be
selected when the user clicks on the control.

@item @qcode{"pushbutton"}
Create a push button control that allows user to press to cause an action.

@item @qcode{"radiobutton"}
Create a radio button control intended to be used for mutually exclusive
input in a group of radiobutton controls.

@item @qcode{"slider"}
Create a slider control that allows user selection from a range of values
by sliding knob on the control.

@item @qcode{"text"}
Create a static text control to display single or multiple lines of text.

@item @qcode{"togglebutton"}
Create a toggle button control that appears like a push button but allows
the user to select between two states.

@end table

Note: For the @qcode{"edit"} and @qcode{"listbox"} styles, the single or
multiple line/selection behavior is determined by the @qcode{"Min"} and
@qcode{"Max"} properties, permitting multiple lines/selections when the
values are set such that @w{@code{Max - Min > 1}}.

Examples:

@example
@group
## 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]);
@end group
@end example

When called with a single argument @var{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 @qcode{"keypressfcn"} callback.
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuipanel,,uipanel}}
@end deftypefn


@c uitable scripts/gui/uitable.m
@anchor{XREFuitable}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uitable (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitable (@var{parent}, @var{property}, @var{value}, @dots{})
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 @var{parent} is omitted then a uitable for the current figure is
created.  If no figure is available, a new figure is created first.

If @var{parent} is given then a uitable relative to @var{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 @ref{Uitable Properties}.

Examples:

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

@group
## 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);
@end group

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

@group
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
@end group

@group
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
@end group

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

@group
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
@end group
@end smallexample

@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuicontrol,,uicontrol}}
@end deftypefn


@c uimenu scripts/gui/uimenu.m
@anchor{XREFuimenu}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uimenu (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uimenu (@var{h}, @var{property}, @var{value}, @dots{})
Create a uimenu object and return a handle to it.

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

uimenu objects have the following specific properties:

@table @asis
@item @qcode{"accelerator"}
A string containing the key, together with CTRL, to execute this
menu entry (e.g., @qcode{"x"} for CTRL+x).

@item @qcode{"checked"}
Can be set @qcode{"on"} or @qcode{"off"}.  Sets a mark at this menu entry.

@item @qcode{"enable"}
Can be set @qcode{"on"} or @qcode{"off"}.  If disabled then the menu entry
cannot be selected and is grayed out.

@item @qcode{"foregroundcolor"}
A color value for the text of the menu entry.

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

@item @qcode{"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.

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

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

@end table

The full list of properties is documented at @ref{Uimenu Properties}.

Examples:

@example
@group
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)");
@end group
@end example
@xseealso{@ref{XREFfigure,,figure}}
@end deftypefn


@c uicontextmenu scripts/gui/uicontextmenu.m
@anchor{XREFuicontextmenu}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uicontextmenu (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uicontextmenu (@var{h}, @var{property}, @var{value}, @dots{})

Create a uicontextmenu object and return a handle to it.

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

If @var{h} is given then a uicontextmenu relative to @var{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 @ref{Uicontextmenu Properties}.

Examples:

@example
@group
## 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);
@end group
@end example
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuimenu,,uimenu}}
@end deftypefn


@c uitoolbar scripts/gui/uitoolbar.m
@anchor{XREFuitoolbar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uitoolbar ()
@deftypefnx {} {@var{hui} =} uitoolbar (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitoolbar (@var{parent})
@deftypefnx {} {@var{hui} =} uitoolbar (@var{parent}, @var{property}, @var{value}, @dots{})

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

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

If @var{parent} is given then a uitoolbar relative to @var{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 @ref{Uitoolbar Properties}.

The optional return value @var{hui} is a graphics handle to the created
uitoolbar object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
@end group
@end example
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuitoggletool,,uitoggletool}, @ref{XREFuipushtool,,uipushtool}}
@end deftypefn


@c uipushtool scripts/gui/uipushtool.m
@anchor{XREFuipushtool}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uipushtool ()
@deftypefnx {} {@var{hui} =} uipushtool (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uipushtool (@var{parent})
@deftypefnx {} {@var{hui} =} uipushtool (@var{parent}, @var{property}, @var{value}, @dots{})

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 @var{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 @var{parent} is given then a uipushtool is created on the @var{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 @ref{Uipushtool Properties}.

The optional return value @var{hui} is a graphics handle to the created
uipushtool object.

Examples:

@example
@group
% 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);
@end group
@end example
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuitoolbar,,uitoolbar}, @ref{XREFuitoggletool,,uitoggletool}}
@end deftypefn


@c uitoggletool scripts/gui/uitoggletool.m
@anchor{XREFuitoggletool}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hui} =} uitoggletool ()
@deftypefnx {} {@var{hui} =} uitoggletool (@var{property}, @var{value}, @dots{})
@deftypefnx {} {@var{hui} =} uitoggletool (@var{parent})
@deftypefnx {} {@var{hui} =} uitoggletool (@var{parent}, @var{property}, @var{value}, @dots{})

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 @var{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 @var{parent} is given then a uitoggletool is created on the
@var{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 @ref{Uitoggletool Properties}.

The optional return value @var{hui} is a graphics handle to the created
uitoggletool object.

Examples:

@example
@group
% 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);
@end group
@end example
@xseealso{@ref{XREFfigure,,figure}, @ref{XREFuitoolbar,,uitoolbar}, @ref{XREFuipushtool,,uipushtool}}
@end deftypefn


@node GUI Utility Functions
@section GUI Utility Functions

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

@c guidata scripts/gui/guidata.m
@anchor{XREFguidata}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{data} =} guidata (@var{h})
@deftypefnx {} {} guidata (@var{h}, @var{data})
Query or set user-custom GUI data.

The GUI data is stored in the figure handle @var{h}.  If @var{h} is not a
figure handle then it's parent figure will be used for storage.

@var{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.

@xseealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFsetappdata,,setappdata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}}
@end deftypefn


@c guihandles scripts/gui/guihandles.m
@anchor{XREFguihandles}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hdata} =} guihandles (@var{h})
@deftypefnx {} {@var{hdata} =} guihandles
Return a structure of object handles for the figure associated with
handle @var{h}.

If no handle is specified the current figure returned by @code{gcf} is used.

The fieldname for each entry of @var{hdata} is taken from the @qcode{"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 @var{hdata} will be a vector of handles.  @code{guihandles}
includes all possible handles, including those for
which @qcode{"HandleVisibility"} is @qcode{"off"}.
@xseealso{@ref{XREFguidata,,guidata}, @ref{XREFfindobj,,findobj}, @ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}}
@end deftypefn


@c have_window_system libinterp/corefcn/display.cc
@anchor{XREFhave_window_system}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} have_window_system ()
Return true if a window system is available (X11, Windows, or Apple OS X)
and false otherwise.
@xseealso{@ref{XREFisguirunning,,isguirunning}}
@end deftypefn


@c isguirunning libinterp/octave.cc
@anchor{XREFisguirunning}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isguirunning ()
Return true if Octave is running in GUI mode and false otherwise.
@xseealso{@ref{XREFhave_window_system,,have_window_system}}
@end deftypefn


@c getpixelposition scripts/gui/getpixelposition.m
@anchor{XREFgetpixelposition}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{pos} =} getpixelposition (@var{h})
@deftypefnx {} {@var{pos} =} getpixelposition (@var{h}, @var{rel_to_fig})
Return the position of a user interface component in pixel units.

The first argument @var{h} must be a handle to a valid graphics object of
type uibuttongroup, uicontrol, uipanel, uitable, axes, or figure.  For other
object types, the function returns zeros.

By default, the position is returned relative to the object's parent.
If the second argument @var{rel_to_fig} is logically true, the position
is computed relative to the enclosing figure object.

The return value @var{pos} is a 4-element vector with values
@code{[lower_left_X, lower_left_Y, width, height]}.

@xseealso{@ref{XREFget,,get}}
@end deftypefn


@c listfonts scripts/gui/listfonts.m
@anchor{XREFlistfonts}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {fonts =} listfonts ()
@deftypefnx {} {fonts =} listfonts (@var{h})
List system fonts.

If a handle to a graphics object @var{h} is provided, also include the
font from the object's @qcode{"FontName"} property in the list.

Programming Note: On systems that don't use FontConfig natively (all but
Linux), the font cache is built when Octave is installed.  You will need to
run @code{system ("fc-cache -fv")} manually after installing new fonts.

@xseealso{@ref{XREFuisetfont,,uisetfont}, @ref{XREFtext,,text}, @ref{XREFaxes,,axes}, @ref{XREFuicontrol,,uicontrol}}
@end deftypefn


@c movegui scripts/gui/movegui.m
@anchor{XREFmovegui}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} movegui
@deftypefnx {} {} movegui (@var{h})
@deftypefnx {} {} movegui (@var{pos})
@deftypefnx {} {} movegui (@var{h}, @var{pos})
@deftypefnx {} {} movegui (@var{h}, @var{event})
@deftypefnx {} {} movegui (@var{h}, @var{event}, @var{pos})
Move a figure specified by figure handle @var{h} to a position on the screen
defined by @var{pos}.

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

@var{pos} is either a two-value numeric vector or a string.  If @var{pos} is
numeric then it must be of the form @code{[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 @var{pos} as a string are

@table @code
@item north
Top center of the screen.

@item south
Bottom center of the screen.

@item east
Right center of the screen.

@item west
Left center of the screen.

@item northeast
Top right of the screen.

@item northwest
Top left of the screen.

@item southeast
Bottom right of the screen.

@item southwest
Bottom left of the screen.

@item center
Center of the screen.

@item 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.
@end table

@var{event} contains event data that will be ignored.  This construct
facilitates a call to movegui from a callback.

@end deftypefn


@c openvar libinterp/corefcn/event-manager.cc
@anchor{XREFopenvar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} openvar (@var{name})
Open the variable @var{name} in the graphical Variable Editor.
@end deftypefn


@c uiwait scripts/gui/uiwait.m
@anchor{XREFuiwait}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} uiwait
@deftypefnx {} {} uiwait (@var{h})
@deftypefnx {} {} uiwait (@var{h}, @var{timeout})
Suspend program execution until the figure with handle @var{h} is deleted
or @code{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, @var{timeout} defines the number of seconds to wait
for the figure deletion or the @code{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 @var{timeout} is not specified,
the program execution is suspended indefinitely.
@xseealso{@ref{XREFuiresume,,uiresume}, @ref{XREFwaitfor,,waitfor}}
@end deftypefn


@c uiresume scripts/gui/uiresume.m
@anchor{XREFuiresume}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} uiresume (@var{h})
Resume program execution suspended with @code{uiwait}.

The handle @var{h} must be the same as the on specified in @code{uiwait}.
If the handle is invalid or there is no @code{uiwait} call pending for the
figure with handle @var{h}, this function does nothing.
@xseealso{@ref{XREFuiwait,,uiwait}}
@end deftypefn


@c waitfor libinterp/corefcn/graphics.cc
@anchor{XREFwaitfor}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} waitfor (@var{h})
@deftypefnx {} {} waitfor (@var{h}, @var{prop})
@deftypefnx {} {} waitfor (@var{h}, @var{prop}, @var{value})
@deftypefnx {} {} waitfor (@dots{}, "timeout", @var{timeout})
Suspend the execution of the current program until a condition is
satisfied on the graphics handle @var{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 @code{waitfor}
call is pending at the top-level.

In the first form, program execution is suspended until the graphics object
@var{h} is destroyed.  If the graphics handle is invalid or if @var{h} is
the root graphics handle and no property @var{prop} was provided, the function
returns immediately.

In the second form, execution is suspended until the graphics object is
destroyed or the property named @var{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 @var{prop} is set to @var{value}.  The
function @code{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 @var{value}, the function returns immediately.

An optional timeout can be specified using the property @qcode{"timeout"}.
This timeout value is the number of seconds to wait for the condition to be
true.  @var{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 @qcode{"timeout"}, use the string
@qcode{'@backslashchar{}timeout'} instead.

In all cases, typing CTRL-C stops program execution immediately.
@xseealso{@ref{XREFwaitforbuttonpress,,waitforbuttonpress}, @ref{XREFisequal,,isequal}}
@end deftypefn


@node User-Defined Preferences
@section User-Defined Preferences

@c getpref scripts/prefs/getpref.m
@anchor{XREFgetpref}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} getpref ("@var{group}", "@var{pref}")
@deftypefnx {} {@var{val} =} getpref ("@var{group}", "@var{pref}", @var{default})
@deftypefnx {} {@{@var{val1}, @var{val2}, @dots{}@} =} getpref ("@var{group}", @{"@var{pref1}", "@var{pref2"}, @dots{}@})
@deftypefnx {} {@var{prefstruct} =} getpref ("@var{group}")
@deftypefnx {} {@var{prefstruct} =} getpref ()
Return the preference value corresponding to the named preference @var{pref}
in the preference group @var{group}.

The named preference group must be a string.

If @var{pref} does not exist in @var{group} and @var{default} is specified,
create the preference with value @var{default} and return @var{default}.

The preference @var{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 @var{default} may be any Octave value,
.e.g., double, struct, cell array, object, etc.  Or, if @var{pref} is a cell
array of strings then @var{default} must be a cell array of values with the
same size as @var{pref}.

If neither @var{pref} nor @var{default} are specified, return a structure
of preferences for the preference group @var{group}.

If no arguments are specified, return a structure containing all groups of
preferences and their values.
@xseealso{@ref{XREFaddpref,,addpref}, @ref{XREFsetpref,,setpref}, @ref{XREFispref,,ispref}, @ref{XREFrmpref,,rmpref}}
@end deftypefn


@c setpref scripts/prefs/setpref.m
@anchor{XREFsetpref}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} setpref ("@var{group}", "@var{pref}", @var{val})
@deftypefnx {} {} setpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
Set the preference @var{pref} to the given @var{val} in the named preference
group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.

The corresponding value @var{val} may be any Octave value, .e.g., double,
struct, cell array, object, etc.  Or, if @var{pref} is a cell array of
strings then @var{val} must be a cell array of values with the same size as
@var{pref}.

If the named preference or group does not exist, it is added.
@xseealso{@ref{XREFaddpref,,addpref}, @ref{XREFgetpref,,getpref}, @ref{XREFispref,,ispref}, @ref{XREFrmpref,,rmpref}}
@end deftypefn


@c addpref scripts/prefs/addpref.m
@anchor{XREFaddpref}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} addpref ("@var{group}", "@var{pref}", @var{val})
@deftypefnx {} {} addpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
Add the preference @var{pref} and associated value @var{val} to the named
preference group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.  An
error will be issued if the preference already exists.

The corresponding value @var{val} may be any Octave value, .e.g., double,
struct, cell array, object, etc.  Or, if @var{pref} is a cell array of
strings then @var{val} must be a cell array of values with the same size as
@var{pref}.
@xseealso{@ref{XREFsetpref,,setpref}, @ref{XREFgetpref,,getpref}, @ref{XREFispref,,ispref}, @ref{XREFrmpref,,rmpref}}
@end deftypefn


@c rmpref scripts/prefs/rmpref.m
@anchor{XREFrmpref}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rmpref ("@var{group}", "@var{pref}")
@deftypefnx {} {} rmpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@})
@deftypefnx {} {} rmpref ("@var{group}")
Remove the named preference @var{pref} from the preference group
@var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or cell array of strings.

If @var{pref} is not specified, remove the preference group @var{group}.

It is an error to remove a nonexistent preference or group.
@xseealso{@ref{XREFaddpref,,addpref}, @ref{XREFispref,,ispref}, @ref{XREFsetpref,,setpref}, @ref{XREFgetpref,,getpref}}
@end deftypefn


@c ispref scripts/prefs/ispref.m
@anchor{XREFispref}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} ispref ("@var{group}", "@var{pref}")
@deftypefnx {} {@var{tf} =} ispref ("@var{group}", @{"@var{pref1}", "@var{pref2"}, @dots{}@})
@deftypefnx {} {@var{tf} =} ispref ("@var{group}")
Return true if the named preference @var{pref} exists in the preference
group @var{group}.

The named preference group must be a string.

The preference @var{pref} may be a string or a cell array of strings.

If @var{pref} is not specified, return true if the preference group
@var{group} exists.
@xseealso{@ref{XREFgetpref,,getpref}, @ref{XREFaddpref,,addpref}, @ref{XREFsetpref,,setpref}, @ref{XREFrmpref,,rmpref}}
@end deftypefn


@c prefdir scripts/prefs/prefdir.m
@anchor{XREFprefdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{dir} =} prefdir
@deftypefnx {} {@var{dir} =} prefdir (1)
Return the directory that holds the preferences for Octave.

Examples:

Display the preferences directory

@example
prefdir
@end example

Change to the preferences folder

@example
cd (prefdir)
@end example

If called with an argument, the preferences directory is created if it
doesn't already exist.
@xseealso{@ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}, @ref{XREFaddpref,,addpref}, @ref{XREFrmpref,,rmpref}, @ref{XREFispref,,ispref}}
@end deftypefn


@c preferences scripts/prefs/preferences.m
@anchor{XREFpreferences}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} preferences
Display the GUI preferences dialog window for Octave.
@end deftypefn


@node Octave Workspace Windows
@section 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.

@c commandhistory libinterp/corefcn/event-manager.cc
@anchor{XREFcommandhistory}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} commandhistory ()
Show the GUI command history window and give it the keyboard focus.
@xseealso{@ref{XREFcommandwindow,,commandwindow}, @ref{XREFfilebrowser,,filebrowser}, @ref{XREFworkspace,,workspace}}
@end deftypefn


@c commandwindow libinterp/corefcn/event-manager.cc
@anchor{XREFcommandwindow}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} commandwindow ()
Show the GUI command window and give it the keyboard focus.
@xseealso{@ref{XREFcommandhistory,,commandhistory}, @ref{XREFfilebrowser,,filebrowser}, @ref{XREFworkspace,,workspace}}
@end deftypefn


@c filebrowser libinterp/corefcn/event-manager.cc
@anchor{XREFfilebrowser}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} filebrowser ()
Show the GUI file browser window and give it the keyboard focus.
@xseealso{@ref{XREFcommandwindow,,commandwindow}, @ref{XREFcommandhistory,,commandhistory}, @ref{XREFworkspace,,workspace}}
@end deftypefn


@c workspace libinterp/corefcn/event-manager.cc
@anchor{XREFworkspace}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} workspace ()
Show the GUI workspace window and give it the keyboard focus.
@xseealso{@ref{XREFcommandwindow,,commandwindow}, @ref{XREFcommandhistory,,commandhistory}, @ref{XREFfilebrowser,,filebrowser}}
@end deftypefn