| 1 |
Tkinter dialogs |
| 2 |
=============== |
| 3 |
|
| 4 |
:mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs |
| 5 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6 |
|
| 7 |
.. module:: tkinter.simpledialog |
| 8 |
:synopsis: Simple dialog windows |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/tkinter/simpledialog.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
The :mod:`tkinter.simpledialog` module contains convenience classes and |
| 15 |
functions for creating simple modal dialogs to get a value from the user. |
| 16 |
|
| 17 |
|
| 18 |
.. function:: askfloat(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) |
| 19 |
askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) |
| 20 |
askstring(title, prompt, *, initialvalue=None, show=None, parent=None) |
| 21 |
|
| 22 |
Prompt the user to enter a value of the desired type and return it, or |
| 23 |
``None`` if the dialog is cancelled. |
| 24 |
|
| 25 |
*title* is the dialog title and *prompt* the message shown above the entry. |
| 26 |
*initialvalue* is the value initially placed in the entry. |
| 27 |
*parent* is the window over which the dialog is shown. |
| 28 |
:func:`askinteger` and :func:`askfloat` also accept *minvalue* and |
| 29 |
*maxvalue*, which bound the accepted value. |
| 30 |
:func:`askstring` also accepts *show*, a character used to mask the entered |
| 31 |
text, for example ``'*'`` to hide a password. |
| 32 |
|
| 33 |
.. class:: Dialog(parent, title=None) |
| 34 |
|
| 35 |
The base class for custom dialogs. |
| 36 |
Instantiating it shows the dialog modally and returns once the user closes |
| 37 |
it; the entered value is then available in the :attr:`!result` attribute. |
| 38 |
|
| 39 |
.. attribute:: result |
| 40 |
|
| 41 |
The value produced by :meth:`apply`, or ``None`` if the dialog was |
| 42 |
cancelled. |
| 43 |
|
| 44 |
.. method:: body(master) |
| 45 |
|
| 46 |
Override to construct the dialog's interface and return the widget that |
| 47 |
should have initial focus. |
| 48 |
|
| 49 |
.. method:: buttonbox() |
| 50 |
|
| 51 |
Default behaviour adds OK and Cancel buttons. Override for custom button |
| 52 |
layouts. |
| 53 |
|
| 54 |
.. method:: validate() |
| 55 |
|
| 56 |
Validate the data entered by the user. |
| 57 |
Return true if it is valid, in which case the dialog proceeds to |
| 58 |
:meth:`apply`; return false to keep the dialog open. |
| 59 |
The default implementation always returns true; override it to check the |
| 60 |
input. |
| 61 |
|
| 62 |
.. method:: apply() |
| 63 |
|
| 64 |
Process the data entered by the user, for example by storing it in the |
| 65 |
:attr:`!result` attribute. |
| 66 |
Called after :meth:`validate` succeeds and just before the dialog is |
| 67 |
destroyed. |
| 68 |
The default implementation does nothing; override it to act on or store |
| 69 |
the result. |
| 70 |
|
| 71 |
.. method:: destroy() |
| 72 |
|
| 73 |
Destroy the dialog window, clearing the reference to the widget that had |
| 74 |
the initial focus. |
| 75 |
|
| 76 |
|
| 77 |
.. class:: SimpleDialog(master, text='', buttons=[], default=None, cancel=None, title=None, class_=None) |
| 78 |
|
| 79 |
A simple modal dialog that displays the message *text* above a row of push |
| 80 |
buttons whose labels are given by *buttons*, and returns the index of the |
| 81 |
button the user presses. |
| 82 |
*default* is the index of the button activated by the Return key, *cancel* |
| 83 |
the index returned when the window is closed through the window manager, |
| 84 |
*title* the window title, and *class_* the Tk class name of the window. |
| 85 |
|
| 86 |
.. method:: go() |
| 87 |
|
| 88 |
Display the dialog, wait until the user presses a button or closes the |
| 89 |
window, and return the index of the chosen button. |
| 90 |
|
| 91 |
|
| 92 |
|
| 93 |
:mod:`tkinter.filedialog` --- File selection dialogs |
| 94 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 95 |
|
| 96 |
.. module:: tkinter.filedialog |
| 97 |
:synopsis: Dialog classes for file selection |
| 98 |
|
| 99 |
**Source code:** :source:`Lib/tkinter/filedialog.py` |
| 100 |
|
| 101 |
-------------- |
| 102 |
|
| 103 |
The :mod:`tkinter.filedialog` module provides classes and factory functions for |
| 104 |
creating file/directory selection windows. |
| 105 |
|
| 106 |
Native load/save dialogs |
| 107 |
------------------------ |
| 108 |
|
| 109 |
The following classes and functions provide file dialog windows that combine a |
| 110 |
native look-and-feel with configuration options to customize behaviour. |
| 111 |
The following keyword arguments are applicable to the classes and functions |
| 112 |
listed below: |
| 113 |
|
| 114 |
| *parent* - the window to place the dialog on top of |
| 115 |
|
| 116 |
| *title* - the title of the window |
| 117 |
|
| 118 |
| *initialdir* - the directory that the dialog starts in |
| 119 |
|
| 120 |
| *initialfile* - the file selected upon opening of the dialog |
| 121 |
|
| 122 |
| *filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed |
| 123 |
|
| 124 |
| *defaultextension* - default extension to append to file (save dialogs) |
| 125 |
|
| 126 |
| *multiple* - when true, selection of multiple items is allowed |
| 127 |
|
| 128 |
|
| 129 |
**Static factory functions** |
| 130 |
|
| 131 |
The below functions when called create a modal, native look-and-feel dialog, |
| 132 |
wait for the user's selection, and return it. |
| 133 |
The exact return value depends on the function (see below); when the dialog is |
| 134 |
cancelled it is an empty string, an empty tuple or ``None``. |
| 135 |
The precise type of this empty value may vary between platforms and Tk |
| 136 |
versions, so test the result for truth rather than comparing it with a |
| 137 |
specific value. |
| 138 |
|
| 139 |
.. function:: askopenfile(mode="r", **options) |
| 140 |
askopenfiles(mode="r", **options) |
| 141 |
|
| 142 |
Create an :class:`Open` dialog. |
| 143 |
:func:`askopenfile` returns the opened file object, or ``None`` if the |
| 144 |
dialog is cancelled. |
| 145 |
:func:`askopenfiles` returns a list of the opened file objects, or an empty |
| 146 |
tuple if cancelled. |
| 147 |
The files are opened in mode *mode* (read-only ``'r'`` by default). |
| 148 |
|
| 149 |
.. function:: asksaveasfile(mode="w", **options) |
| 150 |
|
| 151 |
Create a :class:`SaveAs` dialog and return the opened file object, or |
| 152 |
``None`` if the dialog is cancelled. |
| 153 |
The file is opened in mode *mode* (``'w'`` by default). |
| 154 |
|
| 155 |
.. function:: askopenfilename(**options) |
| 156 |
askopenfilenames(**options) |
| 157 |
|
| 158 |
Create an :class:`Open` dialog. |
| 159 |
:func:`askopenfilename` returns the selected filename as a string, or an |
| 160 |
empty string if the dialog is cancelled. |
| 161 |
:func:`askopenfilenames` returns a tuple of the selected filenames, or an |
| 162 |
empty tuple if cancelled. |
| 163 |
|
| 164 |
.. function:: asksaveasfilename(**options) |
| 165 |
|
| 166 |
Create a :class:`SaveAs` dialog and return the selected filename as a |
| 167 |
string, or an empty string if the dialog is cancelled. |
| 168 |
|
| 169 |
.. function:: askdirectory(**options) |
| 170 |
|
| 171 |
Prompt the user to select a directory, and return its path as a string, or |
| 172 |
an empty string if the dialog is cancelled. |
| 173 |
Additional keyword option: *mustexist* - if true, the user may only select |
| 174 |
an existing directory (false by default). |
| 175 |
|
| 176 |
.. class:: Open(master=None, **options) |
| 177 |
SaveAs(master=None, **options) |
| 178 |
Directory(master=None, **options) |
| 179 |
|
| 180 |
The above three classes provide native dialog windows for loading and saving |
| 181 |
files and for selecting a directory. |
| 182 |
|
| 183 |
**Convenience classes** |
| 184 |
|
| 185 |
The below classes are used for creating file/directory windows from scratch. |
| 186 |
These do not emulate the native look-and-feel of the platform. |
| 187 |
|
| 188 |
.. note:: The *FileDialog* class should be subclassed for custom event |
| 189 |
handling and behaviour. |
| 190 |
|
| 191 |
.. class:: FileDialog(master, title=None) |
| 192 |
|
| 193 |
Create a basic file selection dialog. |
| 194 |
|
| 195 |
.. method:: cancel_command(event=None) |
| 196 |
|
| 197 |
Trigger the termination of the dialog window. |
| 198 |
|
| 199 |
.. method:: dirs_double_event(event) |
| 200 |
|
| 201 |
Event handler for double-click event on directory. |
| 202 |
|
| 203 |
.. method:: dirs_select_event(event) |
| 204 |
|
| 205 |
Event handler for click event on directory. |
| 206 |
|
| 207 |
.. method:: files_double_event(event) |
| 208 |
|
| 209 |
Event handler for double-click event on file. |
| 210 |
|
| 211 |
.. method:: files_select_event(event) |
| 212 |
|
| 213 |
Event handler for single-click event on file. |
| 214 |
|
| 215 |
.. method:: filter_command(event=None) |
| 216 |
|
| 217 |
Filter the files by directory. |
| 218 |
|
| 219 |
.. method:: get_filter() |
| 220 |
|
| 221 |
Retrieve the file filter currently in use. |
| 222 |
|
| 223 |
.. method:: get_selection() |
| 224 |
|
| 225 |
Retrieve the currently selected item. |
| 226 |
|
| 227 |
.. method:: go(dir_or_file=os.curdir, pattern="*", default="", key=None) |
| 228 |
|
| 229 |
Render dialog and start event loop. |
| 230 |
|
| 231 |
.. method:: ok_event(event) |
| 232 |
|
| 233 |
Exit dialog returning current selection. |
| 234 |
|
| 235 |
.. method:: ok_command() |
| 236 |
|
| 237 |
Called when the user confirms the current selection. |
| 238 |
The base implementation accepts the selection and closes the dialog; |
| 239 |
:class:`LoadFileDialog` and :class:`SaveFileDialog` override it to check |
| 240 |
the selection first. |
| 241 |
|
| 242 |
.. method:: quit(how=None) |
| 243 |
|
| 244 |
Exit dialog returning filename, if any. |
| 245 |
|
| 246 |
.. method:: set_filter(dir, pat) |
| 247 |
|
| 248 |
Set the file filter. |
| 249 |
|
| 250 |
.. method:: set_selection(file) |
| 251 |
|
| 252 |
Update the current file selection to *file*. |
| 253 |
|
| 254 |
|
| 255 |
.. class:: LoadFileDialog(master, title=None) |
| 256 |
|
| 257 |
A subclass of FileDialog that creates a dialog window for selecting an |
| 258 |
existing file. |
| 259 |
|
| 260 |
.. method:: ok_command() |
| 261 |
|
| 262 |
Test that a file is provided and that the selection indicates an |
| 263 |
already existing file. |
| 264 |
|
| 265 |
.. class:: SaveFileDialog(master, title=None) |
| 266 |
|
| 267 |
A subclass of FileDialog that creates a dialog window for selecting a |
| 268 |
destination file. |
| 269 |
|
| 270 |
.. method:: ok_command() |
| 271 |
|
| 272 |
Test whether or not the selection points to a valid file that is not a |
| 273 |
directory. Confirmation is required if an already existing file is |
| 274 |
selected. |
| 275 |
|
| 276 |
:mod:`tkinter.commondialog` --- Dialog window templates |
| 277 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 278 |
|
| 279 |
.. module:: tkinter.commondialog |
| 280 |
:synopsis: Tkinter base class for dialogs |
| 281 |
|
| 282 |
**Source code:** :source:`Lib/tkinter/commondialog.py` |
| 283 |
|
| 284 |
-------------- |
| 285 |
|
| 286 |
The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class that |
| 287 |
is the base class for dialogs defined in other supporting modules. |
| 288 |
|
| 289 |
.. class:: Dialog(master=None, **options) |
| 290 |
|
| 291 |
.. method:: show(**options) |
| 292 |
|
| 293 |
Render the Dialog window. |
| 294 |
|
| 295 |
|
| 296 |
:mod:`!tkinter.dialog` --- Classic Tk dialog boxes |
| 297 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 298 |
|
| 299 |
.. module:: tkinter.dialog |
| 300 |
:synopsis: A simple dialog box built on the classic Tk widgets. |
| 301 |
|
| 302 |
**Source code:** :source:`Lib/tkinter/dialog.py` |
| 303 |
|
| 304 |
-------------- |
| 305 |
|
| 306 |
The :mod:`!tkinter.dialog` module provides a simple modal dialog box built on |
| 307 |
the classic (non-themed) Tk widgets. |
| 308 |
|
| 309 |
.. data:: DIALOG_ICON |
| 310 |
|
| 311 |
The name of a bitmap (``'questhead'``) suitable for use as the *bitmap* |
| 312 |
of a :class:`Dialog`. |
| 313 |
|
| 314 |
.. class:: Dialog(master=None, cnf={}, **kw) |
| 315 |
|
| 316 |
Display a modal dialog box built from the classic (non-themed) Tk widgets |
| 317 |
and wait for the user to press one of its buttons. |
| 318 |
The options, given through *cnf* or as keyword arguments, are all required: |
| 319 |
*title* (the window title), *text* (the message), *bitmap* (the name of a |
| 320 |
bitmap icon, such as :data:`DIALOG_ICON`), *default* (the index of the |
| 321 |
default button) and *strings* (the sequence of button labels). |
| 322 |
After construction, the :attr:`!num` attribute holds the index of the button |
| 323 |
the user pressed. |
| 324 |
|
| 325 |
.. method:: destroy() |
| 326 |
|
| 327 |
Do nothing. |
| 328 |
The dialog window is destroyed automatically before the constructor |
| 329 |
returns, so there is nothing left for this method to do. |
| 330 |
|
| 331 |
|
| 332 |
.. seealso:: |
| 333 |
|
| 334 |
Modules :mod:`tkinter.messagebox`, :ref:`tut-files` |