[pull] main from python:main

Doc/library/curses.panel.rst

@@ -45,7 +45,7 @@ The module :mod:`!curses.panel` defines the following functions:
 
 .. _curses-panel-objects:
 
-Panel Objects
+Panel objects
 -------------
 
 Panel objects, as returned by :func:`new_panel` above, are windows with a

Doc/library/curses.rst

@@ -243,7 +243,7 @@ The module :mod:`!curses` defines the following functions:
 
 .. function:: getwin(file)
 
-   Read window related data stored in the file by an earlier :meth:`window.putwin` call.
+   Read window-related data stored in the file by an earlier :meth:`window.putwin` call.
    The routine then creates and initializes a new window using that data, returning
    the new window object.  The *file* argument must be a file object opened for
    reading in binary mode.
@@ -257,7 +257,7 @@ The module :mod:`!curses` defines the following functions:
 
    Return ``True`` if the module supports extended colors; otherwise, return
    ``False``. Extended color support allows more than 256 color pairs for
-   terminals that support more than 16 colors (e.g. xterm-256color).
+   terminals that support more than 16 colors (for example, xterm-256color).
 
    Extended color support requires ncurses version 6.1 or later.
 
@@ -330,6 +330,13 @@ The module :mod:`!curses` defines the following functions:
       cause the interpreter to exit.
 
 
+.. function:: intrflush(flag)
+
+   If *flag* is ``True``, pressing an interrupt key (interrupt, break, or quit)
+   will flush all output in the terminal driver queue.  If *flag* is ``False``,
+   no flushing is done.
+
+
 .. function:: is_term_resized(nlines, ncols)
 
    Return ``True`` if :func:`resize_term` would modify the window structure,
@@ -409,7 +416,7 @@ The module :mod:`!curses` defines the following functions:
    methods of a pad require 6 arguments to specify the part of the pad to be
    displayed and the location on the screen to be used for the display. The
    arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*
-   arguments refer to the upper left corner of the pad region to be displayed and
+   arguments refer to the upper-left corner of the pad region to be displayed and
    the *s* arguments define a clipping box on the screen within which the pad region
    is to be displayed.
 
@@ -646,7 +653,7 @@ The module :mod:`!curses` defines the following functions:
 .. function:: tparm(str[, ...])
 
    Instantiate the bytes object *str* with the supplied parameters, where *str* should
-   be a parameterized string obtained from the terminfo database.  E.g.
+   be a parameterized string obtained from the terminfo database.  For example,
    ``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
    result depending on terminal type.  Up to nine integer parameters may be supplied.
 
@@ -736,7 +743,7 @@ The module :mod:`!curses` defines the following functions:
 
 .. _curses-window-objects:
 
-Window Objects
+Window objects
 --------------
 
 .. class:: window
@@ -755,7 +762,7 @@ Window Objects
    .. note::
 
       Writing outside the window, subwindow, or pad raises a :exc:`curses.error`.
-      Attempting to write to the lower right corner of a window, subwindow,
+      Attempting to write to the lower-right corner of a window, subwindow,
       or pad will cause an exception to be raised after the character is printed.
 
 
@@ -776,7 +783,7 @@ Window Objects
    .. note::
 
       * Writing outside the window, subwindow, or pad raises :exc:`curses.error`.
-        Attempting to write to the lower right corner of a window, subwindow,
+        Attempting to write to the lower-right corner of a window, subwindow,
         or pad will cause an exception to be raised after the string is printed.
 
       * A bug in ncurses, the backend for this Python module, could cause
@@ -1013,8 +1020,8 @@ Window Objects
             window.getstr(y, x, n)
 
    Read a bytes object from the user, with primitive line editing capacity.
-   At most *n* characters are read (2047 by default).
-   The maximum value for *n* is 2047.
+   At most *n* characters are read;
+   *n* defaults to and cannot exceed 2047.
 
    .. versionchanged:: 3.14
       The maximum value for *n* was increased from 1023 to 2047.
@@ -1243,10 +1250,10 @@ Window Objects
 
    The 6 arguments can only be specified, and are then required, when the window
    is a pad created with :func:`newpad`.  The additional parameters are needed to indicate what part
-   of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
-   left-hand corner of the rectangle to be displayed in the pad.  *sminrow*,
+   of the pad and screen are involved. *pminrow* and *pmincol* specify the
+   upper-left corner of the rectangle to be displayed in the pad.  *sminrow*,
    *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
-   displayed on the screen.  The lower right-hand corner of the rectangle to be
+   displayed on the screen.  The lower-right corner of the rectangle to be
    displayed in the pad is calculated from the screen coordinates, since the
    rectangles must be the same size.  Both rectangles must be entirely contained
    within their respective structures.  Negative values of *pminrow*, *pmincol*,
@@ -1415,14 +1422,14 @@ The :mod:`!curses` module defines the following data members:
 
 .. data:: COLS
 
-   The width of the screen, i.e., the number of columns.
+   The width of the screen, that is, the number of columns.
    It is defined only after the call to :func:`initscr`.
    Updated by :func:`update_lines_cols`, :func:`resizeterm` and
    :func:`resize_term`.
 
 .. data:: LINES
 
-   The height of the screen, i.e., the number of lines.
+   The height of the screen, that is, the number of lines.
    It is defined only after the call to :func:`initscr`.
    Updated by :func:`update_lines_cols`, :func:`resizeterm` and
    :func:`resize_term`.
@@ -1725,15 +1732,15 @@ falls back on a crude printable ASCII approximation.
 +------------------------+------------------------------------------+
 | ACS code               | Meaning                                  |
 +========================+==========================================+
-| .. data:: ACS_BBSS     | alternate name for upper right corner    |
+| .. data:: ACS_BBSS     | alternate name for upper-right corner    |
 +------------------------+------------------------------------------+
 | .. data:: ACS_BLOCK    | solid square block                       |
 +------------------------+------------------------------------------+
 | .. data:: ACS_BOARD    | board of squares                         |
 +------------------------+------------------------------------------+
 | .. data:: ACS_BSBS     | alternate name for horizontal line       |
 +------------------------+------------------------------------------+
-| .. data:: ACS_BSSB     | alternate name for upper left corner     |
+| .. data:: ACS_BSSB     | alternate name for upper-left corner     |
 +------------------------+------------------------------------------+
 | .. data:: ACS_BSSS     | alternate name for top tee               |
 +------------------------+------------------------------------------+
@@ -1759,9 +1766,9 @@ falls back on a crude printable ASCII approximation.
 +------------------------+------------------------------------------+
 | .. data:: ACS_LEQUAL   | less-than-or-equal-to                    |
 +------------------------+------------------------------------------+
-| .. data:: ACS_LLCORNER | lower left-hand corner                   |
+| .. data:: ACS_LLCORNER | lower-left corner                        |
 +------------------------+------------------------------------------+
-| .. data:: ACS_LRCORNER | lower right-hand corner                  |
+| .. data:: ACS_LRCORNER | lower-right corner                       |
 +------------------------+------------------------------------------+
 | .. data:: ACS_LTEE     | left tee                                 |
 +------------------------+------------------------------------------+
@@ -1785,13 +1792,13 @@ falls back on a crude printable ASCII approximation.
 +------------------------+------------------------------------------+
 | .. data:: ACS_S9       | scan line 9                              |
 +------------------------+------------------------------------------+
-| .. data:: ACS_SBBS     | alternate name for lower right corner    |
+| .. data:: ACS_SBBS     | alternate name for lower-right corner    |
 +------------------------+------------------------------------------+
 | .. data:: ACS_SBSB     | alternate name for vertical line         |
 +------------------------+------------------------------------------+
 | .. data:: ACS_SBSS     | alternate name for right tee             |
 +------------------------+------------------------------------------+
-| .. data:: ACS_SSBB     | alternate name for lower left corner     |
+| .. data:: ACS_SSBB     | alternate name for lower-left corner     |
 +------------------------+------------------------------------------+
 | .. data:: ACS_SSBS     | alternate name for bottom tee            |
 +------------------------+------------------------------------------+
@@ -1805,9 +1812,9 @@ falls back on a crude printable ASCII approximation.
 +------------------------+------------------------------------------+
 | .. data:: ACS_UARROW   | up arrow                                 |
 +------------------------+------------------------------------------+
-| .. data:: ACS_ULCORNER | upper left corner                        |
+| .. data:: ACS_ULCORNER | upper-left corner                        |
 +------------------------+------------------------------------------+
-| .. data:: ACS_URCORNER | upper right corner                       |
+| .. data:: ACS_URCORNER | upper-right corner                       |
 +------------------------+------------------------------------------+
 | .. data:: ACS_VLINE    | vertical line                            |
 +------------------------+------------------------------------------+
@@ -1880,9 +1887,9 @@ The module :mod:`!curses.textpad` defines the following function:
 
    Draw a rectangle.  The first argument must be a window object; the remaining
    arguments are coordinates relative to that window.  The second and third
-   arguments are the y and x coordinates of the upper left hand corner of the
+   arguments are the y and x coordinates of the upper-left corner of the
    rectangle to be drawn; the fourth and fifth arguments are the y and x
-   coordinates of the lower right hand corner. The rectangle will be drawn using
+   coordinates of the lower-right corner. The rectangle will be drawn using
    VT100/IBM PC forms characters on terminals that make this possible (including
    xterm and most other software terminal emulators).  Otherwise it will be drawn
    with ASCII  dashes, vertical bars, and plus signs.
@@ -1903,7 +1910,7 @@ You can instantiate a :class:`Textbox` object as follows:
    be contained.  If *insert_mode* is true, the textbox inserts typed
    characters, shifting existing text to the right, rather than overwriting it.
    The edit cursor of the textbox is initially located at the
-   upper left hand corner of the containing window, with coordinates ``(0, 0)``.
+   upper-left corner of the containing window, with coordinates ``(0, 0)``.
    The instance's :attr:`stripspaces` flag is initially on.
 
    :class:`Textbox` objects have the following methods:

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`