1.. currentmodule:: dialog
2
3.. _widgets:
4
5The :class:`Dialog` widgets
6===========================
7
8This section describes all widgets (or dialog boxes) offered by the
9:class:`Dialog` class. The descriptions of many of them are adapted from the
10:manpage:`dialog(1)` manual page, with the kind permission of `Thomas Dickey
11<https://invisible-island.net/>`_.
12
13
14.. note::
15
16  All unqualified method names in this section are methods of the
17  :class:`Dialog` class. In other words, whenever a method :meth:`!foo` is
18  mentioned, you have to understand :meth:`!dialog.Dialog.foo`.
19
20.. warning::
21
22  Concerning the older widgets that have fixed defaults for the length
23  parameters such as *width* and *height*:
24
25  Even though explicitely setting one of these length parameters to ``None``
26  will not cause any error in this version, please don't do it. If you know
27  the size you want, specify it directly (e.g., ``width=78``). On the other
28  hand, if you want :program:`dialog` to automagically figure out a suitable
29  size, you have two options:
30
31    - either enable the :ref:`autowidgetsize <autowidgetsize>` option and
32      make sure not to specify the length parameter in the widget call;
33    - or explicitely set it to ``0`` (e.g., ``width=0``).
34
35
36Displaying multi-line text
37--------------------------
38
39Message box
40^^^^^^^^^^^
41
42.. automethod:: Dialog.msgbox
43
44.. figure:: screenshots/msgbox.png
45   :align: center
46
47   :meth:`~Dialog.msgbox` example
48
49
50Text box
51^^^^^^^^
52
53.. automethod:: Dialog.textbox
54
55.. figure:: screenshots/textbox.png
56   :align: center
57
58   :meth:`~Dialog.textbox` example
59
60
61Scroll box
62^^^^^^^^^^
63
64.. Automethod:: Dialog.scrollbox
65
66.. figure:: screenshots/scrollbox.png
67   :align: center
68
69   :meth:`~Dialog.scrollbox` example
70
71
72Edit box
73^^^^^^^^
74
75.. automethod:: Dialog.editbox
76
77.. figure:: screenshots/editbox.png
78   :align: center
79
80   :meth:`~Dialog.editbox` example
81
82.. automethod:: Dialog.editbox_str
83
84
85Progress box
86^^^^^^^^^^^^
87
88.. automethod:: Dialog.progressbox
89
90.. figure:: screenshots/progressbox.png
91   :align: center
92
93   :meth:`~Dialog.progressbox` example
94
95
96Program box
97^^^^^^^^^^^
98
99.. automethod:: Dialog.programbox
100
101.. figure:: screenshots/programbox.png
102   :align: center
103
104   :meth:`~Dialog.programbox` example
105
106
107Tail box
108^^^^^^^^
109
110.. automethod:: Dialog.tailbox
111
112.. figure:: screenshots/tailbox.png
113   :align: center
114
115   :meth:`~Dialog.tailbox` example
116
117
118
119Displaying transient messages
120-----------------------------
121
122Info box
123^^^^^^^^
124
125.. automethod:: Dialog.infobox
126
127.. figure:: screenshots/infobox.png
128   :align: center
129
130   :meth:`~Dialog.infobox` example
131
132
133Pause
134^^^^^
135
136.. automethod:: Dialog.pause
137
138.. figure:: screenshots/pause.png
139   :align: center
140
141   :meth:`~Dialog.pause` example
142
143
144Progress meters
145---------------
146
147.. _gauge-widget:
148
149Regular gauge
150^^^^^^^^^^^^^
151
152.. automethod:: Dialog.gauge_start
153
154.. automethod:: Dialog.gauge_update
155
156.. automethod:: Dialog.gauge_iterate
157
158.. automethod:: Dialog.gauge_stop
159
160.. figure:: screenshots/gauge.png
161   :align: center
162
163   :meth:`~Dialog.gauge` example
164
165
166Mixed gauge
167^^^^^^^^^^^
168
169.. automethod:: Dialog.mixedgauge
170
171.. figure:: screenshots/mixedgauge.png
172   :align: center
173
174   :meth:`~Dialog.mixedgauge` example
175
176
177List-like widgets
178-----------------
179
180Build list
181^^^^^^^^^^
182
183.. automethod:: Dialog.buildlist
184
185.. figure:: screenshots/buildlist.png
186   :align: center
187
188   :meth:`~Dialog.buildlist` example
189
190
191Check list
192^^^^^^^^^^
193
194.. automethod:: Dialog.checklist
195
196.. figure:: screenshots/checklist.png
197   :align: center
198
199   :meth:`~Dialog.checklist` example
200
201
202Menu
203^^^^
204
205.. automethod:: Dialog.menu
206
207.. figure:: screenshots/menu.png
208   :align: center
209
210   :meth:`~Dialog.menu` example
211
212
213Radio list
214^^^^^^^^^^
215
216.. automethod:: Dialog.radiolist
217
218.. figure:: screenshots/radiolist.png
219   :align: center
220
221   :meth:`~Dialog.radiolist` example
222
223
224Tree view
225^^^^^^^^^
226
227.. automethod:: Dialog.treeview
228
229.. figure:: screenshots/treeview.png
230   :align: center
231
232   :meth:`~Dialog.treeview` example
233
234
235
236Single-line input fields
237------------------------
238
239Input box
240^^^^^^^^^
241
242.. automethod:: Dialog.inputbox
243
244.. figure:: screenshots/inputbox.png
245   :align: center
246
247   :meth:`~Dialog.inputbox` example
248
249
250Input menu
251^^^^^^^^^^
252
253.. automethod:: Dialog.inputmenu
254
255.. figure:: screenshots/inputmenu.png
256   :align: center
257
258   :meth:`~Dialog.inputmenu` example
259
260
261Password box
262^^^^^^^^^^^^
263
264.. automethod:: Dialog.passwordbox
265
266.. figure:: screenshots/passwordbox.png
267   :align: center
268
269   :meth:`~Dialog.passwordbox` example
270
271
272
273Forms
274-----
275
276Form
277^^^^
278
279.. automethod:: Dialog.form
280
281.. figure:: screenshots/form.png
282   :align: center
283
284   :meth:`~Dialog.form` example
285
286
287Mixed form
288^^^^^^^^^^
289
290.. automethod:: Dialog.mixedform
291
292.. figure:: screenshots/mixedform.png
293   :align: center
294
295   :meth:`~Dialog.mixedform` example
296
297
298Password form
299^^^^^^^^^^^^^
300
301.. automethod:: Dialog.passwordform
302
303.. figure:: screenshots/passwordform.png
304   :align: center
305
306   :meth:`~Dialog.passwordform` example
307
308
309Selecting files and directories
310-------------------------------
311
312Directory selection
313^^^^^^^^^^^^^^^^^^^
314
315.. automethod:: Dialog.dselect
316
317.. figure:: screenshots/dselect.png
318   :align: center
319
320   :meth:`~Dialog.dselect` example
321
322
323File or directory selection
324^^^^^^^^^^^^^^^^^^^^^^^^^^^
325
326.. automethod:: Dialog.fselect
327
328.. figure:: screenshots/fselect.png
329   :align: center
330
331   :meth:`~Dialog.fselect` example
332
333
334Date and time
335-------------
336
337Calendar
338^^^^^^^^
339
340.. automethod:: Dialog.calendar
341
342.. figure:: screenshots/calendar.png
343   :align: center
344
345   :meth:`~Dialog.calendar` example
346
347
348Time box
349^^^^^^^^
350
351.. automethod:: Dialog.timebox
352
353.. figure:: screenshots/timebox.png
354   :align: center
355
356   :meth:`~Dialog.timebox` example
357
358
359Miscellaneous
360-------------
361
362Range box
363^^^^^^^^^
364
365.. automethod:: Dialog.rangebox
366
367.. figure:: screenshots/rangebox.png
368   :align: center
369
370   :meth:`~Dialog.rangebox` example
371
372
373Yes/No
374^^^^^^
375
376.. automethod:: Dialog.yesno
377
378.. figure:: screenshots/yesno.png
379   :align: center
380
381   :meth:`~Dialog.yesno` example
382