| 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, **kw) |
| 19 |
askinteger(title, prompt, **kw) |
| 20 |
askstring(title, prompt, **kw) |
| 21 |
|
| 22 |
The above three functions provide dialogs that prompt the user to enter a value |
| 23 |
of the desired type. |
| 24 |
|
| 25 |
.. class:: Dialog(parent, title=None) |
| 26 |
|
| 27 |
The base class for custom dialogs. |
| 28 |
|
| 29 |
.. method:: body(master) |
| 30 |
|
| 31 |
Override to construct the dialog's interface and return the widget that |
| 32 |
should have initial focus. |
| 33 |
|
| 34 |
.. method:: buttonbox() |
| 35 |
|
| 36 |
Default behaviour adds OK and Cancel buttons. Override for custom button |
| 37 |
layouts. |
| 38 |
|
| 39 |
|
| 40 |
|
| 41 |
:mod:`!tkinter.filedialog` --- File selection dialogs |
| 42 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 43 |
|
| 44 |
.. module:: tkinter.filedialog |
| 45 |
:synopsis: Dialog classes for file selection |
| 46 |
|
| 47 |
**Source code:** :source:`Lib/tkinter/filedialog.py` |
| 48 |
|
| 49 |
-------------- |
| 50 |
|
| 51 |
The :mod:`!tkinter.filedialog` module provides classes and factory functions for |
| 52 |
creating file/directory selection windows. |
| 53 |
|
| 54 |
Native Load/Save Dialogs |
| 55 |
------------------------ |
| 56 |
|
| 57 |
The following classes and functions provide file dialog windows that combine a |
| 58 |
native look-and-feel with configuration options to customize behaviour. |
| 59 |
The following keyword arguments are applicable to the classes and functions |
| 60 |
listed below: |
| 61 |
|
| 62 |
| *parent* - the window to place the dialog on top of |
| 63 |
|
| 64 |
| *title* - the title of the window |
| 65 |
|
| 66 |
| *initialdir* - the directory that the dialog starts in |
| 67 |
|
| 68 |
| *initialfile* - the file selected upon opening of the dialog |
| 69 |
|
| 70 |
| *filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed |
| 71 |
|
| 72 |
| *defaultextension* - default extension to append to file (save dialogs) |
| 73 |
|
| 74 |
| *multiple* - when true, selection of multiple items is allowed |
| 75 |
|
| 76 |
|
| 77 |
**Static factory functions** |
| 78 |
|
| 79 |
The below functions when called create a modal, native look-and-feel dialog, |
| 80 |
wait for the user's selection, then return the selected value(s) or ``None`` to the |
| 81 |
caller. |
| 82 |
|
| 83 |
.. function:: askopenfile(mode="r", **options) |
| 84 |
askopenfiles(mode="r", **options) |
| 85 |
|
| 86 |
The above two functions create an :class:`Open` dialog and return the opened |
| 87 |
file object(s) in read-only mode. |
| 88 |
|
| 89 |
.. function:: asksaveasfile(mode="w", **options) |
| 90 |
|
| 91 |
Create a :class:`SaveAs` dialog and return a file object opened in write-only mode. |
| 92 |
|
| 93 |
.. function:: askopenfilename(**options) |
| 94 |
askopenfilenames(**options) |
| 95 |
|
| 96 |
The above two functions create an :class:`Open` dialog and return the |
| 97 |
selected filename(s) that correspond to existing file(s). |
| 98 |
|
| 99 |
.. function:: asksaveasfilename(**options) |
| 100 |
|
| 101 |
Create a :class:`SaveAs` dialog and return the selected filename. |
| 102 |
|
| 103 |
.. function:: askdirectory(**options) |
| 104 |
|
| 105 |
| Prompt user to select a directory. |
| 106 |
| Additional keyword option: |
| 107 |
| *mustexist* - determines if selection must be an existing directory. |
| 108 |
|
| 109 |
.. class:: Open(master=None, **options) |
| 110 |
SaveAs(master=None, **options) |
| 111 |
|
| 112 |
The above two classes provide native dialog windows for saving and loading |
| 113 |
files. |
| 114 |
|
| 115 |
**Convenience classes** |
| 116 |
|
| 117 |
The below classes are used for creating file/directory windows from scratch. |
| 118 |
These do not emulate the native look-and-feel of the platform. |
| 119 |
|
| 120 |
.. class:: Directory(master=None, **options) |
| 121 |
|
| 122 |
Create a dialog prompting the user to select a directory. |
| 123 |
|
| 124 |
.. note:: The *FileDialog* class should be subclassed for custom event |
| 125 |
handling and behaviour. |
| 126 |
|
| 127 |
.. class:: FileDialog(master, title=None) |
| 128 |
|
| 129 |
Create a basic file selection dialog. |
| 130 |
|
| 131 |
.. method:: cancel_command(event=None) |
| 132 |
|
| 133 |
Trigger the termination of the dialog window. |
| 134 |
|
| 135 |
.. method:: dirs_double_event(event) |
| 136 |
|
| 137 |
Event handler for double-click event on directory. |
| 138 |
|
| 139 |
.. method:: dirs_select_event(event) |
| 140 |
|
| 141 |
Event handler for click event on directory. |
| 142 |
|
| 143 |
.. method:: files_double_event(event) |
| 144 |
|
| 145 |
Event handler for double-click event on file. |
| 146 |
|
| 147 |
.. method:: files_select_event(event) |
| 148 |
|
| 149 |
Event handler for single-click event on file. |
| 150 |
|
| 151 |
.. method:: filter_command(event=None) |
| 152 |
|
| 153 |
Filter the files by directory. |
| 154 |
|
| 155 |
.. method:: get_filter() |
| 156 |
|
| 157 |
Retrieve the file filter currently in use. |
| 158 |
|
| 159 |
.. method:: get_selection() |
| 160 |
|
| 161 |
Retrieve the currently selected item. |
| 162 |
|
| 163 |
.. method:: go(dir_or_file=os.curdir, pattern="*", default="", key=None) |
| 164 |
|
| 165 |
Render dialog and start event loop. |
| 166 |
|
| 167 |
.. method:: ok_event(event) |
| 168 |
|
| 169 |
Exit dialog returning current selection. |
| 170 |
|
| 171 |
.. method:: quit(how=None) |
| 172 |
|
| 173 |
Exit dialog returning filename, if any. |
| 174 |
|
| 175 |
.. method:: set_filter(dir, pat) |
| 176 |
|
| 177 |
Set the file filter. |
| 178 |
|
| 179 |
.. method:: set_selection(file) |
| 180 |
|
| 181 |
Update the current file selection to *file*. |
| 182 |
|
| 183 |
|
| 184 |
.. class:: LoadFileDialog(master, title=None) |
| 185 |
|
| 186 |
A subclass of FileDialog that creates a dialog window for selecting an |
| 187 |
existing file. |
| 188 |
|
| 189 |
.. method:: ok_command() |
| 190 |
|
| 191 |
Test that a file is provided and that the selection indicates an |
| 192 |
already existing file. |
| 193 |
|
| 194 |
.. class:: SaveFileDialog(master, title=None) |
| 195 |
|
| 196 |
A subclass of FileDialog that creates a dialog window for selecting a |
| 197 |
destination file. |
| 198 |
|
| 199 |
.. method:: ok_command() |
| 200 |
|
| 201 |
Test whether or not the selection points to a valid file that is not a |
| 202 |
directory. Confirmation is required if an already existing file is |
| 203 |
selected. |
| 204 |
|
| 205 |
:mod:`!tkinter.commondialog` --- Dialog window templates |
| 206 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 207 |
|
| 208 |
.. module:: tkinter.commondialog |
| 209 |
:synopsis: Tkinter base class for dialogs |
| 210 |
|
| 211 |
**Source code:** :source:`Lib/tkinter/commondialog.py` |
| 212 |
|
| 213 |
-------------- |
| 214 |
|
| 215 |
The :mod:`!tkinter.commondialog` module provides the :class:`Dialog` class that |
| 216 |
is the base class for dialogs defined in other supporting modules. |
| 217 |
|
| 218 |
.. class:: Dialog(master=None, **options) |
| 219 |
|
| 220 |
.. method:: show(**options) |
| 221 |
|
| 222 |
Render the Dialog window. |
| 223 |
|
| 224 |
|
| 225 |
.. seealso:: |
| 226 |
|
| 227 |
Modules :mod:`tkinter.messagebox`, :ref:`tut-files` |