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