@c Copyright (C) 2012-2022 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
@DOCSTRING(uigetdir)

@cindex dialog, displaying a dialog for selecting files
@DOCSTRING(uigetfile)

@cindex dialog, displaying a dialog for storing files
@DOCSTRING(uiputfile)

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
@DOCSTRING(errordlg)

@cindex dialog, displaying a help dialog
@DOCSTRING(helpdlg)

@cindex dialog, displaying an input dialog
@DOCSTRING(inputdlg)

@cindex dialog, displaying a list dialog
@DOCSTRING(listdlg)

@cindex dialog, displaying a message dialog
@DOCSTRING(msgbox)

@cindex dialog, displaying a question dialog
@DOCSTRING(questdlg)

@cindex dialog, displaying a warning dialog
@DOCSTRING(warndlg)

@cindex dialog, displaying a font selection dialog
@DOCSTRING(uisetfont)

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

@cindex dialog, displaying a modal dialog
@DOCSTRING(dialog)

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

@DOCSTRING(waitbar)

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

@DOCSTRING(uifigure)

@DOCSTRING(uipanel)

@DOCSTRING(uibuttongroup)

@DOCSTRING(uicontrol)

@DOCSTRING(uitable)

@DOCSTRING(uimenu)

@DOCSTRING(uicontextmenu)

@DOCSTRING(uitoolbar)

@DOCSTRING(uipushtool)

@DOCSTRING(uitoggletool)

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

@DOCSTRING(guidata)

@DOCSTRING(guihandles)

@DOCSTRING(have_window_system)

@DOCSTRING(isguirunning)

@DOCSTRING(getpixelposition)

@DOCSTRING(listfonts)

@DOCSTRING(movegui)

@DOCSTRING(openvar)

@DOCSTRING(uiwait)

@DOCSTRING(uiresume)

@DOCSTRING(waitfor)

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

@DOCSTRING(getpref)

@DOCSTRING(setpref)

@DOCSTRING(addpref)

@DOCSTRING(rmpref)

@DOCSTRING(ispref)

@DOCSTRING(prefdir)

@DOCSTRING(preferences)

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

@DOCSTRING(commandhistory)

@DOCSTRING(commandwindow)

@DOCSTRING(filebrowser)

@DOCSTRING(workspace)