bpo-25237: Documentation for tkinter modules (GH-1870)

10 files changed, 479 insertions, 15 deletions

diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst
new file mode 100644
index 0000000..836f662
--- /dev/null
+++ b/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`
\ No newline at end of file
diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst
index 95cd1c7..c6c73f0 100644
--- a/Doc/library/tk.rst
+++ b/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
\ No newline at end of file
diff --git a/Doc/library/tk_msg.png b/Doc/library/tk_msg.png
new file mode 100644
index 0000000..c122d8f
--- /dev/null
+++ b/Doc/library/tk_msg.png
diff --git a/Doc/library/tkinter.colorchooser.rst b/Doc/library/tkinter.colorchooser.rst
new file mode 100644
index 0000000..60f4d70
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/Doc/library/tkinter.dnd.rst b/Doc/library/tkinter.dnd.rst
new file mode 100644
index 0000000..6c11c73
--- /dev/null
+++ b/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`
\ No newline at end of file
diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst
new file mode 100644
index 0000000..30c1e7b
--- /dev/null
+++ b/Doc/library/tkinter.font.rst
@@ -0,0 +1,96 @@
+:mod:`tkinter.font` --- Tkinter font wrapper
+============================================
+
+.. module:: tkinter.font
+   :platform: Tk
+   :synopsis: Tkinter font-wrapping class
+
+**Source code:** :source:`Lib/tkinter/font.py`
+
+--------------
+
+The :mod:`tkinter.font` module provides the :class:`Font` class for creating
+and using named fonts.
+
+The different font weights and slants are:
+
+.. data:: NORMAL
+          BOLD
+          ITALIC
+          ROMAN
+
+.. class:: Font(root=None, font=None, name=None, exists=False, **options)
+
+   The :class:`Font` class represents a named font. *Font* instances are given
+   unique names and can be specified by their family, size, and style
+   configuration. Named fonts are Tk's method of creating and identifying
+   fonts as a single object, rather than specifying a font by its attributes
+   with each occurrence.
+
+    arguments:
+
+       | *font* - font specifier tuple (family, size, options)
+       | *name* - unique font name
+       | *exists* - self points to existing named font if true
+
+    additional keyword options (ignored if *font* is specified):
+
+       | *family* - font family i.e. Courier, Times
+       | *size* - font size
+       |     If *size* is positive it is interpreted as size in points.
+       |     If *size* is a negative number its absolute value is treated as
+             as size in pixels.
+       | *weight* - font emphasis (NORMAL, BOLD)
+       | *slant* - ROMAN, ITALIC
+       | *underline* - font underlining (0 - none, 1 - underline)
+       | *overstrike* - font strikeout (0 - none, 1 - strikeout)
+
+   .. method:: actual(option=None, displayof=None)
+
+      Return the attributes of the font.
+
+   .. method:: cget(option)
+
+      Retrieve an attribute of the font.
+
+   .. method:: config(**options)
+
+      Modify attributes of the font.
+
+   .. method:: copy()
+
+      Return new instance of the current font.
+
+   .. method:: measure(text, displayof=None)
+
+      Return amount of space the text would occupy on the specified display
+      when formatted in the current font. If no display is specified then the
+      main application window is assumed.
+
+   .. method:: metrics(*options, **kw)
+
+      Return font-specific data.
+      Options include:
+
+      *ascent* - distance between baseline and highest point that a
+         character of the font can occupy
+
+      *descent* - distance between baseline and lowest point that a
+         character of the font can occupy
+
+      *linespace* - minimum vertical separation necessary between any two
+         characters of the font that ensures no vertical overlap between lines.
+
+      *fixed* - 1 if font is fixed-width else 0
+
+.. function:: families(root=None, displayof=None)
+
+   Return the different font families.
+
+.. function:: names(root=None)
+
+   Return the names of defined fonts.
+
+.. function:: nametofont(name)
+
+   Return a :class:`Font` representation of a tk named font.
\ No newline at end of file
diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst
new file mode 100644
index 0000000..872e72f
--- /dev/null
+++ b/Doc/library/tkinter.messagebox.rst
@@ -0,0 +1,39 @@
+:mod:`tkinter.messagebox` --- Tkinter message prompts
+=====================================================
+
+.. module:: tkinter.messagebox
+   :platform: Tk
+   :synopsis: Various types of alert dialogs
+
+**Source code:** :source:`Lib/tkinter/messagebox.py`
+
+--------------
+
+The :mod:`tkinter.messagebox` module provides a template base class as well as
+a variety of convenience methods for commonly used configurations. The message
+boxes are modal and will return a subset of (True, False, OK, None, Yes, No) based on
+the user's selection. Common message box styles and layouts include but are not
+limited to:
+
+.. figure:: tk_msg.png
+
+.. class:: Message(master=None, **options)
+
+   Create a default information message box.
+
+**Information message box**
+
+.. method:: showinfo(title=None, message=None, **options)
+
+**Warning message boxes**
+
+.. method:: showwarning(title=None, message=None, **options)
+            showerror(title=None, message=None, **options)
+
+**Question message boxes**
+
+.. method:: askquestion(title=None, message=None, **options)
+            askokcancel(title=None, message=None, **options)
+            askretrycancel(title=None, message=None, **options)
+            askyesno(title=None, message=None, **options)
+            askyesnocancel(title=None, message=None, **options)
\ No newline at end of file
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index e1fc051..2dc44ad 100644
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -109,9 +109,6 @@ Or, more often::
 
 Other modules that provide Tk support include:
 
-:mod:`tkinter.scrolledtext`
-   Text widget with a vertical scroll bar built in.
-
 :mod:`tkinter.colorchooser`
    Dialog to let the user choose a color.
 
@@ -127,6 +124,9 @@ Other modules that provide Tk support include:
 :mod:`tkinter.messagebox`
    Access to standard Tk dialog boxes.
 
+:mod:`tkinter.scrolledtext`
+   Text widget with a vertical scroll bar built in.
+
 :mod:`tkinter.simpledialog`
    Basic dialogs and convenience functions.
 
@@ -680,9 +680,10 @@ scrollcommand
    This is almost always the :meth:`!set` method of some scrollbar widget, but can
    be any widget method that takes a single argument.
 
-wrap:
+wrap
    Must be one of: ``"none"``, ``"char"``, or ``"word"``.
 
+.. _Bindings-and-Events:
 
 Bindings and Events
 ^^^^^^^^^^^^^^^^^^^
@@ -860,4 +861,4 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``.
           WRITABLE
           EXCEPTION
 
-   Constants used in the *mask* arguments.
+   Constants used in the *mask* arguments.
\ No newline at end of file
diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst
index 138720e..d20365b 100644
--- a/Doc/library/tkinter.scrolledtext.rst
+++ b/Doc/library/tkinter.scrolledtext.rst
@@ -14,8 +14,7 @@
 The :mod:`tkinter.scrolledtext` module provides a class of the same name which
 implements a basic text widget which has a vertical scroll bar configured to do
 the "right thing."  Using the :class:`ScrolledText` class is a lot easier than
-setting up a text widget and scroll bar directly.  The constructor is the same
-as that of the :class:`tkinter.Text` class.
+setting up a text widget and scroll bar directly.
 
 The text widget and scrollbar are packed together in a :class:`Frame`, and the
 methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired
@@ -25,12 +24,14 @@ be used directly to achieve most normal geometry management behavior.
 Should more specific control be necessary, the following attributes are
 available:
 
+.. class:: ScrolledText(master=None, **kw)
 
-.. attribute:: ScrolledText.frame
 
-   The frame which surrounds the text and scroll bar widgets.
+   .. attribute:: frame
 
+      The frame which surrounds the text and scroll bar widgets.
 
-.. attribute:: ScrolledText.vbar
 
-   The scroll bar widget.
+   .. attribute:: vbar
+
+      The scroll bar widget.
diff --git a/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst b/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst
new file mode 100644
index 0000000..5778f37
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-06-02-12-55-23.bpo-25237.m8-JMu.rst
@@ -0,0 +1 @@
+Add documentation for tkinter modules