[3.15] gh-86726: Document the full public API of tkinter (GH-151579) (GH-151649)

Replace the previously sparse reference documentation with full coverage of
the public API of the tkinter package, written from the Tcl/Tk manual pages,
the existing documentation and the module docstrings.

* Doc/library/tkinter.rst gains a "Reference" section documenting every public
  class, method, function and constant of the core module -- the widgets, the
  Misc, Wm, Pack, Place, Grid, XView and YView mix-ins, the Variable and image
  classes, the module-level functions and the symbolic constants.
* Doc/library/tkinter.ttk.rst, dialog.rst, tkinter.font.rst and the other
  module pages document their remaining classes, methods and functions.

The descriptions are Python-oriented (correct return types -- tuples rather
than Tcl lists, booleans, integers, None on cancellation, and so on) and were
checked against the Tcl/Tk 9.1 manual pages and the implementation.

versionadded, versionchanged and deprecated directives are added for the
public API, determined from the git history relative to Python 3.0: the
tkinter.ttk module (3.1); the Text, Wm, Menu and Misc methods exposing Tk 8.5
features (3.3); and the many later additions and behavior changes up to 3.15.
The Tk version required by features added after Tk 8.6 is noted as well.  The
bundled Tcl/Tk version is updated to 9.0 and the manual-page links point at
the tcl9.0 reference.

--------
(cherry picked from commit 8b270b7)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Author: 4 people

Doc/library/dialog.rst

@@ -1,4 +1,4 @@
-Tkinter Dialogs
+Tkinter dialogs
 ===============
 
 :mod:`!tkinter.simpledialog` --- Standard Tkinter input dialogs
@@ -36,6 +36,42 @@ functions for creating simple modal dialogs to get a value from the user.
       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.
+      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
@@ -51,7 +87,7 @@ functions for creating simple modal dialogs to get a value from the user.
 The :mod:`!tkinter.filedialog` module provides classes and factory functions for
 creating file/directory selection windows.
 
-Native Load/Save Dialogs
+Native load/save dialogs
 ------------------------
 
 The following classes and functions provide file dialog windows that combine a
@@ -77,34 +113,46 @@ listed below:
 **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.
+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)
 
-   The above two functions create an :class:`Open` dialog and return the opened
-   file object(s) in read-only mode.
+   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 a file object opened in write-only mode.
+   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)
 
-   The above two functions create an :class:`Open` dialog and return the
-   selected filename(s) that correspond to existing file(s).
+   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.
+   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 user to select a directory.
- | Additional keyword option:
- |  *mustexist* - determines if selection must be an existing directory.
+   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)
@@ -168,6 +216,13 @@ These do not emulate the native look-and-feel of the platform.
 
       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.
@@ -222,6 +277,40 @@ is the base class for dialogs defined in other supporting modules.
       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`.
+
+.. 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, 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`

Doc/library/tkinter.colorchooser.rst

@@ -15,14 +15,26 @@ the :class:`~tkinter.commondialog.Dialog` class.
 
 .. class:: Chooser(master=None, **options)
 
+   The class implementing the modal color-choosing dialog.
+   Most applications use the :func:`askcolor` convenience function rather than
+   instantiating this class directly.
+
 .. 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.
+   Show a modal color-choosing dialog and return the chosen color.
+   *color* is the color selected when the dialog opens.
+   The return value is a tuple ``((r, g, b), hexstr)``, where ``r``, ``g`` and
+   ``b`` are the red, green and blue components as integers in the range 0–255
+   and *hexstr* is the equivalent Tk color string, such as ``'#ff8000'``.
+   If the user cancels the dialog, ``(None, None)`` is returned.
+
+   .. versionchanged:: 3.10
+      The RGB values in the returned color are now integers in the range 0–255
+      instead of floats.
 
 
 .. seealso::
 
    Module :mod:`tkinter.commondialog`
       Tkinter standard dialog module
+

Doc/library/tkinter.dnd.rst

@@ -48,15 +48,18 @@ Selection of a target object occurs as follows:
 
    .. method:: on_motion(event)
 
-      Inspect area below mouse for target objects while drag is performed.
+      Inspect area below mouse for target objects while a 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.
+   Factory function for the drag-and-drop process.
+   Return the :class:`DndHandler` instance managing the drag, or ``None`` if a
+   drag could not be started.
 
 .. seealso::
 

Doc/library/tkinter.font.rst

@@ -26,6 +26,10 @@ The different font weights and slants are:
    fonts as a single object, rather than specifying a font by its attributes
    with each occurrence.
 
+   .. versionchanged:: 3.10
+      Two fonts now compare equal (``==``) only when both are :class:`Font`
+      instances with the same name belonging to the same Tcl interpreter.
+
     arguments:
 
        | *font* - font specifier tuple (family, size, options)
@@ -34,7 +38,7 @@ The different font weights and slants are:
 
     additional keyword options (ignored if *font* is specified):
 
-       | *family* - font family i.e. Courier, Times
+       | *family* - font family, for example, 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
@@ -46,15 +50,24 @@ The different font weights and slants are:
 
    .. method:: actual(option=None, displayof=None)
 
-      Return the attributes of the font.
+      Return the actual attributes of the font, which may differ from the
+      requested ones because of platform limitations.
+      With no *option*, return a dictionary of all the attributes; if *option*
+      is given, return the value of that single attribute.
 
    .. method:: cget(option)
 
       Retrieve an attribute of the font.
 
    .. method:: config(**options)
+      :no-typesetting:
+
+   .. method:: configure(**options)
+
+      Modify one or more attributes of the font.
+      With no arguments, return a dictionary of the current attributes.
 
-      Modify attributes of the font.
+      :meth:`config` is an alias of :meth:`!configure`.
 
    .. method:: copy()
 
@@ -63,12 +76,15 @@ The different font weights and slants are:
    .. 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.
+      when formatted in the current font, as an integer number of pixels.
+      If no display is specified then the main application window is assumed.
 
    .. method:: metrics(*options, **kw)
 
       Return font-specific data.
+      With no options, return a dictionary mapping each metric name to its
+      integer value; if one option name is given, return that metric's value as
+      an integer.
       Options include:
 
       *ascent* - distance between baseline and highest point that a
@@ -84,15 +100,17 @@ The different font weights and slants are:
 
 .. function:: families(root=None, displayof=None)
 
-   Return the different font families.
+   Return a tuple of the names of the available font families.
 
 .. function:: names(root=None)
 
-   Return the names of defined fonts.
+   Return a tuple of the names of all the defined fonts.
 
 .. function:: nametofont(name, root=None)
 
-   Return a :class:`Font` representation of a tk named font.
+   Return a :class:`Font` representation of the existing named font *name*.
+   *root* is the widget whose Tcl interpreter owns the font; if omitted, the
+   default root window is used.
 
    .. versionchanged:: 3.10
       The *root* parameter was added.

Doc/library/tkinter.messagebox.rst

@@ -9,11 +9,14 @@
 --------------
 
 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``, ``None``,
-:data:`OK`, :data:`CANCEL`, :data:`YES`, :data:`NO`) based on
-the user's selection. Common message box styles and layouts include but are not
-limited to:
+a variety of convenience methods for commonly used configurations.
+The message boxes are modal: each blocks until the user responds, then returns
+a value that depends on the function.
+The ``show*`` functions and :meth:`Message.show` return the symbolic name of
+the button the user pressed, as a string (such as :data:`OK` or :data:`YES`),
+while the ``ask*`` functions return a :class:`bool` or ``None`` (see each
+function below).
+Common message box styles and layouts include but are not limited to:
 
 .. figure:: tk_msg.png
 
@@ -66,6 +69,10 @@ limited to:
          Arranges for a :ref:`predefined set of buttons <messagebox-types>`
          to be displayed.
 
+   .. note::
+
+      Tk 8.6 added the *command* option.
+
    .. method:: show(**options)
 
       Display a message window and wait for the user to select one of the buttons. Then return the symbolic name of the selected button.