1@c Copyright (C) 2012-2019 Rik Wehbring
2@c
3@c This file is part of Octave.
4@c
5@c Octave is free software: you can redistribute it and/or modify it
6@c under the terms of the GNU General Public License as published by
7@c the Free Software Foundation, either version 3 of the License, or
8@c (at your option) any later version.
9@c
10@c Octave is distributed in the hope that it will be useful, but
11@c WITHOUT ANY WARRANTY; without even the implied warranty of
12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13@c GNU General Public License for more details.
14@c
15@c You should have received a copy of the GNU General Public License
16@c along with Octave; see the file COPYING.  If not, see
17@c <https://www.gnu.org/licenses/>.
18
19@node GUI Development
20@chapter GUI Development
21
22Octave is principally a batch or command-line language.  However, it does
23offer some features for constructing graphical interfaces that interact with
24users.
25
26The GUI elements available are I/O dialogs, a progress bar, and UI elements
27for plot windows.  For example, rather than hardcoding a filename for output
28results a script can open a dialog box and allow the user to choose a file.
29Similarly, if a calculation is expected to take a long time a script can
30display a progress bar.  The various UI elements can be used to fully customize
31the plot window with menubars, toolbars, context menus, pushbuttons, sliders,
32etc.
33
34Several utility functions make it possible to store private data for use with
35a GUI which will not pollute the user's variable space.
36
37Finally, a program written in Octave might want to have long term storage of
38preferences or state variables.  This can be done with user-defined
39preferences.
40
41@menu
42* I/O Dialogs::
43* Progress Bar::
44* UI Elements::
45* GUI Utility Functions::
46* User-Defined Preferences::
47* Octave Workspace Windows::
48@end menu
49
50@node I/O Dialogs
51@section I/O Dialogs
52
53Simple dialog menus are available for choosing directories or files.  They
54return a string variable which can then be used with any command requiring
55a filename.
56
57@cindex dialog, displaying a dialog for selecting directories
58@DOCSTRING(uigetdir)
59
60@cindex dialog, displaying a dialog for selecting files
61@DOCSTRING(uigetfile)
62
63@cindex dialog, displaying a dialog for storing files
64@DOCSTRING(uiputfile)
65
66Additionally, there are dialog boxes for displaying help messages, warnings, or
67errors, and for getting text input from the user.
68
69@cindex dialog, displaying an error dialog
70@DOCSTRING(errordlg)
71
72@cindex dialog, displaying a help dialog
73@DOCSTRING(helpdlg)
74
75@cindex dialog, displaying an input dialog
76@DOCSTRING(inputdlg)
77
78@cindex dialog, displaying a list dialog
79@DOCSTRING(listdlg)
80
81@cindex dialog, displaying a message dialog
82@DOCSTRING(msgbox)
83
84@cindex dialog, displaying a question dialog
85@DOCSTRING(questdlg)
86
87@cindex dialog, displaying a warning dialog
88@DOCSTRING(warndlg)
89
90@cindex dialog, displaying a font selection dialog
91@DOCSTRING(uisetfont)
92
93For creating new dialog types, there is a dialog function.
94
95@cindex dialog, displaying a modal dialog
96@DOCSTRING(dialog)
97
98@node Progress Bar
99@section Progress Bar
100@cindex Progress Bar
101
102@DOCSTRING(waitbar)
103
104@node UI Elements
105@section UI Elements
106
107The @nospell{ui*} series of functions work best with the @code{qt} graphics
108toolkit, although some functionality is available with the @code{fltk} toolkit.
109There is no support for the @code{gnuplot} toolkit.
110
111@DOCSTRING(uipanel)
112
113@DOCSTRING(uibuttongroup)
114
115@DOCSTRING(uicontrol)
116
117@DOCSTRING(uitable)
118
119@DOCSTRING(uimenu)
120
121@DOCSTRING(uicontextmenu)
122
123@DOCSTRING(uitoolbar)
124
125@DOCSTRING(uipushtool)
126
127@DOCSTRING(uitoggletool)
128
129@node GUI Utility Functions
130@section GUI Utility Functions
131
132These functions do not implement a GUI element but are useful when developing
133programs that do.  The functions @code{uiwait}, @code{uiresume}, and
134@code{waitfor} are only available with the @code{qt} or @code{fltk} toolkits.
135
136@DOCSTRING(guidata)
137
138@DOCSTRING(guihandles)
139
140@DOCSTRING(have_window_system)
141
142@DOCSTRING(isguirunning)
143
144@DOCSTRING(movegui)
145
146@DOCSTRING(openvar)
147
148@DOCSTRING(uiwait)
149
150@DOCSTRING(uiresume)
151
152@DOCSTRING(waitfor)
153
154@node User-Defined Preferences
155@section User-Defined Preferences
156
157@DOCSTRING(getpref)
158
159@DOCSTRING(setpref)
160
161@DOCSTRING(addpref)
162
163@DOCSTRING(rmpref)
164
165@DOCSTRING(ispref)
166
167@DOCSTRING(prefdir)
168
169@DOCSTRING(preferences)
170
171@node Octave Workspace Windows
172@section Octave Workspace Windows
173
174The functions below make windows that are a part of Octave's own GUI interface
175visible, and move the keyboard focus to the selected window.  Their utility
176lies in the ability to call these functions from a script and highlight a
177window without using a mouse for selection.
178
179@DOCSTRING(commandhistory)
180
181@DOCSTRING(commandwindow)
182
183@DOCSTRING(filebrowser)
184
185@DOCSTRING(workspace)
186
187