Skip to content

dialog.rst

Latest commit

 

History

History
360 lines (232 loc) · 12 KB

dialog.rst

File metadata and controls

360 lines (232 loc) · 12 KB

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, use_ttk=True)
              askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None, use_ttk=True)
              askstring(title, prompt, *, initialvalue=None, show=None, parent=None, use_ttk=True)

   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.
   They use the themed :mod:`tkinter.ttk` widgets; pass ``use_ttk=False`` for
   the classic widgets.

: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, an empty list or None.

.. 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
   list 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).

The above two classes provide native dialog windows for saving and loading files.

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.

Create a dialog prompting the user to select a directory.

Note

The FileDialog class should be subclassed for custom event handling and behaviour.

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*.

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.

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.

.. 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 the default bitmap (``'questhead'``) displayed by a
   :class:`Dialog`.

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, include title (the window title), text (the message), bitmap (an icon, :data:`DIALOG_ICON` by default), 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()

   Destroy the dialog window.

.. seealso::

   Modules :mod:`tkinter.messagebox`, :ref:`tut-files`