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