Debian Codegraph @

Doc/library/dialog.rst

raw
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`