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, *, 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`