bpo-25237: Documentation for tkinter modules

Doc/library/dialog.rst

@@ -0,0 +1,230 @@
+Tkinter Dialogs
+===============
+
+:mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. module:: tkinter.simpledialog
+   :platform: Tk
+   :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, **kw)
+              askinteger(title, prompt, **kw)
+              askstring(title, prompt, **kw)
+
+   The above three functions provide dialogs that prompt the user to enter a value
+   of the desired type.
+
+.. class:: Dialog(parent, title=None)
+
+   The base class for custom dialogs.
+
+    .. 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.
+
+
+
+:mod:`tkinter.filedialog` --- File selection dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. module:: tkinter.filedialog
+   :platform: Tk
+   :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, then return the selected value(s) or ``None`` to the
+caller.
+
+.. function:: askopenfile(mode="r", **options)
+              askopenfiles(mode="r", **options)
+
+   The above two functions create an :class:`Open` dialog and return the opened
+   file object(s) in read-only mode.
+
+.. function:: asksaveasfile(mode="w", **options)
+
+   Create a :class:`SaveAs` dialog and return a file object opened in write-only mode.
+
+.. function:: askopenfilename(**options)
+              askopenfilenames(**options)
+
+   The above two functions create an :class:`Open` dialog and return the
+   selected filename(s) that correspond to existing file(s).
+
+.. function:: asksaveasfilename(**options)
+
+   Create a :class:`SaveAs` dialog and return the selected filename.
+
+.. function:: askdirectory(**options)
+
+ | Prompt user to select a directory.
+ | Additional keyword option:
+ |  *mustexist* - determines if selection must be an existing directory.
+
+.. class:: Open(master=None, **options)
+           SaveAs(master=None, **options)
+
+   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.
+
+.. class:: Directory(master=None, **options)
+
+   Create a dialog prompting the user to select a directory.
+
+.. 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:: 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
+   :platform: Tk
+   :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(color=None, **options)
+
+      Render the Dialog window.
+
+
+.. seealso::
+
+   Modules :mod:`tkinter.messagebox`, :ref:`tut-files`

Doc/library/tk.rst

@@ -33,14 +33,17 @@ alternatives, see the :ref:`other-gui-packages` section.
 .. toctree::
 
    tkinter.rst
+   tkinter.colorchooser.rst
+   tkinter.font.rst
+   dialog.rst
+   tkinter.messagebox.rst
+   tkinter.scrolledtext.rst
+   tkinter.dnd.rst
    tkinter.ttk.rst
    tkinter.tix.rst
-   tkinter.scrolledtext.rst
    idle.rst
    othergui.rst
 
 .. Other sections I have in mind are
    Tkinter internals
-   Freezing Tkinter applications
-
-
+   Freezing Tkinter applications

Doc/library/tkinter.colorchooser.rst

@@ -0,0 +1,29 @@
+:mod:`tkinter.colorchooser` --- Color choosing dialog
+=====================================================
+
+.. module:: tkinter.colorchooser
+   :platform: Tk
+   :synopsis: Color choosing dialog
+
+**Source code:** :source:`Lib/tkinter/colorchooser.py`
+
+--------------
+
+The :mod:`tkinter.colorchooser` module provides the :class:`Chooser` class
+as an interface to the native color picker dialog. ``Chooser`` implements
+a modal color choosing dialog window. The ``Chooser`` class inherits from
+the :class:`~tkinter.commondialog.Dialog` class.
+
+.. class:: Chooser(master=None, **options)
+
+.. function:: askcolor(color=None, **options)
+
+   Create a color choosing dialog. A call to this method will show the window,
+   wait for the user to make a selection, and return the selected color (or
+   ``None``) to the caller.
+
+
+.. seealso::
+
+   Module :mod:`tkinter.commondialog`
+      Tkinter standard dialog module

Doc/library/tkinter.dnd.rst

@@ -0,0 +1,64 @@
+:mod:`tkinter.dnd` --- Drag and drop support
+============================================
+
+.. module:: tkinter.dnd
+   :platform: Tk
+   :synopsis: Tkinter drag-and-drop interface
+
+**Source code:** :source:`Lib/tkinter/dnd.py`
+
+--------------
+
+.. note:: This is experimental and due to be deprecated when it is replaced
+   with the Tk DND.
+
+The :mod:`tkinter.dnd` module provides drag-and-drop support for objects within
+a single application, within the same window or between windows. To enable an
+object to be dragged, you must create an event binding for it that starts the
+drag-and-drop process. Typically, you bind a ButtonPress event to a callback
+function that you write (see :ref:`Bindings-and-Events`). The function should
+call :func:`dnd_start`, where 'source' is the object to be dragged, and 'event'
+is the event that invoked the call (the argument to your callback function).
+
+Selection of a target object occurs as follows:
+
+#. Top-down search of area under mouse for target widget
+
+ * Target widget should have a callable *dnd_accept* attribute
+ * If *dnd_accept* is not present or returns None, search moves to parent widget
+ * If no target widget is found, then the target object is None
+
+2. Call to *<old_target>.dnd_leave(source, event)*
+#. Call to *<new_target>.dnd_enter(source, event)*
+#. Call to *<target>.dnd_commit(source, event)* to notify of drop
+#. Call to *<source>.dnd_end(target, event)* to signal end of drag-and-drop
+
+
+.. class:: DndHandler(source, event)
+
+   The *DndHandler* class handles drag-and-drop events tracking Motion and
+   ButtonRelease events on the root of the event widget.
+
+   .. method:: cancel(event=None)
+
+      Cancel the drag-and-drop process.
+
+   .. method:: finish(event, commit=0)
+
+      Execute end of drag-and-drop functions.
+
+   .. method:: on_motion(event)
+
+      Inspect area below mouse for target objects while drag is performed.
+
+   .. method:: on_release(event)
+
+      Signal end of drag when the release pattern is triggered.
+
+.. function:: dnd_start(source, event)
+
+   Factory function for drag-and-drop process.
+
+.. seealso::
+
+   :ref:`Bindings-and-Events`