diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst index c18f2bb38b9ff1..0d03eca88b6267 100644 --- a/Doc/library/dialog.rst +++ b/Doc/library/dialog.rst @@ -209,19 +209,16 @@ string, an empty tuple, an empty list or ``None``. .. class:: Open(master=None, **options) SaveAs(master=None, **options) + Directory(master=None, **options) - The above two classes provide native dialog windows for saving and loading - files. + The above three classes provide native dialog windows for loading and saving + files and for selecting a directory. **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. @@ -361,23 +358,25 @@ the classic (non-themed) Tk widgets. .. data:: DIALOG_ICON - The name of the default bitmap (``'questhead'``) displayed by a - :class:`Dialog`. + The name of a bitmap (``'questhead'``) suitable for use as the *bitmap* + of 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). + The options, given through *cnf* or as keyword arguments, are all required: + *title* (the window title), *text* (the message), *bitmap* (the name of a + bitmap icon, such as :data:`DIALOG_ICON`), *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. + Do nothing. + The dialog window is destroyed automatically before the constructor + returns, so there is nothing left for this method to do. .. seealso:: diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst index 7fd561ade2f8bc..47fe680bac9107 100644 --- a/Doc/library/tkinter.messagebox.rst +++ b/Doc/library/tkinter.messagebox.rst @@ -13,9 +13,7 @@ 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). +the button the user pressed, as a string (such as :data:`OK` or :data:`YES`). Common message box styles and layouts include but are not limited to: .. figure:: tk_msg.png diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index d2bd075c2e17d7..6962528b6a1fcd 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -2356,8 +2356,8 @@ Base and mixin classes If all four arguments are given, the window manager keeps the ratio between ``minNumer/minDenom`` and ``maxNumer/maxDenom``; passing empty strings removes any existing restriction. - With no arguments, return a tuple of the four current values, or an empty - string if no aspect restriction is in effect. + With no arguments, return a tuple of the four current values, or ``None`` + if no aspect restriction is in effect. :meth:`wm_aspect` is an alias of :meth:`!aspect`. .. method:: wm_attributes(*args, return_python_dict=False, **kwargs) @@ -2582,8 +2582,8 @@ Base and mixin classes window's internally requested size, and *widthInc* and *heightInc* are the pixel sizes of a horizontal and vertical grid unit. Empty strings turn off gridded management. - With no arguments, return a tuple of the four current values, or an empty - string if the window is not gridded. + With no arguments, return a tuple of the four current values, or ``None`` + if the window is not gridded. :meth:`wm_grid` is an alias of :meth:`!grid`. Not to be confused with the grid geometry manager :meth:`Grid.grid`. @@ -2696,8 +2696,8 @@ Base and mixin classes Set or query a hint to the window manager about where the window's icon should be positioned. Empty strings cancel an existing hint. - With no arguments, return a tuple of the two current values, or an empty - string if no hint is in effect. + With no arguments, return a tuple of the two current values, or ``None`` + if no hint is in effect. :meth:`wm_iconposition` is an alias of :meth:`!iconposition`. .. method:: wm_iconwindow(pathName=None) @@ -2766,7 +2766,8 @@ Base and mixin classes When this flag is set, the window is ignored by the window manager: it is not reparented into a decorative frame and the user cannot manipulate it through the usual window manager controls. - With no argument, return a boolean indicating whether the flag is set. + With no argument, return a boolean indicating whether the flag is set, + or ``None`` if it has not been set. The flag is reliably honored only when the window is first mapped or remapped from the withdrawn state. :meth:`wm_overrideredirect` is an alias of :meth:`!overrideredirect`. diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index fdffa5ebb5da45..33cbaa3ca90d02 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -42,8 +42,9 @@ To override the basic Tk widgets, the import should follow the Tk import:: That code causes several :mod:`!tkinter.ttk` widgets (:class:`Button`, :class:`Checkbutton`, :class:`Entry`, :class:`Frame`, :class:`Label`, -:class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`, -:class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`) to +:class:`LabelFrame`, :class:`Menubutton`, :class:`OptionMenu`, +:class:`PanedWindow`, :class:`Radiobutton`, :class:`Scale`, +:class:`Scrollbar` and :class:`Spinbox`) to automatically replace the Tk widgets. This has the direct benefit of using the new widgets which gives a better look @@ -1039,6 +1040,9 @@ ttk.Treeview The minimum width of the column in pixels. The treeview widget will not make the column any smaller than specified by this option when the widget is resized or the user drags a column. + *separator*: ``True``/``False`` + Specifies whether a column separator should be drawn to the right of + the column. *stretch*: ``True``/``False`` Specifies whether the column's width should be adjusted when the widget is resized. @@ -2167,8 +2171,11 @@ and inherits the common methods of :class:`Widget`. display in the menu. A *command* keyword argument may be given to specify a callable that is invoked with the selected value whenever the selection changes; the *style* - keyword argument sets the style used by the underlying menubutton; and the - *name* keyword argument sets the Tk widget name. + keyword argument sets the style used by the underlying menubutton; the + *direction* keyword argument sets where the menu is posted relative to the + menubutton (one of ``'above'``, ``'below'`` (the default), ``'left'``, + ``'right'`` or ``'flush'``); and the *name* keyword argument sets the Tk + widget name. .. method:: set_menu(default=None, *values) diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py index afc68726f7c8d5..dde4accecf61ba 100644 --- a/Lib/tkinter/__init__.py +++ b/Lib/tkinter/__init__.py @@ -3,7 +3,7 @@ Tkinter provides classes which allow the display, positioning and control of widgets. Toplevel widgets are Tk and Toplevel. Other widgets are Frame, Label, Entry, Text, Canvas, Button, Radiobutton, -Checkbutton, Scale, Listbox, Scrollbar, OptionMenu, Spinbox +Checkbutton, Scale, Listbox, Scrollbar, OptionMenu, Spinbox, LabelFrame and PanedWindow. Properties of the widgets are specified with keyword arguments. @@ -2528,7 +2528,7 @@ def wm_iconphoto(self, default=False, *args): # new in Tk 8.5 def wm_iconposition(self, x=None, y=None): """Set the position of the icon of this widget to X and Y. Return - a tuple of the current values of X and X if None is given.""" + a tuple of the current values of X and Y if None is given.""" return self._getints(self.tk.call( 'wm', 'iconposition', self._w, x, y)) diff --git a/Lib/tkinter/colorchooser.py b/Lib/tkinter/colorchooser.py index e2fb69dba92763..4085bde1637a79 100644 --- a/Lib/tkinter/colorchooser.py +++ b/Lib/tkinter/colorchooser.py @@ -1,3 +1,5 @@ +"""Interface to the native Tk color selection dialog.""" + # tk common color chooser dialogue # # this module provides an interface to the native color dialogue diff --git a/Lib/tkinter/commondialog.py b/Lib/tkinter/commondialog.py index 86f5387e001bf2..408cedc345def6 100644 --- a/Lib/tkinter/commondialog.py +++ b/Lib/tkinter/commondialog.py @@ -1,3 +1,5 @@ +"""Base class for the Tk common dialogs.""" + # base class for tk common dialogues # # this module provides a base class for accessing the common diff --git a/Lib/tkinter/dialog.py b/Lib/tkinter/dialog.py index 36ae6c277cb66a..ef005af0d5a19c 100644 --- a/Lib/tkinter/dialog.py +++ b/Lib/tkinter/dialog.py @@ -1,5 +1,7 @@ # dialog.py -- Tkinter interface to the tk_dialog script. +"""Classic Tk dialog box, wrapping the tk_dialog script.""" + from tkinter import _cnfmerge, Widget, TclError, Button, Pack __all__ = ["Dialog"] @@ -8,6 +10,8 @@ class Dialog(Widget): + """A modal dialog box built from the classic (non-themed) Tk widgets.""" + def __init__(self, master=None, cnf={}, **kw): cnf = _cnfmerge((cnf, kw)) self.widgetName = '__dialog__' @@ -21,7 +25,8 @@ def __init__(self, master=None, cnf={}, **kw): try: Widget.destroy(self) except TclError: pass - def destroy(self): pass + def destroy(self): + """Do nothing; the dialog window is already destroyed.""" def _test(): diff --git a/Lib/tkinter/font.py b/Lib/tkinter/font.py index 7ce7047885fce5..5b663a4e456456 100644 --- a/Lib/tkinter/font.py +++ b/Lib/tkinter/font.py @@ -1,3 +1,5 @@ +"""Utilities to help work with fonts in Tkinter.""" + # Tkinter font wrapper # # written by Fredrik Lundh, February 1998 diff --git a/Lib/tkinter/messagebox.py b/Lib/tkinter/messagebox.py index dd2816cffb1140..f6848142a9aff6 100644 --- a/Lib/tkinter/messagebox.py +++ b/Lib/tkinter/messagebox.py @@ -1,3 +1,5 @@ +"""Interface to the standard Tk message boxes.""" + # tk common message boxes # # this module provides an interface to the native message boxes diff --git a/Lib/tkinter/simpledialog.py b/Lib/tkinter/simpledialog.py index c61881d4872421..1b0cf51317ee08 100644 --- a/Lib/tkinter/simpledialog.py +++ b/Lib/tkinter/simpledialog.py @@ -8,7 +8,7 @@ # fredrik@pythonware.com # http://www.pythonware.com # -"""This modules handles dialog boxes. +"""This module handles dialog boxes. It contains the following public symbols: