Tkinter dialogs =============== :mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: tkinter.simpledialog :synopsis: Simple dialog windows **Source code:** :source:`Lib/tkinter/simpledialog.py` -------------- The :mod:`tkinter.simpledialog` module contains convenience classes and functions for creating simple modal dialogs to get a value from the user. .. function:: askfloat(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None) askstring(title, prompt, *, initialvalue=None, show=None, parent=None) Prompt the user to enter a value of the desired type and return it, or ``None`` if the dialog is cancelled. *title* is the dialog title and *prompt* the message shown above the entry. *initialvalue* is the value initially placed in the entry. *parent* is the window over which the dialog is shown. :func:`askinteger` and :func:`askfloat` also accept *minvalue* and *maxvalue*, which bound the accepted value. :func:`askstring` also accepts *show*, a character used to mask the entered text, for example ``'*'`` to hide a password. .. class:: Dialog(parent, title=None) The base class for custom dialogs. Instantiating it shows the dialog modally and returns once the user closes it; the entered value is then available in the :attr:`!result` attribute. .. attribute:: result The value produced by :meth:`apply`, or ``None`` if the dialog was cancelled. .. method:: body(master) Override to construct the dialog's interface and return the widget that should have initial focus. .. method:: buttonbox() Default behaviour adds OK and Cancel buttons. Override for custom button layouts. .. method:: validate() Validate the data entered by the user. Return true if it is valid, in which case the dialog proceeds to :meth:`apply`; return false to keep the dialog open. The default implementation always returns true; override it to check the input. .. method:: apply() Process the data entered by the user, for example by storing it in the :attr:`!result` attribute. Called after :meth:`validate` succeeds and just before the dialog is destroyed. The default implementation does nothing; override it to act on or store the result. .. method:: destroy() Destroy the dialog window, clearing the reference to the widget that had the initial focus. .. class:: SimpleDialog(master, text='', buttons=[], default=None, cancel=None, title=None, class_=None) A simple modal dialog that displays the message *text* above a row of push buttons whose labels are given by *buttons*, and returns the index of the button the user presses. *default* is the index of the button activated by the Return key, *cancel* the index returned when the window is closed through the window manager, *title* the window title, and *class_* the Tk class name of the window. .. method:: go() Display the dialog, wait until the user presses a button or closes the window, and return the index of the chosen button. :mod:`tkinter.filedialog` --- File selection dialogs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: tkinter.filedialog :synopsis: Dialog classes for file selection **Source code:** :source:`Lib/tkinter/filedialog.py` -------------- The :mod:`tkinter.filedialog` module provides classes and factory functions for creating file/directory selection windows. Native load/save dialogs ------------------------ The following classes and functions provide file dialog windows that combine a native look-and-feel with configuration options to customize behaviour. The following keyword arguments are applicable to the classes and functions listed below: | *parent* - the window to place the dialog on top of | *title* - the title of the window | *initialdir* - the directory that the dialog starts in | *initialfile* - the file selected upon opening of the dialog | *filetypes* - a sequence of (label, pattern) tuples, '*' wildcard is allowed | *defaultextension* - default extension to append to file (save dialogs) | *multiple* - when true, selection of multiple items is allowed **Static factory functions** The below functions when called create a modal, native look-and-feel dialog, wait for the user's selection, and return it. The exact return value depends on the function (see below); when the dialog is cancelled it is an empty string, an empty tuple or ``None``. The precise type of this empty value may vary between platforms and Tk versions, so test the result for truth rather than comparing it with a specific value. .. function:: askopenfile(mode="r", **options) askopenfiles(mode="r", **options) Create an :class:`Open` dialog. :func:`askopenfile` returns the opened file object, or ``None`` if the dialog is cancelled. :func:`askopenfiles` returns a list of the opened file objects, or an empty tuple if cancelled. The files are opened in mode *mode* (read-only ``'r'`` by default). .. function:: asksaveasfile(mode="w", **options) Create a :class:`SaveAs` dialog and return the opened file object, or ``None`` if the dialog is cancelled. The file is opened in mode *mode* (``'w'`` by default). .. function:: askopenfilename(**options) askopenfilenames(**options) Create an :class:`Open` dialog. :func:`askopenfilename` returns the selected filename as a string, or an empty string if the dialog is cancelled. :func:`askopenfilenames` returns a tuple of the selected filenames, or an empty tuple if cancelled. .. function:: asksaveasfilename(**options) Create a :class:`SaveAs` dialog and return the selected filename as a string, or an empty string if the dialog is cancelled. .. function:: askdirectory(**options) Prompt the user to select a directory, and return its path as a string, or an empty string if the dialog is cancelled. Additional keyword option: *mustexist* - if true, the user may only select an existing directory (false by default). .. class:: Open(master=None, **options) SaveAs(master=None, **options) Directory(master=None, **options) The above three classes provide native dialog windows for loading and saving files and for selecting a directory. **Convenience classes** The below classes are used for creating file/directory windows from scratch. These do not emulate the native look-and-feel of the platform. .. note:: The *FileDialog* class should be subclassed for custom event handling and behaviour. .. class:: FileDialog(master, title=None) Create a basic file selection dialog. .. method:: cancel_command(event=None) Trigger the termination of the dialog window. .. method:: dirs_double_event(event) Event handler for double-click event on directory. .. method:: dirs_select_event(event) Event handler for click event on directory. .. method:: files_double_event(event) Event handler for double-click event on file. .. method:: files_select_event(event) Event handler for single-click event on file. .. method:: filter_command(event=None) Filter the files by directory. .. method:: get_filter() Retrieve the file filter currently in use. .. method:: get_selection() Retrieve the currently selected item. .. method:: go(dir_or_file=os.curdir, pattern="*", default="", key=None) Render dialog and start event loop. .. method:: ok_event(event) Exit dialog returning current selection. .. method:: ok_command() Called when the user confirms the current selection. The base implementation accepts the selection and closes the dialog; :class:`LoadFileDialog` and :class:`SaveFileDialog` override it to check the selection first. .. method:: quit(how=None) Exit dialog returning filename, if any. .. method:: set_filter(dir, pat) Set the file filter. .. method:: set_selection(file) Update the current file selection to *file*. .. class:: LoadFileDialog(master, title=None) A subclass of FileDialog that creates a dialog window for selecting an existing file. .. method:: ok_command() Test that a file is provided and that the selection indicates an already existing file. .. class:: SaveFileDialog(master, title=None) A subclass of FileDialog that creates a dialog window for selecting a destination file. .. method:: ok_command() Test whether or not the selection points to a valid file that is not a directory. Confirmation is required if an already existing file is selected. :mod:`tkinter.commondialog` --- Dialog window templates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: tkinter.commondialog :synopsis: Tkinter base class for dialogs **Source code:** :source:`Lib/tkinter/commondialog.py` -------------- The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class that is the base class for dialogs defined in other supporting modules. .. class:: Dialog(master=None, **options) .. method:: show(**options) Render the Dialog window. :mod:`!tkinter.dialog` --- Classic Tk dialog boxes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: tkinter.dialog :synopsis: A simple dialog box built on the classic Tk widgets. **Source code:** :source:`Lib/tkinter/dialog.py` -------------- The :mod:`!tkinter.dialog` module provides a simple modal dialog box built on the classic (non-themed) Tk widgets. .. data:: DIALOG_ICON The name of a bitmap (``'questhead'``) suitable for use as the *bitmap* of a :class:`Dialog`. .. class:: Dialog(master=None, cnf={}, **kw) Display a modal dialog box built from the classic (non-themed) Tk widgets and wait for the user to press one of its buttons. The options, given through *cnf* or as keyword arguments, are all required: *title* (the window title), *text* (the message), *bitmap* (the name of a bitmap icon, such as :data:`DIALOG_ICON`), *default* (the index of the default button) and *strings* (the sequence of button labels). After construction, the :attr:`!num` attribute holds the index of the button the user pressed. .. method:: destroy() Do nothing. The dialog window is destroyed automatically before the constructor returns, so there is nothing left for this method to do. .. seealso:: Modules :mod:`tkinter.messagebox`, :ref:`tut-files`