1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GUI Utility Functions (GNU Octave (version 10.3.0))</title>
<meta name="description" content="GUI Utility Functions (GNU Octave (version 10.3.0))">
<meta name="keywords" content="GUI Utility Functions (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="GUI-Development.html" rel="up" title="GUI Development">
<link href="User_002dDefined-Preferences.html" rel="next" title="User-Defined Preferences">
<link href="UI-Elements.html" rel="prev" title="UI Elements">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section-level-extent" id="GUI-Utility-Functions">
<div class="nav-panel">
<p>
Next: <a href="User_002dDefined-Preferences.html" accesskey="n" rel="next">User-Defined Preferences</a>, Previous: <a href="UI-Elements.html" accesskey="p" rel="prev">UI Elements</a>, Up: <a href="GUI-Development.html" accesskey="u" rel="up">GUI Development</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="GUI-Utility-Functions-1"><span>35.4 GUI Utility Functions<a class="copiable-link" href="#GUI-Utility-Functions-1"> ¶</a></span></h3>
<p>These functions do not implement a GUI element but are useful when developing
programs that do. The functions <code class="code">uiwait</code>, <code class="code">uiresume</code>, and
<code class="code">waitfor</code> are only available with the <code class="code">qt</code> or <code class="code">fltk</code> toolkits.
</p>
<a class="anchor" id="XREFguidata"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-guidata"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">guidata</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-guidata"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-guidata-1"><span><strong class="def-name">guidata</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">data</var>)</code><a class="copiable-link" href="#index-guidata-1"> ¶</a></span></dt>
<dd><p>Query or set user-custom GUI data.
</p>
<p>The GUI data is stored in the figure handle <var class="var">h</var>. If <var class="var">h</var> is not a
figure handle then it’s parent figure will be used for storage.
</p>
<p><var class="var">data</var> 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.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Application_002ddefined-Data.html#XREFgetappdata">getappdata</a>, <a class="ref" href="Application_002ddefined-Data.html#XREFsetappdata">setappdata</a>, <a class="ref" href="Handle-Functions.html#XREFget">get</a>, <a class="ref" href="Handle-Functions.html#XREFset">set</a>, <a class="ref" href="User_002dDefined-Preferences.html#XREFgetpref">getpref</a>, <a class="ref" href="User_002dDefined-Preferences.html#XREFsetpref">setpref</a>.
</p></dd></dl>
<a class="anchor" id="XREFguihandles"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-guihandles"><span><code class="def-type"><var class="var">hdata</var> =</code> <strong class="def-name">guihandles</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-guihandles"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-guihandles-1"><span><code class="def-type"><var class="var">hdata</var> =</code> <strong class="def-name">guihandles</strong><a class="copiable-link" href="#index-guihandles-1"> ¶</a></span></dt>
<dd><p>Return a structure of object handles for the figure associated with
handle <var class="var">h</var>.
</p>
<p>If no handle is specified the current figure returned by <code class="code">gcf</code> is used.
</p>
<p>The fieldname for each entry of <var class="var">hdata</var> is taken from the <code class="code">"tag"</code>
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 class="var">hdata</var> will be a vector of handles. <code class="code">guihandles</code>
includes all possible handles, including those for
which <code class="code">"HandleVisibility"</code> is <code class="code">"off"</code>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFguidata">guidata</a>, <a class="ref" href="Searching-Properties.html#XREFfindobj">findobj</a>, <a class="ref" href="Searching-Properties.html#XREFfindall">findall</a>, <a class="ref" href="Handle-Functions.html#XREFallchild">allchild</a>.
</p></dd></dl>
<a class="anchor" id="XREFhave_005fwindow_005fsystem"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-have_005fwindow_005fsystem"><span><code class="def-type"><var class="var">tf</var> =</code> <strong class="def-name">have_window_system</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-have_005fwindow_005fsystem"> ¶</a></span></dt>
<dd><p>Return true if a window system is available (X11, Windows, or Apple OS X)
and false otherwise.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFisguirunning">isguirunning</a>.
</p></dd></dl>
<a class="anchor" id="XREFisguirunning"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-isguirunning"><span><code class="def-type"><var class="var">tf</var> =</code> <strong class="def-name">isguirunning</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-isguirunning"> ¶</a></span></dt>
<dd><p>Return true if Octave is running in GUI mode and false otherwise.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFhave_005fwindow_005fsystem">have_window_system</a>.
</p></dd></dl>
<a class="anchor" id="XREFgetpixelposition"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-getpixelposition"><span><code class="def-type"><var class="var">pos</var> =</code> <strong class="def-name">getpixelposition</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-getpixelposition"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-getpixelposition-1"><span><code class="def-type"><var class="var">pos</var> =</code> <strong class="def-name">getpixelposition</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">rel_to_fig</var>)</code><a class="copiable-link" href="#index-getpixelposition-1"> ¶</a></span></dt>
<dd><p>Return the position of a user interface component in pixel units.
</p>
<p>The first argument <var class="var">h</var> 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.
</p>
<p>By default, the position is returned relative to the object’s parent.
If the second argument <var class="var">rel_to_fig</var> is logically true, the position
is computed relative to the enclosing figure object.
</p>
<p>The return value <var class="var">pos</var> is a 4-element vector with values
<code class="code">[lower_left_X, lower_left_Y, width, height]</code>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Handle-Functions.html#XREFget">get</a>.
</p></dd></dl>
<a class="anchor" id="XREFlistfonts"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-listfonts"><span><code class="def-type">fonts =</code> <strong class="def-name">listfonts</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-listfonts"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-listfonts-1"><span><code class="def-type">fonts =</code> <strong class="def-name">listfonts</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-listfonts-1"> ¶</a></span></dt>
<dd><p>List system fonts.
</p>
<p>If a handle to a graphics object <var class="var">h</var> is provided, also include the
font from the object’s <code class="code">"FontName"</code> property in the list.
</p>
<p>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 class="code">system ("fc-cache -fv")</code> manually after installing new fonts.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="I_002fO-Dialogs.html#XREFuisetfont">uisetfont</a>, <a class="ref" href="Plot-Annotations.html#XREFtext">text</a>, <a class="ref" href="Creating-Graphics-Objects.html#XREFaxes">axes</a>, <a class="ref" href="UI-Elements.html#XREFuicontrol">uicontrol</a>.
</p></dd></dl>
<a class="anchor" id="XREFmovegui"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-movegui"><span><strong class="def-name">movegui</strong><a class="copiable-link" href="#index-movegui"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-movegui-1"><span><strong class="def-name">movegui</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-movegui-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-movegui-2"><span><strong class="def-name">movegui</strong> <code class="def-code-arguments">(<var class="var">pos</var>)</code><a class="copiable-link" href="#index-movegui-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-movegui-3"><span><strong class="def-name">movegui</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">pos</var>)</code><a class="copiable-link" href="#index-movegui-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-movegui-4"><span><strong class="def-name">movegui</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">event</var>)</code><a class="copiable-link" href="#index-movegui-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-movegui-5"><span><strong class="def-name">movegui</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">event</var>, <var class="var">pos</var>)</code><a class="copiable-link" href="#index-movegui-5"> ¶</a></span></dt>
<dd><p>Move a figure specified by figure handle <var class="var">h</var> to a position on the screen
defined by <var class="var">pos</var>.
</p>
<p><var class="var">h</var> is a figure handle, or a handle to a graphics object. In the latter
case, its parent figure will be used. If unspecified, <var class="var">h</var> will be
set to the handle of the relevant figure if a callback is being executed
(<code class="code">gcbf</code>), otherwise it will be set to the handle of the current figure
(<code class="code">gcf</code>).
</p>
<p><var class="var">pos</var> is either a two-value numeric vector or a string. If <var class="var">pos</var> is
numeric then it must be of the form <code class="code">[h, v]</code> 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.
</p>
<p>Possible values for <var class="var">pos</var> as a string are
</p>
<dl class="table">
<dt><code class="code">north</code></dt>
<dd><p>Top center of the screen.
</p>
</dd>
<dt><code class="code">south</code></dt>
<dd><p>Bottom center of the screen.
</p>
</dd>
<dt><code class="code">east</code></dt>
<dd><p>Right center of the screen.
</p>
</dd>
<dt><code class="code">west</code></dt>
<dd><p>Left center of the screen.
</p>
</dd>
<dt><code class="code">northeast</code></dt>
<dd><p>Top right of the screen.
</p>
</dd>
<dt><code class="code">northwest</code></dt>
<dd><p>Top left of the screen.
</p>
</dd>
<dt><code class="code">southeast</code></dt>
<dd><p>Bottom right of the screen.
</p>
</dd>
<dt><code class="code">southwest</code></dt>
<dd><p>Bottom left of the screen.
</p>
</dd>
<dt><code class="code">center</code></dt>
<dd><p>Center of the screen.
</p>
</dd>
<dt><code class="code">onscreen (default)</code></dt>
<dd><p>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.
</p></dd>
</dl>
<p><var class="var">event</var> contains event data that will be ignored. This construct
facilitates a call to movegui from a callback.
</p>
</dd></dl>
<a class="anchor" id="XREFopenvar"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-openvar"><span><strong class="def-name">openvar</strong> <code class="def-code-arguments">(<var class="var">name</var>)</code><a class="copiable-link" href="#index-openvar"> ¶</a></span></dt>
<dd><p>Open the variable <var class="var">name</var> in the graphical Variable Editor.
</p></dd></dl>
<a class="anchor" id="XREFuiwait"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-uiwait"><span><strong class="def-name">uiwait</strong><a class="copiable-link" href="#index-uiwait"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-uiwait-1"><span><strong class="def-name">uiwait</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-uiwait-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-uiwait-2"><span><strong class="def-name">uiwait</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">timeout</var>)</code><a class="copiable-link" href="#index-uiwait-2"> ¶</a></span></dt>
<dd><p>Suspend program execution until the figure with handle <var class="var">h</var> is deleted
or <code class="code">uiresume</code> is called.
</p>
<p>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.
</p>
<p>When specified, <var class="var">timeout</var> defines the number of seconds to wait
for the figure deletion or the <code class="code">uiresume</code> 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 class="var">timeout</var> is not specified,
the program execution is suspended indefinitely.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFuiresume">uiresume</a>, <a class="ref" href="#XREFwaitfor">waitfor</a>.
</p></dd></dl>
<a class="anchor" id="XREFuiresume"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-uiresume"><span><strong class="def-name">uiresume</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-uiresume"> ¶</a></span></dt>
<dd><p>Resume program execution suspended with <code class="code">uiwait</code>.
</p>
<p>The handle <var class="var">h</var> must be the same as the on specified in <code class="code">uiwait</code>.
If the handle is invalid or there is no <code class="code">uiwait</code> call pending for the
figure with handle <var class="var">h</var>, this function does nothing.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFuiwait">uiwait</a>.
</p></dd></dl>
<a class="anchor" id="XREFwaitfor"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-waitfor"><span><strong class="def-name">waitfor</strong> <code class="def-code-arguments">(<var class="var">h</var>)</code><a class="copiable-link" href="#index-waitfor"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-waitfor-1"><span><strong class="def-name">waitfor</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">prop</var>)</code><a class="copiable-link" href="#index-waitfor-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-waitfor-2"><span><strong class="def-name">waitfor</strong> <code class="def-code-arguments">(<var class="var">h</var>, <var class="var">prop</var>, <var class="var">value</var>)</code><a class="copiable-link" href="#index-waitfor-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-waitfor-3"><span><strong class="def-name">waitfor</strong> <code class="def-code-arguments">(…, "timeout", <var class="var">timeout</var>)</code><a class="copiable-link" href="#index-waitfor-3"> ¶</a></span></dt>
<dd><p>Suspend the execution of the current program until a condition is
satisfied on the graphics handle <var class="var">h</var>.
</p>
<p>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 class="code">waitfor</code>
call is pending at the top-level.
</p>
<p>In the first form, program execution is suspended until the graphics object
<var class="var">h</var> is destroyed. If the graphics handle is invalid or if <var class="var">h</var> is
the root graphics handle and no property <var class="var">prop</var> was provided, the function
returns immediately.
</p>
<p>In the second form, execution is suspended until the graphics object is
destroyed or the property named <var class="var">prop</var> is modified. If the graphics
handle is invalid or the property does not exist, the function returns
immediately.
</p>
<p>In the third form, execution is suspended until the graphics object is
destroyed or the property named <var class="var">prop</var> is set to <var class="var">value</var>. The
function <code class="code">isequal</code> 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 class="var">value</var>, the function returns immediately.
</p>
<p>An optional timeout can be specified using the property <code class="code">"timeout"</code>.
This timeout value is the number of seconds to wait for the condition to be
true. <var class="var">timeout</var> 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.
</p>
<p>To define a condition on a property named <code class="code">"timeout"</code>, use the string
<code class="code">'\timeout'</code> instead.
</p>
<p>In all cases, typing CTRL-C stops program execution immediately.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Interacting-with-Plots.html#XREFwaitforbuttonpress">waitforbuttonpress</a>, <a class="ref" href="Comparison-Ops.html#XREFisequal">isequal</a>.
</p></dd></dl>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="User_002dDefined-Preferences.html">User-Defined Preferences</a>, Previous: <a href="UI-Elements.html">UI Elements</a>, Up: <a href="GUI-Development.html">GUI Development</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
