From cca51459524131915d2f67a56172b98f39a2eb51 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 09:08:42 +0300 Subject: [PATCH 01/18] gh-59551: Document the full public API of tkinter 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. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/dialog.rst | 114 +- Doc/library/tkinter.colorchooser.rst | 18 +- Doc/library/tkinter.dnd.rst | 7 +- Doc/library/tkinter.font.rst | 31 +- Doc/library/tkinter.messagebox.rst | 16 +- Doc/library/tkinter.rst | 4347 ++++++++++++++++- Doc/library/tkinter.scrolledtext.rst | 4 +- Doc/library/tkinter.ttk.rst | 310 +- ...6-06-17-12-00-00.gh-issue-59551.__bOgH.rst | 4 + 9 files changed, 4775 insertions(+), 76 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2026-06-17-12-00-00.gh-issue-59551.__bOgH.rst diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst index 5d522556235a02b..c416fbe51621ab4 100644 --- a/Doc/library/dialog.rst +++ b/Doc/library/dialog.rst @@ -36,6 +36,39 @@ 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 @@ -77,34 +110,43 @@ 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 +210,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. @@ -188,8 +237,8 @@ These do not emulate the native look-and-feel of the platform. .. method:: ok_command() - Test that a file is provided and that the selection indicates an - already existing file. + Test that a file is provided and that the selection + indicates an already existing file. .. class:: SaveFileDialog(master, title=None) @@ -198,9 +247,9 @@ These do not emulate the native look-and-feel of the platform. .. 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. + 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -222,6 +271,39 @@ 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` diff --git a/Doc/library/tkinter.colorchooser.rst b/Doc/library/tkinter.colorchooser.rst index 73f8f76a21044b0..23627cdbc91eeda 100644 --- a/Doc/library/tkinter.colorchooser.rst +++ b/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 + diff --git a/Doc/library/tkinter.dnd.rst b/Doc/library/tkinter.dnd.rst index 48d16ccb204b9d5..caa69467d3680f0 100644 --- a/Doc/library/tkinter.dnd.rst +++ b/Doc/library/tkinter.dnd.rst @@ -48,7 +48,8 @@ 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) @@ -56,7 +57,9 @@ Selection of a target object occurs as follows: .. 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:: diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 9eecb803c3aedcb..c11b272c17dd510 100644 --- a/Doc/library/tkinter.font.rst +++ b/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) @@ -46,7 +50,10 @@ 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) @@ -56,6 +63,12 @@ The different font weights and slants are: Modify attributes of the font. + .. method:: configure(**options) + + Modify one or more attributes of the font. With no arguments, return a + dictionary of the current attributes. :meth:`config` is an alias of + :meth:`configure`. + .. method:: copy() Return new instance of the current font. @@ -63,12 +76,14 @@ 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. + 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 +99,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. diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst index 2a69d282638529d..92eebad039e8968 100644 --- a/Doc/library/tkinter.messagebox.rst +++ b/Doc/library/tkinter.messagebox.rst @@ -10,10 +10,12 @@ 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: +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 @@ -77,19 +79,19 @@ limited to: .. function:: showinfo(title=None, message=None, **options) Creates and displays an information message box with the specified title - and message. + and message. Return the symbolic name :data:`OK` (the string ``'ok'``). **Warning message boxes** .. function:: showwarning(title=None, message=None, **options) Creates and displays a warning message box with the specified title - and message. + and message. Return the symbolic name :data:`OK` (the string ``'ok'``). .. function:: showerror(title=None, message=None, **options) Creates and displays an error message box with the specified title - and message. + and message. Return the symbolic name :data:`OK` (the string ``'ok'``). **Question message boxes** diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index a34b74a088874fe..fde0e909a904171 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -18,10 +18,14 @@ properly installed on your system, and also showing what version of Tcl/Tk is installed, so you can read the Tcl/Tk documentation specific to that version. Tkinter supports a range of Tcl/Tk versions, built either with or -without thread support. The official Python binary release bundles Tcl/Tk 8.6 -threaded. See the source code for the :mod:`_tkinter` module +without thread support. Tcl/Tk 8.5.12 is the minimum supported version; the +official Python binary release bundles Tcl/Tk 9.0. +See the source code for the :mod:`_tkinter` module for more information about supported versions. +.. versionchanged:: 3.11 + Support for Tcl/Tk versions older than 8.5.12 was removed. + Tkinter is not a thin wrapper, but adds a fair amount of its own logic to make the experience more pythonic. This documentation will concentrate on these additions and changes, and refer to the official Tcl/Tk documentation for @@ -47,7 +51,7 @@ details that are unchanged. Tcl/Tk Resources: - * `Tk commands `_ + * `Tk commands `_ Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter. * `Tcl/Tk Home Page `_ @@ -188,6 +192,34 @@ the modern themed widget set and API:: child widget names as the keys and the child instance objects as the values. + .. method:: destroy() + + Destroy this and all descendant widgets and, for the main window, end the + connection to the underlying Tcl interpreter. + + .. method:: loadtk() + + Finish loading and initializing the Tk subsystem. This is needed only + when the interpreter was created without Tk (for example through + :func:`Tcl`); it is called automatically when *useTk* is true. + + .. method:: readprofile(baseName, className) + + Read and source the user's profile files :file:`.{className}.tcl` and + :file:`.{baseName}.tcl` into the Tcl interpreter, and execute the + corresponding :file:`.{className}.py` and :file:`.{baseName}.py` files. + This is called during initialization; see the description of the + constructor above. + + .. method:: report_callback_exception(exc, val, tb) + + Report a callback exception. This is called when an exception propagates + out of a Tkinter callback; *exc*, *val* and *tb* are the exception type, + value and traceback as returned by :func:`sys.exc_info`. The default + implementation prints a traceback to :data:`sys.stderr`. It can be + overridden to customize error handling, for example to display the + traceback in a dialog. + .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) @@ -446,7 +478,7 @@ is helpful. Navigating the Tcl/Tk Reference Manual ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As noted, the official `Tk commands `_ +As noted, the official `Tk commands `_ reference manual (man pages) is often the most accurate description of what specific operations on widgets do. Even when you know the name of the option or method that you need, you may still have a few places to look. @@ -475,20 +507,20 @@ name of a method to call). In the official Tcl/Tk reference documentation, you'll find most operations that look like method calls on the man page for a specific widget (e.g., you'll find the :meth:`invoke` method on the -`ttk::button `_ +`ttk::button `_ man page), while functions that take a widget as a parameter often have their own man page (e.g., -`grid `_). +`grid `_). You'll find many common options and methods in the -`options `_ or -`ttk::widget `_ man +`options `_ or +`ttk::widget `_ man pages, while others are found in the man page for a specific widget class. You'll also find that many Tkinter methods have compound names, e.g., :func:`winfo_x`, :func:`winfo_height`, :func:`winfo_viewable`. You'd find documentation for all of these in the -`winfo `_ man page. +`winfo `_ man page. .. note:: Somewhat confusingly, there are also methods on all Tkinter widgets @@ -532,7 +564,9 @@ interpreter will fail. A number of special cases exist: -* Tcl/Tk libraries can be built so they are not thread-aware. In this case, +* Tcl/Tk libraries built without thread support are now rare: Tcl/Tk 9.0 (the + bundled version) is always thread-aware, so this case only arises with some + older 8.x builds. When the library is not thread-aware, :mod:`!tkinter` calls the library from the originating Python thread, even if this is different than the thread that created the Tcl interpreter. A global lock ensures only one call occurs at a time. @@ -630,6 +664,8 @@ Of course, the dictionary printed will include all the options available and their values. This is meant only as an example. +.. _pack-the-packer: + The Packer ^^^^^^^^^^ @@ -689,6 +725,8 @@ side Legal values are: ``'left'``, ``'right'``, ``'top'``, ``'bottom'``. +.. _coupling-widget-variables: + Coupling Widget Variables ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -758,9 +796,11 @@ directly. To get at the toplevel window that contains a given widget, you can often just refer to the widget's :attr:`master`. Of course if the widget has been packed inside of a frame, the :attr:`!master` won't represent a toplevel window. To get at the toplevel -window that contains an arbitrary widget, you can call the :meth:`_root` method. -This method begins with an underscore to denote the fact that this function is -part of the implementation, and not an interface to Tk functionality. +window that contains an arbitrary widget, you can call the :meth:`winfo_toplevel` +method. There is also a :meth:`_root` method; it begins with an underscore to +denote the fact that this function is part of the implementation, and not an +interface to Tk functionality. It returns the application's root window rather +than the nearest enclosing toplevel. Here are some examples of typical usage:: @@ -794,10 +834,11 @@ anchor ``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``. bitmap - There are eight built-in, named bitmaps: ``'error'``, ``'gray25'``, - ``'gray50'``, ``'hourglass'``, ``'info'``, ``'questhead'``, ``'question'``, - ``'warning'``. To specify an X bitmap filename, give the full path to the file, - preceded with an ``@``, as in ``"@/usr/contrib/bitmap/gumby.bit"``. + There are ten built-in, named bitmaps: ``'error'``, ``'gray12'``, + ``'gray25'``, ``'gray50'``, ``'gray75'``, ``'hourglass'``, ``'info'``, + ``'questhead'``, ``'question'``, ``'warning'``. To specify an X bitmap + filename, give the full path to the file, preceded with an ``@``, as in + ``"@/usr/contrib/bitmap/gumby.bit"``. boolean You can pass integers 0 or 1 or the strings ``"yes"`` or ``"no"``. @@ -829,9 +870,11 @@ distance as ``"3.5i"``. font - Tk uses a list font name format, such as ``{courier 10 bold}``. Font sizes with - positive numbers are measured in points; sizes with negative numbers are - measured in pixels. + Tk uses a font description such as ``{courier 10 bold}``; in + :mod:`!tkinter` this is most naturally passed as a tuple of + ``(family, size, *styles)`` (or as the equivalent string + ``"Courier 10 bold"``). Font sizes with positive numbers are measured in + points; sizes with negative numbers are measured in pixels. geometry This is a string of the form ``widthxheight``, where width and height are @@ -848,7 +891,8 @@ region relief Determines what the border style of a widget will be. Legal values are: - ``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, and ``"ridge"``. + ``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, ``"ridge"``, and + ``"solid"``. scrollcommand This is almost always the :meth:`!set` method of some scrollbar widget, but can @@ -875,7 +919,10 @@ of the bind method is:: where: sequence - is a string that denotes the target kind of event. (See the + is a string that denotes the target kind of event. Physical events use the + ```` form (for example ``""`` or + ``""``); application-defined virtual events use double angle + brackets, as in ``"<>"``. (See the :manpage:`bind(3tk)` man page, and page 201 of John Ousterhout's book, :title-reference:`Tcl and the Tk Toolkit (2nd edition)`, for details). @@ -921,6 +968,10 @@ they are denoted in Tk, which can be useful when referring to the Tk man pages. +----+---------------------+----+---------------------+ | %y | y | %Y | y_root | +----+---------------------+----+---------------------+ +| %# | serial | %b | num | ++----+---------------------+----+---------------------+ +| %d | detail | %D | delta | ++----+---------------------+----+---------------------+ The index Parameter @@ -1046,3 +1097,4255 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``. EXCEPTION Constants used in the *mask* arguments. + + +Reference +--------- + +.. currentmodule:: tkinter + +This section documents the classes, methods, functions and constants of the +:mod:`!tkinter` module. Most of them wrap Tcl/Tk commands; consult the official +Tcl/Tk manual pages for the full list of widget options and further details. + +Base and mixin classes +^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: Misc() + + The :class:`!Misc` class is a mix-in inherited by :class:`Tk` and, through + :class:`BaseWidget`, by every widget. It provides the large set of methods + common to all Tk objects: querying window information, managing event + bindings and the event loop, controlling the keyboard focus and pointer + grabs, accessing the selection, clipboard and option database, and assorted + utility and introspection services. Because they are inherited, these + methods are available on every widget and on the :class:`Tk` application + object, and are documented here once rather than repeated for each widget. + + .. method:: cget(key) + + Return the current value of the configuration option named *key* for this + widget, as a string. The expression ``widget[key]`` is equivalent and may + be used instead. + + .. method:: configure(cnf=None, **kw) + config(cnf=None, **kw) + + Query or modify the configuration options of the widget. With no + arguments, return a dictionary mapping every available option name to a + tuple describing it (its name, X resource name, X resource class, default + value and current value). If a single option name is given as a string, + return the tuple for just that option. If one or more keyword arguments + are given, or a dictionary is passed as *cnf*, set each named option to the + corresponding value; the expression ``widget[key] = value`` sets a single + option in the same way. + + ``config`` is an alias of :meth:`!configure`. + + .. method:: keys() + + Return a list of the names of all configuration options of this widget. + + .. method:: getboolean(s) + + Interpret the string *s* as a Tcl boolean and return the corresponding + :class:`bool`. Tcl accepts values such as ``'1'``, ``'0'``, ``'yes'``, + ``'no'``, ``'true'`` and ``'false'``. Raise :exc:`ValueError` if *s* is + not a valid boolean. + + .. method:: getdouble(s) + + Interpret the string *s* as a Tcl floating-point number and return it as a + :class:`float`. Raise :exc:`ValueError` if *s* is not a valid number. + + .. versionadded:: 3.5 + + + .. method:: getint(s) + + Interpret the string *s* as a Tcl integer and return it as an :class:`int`. + Raise :exc:`ValueError` if *s* is not a valid integer. + + .. method:: getvar(name='PY_VAR') + + Return the value of the Tcl global variable named *name*. + + .. method:: setvar(name='PY_VAR', value='1') + + Set the Tcl global variable named *name* to *value*. + + The :meth:`!getvar` and :meth:`!setvar` methods give direct access to Tcl + variables. In most code you will instead use a :class:`Variable` subclass + such as :class:`StringVar` or :class:`IntVar`, which wraps a Tcl variable + and converts its value to and from a Python type. + + .. method:: register(func, subst=None, needcleanup=1) + + Register the Python callable *func* as a Tcl command and return the name of + the new command as a string. Whenever Tcl invokes that command, *func* is + called; if *subst* is given, it is applied to the command's arguments + first. This is the mechanism used internally to turn Python callbacks into + the command names passed to Tk options such as *command*. Unless + *needcleanup* is false, the command is deleted automatically when the + widget is destroyed. + + .. versionchanged:: 3.13 + The arguments passed to *func* are no longer converted to strings. + + .. method:: deletecommand(name) + + Delete the Tcl command named *name*, such as one previously returned by + :meth:`register`. + + .. method:: nametowidget(name) + + Return the widget instance corresponding to the Tk pathname *name*. + + .. method:: send(interp, cmd, *args) + + Send the Tcl command *cmd*, with the given *args*, to the Tcl interpreter + registered under the name *interp*, and return its result. This is not + available on all platforms. + + .. method:: destroy() + + Destroy this widget and all of its descendant widgets, and delete the Tcl + commands associated with them. + + .. method:: tkraise(aboveThis=None) + lift(aboveThis=None) + + Raise this widget in the stacking order so that it is drawn on top of its + siblings. If *aboveThis* is given, the widget is moved to be just above + it in the stacking order instead. + + ``lift`` is an alias of :meth:`!tkraise`. + + .. method:: lower(belowThis=None) + + Lower this widget in the stacking order so that it is drawn beneath its + siblings. If *belowThis* is given, the widget is moved to be just below + it in the stacking order instead. + + .. method:: image_names() + + Return the names of all images that currently exist in the Tcl + interpreter. + + .. method:: image_types() + + Return the available image types, such as ``'photo'`` and ``'bitmap'``. + + .. method:: grid_anchor(anchor=None) + anchor(anchor=None) + + Set the anchor that controls where the grid is placed inside this + container when the container is larger than the grid and no row or column + has a non-zero weight. *anchor* is one of the usual anchor strings, such + as ``'nw'`` (the default) or ``'center'``. Called with no argument, this + method has no effect. + + ``anchor`` is an alias of :meth:`!grid_anchor`. + + .. versionadded:: 3.3 + + .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) + bbox(column=None, row=None, col2=None, row2=None) + + Return the bounding box, in pixels, of a region of the grid laid out in + this container, as a 4-tuple ``(xoffset, yoffset, width, height)``. With + no arguments the bounding box of the whole grid is returned. If *column* + and *row* are given, the box spans from the cell at row and column 0 to + that cell; if *col2* and *row2* are also given, it spans from the cell + (*column*, *row*) to the cell (*col2*, *row2*). + + ``bbox`` is an alias of :meth:`!grid_bbox`. + + .. method:: grid_columnconfigure(index, cnf={}, **kw) + columnconfigure(index, cnf={}, **kw) + + Query or set the properties of the column (or columns) *index* of the grid + managed by this container. The valid options are *minsize* (the column's + minimum size in pixels), *weight* (how much of any extra space is given to + the column), *uniform* (a group name; columns sharing a group are kept the + same width in proportion to their weights) and *pad* (extra space added to + the column). With a single option name, return that option's value; with + no options, return a dictionary of all of them. + + ``columnconfigure`` is an alias of :meth:`!grid_columnconfigure`. + + .. method:: grid_rowconfigure(index, cnf={}, **kw) + rowconfigure(index, cnf={}, **kw) + + Query or set the properties of the row (or rows) *index* of the grid + managed by this container. The valid options are the same as for + :meth:`grid_columnconfigure`, applied to a row instead of a column. + + ``rowconfigure`` is an alias of :meth:`!grid_rowconfigure`. + + .. method:: grid_location(x, y) + + Return the ``(column, row)`` of the grid cell that contains the pixel at + position (*x*, *y*), given in pixels relative to this container. For + locations above or to the left of the grid, ``-1`` is returned for the + corresponding coordinate. + + .. method:: grid_propagate(flag=['_noarg_']) + + Enable or disable geometry propagation for this container when it manages + its children with the grid geometry manager. When *flag* is true, the + container resizes itself to fit the requested sizes of its children; when + it is false, its size is left under your control. Called with no argument, + return the current setting as a boolean. + + .. method:: grid_size() + size() + + Return the size of the grid managed by this container as a + ``(columns, rows)`` tuple. + + ``size`` is an alias of :meth:`!grid_size`. + + .. method:: grid_slaves(row=None, column=None) + + Return a list of the child widgets managed in this container's grid, most + recently managed first. If *row* or *column* is given, only the children + in that row or column are returned. + + .. method:: grid_content(row=None, column=None) + + Same as :meth:`grid_slaves`: return the child widgets managed in this + container's grid, optionally restricted to a given *row* or *column*. + + .. versionadded:: 3.15 + + + .. method:: pack_propagate(flag=['_noarg_']) + propagate(flag=['_noarg_']) + + Enable or disable geometry propagation for this container when it manages + its children with the pack geometry manager. When *flag* is true, the + container resizes itself to fit the requested sizes of its children; when + it is false, its size is left under your control. Called with no argument, + return the current setting as a boolean. + + ``propagate`` is an alias of :meth:`!pack_propagate`. + + .. method:: pack_slaves() + slaves() + + Return a list of the child widgets managed by this container with the pack + geometry manager, in packing order. + + ``slaves`` is an alias of :meth:`!pack_slaves`. + + .. method:: pack_content() + content() + + Same as :meth:`pack_slaves`: return the child widgets managed by this + container with the pack geometry manager, in packing order. + + ``content`` is an alias of :meth:`!pack_content`. + + .. versionadded:: 3.15 + + + .. method:: place_slaves() + + Return a list of the child widgets managed by this container with the + place geometry manager. + + .. method:: place_content() + + Same as :meth:`place_slaves`: return the child widgets managed by this + container with the place geometry manager. + + .. versionadded:: 3.15 + + .. method:: bind(sequence=None, func=None, add=None) + + Bind the event pattern *sequence* on this widget to the callable *func*. + + *sequence* is an event pattern, such as ``''`` (a mouse + click) or ``''``, optionally a concatenation of several such + patterns that must occur shortly after one another. When the event + occurs, *func* is called with an :class:`Event` instance describing it as + its only argument; if *func* returns the string ``'break'``, no further + bindings for the event are invoked. + + If *add* is true, *func* is added to any functions already bound to + *sequence*; otherwise it replaces them. The binding applies only to this + widget. + + :meth:`!bind` returns a string identifier (a *funcid*) that can later be + passed to :meth:`unbind` to remove the binding without leaking the + associated Tcl command. + + If *func* is omitted, return the binding currently associated with + *sequence*; if *sequence* is also omitted, return a list of all the + sequences for which bindings exist on this widget. + + .. method:: bind_class(className, sequence=None, func=None, add=None) + + Like :meth:`bind`, but bind *func* to the binding tag *className* rather + than to a single widget, so that the binding applies to every widget + having that tag. *className* is usually the name of a widget class, such + as ``'Button'``, in which case the binding affects all widgets of that + class. The set of binding tags for a widget can be inspected and changed + with :meth:`bindtags`. + + The remaining arguments and the return value are as for :meth:`bind`. + + .. method:: bind_all(sequence=None, func=None, add=None) + + Like :meth:`bind`, but bind *func* to the special binding tag ``'all'``, + so that the binding applies to every widget in the application. + + The remaining arguments and the return value are as for :meth:`bind`. + + .. method:: unbind(sequence, funcid=None) + + Remove bindings for the event pattern *sequence* on this widget. + + If *funcid* is given, only the function identified by it (a value returned + from a previous call to :meth:`bind`) is removed, and its associated Tcl + command is deleted. Otherwise all bindings for *sequence* are destroyed, + leaving it unbound. + + .. versionchanged:: 3.13 + If *funcid* is given, only that callback is unbound; other callbacks + bound to *sequence* are kept. + + + .. method:: unbind_class(className, sequence) + + Remove all bindings for the event pattern *sequence* from the binding tag + *className*. See :meth:`bind_class`. + + .. method:: unbind_all(sequence) + + Remove all bindings for the event pattern *sequence* from the special + binding tag ``'all'``. See :meth:`bind_all`. + + .. method:: bindtags(tagList=None) + + If *tagList* is omitted, return a tuple of the binding tags associated + with this widget. When an event occurs in a widget, it is applied to each + of the widget's binding tags in order, and for each tag the most specific + matching binding is executed. By default a widget has four binding tags: + its own pathname, its widget class, the pathname of its nearest toplevel + ancestor, and ``'all'``, in that order. + + If *tagList* is given, it must be a sequence of strings; the widget's + binding tags are set to its elements, which determines the order in which + bindings are evaluated. + + .. method:: event_add(virtual, *sequences) + + Associate the virtual event *virtual*, whose name has the form + ``'<>'``, with each of the physical event patterns given by + *sequences*, so that the virtual event triggers whenever any of them + occurs. If *virtual* is already defined, the new sequences are added to + its existing ones. + + .. method:: event_delete(virtual, *sequences) + + Remove each of *sequences* from those associated with the virtual event + *virtual*. Sequences that are not currently associated with *virtual* are + ignored. If no *sequences* are given, all physical event sequences are + removed, so that *virtual* no longer triggers. + + .. method:: event_generate(sequence, **kw) + + Generate the event *sequence* on this widget and arrange for it to be + processed just as if it had come from the window system. *sequence* must + be a single event pattern, such as ``''`` or ``'<>'``, + not a concatenation of several. Keyword arguments specify additional + fields of the event, for example *x* and *y* for the pointer position, or + *when* to control when the event is processed; refer to the Tk ``event`` + manual page for the full list. + + .. method:: event_info(virtual=None) + + If *virtual* is omitted, return a tuple of all the virtual events that are + currently defined. If *virtual* is given, return a tuple of the physical + event sequences currently associated with it, or an empty tuple if it is + not defined. + + .. method:: after(ms, func=None, *args, **kw) + + Schedule the callable *func* to be called after *ms* milliseconds, with + *args* and *kw* passed to it as positional and keyword arguments. Return + an identifier that can be passed to :meth:`after_cancel` to cancel the + call. + + If *func* is omitted, sleep for *ms* milliseconds instead, processing no + events during that time, and return ``None``. + + .. versionchanged:: 3.10 + *func* can now be any callable object, not only a function. + + .. versionchanged:: 3.14 + Keyword arguments are now passed to *func*. + + + .. method:: after_cancel(id) + + Cancel a callback previously scheduled with :meth:`after` or + :meth:`after_idle`. *id* must be an identifier returned by one of those + methods; passing a value that is not such an identifier raises + :exc:`ValueError`. If the callback has already run or been cancelled, + this has no effect. + + .. versionchanged:: 3.7 + Passing ``None`` (or any false value) as *id* now raises + :exc:`ValueError`. + + + .. method:: after_idle(func, *args, **kw) + + Schedule the callable *func* to be called, with *args* and *kw* passed to + it, when the Tk main loop next becomes idle, that is, when it has no other + events to process. Return an identifier that can be passed to + :meth:`after_cancel` to cancel the call. + + .. versionchanged:: 3.14 + Keyword arguments are now passed to *func*. + + + .. method:: after_info(id=None) + + If *id* is omitted, return a tuple of the identifiers of all callbacks + currently scheduled with :meth:`after` and :meth:`after_idle` for this + interpreter. + + If *id* is given, it must identify a callback that has not yet run or been + cancelled, and the return value is a tuple ``(script, type)``, where + *script* refers to the function to be called and *type* is either + ``'idle'`` or ``'timer'``. A :exc:`TclError` is raised if *id* does not + exist. + + .. versionadded:: 3.13 + + + .. method:: mainloop(n=0) + + Enter the Tk event loop, which processes events until all windows are + destroyed. This is normally called once, on the root window, to run the + application. + + .. method:: quit() + + Quit the Tcl interpreter, causing :meth:`mainloop` to return. + + .. method:: update() + + Enter the event loop until all pending events, including idle callbacks, + have been processed. This brings the display up to date and handles any + events that are already queued, then returns. + + .. method:: update_idletasks() + + Enter the event loop until all pending idle callbacks have been called. + This updates the display of windows, for example after geometry changes, + but does not process events caused by the user. + + .. method:: wait_variable(name='PY_VAR') + waitvar(name='PY_VAR') + + Wait until the Tcl variable *name* is modified, continuing to process + events in the meantime so that the application stays responsive. *name* + is usually a :class:`Variable` instance, such as an :class:`IntVar` or + :class:`StringVar`. + + ``waitvar`` is an alias of :meth:`!wait_variable`. + + .. method:: wait_window(window=None) + + Wait until *window* is destroyed, continuing to process events in the + meantime. If *window* is omitted, this widget is used. This is typically + used to wait for the user to finish interacting with a dialog box. + + .. method:: wait_visibility(window=None) + + Wait until the visibility state of *window* changes, for example when it + first appears on the screen, continuing to process events in the meantime. + If *window* is omitted, this widget is used. This is typically used to + wait for a newly created window to become visible before acting on it. + .. method:: focus() + focus_set() + + Direct the keyboard input focus for this widget's display to this widget. + If the application does not currently have the input focus on this + widget's display, the widget is remembered as the focus window for its + top level, and the focus will be redirected to it the next time the + window manager gives the focus to the top level. ``focus`` is an alias + of :meth:`!focus_set`. + + .. method:: focus_force() + + Direct the keyboard input focus to this widget even if the application + does not currently have the input focus for the widget's display. This + method should be used sparingly, if at all; normally an application + should wait for the window manager to give it the focus rather than + claiming it. + + .. method:: focus_get() + + Return the widget that currently has the keyboard focus in the + application, or ``None`` if no widget in the application has the focus. + Use :meth:`focus_displayof` to work correctly with several displays. + + .. method:: focus_displayof() + + Return the widget that currently has the keyboard focus on the display + where this widget is located, or ``None`` if no widget in the application + has the focus on that display. + + .. method:: focus_lastfor() + + Return the most recent widget to have had the keyboard focus among all + the widgets in the same top level as this widget; this is the widget that + will receive the focus the next time the window manager gives the focus + to the top level. If no widget in that top level has ever had the focus, + or if the most recent focus widget has been deleted, the top level itself + is returned. + + .. method:: tk_focusFollowsMouse() + + Reconfigure Tk to use an implicit focus model in which the focus is set + to a widget whenever the mouse pointer enters it. This cannot easily be + disabled once enabled. + + .. method:: tk_focusNext() + + Return the next widget after this one in the keyboard traversal order, or + ``None`` if there is none. The traversal order goes first to the next + child, then recursively to the children of that child, and then to the + next sibling higher in the stacking order. A widget is skipped if its + ``takefocus`` option is set to ``0``. This method is used in the default + bindings for the :kbd:`Tab` key. + + .. method:: tk_focusPrev() + + Return the previous widget before this one in the keyboard traversal + order, or ``None`` if there is none. See :meth:`tk_focusNext` for how the + order is defined. This method is used in the default bindings for the + :kbd:`Shift-Tab` key. + + .. method:: grab_set() + + Set a local grab on this widget. A grab confines pointer events to this + widget and its descendants: while the pointer is outside the widget's + subtree, button presses and releases and pointer motion are reported to + the grab widget, and windows outside the subtree become insensitive until + the grab is released. A local grab affects only the grabbing + application. Any grab previously set by this application on the widget's + display is automatically released. Setting a grab is the usual way to + make a dialog modal: while the grab is in effect the user cannot interact + with the other windows of the application. + + .. method:: grab_set_global() + + Set a global grab on this widget. A global grab is like the local grab + set by :meth:`grab_set`, but it locks out all other applications on the + screen, so that only this widget's subtree is sensitive to pointer + events, and it also grabs the keyboard. Use with caution: it is easy to + render a display unusable with a global grab, since other applications + stop receiving events until it is released. + + .. method:: grab_release() + + Release the grab on this widget if there is one; otherwise do nothing. + + .. method:: grab_current() + + Return the widget that currently holds the grab in this application for + this widget's display, or ``None`` if there is no such widget. + + .. method:: grab_status() + + Return ``None`` if no grab is currently set on this widget, ``"local"`` + if a local grab is set, or ``"global"`` if a global grab is set. + + .. method:: selection_clear(**kw) + + Clear the X selection, so that no window owns it anymore. The selection + to clear is given by the keyword argument *selection*, an atom name such + as ``'PRIMARY'`` or ``'CLIPBOARD'``; it defaults to ``PRIMARY``. The + *displayof* keyword argument names a widget that determines the display on + which to operate, and defaults to this widget. + + .. method:: selection_get(**kw) + + Return the contents of the current X selection. The keyword argument + *selection* names the selection and defaults to ``PRIMARY``. The keyword + argument *type* specifies the form in which the data is to be returned + (the desired conversion target), an atom name such as ``'STRING'`` or + ``'FILE_NAME'``; it defaults to ``STRING``, except on X11, where + ``UTF8_STRING`` is tried first and ``STRING`` is used as a fallback. The + *displayof* keyword argument names a widget that determines the display + from which to retrieve the selection, and defaults to this widget. + + .. method:: selection_handle(command, **kw) + + Register *command* as a handler to supply the X selection owned by this + widget when another application requests it. When the selection is + retrieved, *command* is called with two arguments, the starting character + offset and the maximum number of characters to return, and must return at + most that many characters of the selection starting at that offset; for + very long selections it is called repeatedly with increasing offsets. + The keyword argument *selection* names the selection (default + ``PRIMARY``) and the keyword argument *type* gives the form of the + selection that the handler supplies (such as ``'STRING'`` or + ``'FILE_NAME'``, default ``STRING``). + + .. method:: selection_own(**kw) + + Make this widget the owner of the X selection on its display. The + previous owner, if any, is notified that it has lost the selection. The + keyword argument *selection* names the selection and defaults to + ``PRIMARY``. + + .. method:: selection_own_get(**kw) + + Return the widget in this application that owns the X selection on the + display containing this widget, or ``None`` if no widget in this + application owns the selection. The keyword argument *selection* names + the selection and defaults to ``PRIMARY``. The *displayof* keyword + argument names a widget that determines the display to query, and + defaults to this widget. + + .. method:: clipboard_append(string, **kw) + + Append *string* to the Tk clipboard and claim ownership of the clipboard + on this widget's display. Before appending, the clipboard should be + emptied with :meth:`clipboard_clear`; all appends should be completed + before returning to the event loop so that the clipboard is updated + atomically. The keyword argument *type* specifies the form of the data, + an atom name such as ``'STRING'`` or ``'FILE_NAME'`` (default + ``STRING``), and the keyword argument *format* specifies the + representation used to transmit it (default ``STRING``). The *displayof* + keyword argument names a widget that determines the target display, and + defaults to this widget. The contents can be retrieved with + :meth:`clipboard_get` or :meth:`selection_get`. + + .. method:: clipboard_clear(**kw) + + Claim ownership of the clipboard on this widget's display and remove any + previous contents. The *displayof* keyword argument names a widget that + determines the target display, and defaults to this widget. + + .. method:: clipboard_get(**kw) + + Retrieve data from the clipboard on this widget's display. The keyword + argument *type* specifies the form in which the data is to be returned, + an atom name such as ``'STRING'`` or ``'FILE_NAME'``; it defaults to + ``STRING``, except on X11, where ``UTF8_STRING`` is tried first and + ``STRING`` is used as a fallback. The *displayof* keyword argument names + a widget that determines the display, and defaults to the root window of + the application. This is equivalent to ``selection_get(selection= + 'CLIPBOARD')``. + + .. method:: option_add(pattern, value, priority=None) + + Add an option to the Tk option database that associates *value* with + *pattern*. *pattern* consists of names and/or classes separated by + asterisks or dots, in the usual X format. *priority* is an integer + between 0 and 100, or one of the symbolic names ``'widgetDefault'`` (20), + ``'startupFile'`` (40), ``'userDefault'`` (60), or ``'interactive'`` + (80); it defaults to ``interactive``. + + .. method:: option_clear() + + Clear the Tk option database. Default options from the + :envvar:`!RESOURCE_MANAGER` property or the :file:`.Xdefaults` file are + reloaded automatically the next time an option is added to or removed from + the database. + + .. method:: option_get(name, className) + + Return the value of the option matching this widget under *name* and + *className* from the Tk option database, or an empty string if there is no + matching entry. When several entries match, the one with the highest + priority is returned, and among entries of equal priority the most + recently added one. + + .. method:: option_readfile(fileName, priority=None) + + Read the file named *fileName*, which should have the standard format for + an X resource database such as :file:`.Xdefaults`, and add all the options + it specifies to the Tk option database. *priority* is interpreted as for + :meth:`option_add` and defaults to ``interactive``. + + .. method:: bell(displayof=0) + + Ring the bell on the display for this widget, using the display's current + bell-related settings, and reset the screen saver for the screen. If + *displayof* is given as a widget, the bell is rung on that widget's + display instead. + + .. method:: tk_setPalette(background, /) + tk_setPalette(*args, **kw) + + Set a new color scheme for all Tk widget elements. Existing widgets are + updated and the option database is changed so that future widgets use the + new colors. A single color argument is taken as the normal background + color, from which a complete palette is computed. Alternatively, the + arguments may be given as keyword *name*/*value* pairs naming individual + options in the option database. The recognized option names are + ``activeBackground``, ``activeForeground``, ``background``, + ``disabledForeground``, ``foreground``, ``highlightBackground``, + ``highlightColor``, ``insertBackground``, ``selectColor``, + ``selectBackground``, ``selectForeground``, and ``troughColor``; + reasonable defaults are computed for any that are not specified. + + .. method:: tk_bisque() + + Restore the application's colors to the light brown (bisque) color scheme + used in Tk 3.6 and earlier versions. Provided for backward + compatibility. + + .. method:: tk_strictMotif(boolean=None) + + Query or set whether Tk's look and feel should strictly adhere to Motif. + A true *boolean* value enables strict Motif compliance (for example, no + color change when the mouse passes over a slider). Return the resulting + setting. + .. method:: tk_busy_hold(**kw) + busy(**kw) + busy_hold(**kw) + tk_busy(**kw) + + Make this widget appear busy. A transparent window is placed in front of + the widget, so that it and all of its descendants in the widget hierarchy + are blocked from pointer events and display a busy cursor. Normally + :meth:`update` should be called immediately afterwards to ensure that the + hold operation is in effect before the application starts its processing. + + The only supported configuration option is *cursor*, the cursor to be + displayed while the widget is busy; it may have any of the values accepted + by :meth:`!configure`. + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + + .. method:: tk_busy_configure(cnf=None, **kw) + busy_configure(cnf=None, **kw) + busy_config(cnf=None, **kw) + tk_busy_config(cnf=None, **kw) + + Query or modify the configuration options of the busy window. The widget + must have been previously made busy by :meth:`tk_busy_hold`. With no + arguments, return a dictionary describing all of the available options; if + *cnf* is the name of an option, return a tuple describing that one option. + Otherwise set the given option(s) to the given value(s). Options may have + any of the values accepted by :meth:`tk_busy_hold`. + + The option database is referenced through the widget name or class. For + example, if a :class:`Frame` widget named ``frame`` is to be made busy, + the busy cursor can be specified for it by either of the calls:: + + w.option_add('*frame.busyCursor', 'gumby') + w.option_add('*Frame.BusyCursor', 'gumby') + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + + .. method:: tk_busy_cget(option) + busy_cget(option) + + Return the current value of the busy configuration *option*. The widget + must have been previously made busy by :meth:`tk_busy_hold`, and *option* + may have any of the values accepted by that method. + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + + .. method:: tk_busy_forget() + busy_forget() + + Make this widget no longer busy, releasing the resources (including the + transparent window) allocated when it was made busy. User events will + again be received by the widget. These resources are also released when + the widget is destroyed. + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + + .. method:: tk_busy_status() + busy_status() + + Return ``True`` if the widget is currently busy, ``False`` otherwise. + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + + .. method:: tk_busy_current(pattern=None) + busy_current(pattern=None) + + Return a list of widgets that are currently busy. If *pattern* is given, + only busy widgets whose path names match the pattern are returned. + + These are equivalent spellings of the same method. + + .. versionadded:: 3.13 + + .. method:: winfo_atom(name, displayof=0) + + Return the integer identifier for the atom whose name is *name*, + creating a new atom if none exists. If *displayof* is given, the atom is + looked up on the display of that window; otherwise it is looked up on the + display of the application's main window. + + .. method:: winfo_atomname(id, displayof=0) + + Return the textual name for the atom whose integer identifier is *id*. + This is the inverse of :meth:`winfo_atom`. If *displayof* is given, the + identifier is looked up on the display of that window; otherwise it is + looked up on the display of the application's main window. + + .. method:: winfo_cells() + + Return the number of cells in the colormap for the widget. + + .. method:: winfo_children() + + Return a list containing the widgets that are children of the widget, in + stacking order from lowest to highest. Toplevel windows are returned as + children of their logical parents. + + .. method:: winfo_class() + + Return the class name of the widget. + + .. method:: winfo_colormapfull() + + Return ``True`` if the colormap for the widget is known to be full, + ``False`` otherwise. + + .. method:: winfo_containing(rootX, rootY, displayof=0) + + Return the widget containing the point given by *rootX* and *rootY*, or + ``None`` if no window in this application contains the point. The + coordinates are in screen units in the coordinate system of the root + window. If *displayof* is given, the coordinates refer to the screen + containing that window; otherwise they refer to the screen of the + application's main window. + + .. method:: winfo_depth() + + Return the depth of the widget, that is, the number of bits per pixel. + + .. method:: winfo_exists() + + Return ``1`` if the widget exists, ``0`` otherwise. + + .. method:: winfo_fpixels(number) + + Return a floating-point value giving the number of pixels in the widget + corresponding to the screen distance *number* (e.g. ``"2.0c"`` or + ``"1i"``). The result may be fractional; for a rounded integer value use + :meth:`winfo_pixels`. + + .. method:: winfo_geometry() + + Return the geometry of the widget, in the form ``widthxheight+x+y``. All + dimensions are in pixels. + + .. method:: winfo_height() + + Return the height of the widget in pixels. When a window is first created + its height is 1 pixel; it is eventually changed by a geometry manager. + See also :meth:`winfo_reqheight`. + + .. method:: winfo_id() + + Return a low-level platform-specific identifier for the widget. On Unix + this is the X window identifier, and on Windows it is the window handle. + + .. method:: winfo_interps(displayof=0) + + Return a tuple of the names of all Tcl interpreters currently registered + for a particular display. If *displayof* is given, the return value + refers to the display of that window; otherwise it refers to the display + of the application's main window. + + .. method:: winfo_ismapped() + + Return ``1`` if the widget is currently mapped, ``0`` otherwise. + + .. method:: winfo_manager() + + Return the name of the geometry manager currently responsible for the + widget, or an empty string if it is not managed by any geometry manager. + + .. method:: winfo_name() + + Return the widget's name within its parent, as opposed to its full path + name. + + .. method:: winfo_parent() + + Return the path name of the widget's parent, or an empty string if the + widget is the main window of the application. + + .. method:: winfo_pathname(id, displayof=0) + + Return the path name of the window whose identifier is *id*. If + *displayof* is given, the identifier is looked up on the display of that + window; otherwise it is looked up on the display of the application's main + window. + + .. method:: winfo_pixels(number) + + Return the number of pixels in the widget corresponding to the screen + distance *number* (e.g. ``"2.0c"`` or ``"1i"``). The result is rounded to + the nearest integer; for a fractional result use :meth:`winfo_fpixels`. + + .. method:: winfo_pointerx() + + Return the pointer's *x* coordinate, in pixels, relative to the screen's + root window (or virtual root, if one is in use). Return ``-1`` if the + pointer is not on the same screen as the widget. + + .. method:: winfo_pointerxy() + + Return the pointer's coordinates as an ``(x, y)`` tuple, in pixels, + relative to the screen's root window (or virtual root, if one is in use). + Both coordinates are ``-1`` if the pointer is not on the same screen as + the widget. + + .. method:: winfo_pointery() + + Return the pointer's *y* coordinate, in pixels, relative to the screen's + root window (or virtual root, if one is in use). Return ``-1`` if the + pointer is not on the same screen as the widget. + + .. method:: winfo_reqheight() + + Return the widget's requested height in pixels. This is the value used by + the widget's geometry manager to compute its geometry. + + .. method:: winfo_reqwidth() + + Return the widget's requested width in pixels. This is the value used by + the widget's geometry manager to compute its geometry. + + .. method:: winfo_rgb(color) + + Return an ``(r, g, b)`` tuple of the red, green, and blue intensities, in + the range 0 to 65535, that correspond to *color* in the widget. *color* + may be specified in any of the forms acceptable for a color option. + + .. method:: winfo_rootx() + + Return the *x* coordinate, in the root window of the screen, of the + upper-left corner of the widget's border (or of the widget itself if it + has no border). + + .. method:: winfo_rooty() + + Return the *y* coordinate, in the root window of the screen, of the + upper-left corner of the widget's border (or of the widget itself if it + has no border). + + .. method:: winfo_screen() + + Return the name of the screen associated with the widget, in the form + ``displayName.screenIndex``. + + .. method:: winfo_screencells() + + Return the number of cells in the default colormap for the widget's + screen. + + .. method:: winfo_screendepth() + + Return the depth of the root window of the widget's screen, that is, the + number of bits per pixel. + + .. method:: winfo_screenheight() + + Return the height of the widget's screen in pixels. + + .. method:: winfo_screenmmheight() + + Return the height of the widget's screen in millimeters. + + .. method:: winfo_screenmmwidth() + + Return the width of the widget's screen in millimeters. + + .. method:: winfo_screenvisual() + + Return the default visual class for the widget's screen, one of + ``"directcolor"``, ``"grayscale"``, ``"pseudocolor"``, ``"staticcolor"``, + ``"staticgray"``, or ``"truecolor"``. + + .. method:: winfo_screenwidth() + + Return the width of the widget's screen in pixels. + + .. method:: winfo_server() + + Return a string containing information about the server for the widget's + display. The exact format of this string may vary from platform to + platform. + + .. method:: winfo_toplevel() + + Return the top-of-hierarchy window containing the widget. In standard Tk + this is always a :class:`Toplevel` widget. + + .. method:: winfo_viewable() + + Return ``1`` if the widget and all of its ancestors up through the + nearest toplevel window are mapped, ``0`` otherwise. + + .. method:: winfo_visual() + + Return the visual class for the widget, one of ``"directcolor"``, + ``"grayscale"``, ``"pseudocolor"``, ``"staticcolor"``, ``"staticgray"``, + or ``"truecolor"``. + + .. method:: winfo_visualid() + + Return the X identifier for the visual for the widget. + + .. method:: winfo_visualsavailable(includeids=False) + + Return a list describing the visuals available for the widget's screen. + Each item consists of a visual class (see :meth:`winfo_visual`) followed + by an integer depth. If *includeids* is true, the X identifier for the + visual is also included. + + .. method:: winfo_vrootheight() + + Return the height of the virtual root window associated with the widget if + there is one; otherwise return the height of the widget's screen. + + .. method:: winfo_vrootwidth() + + Return the width of the virtual root window associated with the widget if + there is one; otherwise return the width of the widget's screen. + + .. method:: winfo_vrootx() + + Return the *x* offset of the virtual root window associated with the + widget, relative to the root window of its screen. This is normally zero + or negative, and is ``0`` if there is no virtual root window. + + .. method:: winfo_vrooty() + + Return the *y* offset of the virtual root window associated with the + widget, relative to the root window of its screen. This is normally zero + or negative, and is ``0`` if there is no virtual root window. + + .. method:: winfo_width() + + Return the width of the widget in pixels. When a window is first created + its width is 1 pixel; it is eventually changed by a geometry manager. See + also :meth:`winfo_reqwidth`. + + .. method:: winfo_x() + + Return the *x* coordinate, in the widget's parent, of the upper-left + corner of the widget's border (or of the widget itself if it has no + border). + + .. method:: winfo_y() + + Return the *y* coordinate, in the widget's parent, of the upper-left + corner of the widget's border (or of the widget itself if it has no + border). + + .. method:: info_patchlevel() + + Return the Tcl/Tk patch level as a string, for example ``'9.1.0'``. + + .. versionadded:: 3.11 + + + +.. class:: Wm() + + The :class:`!Wm` mixin provides access to the window manager, allowing an + application to control such things as the title, geometry and icon of a + top-level window, the way it is resized, and how it responds to window + manager protocols. It is mixed into :class:`Tk` and :class:`Toplevel`, so + its methods are available on every top-level window. Each method has two + equivalent spellings: a short name and a ``wm_``-prefixed name (for example, + :meth:`title` and :meth:`!wm_title`). + + .. method:: aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) + wm_aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) + + Constrain the aspect ratio (the ratio of width to height) of the window. + 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. + The ``wm_``-prefixed spelling (e.g. ``wm_aspect``) is an equivalent alias. + + .. method:: attributes(*args, return_python_dict=False, **kwargs) + wm_attributes(*args, return_python_dict=False, **kwargs) + + Query or set platform-specific attributes of the window. With no + arguments, return the platform-specific flags and their values; pass + *return_python_dict* as true to get them as a dictionary. A single + option name such as ``'-alpha'`` returns the value of that option, and + options may be set either positionally (``'-alpha', 0.5``) or as keyword + arguments (``alpha=0.5``). The available attributes differ by platform; + all platforms support ``-alpha`` (transparency from ``0.0`` to ``1.0``), + ``-fullscreen`` and ``-topmost``, while Windows, macOS and X11 each add + further options. On X11 changes are applied asynchronously, so a queried + value may not yet reflect the most recent request. + The ``wm_``-prefixed spelling (e.g. ``wm_attributes``) is an equivalent + alias. + + .. versionchanged:: 3.13 + A single attribute may now be queried by name without the leading + ``-``, attributes may be set using keyword arguments, and the + *return_python_dict* parameter was added. + + + .. method:: client(name=None) + wm_client(name=None) + + Store *name*, which should be the name of the host on which the + application is running, in the window's ``WM_CLIENT_MACHINE`` property for + use by the window or session manager. An empty string deletes the + property. With no argument, return the last name set, or an empty string. + The ``wm_``-prefixed spelling (e.g. ``wm_client``) is an equivalent alias. + + .. method:: colormapwindows(*wlist) + wm_colormapwindows(*wlist) + + Manipulate the ``WM_COLORMAP_WINDOWS`` property, which tells the window + manager about windows that have private colormaps. If *wlist* is given, + overwrite the property with those windows (their order is a priority order + for installing colormaps). With no arguments, return the list of windows + currently named in the property. + The ``wm_``-prefixed spelling (e.g. ``wm_colormapwindows``) is an + equivalent alias. + + .. method:: command(value=None) + wm_command(value=None) + + Store *value* in the window's ``WM_COMMAND`` property for use by the + window or session manager; it should be a list giving the words of the + command used to invoke the application. An empty string deletes the + property. With no argument, return the last value set, or an empty + string. + The ``wm_``-prefixed spelling (e.g. ``wm_command``) is an equivalent + alias. + + .. method:: deiconify() + wm_deiconify() + + Display the window in normal (non-iconified) form by mapping it. If the + window has never been mapped, this ensures it appears de-iconified when it + is first mapped. On Windows the window is also raised and given the + focus. + The ``wm_``-prefixed spelling (e.g. ``wm_deiconify``) is an equivalent + alias. + + .. method:: focusmodel(model=None) + wm_focusmodel(model=None) + + Set or query the focus model for the window. *model* is either + ``'active'`` (the window claims the input focus for itself or its + descendants, even when the focus is in another application) or + ``'passive'`` (the window relies on the window manager to give it the + focus). With no argument, return the current model. The default is + ``'passive'``, which is what the :meth:`!focus` command assumes. + The ``wm_``-prefixed spelling (e.g. ``wm_focusmodel``) is an equivalent + alias. + + .. method:: forget(window) + wm_forget(window) + + Unmap *window* from the screen so that it is no longer managed by the + window manager. A :class:`Toplevel` is then treated like a :class:`Frame`, + although its ``-menu`` configuration is remembered and the menu reappears + if the widget is managed again. + The ``wm_``-prefixed spelling (e.g. ``wm_forget``) is an equivalent alias. + + .. versionadded:: 3.3 + + .. method:: frame() + wm_frame() + + Return the platform-specific window identifier for the outermost + decorative frame containing the window, if the window manager has + reparented it into such a frame; otherwise return the identifier of the + window itself. + The ``wm_``-prefixed spelling (e.g. ``wm_frame``) is an equivalent alias. + + .. method:: geometry(newGeometry=None) + wm_geometry(newGeometry=None) + + Set or query the geometry of the window. *newGeometry* has the form + ``=widthxheight+x+y``, where any of ``=``, ``widthxheight`` and the + ``+x+y`` position may be omitted. *width* and *height* are in pixels (or + grid units for a gridded window); a position preceded by ``+`` is measured + from the left or top edge of the screen and one preceded by ``-`` from the + right or bottom edge. An empty string cancels any user-specified geometry, + letting the window revert to its natural size. With no argument, return + the current geometry as a string of the form ``'200x200+10+10'``. + The ``wm_``-prefixed spelling (e.g. ``wm_geometry``) is an equivalent + alias. + + .. method:: grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) + wm_grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) + + Manage the window as a gridded window and define the relationship between + grid units and pixels. *baseWidth* and *baseHeight* are the numbers of + grid units for the 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. + The ``wm_``-prefixed spelling (e.g. ``wm_grid``) is an equivalent alias. + + .. method:: group(pathName=None) + wm_group(pathName=None) + + Set or query the leader of a group of related windows. *pathName* gives + the path name of the group leader; the window manager may, for example, + unmap all windows in the group when the leader is iconified. An empty + string removes the window from any group. With no argument, return the + path name of the current group leader, or an empty string. + The ``wm_``-prefixed spelling (e.g. ``wm_group``) is an equivalent alias. + + .. method:: iconbitmap(bitmap=None, default=None) + wm_iconbitmap(bitmap=None, default=None) + + Set or query the bitmap used by the window manager for the window's icon. + *bitmap* names a bitmap in one of the standard forms accepted by Tk; an + empty string cancels the current icon bitmap. With no argument, return + the name of the current icon bitmap, or an empty string. On Windows the + *default* argument names an icon (for example an ``.ico`` file) applied to + all top-level windows that have no icon of their own. + The ``wm_``-prefixed spelling (e.g. ``wm_iconbitmap``) is an equivalent + alias. + + .. method:: iconify() + wm_iconify() + + Iconify the window. If the window has not yet been mapped for the first + time, arrange for it to appear in the iconified state when it is + eventually mapped. + The ``wm_``-prefixed spelling (e.g. ``wm_iconify``) is an equivalent alias. + + .. method:: iconmask(bitmap=None) + wm_iconmask(bitmap=None) + + Set or query the bitmap used as a mask for the icon (see + :meth:`iconbitmap`). Where the mask is zero no icon is displayed; where it + is one, the corresponding bits of the icon bitmap are shown. An empty + string cancels the current mask. With no argument, return the name of the + current icon mask, or an empty string. + The ``wm_``-prefixed spelling (e.g. ``wm_iconmask``) is an equivalent + alias. + + .. method:: iconname(newName=None) + wm_iconname(newName=None) + + Set or query the name displayed by the window manager inside the window's + icon. With no argument, return the current icon name, or an empty string + if none has been set (in which case the window manager normally displays + the window's title). + The ``wm_``-prefixed spelling (e.g. ``wm_iconname``) is an equivalent + alias. + + .. method:: iconphoto(default=False, *images) + wm_iconphoto(default=False, *images) + + Set the titlebar icon for the window from one or more + :class:`PhotoImage` objects given in *images*. Several images of different + sizes (for example 16x16 and 32x32) may be supplied so that the window + manager can choose an appropriate one. The image data is taken as a + snapshot at the time of the call; later changes to the images are not + reflected. If *default* is true, the icon is also applied to all + top-level windows created in the future. On macOS only the first image is + used. + The ``wm_``-prefixed spelling (e.g. ``wm_iconphoto``) is an equivalent + alias. + + .. versionadded:: 3.3 + + .. method:: iconposition(x=None, y=None) + wm_iconposition(x=None, y=None) + + 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. + The ``wm_``-prefixed spelling (e.g. ``wm_iconposition``) is an equivalent + alias. + + .. method:: iconwindow(pathName=None) + wm_iconwindow(pathName=None) + + Set or query the window used as the icon for the window. When the window + is iconified, *pathName* is mapped to serve as its icon and unmapped again + when it is de-iconified. An empty string cancels the association. With no + argument, return the path name of the current icon window, or an empty + string. Not all window managers support icon windows, and the concept is + meaningless on non-X11 platforms. + The ``wm_``-prefixed spelling (e.g. ``wm_iconwindow``) is an equivalent + alias. + + .. method:: manage(widget) + wm_manage(widget) + + Make *widget* a stand-alone top-level window, decorated by the window + manager with a title bar and so on. Only :class:`Frame`, + :class:`LabelFrame` and :class:`Toplevel` widgets may be used; passing any + other widget type raises an error. + The ``wm_``-prefixed spelling (e.g. ``wm_manage``) is an equivalent alias. + + .. versionadded:: 3.3 + + .. method:: maxsize(width=None, height=None) + wm_maxsize(width=None, height=None) + + Set or query the maximum permissible dimensions of the window, in pixels + (or grid units for a gridded window). The window manager restricts the + window to be no larger than *width* and *height*. With no arguments, + return a tuple of the current maximum width and height. The maximum size + defaults to the size of the screen. + The ``wm_``-prefixed spelling (e.g. ``wm_maxsize``) is an equivalent alias. + + .. method:: minsize(width=None, height=None) + wm_minsize(width=None, height=None) + + Set or query the minimum permissible dimensions of the window, in pixels + (or grid units for a gridded window). The window manager restricts the + window to be no smaller than *width* and *height*. With no arguments, + return a tuple of the current minimum width and height. The minimum size + defaults to one pixel in each dimension. + The ``wm_``-prefixed spelling (e.g. ``wm_minsize``) is an equivalent alias. + + .. method:: overrideredirect(boolean=None) + wm_overrideredirect(boolean=None) + + Set or query the override-redirect flag for the window. 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. The flag is reliably honored only when + the window is first mapped or remapped from the withdrawn state. + The ``wm_``-prefixed spelling (e.g. ``wm_overrideredirect``) is an + equivalent alias. + + .. method:: positionfrom(who=None) + wm_positionfrom(who=None) + + Set or query the source of the window's current position. *who* is either + ``'program'`` or ``'user'`` and indicates whether the position was + requested by the program or by the user; an empty string cancels the + current source. With no argument, return the current source, or an empty + string if none has been set. Tk automatically sets the source to + ``'user'`` when :meth:`geometry` is called, unless it has been set + explicitly to ``'program'``. + The ``wm_``-prefixed spelling (e.g. ``wm_positionfrom``) is an equivalent + alias. + + .. method:: protocol(name=None, func=None) + wm_protocol(name=None, func=None) + + Register *func* as the handler for the window manager protocol *name*, an + atom such as ``'WM_DELETE_WINDOW'``, ``'WM_SAVE_YOURSELF'`` or + ``'WM_TAKE_FOCUS'``; *func* is then called whenever the window manager + sends a message of that protocol. Tk installs a default + ``WM_DELETE_WINDOW`` handler that destroys the window, which this method + can replace. If *func* is an empty string, the handler is removed. With + only *name*, return the name of its registered handler command, or an empty + string if none is set (the default ``WM_DELETE_WINDOW`` handler is not + reported); with no arguments, return a tuple of the protocols that + currently have handlers. + The ``wm_``-prefixed spelling (e.g. ``wm_protocol``) is an equivalent + alias. + + .. method:: resizable(width=None, height=None) + wm_resizable(width=None, height=None) + + Control whether the user may interactively resize the window. *width* and + *height* are boolean values that determine whether the window's width and + height may be changed. With no arguments, return a tuple of two ``0``/``1`` + values indicating whether each dimension is currently resizable. By + default a window is resizable in both dimensions. + The ``wm_``-prefixed spelling (e.g. ``wm_resizable``) is an equivalent + alias. + + .. method:: sizefrom(who=None) + wm_sizefrom(who=None) + + Set or query the source of the window's current size. *who* is either + ``'program'`` or ``'user'`` and indicates whether the size was requested by + the program or by the user; an empty string cancels the current source. + With no argument, return the current source, or an empty string if none has + been set. + The ``wm_``-prefixed spelling (e.g. ``wm_sizefrom``) is an equivalent + alias. + + .. method:: state(newstate=None) + wm_state(newstate=None) + + Set or query the state of the window. With no argument, return the current + state: one of ``'normal'``, ``'iconic'``, ``'withdrawn'``, ``'icon'`` or, + on Windows and macOS only, ``'zoomed'``. ``'iconic'`` refers to a window + that has been iconified, while ``'icon'`` refers to a window serving as the + icon for another window (see :meth:`iconwindow`); the ``'icon'`` state + cannot be set. + The ``wm_``-prefixed spelling (e.g. ``wm_state``) is an equivalent alias. + + .. method:: title(string=None) + wm_title(string=None) + + Set or query the title for the window, which the window manager should + display in the window's title bar. With no argument, return the current + title. The title defaults to the window's name. + The ``wm_``-prefixed spelling (e.g. ``wm_title``) is an equivalent alias. + + .. method:: transient(master=None) + wm_transient(master=None) + + Mark the window as a transient window (such as a pull-down menu or dialog) + working on behalf of *master*, the path name of another top-level window. + An empty string clears the transient status. With no argument, return the + path name of the current master, or an empty string. A transient window + mirrors state changes in its master and may be decorated differently by the + window manager; it is an error to make a window a transient of itself. + The ``wm_``-prefixed spelling (e.g. ``wm_transient``) is an equivalent + alias. + + .. method:: withdraw() + wm_withdraw() + + Withdraw the window from the screen, unmapping it and causing the window + manager to forget about it. If the window has never been mapped, it is + instead mapped in the withdrawn state. It is sometimes necessary to + withdraw a window and then re-map it (for example with :meth:`deiconify`) + to make some window managers notice changes to window attributes. + The ``wm_``-prefixed spelling (e.g. ``wm_withdraw``) is an equivalent + alias. + + +.. class:: Pack() + + Geometry manager that arranges widgets by packing them against the sides of + their container. The :class:`!Pack` mix-in is inherited by all widgets + (through :class:`Widget`) and provides the methods for managing a widget with + the *pack* geometry manager. See also :ref:`pack-the-packer`. + + .. method:: pack_configure(cnf={}, **kw) + pack(cnf={}, **kw) + configure(cnf={}, **kw) + config(cnf={}, **kw) + + Pack the widget inside its container, positioning it relative to the + siblings already packed there. Options such as *side* + (``'top'``, ``'bottom'``, ``'left'`` or ``'right'``), *fill* + (``'x'``, ``'y'``, ``'both'`` or ``'none'``), *expand*, *anchor*, + *padx*/*pady*, *ipadx*/*ipady* and *in_* control the placement; see the Tk + ``pack`` manual page for the full list. :meth:`!pack`, :meth:`!configure` + and :meth:`!config` are aliases of :meth:`!pack_configure`. + + .. method:: pack_forget() + forget() + + Unmap the widget and remove it from the packing order, forgetting its + packing options. It can be packed again later with + :meth:`pack_configure`. :meth:`!forget` is an alias of + :meth:`!pack_forget`. + + .. method:: pack_info() + info() + + Return a dictionary of the widget's current packing options. + :meth:`!info` is an alias of :meth:`!pack_info`. + + .. method:: pack_propagate(flag=['_noarg_']) + propagate(flag=['_noarg_']) + + Same as :meth:`Misc.pack_propagate`, treating this widget as a container: + enable or disable geometry propagation. :meth:`!propagate` is an alias of + :meth:`!pack_propagate`. + + .. method:: pack_slaves() + slaves() + + Same as :meth:`Misc.pack_slaves`: return the list of widgets packed in + this widget. :meth:`!slaves` is an alias of :meth:`!pack_slaves`. + + .. method:: pack_content() + content() + + Same as :meth:`Misc.pack_content`. :meth:`!content` is an alias of + :meth:`!pack_content`. + + +.. class:: Place() + + Geometry manager that places widgets at explicit positions and sizes within + their container. The :class:`!Place` mix-in is inherited by all widgets + (through :class:`Widget`). + + .. method:: place_configure(cnf={}, **kw) + place(cnf={}, **kw) + configure(cnf={}, **kw) + config(cnf={}, **kw) + + Place the widget inside its container at an absolute or relative position. + Options include *x*/*y* and *relx*/*rely* (absolute and fractional + position), *width*/*height* and *relwidth*/*relheight* (absolute and + fractional size), *anchor*, *bordermode* and *in_*; see the Tk ``place`` + manual page. :meth:`!place`, :meth:`!configure` and :meth:`!config` are + aliases of :meth:`!place_configure`. + + .. method:: place_forget() + forget() + + Unmap the widget and remove it from the placement, forgetting its place + options. :meth:`!forget` is an alias of :meth:`!place_forget`. + + .. method:: place_info() + info() + + Return a dictionary of the widget's current place options. + :meth:`!info` is an alias of :meth:`!place_info`. + + .. method:: place_slaves() + slaves() + + Same as :meth:`Misc.place_slaves`: return the list of widgets placed in + this widget. :meth:`!slaves` is an alias of :meth:`!place_slaves`. + + .. method:: place_content() + content() + + Same as :meth:`Misc.place_content`. :meth:`!content` is an alias of + :meth:`!place_content`. + + +.. class:: Grid() + + Geometry manager that arranges widgets in a two-dimensional grid of rows and + columns within their container. The :class:`!Grid` mix-in is inherited by + all widgets (through :class:`Widget`). + + .. method:: grid_configure(cnf={}, **kw) + grid(cnf={}, **kw) + configure(cnf={}, **kw) + config(cnf={}, **kw) + + Position the widget in a cell of its container's grid. Options include + *row*/*column*, *rowspan*/*columnspan*, *sticky*, *padx*/*pady*, + *ipadx*/*ipady* and *in_*; see the Tk ``grid`` manual page. :meth:`!grid`, + :meth:`!configure` and :meth:`!config` are aliases of + :meth:`!grid_configure`. + + .. method:: grid_forget() + forget() + + Unmap the widget and remove it from the grid, forgetting its grid options. + :meth:`!forget` is an alias of :meth:`!grid_forget`. + + .. method:: grid_remove() + + Unmap the widget and remove it from the grid, but remember its grid + options so that it is restored to the same cell if it is gridded again. + + .. method:: grid_info() + info() + + Return a dictionary of the widget's current grid options. + :meth:`!info` is an alias of :meth:`!grid_info`. + + .. method:: grid_anchor(anchor=None) + anchor(anchor=None) + + Same as :meth:`Misc.grid_anchor`. :meth:`!anchor` is an alias of + :meth:`!grid_anchor`. + + .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) + bbox(column=None, row=None, col2=None, row2=None) + + Same as :meth:`Misc.grid_bbox`. :meth:`!bbox` is an alias of + :meth:`!grid_bbox`. + + .. method:: grid_columnconfigure(index, cnf={}, **kw) + columnconfigure(index, cnf={}, **kw) + + Same as :meth:`Misc.grid_columnconfigure`: query or set the options + (such as *weight*, *minsize*, *pad* and *uniform*) of a grid column. + :meth:`!columnconfigure` is an alias of :meth:`!grid_columnconfigure`. + + .. method:: grid_rowconfigure(index, cnf={}, **kw) + rowconfigure(index, cnf={}, **kw) + + Same as :meth:`Misc.grid_rowconfigure`: query or set the options of a grid + row. :meth:`!rowconfigure` is an alias of :meth:`!grid_rowconfigure`. + + .. method:: grid_location(x, y) + location(x, y) + + Same as :meth:`Misc.grid_location`: return the ``(column, row)`` of the + cell that covers the pixel at *x*, *y*. :meth:`!location` is an alias of + :meth:`!grid_location`. + + .. method:: grid_size() + size() + + Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving + the size of the grid. :meth:`!size` is an alias of :meth:`!grid_size`. + + .. method:: grid_propagate(flag=['_noarg_']) + propagate(flag=['_noarg_']) + + Same as :meth:`Misc.grid_propagate`. :meth:`!propagate` is an alias of + :meth:`!grid_propagate`. + + .. method:: grid_slaves(row=None, column=None) + slaves(row=None, column=None) + + Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid, + optionally restricted to a *row* and/or *column*. :meth:`!slaves` is an + alias of :meth:`!grid_slaves`. + + .. method:: grid_content(row=None, column=None) + content(row=None, column=None) + + Same as :meth:`Misc.grid_content`. :meth:`!content` is an alias of + :meth:`!grid_content`. + + +.. class:: XView() + + Mix-in providing the horizontal-scrolling interface shared by widgets such as + :class:`Entry`, :class:`Canvas`, :class:`Listbox`, :class:`Text` and + :class:`Spinbox`. A widget's :meth:`xview` method is registered as the + *command* of a horizontal :class:`Scrollbar`. + + .. method:: xview(*args) + + Query or change the horizontal position of the view. With no arguments, + return a tuple ``(first, last)`` of two fractions between 0 and 1 giving + the portion of the document that is currently visible. Otherwise the + arguments are passed to the Tk ``xview`` widget command and are usually + generated by a scrollbar; :meth:`xview_moveto` and :meth:`xview_scroll` + provide a more convenient interface. + + .. method:: xview_moveto(fraction) + + Adjust the view so that *fraction* of the total width of the document is + off-screen to the left. *fraction* is a number between 0 and 1. + + .. method:: xview_scroll(number, what) + + Shift the view left or right by *number* units. *what* is either + ``'units'`` or ``'pages'``; a negative *number* scrolls left and a + positive one scrolls right. + + +.. class:: YView() + + Mix-in providing the vertical-scrolling interface shared by widgets such as + :class:`Canvas`, :class:`Listbox` and :class:`Text`. A widget's :meth:`yview` + method is registered as the *command* of a vertical :class:`Scrollbar`. + + .. method:: yview(*args) + + Query or change the vertical position of the view. With no arguments, + return a tuple ``(first, last)`` of two fractions between 0 and 1 giving + the portion of the document that is currently visible. Otherwise the + arguments are passed to the Tk ``yview`` widget command, usually generated + by a scrollbar; :meth:`yview_moveto` and :meth:`yview_scroll` provide a + more convenient interface. + + .. method:: yview_moveto(fraction) + + Adjust the view so that *fraction* of the total height of the document is + off-screen above the top. *fraction* is a number between 0 and 1. + + .. method:: yview_scroll(number, what) + + Shift the view up or down by *number* units. *what* is either ``'units'`` + or ``'pages'``; a negative *number* scrolls up and a positive one scrolls + down. + + +.. class:: BaseWidget(master, widgetName, cnf={}, kw={}, extra=()) + + Internal base class for all widgets. It inherits from :class:`Misc` and + adds the machinery that creates the underlying Tk widget; application code + normally uses :class:`Widget` or a concrete widget class rather than + instantiating :class:`!BaseWidget` directly. + + .. method:: destroy() + + Destroy this widget and all of its children, removing the corresponding + Tk widgets and deleting the associated Tcl commands. + + +.. class:: Widget(master, widgetName, cnf={}, kw={}, extra=()) + + Internal base class for the standard widgets. It combines :class:`BaseWidget` + with the geometry-manager mix-ins :class:`Pack`, :class:`Place` and + :class:`Grid`, so that every widget can be managed by any of the three + geometry managers. The concrete widget classes (:class:`Button`, + :class:`Label`, and so on) derive from :class:`!Widget`. + + +.. class:: Toplevel(master=None, cnf={}, **kw) + + A :class:`!Toplevel` widget is a top-level window, similar to a + :class:`Frame` except that its X parent is the root window of a screen + rather than its logical parent. Its primary purpose is to serve as a + container for dialog boxes and other collections of widgets; its only + visible features are its background and an optional 3-D border. Notable + options include *menu*, which installs a :class:`Menu` as the window's + menubar. Inherits from :class:`BaseWidget` and :class:`Wm`, so a toplevel + is managed by the window manager. Refer to the Tk ``toplevel`` manual page + for the full list of options. + + +Widget classes +^^^^^^^^^^^^^^ + +.. class:: Button(master=None, cnf={}, **kw) + + A :class:`!Button` widget displays a textual string, bitmap or image and + invokes a command when the user presses it (by clicking mouse button 1 over + the button or, when the button has focus, by pressing the space key). + Inherits from :class:`Widget`. In addition to the standard widget options, + a button accepts the options documented in the Tk ``button`` manual page, + such as *command* (the callback invoked when the button is pressed), + *textvariable*, *state* and *default*. + + .. method:: invoke() + + Invoke the command associated with the button, if there is one, and + return its result, or an empty string if no command is associated with + the button. This is ignored if the button's state is ``disabled``. + + .. method:: flash() + + Flash the button by redisplaying it several times, alternating between + the active and normal colors. At the end of the flash the button is left + in the same normal or active state as when the method was called. This + is ignored if the button's state is ``disabled``. + + +.. class:: Canvas(master=None, cnf={}, **kw) + + A :class:`!Canvas` widget implements structured graphics. It displays any + number of *items*, such as arcs, lines, ovals, polygons, rectangles, text, + bitmaps, images and embedded windows, which may be drawn, moved, re-colored + and bound to events. Inherits from :class:`Widget`, :class:`XView` and + :class:`YView`, so the view can be scrolled horizontally and vertically with + :meth:`~XView.xview` and :meth:`~YView.yview`. Refer to the Tk ``canvas`` + manual page for the full list of widget and item options. + + Each item has a unique integer *id*, assigned when it is created, and zero or + more string *tags*. A tag is an arbitrary string that does not have the form + of an integer; the same tag may be shared by many items, which makes tags + convenient for grouping items. The special tag ``'all'`` matches every item + in the canvas, and ``'current'`` matches the topmost item under the mouse + pointer. Most methods take a *tagOrId* argument that may be an integer id + naming a single item, or a tag naming zero or more items; as described in the + Tk ``canvas`` manual page, a tag may also be a logical expression of tags + combined with the operators ``&&``, ``||``, ``^``, ``!`` and parentheses. + When a method that operates on a single item is given a *tagOrId* matching + several items, it normally uses the lowest matching item in the display list. + + The items are kept in a *display list* that determines drawing order: items + later in the list are drawn on top of earlier ones. A newly created item is + placed at the top of the list; the order can be changed with :meth:`tag_raise` + and :meth:`tag_lower`. + + .. method:: create_arc(*args, **kw) + create_bitmap(*args, **kw) + create_image(*args, **kw) + create_line(*args, **kw) + create_oval(*args, **kw) + create_polygon(*args, **kw) + create_rectangle(*args, **kw) + create_text(*args, **kw) + create_window(*args, **kw) + + Create a new item of the corresponding type and return its integer id. + Each method is called as ``create_TYPE(coord..., **options)``: the leading + positional arguments give the coordinates that define the item (as + separate numbers, as a single sequence of numbers, or as coordinate + pairs), and the keyword arguments set item-specific options. Coordinates + and screen distances may be given as numbers (interpreted as pixels) or as + strings with a unit suffix (``'m'``, ``'c'``, ``'i'`` or ``'p'`` for + millimetres, centimetres, inches or printer's points), but are always + stored and returned in pixels. + + The item types are: ``arc`` (an arc-shaped region that is a section of an + oval, defined by two diagonally opposite corners ``x1, y1, x2, y2`` of the + enclosing rectangle); ``bitmap`` (a two-color bitmap positioned at a point + ``x, y``); ``image`` (a Tk image positioned at a point ``x, y``); ``line`` + (a line or curve through the points ``x1, y1, ..., xn, yn``); ``oval`` (a + circle or ellipse inscribed in the rectangle ``x1, y1, x2, y2``); + ``polygon`` (a closed polygon through the points ``x1, y1, ..., xn, yn``); + ``rectangle`` (a rectangle with corners ``x1, y1, x2, y2``); ``text`` (a + string of text positioned at a point ``x, y``); and ``window`` (a child + widget embedded in the canvas at a point ``x, y``, specified with the + *window* option). + + .. method:: coords(tagOrId) + coords(tagOrId, coordList, /) + coords(tagOrId, /, *coordList) + + Query or modify the coordinates of an item. With only *tagOrId*, return a + list of the floating-point coordinates of the item given by *tagOrId* (the + first matching item if it matches several). Given new coordinates, + replace the coordinates of that item with them; like the ``create_*`` + methods, the coordinates may be given as separate numbers, as a single + sequence, or as coordinate pairs. + The returned coordinates are always in pixels, regardless + of the units used to specify them; for rectangles, ovals and arcs they are + ordered left, top, right, bottom. + + .. versionchanged:: 3.12 + The arguments are now flattened: the coordinates may be given as + separate arguments, as a single sequence, or grouped in pairs, like + the ``create_*`` methods. + + + .. method:: move(tagOrId, xAmount, yAmount, /) + + Move each of the items given by *tagOrId* in the canvas coordinate space by + adding *xAmount* to every x-coordinate and *yAmount* to every y-coordinate + of the item. + + .. method:: moveto(tagOrId, x='', y='') + + Move the items given by *tagOrId* so that the first coordinate pair (the + upper-left corner of the bounding box) of the lowest matching item is at + position (*x*, *y*). *x* or *y* may be an empty string, in which case the + corresponding coordinate is unchanged. All matching items keep their + positions relative to each other. + + .. versionadded:: 3.8 + + + .. method:: scale(tagOrId, xOrigin, yOrigin, xScale, yScale, /) + + Rescale the coordinates of all items given by *tagOrId* in canvas + coordinate space. + Each x-coordinate is adjusted so that its distance from *xOrigin* changes + by a factor of *xScale*, and each y-coordinate so that its distance from + *yOrigin* changes by a factor of *yScale* (a factor of ``1.0`` leaves the + coordinate unchanged). + + .. method:: delete(*tagOrIds) + + Delete each of the items given by the *tagOrIds* arguments. + + .. method:: dchars(tagOrId, first, /) + dchars(tagOrId, first, last, /) + + Delete from each of the items given by *tagOrId* the characters (for text + items) or coordinates (for line and polygon items) in the range from + *first* to *last* inclusive; *last* defaults to *first*. Items that do not + support indexing ignore this operation. + + .. method:: insert(tagOrId, beforeThis, string, /) + + Insert *string* into each of the items given by *tagOrId* just before the + character or coordinate whose index is *beforeThis*. For line and polygon + items *string* must be a valid sequence of coordinates. + + .. method:: itemcget(tagOrId, option) + + Return the current value of the configuration option *option* for the item + given by *tagOrId* (the lowest matching item if it matches several). This + is like :meth:`~Widget.cget` but applies to an individual item. + + .. method:: itemconfigure(tagOrId, cnf=None, **kw) + itemconfig(tagOrId, cnf=None, **kw) + + Query or modify the configuration options of the items given by *tagOrId*. + This mirrors :meth:`~Widget.configure`, except that it applies to + individual items rather than to the canvas as a whole. With no options, it + returns a dictionary describing the current options of the first matching + item; otherwise it sets the given options on every matching item. The + legal options are those accepted by the corresponding ``create_*`` method. + :meth:`!itemconfig` is an alias of :meth:`!itemconfigure`. + + .. method:: type(tagOrId) + + Return the type of the item given by *tagOrId* (the first matching item if + it matches several), such as ``'rectangle'`` or ``'text'``, or ``None`` if + *tagOrId* does not match any item. + + .. method:: gettags(tagOrId, /) + + Return a tuple of the tags associated with the item given by *tagOrId* + (the first matching item in display-list order if it matches several). + Return an empty tuple if no item matches or the item has no tags. + + .. method:: dtag(tagOrId, /) + dtag(tagOrId, tagToDelete, /) + + Remove the tag *tagToDelete* (which defaults to *tagOrId*) from each of the + items given by *tagOrId*. Items that do not have that tag are unaffected. + + .. method:: addtag(newtag, searchSpec, /, *args) + + Add the tag *newtag* to each item selected by the search specification + *searchSpec* (and any further *args*). *searchSpec* is one of ``'above'``, + ``'all'``, ``'below'``, ``'closest'``, ``'enclosed'``, ``'overlapping'`` or + ``'withtag'``; the ``addtag_*`` methods below are convenient wrappers that + supply each of these forms. + + .. method:: addtag_above(newtag, tagOrId) + + Add the tag *newtag* to the item just above (after) *tagOrId* in the + display list. + + .. method:: addtag_all(newtag) + + Add the tag *newtag* to all items in the canvas. + + .. method:: addtag_below(newtag, tagOrId) + + Add the tag *newtag* to the item just below (before) *tagOrId* in the + display list. + + .. method:: addtag_closest(newtag, x, y, halo=None, start=None) + + Add the tag *newtag* to the item closest to the point (*x*, *y*). If + *halo* is given, any item within that distance of the point is treated as + overlapping it. If *start* is given (a tag or id), select the topmost + closest item that lies below *start* in the display list, which can be used + to step through all the closest items. + + .. method:: addtag_enclosed(newtag, x1, y1, x2, y2) + + Add the tag *newtag* to every item completely enclosed within the + rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= *y2*. + + .. method:: addtag_overlapping(newtag, x1, y1, x2, y2) + + Add the tag *newtag* to every item that overlaps or is enclosed within the + rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= *y2*. + + .. method:: addtag_withtag(newtag, tagOrId) + + Add the tag *newtag* to every item given by *tagOrId*. + + .. method:: find(searchSpec, /, *args) + + Return a tuple of the ids of all items selected by the search + specification *searchSpec* (and any further *args*), in stacking order + with the lowest item first. The search specification has any of the forms + accepted by :meth:`addtag`. The ``find_*`` methods below are more + convenient wrappers around it. + + .. method:: find_above(tagOrId) + + Return a tuple containing the id of the item just above *tagOrId* in the + display list. + + .. method:: find_all() + + Return a tuple of the ids of all items in the canvas, in stacking order. + + .. method:: find_below(tagOrId) + + Return a tuple containing the id of the item just below *tagOrId* in the + display list. + + .. method:: find_closest(x, y, halo=None, start=None) + + Return a tuple containing the id of the item closest to the point + (*x*, *y*). *halo* and *start* are interpreted as for + :meth:`addtag_closest`. + + .. method:: find_enclosed(x1, y1, x2, y2) + + Return a tuple of the ids of all items completely enclosed within the + rectangle (*x1*, *y1*, *x2*, *y2*). + + .. method:: find_overlapping(x1, y1, x2, y2) + + Return a tuple of the ids of all items that overlap or are enclosed within + the rectangle (*x1*, *y1*, *x2*, *y2*). + + .. method:: find_withtag(tagOrId) + + Return a tuple of the ids of all items given by *tagOrId*. + + .. method:: tag_raise(tagOrId, aboveThis=None, /) + lift(tagOrId, aboveThis=None, /) + tkraise(tagOrId, aboveThis=None, /) + + Move all items given by *tagOrId* to a new position in the display list + just above the item given by *aboveThis*, or to the top of the display + list if *aboveThis* is omitted. When several items are moved their + relative order is preserved. + This has no effect on embedded window items, whose stacking order is + controlled by :meth:`Misc.tkraise` and :meth:`Misc.lower` instead. + :meth:`!lift` and :meth:`!tkraise` are aliases of :meth:`!tag_raise`. + + .. method:: tag_lower(tagOrId, belowThis=None, /) + lower(tagOrId, belowThis=None, /) + + Move all items given by *tagOrId* to a new position in the display list + just below the item given by *belowThis*, or to the bottom of the display + list if *belowThis* is omitted. When several items are moved their + relative order is preserved. + This has no effect on embedded window items. :meth:`!lower` is an alias of + :meth:`!tag_lower`. + + .. method:: tag_bind(tagOrId, sequence=None, func=None, add=None) + + Bind the callback *func* to the event *sequence* for all items given by + *tagOrId*, so that *func* is invoked whenever that event occurs for one of + the items. This is like :meth:`Widget.bind` but operates on canvas items + rather than on whole widgets; only mouse, keyboard and virtual events may + be bound. Mouse events are directed to the current item and keyboard + events to the focus item (see :meth:`focus`). If *add* is true the new + binding is added to any existing bindings for the same sequence, rather + than replacing them. Return the identifier of the bound function, which + can be passed to :meth:`tag_unbind`. + + .. method:: tag_unbind(tagOrId, sequence, funcid=None) + + Remove for all items given by *tagOrId* the binding for the event + *sequence*. If *funcid* is given, only that callback (as returned by + :meth:`tag_bind`) is unbound and deregistered. + + .. versionchanged:: 3.13 + If *funcid* is given, only that callback is unbound. + + + .. method:: bbox(tagOrId, /, *tagOrIds) + + Return a 4-tuple ``(x1, y1, x2, y2)`` giving an approximate bounding box, + in pixels, that encloses all the items given by *tagOrId* and any further + *tagOrIds*. The result may overestimate the true + bounding box by a few pixels. Return ``None`` if no item matches or the + matching items have nothing to display. + + .. method:: canvasx(screenx, gridspacing=None) + + Given a window x-coordinate *screenx*, return the canvas x-coordinate + displayed at that location. If *gridspacing* is given, the result is + rounded to the nearest multiple of *gridspacing* units. + + .. method:: canvasy(screeny, gridspacing=None) + + Given a window y-coordinate *screeny*, return the canvas y-coordinate + displayed at that location. If *gridspacing* is given, the result is + rounded to the nearest multiple of *gridspacing* units. + + .. method:: focus() + focus(tagOrId, /) + + With *tagOrId*, set the keyboard focus for the canvas to the first item + given by *tagOrId* that supports the insertion cursor; the focus is left + unchanged if no such item exists. If *tagOrId* is an empty string, reset + the focus so that no item has it. With no argument, return the id of the + item that currently has the focus, or an empty string if none does. An + item only displays the insertion cursor when both it is the focus item and + its canvas has the input focus. + + .. method:: icursor(tagOrId, index, /) + + Set the insertion cursor of the items given by *tagOrId* to just before + the character given by *index*. + Items that do not support an insertion cursor are unaffected. The cursor + is only displayed when the item has the focus, but its position may be set + at any time. + + .. method:: index(tagOrId, index, /) + + Return as an integer the numerical index within *tagOrId* corresponding to + *index*, which is a textual + description of a position (for text items an index into the characters, for + line and polygon items an index into the coordinates). If *tagOrId* + matches several items, the first one that supports indexing is used. + + .. method:: select_adjust(tagOrId, index) + + Adjust the end of the selection in *tagOrId* nearest to *index* so that it + is at *index*, and make the other end the anchor point for future + :meth:`select_to` calls. If the selection is not currently in *tagOrId*, + this behaves like :meth:`select_to`. + + .. method:: select_clear() + + Clear the selection if it is in this canvas; otherwise do nothing. + + .. method:: select_from(tagOrId, index) + + Set the selection anchor point to just before the character given by + *index* in the item given by *tagOrId*. This does not change the + selection itself; it sets the fixed end for future :meth:`select_to` calls. + + .. method:: select_item() + + Return the id of the item that holds the selection, or ``None`` if the + selection is not in this canvas. Unlike :meth:`find` and the ``find_*`` + methods, this returns the id as a string rather than an integer. + + .. method:: select_to(tagOrId, index) + + Set the selection to the characters of *tagOrId* between the selection + anchor point and *index*, inclusive of *index*. The anchor point is the + one set by the most recent :meth:`select_adjust` or :meth:`select_from` + call. + + .. method:: scan_mark(x, y) + + Record *x*, *y* and the current view, for use with later + :meth:`scan_dragto` calls. This is typically bound to a mouse button press + in the widget. + + .. method:: scan_dragto(x, y, gain=10) + + Scroll the canvas by *gain* times the difference between *x*, *y* and the + coordinates passed to the last :meth:`scan_mark` call. This is typically + bound to mouse motion events in the widget, producing the effect of + dragging the canvas at high speed through its window. + + .. method:: postscript(cnf={}, **kw) + + Generate a PostScript (Encapsulated PostScript, version 3.0) representation + of part or all of the canvas. If the *file* or *channel* option is given, + the PostScript is written there and an empty string is returned; otherwise + it is returned as a string. By default only the area currently visible in + the window is generated, so it is usually necessary either to call + :meth:`~Misc.update` first or to use the *width* and *height* options. + Supported options include *colormap*, *colormode*, *file*, *fontmap*, + *height*, *pageanchor*, *pageheight*, *pagewidth*, *pagex*, *pagey*, + *rotate*, *width*, *x* and *y*. + + +.. class:: Checkbutton(master=None, cnf={}, **kw) + + A :class:`!Checkbutton` widget displays a textual string, bitmap or image + together with a square indicator, and toggles a boolean selection when + pressed. It has all the behavior of a simple button and, in addition, can + be selected: when selected the indicator is drawn with a check mark and the + associated variable is set to the ``onvalue``, and when deselected the + indicator is drawn empty and the variable is set to the ``offvalue``. + Inherits from :class:`Widget`. In addition to the standard widget options, + a checkbutton accepts the options documented in the Tk ``checkbutton`` + manual page, such as *variable*, *onvalue*, *offvalue* and *command*. + + .. method:: invoke() + + Do just what would happen if the user pressed the checkbutton with the + mouse: toggle the selection state of the button and invoke the associated + command, if there is one. Return the result of the command, or an empty + string if no command is associated with the checkbutton. This is ignored + if the checkbutton's state is ``disabled``. + + .. method:: select() + + Select the checkbutton and set the associated variable to its + ``onvalue``. + + .. method:: deselect() + + Deselect the checkbutton and set the associated variable to its + ``offvalue``. + + .. method:: toggle() + + Toggle the selection state of the button, redisplaying it and modifying + its associated variable to reflect the new state. + + .. method:: flash() + + Flash the checkbutton by redisplaying it several times, alternating + between the active and normal colors. At the end of the flash the + checkbutton is left in the same normal or active state as when the method + was called. This is ignored if the checkbutton's state is ``disabled``. + + +.. class:: Entry(master=None, cnf={}, **kw) + + An :class:`!Entry` widget displays a single line of text and lets the user + edit it. Inherits from :class:`Widget` and :class:`XView`; since entries + can hold strings too long to fit in the window, they support horizontal + scrolling through :meth:`~XView.xview`. + + In addition to the standard widget options, an entry accepts the options + documented in the Tk ``entry`` manual page. Notable ones are *textvariable* + (the name of a variable kept in sync with the entry's contents), *show* (if + set, each character is displayed as the given character rather than its true + value, useful for password entry), *validate* and *validatecommand* (which + together let a callback accept or reject edits), and *state* (one of + ``'normal'``, ``'disabled'`` or ``'readonly'``). + + Many of the methods below take an *index* argument that selects a character + in the entry's string. As described in the Tk ``entry`` manual page, + *index* may be a number (counting from 0), ``'insert'`` (the character just + after the insertion cursor), ``'end'`` (just after the last character), + ``'anchor'`` (the selection anchor point), ``'sel.first'`` and ``'sel.last'`` + (the ends of the selection), or ``@x`` (the character covering pixel + x-coordinate *x* in the window). Out-of-range indices are rounded to the + nearest legal value. + + .. method:: delete(first, last=None) + + Delete the characters from index *first* up to but not including index + *last*. If *last* is omitted, only the single character at *first* is + deleted. + + .. method:: get() + + Return the entry's current string. + + .. method:: insert(index, string) + + Insert *string* just before the character given by *index*. + + .. method:: icursor(index) + + Arrange for the insertion cursor to be displayed just before the + character given by *index*. + + .. method:: index(index) + + Return the numerical index corresponding to *index*. + + .. method:: selection_adjust(index) + select_adjust(index) + + Locate the end of the selection nearest to the character given by + *index*, and adjust that end to be at *index* (including but not going + beyond it); the other end becomes the anchor point for future + :meth:`selection_to` calls. If there is no selection in the entry, a new + one is created between *index* and the most recent anchor point, + inclusive. ``select_adjust`` is an alias of :meth:`!selection_adjust`. + + .. method:: selection_clear() + select_clear() + + Clear the selection if it is currently in this widget. If the selection + is not in this widget the method has no effect. ``select_clear`` is an + alias of :meth:`!selection_clear`. + + .. method:: selection_from(index) + select_from(index) + + Set the selection anchor point to just before the character given by + *index*, without changing the selection. ``select_from`` is an alias of + :meth:`!selection_from`. + + .. method:: selection_present() + select_present() + + Return ``True`` if there are characters selected in the entry, ``False`` + otherwise. ``select_present`` is an alias of :meth:`!selection_present`. + + .. method:: selection_range(start, end) + select_range(start, end) + + Set the selection to include the characters starting with the one indexed + by *start* and ending with the one just before *end*. If *end* refers to + the same character as *start* or an earlier one, the selection is cleared. + ``select_range`` is an alias of :meth:`!selection_range`. + + .. method:: selection_to(index) + select_to(index) + + Set the selection between the anchor point and *index*: if *index* is + before the anchor point, the selection runs from *index* up to but not + including the anchor; if *index* is after it, from the anchor up to but + not including *index*; if they coincide, nothing happens. The anchor + point is the one set by the most recent :meth:`selection_from` or + :meth:`selection_adjust` call. If there is no selection in the entry, a + new one is created using the most recent anchor point. ``select_to`` is + an alias of :meth:`!selection_to`. + + .. method:: scan_mark(x) + + Record *x* and the current view in the entry window, for use with later + :meth:`scan_dragto` calls. Typically associated with a mouse button + press in the widget. + + .. method:: scan_dragto(x) + + Compute the difference between *x* and the *x* given to the last + :meth:`scan_mark` call, and adjust the view left or right by 10 times that + difference. Typically associated with mouse motion events, to produce the + effect of dragging the entry at high speed through the window. + + +.. class:: Frame(master=None, cnf={}, **kw) + + A :class:`!Frame` widget is a simple container. Its primary purpose is to + act as a spacer or container for complex window layouts; its only features + are its background and an optional 3-D border to make the frame appear + raised or sunken. Inherits from :class:`Widget`. Refer to the Tk + ``frame`` manual page for the full list of options. + + +.. class:: Label(master=None, cnf={}, **kw) + + A :class:`!Label` widget displays a non-interactive textual string, bitmap + or image. The displayed text is set with the *text* option or linked to a + variable through *textvariable*, and an image can be shown using the + *image* option. Text must all be in a single font but may occupy multiple + lines, and one character may be underlined with the *underline* option. + Inherits from :class:`Widget`. Refer to the Tk ``label`` manual page for + the full list of options. + + +.. class:: LabelFrame(master=None, cnf={}, **kw) + + A :class:`!LabelFrame` widget is a container that has the features of a + :class:`Frame` plus the ability to display a label. The label text is set + with the *text* option and positioned with *labelanchor*, or an arbitrary + widget may be used as the label by giving it as the *labelwidget* option. + Inherits from :class:`Widget`. Refer to the Tk ``labelframe`` manual page + for the full list of options. + + +.. class:: Listbox(master=None, cnf={}, **kw) + + A :class:`!Listbox` widget displays a list of single-line text items, one + per line, of which the user can select one or more. The way the selection + behaves is governed by the *selectmode* option, which is one of ``browse`` + (the default; at most one item, which may be dragged with the mouse), + ``single`` (at most one item), ``multiple`` (any number of items, toggled + individually), or ``extended`` (any number of items, including + discontiguous ranges, selected by clicking and dragging). Inherits from + :class:`Widget`, :class:`XView` and :class:`YView`, so the view can be + scrolled horizontally and vertically with :meth:`~XView.xview` and + :meth:`~YView.yview`. Refer to the Tk ``listbox`` manual page for the full + list of options. + + Many of the methods take an *index* argument identifying a particular item. + As described in the Tk ``listbox`` manual page, *index* may be a numeric + index (counting from 0 at the top), ``'active'`` (the item with the location + cursor, set with :meth:`activate`), ``'anchor'`` (the selection anchor, set + with :meth:`selection_anchor`), ``'end'`` (the last item, or for + :meth:`index` and :meth:`insert` the position just after it), or ``@x,y`` + (the item covering pixel coordinates *x*, *y* in the listbox window). + Arguments named *first* and *last* are indices of the same forms. + + .. method:: insert(index, *elements) + + Insert the given *elements* as new items just before the item given by + *index*. If *index* is ``'end'``, the new items are appended to the end + of the list. + + .. method:: delete(first, last=None) + + Delete the items in the range from *first* to *last* inclusive. If + *last* is omitted, it defaults to *first*, so that a single item is + deleted. + + .. method:: get(first, last=None) + + If *last* is omitted, return the contents of the item given by *first*, + or an empty string if *first* refers to a non-existent item. If *last* + is given, return a tuple of all the items in the range from *first* to + *last* inclusive. + + .. method:: size() + + Return the total number of items in the listbox. + + .. method:: index(index) + + Return the integer index value corresponding to *index*, or ``None`` if + *index* is out of range. If *index* is ``'end'``, the result is a count + of the number of items in the listbox (not the index of the last item). + + .. method:: bbox(index) + + Return a tuple ``(x, y, width, height)`` describing the bounding box, in + pixels relative to the widget, of the text of the item given by *index*. + Return ``None`` if no part of that item is visible on the screen, or if + *index* refers to a non-existent item; if the item is only partly + visible, the result still gives the full area of the item, including the + parts that are not visible. + + .. method:: nearest(y) + + Given a y-coordinate within the listbox window, return the index of the + visible item nearest to that y-coordinate. + + .. method:: see(index) + + Adjust the view so that the item given by *index* is visible. If the + item is already visible the method has no effect; if it is near an edge + of the window the listbox scrolls just enough to bring it into view at + that edge, otherwise the listbox scrolls to center the item. + + .. method:: activate(index) + + Set the active item to the one given by *index*. If *index* is outside + the range of items, the closest item is activated instead. The active + item is drawn as specified by the *activestyle* option when the widget + has the input focus, and its index may be retrieved with the ``'active'`` + index. + + .. method:: curselection() + + Return a tuple containing the numerical indices of all of the items that + are currently selected, or an empty tuple if no items are selected. + + .. method:: selection_anchor(index) + + Set the selection anchor to the item given by *index*. If *index* refers + to a non-existent item, the closest item is used. The selection anchor + is the end of the selection that is fixed while dragging out a selection + with the mouse, and may afterwards be referred to with the ``'anchor'`` + index. :meth:`!select_anchor` is an alias of :meth:`!selection_anchor`. + + .. method:: selection_clear(first, last=None) + + Deselect any of the items in the range from *first* to *last* inclusive + that are selected. The selection state of items outside this range is + not changed. :meth:`!select_clear` is an alias of + :meth:`!selection_clear`. + + .. method:: selection_includes(index) + + Return ``True`` if the item given by *index* is currently selected, + ``False`` otherwise. :meth:`!select_includes` is an alias of + :meth:`!selection_includes`. + + .. method:: selection_set(first, last=None) + + Select all of the items in the range from *first* to *last* inclusive, + without affecting the selection state of items outside that range. + :meth:`!select_set` is an alias of :meth:`!selection_set`. + + .. method:: itemcget(index, option) + + Return the current value of the configuration option *option* for the + item given by *index*. + + .. method:: itemconfigure(index, cnf=None, **kw) + + Query or modify the configuration options of the item given by *index*. + This mirrors :meth:`~Widget.configure`, except that it applies to an + individual item rather than to the listbox as a whole. With no options, + it returns a dictionary describing the current options of the item; + otherwise it sets the given options. The supported item options are + *background*, *foreground*, *selectbackground* and *selectforeground*. + :meth:`!itemconfig` is an alias of :meth:`!itemconfigure`. + + .. method:: scan_mark(x, y) + + Record *x*, *y* and the current view, for use with later + :meth:`scan_dragto` calls. This is typically bound to a mouse button + press in the widget. + + .. method:: scan_dragto(x, y) + + Scroll the listbox by 10 times the difference between *x*, *y* and the + coordinates passed to the last :meth:`scan_mark` call. This is typically + bound to mouse motion events in the widget, producing the effect of + dragging the list at high speed through the window. + + +.. class:: Menu(master=None, cnf={}, **kw) + + A :class:`!Menu` widget displays a column of entries, each of which may be a + command, a checkbutton, a radiobutton, a cascade (which posts an associated + submenu) or a separator. Menus are used as the menubar of a toplevel + window, as pulldown menus posted from a cascade entry or menubutton, and as + popup menus. Inherits from :class:`Widget`. + + Many of the entry methods take an *index* argument that selects which entry + to operate on. As described in the Tk ``menu`` manual page, *index* may be a + numeric index (counting from 0 at the top), ``'active'`` (the currently + active entry), ``'end'`` or ``'last'`` (the bottommost entry), ``'none'`` (no + entry at all, written ``{}`` in Tcl), ``@y`` (the entry covering pixel + y-coordinate *y* in the menu window), or a pattern matched against the labels + of the entries from the top down. + + .. method:: add(itemType, cnf={}, **kw) + + Add a new entry to the bottom of the menu. *itemType* is one of + ``'command'``, ``'cascade'``, ``'checkbutton'``, ``'radiobutton'`` or + ``'separator'`` and determines the type of the new entry; the remaining + options configure it. The :meth:`!add_command`, :meth:`!add_cascade`, + :meth:`!add_checkbutton`, :meth:`!add_radiobutton` and + :meth:`!add_separator` convenience methods call this method with the + corresponding *itemType*. + + .. method:: add_cascade(cnf={}, **kw) + + Add a new cascade entry to the bottom of the menu. A cascade entry has an + associated submenu, given by its *menu* option, which must be a child of + this menu; posting the entry posts the submenu next to it. + + .. method:: add_checkbutton(cnf={}, **kw) + + Add a new checkbutton entry to the bottom of the menu. When invoked, a + checkbutton entry toggles between its *onvalue* and *offvalue*, storing the + result in its associated *variable*, and displays an indicator showing + whether it is selected. + + .. method:: add_command(cnf={}, **kw) + + Add a new command entry to the bottom of the menu. A command entry + behaves much like a button: when it is invoked, the callback given by its + *command* option is called. + + .. method:: add_radiobutton(cnf={}, **kw) + + Add a new radiobutton entry to the bottom of the menu. Radiobutton + entries sharing the same *variable* form a group of which only one may be + selected at a time; selecting an entry stores its *value* in the variable. + + .. method:: add_separator(cnf={}, **kw) + + Add a separator to the bottom of the menu. A separator is displayed as a + horizontal dividing line and cannot be activated or invoked. + + .. method:: insert(index, itemType, cnf={}, **kw) + + Same as :meth:`add`, except that the new entry is inserted just before the + entry given by *index* instead of being appended to the end of the menu. + *itemType* is one of ``'command'``, ``'cascade'``, ``'checkbutton'``, + ``'radiobutton'`` or ``'separator'``. The :meth:`!insert_command`, + :meth:`!insert_cascade`, :meth:`!insert_checkbutton`, + :meth:`!insert_radiobutton` and :meth:`!insert_separator` convenience + methods call this method with the corresponding *itemType*. + + .. method:: insert_cascade(index, cnf={}, **kw) + + Insert a new cascade entry before the entry given by *index* (see + :meth:`add_cascade`). + + .. method:: insert_checkbutton(index, cnf={}, **kw) + + Insert a new checkbutton entry before the entry given by *index* (see + :meth:`add_checkbutton`). + + .. method:: insert_command(index, cnf={}, **kw) + + Insert a new command entry before the entry given by *index* (see + :meth:`add_command`). + + .. method:: insert_radiobutton(index, cnf={}, **kw) + + Insert a new radiobutton entry before the entry given by *index* (see + :meth:`add_radiobutton`). + + .. method:: insert_separator(index, cnf={}, **kw) + + Insert a separator before the entry given by *index* (see + :meth:`add_separator`). + + .. method:: delete(index1, index2=None) + + Delete all of the menu entries between *index1* and *index2* inclusive. + If *index2* is omitted, it defaults to *index1*, so that a single entry is + deleted. Attempts to delete a tear-off entry are ignored; remove it by + changing the *tearoff* option instead. + + .. method:: entrycget(index, option) + + Return the current value of the configuration option *option* for the + entry given by *index*. + + .. method:: entryconfigure(index, cnf=None, **kw) + entryconfig(index, cnf=None, **kw) + + Query or modify the configuration options of the entry given by *index*. + This mirrors :meth:`~Widget.configure`, except that it applies to an + individual entry rather than to the menu as a whole. With no options, it + returns a dictionary describing the current options of the entry; + otherwise it sets the given options. :meth:`!entryconfig` is an alias of + :meth:`!entryconfigure`. + + .. method:: index(index) + + Return the numerical index corresponding to *index*, or ``None`` if + *index* selects no entry. + + .. method:: type(index) + + Return the type of the entry given by *index*: one of ``'command'``, + ``'cascade'``, ``'checkbutton'``, ``'radiobutton'``, ``'separator'`` or + ``'tearoff'`` (for the tear-off entry). + + .. method:: activate(index) + + Make the entry given by *index* the active entry, redisplaying it with its + active colors, and deactivate any previously active entry. If *index* + selects no entry, or the selected entry is disabled, the menu ends up with + no active entry. + + .. method:: invoke(index) + + Invoke the action of the entry given by *index*, as if it had been clicked. + Nothing happens if the entry is disabled. If the entry has a *command* + associated with it, the result of that command is returned; otherwise the + result is an empty string. + + .. method:: post(x, y) + + Display the menu on the screen at the root-window coordinates *x* and *y*, + adjusting them if necessary so that the whole menu is visible. If the + *postcommand* option has been specified, it is evaluated before the menu is + posted. + + .. method:: tk_popup(x, y, entry='') + + Post the menu as a popup at the root-window coordinates *x* and *y*. If + *entry* is given, the menu is positioned so that this entry is displayed + under the pointer. + + .. method:: unpost() + + Unmap the menu so that it is no longer displayed, also unposting any posted + lower-level cascaded submenu. This has no effect on Windows and macOS, + which manage the unposting of menus themselves. + + .. method:: xposition(index) + + Return the x-coordinate, within the menu window, of the leftmost pixel of + the entry given by *index*. + + .. versionadded:: 3.3 + + .. method:: yposition(index) + + Return the y-coordinate, within the menu window, of the topmost pixel of + the entry given by *index*. + + +.. class:: Menubutton(master=None, cnf={}, **kw) + + A :class:`!Menubutton` widget displays a textual string, bitmap or image + and posts an associated :class:`Menu`, given by its *menu* option, when the + user presses it. Like a :class:`Label` it can show *text*, a + *textvariable*, or an *image*, and the *direction* option controls where + the menu appears relative to the button. Inherits from :class:`Widget`. + Refer to the Tk ``menubutton`` manual page for the full list of options. + + +.. class:: Message(master=None, cnf={}, **kw) + + A :class:`!Message` widget displays a non-interactive textual string, + given by the *text* option or linked to a variable through *textvariable*. + Unlike a :class:`Label`, it breaks the string into multiple lines in order + to produce a given aspect ratio, choosing line breaks at word boundaries, + and it can justify the text left, centered or right. Inherits from + :class:`Widget`. Refer to the Tk ``message`` manual page for the full + list of options. + + +.. class:: OptionMenu(master, variable, value, *values, **kwargs) + + A helper subclass of :class:`Menubutton` that displays a pop-up menu of + mutually exclusive choices. *variable* is a :class:`Variable` kept in sync + with the selection, *value* is the initial choice, and *values* are the + remaining menu entries. The keyword argument *command* may be given a + callback that is invoked with the selected value, and the keyword argument + *name* sets the Tk widget name. + + .. method:: destroy() + + Destroy the widget, also cleaning up the associated pop-up menu. + + .. versionchanged:: 3.14 + Added support for the *name* keyword argument. + + + +.. class:: PanedWindow(master=None, cnf={}, **kw) + + A :class:`!PanedWindow` is a geometry-manager widget that arranges any + number of child *panes* in a row (when *orient* is ``'horizontal'``) or a + column (when *orient* is ``'vertical'``). Each pane holds one widget, and + each pair of adjacent panes is separated by a movable *sash* that the user + can drag with the mouse to resize the widgets on either side of it. + Inherits from :class:`Widget`. + + The *orient* option selects the layout direction, *sashwidth* sets the + width of each sash and *sashrelief* its relief. When *showhandle* is true + a small handle is drawn on each sash that the user can grab to drag it. + Refer to the Tk ``panedwindow`` manual page for the full list of options. + + .. method:: add(child, **kw) + + Add *child* to the panedwindow as a new pane, placed after any existing + panes. The keyword arguments specify per-pane management options for + *child*; they may be any of the options accepted by + :meth:`paneconfigure`. + + .. method:: remove(child) + forget(child) + + Remove the pane containing *child* from the panedwindow. All geometry + management options for *child* are forgotten. :meth:`!forget` is an + alias of :meth:`!remove`. + + .. method:: panes() + + Return a tuple of the widgets managed by the panedwindow, one per pane, + in order. + + .. method:: panecget(child, option) + + Return the current value of the management option *option* for the pane + containing *child*. *option* may be any value allowed by + :meth:`paneconfigure`. + + .. method:: paneconfigure(tagOrId, cnf=None, **kw) + paneconfig(tagOrId, cnf=None, **kw) + + Query or modify the management options of the pane containing the widget + *tagOrId*. With no options, it returns a dictionary describing all of + the available options for the pane; given a single option name as a + string, it returns a description of that one option; otherwise it sets + the given options. The supported options include *after* and *before* + (insert the pane after or before another managed window), *height* and + *width* (the outer dimensions of the window, including any border), + *minsize* (the minimum size in the paned dimension), *padx* and *pady* + (extra space to leave on each side of the window), *sticky* (position or + stretch the window within an oversized pane, using a string of the + characters ``n``, ``s``, ``e`` and ``w``), *hide* (hide the pane while + keeping it in the list of panes) and *stretch* (how extra space is + allocated to the pane: one of ``'always'``, ``'first'``, ``'last'``, + ``'middle'`` or ``'never'``). :meth:`!paneconfig` is an alias of + :meth:`!paneconfigure`. + + .. method:: identify(x, y) + + Identify the panedwindow component underneath the point given by *x* and + *y*, in window coordinates. If the point is over a sash or a sash + handle, the result is a two-element tuple containing the index of the + sash or handle and a word indicating whether it is over a sash or a + handle, such as ``(0, 'sash')`` or ``(2, 'handle')``. If the point is + over any other part of the panedwindow, the result is an empty string. + + .. method:: sash(*args) + + Query or change the position of the sashes in the panedwindow. This is + a thin wrapper around the Tk ``sash`` subcommand; the convenience + methods :meth:`sash_coord`, :meth:`sash_mark` and :meth:`sash_place` + should normally be used instead. + + .. method:: sash_coord(index) + + Return the current x and y coordinate pair for the sash given by + *index*, which must be an integer between 0 and one less than the number + of panes in the panedwindow. The coordinates returned are those of the + top left corner of the region containing the sash. + + .. method:: sash_mark(index) + + Record the current mouse position for the sash given by *index*, for use + together with later sash-drag operations to move the sash. + + .. method:: sash_place(index, x, y) + + Place the sash given by *index* at the coordinates *x* and *y*. + + .. method:: proxy(*args) + + Query or change the position of the sash proxy, the "ghost" sash shown + while a sash is being dragged with non-opaque resizing. This is a thin + wrapper around the Tk ``proxy`` subcommand; the convenience methods + :meth:`proxy_coord`, :meth:`proxy_forget` and :meth:`proxy_place` should + normally be used instead. + + .. method:: proxy_coord() + + Return a tuple containing the x and y coordinates of the most recent + proxy location. + + .. method:: proxy_forget() + + Remove the proxy from the display. + + .. method:: proxy_place(x, y) + + Place the proxy at the coordinates *x* and *y*. + + +.. class:: Radiobutton(master=None, cnf={}, **kw) + + A :class:`!Radiobutton` widget displays a textual string, bitmap or image + together with a diamond or circular indicator, and selects one choice out of + several. It has all the behavior of a simple button and, in addition, can + be selected: typically several radiobuttons share a single *variable*, and + selecting one sets that variable to the radiobutton's *value*; each + radiobutton also monitors the variable and automatically selects or + deselects itself when the variable changes. Inherits from :class:`Widget`. + In addition to the standard widget options, a radiobutton accepts the + options documented in the Tk ``radiobutton`` manual page, such as + *variable*, *value* and *command*. + + .. method:: invoke() + + Do just what would happen if the user pressed the radiobutton with the + mouse: select the button and invoke the associated command, if there is + one. Return the result of the command, or an empty string if no command + is associated with the radiobutton. This is ignored if the radiobutton's + state is ``disabled``. + + .. method:: select() + + Select the radiobutton and set the associated variable to the value + corresponding to this widget. + + .. method:: deselect() + + Deselect the radiobutton and set the associated variable to an empty + string. If this radiobutton was not currently selected, this has no + effect. + + .. method:: flash() + + Flash the radiobutton by redisplaying it several times, alternating + between the active and normal colors. At the end of the flash the + radiobutton is left in the same normal or active state as when the method + was called. This is ignored if the radiobutton's state is ``disabled``. + + +.. class:: Scale(master=None, cnf={}, **kw) + + A :class:`!Scale` widget lets the user select a numerical value by moving a + slider along a trough. It can be oriented vertically or horizontally and + can optionally display a label and the current value. Inherits from + :class:`Widget`. + + In addition to the standard widget options, a scale accepts the options + documented in the Tk ``scale`` manual page, such as *from_*, *to*, + *resolution*, *orient*, *tickinterval*, *variable* and *command*. As + elsewhere in :mod:`!tkinter`, the leading ``-`` of the Tk option name is + dropped; *from* is spelled ``from_`` because :keyword:`from` is a Python + keyword. + + .. method:: get() + + Return the current value of the scale. The result is an integer if the + scale's *resolution* yields whole numbers, and a float otherwise. + + .. method:: set(value) + + Set the scale to *value*, moving the slider accordingly. This has no + effect if the scale is disabled. + + .. method:: coords(value=None) + + Return a tuple ``(x, y)`` giving the pixel coordinates, relative to the + widget, of the point on the centerline of the trough that corresponds to + *value*. If *value* is omitted, the scale's current value is used. + + .. method:: identify(x, y) + + Return a string describing the part of the scale at the pixel coordinates + *x*, *y*: ``'slider'``, ``'trough1'`` (the part of the trough above or to + the left of the slider), ``'trough2'`` (below or to the right of the + slider), or an empty string if the point is not over any of these + elements. + + +.. class:: Scrollbar(master=None, cnf={}, **kw) + + A :class:`!Scrollbar` widget displays a slider and two arrows that let the + user scroll an associated widget, such as a :class:`Listbox`, :class:`Text`, + :class:`Canvas` or :class:`Entry`. It is connected to the scrolled widget by + setting that widget's *xscrollcommand* or *yscrollcommand* option to the + scrollbar's :meth:`set` method, and the scrollbar's *command* option to the + scrolled widget's :meth:`~XView.xview` or :meth:`~YView.yview` method. + Inherits from :class:`Widget`. + + .. method:: get() + + Return the current scrollbar settings as a tuple ``(first, last)`` of two + fractions between 0 and 1, describing the portion of the document that is + currently visible, as last passed to :meth:`set`. + + .. method:: set(first, last) + + Set the scrollbar. *first* and *last* are fractions between 0 and 1 + giving the positions of the start and end of the visible portion of the + associated document. This method is normally registered as the scrolled + widget's *xscrollcommand* or *yscrollcommand* and called by that widget. + + .. method:: activate(index=None) + + Mark the element *index* (one of ``'arrow1'``, ``'slider'`` or + ``'arrow2'``) as active, displaying it according to the *activebackground* + and *activerelief* options. If *index* is omitted, return the name of the + currently active element, or ``None`` if no element is active. + + .. versionchanged:: 3.5 + The *index* argument is now optional. + + .. method:: delta(deltax, deltay) + + Return a float indicating the fractional change in the scrollbar setting + that corresponds to moving the slider by *deltax* pixels horizontally (for + horizontal scrollbars) or *deltay* pixels vertically (for vertical + scrollbars). + + .. method:: fraction(x, y) + + Return a float between 0 and 1 indicating where the point at pixel + coordinates *x*, *y* lies in the trough: 0 corresponds to the top or left + of the trough and 1 to the bottom or right. + + .. method:: identify(x, y) + + Return the name of the element under the pixel coordinates *x*, *y* (such + as ``'arrow1'``), or an empty string if the point does not lie in any + element of the scrollbar. + + +.. class:: Spinbox(master=None, cnf={}, **kw) + + A :class:`!Spinbox` widget is an :class:`Entry`-like widget with a pair of + up/down arrow buttons that let the user step through a range of values in + addition to editing the value directly. The set of values may be a numeric + range given by the *from_*, *to* and *increment* options, or an explicit list + of strings given by the *values* option (which takes precedence over the + range). Each time an arrow is invoked the *command* callback, if any, is + called; the *wrap* option controls whether stepping past either end of the + range wraps around to the other end; the *format* option specifies how + numeric values are formatted; and the *validate* option enables validation of + the entered text. Inherits from :class:`Widget` and :class:`XView`. + + Many of the methods take an *index* argument identifying a character in the + spinbox's string. As described in the Tk ``spinbox`` manual page, *index* + may be a numeric index (counting from 0), ``'anchor'`` (the selection anchor + point), ``'end'`` (just after the last character), ``'insert'`` (the + character just after the insertion cursor), ``'sel.first'`` or ``'sel.last'`` + (the ends of the selection), or ``@x`` (the character covering pixel + x-coordinate *x* in the window). + + .. method:: get() + + Return the spinbox's string. + + .. method:: insert(index, s) + + Insert the characters of the string *s* just before the character given by + *index*. + + .. method:: delete(first, last=None) + + Delete one or more characters of the spinbox. *first* is the index of the + first character to delete, and *last* is the index of the character just + after the last one to delete. If *last* is omitted, a single character at + *first* is deleted. + + .. method:: icursor(index) + + Arrange for the insertion cursor to be displayed just before the character + given by *index*. + + .. method:: index(index) + + Return the numerical index corresponding to *index*, as a string. + + .. method:: bbox(index) + + Return a tuple of four integers ``(x, y, width, height)`` describing the + bounding box of the character given by *index*. *x* and *y* are the pixel + coordinates of the upper-left corner of the character relative to the + widget, and *width* and *height* are its size in pixels. The bounding box + may refer to a region outside the visible area of the window. + + .. method:: identify(x, y) + + Return the name of the window element at the pixel coordinates *x*, *y*: + one of ``'buttondown'``, ``'buttonup'``, ``'entry'`` or ``'none'``. + + .. method:: invoke(element) + + Invoke the spin button given by *element*, either ``'buttonup'`` or + ``'buttondown'``, triggering the action associated with it. + + .. method:: scan(*args) + + A thin wrapper around the Tk ``scan`` widget subcommand, used to implement + fast dragging of the view: ``scan('mark', x)`` records *x* and the current + view, and ``scan('dragto', x)`` adjusts the view relative to that mark. + The :meth:`scan_mark` and :meth:`scan_dragto` methods wrap the two forms. + + .. method:: scan_mark(x) + + Record *x* and the current view in the spinbox window, for use with a + later :meth:`scan_dragto` call. This is typically associated with a mouse + button press in the widget. + + .. method:: scan_dragto(x) + + Adjust the view by 10 times the difference between *x* and the *x* passed + to the last :meth:`scan_mark` call. This is typically associated with + mouse motion events, producing the effect of dragging the spinbox at high + speed through the window. + + .. method:: selection(*args) + + A thin wrapper around the Tk ``selection`` widget subcommand, used to + adjust the selection within the spinbox. It has several forms depending on + the first argument, such as ``selection('adjust', index)``, + ``selection('clear')``, ``selection('element', ?elem?)``, + ``selection('from', index)``, ``selection('present')``, + ``selection('range', start, end)`` and ``selection('to', index)``. The + :meth:`selection_adjust`, :meth:`selection_clear`, + :meth:`selection_element`, :meth:`selection_from`, + :meth:`selection_present`, :meth:`selection_range` and :meth:`selection_to` + methods wrap these forms. + + .. method:: selection_adjust(index) + + Locate the end of the selection nearest to the character given by *index* + and adjust that end of the selection to be at *index* (including but not + going beyond *index*). The other end becomes the anchor point for future + :meth:`selection_to` calls. If the selection is not currently in the + spinbox, a new selection is created to include the characters between + *index* and the most recent anchor point, inclusive. + + .. method:: selection_clear() + + Clear the selection if it is currently in this widget. If the selection is + not in this widget, the method has no effect. + + .. method:: selection_element(element=None) + + Set or get the currently selected element. If *element* (one of + ``'buttonup'``, ``'buttondown'`` or ``'none'``) is given, that spin button + is selected and displayed depressed; otherwise the name of the currently + selected element is returned. + + .. method:: selection_from(index) + + Set the selection anchor point to just before the character given by + *index*, without changing the selection itself. + + .. versionadded:: 3.8 + + + .. method:: selection_present() + + Return ``True`` if there are characters selected in the spinbox, + ``False`` otherwise. + + .. versionadded:: 3.8 + + + .. method:: selection_range(start, end) + + Set the selection to include the characters starting with the one indexed + by *start* and ending with the one just before *end*. If *end* refers to + the same character as *start* or an earlier one, the selection is cleared. + + .. versionadded:: 3.8 + + + .. method:: selection_to(index) + + Set the selection between *index* and the anchor point. If *index* is + before the anchor point, the selection runs from *index* up to but not + including the anchor point; if it is after, the selection runs from the + anchor point up to but not including *index*; if it is the same, nothing + happens. The anchor point is the one set by the most recent + :meth:`selection_from` or :meth:`selection_adjust` call. If the selection + is not in this widget, a new selection is created using the most recent + anchor point. + + .. versionadded:: 3.8 + + + +.. class:: Text(master=None, cnf={}, **kw) + + A :class:`!Text` widget displays and edits multi-line text. Portions of the + text may be styled with **tags**, particular positions may be annotated with + floating **marks**, and arbitrary images and other widgets may be embedded + in the text. The widget also provides an unlimited undo/redo mechanism and + supports peer widgets that share the same underlying data. Inherits from + :class:`Widget`, :class:`XView` and :class:`YView`, so the view can be + scrolled horizontally and vertically with :meth:`~XView.xview` and + :meth:`~YView.yview`. Refer to the Tk ``text`` manual page for the full + list of options. + + Most of the methods take one or more *index* arguments that identify a + position within the text. As described in the Tk ``text`` manual page, an + index is a string consisting of a base, optionally followed by one or more + modifiers. The base may be ``'line.char'`` (line *line*, character *char*, + where lines are counted from 1 and characters within a line from 0; + ``'line.end'`` refers to the newline ending the line), ``'end'`` (the + position just after the last newline), the name of a mark, ``'tag.first'`` + or ``'tag.last'`` (the first character tagged with *tag*, or the position + just after the last such character), the name of an embedded image or + window, or ``@x,y`` (the character covering pixel coordinates *x*, *y* in + the widget). A modifier such as ``'+5 chars'``, ``'-3 lines'``, + ``'linestart'``, ``'lineend'``, ``'wordstart'`` or ``'wordend'`` adjusts the + index relative to its base; several modifiers may be combined and are + applied from left to right, for example ``'insert wordstart - 1 c'``. + + .. method:: insert(index, chars, *args) + + Insert the string *chars* just before the character at *index* (if + *index* is ``'end'``, just before the final newline). By default the new + text inherits any tags present on both sides of the insertion point. If + *args* is given, it consists of alternating *tagList*, *chars* values: the + preceding *chars* receives exactly the tags listed (a tag list may be a + single tag name or a sequence of names), overriding the surrounding tags. + + .. method:: delete(index1, index2=None) + + Delete the range of characters from *index1* up to but not including + *index2*. If *index2* is omitted, the single character at *index1* is + deleted. The widget always keeps a newline as its last character, so a + deletion that would remove it is adjusted accordingly. + + .. method:: replace(index1, index2, chars, *args) + + Replace the range of characters from *index1* up to but not including + *index2* with *chars*. This is equivalent to a :meth:`delete` followed by + an :meth:`insert` at *index1*; *args* is interpreted as for + :meth:`insert`. + + .. versionadded:: 3.3 + + .. method:: get(index1, index2=None) + + Return the text from *index1* up to but not including *index2* as a + string. If *index2* is omitted, return the single character at *index1*. + Embedded images and windows are omitted from the result. + + .. method:: index(index) + + Return the position corresponding to *index* in the canonical + ``'line.char'`` form. + + .. method:: compare(index1, op, index2) + + Compare the positions of *index1* and *index2* using the relational + operator *op*, which must be one of ``'<'``, ``'<='``, ``'=='``, + ``'>='``, ``'>'`` or ``'!='``, and return the boolean result. + + .. method:: count(index1, index2, *options, return_ints=False) + + Count the number of items of the requested kinds between *index1* and + *index2*; the count is negative if *index1* is after *index2*. Each of + *options* names a kind of item to count: ``'chars'``, ``'displaychars'``, + ``'displayindices'``, ``'displaylines'``, ``'indices'``, ``'lines'``, + ``'xpixels'`` or ``'ypixels'`` (the default, used when no option is given, + is ``'indices'``). The pseudo-option ``'update'`` forces any out-of-date + layout information to be recalculated before the following options are + evaluated. When *return_ints* is true and a single counting option is + given, return a plain integer; otherwise return a tuple with one integer + per counting option (or ``None`` if the result is empty). + + .. versionadded:: 3.3 + + .. versionchanged:: 3.13 + Added the *return_ints* parameter. + + + .. method:: see(index) + + Adjust the view so that the character given by *index* is visible. If it + is already visible the method has no effect; if it is a short distance out + of view the widget scrolls just enough to bring it to the nearest edge, + otherwise it scrolls to center *index* in the window. + + .. method:: bbox(index) + + Return a tuple ``(x, y, width, height)`` giving the bounding box, in + pixels, of the visible part of the character at *index*, or ``None`` if + that character is not visible on the screen. + + .. method:: dlineinfo(index) + + Return a tuple ``(x, y, width, height, baseline)`` describing the display + line that contains *index*: the first four values give the bounding box + of the line in pixels and *baseline* gives the offset of the baseline + measured down from the top of the area. Return ``None`` if that display + line is not visible on the screen. + + .. method:: mark_set(markName, index) + + Set the mark named *markName* to the position just before the character at + *index*, creating the mark if it does not already exist. A mark created + this way has right gravity by default. + + .. method:: mark_unset(*markNames) + + Remove each of the marks named in *markNames*. The special ``insert`` and + ``current`` marks may not be removed. + + .. method:: mark_names() + + Return a tuple of the names of all marks currently set in the widget. + + .. method:: mark_gravity(markName, direction=None) + + If *direction* is omitted, return the gravity of mark *markName*, either + ``'left'`` or ``'right'``. Otherwise set its gravity to *direction*. The + gravity determines on which side of the mark text inserted at the mark's + position appears: a mark with right gravity (the default) stays to the + right of such text. + + .. method:: mark_next(index) + + Return the name of the first mark at or after *index*, or ``None`` if + there is none. When *index* is the name of a mark, the search starts just + after that mark. + + .. method:: mark_previous(index) + + Return the name of the last mark at or before *index*, or ``None`` if + there is none. When *index* is the name of a mark, the search starts just + before that mark. + + .. method:: tag_add(tagName, index1, *args) + + Add the tag *tagName* to the range of characters from *index1* up to but + not including the next index in *args*. Further pairs of indices may + follow in *args* to tag additional ranges; a trailing single index tags + just the character at that index. + + .. method:: tag_remove(tagName, index1, index2=None) + + Remove the tag *tagName* from the characters from *index1* up to but not + including *index2* (or from the single character at *index1* if *index2* is + omitted). The tag itself continues to exist even if no characters carry + it. + + .. method:: tag_delete(*tagNames) + + Delete each of the tags named in *tagNames*, removing them from all + characters and discarding their options and bindings. + + .. method:: tag_configure(tagName, cnf=None, **kw) + tag_config(tagName, cnf=None, **kw) + + Query or modify the configuration options of the tag *tagName*. This + mirrors :meth:`~Widget.configure`, except that it applies to a tag rather + than to the widget as a whole: with no options it returns a dictionary + describing the current options, otherwise it sets the given options. + Supported tag options control the appearance of the tagged text and + include *background*, *foreground*, *font*, *justify*, *underline*, + *overstrike*, *relief*, *borderwidth*, the margin and spacing options, and + *elide* (whether the text is hidden). Defining a tag this way also gives + it a priority higher than any existing tag. + + :meth:`!tag_config` is an alias of :meth:`!tag_configure`. + + .. method:: tag_cget(tagName, option) + + Return the current value of the configuration option *option* for the tag + *tagName*. + + .. method:: tag_names(index=None) + + If *index* is omitted, return a tuple of the names of all tags defined in + the widget; otherwise return only the names of the tags applied to the + character at *index*. The names are ordered from lowest to highest + priority. + + .. method:: tag_ranges(tagName) + + Return a tuple of indices describing all ranges of text tagged with + *tagName*. The result alternates start and end indices, so that elements + ``2*i`` and ``2*i+1`` bound the *i*-th range. + + .. method:: tag_nextrange(tagName, index1, index2=None) + + Search forward from *index1* (up to *index2* if given) for the first range + of characters tagged with *tagName*, and return a two-element tuple of its + start and end indices, or an empty tuple if there is no such range. + + .. method:: tag_prevrange(tagName, index1, index2=None) + + Search backward from *index1* (down to *index2* if given) for the nearest + preceding range of characters tagged with *tagName*, and return a + two-element tuple of its start and end indices, or an empty tuple if there + is no such range. + + .. method:: tag_raise(tagName, aboveThis=None) + + Raise the priority of tag *tagName* so that it is just above the priority + of *aboveThis*, or to the highest priority of all tags if *aboveThis* is + omitted. When the display options of overlapping tags conflict, the + higher-priority tag wins. + + .. method:: tag_lower(tagName, belowThis=None) + + Lower the priority of tag *tagName* so that it is just below the priority + of *belowThis*, or to the lowest priority of all tags if *belowThis* is + omitted. + + .. method:: tag_bind(tagName, sequence, func, add=None) + + Bind the event *sequence* on characters tagged with *tagName* to the + callback *func*, so that *func* is invoked when that event occurs over such + a character. If *add* is true the binding is added alongside any existing + bindings for *sequence*, otherwise it replaces them. Works like + :meth:`~Misc.bind` and returns the identifier of the new binding. + + .. method:: tag_unbind(tagName, sequence, funcid=None) + + Remove the bindings of the event *sequence* on characters tagged with + *tagName*. If *funcid* is given, only that binding (as returned by + :meth:`tag_bind`) is removed and its callback is unregistered. + + .. versionchanged:: 3.13 + If *funcid* is given, only that callback is unbound. + + + .. method:: image_create(index, cnf={}, **kw) + + Embed an image at *index* and return the name assigned to this image + instance, which may then be used as an index or passed to the other + ``image_*`` methods. The options, given in *cnf* and *kw*, include + *image* (the Tk image to display), *name* (a base name for the instance), + *align*, *padx* and *pady*. + + .. method:: image_cget(index, option) + + Return the current value of the configuration option *option* for the + embedded image at *index*. + + .. method:: image_configure(index, cnf=None, **kw) + + Query or modify the configuration options of the embedded image at + *index*, like :meth:`~Widget.configure` but applied to that image. + + .. method:: image_names() + + Return a tuple of the names of all images embedded in the widget. + + .. method:: window_create(index, cnf={}, **kw) + + Embed a window (any widget) at *index*. The options, given in *cnf* and + *kw*, include *window* (the widget to embed), *create* (a callback that + creates the widget on demand), *align*, *stretch*, *padx* and *pady*. The + embedded widget must be a descendant of the text widget's parent. + + .. method:: window_cget(index, option) + + Return the current value of the configuration option *option* for the + embedded window at *index*. + + .. method:: window_configure(index, cnf=None, **kw) + window_config(index, cnf=None, **kw) + + Query or modify the configuration options of the embedded window at + *index*, like :meth:`~Widget.configure` but applied to that window. + + :meth:`!window_config` is an alias of :meth:`!window_configure`. + + .. method:: window_names() + + Return a tuple of the names of all windows embedded in the widget. + + .. method:: edit(*args) + + Low-level wrapper around the Tk ``edit`` widget command that controls the + undo/redo mechanism and the modified flag; *args* is the ``edit`` + subcommand and its arguments. The :meth:`!edit_\*` methods below are + thin wrappers around it and are usually more convenient. + + .. method:: edit_modified(arg=None) + + If *arg* is omitted, return the current state of the modified flag as + ``0`` or ``1``; the flag is set automatically whenever the text is + inserted or deleted. Otherwise set the flag to the boolean *arg*. + + .. method:: edit_undo() + + Undo the most recent edit action, that is, all the inserts and deletes + recorded on the undo stack since the previous separator, and move it to + the redo stack. Raises :exc:`TclError` if the undo stack is empty. Has + no effect unless the *undo* option is true. Since Tk 9.0, returns a tuple + of indices delimiting the ranges of text that were changed. + + .. method:: edit_redo() + + Reapply the most recently undone edit action, provided no further edits + have been made since, and move it back to the undo stack. Raises + :exc:`TclError` if the redo stack is empty. Has no effect unless the + *undo* option is true. Since Tk 9.0, returns a tuple of indices delimiting + the ranges of text that were changed. + + .. method:: edit_reset() + + Clear the undo and redo stacks. + + .. method:: edit_separator() + + Push a separator onto the undo stack, marking a boundary between edit + actions for undo and redo. Has no effect unless the *undo* option is + true. Separators are inserted automatically when the *autoseparators* + option is true. + + .. method:: search(pattern, index, stopindex=None, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, *, nolinestop=None, strictlimits=None) + + Search for *pattern* starting at *index* and return the index of the first + character of the first match, or an empty string if there is no match. + Searching stops at *stopindex* if given; otherwise it wraps around the + ends of the text until the starting position is reached again. The + following boolean keyword flags control the search: *forwards* or + *backwards* select the direction (forward is the default); *exact* (the + default) or *regexp* select literal or regular-expression matching; + *nocase* makes the match case-insensitive; *elide* causes hidden text to + be searched as well; *nolinestop* (regexp only) lets ``.`` and ``[^`` + match newlines; and *strictlimits* requires the whole match to lie within + *index* and *stopindex*. If *count* is a :class:`Variable`, the number of + index positions in the match is stored in it. + + .. versionchanged:: 3.15 + Added the *nolinestop* and *strictlimits* parameters. + + + .. method:: search_all(pattern, index, stopindex=None, *, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, nolinestop=None, overlap=None, strictlimits=None) + + Like :meth:`search`, but find every match in the searched range and return + a tuple of the starting indices of all matches (empty if there are none). + By default overlapping matches are not reported; passing a true *overlap* + returns every match that is not wholly contained in another. If *count* + is a :class:`Variable`, it receives a list with one element per match. + + .. versionadded:: 3.15 + + + .. method:: scan_mark(x, y) + + Record *x*, *y* and the current view, for use with later + :meth:`scan_dragto` calls. This is typically bound to a mouse button + press in the widget. + + .. method:: scan_dragto(x, y) + + Scroll the widget by 10 times the difference between *x*, *y* and the + coordinates passed to the last :meth:`scan_mark` call. This is typically + bound to mouse motion events, producing the effect of dragging the text at + high speed through the window. + + .. method:: debug(boolean=None) + + If *boolean* is omitted, return whether internal consistency checks of the + B-tree data structure are enabled. Otherwise enable or disable them. The + setting is shared by all text widgets and may noticeably slow down widgets + holding large amounts of text. + + .. method:: dump(index1, index2=None, command=None, **kw) + + Return the contents of the widget from *index1* up to but not including + *index2* (or just the segment at *index1* if *index2* is omitted), + including text and information about marks, tags, images and windows. The + result is a list of ``(key, value, index)`` triples, where *key* is one of + ``'text'``, ``'mark'``, ``'tagon'``, ``'tagoff'``, ``'image'`` or + ``'window'``. By default all kinds are reported; passing any of the + keyword arguments *all*, *text*, *mark*, *tag*, *image* or *window* as true + restricts the dump to the selected kinds. If *command* is given, it is + called once per triple with the three values as arguments and nothing is + returned. + + .. method:: peer_create(newPathName, cnf={}, **kw) + + Create a peer text widget with the path name *newPathName* that shares + this widget's underlying data (text, marks, tags, images and the undo + stack). Changes made through any peer are reflected in all of them. By + default the peer covers the same lines as this widget; standard text + options, including *startline* and *endline*, may be given to override + this. + + .. versionadded:: 3.3 + + .. method:: peer_names() + + Return a tuple of the path names of this widget's peers, not including the + widget itself. + + .. versionadded:: 3.3 + + .. method:: yview_pickplace(*what) + + Adjust the view so that the location given by *what* is visible. This is + an obsolete equivalent of :meth:`see`, which should be used instead. + + +Variable classes +^^^^^^^^^^^^^^^^ + +.. class:: Variable(master=None, value=None, name=None) + + The base class for the Tk variable wrappers. A Tk variable is a value + stored in the Tcl interpreter that can be linked to widgets through their + *variable* or *textvariable* options (see :ref:`coupling-widget-variables`), + so that changes propagate both ways: updating the variable updates every + widget bound to it, and a user editing such a widget updates the variable. + + *master* is the widget whose Tcl interpreter owns the variable; if omitted, + the default root window is used. *value* is the initial value; if omitted, + a type-specific default is used. *name* is the name of the variable in the + Tcl interpreter; if omitted, a unique name of the form ``'PY_VARnum'`` is + generated. If *name* matches an existing variable and *value* is omitted, + the existing value is retained. + + In most cases you should use one of the typed subclasses below -- + :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` or + :class:`BooleanVar` -- rather than :class:`!Variable` directly. + + .. versionchanged:: 3.10 + Two variables now compare equal (``==``) only when they have the same + name, are of the same class, and belong to the same Tcl interpreter. + + .. method:: get() + + Return the current value of the variable. For the base class the value + is returned as a string; the typed subclasses convert it to the + appropriate Python type. + + .. method:: set(value) + + Set the variable to *value*. + + .. method:: initialize(value) + + Set the initial value of the variable. This is an alias for + :meth:`set`. + + .. versionadded:: 3.3 + + .. method:: trace_add(mode, callback) + + Register *callback* to be called when the variable is accessed according + to *mode*. *mode* is one of the strings ``'array'``, ``'read'``, + ``'write'`` or ``'unset'``, or a list or tuple of such strings. + + When triggered, *callback* is called with three arguments: the name of + the Tcl variable, an index (or an empty string if the variable is not an + element of an array), and the *mode* that triggered the call. + + Return the internal name of the registered callback, which can be passed + to :meth:`trace_remove`. + + .. versionadded:: 3.6 + + .. method:: trace_remove(mode, cbname) + + Remove a trace callback from the variable. *mode* must match the *mode* + that was passed to :meth:`trace_add`, and *cbname* is the callback name + returned by :meth:`trace_add`. + + .. versionadded:: 3.6 + + .. method:: trace_info() + + Return a list of ``(modes, cbname)`` pairs describing all traces + currently set on the variable, where *modes* is a tuple of mode strings + and *cbname* is the internal callback name. + + .. versionadded:: 3.6 + + .. method:: trace_variable(mode, callback) + + Register *callback* to be called when the variable is accessed according + to *mode*. *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for + read, write or unset. Return the internal name of the registered + callback. + + .. deprecated:: 3.6 + Use :meth:`trace_add` instead. This method wraps a Tcl feature that + was removed in Tcl 9.0. + + .. method:: trace(mode, callback) + + An alias for :meth:`trace_variable`. + + .. deprecated:: 3.6 + Use :meth:`trace_add` instead. + + .. method:: trace_vdelete(mode, cbname) + + Remove the trace callback named *cbname* registered for *mode* with + :meth:`trace_variable`. + + .. deprecated:: 3.6 + Use :meth:`trace_remove` instead. This method wraps a Tcl feature + that was removed in Tcl 9.0. + + .. method:: trace_vinfo() + + Return a list of ``(mode, cbname)`` pairs for all traces set on the + variable with :meth:`trace_variable`. + + .. deprecated:: 3.6 + Use :meth:`trace_info` instead. This method wraps a Tcl feature that + was removed in Tcl 9.0. + + +.. class:: StringVar(master=None, value=None, name=None) + + A :class:`Variable` subclass that holds a string. The default value is + ``''``. + + .. method:: get() + + Return the value of the variable as a :class:`str`. + + +.. class:: IntVar(master=None, value=None, name=None) + + A :class:`Variable` subclass that holds an integer. The default value is + ``0``. + + .. method:: get() + + Return the value of the variable as an :class:`int`. + + +.. class:: DoubleVar(master=None, value=None, name=None) + + A :class:`Variable` subclass that holds a float. The default value is + ``0.0``. + + .. method:: get() + + Return the value of the variable as a :class:`float`. + + +.. class:: BooleanVar(master=None, value=None, name=None) + + A :class:`Variable` subclass that holds a boolean. The default value is + ``False``. + + .. method:: get() + + Return the value of the variable as a :class:`bool`. Raise a + :exc:`ValueError` if the value cannot be interpreted as a boolean. + + .. method:: set(value) + + Set the variable to *value*, converting it to a boolean. + + .. method:: initialize(value) + + Set the initial value of the variable. This is an alias for + :meth:`set`. + + +Image classes +^^^^^^^^^^^^^ + +.. class:: Image(imgtype, name=None, cnf={}, master=None, **kw) + + Base class for Tk images. *imgtype* is the Tk image type, one of + ``'photo'`` or ``'bitmap'``. An image is a named object that can be + displayed by widgets through their *image* option; deleting all references + to the :class:`!Image` object deletes the underlying Tk image. Usually you + create a :class:`PhotoImage` or :class:`BitmapImage` rather than an + :class:`!Image` directly. + + The image's configuration options are given by *cnf* and *kw* and may be + queried and changed later with the mapping protocol (using ``image[key]``) + or with the :meth:`configure` method. + + .. method:: configure(**kw) + config(**kw) + + Modify one or more configuration options of the image. The valid options + depend on the image type; see :class:`PhotoImage` and :class:`BitmapImage`. + :meth:`!config` is an alias of :meth:`!configure`. + + .. method:: height() + + Return the height of the image, in pixels. + + .. method:: width() + + Return the width of the image, in pixels. + + .. method:: type() + + Return the type of the image, that is the value of *imgtype* with which it + was created (for example ``'photo'`` or ``'bitmap'``). + + +.. class:: PhotoImage(name=None, cnf={}, master=None, **kw) + + A full-color image (the Tk ``photo`` image type), stored internally with a + varying degree of transparency per pixel. It can read and write GIF, + PPM/PGM and (in Tk 8.6 and later) PNG files, read SVG files (in Tk 9.0 and + later), and be drawn in widgets. Inherits from :class:`Image`. + + The configuration options include *data* (the image contents as a string), + *file* (the name of a file to read the contents from), *format* (the name of + the file format handler), *width* and *height* (the size of the image, used + when building it up piece by piece), *gamma* and *palette*. + + .. method:: blank() + + Blank the image; that is, set the entire image to have no data, so that it + is displayed as transparent and the background of whatever window it is + displayed in shows through. + + .. method:: cget(option) + + Return the current value of the configuration option *option*. + + .. method:: copy(*, from_coords=None, zoom=None, subsample=None) + + Return a new :class:`PhotoImage` with a copy of this image. + + *from_coords* specifies a rectangular sub-region of the source image to be + copied. It must be a tuple or a list of 1 to 4 integers + ``(x1, y1, x2, y2)``. ``(x1, y1)`` and ``(x2, y2)`` specify diagonally + opposite corners of the rectangle. If *x2* and *y2* are not specified, + they default to the bottom-right corner of the source image. The pixels + copied include the left and top edges of the rectangle but not the bottom + or right edges. If *from_coords* is not given, the whole source image is + copied. + + If *zoom* or *subsample* are specified, the image is transformed as in the + :meth:`zoom` or :meth:`subsample` methods. The value must be a single + integer or a pair of integers. + + .. versionchanged:: 3.13 + Added the *from_coords*, *zoom* and *subsample* parameters. + + + .. method:: copy_replace(sourceImage, *, from_coords=None, to=None, \ + shrink=False, zoom=None, subsample=None, \ + compositingrule=None) + + Copy a region from *sourceImage* (which must be a :class:`PhotoImage`) + into this image, possibly with pixel zooming and/or subsampling. If no + options are specified, the whole of *sourceImage* is copied into this + image, starting at coordinates ``(0, 0)``. + + *from_coords* specifies a rectangular sub-region of the source image to be + copied, as in the :meth:`copy` method. + + *to* specifies a rectangular sub-region of the destination image to be + affected. It must be a tuple or a list of 1 to 4 integers + ``(x1, y1, x2, y2)``. If *x2* and *y2* are not specified, they default to + ``(x1, y1)`` plus the size of the source region (after subsampling and + zooming, if specified). If *x2* and *y2* are specified, the source region + is replicated if necessary to fill the destination region in a tiled + fashion. + + If *shrink* is true, the size of the destination image is reduced, if + necessary, so that the region being copied into is at the bottom-right + corner of the image. + + If *zoom* or *subsample* are specified, the image is transformed as in the + :meth:`zoom` or :meth:`subsample` methods. The value must be a single + integer or a pair of integers. + + *compositingrule* specifies how transparent pixels in the source image are + combined with the destination image. With ``'overlay'`` (the default), + the old contents of the destination image remain visible, as if the source + image were printed on a piece of transparent film and placed over the top + of the destination. With ``'set'``, the old contents of the destination + image are discarded and the source image is used as-is. + + .. versionadded:: 3.13 + + + .. method:: data(format=None, *, from_coords=None, background=None, \ + grayscale=False) + + Return the image data. + + *format* specifies the name of the image file format handler to use. If + it is not given, the data is returned as a tuple (one element per row) of + strings containing space-separated (one element per pixel/column) colors + in ``#RRGGBB`` format. + + *from_coords* specifies a rectangular region of the image to be returned. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. If + only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` to + the bottom-right corner of the image. If all four coordinates are given, + they specify diagonally opposite corners of the region, including + ``(x1, y1)`` and excluding ``(x2, y2)``. If *from_coords* is not given, + the whole image is returned. + + If *background* is specified, the data does not contain any transparency + information; in all transparent pixels the color is replaced by the + specified color. + + If *grayscale* is true, the data does not contain color information; all + pixel data is transformed into grayscale. + + .. versionadded:: 3.13 + + + .. method:: get(x, y) + + Return the color of the pixel at coordinates (*x*, *y*) as an + ``(r, g, b)`` tuple of three integers between 0 and 255, representing the + red, green and blue components respectively. + + .. method:: put(data, to=None) + + Set pixels of the image to the colors given in *data*, which must be a + string or a nested sequence of horizontal rows of pixel colors (for + example ``"{red green} {blue yellow}"``). + + *to* specifies the coordinates of the region of the image into which the + data are copied. It must be a tuple or a list of 2 or 4 integers + ``(x1, y1)`` or ``(x1, y1, x2, y2)`` giving the top-left corner, and + optionally the bottom-right corner, of the region. The default position + is ``(0, 0)``. + + .. method:: read(filename, format=None, *, from_coords=None, to=None, \ + shrink=False) + + Read image data from the file named *filename* into the image. + + *format* specifies the format of the image data in the file. + + *from_coords* specifies a rectangular sub-region of the image file data to + be copied to the destination image. It must be a tuple or a list of 1 to + 4 integers ``(x1, y1, x2, y2)``. If only *x1* and *y1* are specified, the + region extends from ``(x1, y1)`` to the bottom-right corner of the image + in the file. If all four coordinates are given, they specify diagonally + opposite corners of the region. If *from_coords* is not given, the whole + of the image in the file is read. + + *to* specifies the coordinates of the top-left corner of the region of the + image into which the data are read. The default is ``(0, 0)``. + + If *shrink* is true, the size of the image is reduced, if necessary, so + that the region into which the file data are read is at the bottom-right + corner of the image. + + .. versionadded:: 3.13 + + + .. method:: subsample(x, y='', *, from_coords=None) + + Return a new :class:`PhotoImage` based on this image but using only every + *x*-th pixel in the X direction and every *y*-th pixel in the Y direction. + If *y* is not given, it defaults to the same value as *x*. + + *from_coords* specifies a rectangular sub-region of the source image to be + copied, as in the :meth:`copy` method. + + .. versionchanged:: 3.13 + Added the *from_coords* parameter. + + + .. method:: transparency_get(x, y) + + Return ``True`` if the pixel at coordinates (*x*, *y*) is fully + transparent, ``False`` otherwise. + + .. versionadded:: 3.8 + + + .. method:: transparency_set(x, y, boolean) + + Make the pixel at coordinates (*x*, *y*) fully transparent if *boolean* is + true, fully opaque otherwise. + + .. versionadded:: 3.8 + + + .. method:: write(filename, format=None, from_coords=None, *, \ + background=None, grayscale=False) + + Write image data from the image to the file named *filename*. + + *format* specifies the name of the image file format handler to use. If + it is not given, the format is guessed from the file extension. + + *from_coords* specifies a rectangular region of the image to be written. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. If + only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` to + the bottom-right corner of the image. If all four coordinates are given, + they specify diagonally opposite corners of the region. If *from_coords* + is not given, the whole image is written. + + If *background* is specified, the data does not contain any transparency + information; in all transparent pixels the color is replaced by the + specified color. + + If *grayscale* is true, the data does not contain color information; all + pixel data is transformed into grayscale. + + .. versionchanged:: 3.13 + Added the *background* and *grayscale* parameters. + + + .. method:: zoom(x, y='', *, from_coords=None) + + Return a new :class:`PhotoImage` with this image magnified by a factor of + *x* in the X direction and *y* in the Y direction. If *y* is not given, + it defaults to the same value as *x*. + + *from_coords* specifies a rectangular sub-region of the source image to be + copied, as in the :meth:`copy` method. + + .. versionchanged:: 3.13 + Added the *from_coords* parameter. + + + +.. class:: BitmapImage(name=None, cnf={}, master=None, **kw) + + A two-color image (the Tk ``bitmap`` image type) created from an X11 bitmap. + Each pixel displays a foreground color, a background color, or nothing + (producing a transparent effect). Inherits from :class:`Image`. + + The configuration options are *data* or *file* (the source bitmap, given as + a string in X11 bitmap format or as the name of a file in that format), + *maskdata* or *maskfile* (the mask bitmap, in the same forms), and + *foreground* and *background* (the two colors). For pixels where the mask is + zero the image displays nothing; for other pixels it displays the foreground + color where the source is one and the background color where the source is + zero. If *background* is set to an empty string, the background pixels are + transparent. + + :class:`!BitmapImage` has no methods of its own beyond those inherited from + :class:`Image`. + + +Other classes +^^^^^^^^^^^^^ + +.. class:: Event() + + A container for the attributes of an event passed to a callback bound with + :meth:`Misc.bind`. An :class:`!Event` instance has the following attributes, + each corresponding to a field of the underlying Tk event; depending on the + event type, some attributes may be set to the string ``'??'`` to indicate + that they are not meaningful. See :ref:`bindings-and-events`. + + .. attribute:: serial + + The serial number of the event. + + .. attribute:: num + + The mouse button that was pressed or released (for button events). + + .. attribute:: focus + + Whether the window has the focus (for ``Enter`` and ``Leave`` events). + + .. attribute:: height + width + + The new height and width of the window (for ``Configure`` and ``Expose`` + events). + + .. attribute:: keycode + + The keycode of the key that was pressed or released. + + .. attribute:: state + + The state of the event, as a number (for most events) or a string (for + ``Visibility`` events). + + .. attribute:: time + + The timestamp of the event, in milliseconds. + + .. attribute:: x + y + + The pointer position relative to the widget, in pixels. + + .. attribute:: x_root + y_root + + The pointer position relative to the top-left corner of the screen, in + pixels. + + .. attribute:: char + + The character typed, as a string (for key events). + + .. attribute:: send_event + + ``True`` if the event was sent by another application. + + .. attribute:: keysym + + The symbolic name of the key that was pressed or released. + + .. attribute:: keysym_num + + The numeric value of :attr:`keysym`. + + .. attribute:: type + + The :class:`EventType` of the event. + + .. attribute:: widget + + The widget on which the event occurred. + + .. attribute:: delta + + The amount the mouse wheel was rotated (for ``MouseWheel`` events). + + .. attribute:: user_data + + The data string of a virtual event, as passed to the *data* option of + :meth:`Misc.event_generate`. It is ``'??'`` for non-virtual events. + + .. versionadded:: 3.15 + + .. attribute:: detail + + A fixed detail string for ``Enter``, ``Leave``, ``FocusIn``, + ``FocusOut`` and ``ConfigureRequest`` events (see the Tcl/Tk + documentation). It is ``'??'`` for other events. + + .. versionadded:: 3.15 + + +.. class:: EventType(*values) + + An :class:`enum.StrEnum` enumerating the Tk event types, used as the value of + :attr:`Event.type`. Its members include, among others, ``KeyPress``, + ``KeyRelease``, ``ButtonPress``, ``ButtonRelease``, ``Motion``, ``Enter``, + ``Leave``, ``FocusIn``, ``FocusOut``, ``Configure``, ``Map``, ``Unmap``, + ``Expose``, ``Destroy`` and ``MouseWheel``. + + .. versionadded:: 3.6 + + + +.. class:: CallWrapper(func, subst, widget) + + Internal helper that wraps a Python callback so that it can be invoked from + Tcl. *func* is the Python function, *subst* is an optional function that + pre-processes the Tcl arguments, and *widget* is the widget used for error + reporting. Instances are created automatically by :meth:`Misc.register`; this + class is not normally used directly. + + +Module-level functions +^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: NoDefaultRoot() + + Inhibit the creation of an implicit default root window. Afterwards + :mod:`!tkinter` no longer creates a shared default root automatically, and + operations that rely on one --- such as constructing a widget without an + explicit *master* --- raise a :exc:`RuntimeError`. Call this early in larger + applications to make the root window explicit. + +.. function:: mainloop(n=0) + + Run the Tk main event loop on the default root window until all windows are + destroyed. Equivalent to calling :meth:`Misc.mainloop` on the default root. + +.. function:: getboolean(s) + + Convert the Tcl boolean string *s* (one of ``'1'``, ``'true'``, ``'yes'``, + ``'on'`` and similar, or their false counterparts) to a Python :class:`bool`. + Raise :exc:`TclError` for an invalid value. + +.. function:: getdouble(s) + + Convert *s* to a floating-point number. This is the built-in :class:`float`. + +.. function:: getint(s) + + Convert *s* to an integer. This is the built-in :class:`int`. + +.. function:: image_names() + + Return the names of all existing images in the default root's interpreter. + +.. function:: image_types() + + Return the available image types (such as ``'photo'`` and ``'bitmap'``) in + the default root's interpreter. + +Constants +^^^^^^^^^ + +The following symbolic constants are available in both the :mod:`!tkinter` +and :mod:`tkinter.constants` namespaces. + +.. data:: TRUE + YES + ON + + Truthy values, all equal to the integer ``1``. + +.. data:: FALSE + NO + OFF + + Falsy values, all equal to the integer ``0``. + +.. data:: N + S + E + W + NE + NW + SE + SW + NS + EW + NSEW + CENTER + + Compass directions (``'n'``, ``'s'``, ``'e'``, ``'w'`` and the diagonals and + edges) plus ``CENTER`` (``'center'``), used as values for the *anchor* and + *sticky* options and by methods such as :meth:`Misc.grid_anchor`. + +.. data:: LEFT + RIGHT + TOP + BOTTOM + + Sides for the *side* option of the packer (see :meth:`Pack.pack_configure`). + +.. data:: X + Y + BOTH + NONE + + Values for the *fill* option of the packer: ``'x'``, ``'y'``, ``'both'`` or + ``'none'``. + +.. data:: RAISED + SUNKEN + FLAT + RIDGE + GROOVE + SOLID + + Values for the *relief* option, which controls a widget's 3-D border. + +.. data:: HORIZONTAL + VERTICAL + + Values for the *orient* option of widgets such as :class:`Scale`, + :class:`Scrollbar` and :class:`PanedWindow`. + +.. data:: CHAR + WORD + + Values for the *wrap* option of the :class:`Text` widget, selecting line + wrapping on character or word boundaries. + +.. data:: BASELINE + + The text-alignment value ``'baseline'``. + +.. data:: INSIDE + OUTSIDE + + Values for the *bordermode* option of the placer (see + :meth:`Place.place_configure`). + +.. data:: INSERT + CURRENT + END + ANCHOR + SEL + SEL_FIRST + SEL_LAST + + Symbolic indices used by the :class:`Text`, :class:`Entry`, :class:`Listbox` + and :class:`Canvas` widgets, such as ``'insert'`` (the insertion cursor), + ``'current'``, ``'end'``, ``'anchor'`` and the bounds of the selection + (``'sel.first'`` and ``'sel.last'``). + +.. data:: ALL + + The special tag ``'all'``, which matches every item of a :class:`Canvas` or + every character of a :class:`Text` (for example ``canvas.delete(ALL)``). + +.. data:: NORMAL + DISABLED + ACTIVE + HIDDEN + + Values for the *state* option of various widgets and items. + +.. data:: CASCADE + CHECKBUTTON + COMMAND + RADIOBUTTON + SEPARATOR + + Menu entry types, used as the *itemType* argument of :meth:`Menu.add` and + :meth:`Menu.insert`. + +.. data:: SINGLE + BROWSE + MULTIPLE + EXTENDED + + Values for the *selectmode* option of the :class:`Listbox` widget. + +.. data:: PIESLICE + CHORD + ARC + + Values for the *style* option of :class:`Canvas` arc items. + +.. data:: BUTT + PROJECTING + ROUND + BEVEL + MITER + + Values for the *capstyle* (``'butt'``, ``'projecting'``, ``'round'``) and + *joinstyle* (``'round'``, ``'bevel'``, ``'miter'``) options of + :class:`Canvas` line items. + +.. data:: FIRST + LAST + + Values for the *arrow* option of :class:`Canvas` line items, indicating which + ends have arrowheads. + +.. data:: MOVETO + SCROLL + + The first argument passed by a :class:`Scrollbar` to the :meth:`XView.xview` + or :meth:`YView.yview` method of the scrolled widget. + +.. data:: UNITS + PAGES + + Values for the *what* argument of :meth:`XView.xview_scroll` and + :meth:`YView.yview_scroll`. + +.. data:: UNDERLINE + NUMERIC + DOTBOX + + Other option values: ``'underline'``, ``'numeric'`` and ``'dotbox'``. diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst index eb30b9c3eacc1b6..f206bdb59d6583e 100644 --- a/Doc/library/tkinter.scrolledtext.rst +++ b/Doc/library/tkinter.scrolledtext.rst @@ -14,8 +14,8 @@ the "right thing." Using the :class:`ScrolledText` class is a lot easier than 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 -from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to +methods of the :class:`Pack`, :class:`Grid` and :class:`Place` geometry managers +are acquired from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to be used directly to achieve most normal geometry management behavior. Should more specific control be necessary, the following attributes are diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index e1383e189a31a2b..ce07a387db16840 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -19,6 +19,8 @@ The basic idea for :mod:`!tkinter.ttk` is to separate, to the extent possible, the code implementing a widget's behavior from the code implementing its appearance. +.. versionadded:: 3.1 + .. seealso:: @@ -116,7 +118,7 @@ All the :mod:`ttk` Widgets accept the following options: +-----------+--------------------------------------------------------------+ | cursor | Specifies the mouse cursor to be used for the widget. If set | | | to the empty string (the default), the cursor is inherited | -| | for the parent widget. | +| | from the parent widget. | +-----------+--------------------------------------------------------------+ | takefocus | Determines whether the window accepts the focus during | | | keyboard traversal. 0, 1 or an empty string is returned. | @@ -144,8 +146,8 @@ scrollbar. +================+=========================================================+ | xscrollcommand | Used to communicate with horizontal scrollbars. | | | | -| | When the view in the widget's window change, the widget | -| | will generate a Tcl command based on the scrollcommand. | +| | When the view in the widget's window changes, the widget| +| | calls the *xscrollcommand* callback. | | | | | | Usually this option consists of the method | | | :meth:`Scrollbar.set` of some scrollbar. This will cause| @@ -315,7 +317,7 @@ This widget accepts the following specific options: | Option | Description | +=================+========================================================+ | exportselection | Boolean value. If set, the widget selection is linked | -| | to the Window Manager selection (which can be returned | +| | to the X selection (which can be returned | | | by invoking Misc.selection_get, for example). | +-----------------+--------------------------------------------------------+ | justify | Specifies how the text is aligned within the widget. | @@ -329,7 +331,7 @@ This widget accepts the following specific options: +-----------------+--------------------------------------------------------+ | state | One of "normal", "readonly", or "disabled". In the | | | "readonly" state, the value may not be edited directly,| -| | and the user can only selection of the values from the | +| | and the user can only select one of the values from the| | | dropdown list. In the "normal" state, the text field is| | | directly editable. In the "disabled" state, no | | | interaction is possible. | @@ -347,6 +349,11 @@ This widget accepts the following specific options: | | widget's font. | +-----------------+--------------------------------------------------------+ +.. note:: + + Tk 9.1 added the *locale* option, which selects the locale used to determine + word and character boundaries within the text (``"C"`` by default). + Virtual events ^^^^^^^^^^^^^^ @@ -448,6 +455,8 @@ ttk.Spinbox .. class:: Spinbox + .. versionadded:: 3.8 + .. method:: get() Returns the current value of the spinbox. @@ -458,6 +467,7 @@ ttk.Spinbox Sets the value of the spinbox to *value*. + Notebook -------- @@ -626,7 +636,7 @@ ttk.Notebook .. method:: tabs() - Returns a list of windows managed by the notebook. + Returns a tuple of windows managed by the notebook. .. method:: enable_traversal() @@ -643,7 +653,7 @@ ttk.Notebook Multiple notebooks in a single toplevel may be enabled for traversal, including nested notebooks. However, notebook traversal only works - properly if all panes have the notebook they are in as master. + properly if all panes are direct children of the notebook. Progressbar @@ -844,6 +854,15 @@ This widget accepts the following specific options: | | even if show="tree" is not specified. | +----------------+--------------------------------------------------------+ +.. note:: + + Tk 9.0 added several :class:`Treeview` features. The *selectmode* option + gained the values ``"single"`` and ``"multiple"``; the new widget options + *selecttype* (``"item"`` or ``"cell"`` selection), *striped* (zebra-striped + rows), and *titlecolumns* / *titleitems* (columns or rows frozen against + scrolling) were introduced; and items gained a *hidden* option. Tk 9.1 + added the *rowheight* and *headingheight* options. + Item Options ^^^^^^^^^^^^ @@ -959,14 +978,14 @@ ttk.Treeview .. method:: get_children(item=None) - Returns the list of children belonging to *item*. + Returns a tuple of children belonging to *item*. If *item* is not specified, returns root children. .. method:: set_children(item, *newchildren) - Replaces *item*'s child with *newchildren*. + Replaces *item*'s children with *newchildren*. Children present in *item* that are not present in *newchildren* are detached from the tree. No items in *newchildren* may be an ancestor of @@ -1020,7 +1039,8 @@ ttk.Treeview .. method:: exists(item) - Returns ``True`` if the specified *item* is present in the tree. + Returns ``True`` if the specified *item* is present in the tree, + ``False`` otherwise. .. method:: focus(item=None) @@ -1066,7 +1086,7 @@ ttk.Treeview .. method:: identify_column(x) - Returns the data column identifier of the cell at position *x*. + Returns the display column identifier of the cell at position *x*. The tree column has ID #0. @@ -1239,9 +1259,9 @@ ttk.Treeview .. method:: tag_has(tagname, item=None) - If *item* is specified, returns 1 or 0 depending on whether the specified - *item* has the given *tagname*. Otherwise, returns a list of all items - that have the specified tag. + If *item* is specified, returns ``True`` if the specified *item* has the + given *tagname* and ``False`` otherwise. Otherwise, returns a tuple of all + items that have the specified tag. Availability: Tk 8.6 @@ -1335,6 +1355,12 @@ option. If you don't know the class name of a widget, use the method 'red')]`` in the foreground option, for example, the result would be a blue foreground when the widget were in active or pressed states. + When called to query the map (without specifying values to set), it + returns a dictionary mapping each option to its list of statespecs. + + .. versionchanged:: 3.10 + The value returned when querying the map was corrected. + .. method:: lookup(style, option, state=None, default=None) @@ -1498,12 +1524,12 @@ option. If you don't know the class name of a widget, use the method .. method:: element_names() - Returns the list of elements defined in the current theme. + Returns a tuple of elements defined in the current theme. .. method:: element_options(elementname) - Returns the list of *elementname*'s options. + Returns a tuple of *elementname*'s options. .. method:: theme_create(themename, parent=None, settings=None) @@ -1555,7 +1581,7 @@ option. If you don't know the class name of a widget, use the method .. method:: theme_names() - Returns a list of all known themes. + Returns a tuple of all known themes. .. method:: theme_use(themename=None) @@ -1594,3 +1620,253 @@ The valid options/values are: the layout name, and the other is a `Layout`_. .. _Layout: `Layouts`_ + + +Additional widgets +------------------ + +The following themed widgets complete the :mod:`tkinter.ttk` widget set. Each +is the themed counterpart of the like-named classic :mod:`tkinter` widget and +inherits the common methods of :class:`Widget`. + +.. class:: Button(master=None, **kw) + + Ttk :class:`Button` widget, displays a textual label and/or image, and + evaluates a command when pressed. It is the themed counterpart of + :class:`tkinter.Button` and inherits the common widget methods from + :class:`Widget`. + + .. method:: invoke() + + Invoke the command associated with the button and return its result. + + +.. class:: Checkbutton(master=None, **kw) + + Ttk :class:`Checkbutton` widget, used to control a Boolean variable that is + toggled on and off. It is the themed counterpart of + :class:`tkinter.Checkbutton` and inherits the common widget methods from + :class:`Widget`. + + .. method:: invoke() + + Toggle the button between its selected and deselected states, invoke the + command associated with the button, and return its result. + + +.. class:: Entry(master=None, widget=None, **kw) + + Ttk :class:`Entry` widget, displays a one-line text string and allows the + user to edit it. It is the themed counterpart of :class:`tkinter.Entry` and + inherits the common widget methods from :class:`Widget` as well as the + editing methods from :class:`tkinter.Entry`. + + .. method:: bbox(index) + + Return a tuple ``(x, y, width, height)`` giving the bounding box of the + character at the given *index*. + + .. method:: identify(x, y) + + Return the name of the element under the point given by *x* and *y*, or + the empty string if no element is present at that location. + + .. method:: validate() + + Force validation of the entry and return ``True`` if validation succeeded, + and ``False`` otherwise. + + +.. class:: Frame(master=None, **kw) + + Ttk :class:`Frame` widget, a container used to group and lay out other + widgets. It is the themed counterpart of :class:`tkinter.Frame` and inherits + the common widget methods from :class:`Widget`. + + +.. class:: Label(master=None, **kw) + + Ttk :class:`Label` widget, displays a textual label and/or image. It is the + themed counterpart of :class:`tkinter.Label` and inherits the common widget + methods from :class:`Widget`. + + +.. class:: Labelframe(master=None, **kw) + + Ttk :class:`Labelframe` widget, a container that draws a border and a title + label around its contents. It is the themed counterpart of + :class:`tkinter.LabelFrame` and inherits the common widget methods from + :class:`Widget`. + + +.. class:: Menubutton(master=None, **kw) + + Ttk :class:`Menubutton` widget, displays a textual label and/or image, and + pops up a menu when pressed. It is the themed counterpart of + :class:`tkinter.Menubutton` and inherits the common widget methods from + :class:`Widget`. + + +.. class:: OptionMenu(master, variable, default=None, *values, **kwargs) + + Ttk :class:`OptionMenu` widget, a :class:`Menubutton` that pops up a menu of + mutually exclusive choices. *variable* is the variable that tracks the + currently selected value, *default* is the value to set initially, and + *values* are the entries to 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. + + .. method:: set_menu(default=None, *values) + + Replace the entries of the menu with *values*. If *default* is given, + also set it as the current value of the *variable*. + + .. method:: destroy() + + Destroy this widget and its associated menu. + + .. versionchanged:: 3.14 + Added support for the *name* keyword argument. + + + +.. class:: Panedwindow(master=None, **kw) + + Ttk :class:`Panedwindow` widget, displays a number of subwindows stacked + either vertically or horizontally. The user may adjust the relative sizes of + the subwindows by dragging the sash between panes. It is the themed + counterpart of :class:`tkinter.PanedWindow` and inherits the common widget + methods from :class:`Widget`, as well as the :meth:`!add` and :meth:`!panes` + methods from :class:`tkinter.PanedWindow`. + + .. method:: insert(pos, child, **kw) + + Insert a pane containing *child* at the position *pos*. *pos* is either + the string ``'end'``, an integer index, or the name of a managed + subwindow. If *child* is already managed by the paned window, move it to + the specified position. Any keyword arguments set pane options. + + .. method:: forget(child) + + Remove *child*, which may be either an integer index or the name of a + managed subwindow, from the panes. + + .. method:: pane(pane, option=None, **kw) + + Query or modify the options of the specified *pane*, where *pane* is + either an integer index or the name of a managed subwindow. If no + arguments are given, return a dictionary of the pane option values. If + *option* is specified, return the value of that option. Otherwise, set + the options given as keyword arguments to their corresponding values. + + .. method:: sashpos(index, newpos=None) + + If *newpos* is specified, set the position of sash number *index* and + return its new position. This may adjust the positions of adjacent sashes + to ensure that positions are monotonically increasing; positions are also + constrained to be between 0 and the total size of the widget. If *newpos* + is omitted, return the current position of the sash. + + +.. class:: Radiobutton(master=None, **kw) + + Ttk :class:`Radiobutton` widget, used as part of a group to control a single + shared variable by selecting one of several mutually exclusive values. It is + the themed counterpart of :class:`tkinter.Radiobutton` and inherits the + common widget methods from :class:`Widget`. + + .. method:: invoke() + + Set the option variable to the button's value, select the button, invoke + the command associated with the button, and return its result. + + +.. class:: Scale(master=None, **kw) + + Ttk :class:`Scale` widget, displays a slider that lets the user select a + numeric value from a range by moving the slider along a trough. It is the + themed counterpart of :class:`tkinter.Scale` and inherits the common widget + methods from :class:`Widget`. + + .. method:: configure(cnf=None, **kw) + + Modify or query the widget options, like :meth:`Widget.configure`. In + addition, this method clips the ``from`` and ``to`` values so that the + current value stays within the range defined by them. + + .. versionchanged:: 3.9 + Now returns the configuration value, like :meth:`Widget.configure`. + + + .. method:: get(x=None, y=None) + + Return the current value of the scale. If *x* and *y* are given, return + the value corresponding to the pixel coordinate *x*, *y* instead. + + +.. class:: Scrollbar(master=None, **kw) + + Ttk :class:`Scrollbar` widget, controls the viewport of an associated + scrollable widget such as a :class:`Treeview`, :class:`Entry` or + :class:`tkinter.Text`. It is the themed counterpart of + :class:`tkinter.Scrollbar` and inherits the common widget methods from + :class:`Widget`, as well as the :meth:`!set` and :meth:`!get` methods from + :class:`tkinter.Scrollbar`. + + +.. class:: Separator(master=None, **kw) + + Ttk :class:`Separator` widget, displays a horizontal or vertical separator + line. It has no direct counterpart in :mod:`tkinter` and inherits the common + widget methods from :class:`Widget`. + + +.. class:: Sizegrip(master=None, **kw) + + Ttk :class:`Sizegrip` widget, displays a grip that allows the user to resize + the containing toplevel window by pressing and dragging the grip, typically + placed in the bottom-right corner. It has no direct counterpart in + :mod:`tkinter` and inherits the common widget methods from :class:`Widget`. + + +.. class:: LabeledScale(master=None, variable=None, from_=0, to=10, **kw) + + A :class:`Frame` containing a :class:`Scale` and a :class:`Label` that shows + the scale's current value. *variable* is the :class:`IntVar` tracked by the + scale (one is created if it is not given), and *from_* and *to* define the + range of the scale. + + .. method:: destroy() + + Destroy this widget and remove the trace callback registered on the + associated variable. + + +.. class:: LabelFrame(master=None, **kw) + + Alias of :class:`Labelframe`, kept for naming compatibility with + :class:`tkinter.LabelFrame`. + + +.. class:: PanedWindow(master=None, **kw) + + Alias of :class:`Panedwindow`, kept for naming compatibility with + :class:`tkinter.PanedWindow`. + + +Utility functions +----------------- + +.. function:: tclobjs_to_py(adict) + + Return a copy of the dictionary *adict* in which any Tcl object values have + been converted to their Python equivalents. This is a helper used + internally to post-process the option dictionaries returned by Tk. + +.. function:: setup_master(master=None) + + Return a master widget to use as the parent of a new widget. If *master* is + ``None``, the default root window is used, creating it if necessary. This is + a helper used internally when constructing widgets. diff --git a/Misc/NEWS.d/next/Documentation/2026-06-17-12-00-00.gh-issue-59551.__bOgH.rst b/Misc/NEWS.d/next/Documentation/2026-06-17-12-00-00.gh-issue-59551.__bOgH.rst new file mode 100644 index 000000000000000..787b95dbf236279 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-06-17-12-00-00.gh-issue-59551.__bOgH.rst @@ -0,0 +1,4 @@ +Greatly expand the :mod:`tkinter` documentation to cover the full public API +of the package and its submodules. The descriptions are oriented towards +Python rather than Tcl/Tk, with corrected return types and +``versionadded``/``versionchanged`` information. From 9d7c91e10de085f1f10f689c01c13c634f0d6a3d Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 10:06:39 +0300 Subject: [PATCH 02/18] gh-59551: Do not document tkinter aliases separately Merge alias methods into a single directive with stacked signatures instead of documenting each spelling separately: Font.config/configure, Variable.set/initialize, Variable.trace_variable/trace, and BooleanVar.set/initialize. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.font.rst | 8 ++------ Doc/library/tkinter.messagebox.rst | 6 +++--- Doc/library/tkinter.rst | 22 ++++++---------------- 3 files changed, 11 insertions(+), 25 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index c11b272c17dd510..0c05f46f5094fa9 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -59,15 +59,11 @@ The different font weights and slants are: Retrieve an attribute of the font. - .. method:: config(**options) - - Modify attributes of the font. - .. method:: configure(**options) + config(**options) Modify one or more attributes of the font. With no arguments, return a - dictionary of the current attributes. :meth:`config` is an alias of - :meth:`configure`. + dictionary of the current attributes. .. method:: copy() diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst index 92eebad039e8968..0cc2f6b997de9ee 100644 --- a/Doc/library/tkinter.messagebox.rst +++ b/Doc/library/tkinter.messagebox.rst @@ -79,19 +79,19 @@ include but are not limited to: .. function:: showinfo(title=None, message=None, **options) Creates and displays an information message box with the specified title - and message. Return the symbolic name :data:`OK` (the string ``'ok'``). + and message. **Warning message boxes** .. function:: showwarning(title=None, message=None, **options) Creates and displays a warning message box with the specified title - and message. Return the symbolic name :data:`OK` (the string ``'ok'``). + and message. .. function:: showerror(title=None, message=None, **options) Creates and displays an error message box with the specified title - and message. Return the symbolic name :data:`OK` (the string ``'ok'``). + and message. **Question message boxes** diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index fde0e909a904171..85394b49c66a0a5 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -4626,15 +4626,12 @@ Variable classes appropriate Python type. .. method:: set(value) + initialize(value) Set the variable to *value*. - .. method:: initialize(value) - - Set the initial value of the variable. This is an alias for - :meth:`set`. - .. versionadded:: 3.3 + The *initialize* spelling. .. method:: trace_add(mode, callback) @@ -4668,6 +4665,7 @@ Variable classes .. versionadded:: 3.6 .. method:: trace_variable(mode, callback) + trace(mode, callback) Register *callback* to be called when the variable is accessed according to *mode*. *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for @@ -4678,13 +4676,6 @@ Variable classes Use :meth:`trace_add` instead. This method wraps a Tcl feature that was removed in Tcl 9.0. - .. method:: trace(mode, callback) - - An alias for :meth:`trace_variable`. - - .. deprecated:: 3.6 - Use :meth:`trace_add` instead. - .. method:: trace_vdelete(mode, cbname) Remove the trace callback named *cbname* registered for *mode* with @@ -4745,13 +4736,12 @@ Variable classes :exc:`ValueError` if the value cannot be interpreted as a boolean. .. method:: set(value) + initialize(value) Set the variable to *value*, converting it to a boolean. - .. method:: initialize(value) - - Set the initial value of the variable. This is an alias for - :meth:`set`. + .. versionadded:: 3.3 + The *initialize* spelling. Image classes From 77f3ae0d883440453a16672444cd0521ee98e996 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 11:05:14 +0300 Subject: [PATCH 03/18] gh-59551: Document tkinter aliases as hidden :no-typesetting: anchors Document each alias as a :no-typesetting: directive placed just before its main definition, so the alias keeps an index entry and a reference anchor without rendering a duplicate signature. Each alias is named in the prose of the main method, with the alias spelling as a live link. The common geometry-manager spellings pack(), place() and grid() are kept as visible stacked signatures rather than hidden. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.font.rst | 6 +- Doc/library/tkinter.rst | 592 ++++++++++++++++++++++++----------- Doc/library/tkinter.ttk.rst | 10 +- 3 files changed, 411 insertions(+), 197 deletions(-) diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index 0c05f46f5094fa9..c1b2f8a96e569cf 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -59,12 +59,16 @@ The different font weights and slants are: Retrieve an attribute of the font. + .. method:: config(**options) + :no-typesetting: + .. method:: configure(**options) - config(**options) Modify one or more attributes of the font. With no arguments, return a dictionary of the current attributes. + :meth:`config` is an alias of :meth:`!configure`. + .. method:: copy() Return new instance of the current font. diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 85394b49c66a0a5..214dcf3ed4a601e 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -1128,8 +1128,10 @@ Base and mixin classes widget, as a string. The expression ``widget[key]`` is equivalent and may be used instead. + .. method:: config(cnf=None, **kw) + :no-typesetting: + .. method:: configure(cnf=None, **kw) - config(cnf=None, **kw) Query or modify the configuration options of the widget. With no arguments, return a dictionary mapping every available option name to a @@ -1140,7 +1142,7 @@ Base and mixin classes corresponding value; the expression ``widget[key] = value`` sets a single option in the same way. - ``config`` is an alias of :meth:`!configure`. + :meth:`config` is an alias of :meth:`!configure`. .. method:: keys() @@ -1212,14 +1214,16 @@ Base and mixin classes Destroy this widget and all of its descendant widgets, and delete the Tcl commands associated with them. + .. method:: lift(aboveThis=None) + :no-typesetting: + .. method:: tkraise(aboveThis=None) - lift(aboveThis=None) Raise this widget in the stacking order so that it is drawn on top of its siblings. If *aboveThis* is given, the widget is moved to be just above it in the stacking order instead. - ``lift`` is an alias of :meth:`!tkraise`. + :meth:`lift` is an alias of :meth:`!tkraise`. .. method:: lower(belowThis=None) @@ -1236,8 +1240,10 @@ Base and mixin classes Return the available image types, such as ``'photo'`` and ``'bitmap'``. + .. method:: anchor(anchor=None) + :no-typesetting: + .. method:: grid_anchor(anchor=None) - anchor(anchor=None) Set the anchor that controls where the grid is placed inside this container when the container is larger than the grid and no row or column @@ -1245,12 +1251,14 @@ Base and mixin classes as ``'nw'`` (the default) or ``'center'``. Called with no argument, this method has no effect. - ``anchor`` is an alias of :meth:`!grid_anchor`. + :meth:`anchor` is an alias of :meth:`!grid_anchor`. .. versionadded:: 3.3 + .. method:: bbox(column=None, row=None, col2=None, row2=None) + :no-typesetting: + .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) - bbox(column=None, row=None, col2=None, row2=None) Return the bounding box, in pixels, of a region of the grid laid out in this container, as a 4-tuple ``(xoffset, yoffset, width, height)``. With @@ -1259,10 +1267,12 @@ Base and mixin classes that cell; if *col2* and *row2* are also given, it spans from the cell (*column*, *row*) to the cell (*col2*, *row2*). - ``bbox`` is an alias of :meth:`!grid_bbox`. + :meth:`bbox` is an alias of :meth:`!grid_bbox`. + + .. method:: columnconfigure(index, cnf={}, **kw) + :no-typesetting: .. method:: grid_columnconfigure(index, cnf={}, **kw) - columnconfigure(index, cnf={}, **kw) Query or set the properties of the column (or columns) *index* of the grid managed by this container. The valid options are *minsize* (the column's @@ -1272,16 +1282,18 @@ Base and mixin classes the column). With a single option name, return that option's value; with no options, return a dictionary of all of them. - ``columnconfigure`` is an alias of :meth:`!grid_columnconfigure`. + :meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. + + .. method:: rowconfigure(index, cnf={}, **kw) + :no-typesetting: .. method:: grid_rowconfigure(index, cnf={}, **kw) - rowconfigure(index, cnf={}, **kw) Query or set the properties of the row (or rows) *index* of the grid managed by this container. The valid options are the same as for :meth:`grid_columnconfigure`, applied to a row instead of a column. - ``rowconfigure`` is an alias of :meth:`!grid_rowconfigure`. + :meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. .. method:: grid_location(x, y) @@ -1298,13 +1310,15 @@ Base and mixin classes it is false, its size is left under your control. Called with no argument, return the current setting as a boolean. + .. method:: size() + :no-typesetting: + .. method:: grid_size() - size() Return the size of the grid managed by this container as a ``(columns, rows)`` tuple. - ``size`` is an alias of :meth:`!grid_size`. + :meth:`size` is an alias of :meth:`!grid_size`. .. method:: grid_slaves(row=None, column=None) @@ -1320,8 +1334,10 @@ Base and mixin classes .. versionadded:: 3.15 + .. method:: propagate(flag=['_noarg_']) + :no-typesetting: + .. method:: pack_propagate(flag=['_noarg_']) - propagate(flag=['_noarg_']) Enable or disable geometry propagation for this container when it manages its children with the pack geometry manager. When *flag* is true, the @@ -1329,23 +1345,27 @@ Base and mixin classes it is false, its size is left under your control. Called with no argument, return the current setting as a boolean. - ``propagate`` is an alias of :meth:`!pack_propagate`. + :meth:`propagate` is an alias of :meth:`!pack_propagate`. + + .. method:: slaves() + :no-typesetting: .. method:: pack_slaves() - slaves() Return a list of the child widgets managed by this container with the pack geometry manager, in packing order. - ``slaves`` is an alias of :meth:`!pack_slaves`. + :meth:`slaves` is an alias of :meth:`!pack_slaves`. + + .. method:: content() + :no-typesetting: .. method:: pack_content() - content() Same as :meth:`pack_slaves`: return the child widgets managed by this container with the pack geometry manager, in packing order. - ``content`` is an alias of :meth:`!pack_content`. + :meth:`content` is an alias of :meth:`!pack_content`. .. versionadded:: 3.15 @@ -1550,15 +1570,17 @@ Base and mixin classes This updates the display of windows, for example after geometry changes, but does not process events caused by the user. + .. method:: waitvar(name='PY_VAR') + :no-typesetting: + .. method:: wait_variable(name='PY_VAR') - waitvar(name='PY_VAR') Wait until the Tcl variable *name* is modified, continuing to process events in the meantime so that the application stays responsive. *name* is usually a :class:`Variable` instance, such as an :class:`IntVar` or :class:`StringVar`. - ``waitvar`` is an alias of :meth:`!wait_variable`. + :meth:`waitvar` is an alias of :meth:`!wait_variable`. .. method:: wait_window(window=None) @@ -1572,14 +1594,16 @@ Base and mixin classes first appears on the screen, continuing to process events in the meantime. If *window* is omitted, this widget is used. This is typically used to wait for a newly created window to become visible before acting on it. + .. method:: focus_set() + :no-typesetting: + .. method:: focus() - focus_set() Direct the keyboard input focus for this widget's display to this widget. If the application does not currently have the input focus on this widget's display, the widget is remembered as the focus window for its top level, and the focus will be redirected to it the next time the - window manager gives the focus to the top level. ``focus`` is an alias + window manager gives the focus to the top level. :meth:`focus` is an alias of :meth:`!focus_set`. .. method:: focus_force() @@ -1812,10 +1836,16 @@ Base and mixin classes A true *boolean* value enables strict Motif compliance (for example, no color change when the mouse passes over a slider). Return the resulting setting. + .. method:: busy(**kw) + :no-typesetting: + + .. method:: busy_hold(**kw) + :no-typesetting: + + .. method:: tk_busy(**kw) + :no-typesetting: + .. method:: tk_busy_hold(**kw) - busy(**kw) - busy_hold(**kw) - tk_busy(**kw) Make this widget appear busy. A transparent window is placed in front of the widget, so that it and all of its descendants in the widget hierarchy @@ -1827,15 +1857,22 @@ Base and mixin classes displayed while the widget is busy; it may have any of the values accepted by :meth:`!configure`. - These are equivalent spellings of the same method. + :meth:`busy_hold`, :meth:`busy` and :meth:`tk_busy` are aliases of + :meth:`!tk_busy_hold`. .. versionadded:: 3.13 + .. method:: busy_configure(cnf=None, **kw) + :no-typesetting: + + .. method:: busy_config(cnf=None, **kw) + :no-typesetting: + + .. method:: tk_busy_config(cnf=None, **kw) + :no-typesetting: + .. method:: tk_busy_configure(cnf=None, **kw) - busy_configure(cnf=None, **kw) - busy_config(cnf=None, **kw) - tk_busy_config(cnf=None, **kw) Query or modify the configuration options of the busy window. The widget must have been previously made busy by :meth:`tk_busy_hold`. With no @@ -1851,53 +1888,62 @@ Base and mixin classes w.option_add('*frame.busyCursor', 'gumby') w.option_add('*Frame.BusyCursor', 'gumby') - These are equivalent spellings of the same method. + :meth:`busy_configure`, :meth:`busy_config` and :meth:`tk_busy_config` are aliases of + :meth:`!tk_busy_configure`. .. versionadded:: 3.13 + .. method:: busy_cget(option) + :no-typesetting: + .. method:: tk_busy_cget(option) - busy_cget(option) Return the current value of the busy configuration *option*. The widget must have been previously made busy by :meth:`tk_busy_hold`, and *option* may have any of the values accepted by that method. - These are equivalent spellings of the same method. + :meth:`busy_cget` is an alias of :meth:`!tk_busy_cget`. .. versionadded:: 3.13 + .. method:: busy_forget() + :no-typesetting: + .. method:: tk_busy_forget() - busy_forget() Make this widget no longer busy, releasing the resources (including the transparent window) allocated when it was made busy. User events will again be received by the widget. These resources are also released when the widget is destroyed. - These are equivalent spellings of the same method. + :meth:`busy_forget` is an alias of :meth:`!tk_busy_forget`. .. versionadded:: 3.13 + .. method:: busy_status() + :no-typesetting: + .. method:: tk_busy_status() - busy_status() Return ``True`` if the widget is currently busy, ``False`` otherwise. - These are equivalent spellings of the same method. + :meth:`busy_status` is an alias of :meth:`!tk_busy_status`. .. versionadded:: 3.13 + .. method:: busy_current(pattern=None) + :no-typesetting: + .. method:: tk_busy_current(pattern=None) - busy_current(pattern=None) Return a list of widgets that are currently busy. If *pattern* is given, only busy widgets whose path names match the pattern are returned. - These are equivalent spellings of the same method. + :meth:`busy_current` is an alias of :meth:`!tk_busy_current`. .. versionadded:: 3.13 @@ -2186,10 +2232,12 @@ Base and mixin classes manager protocols. It is mixed into :class:`Tk` and :class:`Toplevel`, so its methods are available on every top-level window. Each method has two equivalent spellings: a short name and a ``wm_``-prefixed name (for example, - :meth:`title` and :meth:`!wm_title`). + :meth:`title` and :meth:`wm_title`). + + .. method:: wm_aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) + :no-typesetting: .. method:: aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) - wm_aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) Constrain the aspect ratio (the ratio of width to height) of the window. If all four arguments are given, the window manager keeps the ratio @@ -2197,10 +2245,12 @@ Base and mixin classes 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. - The ``wm_``-prefixed spelling (e.g. ``wm_aspect``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_aspect`) is an equivalent alias. + + .. method:: wm_attributes(*args, return_python_dict=False, **kwargs) + :no-typesetting: .. method:: attributes(*args, return_python_dict=False, **kwargs) - wm_attributes(*args, return_python_dict=False, **kwargs) Query or set platform-specific attributes of the window. With no arguments, return the platform-specific flags and their values; pass @@ -2212,7 +2262,7 @@ Base and mixin classes ``-fullscreen`` and ``-topmost``, while Windows, macOS and X11 each add further options. On X11 changes are applied asynchronously, so a queried value may not yet reflect the most recent request. - The ``wm_``-prefixed spelling (e.g. ``wm_attributes``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_attributes`) is an equivalent alias. .. versionchanged:: 3.13 @@ -2221,17 +2271,21 @@ Base and mixin classes *return_python_dict* parameter was added. + .. method:: wm_client(name=None) + :no-typesetting: + .. method:: client(name=None) - wm_client(name=None) Store *name*, which should be the name of the host on which the application is running, in the window's ``WM_CLIENT_MACHINE`` property for use by the window or session manager. An empty string deletes the property. With no argument, return the last name set, or an empty string. - The ``wm_``-prefixed spelling (e.g. ``wm_client``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_client`) is an equivalent alias. + + .. method:: wm_colormapwindows(*wlist) + :no-typesetting: .. method:: colormapwindows(*wlist) - wm_colormapwindows(*wlist) Manipulate the ``WM_COLORMAP_WINDOWS`` property, which tells the window manager about windows that have private colormaps. If *wlist* is given, @@ -2241,29 +2295,35 @@ Base and mixin classes The ``wm_``-prefixed spelling (e.g. ``wm_colormapwindows``) is an equivalent alias. + .. method:: wm_command(value=None) + :no-typesetting: + .. method:: command(value=None) - wm_command(value=None) Store *value* in the window's ``WM_COMMAND`` property for use by the window or session manager; it should be a list giving the words of the command used to invoke the application. An empty string deletes the property. With no argument, return the last value set, or an empty string. - The ``wm_``-prefixed spelling (e.g. ``wm_command``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_command`) is an equivalent alias. + .. method:: wm_deiconify() + :no-typesetting: + .. method:: deiconify() - wm_deiconify() Display the window in normal (non-iconified) form by mapping it. If the window has never been mapped, this ensures it appears de-iconified when it is first mapped. On Windows the window is also raised and given the focus. - The ``wm_``-prefixed spelling (e.g. ``wm_deiconify``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_deiconify`) is an equivalent alias. + .. method:: wm_focusmodel(model=None) + :no-typesetting: + .. method:: focusmodel(model=None) - wm_focusmodel(model=None) Set or query the focus model for the window. *model* is either ``'active'`` (the window claims the input focus for itself or its @@ -2271,31 +2331,37 @@ Base and mixin classes ``'passive'`` (the window relies on the window manager to give it the focus). With no argument, return the current model. The default is ``'passive'``, which is what the :meth:`!focus` command assumes. - The ``wm_``-prefixed spelling (e.g. ``wm_focusmodel``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_focusmodel`) is an equivalent alias. + .. method:: wm_forget(window) + :no-typesetting: + .. method:: forget(window) - wm_forget(window) Unmap *window* from the screen so that it is no longer managed by the window manager. A :class:`Toplevel` is then treated like a :class:`Frame`, although its ``-menu`` configuration is remembered and the menu reappears if the widget is managed again. - The ``wm_``-prefixed spelling (e.g. ``wm_forget``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_forget`) is an equivalent alias. .. versionadded:: 3.3 + .. method:: wm_frame() + :no-typesetting: + .. method:: frame() - wm_frame() Return the platform-specific window identifier for the outermost decorative frame containing the window, if the window manager has reparented it into such a frame; otherwise return the identifier of the window itself. - The ``wm_``-prefixed spelling (e.g. ``wm_frame``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_frame`) is an equivalent alias. + + .. method:: wm_geometry(newGeometry=None) + :no-typesetting: .. method:: geometry(newGeometry=None) - wm_geometry(newGeometry=None) Set or query the geometry of the window. *newGeometry* has the form ``=widthxheight+x+y``, where any of ``=``, ``widthxheight`` and the @@ -2305,11 +2371,13 @@ Base and mixin classes right or bottom edge. An empty string cancels any user-specified geometry, letting the window revert to its natural size. With no argument, return the current geometry as a string of the form ``'200x200+10+10'``. - The ``wm_``-prefixed spelling (e.g. ``wm_geometry``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_geometry`) is an equivalent alias. + .. method:: wm_grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) + :no-typesetting: + .. method:: grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) - wm_grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) Manage the window as a gridded window and define the relationship between grid units and pixels. *baseWidth* and *baseHeight* are the numbers of @@ -2318,20 +2386,24 @@ Base and mixin classes 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. - The ``wm_``-prefixed spelling (e.g. ``wm_grid``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_grid`) is an equivalent alias. + + .. method:: wm_group(pathName=None) + :no-typesetting: .. method:: group(pathName=None) - wm_group(pathName=None) Set or query the leader of a group of related windows. *pathName* gives the path name of the group leader; the window manager may, for example, unmap all windows in the group when the leader is iconified. An empty string removes the window from any group. With no argument, return the path name of the current group leader, or an empty string. - The ``wm_``-prefixed spelling (e.g. ``wm_group``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_group`) is an equivalent alias. + + .. method:: wm_iconbitmap(bitmap=None, default=None) + :no-typesetting: .. method:: iconbitmap(bitmap=None, default=None) - wm_iconbitmap(bitmap=None, default=None) Set or query the bitmap used by the window manager for the window's icon. *bitmap* names a bitmap in one of the standard forms accepted by Tk; an @@ -2339,40 +2411,48 @@ Base and mixin classes the name of the current icon bitmap, or an empty string. On Windows the *default* argument names an icon (for example an ``.ico`` file) applied to all top-level windows that have no icon of their own. - The ``wm_``-prefixed spelling (e.g. ``wm_iconbitmap``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconbitmap`) is an equivalent alias. + .. method:: wm_iconify() + :no-typesetting: + .. method:: iconify() - wm_iconify() Iconify the window. If the window has not yet been mapped for the first time, arrange for it to appear in the iconified state when it is eventually mapped. - The ``wm_``-prefixed spelling (e.g. ``wm_iconify``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconify`) is an equivalent alias. + + .. method:: wm_iconmask(bitmap=None) + :no-typesetting: .. method:: iconmask(bitmap=None) - wm_iconmask(bitmap=None) Set or query the bitmap used as a mask for the icon (see :meth:`iconbitmap`). Where the mask is zero no icon is displayed; where it is one, the corresponding bits of the icon bitmap are shown. An empty string cancels the current mask. With no argument, return the name of the current icon mask, or an empty string. - The ``wm_``-prefixed spelling (e.g. ``wm_iconmask``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconmask`) is an equivalent alias. + .. method:: wm_iconname(newName=None) + :no-typesetting: + .. method:: iconname(newName=None) - wm_iconname(newName=None) Set or query the name displayed by the window manager inside the window's icon. With no argument, return the current icon name, or an empty string if none has been set (in which case the window manager normally displays the window's title). - The ``wm_``-prefixed spelling (e.g. ``wm_iconname``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconname`) is an equivalent alias. + .. method:: wm_iconphoto(default=False, *images) + :no-typesetting: + .. method:: iconphoto(default=False, *images) - wm_iconphoto(default=False, *images) Set the titlebar icon for the window from one or more :class:`PhotoImage` objects given in *images*. Several images of different @@ -2382,23 +2462,27 @@ Base and mixin classes reflected. If *default* is true, the icon is also applied to all top-level windows created in the future. On macOS only the first image is used. - The ``wm_``-prefixed spelling (e.g. ``wm_iconphoto``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconphoto`) is an equivalent alias. .. versionadded:: 3.3 + .. method:: wm_iconposition(x=None, y=None) + :no-typesetting: + .. method:: iconposition(x=None, y=None) - wm_iconposition(x=None, y=None) 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. - The ``wm_``-prefixed spelling (e.g. ``wm_iconposition``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconposition`) is an equivalent alias. + .. method:: wm_iconwindow(pathName=None) + :no-typesetting: + .. method:: iconwindow(pathName=None) - wm_iconwindow(pathName=None) Set or query the window used as the icon for the window. When the window is iconified, *pathName* is mapped to serve as its icon and unmapped again @@ -2406,42 +2490,50 @@ Base and mixin classes argument, return the path name of the current icon window, or an empty string. Not all window managers support icon windows, and the concept is meaningless on non-X11 platforms. - The ``wm_``-prefixed spelling (e.g. ``wm_iconwindow``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconwindow`) is an equivalent alias. + .. method:: wm_manage(widget) + :no-typesetting: + .. method:: manage(widget) - wm_manage(widget) Make *widget* a stand-alone top-level window, decorated by the window manager with a title bar and so on. Only :class:`Frame`, :class:`LabelFrame` and :class:`Toplevel` widgets may be used; passing any other widget type raises an error. - The ``wm_``-prefixed spelling (e.g. ``wm_manage``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_manage`) is an equivalent alias. .. versionadded:: 3.3 + .. method:: wm_maxsize(width=None, height=None) + :no-typesetting: + .. method:: maxsize(width=None, height=None) - wm_maxsize(width=None, height=None) Set or query the maximum permissible dimensions of the window, in pixels (or grid units for a gridded window). The window manager restricts the window to be no larger than *width* and *height*. With no arguments, return a tuple of the current maximum width and height. The maximum size defaults to the size of the screen. - The ``wm_``-prefixed spelling (e.g. ``wm_maxsize``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_maxsize`) is an equivalent alias. + + .. method:: wm_minsize(width=None, height=None) + :no-typesetting: .. method:: minsize(width=None, height=None) - wm_minsize(width=None, height=None) Set or query the minimum permissible dimensions of the window, in pixels (or grid units for a gridded window). The window manager restricts the window to be no smaller than *width* and *height*. With no arguments, return a tuple of the current minimum width and height. The minimum size defaults to one pixel in each dimension. - The ``wm_``-prefixed spelling (e.g. ``wm_minsize``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_minsize`) is an equivalent alias. + + .. method:: wm_overrideredirect(boolean=None) + :no-typesetting: .. method:: overrideredirect(boolean=None) - wm_overrideredirect(boolean=None) Set or query the override-redirect flag for the window. When this flag is set, the window is ignored by the window manager: it is not reparented into @@ -2452,8 +2544,10 @@ Base and mixin classes The ``wm_``-prefixed spelling (e.g. ``wm_overrideredirect``) is an equivalent alias. + .. method:: wm_positionfrom(who=None) + :no-typesetting: + .. method:: positionfrom(who=None) - wm_positionfrom(who=None) Set or query the source of the window's current position. *who* is either ``'program'`` or ``'user'`` and indicates whether the position was @@ -2462,11 +2556,13 @@ Base and mixin classes string if none has been set. Tk automatically sets the source to ``'user'`` when :meth:`geometry` is called, unless it has been set explicitly to ``'program'``. - The ``wm_``-prefixed spelling (e.g. ``wm_positionfrom``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_positionfrom`) is an equivalent alias. + .. method:: wm_protocol(name=None, func=None) + :no-typesetting: + .. method:: protocol(name=None, func=None) - wm_protocol(name=None, func=None) Register *func* as the handler for the window manager protocol *name*, an atom such as ``'WM_DELETE_WINDOW'``, ``'WM_SAVE_YOURSELF'`` or @@ -2478,33 +2574,39 @@ Base and mixin classes string if none is set (the default ``WM_DELETE_WINDOW`` handler is not reported); with no arguments, return a tuple of the protocols that currently have handlers. - The ``wm_``-prefixed spelling (e.g. ``wm_protocol``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_protocol`) is an equivalent alias. + .. method:: wm_resizable(width=None, height=None) + :no-typesetting: + .. method:: resizable(width=None, height=None) - wm_resizable(width=None, height=None) Control whether the user may interactively resize the window. *width* and *height* are boolean values that determine whether the window's width and height may be changed. With no arguments, return a tuple of two ``0``/``1`` values indicating whether each dimension is currently resizable. By default a window is resizable in both dimensions. - The ``wm_``-prefixed spelling (e.g. ``wm_resizable``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_resizable`) is an equivalent alias. + .. method:: wm_sizefrom(who=None) + :no-typesetting: + .. method:: sizefrom(who=None) - wm_sizefrom(who=None) Set or query the source of the window's current size. *who* is either ``'program'`` or ``'user'`` and indicates whether the size was requested by the program or by the user; an empty string cancels the current source. With no argument, return the current source, or an empty string if none has been set. - The ``wm_``-prefixed spelling (e.g. ``wm_sizefrom``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_sizefrom`) is an equivalent alias. + .. method:: wm_state(newstate=None) + :no-typesetting: + .. method:: state(newstate=None) - wm_state(newstate=None) Set or query the state of the window. With no argument, return the current state: one of ``'normal'``, ``'iconic'``, ``'withdrawn'``, ``'icon'`` or, @@ -2512,18 +2614,22 @@ Base and mixin classes that has been iconified, while ``'icon'`` refers to a window serving as the icon for another window (see :meth:`iconwindow`); the ``'icon'`` state cannot be set. - The ``wm_``-prefixed spelling (e.g. ``wm_state``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_state`) is an equivalent alias. + + .. method:: wm_title(string=None) + :no-typesetting: .. method:: title(string=None) - wm_title(string=None) Set or query the title for the window, which the window manager should display in the window's title bar. With no argument, return the current title. The title defaults to the window's name. - The ``wm_``-prefixed spelling (e.g. ``wm_title``) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_title`) is an equivalent alias. + + .. method:: wm_transient(master=None) + :no-typesetting: .. method:: transient(master=None) - wm_transient(master=None) Mark the window as a transient window (such as a pull-down menu or dialog) working on behalf of *master*, the path name of another top-level window. @@ -2531,18 +2637,20 @@ Base and mixin classes path name of the current master, or an empty string. A transient window mirrors state changes in its master and may be decorated differently by the window manager; it is an error to make a window a transient of itself. - The ``wm_``-prefixed spelling (e.g. ``wm_transient``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_transient`) is an equivalent alias. + .. method:: wm_withdraw() + :no-typesetting: + .. method:: withdraw() - wm_withdraw() Withdraw the window from the screen, unmapping it and causing the window manager to forget about it. If the window has never been mapped, it is instead mapped in the withdrawn state. It is sometimes necessary to withdraw a window and then re-map it (for example with :meth:`deiconify`) to make some window managers notice changes to window attributes. - The ``wm_``-prefixed spelling (e.g. ``wm_withdraw``) is an equivalent + The ``wm_``-prefixed spelling (e.g. :meth:`wm_withdraw`) is an equivalent alias. @@ -2553,50 +2661,64 @@ Base and mixin classes (through :class:`Widget`) and provides the methods for managing a widget with the *pack* geometry manager. See also :ref:`pack-the-packer`. + .. method:: configure(cnf={}, **kw) + :no-typesetting: + + .. method:: config(cnf={}, **kw) + :no-typesetting: + .. method:: pack_configure(cnf={}, **kw) pack(cnf={}, **kw) - configure(cnf={}, **kw) - config(cnf={}, **kw) Pack the widget inside its container, positioning it relative to the siblings already packed there. Options such as *side* (``'top'``, ``'bottom'``, ``'left'`` or ``'right'``), *fill* (``'x'``, ``'y'``, ``'both'`` or ``'none'``), *expand*, *anchor*, *padx*/*pady*, *ipadx*/*ipady* and *in_* control the placement; see the Tk - ``pack`` manual page for the full list. :meth:`!pack`, :meth:`!configure` - and :meth:`!config` are aliases of :meth:`!pack_configure`. + ``pack`` manual page for the full list. :meth:`pack`, :meth:`configure` + and :meth:`config` are aliases of :meth:`!pack_configure`. + + .. method:: forget() + :no-typesetting: .. method:: pack_forget() - forget() Unmap the widget and remove it from the packing order, forgetting its packing options. It can be packed again later with - :meth:`pack_configure`. :meth:`!forget` is an alias of + :meth:`pack_configure`. :meth:`forget` is an alias of :meth:`!pack_forget`. + .. method:: info() + :no-typesetting: + .. method:: pack_info() - info() Return a dictionary of the widget's current packing options. - :meth:`!info` is an alias of :meth:`!pack_info`. + :meth:`info` is an alias of :meth:`!pack_info`. + + .. method:: propagate(flag=['_noarg_']) + :no-typesetting: .. method:: pack_propagate(flag=['_noarg_']) - propagate(flag=['_noarg_']) Same as :meth:`Misc.pack_propagate`, treating this widget as a container: - enable or disable geometry propagation. :meth:`!propagate` is an alias of + enable or disable geometry propagation. :meth:`propagate` is an alias of :meth:`!pack_propagate`. + .. method:: slaves() + :no-typesetting: + .. method:: pack_slaves() - slaves() Same as :meth:`Misc.pack_slaves`: return the list of widgets packed in - this widget. :meth:`!slaves` is an alias of :meth:`!pack_slaves`. + this widget. :meth:`slaves` is an alias of :meth:`!pack_slaves`. + + .. method:: content() + :no-typesetting: .. method:: pack_content() - content() - Same as :meth:`Misc.pack_content`. :meth:`!content` is an alias of + Same as :meth:`Misc.pack_content`. :meth:`content` is an alias of :meth:`!pack_content`. @@ -2606,40 +2728,52 @@ Base and mixin classes their container. The :class:`!Place` mix-in is inherited by all widgets (through :class:`Widget`). + .. method:: configure(cnf={}, **kw) + :no-typesetting: + + .. method:: config(cnf={}, **kw) + :no-typesetting: + .. method:: place_configure(cnf={}, **kw) place(cnf={}, **kw) - configure(cnf={}, **kw) - config(cnf={}, **kw) Place the widget inside its container at an absolute or relative position. Options include *x*/*y* and *relx*/*rely* (absolute and fractional position), *width*/*height* and *relwidth*/*relheight* (absolute and fractional size), *anchor*, *bordermode* and *in_*; see the Tk ``place`` - manual page. :meth:`!place`, :meth:`!configure` and :meth:`!config` are + manual page. :meth:`place`, :meth:`configure` and :meth:`config` are aliases of :meth:`!place_configure`. + .. method:: forget() + :no-typesetting: + .. method:: place_forget() - forget() Unmap the widget and remove it from the placement, forgetting its place - options. :meth:`!forget` is an alias of :meth:`!place_forget`. + options. :meth:`forget` is an alias of :meth:`!place_forget`. + + .. method:: info() + :no-typesetting: .. method:: place_info() - info() Return a dictionary of the widget's current place options. - :meth:`!info` is an alias of :meth:`!place_info`. + :meth:`info` is an alias of :meth:`!place_info`. + + .. method:: slaves() + :no-typesetting: .. method:: place_slaves() - slaves() Same as :meth:`Misc.place_slaves`: return the list of widgets placed in - this widget. :meth:`!slaves` is an alias of :meth:`!place_slaves`. + this widget. :meth:`slaves` is an alias of :meth:`!place_slaves`. + + .. method:: content() + :no-typesetting: .. method:: place_content() - content() - Same as :meth:`Misc.place_content`. :meth:`!content` is an alias of + Same as :meth:`Misc.place_content`. :meth:`content` is an alias of :meth:`!place_content`. @@ -2649,89 +2783,115 @@ Base and mixin classes columns within their container. The :class:`!Grid` mix-in is inherited by all widgets (through :class:`Widget`). + .. method:: configure(cnf={}, **kw) + :no-typesetting: + + .. method:: config(cnf={}, **kw) + :no-typesetting: + .. method:: grid_configure(cnf={}, **kw) grid(cnf={}, **kw) - configure(cnf={}, **kw) - config(cnf={}, **kw) Position the widget in a cell of its container's grid. Options include *row*/*column*, *rowspan*/*columnspan*, *sticky*, *padx*/*pady*, - *ipadx*/*ipady* and *in_*; see the Tk ``grid`` manual page. :meth:`!grid`, - :meth:`!configure` and :meth:`!config` are aliases of + *ipadx*/*ipady* and *in_*; see the Tk ``grid`` manual page. :meth:`grid`, + :meth:`configure` and :meth:`config` are aliases of :meth:`!grid_configure`. + .. method:: forget() + :no-typesetting: + .. method:: grid_forget() - forget() Unmap the widget and remove it from the grid, forgetting its grid options. - :meth:`!forget` is an alias of :meth:`!grid_forget`. + :meth:`forget` is an alias of :meth:`!grid_forget`. .. method:: grid_remove() Unmap the widget and remove it from the grid, but remember its grid options so that it is restored to the same cell if it is gridded again. + .. method:: info() + :no-typesetting: + .. method:: grid_info() - info() Return a dictionary of the widget's current grid options. - :meth:`!info` is an alias of :meth:`!grid_info`. + :meth:`info` is an alias of :meth:`!grid_info`. + + .. method:: anchor(anchor=None) + :no-typesetting: .. method:: grid_anchor(anchor=None) - anchor(anchor=None) - Same as :meth:`Misc.grid_anchor`. :meth:`!anchor` is an alias of + Same as :meth:`Misc.grid_anchor`. :meth:`anchor` is an alias of :meth:`!grid_anchor`. + .. method:: bbox(column=None, row=None, col2=None, row2=None) + :no-typesetting: + .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) - bbox(column=None, row=None, col2=None, row2=None) - Same as :meth:`Misc.grid_bbox`. :meth:`!bbox` is an alias of + Same as :meth:`Misc.grid_bbox`. :meth:`bbox` is an alias of :meth:`!grid_bbox`. + .. method:: columnconfigure(index, cnf={}, **kw) + :no-typesetting: + .. method:: grid_columnconfigure(index, cnf={}, **kw) - columnconfigure(index, cnf={}, **kw) Same as :meth:`Misc.grid_columnconfigure`: query or set the options (such as *weight*, *minsize*, *pad* and *uniform*) of a grid column. - :meth:`!columnconfigure` is an alias of :meth:`!grid_columnconfigure`. + :meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. + + .. method:: rowconfigure(index, cnf={}, **kw) + :no-typesetting: .. method:: grid_rowconfigure(index, cnf={}, **kw) - rowconfigure(index, cnf={}, **kw) Same as :meth:`Misc.grid_rowconfigure`: query or set the options of a grid - row. :meth:`!rowconfigure` is an alias of :meth:`!grid_rowconfigure`. + row. :meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. + + .. method:: location(x, y) + :no-typesetting: .. method:: grid_location(x, y) - location(x, y) Same as :meth:`Misc.grid_location`: return the ``(column, row)`` of the - cell that covers the pixel at *x*, *y*. :meth:`!location` is an alias of + cell that covers the pixel at *x*, *y*. :meth:`location` is an alias of :meth:`!grid_location`. + .. method:: size() + :no-typesetting: + .. method:: grid_size() - size() Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving - the size of the grid. :meth:`!size` is an alias of :meth:`!grid_size`. + the size of the grid. :meth:`size` is an alias of :meth:`!grid_size`. + + .. method:: propagate(flag=['_noarg_']) + :no-typesetting: .. method:: grid_propagate(flag=['_noarg_']) - propagate(flag=['_noarg_']) - Same as :meth:`Misc.grid_propagate`. :meth:`!propagate` is an alias of + Same as :meth:`Misc.grid_propagate`. :meth:`propagate` is an alias of :meth:`!grid_propagate`. + .. method:: slaves(row=None, column=None) + :no-typesetting: + .. method:: grid_slaves(row=None, column=None) - slaves(row=None, column=None) Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid, - optionally restricted to a *row* and/or *column*. :meth:`!slaves` is an + optionally restricted to a *row* and/or *column*. :meth:`slaves` is an alias of :meth:`!grid_slaves`. + .. method:: content(row=None, column=None) + :no-typesetting: + .. method:: grid_content(row=None, column=None) - content(row=None, column=None) - Same as :meth:`Misc.grid_content`. :meth:`!content` is an alias of + Same as :meth:`Misc.grid_content`. :meth:`content` is an alias of :meth:`!grid_content`. @@ -2981,8 +3141,10 @@ Widget classes given by *tagOrId* (the lowest matching item if it matches several). This is like :meth:`~Widget.cget` but applies to an individual item. + .. method:: itemconfig(tagOrId, cnf=None, **kw) + :no-typesetting: + .. method:: itemconfigure(tagOrId, cnf=None, **kw) - itemconfig(tagOrId, cnf=None, **kw) Query or modify the configuration options of the items given by *tagOrId*. This mirrors :meth:`~Widget.configure`, except that it applies to @@ -2990,7 +3152,7 @@ Widget classes returns a dictionary describing the current options of the first matching item; otherwise it sets the given options on every matching item. The legal options are those accepted by the corresponding ``create_*`` method. - :meth:`!itemconfig` is an alias of :meth:`!itemconfigure`. + :meth:`itemconfig` is an alias of :meth:`!itemconfigure`. .. method:: type(tagOrId) @@ -3096,9 +3258,13 @@ Widget classes Return a tuple of the ids of all items given by *tagOrId*. + .. method:: lift(tagOrId, aboveThis=None, /) + :no-typesetting: + + .. method:: tkraise(tagOrId, aboveThis=None, /) + :no-typesetting: + .. method:: tag_raise(tagOrId, aboveThis=None, /) - lift(tagOrId, aboveThis=None, /) - tkraise(tagOrId, aboveThis=None, /) Move all items given by *tagOrId* to a new position in the display list just above the item given by *aboveThis*, or to the top of the display @@ -3106,16 +3272,18 @@ Widget classes relative order is preserved. This has no effect on embedded window items, whose stacking order is controlled by :meth:`Misc.tkraise` and :meth:`Misc.lower` instead. - :meth:`!lift` and :meth:`!tkraise` are aliases of :meth:`!tag_raise`. + :meth:`lift` and :meth:`tkraise` are aliases of :meth:`!tag_raise`. + + .. method:: lower(tagOrId, belowThis=None, /) + :no-typesetting: .. method:: tag_lower(tagOrId, belowThis=None, /) - lower(tagOrId, belowThis=None, /) Move all items given by *tagOrId* to a new position in the display list just below the item given by *belowThis*, or to the bottom of the display list if *belowThis* is omitted. When several items are moved their relative order is preserved. - This has no effect on embedded window items. :meth:`!lower` is an alias of + This has no effect on embedded window items. :meth:`lower` is an alias of :meth:`!tag_lower`. .. method:: tag_bind(tagOrId, sequence=None, func=None, add=None) @@ -3333,46 +3501,58 @@ Widget classes Return the numerical index corresponding to *index*. + .. method:: select_adjust(index) + :no-typesetting: + .. method:: selection_adjust(index) - select_adjust(index) Locate the end of the selection nearest to the character given by *index*, and adjust that end to be at *index* (including but not going beyond it); the other end becomes the anchor point for future :meth:`selection_to` calls. If there is no selection in the entry, a new one is created between *index* and the most recent anchor point, - inclusive. ``select_adjust`` is an alias of :meth:`!selection_adjust`. + inclusive. :meth:`select_adjust` is an alias of :meth:`!selection_adjust`. + + .. method:: select_clear() + :no-typesetting: .. method:: selection_clear() - select_clear() Clear the selection if it is currently in this widget. If the selection - is not in this widget the method has no effect. ``select_clear`` is an + is not in this widget the method has no effect. :meth:`select_clear` is an alias of :meth:`!selection_clear`. + .. method:: select_from(index) + :no-typesetting: + .. method:: selection_from(index) - select_from(index) Set the selection anchor point to just before the character given by - *index*, without changing the selection. ``select_from`` is an alias of + *index*, without changing the selection. :meth:`select_from` is an alias of :meth:`!selection_from`. + .. method:: select_present() + :no-typesetting: + .. method:: selection_present() - select_present() Return ``True`` if there are characters selected in the entry, ``False`` - otherwise. ``select_present`` is an alias of :meth:`!selection_present`. + otherwise. :meth:`select_present` is an alias of :meth:`!selection_present`. + + .. method:: select_range(start, end) + :no-typesetting: .. method:: selection_range(start, end) - select_range(start, end) Set the selection to include the characters starting with the one indexed by *start* and ending with the one just before *end*. If *end* refers to the same character as *start* or an earlier one, the selection is cleared. - ``select_range`` is an alias of :meth:`!selection_range`. + :meth:`select_range` is an alias of :meth:`!selection_range`. + + .. method:: select_to(index) + :no-typesetting: .. method:: selection_to(index) - select_to(index) Set the selection between the anchor point and *index*: if *index* is before the anchor point, the selection runs from *index* up to but not @@ -3380,7 +3560,7 @@ Widget classes not including *index*; if they coincide, nothing happens. The anchor point is the one set by the most recent :meth:`selection_from` or :meth:`selection_adjust` call. If there is no selection in the entry, a - new one is created using the most recent anchor point. ``select_to`` is + new one is created using the most recent anchor point. :meth:`select_to` is an alias of :meth:`!selection_to`. .. method:: scan_mark(x) @@ -3513,32 +3693,44 @@ Widget classes Return a tuple containing the numerical indices of all of the items that are currently selected, or an empty tuple if no items are selected. + .. method:: select_anchor(index) + :no-typesetting: + .. method:: selection_anchor(index) Set the selection anchor to the item given by *index*. If *index* refers to a non-existent item, the closest item is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse, and may afterwards be referred to with the ``'anchor'`` - index. :meth:`!select_anchor` is an alias of :meth:`!selection_anchor`. + index. :meth:`select_anchor` is an alias of :meth:`!selection_anchor`. + + .. method:: select_clear(first, last=None) + :no-typesetting: .. method:: selection_clear(first, last=None) Deselect any of the items in the range from *first* to *last* inclusive that are selected. The selection state of items outside this range is - not changed. :meth:`!select_clear` is an alias of + not changed. :meth:`select_clear` is an alias of :meth:`!selection_clear`. + .. method:: select_includes(index) + :no-typesetting: + .. method:: selection_includes(index) Return ``True`` if the item given by *index* is currently selected, - ``False`` otherwise. :meth:`!select_includes` is an alias of + ``False`` otherwise. :meth:`select_includes` is an alias of :meth:`!selection_includes`. + .. method:: select_set(first, last=None) + :no-typesetting: + .. method:: selection_set(first, last=None) Select all of the items in the range from *first* to *last* inclusive, without affecting the selection state of items outside that range. - :meth:`!select_set` is an alias of :meth:`!selection_set`. + :meth:`select_set` is an alias of :meth:`!selection_set`. .. method:: itemcget(index, option) @@ -3553,7 +3745,7 @@ Widget classes it returns a dictionary describing the current options of the item; otherwise it sets the given options. The supported item options are *background*, *foreground*, *selectbackground* and *selectforeground*. - :meth:`!itemconfig` is an alias of :meth:`!itemconfigure`. + :meth:`itemconfig` is an alias of :meth:`!itemconfigure`. .. method:: scan_mark(x, y) @@ -3672,14 +3864,16 @@ Widget classes Return the current value of the configuration option *option* for the entry given by *index*. + .. method:: entryconfig(index, cnf=None, **kw) + :no-typesetting: + .. method:: entryconfigure(index, cnf=None, **kw) - entryconfig(index, cnf=None, **kw) Query or modify the configuration options of the entry given by *index*. This mirrors :meth:`~Widget.configure`, except that it applies to an individual entry rather than to the menu as a whole. With no options, it returns a dictionary describing the current options of the entry; - otherwise it sets the given options. :meth:`!entryconfig` is an alias of + otherwise it sets the given options. :meth:`entryconfig` is an alias of :meth:`!entryconfigure`. .. method:: index(index) @@ -3799,11 +3993,13 @@ Widget classes *child*; they may be any of the options accepted by :meth:`paneconfigure`. + .. method:: forget(child) + :no-typesetting: + .. method:: remove(child) - forget(child) Remove the pane containing *child* from the panedwindow. All geometry - management options for *child* are forgotten. :meth:`!forget` is an + management options for *child* are forgotten. :meth:`forget` is an alias of :meth:`!remove`. .. method:: panes() @@ -3817,8 +4013,10 @@ Widget classes containing *child*. *option* may be any value allowed by :meth:`paneconfigure`. + .. method:: paneconfig(tagOrId, cnf=None, **kw) + :no-typesetting: + .. method:: paneconfigure(tagOrId, cnf=None, **kw) - paneconfig(tagOrId, cnf=None, **kw) Query or modify the management options of the pane containing the widget *tagOrId*. With no options, it returns a dictionary describing all of @@ -3833,7 +4031,7 @@ Widget classes characters ``n``, ``s``, ``e`` and ``w``), *hide* (hide the pane while keeping it in the list of panes) and *stretch* (how extra space is allocated to the pane: one of ``'always'``, ``'first'``, ``'last'``, - ``'middle'`` or ``'never'``). :meth:`!paneconfig` is an alias of + ``'middle'`` or ``'never'``). :meth:`paneconfig` is an alias of :meth:`!paneconfigure`. .. method:: identify(x, y) @@ -4343,8 +4541,10 @@ Widget classes Delete each of the tags named in *tagNames*, removing them from all characters and discarding their options and bindings. + .. method:: tag_config(tagName, cnf=None, **kw) + :no-typesetting: + .. method:: tag_configure(tagName, cnf=None, **kw) - tag_config(tagName, cnf=None, **kw) Query or modify the configuration options of the tag *tagName*. This mirrors :meth:`~Widget.configure`, except that it applies to a tag rather @@ -4356,7 +4556,7 @@ Widget classes *elide* (whether the text is hidden). Defining a tag this way also gives it a priority higher than any existing tag. - :meth:`!tag_config` is an alias of :meth:`!tag_configure`. + :meth:`tag_config` is an alias of :meth:`!tag_configure`. .. method:: tag_cget(tagName, option) @@ -4454,13 +4654,15 @@ Widget classes Return the current value of the configuration option *option* for the embedded window at *index*. + .. method:: window_config(index, cnf=None, **kw) + :no-typesetting: + .. method:: window_configure(index, cnf=None, **kw) - window_config(index, cnf=None, **kw) Query or modify the configuration options of the embedded window at *index*, like :meth:`~Widget.configure` but applied to that window. - :meth:`!window_config` is an alias of :meth:`!window_configure`. + :meth:`window_config` is an alias of :meth:`!window_configure`. .. method:: window_names() @@ -4625,8 +4827,10 @@ Variable classes is returned as a string; the typed subclasses convert it to the appropriate Python type. + .. method:: initialize(value) + :no-typesetting: + .. method:: set(value) - initialize(value) Set the variable to *value*. @@ -4664,8 +4868,10 @@ Variable classes .. versionadded:: 3.6 + .. method:: trace(mode, callback) + :no-typesetting: + .. method:: trace_variable(mode, callback) - trace(mode, callback) Register *callback* to be called when the variable is accessed according to *mode*. *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for @@ -4735,8 +4941,10 @@ Variable classes Return the value of the variable as a :class:`bool`. Raise a :exc:`ValueError` if the value cannot be interpreted as a boolean. + .. method:: initialize(value) + :no-typesetting: + .. method:: set(value) - initialize(value) Set the variable to *value*, converting it to a boolean. @@ -4760,12 +4968,14 @@ Image classes queried and changed later with the mapping protocol (using ``image[key]``) or with the :meth:`configure` method. + .. method:: config(**kw) + :no-typesetting: + .. method:: configure(**kw) - config(**kw) Modify one or more configuration options of the image. The valid options depend on the image type; see :class:`PhotoImage` and :class:`BitmapImage`. - :meth:`!config` is an alias of :meth:`!configure`. + :meth:`config` is an alias of :meth:`!configure`. .. method:: height() diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index ce07a387db16840..8f3a9e3dea38e11 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -1149,6 +1149,9 @@ ttk.Treeview Otherwise, sets the options to the corresponding values as given by *kw*. + .. method:: reattach(item, parent, index) + :no-typesetting: + .. method:: move(item, parent, index) Moves *item* to position *index* in *parent*'s list of children. @@ -1158,6 +1161,8 @@ ttk.Treeview than or equal to the number of children, it is moved to the end. If *item* was detached it is reattached. + :meth:`reattach` is an alias of :meth:`!move`. + .. method:: next(item) @@ -1177,11 +1182,6 @@ ttk.Treeview the first child of its parent. - .. method:: reattach(item, parent, index) - - An alias for :meth:`Treeview.move`. - - .. method:: see(item) Ensure that *item* is visible. From 303589e6d5c059755676f1e8d6aaca3d68719f4e Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 11:13:38 +0300 Subject: [PATCH 04/18] gh-59551: Replace the ['_noarg_'] sentinel with two tkinter signatures Document the propagate(), pack_propagate() and grid_propagate() query/set methods with separate no-argument and one-argument signatures instead of exposing the internal ['_noarg_'] default placeholder. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 214dcf3ed4a601e..2939ad784ba53cd 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -1302,7 +1302,8 @@ Base and mixin classes locations above or to the left of the grid, ``-1`` is returned for the corresponding coordinate. - .. method:: grid_propagate(flag=['_noarg_']) + .. method:: grid_propagate() + grid_propagate(flag) Enable or disable geometry propagation for this container when it manages its children with the grid geometry manager. When *flag* is true, the @@ -1334,10 +1335,12 @@ Base and mixin classes .. versionadded:: 3.15 - .. method:: propagate(flag=['_noarg_']) + .. method:: propagate() + propagate(flag) :no-typesetting: - .. method:: pack_propagate(flag=['_noarg_']) + .. method:: pack_propagate() + pack_propagate(flag) Enable or disable geometry propagation for this container when it manages its children with the pack geometry manager. When *flag* is true, the @@ -2696,10 +2699,12 @@ Base and mixin classes Return a dictionary of the widget's current packing options. :meth:`info` is an alias of :meth:`!pack_info`. - .. method:: propagate(flag=['_noarg_']) + .. method:: propagate() + propagate(flag) :no-typesetting: - .. method:: pack_propagate(flag=['_noarg_']) + .. method:: pack_propagate() + pack_propagate(flag) Same as :meth:`Misc.pack_propagate`, treating this widget as a container: enable or disable geometry propagation. :meth:`propagate` is an alias of @@ -2869,10 +2874,12 @@ Base and mixin classes Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving the size of the grid. :meth:`size` is an alias of :meth:`!grid_size`. - .. method:: propagate(flag=['_noarg_']) + .. method:: propagate() + propagate(flag) :no-typesetting: - .. method:: grid_propagate(flag=['_noarg_']) + .. method:: grid_propagate() + grid_propagate(flag) Same as :meth:`Misc.grid_propagate`. :meth:`propagate` is an alias of :meth:`!grid_propagate`. From 5b2a713f87d9330b587c30f29e7cf31056819561 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 11:42:24 +0300 Subject: [PATCH 05/18] gh-59551: Reformat tkinter docs with one sentence per line Reflow the prose added or modified on this branch so that each sentence starts on a new line (semantic line breaks), wrapping long sentences at 79 columns. Only changed paragraphs are touched; tables, literal blocks, lists and definition lists are left as they were. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/dialog.rst | 89 +- Doc/library/tkinter.colorchooser.rst | 18 +- Doc/library/tkinter.dnd.rst | 6 +- Doc/library/tkinter.font.rst | 21 +- Doc/library/tkinter.messagebox.rst | 15 +- Doc/library/tkinter.rst | 3104 ++++++++++++++------------ Doc/library/tkinter.scrolledtext.rst | 7 +- Doc/library/tkinter.ttk.rst | 188 +- 8 files changed, 1886 insertions(+), 1562 deletions(-) diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst index c416fbe51621ab4..9f7f14e14ccc595 100644 --- a/Doc/library/dialog.rst +++ b/Doc/library/dialog.rst @@ -38,16 +38,19 @@ functions for creating simple modal dialogs to get a value from the user. .. 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. + 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. + 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() @@ -59,10 +62,10 @@ functions for creating simple modal dialogs to get a value from the user. 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. + 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() @@ -110,43 +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, 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``. +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) - 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). + 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 the opened file object, or ``None`` - if the dialog is cancelled. The file is opened in mode *mode* (``'w'`` by - default). + 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) - Create an :class:`Open` dialog. :func:`askopenfilename` returns the selected - filename as a string, or an empty string if the dialog is cancelled. + 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 as a string, - or an empty string if the dialog is cancelled. + 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 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). + 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) @@ -212,8 +218,8 @@ These do not emulate the native look-and-feel of the platform. .. method:: ok_command() - Called when the user confirms the current selection. The base - implementation accepts the selection and closes the dialog; + 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. @@ -247,9 +253,9 @@ These do not emulate the native look-and-feel of the platform. .. 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. + 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -291,13 +297,14 @@ the classic (non-themed) Tk widgets. .. 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. + 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() diff --git a/Doc/library/tkinter.colorchooser.rst b/Doc/library/tkinter.colorchooser.rst index 23627cdbc91eeda..e1e04d04a08b80e 100644 --- a/Doc/library/tkinter.colorchooser.rst +++ b/Doc/library/tkinter.colorchooser.rst @@ -15,18 +15,18 @@ 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. + 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) - 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. + 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 diff --git a/Doc/library/tkinter.dnd.rst b/Doc/library/tkinter.dnd.rst index caa69467d3680f0..ba267c0e3840fe2 100644 --- a/Doc/library/tkinter.dnd.rst +++ b/Doc/library/tkinter.dnd.rst @@ -57,9 +57,9 @@ Selection of a target object occurs as follows: .. function:: dnd_start(source, event) - 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. + 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:: diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst index c1b2f8a96e569cf..3d7b1196619f8fd 100644 --- a/Doc/library/tkinter.font.rst +++ b/Doc/library/tkinter.font.rst @@ -51,9 +51,9 @@ The different font weights and slants are: .. method:: actual(option=None, displayof=None) 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. + 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) @@ -64,8 +64,8 @@ The different font weights and slants are: .. method:: configure(**options) - Modify one or more attributes of the font. With no arguments, return a - dictionary of the current attributes. + Modify one or more attributes of the font. + With no arguments, return a dictionary of the current attributes. :meth:`config` is an alias of :meth:`!configure`. @@ -76,14 +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, as an integer number of pixels. 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. + 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 diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst index 0cc2f6b997de9ee..aa6bf32d4a75eba 100644 --- a/Doc/library/tkinter.messagebox.rst +++ b/Doc/library/tkinter.messagebox.rst @@ -9,13 +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: 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: +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 diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2939ad784ba53cd..988363e9ebd6e80 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -17,11 +17,12 @@ demonstrating a simple Tk interface, letting you know that :mod:`!tkinter` is properly installed on your system, and also showing what version of Tcl/Tk is installed, so you can read the Tcl/Tk documentation specific to that version. -Tkinter supports a range of Tcl/Tk versions, built either with or -without thread support. Tcl/Tk 8.5.12 is the minimum supported version; the -official Python binary release bundles Tcl/Tk 9.0. -See the source code for the :mod:`_tkinter` module -for more information about supported versions. +Tkinter supports a range of Tcl/Tk versions, built either with or without +thread support. +Tcl/Tk 8.5.12 is the minimum supported version; the official Python binary +release bundles Tcl/Tk 9.0. +See the source code for the :mod:`_tkinter` module for more information about +supported versions. .. versionchanged:: 3.11 Support for Tcl/Tk versions older than 8.5.12 was removed. @@ -199,9 +200,10 @@ the modern themed widget set and API:: .. method:: loadtk() - Finish loading and initializing the Tk subsystem. This is needed only - when the interpreter was created without Tk (for example through - :func:`Tcl`); it is called automatically when *useTk* is true. + Finish loading and initializing the Tk subsystem. + This is needed only when the interpreter was created without Tk (for + example through :func:`Tcl`); it is called automatically when *useTk* is + true. .. method:: readprofile(baseName, className) @@ -213,12 +215,13 @@ the modern themed widget set and API:: .. method:: report_callback_exception(exc, val, tb) - Report a callback exception. This is called when an exception propagates - out of a Tkinter callback; *exc*, *val* and *tb* are the exception type, - value and traceback as returned by :func:`sys.exc_info`. The default - implementation prints a traceback to :data:`sys.stderr`. It can be - overridden to customize error handling, for example to display the - traceback in a dialog. + Report a callback exception. + This is called when an exception propagates out of a Tkinter callback; + *exc*, *val* and *tb* are the exception type, value and traceback as + returned by :func:`sys.exc_info`. + The default implementation prints a traceback to :data:`sys.stderr`. + It can be overridden to customize error handling, for example to display + the traceback in a dialog. .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) @@ -478,10 +481,12 @@ is helpful. Navigating the Tcl/Tk Reference Manual ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As noted, the official `Tk commands `_ -reference manual (man pages) is often the most accurate description of what -specific operations on widgets do. Even when you know the name of the option -or method that you need, you may still have a few places to look. +As noted, the official +`Tk commands `_ reference +manual (man pages) is often the most accurate description of what specific +operations on widgets do. +Even when you know the name of the option or method that you need, you may +still have a few places to look. While all operations in Tkinter are implemented as method calls on widget objects, you've seen that many Tcl/Tk operations appear as commands that @@ -518,8 +523,8 @@ You'll find many common options and methods in the pages, while others are found in the man page for a specific widget class. You'll also find that many Tkinter methods have compound names, e.g., -:func:`winfo_x`, :func:`winfo_height`, :func:`winfo_viewable`. You'd find -documentation for all of these in the +:func:`winfo_x`, :func:`winfo_height`, :func:`winfo_viewable`. +You'd find documentation for all of these in the `winfo `_ man page. .. note:: @@ -794,13 +799,16 @@ subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods directly. To get at the toplevel window that contains a given widget, you can often just -refer to the widget's :attr:`master`. Of course if the widget has been packed inside of -a frame, the :attr:`!master` won't represent a toplevel window. To get at the toplevel -window that contains an arbitrary widget, you can call the :meth:`winfo_toplevel` -method. There is also a :meth:`_root` method; it begins with an underscore to -denote the fact that this function is part of the implementation, and not an -interface to Tk functionality. It returns the application's root window rather -than the nearest enclosing toplevel. +refer to the widget's :attr:`master`. +Of course if the widget has been packed inside of a frame, the :attr:`!master` +won't represent a toplevel window. +To get at the toplevel window that contains an arbitrary widget, you can call +the :meth:`winfo_toplevel` method. +There is also a :meth:`_root` method; it begins with an underscore to denote +the fact that this function is part of the implementation, and not an interface +to Tk functionality. +It returns the application's root window rather than the nearest enclosing +toplevel. Here are some examples of typical usage:: @@ -1105,8 +1113,9 @@ Reference .. currentmodule:: tkinter This section documents the classes, methods, functions and constants of the -:mod:`!tkinter` module. Most of them wrap Tcl/Tk commands; consult the official -Tcl/Tk manual pages for the full list of widget options and further details. +:mod:`!tkinter` module. +Most of them wrap Tcl/Tk commands; consult the official Tcl/Tk manual pages for +the full list of widget options and further details. Base and mixin classes ^^^^^^^^^^^^^^^^^^^^^^ @@ -1114,33 +1123,35 @@ Base and mixin classes .. class:: Misc() The :class:`!Misc` class is a mix-in inherited by :class:`Tk` and, through - :class:`BaseWidget`, by every widget. It provides the large set of methods - common to all Tk objects: querying window information, managing event - bindings and the event loop, controlling the keyboard focus and pointer - grabs, accessing the selection, clipboard and option database, and assorted - utility and introspection services. Because they are inherited, these - methods are available on every widget and on the :class:`Tk` application - object, and are documented here once rather than repeated for each widget. + :class:`BaseWidget`, by every widget. + It provides the large set of methods common to all Tk objects: querying + window information, managing event bindings and the event loop, controlling + the keyboard focus and pointer grabs, accessing the selection, clipboard and + option database, and assorted utility and introspection services. + Because they are inherited, these methods are available on every widget and + on the :class:`Tk` application object, and are documented here once rather + than repeated for each widget. .. method:: cget(key) Return the current value of the configuration option named *key* for this - widget, as a string. The expression ``widget[key]`` is equivalent and may - be used instead. + widget, as a string. + The expression ``widget[key]`` is equivalent and may be used instead. .. method:: config(cnf=None, **kw) :no-typesetting: .. method:: configure(cnf=None, **kw) - Query or modify the configuration options of the widget. With no - arguments, return a dictionary mapping every available option name to a - tuple describing it (its name, X resource name, X resource class, default - value and current value). If a single option name is given as a string, - return the tuple for just that option. If one or more keyword arguments - are given, or a dictionary is passed as *cnf*, set each named option to the - corresponding value; the expression ``widget[key] = value`` sets a single - option in the same way. + Query or modify the configuration options of the widget. + With no arguments, return a dictionary mapping every available option + name to a tuple describing it (its name, X resource name, X resource + class, default value and current value). + If a single option name is given as a string, return the tuple for just + that option. + If one or more keyword arguments are given, or a dictionary is passed as + *cnf*, set each named option to the corresponding value; the expression + ``widget[key] = value`` sets a single option in the same way. :meth:`config` is an alias of :meth:`!configure`. @@ -1151,21 +1162,24 @@ Base and mixin classes .. method:: getboolean(s) Interpret the string *s* as a Tcl boolean and return the corresponding - :class:`bool`. Tcl accepts values such as ``'1'``, ``'0'``, ``'yes'``, - ``'no'``, ``'true'`` and ``'false'``. Raise :exc:`ValueError` if *s* is - not a valid boolean. + :class:`bool`. + Tcl accepts values such as ``'1'``, ``'0'``, ``'yes'``, ``'no'``, + ``'true'`` and ``'false'``. + Raise :exc:`ValueError` if *s* is not a valid boolean. .. method:: getdouble(s) - Interpret the string *s* as a Tcl floating-point number and return it as a - :class:`float`. Raise :exc:`ValueError` if *s* is not a valid number. + Interpret the string *s* as a Tcl floating-point number and return it as + a :class:`float`. + Raise :exc:`ValueError` if *s* is not a valid number. .. versionadded:: 3.5 .. method:: getint(s) - Interpret the string *s* as a Tcl integer and return it as an :class:`int`. + Interpret the string *s* as a Tcl integer and return it as an + :class:`int`. Raise :exc:`ValueError` if *s* is not a valid integer. .. method:: getvar(name='PY_VAR') @@ -1177,19 +1191,21 @@ Base and mixin classes Set the Tcl global variable named *name* to *value*. The :meth:`!getvar` and :meth:`!setvar` methods give direct access to Tcl - variables. In most code you will instead use a :class:`Variable` subclass - such as :class:`StringVar` or :class:`IntVar`, which wraps a Tcl variable - and converts its value to and from a Python type. + variables. + In most code you will instead use a :class:`Variable` subclass such as + :class:`StringVar` or :class:`IntVar`, which wraps a Tcl variable and + converts its value to and from a Python type. .. method:: register(func, subst=None, needcleanup=1) - Register the Python callable *func* as a Tcl command and return the name of - the new command as a string. Whenever Tcl invokes that command, *func* is - called; if *subst* is given, it is applied to the command's arguments - first. This is the mechanism used internally to turn Python callbacks into - the command names passed to Tk options such as *command*. Unless - *needcleanup* is false, the command is deleted automatically when the - widget is destroyed. + Register the Python callable *func* as a Tcl command and return the name + of the new command as a string. + Whenever Tcl invokes that command, *func* is called; if *subst* is given, + it is applied to the command's arguments first. + This is the mechanism used internally to turn Python callbacks into the + command names passed to Tk options such as *command*. + Unless *needcleanup* is false, the command is deleted automatically when + the widget is destroyed. .. versionchanged:: 3.13 The arguments passed to *func* are no longer converted to strings. @@ -1206,8 +1222,8 @@ Base and mixin classes .. method:: send(interp, cmd, *args) Send the Tcl command *cmd*, with the given *args*, to the Tcl interpreter - registered under the name *interp*, and return its result. This is not - available on all platforms. + registered under the name *interp*, and return its result. + This is not available on all platforms. .. method:: destroy() @@ -1220,16 +1236,18 @@ Base and mixin classes .. method:: tkraise(aboveThis=None) Raise this widget in the stacking order so that it is drawn on top of its - siblings. If *aboveThis* is given, the widget is moved to be just above - it in the stacking order instead. + siblings. + If *aboveThis* is given, the widget is moved to be just above it in the + stacking order instead. :meth:`lift` is an alias of :meth:`!tkraise`. .. method:: lower(belowThis=None) Lower this widget in the stacking order so that it is drawn beneath its - siblings. If *belowThis* is given, the widget is moved to be just below - it in the stacking order instead. + siblings. + If *belowThis* is given, the widget is moved to be just below it in the + stacking order instead. .. method:: image_names() @@ -1247,9 +1265,10 @@ Base and mixin classes Set the anchor that controls where the grid is placed inside this container when the container is larger than the grid and no row or column - has a non-zero weight. *anchor* is one of the usual anchor strings, such - as ``'nw'`` (the default) or ``'center'``. Called with no argument, this - method has no effect. + has a non-zero weight. + *anchor* is one of the usual anchor strings, such as ``'nw'`` (the + default) or ``'center'``. + Called with no argument, this method has no effect. :meth:`anchor` is an alias of :meth:`!grid_anchor`. @@ -1261,11 +1280,11 @@ Base and mixin classes .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) Return the bounding box, in pixels, of a region of the grid laid out in - this container, as a 4-tuple ``(xoffset, yoffset, width, height)``. With - no arguments the bounding box of the whole grid is returned. If *column* - and *row* are given, the box spans from the cell at row and column 0 to - that cell; if *col2* and *row2* are also given, it spans from the cell - (*column*, *row*) to the cell (*col2*, *row2*). + this container, as a 4-tuple ``(xoffset, yoffset, width, height)``. + With no arguments the bounding box of the whole grid is returned. + If *column* and *row* are given, the box spans from the cell at row and + column 0 to that cell; if *col2* and *row2* are also given, it spans from + the cell (*column*, *row*) to the cell (*col2*, *row2*). :meth:`bbox` is an alias of :meth:`!grid_bbox`. @@ -1274,13 +1293,14 @@ Base and mixin classes .. method:: grid_columnconfigure(index, cnf={}, **kw) - Query or set the properties of the column (or columns) *index* of the grid - managed by this container. The valid options are *minsize* (the column's - minimum size in pixels), *weight* (how much of any extra space is given to - the column), *uniform* (a group name; columns sharing a group are kept the - same width in proportion to their weights) and *pad* (extra space added to - the column). With a single option name, return that option's value; with - no options, return a dictionary of all of them. + Query or set the properties of the column (or columns) *index* of the + grid managed by this container. + The valid options are *minsize* (the column's minimum size in pixels), + *weight* (how much of any extra space is given to the column), *uniform* + (a group name; columns sharing a group are kept the same width in + proportion to their weights) and *pad* (extra space added to the column). + With a single option name, return that option's value; with no options, + return a dictionary of all of them. :meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. @@ -1290,26 +1310,28 @@ Base and mixin classes .. method:: grid_rowconfigure(index, cnf={}, **kw) Query or set the properties of the row (or rows) *index* of the grid - managed by this container. The valid options are the same as for - :meth:`grid_columnconfigure`, applied to a row instead of a column. + managed by this container. + The valid options are the same as for :meth:`grid_columnconfigure`, + applied to a row instead of a column. :meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. .. method:: grid_location(x, y) Return the ``(column, row)`` of the grid cell that contains the pixel at - position (*x*, *y*), given in pixels relative to this container. For - locations above or to the left of the grid, ``-1`` is returned for the - corresponding coordinate. + position (*x*, *y*), given in pixels relative to this container. + For locations above or to the left of the grid, ``-1`` is returned for + the corresponding coordinate. .. method:: grid_propagate() grid_propagate(flag) Enable or disable geometry propagation for this container when it manages - its children with the grid geometry manager. When *flag* is true, the - container resizes itself to fit the requested sizes of its children; when - it is false, its size is left under your control. Called with no argument, - return the current setting as a boolean. + its children with the grid geometry manager. + When *flag* is true, the container resizes itself to fit the requested + sizes of its children; when it is false, its size is left under your + control. + Called with no argument, return the current setting as a boolean. .. method:: size() :no-typesetting: @@ -1324,8 +1346,9 @@ Base and mixin classes .. method:: grid_slaves(row=None, column=None) Return a list of the child widgets managed in this container's grid, most - recently managed first. If *row* or *column* is given, only the children - in that row or column are returned. + recently managed first. + If *row* or *column* is given, only the children in that row or column + are returned. .. method:: grid_content(row=None, column=None) @@ -1343,10 +1366,11 @@ Base and mixin classes pack_propagate(flag) Enable or disable geometry propagation for this container when it manages - its children with the pack geometry manager. When *flag* is true, the - container resizes itself to fit the requested sizes of its children; when - it is false, its size is left under your control. Called with no argument, - return the current setting as a boolean. + its children with the pack geometry manager. + When *flag* is true, the container resizes itself to fit the requested + sizes of its children; when it is false, its size is left under your + control. + Called with no argument, return the current setting as a boolean. :meth:`propagate` is an alias of :meth:`!pack_propagate`. @@ -1355,8 +1379,8 @@ Base and mixin classes .. method:: pack_slaves() - Return a list of the child widgets managed by this container with the pack - geometry manager, in packing order. + Return a list of the child widgets managed by this container with the + pack geometry manager, in packing order. :meth:`slaves` is an alias of :meth:`!pack_slaves`. @@ -1389,16 +1413,16 @@ Base and mixin classes Bind the event pattern *sequence* on this widget to the callable *func*. - *sequence* is an event pattern, such as ``''`` (a mouse - click) or ``''``, optionally a concatenation of several such - patterns that must occur shortly after one another. When the event - occurs, *func* is called with an :class:`Event` instance describing it as - its only argument; if *func* returns the string ``'break'``, no further - bindings for the event are invoked. + *sequence* is an event pattern, such as ``''`` (a mouse click) + or ``''``, optionally a concatenation of several such + patterns that must occur shortly after one another. + When the event occurs, *func* is called with an :class:`Event` instance + describing it as its only argument; if *func* returns the string + ``'break'``, no further bindings for the event are invoked. If *add* is true, *func* is added to any functions already bound to - *sequence*; otherwise it replaces them. The binding applies only to this - widget. + *sequence*; otherwise it replaces them. + The binding applies only to this widget. :meth:`!bind` returns a string identifier (a *funcid*) that can later be passed to :meth:`unbind` to remove the binding without leaking the @@ -1412,10 +1436,11 @@ Base and mixin classes Like :meth:`bind`, but bind *func* to the binding tag *className* rather than to a single widget, so that the binding applies to every widget - having that tag. *className* is usually the name of a widget class, such - as ``'Button'``, in which case the binding affects all widgets of that - class. The set of binding tags for a widget can be inspected and changed - with :meth:`bindtags`. + having that tag. + *className* is usually the name of a widget class, such as ``'Button'``, + in which case the binding affects all widgets of that class. + The set of binding tags for a widget can be inspected and changed with + :meth:`bindtags`. The remaining arguments and the return value are as for :meth:`bind`. @@ -1430,10 +1455,10 @@ Base and mixin classes Remove bindings for the event pattern *sequence* on this widget. - If *funcid* is given, only the function identified by it (a value returned - from a previous call to :meth:`bind`) is removed, and its associated Tcl - command is deleted. Otherwise all bindings for *sequence* are destroyed, - leaving it unbound. + If *funcid* is given, only the function identified by it (a value + returned from a previous call to :meth:`bind`) is removed, and its + associated Tcl command is deleted. + Otherwise all bindings for *sequence* are destroyed, leaving it unbound. .. versionchanged:: 3.13 If *funcid* is given, only that callback is unbound; other callbacks @@ -1443,21 +1468,25 @@ Base and mixin classes .. method:: unbind_class(className, sequence) Remove all bindings for the event pattern *sequence* from the binding tag - *className*. See :meth:`bind_class`. + *className*. + See :meth:`bind_class`. .. method:: unbind_all(sequence) Remove all bindings for the event pattern *sequence* from the special - binding tag ``'all'``. See :meth:`bind_all`. + binding tag ``'all'``. + See :meth:`bind_all`. .. method:: bindtags(tagList=None) If *tagList* is omitted, return a tuple of the binding tags associated - with this widget. When an event occurs in a widget, it is applied to each - of the widget's binding tags in order, and for each tag the most specific - matching binding is executed. By default a widget has four binding tags: - its own pathname, its widget class, the pathname of its nearest toplevel - ancestor, and ``'all'``, in that order. + with this widget. + When an event occurs in a widget, it is applied to each of the widget's + binding tags in order, and for each tag the most specific matching + binding is executed. + By default a widget has four binding tags: its own pathname, its widget + class, the pathname of its nearest toplevel ancestor, and ``'all'``, in + that order. If *tagList* is given, it must be a sequence of strings; the widget's binding tags are set to its elements, which determines the order in which @@ -1468,39 +1497,41 @@ Base and mixin classes Associate the virtual event *virtual*, whose name has the form ``'<>'``, with each of the physical event patterns given by *sequences*, so that the virtual event triggers whenever any of them - occurs. If *virtual* is already defined, the new sequences are added to - its existing ones. + occurs. + If *virtual* is already defined, the new sequences are added to its + existing ones. .. method:: event_delete(virtual, *sequences) Remove each of *sequences* from those associated with the virtual event - *virtual*. Sequences that are not currently associated with *virtual* are - ignored. If no *sequences* are given, all physical event sequences are - removed, so that *virtual* no longer triggers. + *virtual*. + Sequences that are not currently associated with *virtual* are ignored. + If no *sequences* are given, all physical event sequences are removed, so + that *virtual* no longer triggers. .. method:: event_generate(sequence, **kw) Generate the event *sequence* on this widget and arrange for it to be - processed just as if it had come from the window system. *sequence* must - be a single event pattern, such as ``''`` or ``'<>'``, - not a concatenation of several. Keyword arguments specify additional - fields of the event, for example *x* and *y* for the pointer position, or - *when* to control when the event is processed; refer to the Tk ``event`` - manual page for the full list. + processed just as if it had come from the window system. + *sequence* must be a single event pattern, such as ``''`` or + ``'<>'``, not a concatenation of several. + Keyword arguments specify additional fields of the event, for example *x* + and *y* for the pointer position, or *when* to control when the event is + processed; refer to the Tk ``event`` manual page for the full list. .. method:: event_info(virtual=None) - If *virtual* is omitted, return a tuple of all the virtual events that are - currently defined. If *virtual* is given, return a tuple of the physical - event sequences currently associated with it, or an empty tuple if it is - not defined. + If *virtual* is omitted, return a tuple of all the virtual events that + are currently defined. + If *virtual* is given, return a tuple of the physical event sequences + currently associated with it, or an empty tuple if it is not defined. .. method:: after(ms, func=None, *args, **kw) Schedule the callable *func* to be called after *ms* milliseconds, with - *args* and *kw* passed to it as positional and keyword arguments. Return - an identifier that can be passed to :meth:`after_cancel` to cancel the - call. + *args* and *kw* passed to it as positional and keyword arguments. + Return an identifier that can be passed to :meth:`after_cancel` to cancel + the call. If *func* is omitted, sleep for *ms* milliseconds instead, processing no events during that time, and return ``None``. @@ -1515,10 +1546,10 @@ Base and mixin classes .. method:: after_cancel(id) Cancel a callback previously scheduled with :meth:`after` or - :meth:`after_idle`. *id* must be an identifier returned by one of those - methods; passing a value that is not such an identifier raises - :exc:`ValueError`. If the callback has already run or been cancelled, - this has no effect. + :meth:`after_idle`. + *id* must be an identifier returned by one of those methods; passing a + value that is not such an identifier raises :exc:`ValueError`. + If the callback has already run or been cancelled, this has no effect. .. versionchanged:: 3.7 Passing ``None`` (or any false value) as *id* now raises @@ -1528,9 +1559,10 @@ Base and mixin classes .. method:: after_idle(func, *args, **kw) Schedule the callable *func* to be called, with *args* and *kw* passed to - it, when the Tk main loop next becomes idle, that is, when it has no other - events to process. Return an identifier that can be passed to - :meth:`after_cancel` to cancel the call. + it, when the Tk main loop next becomes idle, that is, when it has no + other events to process. + Return an identifier that can be passed to :meth:`after_cancel` to cancel + the call. .. versionchanged:: 3.14 Keyword arguments are now passed to *func*. @@ -1542,11 +1574,11 @@ Base and mixin classes currently scheduled with :meth:`after` and :meth:`after_idle` for this interpreter. - If *id* is given, it must identify a callback that has not yet run or been - cancelled, and the return value is a tuple ``(script, type)``, where + If *id* is given, it must identify a callback that has not yet run or + been cancelled, and the return value is a tuple ``(script, type)``, where *script* refers to the function to be called and *type* is either - ``'idle'`` or ``'timer'``. A :exc:`TclError` is raised if *id* does not - exist. + ``'idle'`` or ``'timer'``. + A :exc:`TclError` is raised if *id* does not exist. .. versionadded:: 3.13 @@ -1554,8 +1586,8 @@ Base and mixin classes .. method:: mainloop(n=0) Enter the Tk event loop, which processes events until all windows are - destroyed. This is normally called once, on the root window, to run the - application. + destroyed. + This is normally called once, on the root window, to run the application. .. method:: quit() @@ -1564,8 +1596,9 @@ Base and mixin classes .. method:: update() Enter the event loop until all pending events, including idle callbacks, - have been processed. This brings the display up to date and handles any - events that are already queued, then returns. + have been processed. + This brings the display up to date and handles any events that are + already queued, then returns. .. method:: update_idletasks() @@ -1579,24 +1612,28 @@ Base and mixin classes .. method:: wait_variable(name='PY_VAR') Wait until the Tcl variable *name* is modified, continuing to process - events in the meantime so that the application stays responsive. *name* - is usually a :class:`Variable` instance, such as an :class:`IntVar` or - :class:`StringVar`. + events in the meantime so that the application stays responsive. + *name* is usually a :class:`Variable` instance, such as an + :class:`IntVar` or :class:`StringVar`. :meth:`waitvar` is an alias of :meth:`!wait_variable`. .. method:: wait_window(window=None) Wait until *window* is destroyed, continuing to process events in the - meantime. If *window* is omitted, this widget is used. This is typically - used to wait for the user to finish interacting with a dialog box. + meantime. + If *window* is omitted, this widget is used. + This is typically used to wait for the user to finish interacting with a + dialog box. .. method:: wait_visibility(window=None) Wait until the visibility state of *window* changes, for example when it - first appears on the screen, continuing to process events in the meantime. - If *window* is omitted, this widget is used. This is typically used to - wait for a newly created window to become visible before acting on it. + first appears on the screen, continuing to process events in the + meantime. + If *window* is omitted, this widget is used. + This is typically used to wait for a newly created window to become + visible before acting on it. .. method:: focus_set() :no-typesetting: @@ -1606,14 +1643,14 @@ Base and mixin classes If the application does not currently have the input focus on this widget's display, the widget is remembered as the focus window for its top level, and the focus will be redirected to it the next time the - window manager gives the focus to the top level. :meth:`focus` is an alias - of :meth:`!focus_set`. + window manager gives the focus to the top level. + :meth:`focus` is an alias of :meth:`!focus_set`. .. method:: focus_force() Direct the keyboard input focus to this widget even if the application - does not currently have the input focus for the widget's display. This - method should be used sparingly, if at all; normally an application + does not currently have the input focus for the widget's display. + This method should be used sparingly, if at all; normally an application should wait for the window manager to give it the focus rather than claiming it. @@ -1634,52 +1671,57 @@ Base and mixin classes Return the most recent widget to have had the keyboard focus among all the widgets in the same top level as this widget; this is the widget that will receive the focus the next time the window manager gives the focus - to the top level. If no widget in that top level has ever had the focus, - or if the most recent focus widget has been deleted, the top level itself - is returned. + to the top level. + If no widget in that top level has ever had the focus, or if the most + recent focus widget has been deleted, the top level itself is returned. .. method:: tk_focusFollowsMouse() Reconfigure Tk to use an implicit focus model in which the focus is set - to a widget whenever the mouse pointer enters it. This cannot easily be - disabled once enabled. + to a widget whenever the mouse pointer enters it. + This cannot easily be disabled once enabled. .. method:: tk_focusNext() Return the next widget after this one in the keyboard traversal order, or - ``None`` if there is none. The traversal order goes first to the next - child, then recursively to the children of that child, and then to the - next sibling higher in the stacking order. A widget is skipped if its - ``takefocus`` option is set to ``0``. This method is used in the default - bindings for the :kbd:`Tab` key. + ``None`` if there is none. + The traversal order goes first to the next child, then recursively to the + children of that child, and then to the next sibling higher in the + stacking order. + A widget is skipped if its ``takefocus`` option is set to ``0``. + This method is used in the default bindings for the :kbd:`Tab` key. .. method:: tk_focusPrev() Return the previous widget before this one in the keyboard traversal - order, or ``None`` if there is none. See :meth:`tk_focusNext` for how the - order is defined. This method is used in the default bindings for the - :kbd:`Shift-Tab` key. + order, or ``None`` if there is none. + See :meth:`tk_focusNext` for how the order is defined. + This method is used in the default bindings for the :kbd:`Shift-Tab` key. .. method:: grab_set() - Set a local grab on this widget. A grab confines pointer events to this - widget and its descendants: while the pointer is outside the widget's - subtree, button presses and releases and pointer motion are reported to - the grab widget, and windows outside the subtree become insensitive until - the grab is released. A local grab affects only the grabbing - application. Any grab previously set by this application on the widget's - display is automatically released. Setting a grab is the usual way to - make a dialog modal: while the grab is in effect the user cannot interact - with the other windows of the application. + Set a local grab on this widget. + A grab confines pointer events to this widget and its descendants: while + the pointer is outside the widget's subtree, button presses and releases + and pointer motion are reported to the grab widget, and windows outside + the subtree become insensitive until the grab is released. + A local grab affects only the grabbing application. + Any grab previously set by this application on the widget's display is + automatically released. + Setting a grab is the usual way to make a dialog modal: while the grab is + in effect the user cannot interact with the other windows of the + application. .. method:: grab_set_global() - Set a global grab on this widget. A global grab is like the local grab - set by :meth:`grab_set`, but it locks out all other applications on the - screen, so that only this widget's subtree is sensitive to pointer - events, and it also grabs the keyboard. Use with caution: it is easy to - render a display unusable with a global grab, since other applications - stop receiving events until it is released. + Set a global grab on this widget. + A global grab is like the local grab set by :meth:`grab_set`, but it + locks out all other applications on the screen, so that only this + widget's subtree is sensitive to pointer events, and it also grabs the + keyboard. + Use with caution: it is easy to render a display unusable with a global + grab, since other applications stop receiving events until it is + released. .. method:: grab_release() @@ -1697,31 +1739,36 @@ Base and mixin classes .. method:: selection_clear(**kw) - Clear the X selection, so that no window owns it anymore. The selection - to clear is given by the keyword argument *selection*, an atom name such - as ``'PRIMARY'`` or ``'CLIPBOARD'``; it defaults to ``PRIMARY``. The - *displayof* keyword argument names a widget that determines the display on - which to operate, and defaults to this widget. + Clear the X selection, so that no window owns it anymore. + The selection to clear is given by the keyword argument *selection*, an + atom name such as ``'PRIMARY'`` or ``'CLIPBOARD'``; it defaults to + ``PRIMARY``. + The *displayof* keyword argument names a widget that determines the + display on which to operate, and defaults to this widget. .. method:: selection_get(**kw) - Return the contents of the current X selection. The keyword argument - *selection* names the selection and defaults to ``PRIMARY``. The keyword - argument *type* specifies the form in which the data is to be returned - (the desired conversion target), an atom name such as ``'STRING'`` or - ``'FILE_NAME'``; it defaults to ``STRING``, except on X11, where - ``UTF8_STRING`` is tried first and ``STRING`` is used as a fallback. The - *displayof* keyword argument names a widget that determines the display - from which to retrieve the selection, and defaults to this widget. + Return the contents of the current X selection. + The keyword argument *selection* names the selection and defaults to + ``PRIMARY``. + The keyword argument *type* specifies the form in which the data is to be + returned (the desired conversion target), an atom name such as + ``'STRING'`` or ``'FILE_NAME'``; it defaults to ``STRING``, except on + X11, where ``UTF8_STRING`` is tried first and ``STRING`` is used as a + fallback. + The *displayof* keyword argument names a widget that determines the + display from which to retrieve the selection, and defaults to this + widget. .. method:: selection_handle(command, **kw) Register *command* as a handler to supply the X selection owned by this - widget when another application requests it. When the selection is - retrieved, *command* is called with two arguments, the starting character - offset and the maximum number of characters to return, and must return at - most that many characters of the selection starting at that offset; for - very long selections it is called repeatedly with increasing offsets. + widget when another application requests it. + When the selection is retrieved, *command* is called with two arguments, + the starting character offset and the maximum number of characters to + return, and must return at most that many characters of the selection + starting at that offset; for very long selections it is called repeatedly + with increasing offsets. The keyword argument *selection* names the selection (default ``PRIMARY``) and the keyword argument *type* gives the form of the selection that the handler supplies (such as ``'STRING'`` or @@ -1729,116 +1776,125 @@ Base and mixin classes .. method:: selection_own(**kw) - Make this widget the owner of the X selection on its display. The - previous owner, if any, is notified that it has lost the selection. The - keyword argument *selection* names the selection and defaults to + Make this widget the owner of the X selection on its display. + The previous owner, if any, is notified that it has lost the selection. + The keyword argument *selection* names the selection and defaults to ``PRIMARY``. .. method:: selection_own_get(**kw) Return the widget in this application that owns the X selection on the display containing this widget, or ``None`` if no widget in this - application owns the selection. The keyword argument *selection* names - the selection and defaults to ``PRIMARY``. The *displayof* keyword - argument names a widget that determines the display to query, and - defaults to this widget. + application owns the selection. + The keyword argument *selection* names the selection and defaults to + ``PRIMARY``. + The *displayof* keyword argument names a widget that determines the + display to query, and defaults to this widget. .. method:: clipboard_append(string, **kw) Append *string* to the Tk clipboard and claim ownership of the clipboard - on this widget's display. Before appending, the clipboard should be - emptied with :meth:`clipboard_clear`; all appends should be completed - before returning to the event loop so that the clipboard is updated - atomically. The keyword argument *type* specifies the form of the data, - an atom name such as ``'STRING'`` or ``'FILE_NAME'`` (default - ``STRING``), and the keyword argument *format* specifies the - representation used to transmit it (default ``STRING``). The *displayof* - keyword argument names a widget that determines the target display, and - defaults to this widget. The contents can be retrieved with - :meth:`clipboard_get` or :meth:`selection_get`. + on this widget's display. + Before appending, the clipboard should be emptied with + :meth:`clipboard_clear`; all appends should be completed before returning + to the event loop so that the clipboard is updated atomically. + The keyword argument *type* specifies the form of the data, an atom name + such as ``'STRING'`` or ``'FILE_NAME'`` (default ``STRING``), and the + keyword argument *format* specifies the representation used to transmit + it (default ``STRING``). + The *displayof* keyword argument names a widget that determines the + target display, and defaults to this widget. + The contents can be retrieved with :meth:`clipboard_get` or + :meth:`selection_get`. .. method:: clipboard_clear(**kw) Claim ownership of the clipboard on this widget's display and remove any - previous contents. The *displayof* keyword argument names a widget that - determines the target display, and defaults to this widget. + previous contents. + The *displayof* keyword argument names a widget that determines the + target display, and defaults to this widget. .. method:: clipboard_get(**kw) - Retrieve data from the clipboard on this widget's display. The keyword - argument *type* specifies the form in which the data is to be returned, - an atom name such as ``'STRING'`` or ``'FILE_NAME'``; it defaults to - ``STRING``, except on X11, where ``UTF8_STRING`` is tried first and - ``STRING`` is used as a fallback. The *displayof* keyword argument names - a widget that determines the display, and defaults to the root window of - the application. This is equivalent to ``selection_get(selection= - 'CLIPBOARD')``. + Retrieve data from the clipboard on this widget's display. + The keyword argument *type* specifies the form in which the data is to be + returned, an atom name such as ``'STRING'`` or ``'FILE_NAME'``; it + defaults to ``STRING``, except on X11, where ``UTF8_STRING`` is tried + first and ``STRING`` is used as a fallback. + The *displayof* keyword argument names a widget that determines the + display, and defaults to the root window of the application. + This is equivalent to ``selection_get(selection= 'CLIPBOARD')``. .. method:: option_add(pattern, value, priority=None) Add an option to the Tk option database that associates *value* with - *pattern*. *pattern* consists of names and/or classes separated by - asterisks or dots, in the usual X format. *priority* is an integer - between 0 and 100, or one of the symbolic names ``'widgetDefault'`` (20), - ``'startupFile'`` (40), ``'userDefault'`` (60), or ``'interactive'`` - (80); it defaults to ``interactive``. + *pattern*. + *pattern* consists of names and/or classes separated by asterisks or + dots, in the usual X format. + *priority* is an integer between 0 and 100, or one of the symbolic names + ``'widgetDefault'`` (20), ``'startupFile'`` (40), ``'userDefault'`` (60), + or ``'interactive'`` (80); it defaults to ``interactive``. .. method:: option_clear() - Clear the Tk option database. Default options from the - :envvar:`!RESOURCE_MANAGER` property or the :file:`.Xdefaults` file are - reloaded automatically the next time an option is added to or removed from - the database. + Clear the Tk option database. + Default options from the :envvar:`!RESOURCE_MANAGER` property or the + :file:`.Xdefaults` file are reloaded automatically the next time an + option is added to or removed from the database. .. method:: option_get(name, className) Return the value of the option matching this widget under *name* and - *className* from the Tk option database, or an empty string if there is no - matching entry. When several entries match, the one with the highest - priority is returned, and among entries of equal priority the most - recently added one. + *className* from the Tk option database, or an empty string if there is + no matching entry. + When several entries match, the one with the highest priority is + returned, and among entries of equal priority the most recently added + one. .. method:: option_readfile(fileName, priority=None) Read the file named *fileName*, which should have the standard format for - an X resource database such as :file:`.Xdefaults`, and add all the options - it specifies to the Tk option database. *priority* is interpreted as for - :meth:`option_add` and defaults to ``interactive``. + an X resource database such as :file:`.Xdefaults`, and add all the + options it specifies to the Tk option database. + *priority* is interpreted as for :meth:`option_add` and defaults to + ``interactive``. .. method:: bell(displayof=0) Ring the bell on the display for this widget, using the display's current - bell-related settings, and reset the screen saver for the screen. If - *displayof* is given as a widget, the bell is rung on that widget's + bell-related settings, and reset the screen saver for the screen. + If *displayof* is given as a widget, the bell is rung on that widget's display instead. .. method:: tk_setPalette(background, /) tk_setPalette(*args, **kw) - Set a new color scheme for all Tk widget elements. Existing widgets are - updated and the option database is changed so that future widgets use the - new colors. A single color argument is taken as the normal background - color, from which a complete palette is computed. Alternatively, the - arguments may be given as keyword *name*/*value* pairs naming individual - options in the option database. The recognized option names are - ``activeBackground``, ``activeForeground``, ``background``, - ``disabledForeground``, ``foreground``, ``highlightBackground``, - ``highlightColor``, ``insertBackground``, ``selectColor``, - ``selectBackground``, ``selectForeground``, and ``troughColor``; - reasonable defaults are computed for any that are not specified. + Set a new color scheme for all Tk widget elements. + Existing widgets are updated and the option database is changed so that + future widgets use the new colors. + A single color argument is taken as the normal background color, from + which a complete palette is computed. + Alternatively, the arguments may be given as keyword *name*/*value* pairs + naming individual options in the option database. + The recognized option names are ``activeBackground``, + ``activeForeground``, ``background``, ``disabledForeground``, + ``foreground``, ``highlightBackground``, ``highlightColor``, + ``insertBackground``, ``selectColor``, ``selectBackground``, + ``selectForeground``, and ``troughColor``; reasonable defaults are + computed for any that are not specified. .. method:: tk_bisque() Restore the application's colors to the light brown (bisque) color scheme - used in Tk 3.6 and earlier versions. Provided for backward - compatibility. + used in Tk 3.6 and earlier versions. + Provided for backward compatibility. .. method:: tk_strictMotif(boolean=None) Query or set whether Tk's look and feel should strictly adhere to Motif. A true *boolean* value enables strict Motif compliance (for example, no - color change when the mouse passes over a slider). Return the resulting - setting. + color change when the mouse passes over a slider). + Return the resulting setting. .. method:: busy(**kw) :no-typesetting: @@ -1850,15 +1906,17 @@ Base and mixin classes .. method:: tk_busy_hold(**kw) - Make this widget appear busy. A transparent window is placed in front of - the widget, so that it and all of its descendants in the widget hierarchy - are blocked from pointer events and display a busy cursor. Normally - :meth:`update` should be called immediately afterwards to ensure that the - hold operation is in effect before the application starts its processing. + Make this widget appear busy. + A transparent window is placed in front of the widget, so that it and all + of its descendants in the widget hierarchy are blocked from pointer + events and display a busy cursor. + Normally :meth:`update` should be called immediately afterwards to ensure + that the hold operation is in effect before the application starts its + processing. The only supported configuration option is *cursor*, the cursor to be - displayed while the widget is busy; it may have any of the values accepted - by :meth:`!configure`. + displayed while the widget is busy; it may have any of the values + accepted by :meth:`!configure`. :meth:`busy_hold`, :meth:`busy` and :meth:`tk_busy` are aliases of :meth:`!tk_busy_hold`. @@ -1877,22 +1935,23 @@ Base and mixin classes .. method:: tk_busy_configure(cnf=None, **kw) - Query or modify the configuration options of the busy window. The widget - must have been previously made busy by :meth:`tk_busy_hold`. With no - arguments, return a dictionary describing all of the available options; if - *cnf* is the name of an option, return a tuple describing that one option. - Otherwise set the given option(s) to the given value(s). Options may have - any of the values accepted by :meth:`tk_busy_hold`. + Query or modify the configuration options of the busy window. + The widget must have been previously made busy by :meth:`tk_busy_hold`. + With no arguments, return a dictionary describing all of the available + options; if *cnf* is the name of an option, return a tuple describing + that one option. + Otherwise set the given option(s) to the given value(s). + Options may have any of the values accepted by :meth:`tk_busy_hold`. - The option database is referenced through the widget name or class. For - example, if a :class:`Frame` widget named ``frame`` is to be made busy, - the busy cursor can be specified for it by either of the calls:: + The option database is referenced through the widget name or class. + For example, if a :class:`Frame` widget named ``frame`` is to be made + busy, the busy cursor can be specified for it by either of the calls:: w.option_add('*frame.busyCursor', 'gumby') w.option_add('*Frame.BusyCursor', 'gumby') - :meth:`busy_configure`, :meth:`busy_config` and :meth:`tk_busy_config` are aliases of - :meth:`!tk_busy_configure`. + :meth:`busy_configure`, :meth:`busy_config` and :meth:`tk_busy_config` + are aliases of :meth:`!tk_busy_configure`. .. versionadded:: 3.13 @@ -1902,9 +1961,9 @@ Base and mixin classes .. method:: tk_busy_cget(option) - Return the current value of the busy configuration *option*. The widget - must have been previously made busy by :meth:`tk_busy_hold`, and *option* - may have any of the values accepted by that method. + Return the current value of the busy configuration *option*. + The widget must have been previously made busy by :meth:`tk_busy_hold`, + and *option* may have any of the values accepted by that method. :meth:`busy_cget` is an alias of :meth:`!tk_busy_cget`. @@ -1917,9 +1976,9 @@ Base and mixin classes .. method:: tk_busy_forget() Make this widget no longer busy, releasing the resources (including the - transparent window) allocated when it was made busy. User events will - again be received by the widget. These resources are also released when - the widget is destroyed. + transparent window) allocated when it was made busy. + User events will again be received by the widget. + These resources are also released when the widget is destroyed. :meth:`busy_forget` is an alias of :meth:`!tk_busy_forget`. @@ -1943,8 +2002,9 @@ Base and mixin classes .. method:: tk_busy_current(pattern=None) - Return a list of widgets that are currently busy. If *pattern* is given, - only busy widgets whose path names match the pattern are returned. + Return a list of widgets that are currently busy. + If *pattern* is given, only busy widgets whose path names match the + pattern are returned. :meth:`busy_current` is an alias of :meth:`!tk_busy_current`. @@ -1952,17 +2012,19 @@ Base and mixin classes .. method:: winfo_atom(name, displayof=0) - Return the integer identifier for the atom whose name is *name*, - creating a new atom if none exists. If *displayof* is given, the atom is - looked up on the display of that window; otherwise it is looked up on the - display of the application's main window. + Return the integer identifier for the atom whose name is *name*, creating + a new atom if none exists. + If *displayof* is given, the atom is looked up on the display of that + window; otherwise it is looked up on the display of the application's + main window. .. method:: winfo_atomname(id, displayof=0) Return the textual name for the atom whose integer identifier is *id*. - This is the inverse of :meth:`winfo_atom`. If *displayof* is given, the - identifier is looked up on the display of that window; otherwise it is - looked up on the display of the application's main window. + This is the inverse of :meth:`winfo_atom`. + If *displayof* is given, the identifier is looked up on the display of + that window; otherwise it is looked up on the display of the + application's main window. .. method:: winfo_cells() @@ -1971,8 +2033,8 @@ Base and mixin classes .. method:: winfo_children() Return a list containing the widgets that are children of the widget, in - stacking order from lowest to highest. Toplevel windows are returned as - children of their logical parents. + stacking order from lowest to highest. + Toplevel windows are returned as children of their logical parents. .. method:: winfo_class() @@ -1986,11 +2048,12 @@ Base and mixin classes .. method:: winfo_containing(rootX, rootY, displayof=0) Return the widget containing the point given by *rootX* and *rootY*, or - ``None`` if no window in this application contains the point. The - coordinates are in screen units in the coordinate system of the root - window. If *displayof* is given, the coordinates refer to the screen - containing that window; otherwise they refer to the screen of the - application's main window. + ``None`` if no window in this application contains the point. + The coordinates are in screen units in the coordinate system of the root + window. + If *displayof* is given, the coordinates refer to the screen containing + that window; otherwise they refer to the screen of the application's main + window. .. method:: winfo_depth() @@ -2004,31 +2067,35 @@ Base and mixin classes Return a floating-point value giving the number of pixels in the widget corresponding to the screen distance *number* (e.g. ``"2.0c"`` or - ``"1i"``). The result may be fractional; for a rounded integer value use + ``"1i"``). + The result may be fractional; for a rounded integer value use :meth:`winfo_pixels`. .. method:: winfo_geometry() - Return the geometry of the widget, in the form ``widthxheight+x+y``. All - dimensions are in pixels. + Return the geometry of the widget, in the form ``widthxheight+x+y``. + All dimensions are in pixels. .. method:: winfo_height() - Return the height of the widget in pixels. When a window is first created - its height is 1 pixel; it is eventually changed by a geometry manager. + Return the height of the widget in pixels. + When a window is first created its height is 1 pixel; it is eventually + changed by a geometry manager. See also :meth:`winfo_reqheight`. .. method:: winfo_id() - Return a low-level platform-specific identifier for the widget. On Unix - this is the X window identifier, and on Windows it is the window handle. + Return a low-level platform-specific identifier for the widget. + On Unix this is the X window identifier, and on Windows it is the window + handle. .. method:: winfo_interps(displayof=0) Return a tuple of the names of all Tcl interpreters currently registered - for a particular display. If *displayof* is given, the return value - refers to the display of that window; otherwise it refers to the display - of the application's main window. + for a particular display. + If *displayof* is given, the return value refers to the display of that + window; otherwise it refers to the display of the application's main + window. .. method:: winfo_ismapped() @@ -2051,22 +2118,23 @@ Base and mixin classes .. method:: winfo_pathname(id, displayof=0) - Return the path name of the window whose identifier is *id*. If - *displayof* is given, the identifier is looked up on the display of that - window; otherwise it is looked up on the display of the application's main - window. + Return the path name of the window whose identifier is *id*. + If *displayof* is given, the identifier is looked up on the display of + that window; otherwise it is looked up on the display of the + application's main window. .. method:: winfo_pixels(number) Return the number of pixels in the widget corresponding to the screen - distance *number* (e.g. ``"2.0c"`` or ``"1i"``). The result is rounded to - the nearest integer; for a fractional result use :meth:`winfo_fpixels`. + distance *number* (e.g. ``"2.0c"`` or ``"1i"``). + The result is rounded to the nearest integer; for a fractional result use + :meth:`winfo_fpixels`. .. method:: winfo_pointerx() Return the pointer's *x* coordinate, in pixels, relative to the screen's - root window (or virtual root, if one is in use). Return ``-1`` if the - pointer is not on the same screen as the widget. + root window (or virtual root, if one is in use). + Return ``-1`` if the pointer is not on the same screen as the widget. .. method:: winfo_pointerxy() @@ -2078,24 +2146,27 @@ Base and mixin classes .. method:: winfo_pointery() Return the pointer's *y* coordinate, in pixels, relative to the screen's - root window (or virtual root, if one is in use). Return ``-1`` if the - pointer is not on the same screen as the widget. + root window (or virtual root, if one is in use). + Return ``-1`` if the pointer is not on the same screen as the widget. .. method:: winfo_reqheight() - Return the widget's requested height in pixels. This is the value used by - the widget's geometry manager to compute its geometry. + Return the widget's requested height in pixels. + This is the value used by the widget's geometry manager to compute its + geometry. .. method:: winfo_reqwidth() - Return the widget's requested width in pixels. This is the value used by - the widget's geometry manager to compute its geometry. + Return the widget's requested width in pixels. + This is the value used by the widget's geometry manager to compute its + geometry. .. method:: winfo_rgb(color) Return an ``(r, g, b)`` tuple of the red, green, and blue intensities, in - the range 0 to 65535, that correspond to *color* in the widget. *color* - may be specified in any of the forms acceptable for a color option. + the range 0 to 65535, that correspond to *color* in the widget. + *color* may be specified in any of the forms acceptable for a color + option. .. method:: winfo_rootx() @@ -2149,13 +2220,13 @@ Base and mixin classes .. method:: winfo_server() Return a string containing information about the server for the widget's - display. The exact format of this string may vary from platform to - platform. + display. + The exact format of this string may vary from platform to platform. .. method:: winfo_toplevel() - Return the top-of-hierarchy window containing the widget. In standard Tk - this is always a :class:`Toplevel` widget. + Return the top-of-hierarchy window containing the widget. + In standard Tk this is always a :class:`Toplevel` widget. .. method:: winfo_viewable() @@ -2176,13 +2247,14 @@ Base and mixin classes Return a list describing the visuals available for the widget's screen. Each item consists of a visual class (see :meth:`winfo_visual`) followed - by an integer depth. If *includeids* is true, the X identifier for the - visual is also included. + by an integer depth. + If *includeids* is true, the X identifier for the visual is also + included. .. method:: winfo_vrootheight() - Return the height of the virtual root window associated with the widget if - there is one; otherwise return the height of the widget's screen. + Return the height of the virtual root window associated with the widget + if there is one; otherwise return the height of the widget's screen. .. method:: winfo_vrootwidth() @@ -2192,20 +2264,23 @@ Base and mixin classes .. method:: winfo_vrootx() Return the *x* offset of the virtual root window associated with the - widget, relative to the root window of its screen. This is normally zero - or negative, and is ``0`` if there is no virtual root window. + widget, relative to the root window of its screen. + This is normally zero or negative, and is ``0`` if there is no virtual + root window. .. method:: winfo_vrooty() Return the *y* offset of the virtual root window associated with the - widget, relative to the root window of its screen. This is normally zero - or negative, and is ``0`` if there is no virtual root window. + widget, relative to the root window of its screen. + This is normally zero or negative, and is ``0`` if there is no virtual + root window. .. method:: winfo_width() - Return the width of the widget in pixels. When a window is first created - its width is 1 pixel; it is eventually changed by a geometry manager. See - also :meth:`winfo_reqwidth`. + Return the width of the widget in pixels. + When a window is first created its width is 1 pixel; it is eventually + changed by a geometry manager. + See also :meth:`winfo_reqwidth`. .. method:: winfo_x() @@ -2232,10 +2307,11 @@ Base and mixin classes The :class:`!Wm` mixin provides access to the window manager, allowing an application to control such things as the title, geometry and icon of a top-level window, the way it is resized, and how it responds to window - manager protocols. It is mixed into :class:`Tk` and :class:`Toplevel`, so - its methods are available on every top-level window. Each method has two - equivalent spellings: a short name and a ``wm_``-prefixed name (for example, - :meth:`title` and :meth:`wm_title`). + manager protocols. + It is mixed into :class:`Tk` and :class:`Toplevel`, so its methods are + available on every top-level window. + Each method has two equivalent spellings: a short name and a + ``wm_``-prefixed name (for example, :meth:`title` and :meth:`wm_title`). .. method:: wm_aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) :no-typesetting: @@ -2245,28 +2321,30 @@ Base and mixin classes Constrain the aspect ratio (the ratio of width to height) of the window. 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_aspect`) is an equivalent alias. + 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. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_aspect`) is an equivalent + alias. .. method:: wm_attributes(*args, return_python_dict=False, **kwargs) :no-typesetting: .. method:: attributes(*args, return_python_dict=False, **kwargs) - Query or set platform-specific attributes of the window. With no - arguments, return the platform-specific flags and their values; pass - *return_python_dict* as true to get them as a dictionary. A single - option name such as ``'-alpha'`` returns the value of that option, and - options may be set either positionally (``'-alpha', 0.5``) or as keyword - arguments (``alpha=0.5``). The available attributes differ by platform; - all platforms support ``-alpha`` (transparency from ``0.0`` to ``1.0``), - ``-fullscreen`` and ``-topmost``, while Windows, macOS and X11 each add - further options. On X11 changes are applied asynchronously, so a queried - value may not yet reflect the most recent request. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_attributes`) is an equivalent - alias. + Query or set platform-specific attributes of the window. + With no arguments, return the platform-specific flags and their values; + pass *return_python_dict* as true to get them as a dictionary. + A single option name such as ``'-alpha'`` returns the value of that + option, and options may be set either positionally (``'-alpha', 0.5``) or + as keyword arguments (``alpha=0.5``). + The available attributes differ by platform; all platforms support + ``-alpha`` (transparency from ``0.0`` to ``1.0``), ``-fullscreen`` and + ``-topmost``, while Windows, macOS and X11 each add further options. + On X11 changes are applied asynchronously, so a queried value may not yet + reflect the most recent request. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_attributes`) is an + equivalent alias. .. versionchanged:: 3.13 A single attribute may now be queried by name without the leading @@ -2280,10 +2358,12 @@ Base and mixin classes .. method:: client(name=None) Store *name*, which should be the name of the host on which the - application is running, in the window's ``WM_CLIENT_MACHINE`` property for - use by the window or session manager. An empty string deletes the - property. With no argument, return the last name set, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_client`) is an equivalent alias. + application is running, in the window's ``WM_CLIENT_MACHINE`` property + for use by the window or session manager. + An empty string deletes the property. + With no argument, return the last name set, or an empty string. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_client`) is an equivalent + alias. .. method:: wm_colormapwindows(*wlist) :no-typesetting: @@ -2291,10 +2371,11 @@ Base and mixin classes .. method:: colormapwindows(*wlist) Manipulate the ``WM_COLORMAP_WINDOWS`` property, which tells the window - manager about windows that have private colormaps. If *wlist* is given, - overwrite the property with those windows (their order is a priority order - for installing colormaps). With no arguments, return the list of windows - currently named in the property. + manager about windows that have private colormaps. + If *wlist* is given, overwrite the property with those windows (their + order is a priority order for installing colormaps). + With no arguments, return the list of windows currently named in the + property. The ``wm_``-prefixed spelling (e.g. ``wm_colormapwindows``) is an equivalent alias. @@ -2305,9 +2386,9 @@ Base and mixin classes Store *value* in the window's ``WM_COMMAND`` property for use by the window or session manager; it should be a list giving the words of the - command used to invoke the application. An empty string deletes the - property. With no argument, return the last value set, or an empty - string. + command used to invoke the application. + An empty string deletes the property. + With no argument, return the last value set, or an empty string. The ``wm_``-prefixed spelling (e.g. :meth:`wm_command`) is an equivalent alias. @@ -2316,26 +2397,28 @@ Base and mixin classes .. method:: deiconify() - Display the window in normal (non-iconified) form by mapping it. If the - window has never been mapped, this ensures it appears de-iconified when it - is first mapped. On Windows the window is also raised and given the - focus. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_deiconify`) is an equivalent - alias. + Display the window in normal (non-iconified) form by mapping it. + If the window has never been mapped, this ensures it appears de-iconified + when it is first mapped. + On Windows the window is also raised and given the focus. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_deiconify`) is an + equivalent alias. .. method:: wm_focusmodel(model=None) :no-typesetting: .. method:: focusmodel(model=None) - Set or query the focus model for the window. *model* is either - ``'active'`` (the window claims the input focus for itself or its - descendants, even when the focus is in another application) or - ``'passive'`` (the window relies on the window manager to give it the - focus). With no argument, return the current model. The default is - ``'passive'``, which is what the :meth:`!focus` command assumes. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_focusmodel`) is an equivalent - alias. + Set or query the focus model for the window. + *model* is either ``'active'`` (the window claims the input focus for + itself or its descendants, even when the focus is in another application) + or ``'passive'`` (the window relies on the window manager to give it the + focus). + With no argument, return the current model. + The default is ``'passive'``, which is what the :meth:`!focus` command + assumes. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_focusmodel`) is an + equivalent alias. .. method:: wm_forget(window) :no-typesetting: @@ -2343,10 +2426,12 @@ Base and mixin classes .. method:: forget(window) Unmap *window* from the screen so that it is no longer managed by the - window manager. A :class:`Toplevel` is then treated like a :class:`Frame`, - although its ``-menu`` configuration is remembered and the menu reappears - if the widget is managed again. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_forget`) is an equivalent alias. + window manager. + A :class:`Toplevel` is then treated like a :class:`Frame`, although its + ``-menu`` configuration is remembered and the menu reappears if the + widget is managed again. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_forget`) is an equivalent + alias. .. versionadded:: 3.3 @@ -2359,21 +2444,24 @@ Base and mixin classes decorative frame containing the window, if the window manager has reparented it into such a frame; otherwise return the identifier of the window itself. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_frame`) is an equivalent alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_frame`) is an equivalent + alias. .. method:: wm_geometry(newGeometry=None) :no-typesetting: .. method:: geometry(newGeometry=None) - Set or query the geometry of the window. *newGeometry* has the form - ``=widthxheight+x+y``, where any of ``=``, ``widthxheight`` and the - ``+x+y`` position may be omitted. *width* and *height* are in pixels (or - grid units for a gridded window); a position preceded by ``+`` is measured - from the left or top edge of the screen and one preceded by ``-`` from the - right or bottom edge. An empty string cancels any user-specified geometry, - letting the window revert to its natural size. With no argument, return - the current geometry as a string of the form ``'200x200+10+10'``. + Set or query the geometry of the window. + *newGeometry* has the form ``=widthxheight+x+y``, where any of ``=``, + ``widthxheight`` and the ``+x+y`` position may be omitted. + *width* and *height* are in pixels (or grid units for a gridded window); + a position preceded by ``+`` is measured from the left or top edge of the + screen and one preceded by ``-`` from the right or bottom edge. + An empty string cancels any user-specified geometry, letting the window + revert to its natural size. + With no argument, return the current geometry as a string of the form + ``'200x200+10+10'``. The ``wm_``-prefixed spelling (e.g. :meth:`wm_geometry`) is an equivalent alias. @@ -2383,25 +2471,30 @@ Base and mixin classes .. method:: grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) Manage the window as a gridded window and define the relationship between - grid units and pixels. *baseWidth* and *baseHeight* are the numbers of - grid units for the 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_grid`) is an equivalent alias. + grid units and pixels. + *baseWidth* and *baseHeight* are the numbers of grid units for the + 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. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_grid`) is an equivalent + alias. .. method:: wm_group(pathName=None) :no-typesetting: .. method:: group(pathName=None) - Set or query the leader of a group of related windows. *pathName* gives - the path name of the group leader; the window manager may, for example, - unmap all windows in the group when the leader is iconified. An empty - string removes the window from any group. With no argument, return the - path name of the current group leader, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_group`) is an equivalent alias. + Set or query the leader of a group of related windows. + *pathName* gives the path name of the group leader; the window manager + may, for example, unmap all windows in the group when the leader is + iconified. + An empty string removes the window from any group. + With no argument, return the path name of the current group leader, or an + empty string. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_group`) is an equivalent + alias. .. method:: wm_iconbitmap(bitmap=None, default=None) :no-typesetting: @@ -2410,22 +2503,24 @@ Base and mixin classes Set or query the bitmap used by the window manager for the window's icon. *bitmap* names a bitmap in one of the standard forms accepted by Tk; an - empty string cancels the current icon bitmap. With no argument, return - the name of the current icon bitmap, or an empty string. On Windows the - *default* argument names an icon (for example an ``.ico`` file) applied to - all top-level windows that have no icon of their own. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconbitmap`) is an equivalent - alias. + empty string cancels the current icon bitmap. + With no argument, return the name of the current icon bitmap, or an empty + string. + On Windows the *default* argument names an icon (for example an ``.ico`` + file) applied to all top-level windows that have no icon of their own. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconbitmap`) is an + equivalent alias. .. method:: wm_iconify() :no-typesetting: .. method:: iconify() - Iconify the window. If the window has not yet been mapped for the first - time, arrange for it to appear in the iconified state when it is - eventually mapped. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconify`) is an equivalent alias. + Iconify the window. + If the window has not yet been mapped for the first time, arrange for it + to appear in the iconified state when it is eventually mapped. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconify`) is an equivalent + alias. .. method:: wm_iconmask(bitmap=None) :no-typesetting: @@ -2433,10 +2528,12 @@ Base and mixin classes .. method:: iconmask(bitmap=None) Set or query the bitmap used as a mask for the icon (see - :meth:`iconbitmap`). Where the mask is zero no icon is displayed; where it - is one, the corresponding bits of the icon bitmap are shown. An empty - string cancels the current mask. With no argument, return the name of the - current icon mask, or an empty string. + :meth:`iconbitmap`). + Where the mask is zero no icon is displayed; where it is one, the + corresponding bits of the icon bitmap are shown. + An empty string cancels the current mask. + With no argument, return the name of the current icon mask, or an empty + string. The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconmask`) is an equivalent alias. @@ -2446,9 +2543,10 @@ Base and mixin classes .. method:: iconname(newName=None) Set or query the name displayed by the window manager inside the window's - icon. With no argument, return the current icon name, or an empty string - if none has been set (in which case the window manager normally displays - the window's title). + icon. + With no argument, return the current icon name, or an empty string if + none has been set (in which case the window manager normally displays the + window's title). The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconname`) is an equivalent alias. @@ -2457,16 +2555,17 @@ Base and mixin classes .. method:: iconphoto(default=False, *images) - Set the titlebar icon for the window from one or more - :class:`PhotoImage` objects given in *images*. Several images of different - sizes (for example 16x16 and 32x32) may be supplied so that the window - manager can choose an appropriate one. The image data is taken as a - snapshot at the time of the call; later changes to the images are not - reflected. If *default* is true, the icon is also applied to all - top-level windows created in the future. On macOS only the first image is - used. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconphoto`) is an equivalent - alias. + Set the titlebar icon for the window from one or more :class:`PhotoImage` + objects given in *images*. + Several images of different sizes (for example 16x16 and 32x32) may be + supplied so that the window manager can choose an appropriate one. + The image data is taken as a snapshot at the time of the call; later + changes to the images are not reflected. + If *default* is true, the icon is also applied to all top-level windows + created in the future. + On macOS only the first image is used. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconphoto`) is an + equivalent alias. .. versionadded:: 3.3 @@ -2476,25 +2575,28 @@ Base and mixin classes .. method:: iconposition(x=None, y=None) 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconposition`) is an equivalent - alias. + 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. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconposition`) is an + equivalent alias. .. method:: wm_iconwindow(pathName=None) :no-typesetting: .. method:: iconwindow(pathName=None) - Set or query the window used as the icon for the window. When the window - is iconified, *pathName* is mapped to serve as its icon and unmapped again - when it is de-iconified. An empty string cancels the association. With no - argument, return the path name of the current icon window, or an empty - string. Not all window managers support icon windows, and the concept is + Set or query the window used as the icon for the window. + When the window is iconified, *pathName* is mapped to serve as its icon + and unmapped again when it is de-iconified. + An empty string cancels the association. + With no argument, return the path name of the current icon window, or an + empty string. + Not all window managers support icon windows, and the concept is meaningless on non-X11 platforms. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconwindow`) is an equivalent - alias. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconwindow`) is an + equivalent alias. .. method:: wm_manage(widget) :no-typesetting: @@ -2502,10 +2604,11 @@ Base and mixin classes .. method:: manage(widget) Make *widget* a stand-alone top-level window, decorated by the window - manager with a title bar and so on. Only :class:`Frame`, - :class:`LabelFrame` and :class:`Toplevel` widgets may be used; passing any - other widget type raises an error. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_manage`) is an equivalent alias. + manager with a title bar and so on. + Only :class:`Frame`, :class:`LabelFrame` and :class:`Toplevel` widgets + may be used; passing any other widget type raises an error. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_manage`) is an equivalent + alias. .. versionadded:: 3.3 @@ -2515,11 +2618,14 @@ Base and mixin classes .. method:: maxsize(width=None, height=None) Set or query the maximum permissible dimensions of the window, in pixels - (or grid units for a gridded window). The window manager restricts the - window to be no larger than *width* and *height*. With no arguments, - return a tuple of the current maximum width and height. The maximum size - defaults to the size of the screen. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_maxsize`) is an equivalent alias. + (or grid units for a gridded window). + The window manager restricts the window to be no larger than *width* and + *height*. + With no arguments, return a tuple of the current maximum width and + height. + The maximum size defaults to the size of the screen. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_maxsize`) is an equivalent + alias. .. method:: wm_minsize(width=None, height=None) :no-typesetting: @@ -2527,23 +2633,27 @@ Base and mixin classes .. method:: minsize(width=None, height=None) Set or query the minimum permissible dimensions of the window, in pixels - (or grid units for a gridded window). The window manager restricts the - window to be no smaller than *width* and *height*. With no arguments, - return a tuple of the current minimum width and height. The minimum size - defaults to one pixel in each dimension. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_minsize`) is an equivalent alias. + (or grid units for a gridded window). + The window manager restricts the window to be no smaller than *width* and + *height*. + With no arguments, return a tuple of the current minimum width and + height. + The minimum size defaults to one pixel in each dimension. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_minsize`) is an equivalent + alias. .. method:: wm_overrideredirect(boolean=None) :no-typesetting: .. method:: overrideredirect(boolean=None) - Set or query the override-redirect flag for the window. 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. The flag is reliably honored only when - the window is first mapped or remapped from the withdrawn state. + Set or query the override-redirect flag for the window. + 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. + The flag is reliably honored only when the window is first mapped or + remapped from the withdrawn state. The ``wm_``-prefixed spelling (e.g. ``wm_overrideredirect``) is an equivalent alias. @@ -2552,15 +2662,16 @@ Base and mixin classes .. method:: positionfrom(who=None) - Set or query the source of the window's current position. *who* is either - ``'program'`` or ``'user'`` and indicates whether the position was - requested by the program or by the user; an empty string cancels the - current source. With no argument, return the current source, or an empty - string if none has been set. Tk automatically sets the source to - ``'user'`` when :meth:`geometry` is called, unless it has been set - explicitly to ``'program'``. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_positionfrom`) is an equivalent - alias. + Set or query the source of the window's current position. + *who* is either ``'program'`` or ``'user'`` and indicates whether the + position was requested by the program or by the user; an empty string + cancels the current source. + With no argument, return the current source, or an empty string if none + has been set. + Tk automatically sets the source to ``'user'`` when :meth:`geometry` is + called, unless it has been set explicitly to ``'program'``. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_positionfrom`) is an + equivalent alias. .. method:: wm_protocol(name=None, func=None) :no-typesetting: @@ -2570,12 +2681,13 @@ Base and mixin classes Register *func* as the handler for the window manager protocol *name*, an atom such as ``'WM_DELETE_WINDOW'``, ``'WM_SAVE_YOURSELF'`` or ``'WM_TAKE_FOCUS'``; *func* is then called whenever the window manager - sends a message of that protocol. Tk installs a default - ``WM_DELETE_WINDOW`` handler that destroys the window, which this method - can replace. If *func* is an empty string, the handler is removed. With - only *name*, return the name of its registered handler command, or an empty - string if none is set (the default ``WM_DELETE_WINDOW`` handler is not - reported); with no arguments, return a tuple of the protocols that + sends a message of that protocol. + Tk installs a default ``WM_DELETE_WINDOW`` handler that destroys the + window, which this method can replace. + If *func* is an empty string, the handler is removed. + With only *name*, return the name of its registered handler command, or + an empty string if none is set (the default ``WM_DELETE_WINDOW`` handler + is not reported); with no arguments, return a tuple of the protocols that currently have handlers. The ``wm_``-prefixed spelling (e.g. :meth:`wm_protocol`) is an equivalent alias. @@ -2585,24 +2697,26 @@ Base and mixin classes .. method:: resizable(width=None, height=None) - Control whether the user may interactively resize the window. *width* and - *height* are boolean values that determine whether the window's width and - height may be changed. With no arguments, return a tuple of two ``0``/``1`` - values indicating whether each dimension is currently resizable. By - default a window is resizable in both dimensions. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_resizable`) is an equivalent - alias. + Control whether the user may interactively resize the window. + *width* and *height* are boolean values that determine whether the + window's width and height may be changed. + With no arguments, return a tuple of two ``0``/``1`` values indicating + whether each dimension is currently resizable. + By default a window is resizable in both dimensions. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_resizable`) is an + equivalent alias. .. method:: wm_sizefrom(who=None) :no-typesetting: .. method:: sizefrom(who=None) - Set or query the source of the window's current size. *who* is either - ``'program'`` or ``'user'`` and indicates whether the size was requested by - the program or by the user; an empty string cancels the current source. - With no argument, return the current source, or an empty string if none has - been set. + Set or query the source of the window's current size. + *who* is either ``'program'`` or ``'user'`` and indicates whether the + size was requested by the program or by the user; an empty string cancels + the current source. + With no argument, return the current source, or an empty string if none + has been set. The ``wm_``-prefixed spelling (e.g. :meth:`wm_sizefrom`) is an equivalent alias. @@ -2611,13 +2725,15 @@ Base and mixin classes .. method:: state(newstate=None) - Set or query the state of the window. With no argument, return the current - state: one of ``'normal'``, ``'iconic'``, ``'withdrawn'``, ``'icon'`` or, - on Windows and macOS only, ``'zoomed'``. ``'iconic'`` refers to a window - that has been iconified, while ``'icon'`` refers to a window serving as the - icon for another window (see :meth:`iconwindow`); the ``'icon'`` state - cannot be set. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_state`) is an equivalent alias. + Set or query the state of the window. + With no argument, return the current state: one of ``'normal'``, + ``'iconic'``, ``'withdrawn'``, ``'icon'`` or, on Windows and macOS only, + ``'zoomed'``. + ``'iconic'`` refers to a window that has been iconified, while ``'icon'`` + refers to a window serving as the icon for another window (see + :meth:`iconwindow`); the ``'icon'`` state cannot be set. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_state`) is an equivalent + alias. .. method:: wm_title(string=None) :no-typesetting: @@ -2625,23 +2741,28 @@ Base and mixin classes .. method:: title(string=None) Set or query the title for the window, which the window manager should - display in the window's title bar. With no argument, return the current - title. The title defaults to the window's name. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_title`) is an equivalent alias. + display in the window's title bar. + With no argument, return the current title. + The title defaults to the window's name. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_title`) is an equivalent + alias. .. method:: wm_transient(master=None) :no-typesetting: .. method:: transient(master=None) - Mark the window as a transient window (such as a pull-down menu or dialog) - working on behalf of *master*, the path name of another top-level window. - An empty string clears the transient status. With no argument, return the - path name of the current master, or an empty string. A transient window - mirrors state changes in its master and may be decorated differently by the - window manager; it is an error to make a window a transient of itself. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_transient`) is an equivalent - alias. + Mark the window as a transient window (such as a pull-down menu or + dialog) working on behalf of *master*, the path name of another top-level + window. + An empty string clears the transient status. + With no argument, return the path name of the current master, or an empty + string. + A transient window mirrors state changes in its master and may be + decorated differently by the window manager; it is an error to make a + window a transient of itself. + The ``wm_``-prefixed spelling (e.g. :meth:`wm_transient`) is an + equivalent alias. .. method:: wm_withdraw() :no-typesetting: @@ -2649,10 +2770,12 @@ Base and mixin classes .. method:: withdraw() Withdraw the window from the screen, unmapping it and causing the window - manager to forget about it. If the window has never been mapped, it is - instead mapped in the withdrawn state. It is sometimes necessary to - withdraw a window and then re-map it (for example with :meth:`deiconify`) - to make some window managers notice changes to window attributes. + manager to forget about it. + If the window has never been mapped, it is instead mapped in the + withdrawn state. + It is sometimes necessary to withdraw a window and then re-map it (for + example with :meth:`deiconify`) to make some window managers notice + changes to window attributes. The ``wm_``-prefixed spelling (e.g. :meth:`wm_withdraw`) is an equivalent alias. @@ -2660,9 +2783,11 @@ Base and mixin classes .. class:: Pack() Geometry manager that arranges widgets by packing them against the sides of - their container. The :class:`!Pack` mix-in is inherited by all widgets - (through :class:`Widget`) and provides the methods for managing a widget with - the *pack* geometry manager. See also :ref:`pack-the-packer`. + their container. + The :class:`!Pack` mix-in is inherited by all widgets (through + :class:`Widget`) and provides the methods for managing a widget with the + *pack* geometry manager. + See also :ref:`pack-the-packer`. .. method:: configure(cnf={}, **kw) :no-typesetting: @@ -2674,12 +2799,13 @@ Base and mixin classes pack(cnf={}, **kw) Pack the widget inside its container, positioning it relative to the - siblings already packed there. Options such as *side* - (``'top'``, ``'bottom'``, ``'left'`` or ``'right'``), *fill* - (``'x'``, ``'y'``, ``'both'`` or ``'none'``), *expand*, *anchor*, - *padx*/*pady*, *ipadx*/*ipady* and *in_* control the placement; see the Tk - ``pack`` manual page for the full list. :meth:`pack`, :meth:`configure` - and :meth:`config` are aliases of :meth:`!pack_configure`. + siblings already packed there. + Options such as *side* (``'top'``, ``'bottom'``, ``'left'`` or + ``'right'``), *fill* (``'x'``, ``'y'``, ``'both'`` or ``'none'``), + *expand*, *anchor*, *padx*/*pady*, *ipadx*/*ipady* and *in_* control the + placement; see the Tk ``pack`` manual page for the full list. + :meth:`pack`, :meth:`configure` and :meth:`config` are aliases of + :meth:`!pack_configure`. .. method:: forget() :no-typesetting: @@ -2687,9 +2813,9 @@ Base and mixin classes .. method:: pack_forget() Unmap the widget and remove it from the packing order, forgetting its - packing options. It can be packed again later with - :meth:`pack_configure`. :meth:`forget` is an alias of - :meth:`!pack_forget`. + packing options. + It can be packed again later with :meth:`pack_configure`. + :meth:`forget` is an alias of :meth:`!pack_forget`. .. method:: info() :no-typesetting: @@ -2707,8 +2833,8 @@ Base and mixin classes pack_propagate(flag) Same as :meth:`Misc.pack_propagate`, treating this widget as a container: - enable or disable geometry propagation. :meth:`propagate` is an alias of - :meth:`!pack_propagate`. + enable or disable geometry propagation. + :meth:`propagate` is an alias of :meth:`!pack_propagate`. .. method:: slaves() :no-typesetting: @@ -2716,22 +2842,24 @@ Base and mixin classes .. method:: pack_slaves() Same as :meth:`Misc.pack_slaves`: return the list of widgets packed in - this widget. :meth:`slaves` is an alias of :meth:`!pack_slaves`. + this widget. + :meth:`slaves` is an alias of :meth:`!pack_slaves`. .. method:: content() :no-typesetting: .. method:: pack_content() - Same as :meth:`Misc.pack_content`. :meth:`content` is an alias of - :meth:`!pack_content`. + Same as :meth:`Misc.pack_content`. + :meth:`content` is an alias of :meth:`!pack_content`. .. class:: Place() Geometry manager that places widgets at explicit positions and sizes within - their container. The :class:`!Place` mix-in is inherited by all widgets - (through :class:`Widget`). + their container. + The :class:`!Place` mix-in is inherited by all widgets (through + :class:`Widget`). .. method:: configure(cnf={}, **kw) :no-typesetting: @@ -2742,12 +2870,14 @@ Base and mixin classes .. method:: place_configure(cnf={}, **kw) place(cnf={}, **kw) - Place the widget inside its container at an absolute or relative position. + Place the widget inside its container at an absolute or relative + position. Options include *x*/*y* and *relx*/*rely* (absolute and fractional position), *width*/*height* and *relwidth*/*relheight* (absolute and fractional size), *anchor*, *bordermode* and *in_*; see the Tk ``place`` - manual page. :meth:`place`, :meth:`configure` and :meth:`config` are - aliases of :meth:`!place_configure`. + manual page. + :meth:`place`, :meth:`configure` and :meth:`config` are aliases of + :meth:`!place_configure`. .. method:: forget() :no-typesetting: @@ -2755,7 +2885,8 @@ Base and mixin classes .. method:: place_forget() Unmap the widget and remove it from the placement, forgetting its place - options. :meth:`forget` is an alias of :meth:`!place_forget`. + options. + :meth:`forget` is an alias of :meth:`!place_forget`. .. method:: info() :no-typesetting: @@ -2771,22 +2902,24 @@ Base and mixin classes .. method:: place_slaves() Same as :meth:`Misc.place_slaves`: return the list of widgets placed in - this widget. :meth:`slaves` is an alias of :meth:`!place_slaves`. + this widget. + :meth:`slaves` is an alias of :meth:`!place_slaves`. .. method:: content() :no-typesetting: .. method:: place_content() - Same as :meth:`Misc.place_content`. :meth:`content` is an alias of - :meth:`!place_content`. + Same as :meth:`Misc.place_content`. + :meth:`content` is an alias of :meth:`!place_content`. .. class:: Grid() Geometry manager that arranges widgets in a two-dimensional grid of rows and - columns within their container. The :class:`!Grid` mix-in is inherited by - all widgets (through :class:`Widget`). + columns within their container. + The :class:`!Grid` mix-in is inherited by all widgets (through + :class:`Widget`). .. method:: configure(cnf={}, **kw) :no-typesetting: @@ -2797,10 +2930,11 @@ Base and mixin classes .. method:: grid_configure(cnf={}, **kw) grid(cnf={}, **kw) - Position the widget in a cell of its container's grid. Options include - *row*/*column*, *rowspan*/*columnspan*, *sticky*, *padx*/*pady*, - *ipadx*/*ipady* and *in_*; see the Tk ``grid`` manual page. :meth:`grid`, - :meth:`configure` and :meth:`config` are aliases of + Position the widget in a cell of its container's grid. + Options include *row*/*column*, *rowspan*/*columnspan*, *sticky*, + *padx*/*pady*, *ipadx*/*ipady* and *in_*; see the Tk ``grid`` manual + page. + :meth:`grid`, :meth:`configure` and :meth:`config` are aliases of :meth:`!grid_configure`. .. method:: forget() @@ -2808,7 +2942,8 @@ Base and mixin classes .. method:: grid_forget() - Unmap the widget and remove it from the grid, forgetting its grid options. + Unmap the widget and remove it from the grid, forgetting its grid + options. :meth:`forget` is an alias of :meth:`!grid_forget`. .. method:: grid_remove() @@ -2829,24 +2964,24 @@ Base and mixin classes .. method:: grid_anchor(anchor=None) - Same as :meth:`Misc.grid_anchor`. :meth:`anchor` is an alias of - :meth:`!grid_anchor`. + Same as :meth:`Misc.grid_anchor`. + :meth:`anchor` is an alias of :meth:`!grid_anchor`. .. method:: bbox(column=None, row=None, col2=None, row2=None) :no-typesetting: .. method:: grid_bbox(column=None, row=None, col2=None, row2=None) - Same as :meth:`Misc.grid_bbox`. :meth:`bbox` is an alias of - :meth:`!grid_bbox`. + Same as :meth:`Misc.grid_bbox`. + :meth:`bbox` is an alias of :meth:`!grid_bbox`. .. method:: columnconfigure(index, cnf={}, **kw) :no-typesetting: .. method:: grid_columnconfigure(index, cnf={}, **kw) - Same as :meth:`Misc.grid_columnconfigure`: query or set the options - (such as *weight*, *minsize*, *pad* and *uniform*) of a grid column. + Same as :meth:`Misc.grid_columnconfigure`: query or set the options (such + as *weight*, *minsize*, *pad* and *uniform*) of a grid column. :meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. .. method:: rowconfigure(index, cnf={}, **kw) @@ -2854,8 +2989,9 @@ Base and mixin classes .. method:: grid_rowconfigure(index, cnf={}, **kw) - Same as :meth:`Misc.grid_rowconfigure`: query or set the options of a grid - row. :meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. + Same as :meth:`Misc.grid_rowconfigure`: query or set the options of a + grid row. + :meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. .. method:: location(x, y) :no-typesetting: @@ -2863,8 +2999,8 @@ Base and mixin classes .. method:: grid_location(x, y) Same as :meth:`Misc.grid_location`: return the ``(column, row)`` of the - cell that covers the pixel at *x*, *y*. :meth:`location` is an alias of - :meth:`!grid_location`. + cell that covers the pixel at *x*, *y*. + :meth:`location` is an alias of :meth:`!grid_location`. .. method:: size() :no-typesetting: @@ -2872,7 +3008,8 @@ Base and mixin classes .. method:: grid_size() Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving - the size of the grid. :meth:`size` is an alias of :meth:`!grid_size`. + the size of the grid. + :meth:`size` is an alias of :meth:`!grid_size`. .. method:: propagate() propagate(flag) @@ -2881,8 +3018,8 @@ Base and mixin classes .. method:: grid_propagate() grid_propagate(flag) - Same as :meth:`Misc.grid_propagate`. :meth:`propagate` is an alias of - :meth:`!grid_propagate`. + Same as :meth:`Misc.grid_propagate`. + :meth:`propagate` is an alias of :meth:`!grid_propagate`. .. method:: slaves(row=None, column=None) :no-typesetting: @@ -2890,79 +3027,86 @@ Base and mixin classes .. method:: grid_slaves(row=None, column=None) Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid, - optionally restricted to a *row* and/or *column*. :meth:`slaves` is an - alias of :meth:`!grid_slaves`. + optionally restricted to a *row* and/or *column*. + :meth:`slaves` is an alias of :meth:`!grid_slaves`. .. method:: content(row=None, column=None) :no-typesetting: .. method:: grid_content(row=None, column=None) - Same as :meth:`Misc.grid_content`. :meth:`content` is an alias of - :meth:`!grid_content`. + Same as :meth:`Misc.grid_content`. + :meth:`content` is an alias of :meth:`!grid_content`. .. class:: XView() - Mix-in providing the horizontal-scrolling interface shared by widgets such as - :class:`Entry`, :class:`Canvas`, :class:`Listbox`, :class:`Text` and - :class:`Spinbox`. A widget's :meth:`xview` method is registered as the - *command* of a horizontal :class:`Scrollbar`. + Mix-in providing the horizontal-scrolling interface shared by widgets such + as :class:`Entry`, :class:`Canvas`, :class:`Listbox`, :class:`Text` and + :class:`Spinbox`. + A widget's :meth:`xview` method is registered as the *command* of a + horizontal :class:`Scrollbar`. .. method:: xview(*args) - Query or change the horizontal position of the view. With no arguments, - return a tuple ``(first, last)`` of two fractions between 0 and 1 giving - the portion of the document that is currently visible. Otherwise the - arguments are passed to the Tk ``xview`` widget command and are usually - generated by a scrollbar; :meth:`xview_moveto` and :meth:`xview_scroll` - provide a more convenient interface. + Query or change the horizontal position of the view. + With no arguments, return a tuple ``(first, last)`` of two fractions + between 0 and 1 giving the portion of the document that is currently + visible. + Otherwise the arguments are passed to the Tk ``xview`` widget command and + are usually generated by a scrollbar; :meth:`xview_moveto` and + :meth:`xview_scroll` provide a more convenient interface. .. method:: xview_moveto(fraction) Adjust the view so that *fraction* of the total width of the document is - off-screen to the left. *fraction* is a number between 0 and 1. + off-screen to the left. + *fraction* is a number between 0 and 1. .. method:: xview_scroll(number, what) - Shift the view left or right by *number* units. *what* is either - ``'units'`` or ``'pages'``; a negative *number* scrolls left and a - positive one scrolls right. + Shift the view left or right by *number* units. + *what* is either ``'units'`` or ``'pages'``; a negative *number* scrolls + left and a positive one scrolls right. .. class:: YView() Mix-in providing the vertical-scrolling interface shared by widgets such as - :class:`Canvas`, :class:`Listbox` and :class:`Text`. A widget's :meth:`yview` - method is registered as the *command* of a vertical :class:`Scrollbar`. + :class:`Canvas`, :class:`Listbox` and :class:`Text`. + A widget's :meth:`yview` method is registered as the *command* of a vertical + :class:`Scrollbar`. .. method:: yview(*args) - Query or change the vertical position of the view. With no arguments, - return a tuple ``(first, last)`` of two fractions between 0 and 1 giving - the portion of the document that is currently visible. Otherwise the - arguments are passed to the Tk ``yview`` widget command, usually generated - by a scrollbar; :meth:`yview_moveto` and :meth:`yview_scroll` provide a - more convenient interface. + Query or change the vertical position of the view. + With no arguments, return a tuple ``(first, last)`` of two fractions + between 0 and 1 giving the portion of the document that is currently + visible. + Otherwise the arguments are passed to the Tk ``yview`` widget command, + usually generated by a scrollbar; :meth:`yview_moveto` and + :meth:`yview_scroll` provide a more convenient interface. .. method:: yview_moveto(fraction) Adjust the view so that *fraction* of the total height of the document is - off-screen above the top. *fraction* is a number between 0 and 1. + off-screen above the top. + *fraction* is a number between 0 and 1. .. method:: yview_scroll(number, what) - Shift the view up or down by *number* units. *what* is either ``'units'`` - or ``'pages'``; a negative *number* scrolls up and a positive one scrolls - down. + Shift the view up or down by *number* units. + *what* is either ``'units'`` or ``'pages'``; a negative *number* scrolls + up and a positive one scrolls down. .. class:: BaseWidget(master, widgetName, cnf={}, kw={}, extra=()) - Internal base class for all widgets. It inherits from :class:`Misc` and - adds the machinery that creates the underlying Tk widget; application code - normally uses :class:`Widget` or a concrete widget class rather than - instantiating :class:`!BaseWidget` directly. + Internal base class for all widgets. + It inherits from :class:`Misc` and adds the machinery that creates the + underlying Tk widget; application code normally uses :class:`Widget` or a + concrete widget class rather than instantiating :class:`!BaseWidget` + directly. .. method:: destroy() @@ -2972,24 +3116,27 @@ Base and mixin classes .. class:: Widget(master, widgetName, cnf={}, kw={}, extra=()) - Internal base class for the standard widgets. It combines :class:`BaseWidget` - with the geometry-manager mix-ins :class:`Pack`, :class:`Place` and - :class:`Grid`, so that every widget can be managed by any of the three - geometry managers. The concrete widget classes (:class:`Button`, - :class:`Label`, and so on) derive from :class:`!Widget`. + Internal base class for the standard widgets. + It combines :class:`BaseWidget` with the geometry-manager mix-ins + :class:`Pack`, :class:`Place` and :class:`Grid`, so that every widget can be + managed by any of the three geometry managers. + The concrete widget classes (:class:`Button`, :class:`Label`, and so on) + derive from :class:`!Widget`. .. class:: Toplevel(master=None, cnf={}, **kw) A :class:`!Toplevel` widget is a top-level window, similar to a :class:`Frame` except that its X parent is the root window of a screen - rather than its logical parent. Its primary purpose is to serve as a - container for dialog boxes and other collections of widgets; its only - visible features are its background and an optional 3-D border. Notable - options include *menu*, which installs a :class:`Menu` as the window's - menubar. Inherits from :class:`BaseWidget` and :class:`Wm`, so a toplevel - is managed by the window manager. Refer to the Tk ``toplevel`` manual page - for the full list of options. + rather than its logical parent. + Its primary purpose is to serve as a container for dialog boxes and other + collections of widgets; its only visible features are its background and an + optional 3-D border. + Notable options include *menu*, which installs a :class:`Menu` as the + window's menubar. + Inherits from :class:`BaseWidget` and :class:`Wm`, so a toplevel is managed + by the window manager. + Refer to the Tk ``toplevel`` manual page for the full list of options. Widget classes @@ -3000,51 +3147,58 @@ Widget classes A :class:`!Button` widget displays a textual string, bitmap or image and invokes a command when the user presses it (by clicking mouse button 1 over the button or, when the button has focus, by pressing the space key). - Inherits from :class:`Widget`. In addition to the standard widget options, - a button accepts the options documented in the Tk ``button`` manual page, - such as *command* (the callback invoked when the button is pressed), - *textvariable*, *state* and *default*. + Inherits from :class:`Widget`. + In addition to the standard widget options, a button accepts the options + documented in the Tk ``button`` manual page, such as *command* (the callback + invoked when the button is pressed), *textvariable*, *state* and *default*. .. method:: invoke() Invoke the command associated with the button, if there is one, and return its result, or an empty string if no command is associated with - the button. This is ignored if the button's state is ``disabled``. + the button. + This is ignored if the button's state is ``disabled``. .. method:: flash() Flash the button by redisplaying it several times, alternating between - the active and normal colors. At the end of the flash the button is left - in the same normal or active state as when the method was called. This - is ignored if the button's state is ``disabled``. + the active and normal colors. + At the end of the flash the button is left in the same normal or active + state as when the method was called. + This is ignored if the button's state is ``disabled``. .. class:: Canvas(master=None, cnf={}, **kw) - A :class:`!Canvas` widget implements structured graphics. It displays any - number of *items*, such as arcs, lines, ovals, polygons, rectangles, text, - bitmaps, images and embedded windows, which may be drawn, moved, re-colored - and bound to events. Inherits from :class:`Widget`, :class:`XView` and - :class:`YView`, so the view can be scrolled horizontally and vertically with - :meth:`~XView.xview` and :meth:`~YView.yview`. Refer to the Tk ``canvas`` - manual page for the full list of widget and item options. - - Each item has a unique integer *id*, assigned when it is created, and zero or - more string *tags*. A tag is an arbitrary string that does not have the form - of an integer; the same tag may be shared by many items, which makes tags - convenient for grouping items. The special tag ``'all'`` matches every item - in the canvas, and ``'current'`` matches the topmost item under the mouse - pointer. Most methods take a *tagOrId* argument that may be an integer id - naming a single item, or a tag naming zero or more items; as described in the - Tk ``canvas`` manual page, a tag may also be a logical expression of tags + A :class:`!Canvas` widget implements structured graphics. + It displays any number of *items*, such as arcs, lines, ovals, polygons, + rectangles, text, bitmaps, images and embedded windows, which may be drawn, + moved, re-colored and bound to events. + Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the + view can be scrolled horizontally and vertically with :meth:`~XView.xview` + and :meth:`~YView.yview`. + Refer to the Tk ``canvas`` manual page for the full list of widget and item + options. + + Each item has a unique integer *id*, assigned when it is created, and zero + or more string *tags*. + A tag is an arbitrary string that does not have the form of an integer; the + same tag may be shared by many items, which makes tags convenient for + grouping items. + The special tag ``'all'`` matches every item in the canvas, and + ``'current'`` matches the topmost item under the mouse pointer. + Most methods take a *tagOrId* argument that may be an integer id naming a + single item, or a tag naming zero or more items; as described in the Tk + ``canvas`` manual page, a tag may also be a logical expression of tags combined with the operators ``&&``, ``||``, ``^``, ``!`` and parentheses. When a method that operates on a single item is given a *tagOrId* matching - several items, it normally uses the lowest matching item in the display list. + several items, it normally uses the lowest matching item in the display + list. The items are kept in a *display list* that determines drawing order: items - later in the list are drawn on top of earlier ones. A newly created item is - placed at the top of the list; the order can be changed with :meth:`tag_raise` - and :meth:`tag_lower`. + later in the list are drawn on top of earlier ones. + A newly created item is placed at the top of the list; the order can be + changed with :meth:`tag_raise` and :meth:`tag_lower`. .. method:: create_arc(*args, **kw) create_bitmap(*args, **kw) @@ -3057,40 +3211,41 @@ Widget classes create_window(*args, **kw) Create a new item of the corresponding type and return its integer id. - Each method is called as ``create_TYPE(coord..., **options)``: the leading - positional arguments give the coordinates that define the item (as - separate numbers, as a single sequence of numbers, or as coordinate - pairs), and the keyword arguments set item-specific options. Coordinates - and screen distances may be given as numbers (interpreted as pixels) or as - strings with a unit suffix (``'m'``, ``'c'``, ``'i'`` or ``'p'`` for - millimetres, centimetres, inches or printer's points), but are always - stored and returned in pixels. + Each method is called as ``create_TYPE(coord..., **options)``: the + leading positional arguments give the coordinates that define the item + (as separate numbers, as a single sequence of numbers, or as coordinate + pairs), and the keyword arguments set item-specific options. + Coordinates and screen distances may be given as numbers (interpreted as + pixels) or as strings with a unit suffix (``'m'``, ``'c'``, ``'i'`` or + ``'p'`` for millimetres, centimetres, inches or printer's points), but + are always stored and returned in pixels. The item types are: ``arc`` (an arc-shaped region that is a section of an - oval, defined by two diagonally opposite corners ``x1, y1, x2, y2`` of the - enclosing rectangle); ``bitmap`` (a two-color bitmap positioned at a point - ``x, y``); ``image`` (a Tk image positioned at a point ``x, y``); ``line`` - (a line or curve through the points ``x1, y1, ..., xn, yn``); ``oval`` (a - circle or ellipse inscribed in the rectangle ``x1, y1, x2, y2``); - ``polygon`` (a closed polygon through the points ``x1, y1, ..., xn, yn``); - ``rectangle`` (a rectangle with corners ``x1, y1, x2, y2``); ``text`` (a - string of text positioned at a point ``x, y``); and ``window`` (a child - widget embedded in the canvas at a point ``x, y``, specified with the - *window* option). + oval, defined by two diagonally opposite corners ``x1, y1, x2, y2`` of + the enclosing rectangle); ``bitmap`` (a two-color bitmap positioned at a + point ``x, y``); ``image`` (a Tk image positioned at a point ``x, y``); + ``line`` (a line or curve through the points ``x1, y1, ..., xn, yn``); + ``oval`` (a circle or ellipse inscribed in the rectangle + ``x1, y1, x2, y2``); ``polygon`` (a closed polygon through the points + ``x1, y1, ..., xn, yn``); ``rectangle`` (a rectangle with corners + ``x1, y1, x2, y2``); ``text`` (a string of text positioned at a point + ``x, y``); and ``window`` (a child widget embedded in the canvas at a + point ``x, y``, specified with the *window* option). .. method:: coords(tagOrId) coords(tagOrId, coordList, /) coords(tagOrId, /, *coordList) - Query or modify the coordinates of an item. With only *tagOrId*, return a - list of the floating-point coordinates of the item given by *tagOrId* (the - first matching item if it matches several). Given new coordinates, - replace the coordinates of that item with them; like the ``create_*`` - methods, the coordinates may be given as separate numbers, as a single - sequence, or as coordinate pairs. - The returned coordinates are always in pixels, regardless - of the units used to specify them; for rectangles, ovals and arcs they are - ordered left, top, right, bottom. + Query or modify the coordinates of an item. + With only *tagOrId*, return a list of the floating-point coordinates of + the item given by *tagOrId* (the first matching item if it matches + several). + Given new coordinates, replace the coordinates of that item with them; + like the ``create_*`` methods, the coordinates may be given as separate + numbers, as a single sequence, or as coordinate pairs. + The returned coordinates are always in pixels, regardless of the units + used to specify them; for rectangles, ovals and arcs they are ordered + left, top, right, bottom. .. versionchanged:: 3.12 The arguments are now flattened: the coordinates may be given as @@ -3100,17 +3255,18 @@ Widget classes .. method:: move(tagOrId, xAmount, yAmount, /) - Move each of the items given by *tagOrId* in the canvas coordinate space by - adding *xAmount* to every x-coordinate and *yAmount* to every y-coordinate - of the item. + Move each of the items given by *tagOrId* in the canvas coordinate space + by adding *xAmount* to every x-coordinate and *yAmount* to every + y-coordinate of the item. .. method:: moveto(tagOrId, x='', y='') Move the items given by *tagOrId* so that the first coordinate pair (the upper-left corner of the bounding box) of the lowest matching item is at - position (*x*, *y*). *x* or *y* may be an empty string, in which case the - corresponding coordinate is unchanged. All matching items keep their - positions relative to each other. + position (*x*, *y*). + *x* or *y* may be an empty string, in which case the corresponding + coordinate is unchanged. + All matching items keep their positions relative to each other. .. versionadded:: 3.8 @@ -3133,39 +3289,43 @@ Widget classes Delete from each of the items given by *tagOrId* the characters (for text items) or coordinates (for line and polygon items) in the range from - *first* to *last* inclusive; *last* defaults to *first*. Items that do not - support indexing ignore this operation. + *first* to *last* inclusive; *last* defaults to *first*. + Items that do not support indexing ignore this operation. .. method:: insert(tagOrId, beforeThis, string, /) Insert *string* into each of the items given by *tagOrId* just before the - character or coordinate whose index is *beforeThis*. For line and polygon - items *string* must be a valid sequence of coordinates. + character or coordinate whose index is *beforeThis*. + For line and polygon items *string* must be a valid sequence of + coordinates. .. method:: itemcget(tagOrId, option) - Return the current value of the configuration option *option* for the item - given by *tagOrId* (the lowest matching item if it matches several). This - is like :meth:`~Widget.cget` but applies to an individual item. + Return the current value of the configuration option *option* for the + item given by *tagOrId* (the lowest matching item if it matches several). + This is like :meth:`~Widget.cget` but applies to an individual item. .. method:: itemconfig(tagOrId, cnf=None, **kw) :no-typesetting: .. method:: itemconfigure(tagOrId, cnf=None, **kw) - Query or modify the configuration options of the items given by *tagOrId*. + Query or modify the configuration options of the items given by + *tagOrId*. This mirrors :meth:`~Widget.configure`, except that it applies to - individual items rather than to the canvas as a whole. With no options, it - returns a dictionary describing the current options of the first matching - item; otherwise it sets the given options on every matching item. The - legal options are those accepted by the corresponding ``create_*`` method. + individual items rather than to the canvas as a whole. + With no options, it returns a dictionary describing the current options + of the first matching item; otherwise it sets the given options on every + matching item. + The legal options are those accepted by the corresponding ``create_*`` + method. :meth:`itemconfig` is an alias of :meth:`!itemconfigure`. .. method:: type(tagOrId) - Return the type of the item given by *tagOrId* (the first matching item if - it matches several), such as ``'rectangle'`` or ``'text'``, or ``None`` if - *tagOrId* does not match any item. + Return the type of the item given by *tagOrId* (the first matching item + if it matches several), such as ``'rectangle'`` or ``'text'``, or + ``None`` if *tagOrId* does not match any item. .. method:: gettags(tagOrId, /) @@ -3176,16 +3336,18 @@ Widget classes .. method:: dtag(tagOrId, /) dtag(tagOrId, tagToDelete, /) - Remove the tag *tagToDelete* (which defaults to *tagOrId*) from each of the - items given by *tagOrId*. Items that do not have that tag are unaffected. + Remove the tag *tagToDelete* (which defaults to *tagOrId*) from each of + the items given by *tagOrId*. + Items that do not have that tag are unaffected. .. method:: addtag(newtag, searchSpec, /, *args) Add the tag *newtag* to each item selected by the search specification - *searchSpec* (and any further *args*). *searchSpec* is one of ``'above'``, - ``'all'``, ``'below'``, ``'closest'``, ``'enclosed'``, ``'overlapping'`` or - ``'withtag'``; the ``addtag_*`` methods below are convenient wrappers that - supply each of these forms. + *searchSpec* (and any further *args*). + *searchSpec* is one of ``'above'``, ``'all'``, ``'below'``, + ``'closest'``, ``'enclosed'``, ``'overlapping'`` or ``'withtag'``; the + ``addtag_*`` methods below are convenient wrappers that supply each of + these forms. .. method:: addtag_above(newtag, tagOrId) @@ -3203,11 +3365,12 @@ Widget classes .. method:: addtag_closest(newtag, x, y, halo=None, start=None) - Add the tag *newtag* to the item closest to the point (*x*, *y*). If - *halo* is given, any item within that distance of the point is treated as - overlapping it. If *start* is given (a tag or id), select the topmost - closest item that lies below *start* in the display list, which can be used - to step through all the closest items. + Add the tag *newtag* to the item closest to the point (*x*, *y*). + If *halo* is given, any item within that distance of the point is treated + as overlapping it. + If *start* is given (a tag or id), select the topmost closest item that + lies below *start* in the display list, which can be used to step through + all the closest items. .. method:: addtag_enclosed(newtag, x1, y1, x2, y2) @@ -3216,8 +3379,9 @@ Widget classes .. method:: addtag_overlapping(newtag, x1, y1, x2, y2) - Add the tag *newtag* to every item that overlaps or is enclosed within the - rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= *y2*. + Add the tag *newtag* to every item that overlaps or is enclosed within + the rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= + *y2*. .. method:: addtag_withtag(newtag, tagOrId) @@ -3227,9 +3391,9 @@ Widget classes Return a tuple of the ids of all items selected by the search specification *searchSpec* (and any further *args*), in stacking order - with the lowest item first. The search specification has any of the forms - accepted by :meth:`addtag`. The ``find_*`` methods below are more - convenient wrappers around it. + with the lowest item first. + The search specification has any of the forms accepted by :meth:`addtag`. + The ``find_*`` methods below are more convenient wrappers around it. .. method:: find_above(tagOrId) @@ -3247,9 +3411,9 @@ Widget classes .. method:: find_closest(x, y, halo=None, start=None) - Return a tuple containing the id of the item closest to the point - (*x*, *y*). *halo* and *start* are interpreted as for - :meth:`addtag_closest`. + Return a tuple containing the id of the item closest to the point (*x*, + *y*). + *halo* and *start* are interpreted as for :meth:`addtag_closest`. .. method:: find_enclosed(x1, y1, x2, y2) @@ -3258,8 +3422,8 @@ Widget classes .. method:: find_overlapping(x1, y1, x2, y2) - Return a tuple of the ids of all items that overlap or are enclosed within - the rectangle (*x1*, *y1*, *x2*, *y2*). + Return a tuple of the ids of all items that overlap or are enclosed + within the rectangle (*x1*, *y1*, *x2*, *y2*). .. method:: find_withtag(tagOrId) @@ -3275,8 +3439,8 @@ Widget classes Move all items given by *tagOrId* to a new position in the display list just above the item given by *aboveThis*, or to the top of the display - list if *aboveThis* is omitted. When several items are moved their - relative order is preserved. + list if *aboveThis* is omitted. + When several items are moved their relative order is preserved. This has no effect on embedded window items, whose stacking order is controlled by :meth:`Misc.tkraise` and :meth:`Misc.lower` instead. :meth:`lift` and :meth:`tkraise` are aliases of :meth:`!tag_raise`. @@ -3288,27 +3452,30 @@ Widget classes Move all items given by *tagOrId* to a new position in the display list just below the item given by *belowThis*, or to the bottom of the display - list if *belowThis* is omitted. When several items are moved their - relative order is preserved. - This has no effect on embedded window items. :meth:`lower` is an alias of - :meth:`!tag_lower`. + list if *belowThis* is omitted. + When several items are moved their relative order is preserved. + This has no effect on embedded window items. + :meth:`lower` is an alias of :meth:`!tag_lower`. .. method:: tag_bind(tagOrId, sequence=None, func=None, add=None) Bind the callback *func* to the event *sequence* for all items given by - *tagOrId*, so that *func* is invoked whenever that event occurs for one of - the items. This is like :meth:`Widget.bind` but operates on canvas items - rather than on whole widgets; only mouse, keyboard and virtual events may - be bound. Mouse events are directed to the current item and keyboard - events to the focus item (see :meth:`focus`). If *add* is true the new - binding is added to any existing bindings for the same sequence, rather - than replacing them. Return the identifier of the bound function, which - can be passed to :meth:`tag_unbind`. + *tagOrId*, so that *func* is invoked whenever that event occurs for one + of the items. + This is like :meth:`Widget.bind` but operates on canvas items rather than + on whole widgets; only mouse, keyboard and virtual events may be bound. + Mouse events are directed to the current item and keyboard events to the + focus item (see :meth:`focus`). + If *add* is true the new binding is added to any existing bindings for + the same sequence, rather than replacing them. + Return the identifier of the bound function, which can be passed to + :meth:`tag_unbind`. .. method:: tag_unbind(tagOrId, sequence, funcid=None) Remove for all items given by *tagOrId* the binding for the event - *sequence*. If *funcid* is given, only that callback (as returned by + *sequence*. + If *funcid* is given, only that callback (as returned by :meth:`tag_bind`) is unbound and deregistered. .. versionchanged:: 3.13 @@ -3319,55 +3486,61 @@ Widget classes Return a 4-tuple ``(x1, y1, x2, y2)`` giving an approximate bounding box, in pixels, that encloses all the items given by *tagOrId* and any further - *tagOrIds*. The result may overestimate the true - bounding box by a few pixels. Return ``None`` if no item matches or the - matching items have nothing to display. + *tagOrIds*. + The result may overestimate the true bounding box by a few pixels. + Return ``None`` if no item matches or the matching items have nothing to + display. .. method:: canvasx(screenx, gridspacing=None) Given a window x-coordinate *screenx*, return the canvas x-coordinate - displayed at that location. If *gridspacing* is given, the result is - rounded to the nearest multiple of *gridspacing* units. + displayed at that location. + If *gridspacing* is given, the result is rounded to the nearest multiple + of *gridspacing* units. .. method:: canvasy(screeny, gridspacing=None) Given a window y-coordinate *screeny*, return the canvas y-coordinate - displayed at that location. If *gridspacing* is given, the result is - rounded to the nearest multiple of *gridspacing* units. + displayed at that location. + If *gridspacing* is given, the result is rounded to the nearest multiple + of *gridspacing* units. .. method:: focus() focus(tagOrId, /) With *tagOrId*, set the keyboard focus for the canvas to the first item given by *tagOrId* that supports the insertion cursor; the focus is left - unchanged if no such item exists. If *tagOrId* is an empty string, reset - the focus so that no item has it. With no argument, return the id of the - item that currently has the focus, or an empty string if none does. An - item only displays the insertion cursor when both it is the focus item and - its canvas has the input focus. + unchanged if no such item exists. + If *tagOrId* is an empty string, reset the focus so that no item has it. + With no argument, return the id of the item that currently has the focus, + or an empty string if none does. + An item only displays the insertion cursor when both it is the focus item + and its canvas has the input focus. .. method:: icursor(tagOrId, index, /) Set the insertion cursor of the items given by *tagOrId* to just before the character given by *index*. - Items that do not support an insertion cursor are unaffected. The cursor - is only displayed when the item has the focus, but its position may be set - at any time. + Items that do not support an insertion cursor are unaffected. + The cursor is only displayed when the item has the focus, but its + position may be set at any time. .. method:: index(tagOrId, index, /) - Return as an integer the numerical index within *tagOrId* corresponding to - *index*, which is a textual - description of a position (for text items an index into the characters, for - line and polygon items an index into the coordinates). If *tagOrId* - matches several items, the first one that supports indexing is used. + Return as an integer the numerical index within *tagOrId* corresponding + to *index*, which is a textual description of a position (for text items + an index into the characters, for line and polygon items an index into + the coordinates). + If *tagOrId* matches several items, the first one that supports indexing + is used. .. method:: select_adjust(tagOrId, index) - Adjust the end of the selection in *tagOrId* nearest to *index* so that it - is at *index*, and make the other end the anchor point for future - :meth:`select_to` calls. If the selection is not currently in *tagOrId*, - this behaves like :meth:`select_to`. + Adjust the end of the selection in *tagOrId* nearest to *index* so that + it is at *index*, and make the other end the anchor point for future + :meth:`select_to` calls. + If the selection is not currently in *tagOrId*, this behaves like + :meth:`select_to`. .. method:: select_clear() @@ -3376,43 +3549,47 @@ Widget classes .. method:: select_from(tagOrId, index) Set the selection anchor point to just before the character given by - *index* in the item given by *tagOrId*. This does not change the - selection itself; it sets the fixed end for future :meth:`select_to` calls. + *index* in the item given by *tagOrId*. + This does not change the selection itself; it sets the fixed end for + future :meth:`select_to` calls. .. method:: select_item() Return the id of the item that holds the selection, or ``None`` if the - selection is not in this canvas. Unlike :meth:`find` and the ``find_*`` - methods, this returns the id as a string rather than an integer. + selection is not in this canvas. + Unlike :meth:`find` and the ``find_*`` methods, this returns the id as a + string rather than an integer. .. method:: select_to(tagOrId, index) Set the selection to the characters of *tagOrId* between the selection - anchor point and *index*, inclusive of *index*. The anchor point is the - one set by the most recent :meth:`select_adjust` or :meth:`select_from` - call. + anchor point and *index*, inclusive of *index*. + The anchor point is the one set by the most recent :meth:`select_adjust` + or :meth:`select_from` call. .. method:: scan_mark(x, y) Record *x*, *y* and the current view, for use with later - :meth:`scan_dragto` calls. This is typically bound to a mouse button press - in the widget. + :meth:`scan_dragto` calls. + This is typically bound to a mouse button press in the widget. .. method:: scan_dragto(x, y, gain=10) Scroll the canvas by *gain* times the difference between *x*, *y* and the - coordinates passed to the last :meth:`scan_mark` call. This is typically - bound to mouse motion events in the widget, producing the effect of - dragging the canvas at high speed through its window. + coordinates passed to the last :meth:`scan_mark` call. + This is typically bound to mouse motion events in the widget, producing + the effect of dragging the canvas at high speed through its window. .. method:: postscript(cnf={}, **kw) - Generate a PostScript (Encapsulated PostScript, version 3.0) representation - of part or all of the canvas. If the *file* or *channel* option is given, - the PostScript is written there and an empty string is returned; otherwise - it is returned as a string. By default only the area currently visible in - the window is generated, so it is usually necessary either to call - :meth:`~Misc.update` first or to use the *width* and *height* options. + Generate a PostScript (Encapsulated PostScript, version 3.0) + representation of part or all of the canvas. + If the *file* or *channel* option is given, the PostScript is written + there and an empty string is returned; otherwise it is returned as a + string. + By default only the area currently visible in the window is generated, so + it is usually necessary either to call :meth:`~Misc.update` first or to + use the *width* and *height* options. Supported options include *colormap*, *colormode*, *file*, *fontmap*, *height*, *pageanchor*, *pageheight*, *pagewidth*, *pagex*, *pagey*, *rotate*, *width*, *x* and *y*. @@ -3422,21 +3599,24 @@ Widget classes A :class:`!Checkbutton` widget displays a textual string, bitmap or image together with a square indicator, and toggles a boolean selection when - pressed. It has all the behavior of a simple button and, in addition, can - be selected: when selected the indicator is drawn with a check mark and the + pressed. + It has all the behavior of a simple button and, in addition, can be + selected: when selected the indicator is drawn with a check mark and the associated variable is set to the ``onvalue``, and when deselected the indicator is drawn empty and the variable is set to the ``offvalue``. - Inherits from :class:`Widget`. In addition to the standard widget options, - a checkbutton accepts the options documented in the Tk ``checkbutton`` - manual page, such as *variable*, *onvalue*, *offvalue* and *command*. + Inherits from :class:`Widget`. + In addition to the standard widget options, a checkbutton accepts the + options documented in the Tk ``checkbutton`` manual page, such as + *variable*, *onvalue*, *offvalue* and *command*. .. method:: invoke() Do just what would happen if the user pressed the checkbutton with the mouse: toggle the selection state of the button and invoke the associated - command, if there is one. Return the result of the command, or an empty - string if no command is associated with the checkbutton. This is ignored - if the checkbutton's state is ``disabled``. + command, if there is one. + Return the result of the command, or an empty string if no command is + associated with the checkbutton. + This is ignored if the checkbutton's state is ``disabled``. .. method:: select() @@ -3456,40 +3636,44 @@ Widget classes .. method:: flash() Flash the checkbutton by redisplaying it several times, alternating - between the active and normal colors. At the end of the flash the - checkbutton is left in the same normal or active state as when the method - was called. This is ignored if the checkbutton's state is ``disabled``. + between the active and normal colors. + At the end of the flash the checkbutton is left in the same normal or + active state as when the method was called. + This is ignored if the checkbutton's state is ``disabled``. .. class:: Entry(master=None, cnf={}, **kw) An :class:`!Entry` widget displays a single line of text and lets the user - edit it. Inherits from :class:`Widget` and :class:`XView`; since entries - can hold strings too long to fit in the window, they support horizontal - scrolling through :meth:`~XView.xview`. + edit it. + Inherits from :class:`Widget` and :class:`XView`; since entries can hold + strings too long to fit in the window, they support horizontal scrolling + through :meth:`~XView.xview`. In addition to the standard widget options, an entry accepts the options - documented in the Tk ``entry`` manual page. Notable ones are *textvariable* - (the name of a variable kept in sync with the entry's contents), *show* (if - set, each character is displayed as the given character rather than its true - value, useful for password entry), *validate* and *validatecommand* (which - together let a callback accept or reject edits), and *state* (one of - ``'normal'``, ``'disabled'`` or ``'readonly'``). + documented in the Tk ``entry`` manual page. + Notable ones are *textvariable* (the name of a variable kept in sync with + the entry's contents), *show* (if set, each character is displayed as the + given character rather than its true value, useful for password entry), + *validate* and *validatecommand* (which together let a callback accept or + reject edits), and *state* (one of ``'normal'``, ``'disabled'`` or + ``'readonly'``). Many of the methods below take an *index* argument that selects a character - in the entry's string. As described in the Tk ``entry`` manual page, - *index* may be a number (counting from 0), ``'insert'`` (the character just - after the insertion cursor), ``'end'`` (just after the last character), - ``'anchor'`` (the selection anchor point), ``'sel.first'`` and ``'sel.last'`` - (the ends of the selection), or ``@x`` (the character covering pixel - x-coordinate *x* in the window). Out-of-range indices are rounded to the - nearest legal value. + in the entry's string. + As described in the Tk ``entry`` manual page, *index* may be a number + (counting from 0), ``'insert'`` (the character just after the insertion + cursor), ``'end'`` (just after the last character), ``'anchor'`` (the + selection anchor point), ``'sel.first'`` and ``'sel.last'`` (the ends of the + selection), or ``@x`` (the character covering pixel x-coordinate *x* in the + window). + Out-of-range indices are rounded to the nearest legal value. .. method:: delete(first, last=None) Delete the characters from index *first* up to but not including index - *last*. If *last* is omitted, only the single character at *first* is - deleted. + *last*. + If *last* is omitted, only the single character at *first* is deleted. .. method:: get() @@ -3516,18 +3700,19 @@ Widget classes Locate the end of the selection nearest to the character given by *index*, and adjust that end to be at *index* (including but not going beyond it); the other end becomes the anchor point for future - :meth:`selection_to` calls. If there is no selection in the entry, a new - one is created between *index* and the most recent anchor point, - inclusive. :meth:`select_adjust` is an alias of :meth:`!selection_adjust`. + :meth:`selection_to` calls. + If there is no selection in the entry, a new one is created between + *index* and the most recent anchor point, inclusive. + :meth:`select_adjust` is an alias of :meth:`!selection_adjust`. .. method:: select_clear() :no-typesetting: .. method:: selection_clear() - Clear the selection if it is currently in this widget. If the selection - is not in this widget the method has no effect. :meth:`select_clear` is an - alias of :meth:`!selection_clear`. + Clear the selection if it is currently in this widget. + If the selection is not in this widget the method has no effect. + :meth:`select_clear` is an alias of :meth:`!selection_clear`. .. method:: select_from(index) :no-typesetting: @@ -3535,8 +3720,8 @@ Widget classes .. method:: selection_from(index) Set the selection anchor point to just before the character given by - *index*, without changing the selection. :meth:`select_from` is an alias of - :meth:`!selection_from`. + *index*, without changing the selection. + :meth:`select_from` is an alias of :meth:`!selection_from`. .. method:: select_present() :no-typesetting: @@ -3544,7 +3729,8 @@ Widget classes .. method:: selection_present() Return ``True`` if there are characters selected in the entry, ``False`` - otherwise. :meth:`select_present` is an alias of :meth:`!selection_present`. + otherwise. + :meth:`select_present` is an alias of :meth:`!selection_present`. .. method:: select_range(start, end) :no-typesetting: @@ -3552,8 +3738,9 @@ Widget classes .. method:: selection_range(start, end) Set the selection to include the characters starting with the one indexed - by *start* and ending with the one just before *end*. If *end* refers to - the same character as *start* or an earlier one, the selection is cleared. + by *start* and ending with the one just before *end*. + If *end* refers to the same character as *start* or an earlier one, the + selection is cleared. :meth:`select_range` is an alias of :meth:`!selection_range`. .. method:: select_to(index) @@ -3564,69 +3751,74 @@ Widget classes Set the selection between the anchor point and *index*: if *index* is before the anchor point, the selection runs from *index* up to but not including the anchor; if *index* is after it, from the anchor up to but - not including *index*; if they coincide, nothing happens. The anchor - point is the one set by the most recent :meth:`selection_from` or - :meth:`selection_adjust` call. If there is no selection in the entry, a - new one is created using the most recent anchor point. :meth:`select_to` is - an alias of :meth:`!selection_to`. + not including *index*; if they coincide, nothing happens. + The anchor point is the one set by the most recent :meth:`selection_from` + or :meth:`selection_adjust` call. + If there is no selection in the entry, a new one is created using the + most recent anchor point. + :meth:`select_to` is an alias of :meth:`!selection_to`. .. method:: scan_mark(x) Record *x* and the current view in the entry window, for use with later - :meth:`scan_dragto` calls. Typically associated with a mouse button - press in the widget. + :meth:`scan_dragto` calls. + Typically associated with a mouse button press in the widget. .. method:: scan_dragto(x) Compute the difference between *x* and the *x* given to the last - :meth:`scan_mark` call, and adjust the view left or right by 10 times that - difference. Typically associated with mouse motion events, to produce the - effect of dragging the entry at high speed through the window. + :meth:`scan_mark` call, and adjust the view left or right by 10 times + that difference. + Typically associated with mouse motion events, to produce the effect of + dragging the entry at high speed through the window. .. class:: Frame(master=None, cnf={}, **kw) - A :class:`!Frame` widget is a simple container. Its primary purpose is to - act as a spacer or container for complex window layouts; its only features - are its background and an optional 3-D border to make the frame appear - raised or sunken. Inherits from :class:`Widget`. Refer to the Tk - ``frame`` manual page for the full list of options. + A :class:`!Frame` widget is a simple container. + Its primary purpose is to act as a spacer or container for complex window + layouts; its only features are its background and an optional 3-D border to + make the frame appear raised or sunken. + Inherits from :class:`Widget`. + Refer to the Tk ``frame`` manual page for the full list of options. .. class:: Label(master=None, cnf={}, **kw) A :class:`!Label` widget displays a non-interactive textual string, bitmap - or image. The displayed text is set with the *text* option or linked to a - variable through *textvariable*, and an image can be shown using the - *image* option. Text must all be in a single font but may occupy multiple - lines, and one character may be underlined with the *underline* option. - Inherits from :class:`Widget`. Refer to the Tk ``label`` manual page for - the full list of options. + or image. + The displayed text is set with the *text* option or linked to a variable + through *textvariable*, and an image can be shown using the *image* option. + Text must all be in a single font but may occupy multiple lines, and one + character may be underlined with the *underline* option. + Inherits from :class:`Widget`. + Refer to the Tk ``label`` manual page for the full list of options. .. class:: LabelFrame(master=None, cnf={}, **kw) A :class:`!LabelFrame` widget is a container that has the features of a - :class:`Frame` plus the ability to display a label. The label text is set - with the *text* option and positioned with *labelanchor*, or an arbitrary - widget may be used as the label by giving it as the *labelwidget* option. - Inherits from :class:`Widget`. Refer to the Tk ``labelframe`` manual page - for the full list of options. + :class:`Frame` plus the ability to display a label. + The label text is set with the *text* option and positioned with + *labelanchor*, or an arbitrary widget may be used as the label by giving it + as the *labelwidget* option. + Inherits from :class:`Widget`. + Refer to the Tk ``labelframe`` manual page for the full list of options. .. class:: Listbox(master=None, cnf={}, **kw) A :class:`!Listbox` widget displays a list of single-line text items, one - per line, of which the user can select one or more. The way the selection - behaves is governed by the *selectmode* option, which is one of ``browse`` - (the default; at most one item, which may be dragged with the mouse), - ``single`` (at most one item), ``multiple`` (any number of items, toggled - individually), or ``extended`` (any number of items, including - discontiguous ranges, selected by clicking and dragging). Inherits from - :class:`Widget`, :class:`XView` and :class:`YView`, so the view can be - scrolled horizontally and vertically with :meth:`~XView.xview` and - :meth:`~YView.yview`. Refer to the Tk ``listbox`` manual page for the full - list of options. + per line, of which the user can select one or more. + The way the selection behaves is governed by the *selectmode* option, which + is one of ``browse`` (the default; at most one item, which may be dragged + with the mouse), ``single`` (at most one item), ``multiple`` (any number of + items, toggled individually), or ``extended`` (any number of items, + including discontiguous ranges, selected by clicking and dragging). + Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the + view can be scrolled horizontally and vertically with :meth:`~XView.xview` + and :meth:`~YView.yview`. + Refer to the Tk ``listbox`` manual page for the full list of options. Many of the methods take an *index* argument identifying a particular item. As described in the Tk ``listbox`` manual page, *index* may be a numeric @@ -3640,21 +3832,22 @@ Widget classes .. method:: insert(index, *elements) Insert the given *elements* as new items just before the item given by - *index*. If *index* is ``'end'``, the new items are appended to the end - of the list. + *index*. + If *index* is ``'end'``, the new items are appended to the end of the + list. .. method:: delete(first, last=None) - Delete the items in the range from *first* to *last* inclusive. If - *last* is omitted, it defaults to *first*, so that a single item is + Delete the items in the range from *first* to *last* inclusive. + If *last* is omitted, it defaults to *first*, so that a single item is deleted. .. method:: get(first, last=None) If *last* is omitted, return the contents of the item given by *first*, - or an empty string if *first* refers to a non-existent item. If *last* - is given, return a tuple of all the items in the range from *first* to - *last* inclusive. + or an empty string if *first* refers to a non-existent item. + If *last* is given, return a tuple of all the items in the range from + *first* to *last* inclusive. .. method:: size() @@ -3663,8 +3856,9 @@ Widget classes .. method:: index(index) Return the integer index value corresponding to *index*, or ``None`` if - *index* is out of range. If *index* is ``'end'``, the result is a count - of the number of items in the listbox (not the index of the last item). + *index* is out of range. + If *index* is ``'end'``, the result is a count of the number of items in + the listbox (not the index of the last item). .. method:: bbox(index) @@ -3682,18 +3876,19 @@ Widget classes .. method:: see(index) - Adjust the view so that the item given by *index* is visible. If the - item is already visible the method has no effect; if it is near an edge - of the window the listbox scrolls just enough to bring it into view at - that edge, otherwise the listbox scrolls to center the item. + Adjust the view so that the item given by *index* is visible. + If the item is already visible the method has no effect; if it is near an + edge of the window the listbox scrolls just enough to bring it into view + at that edge, otherwise the listbox scrolls to center the item. .. method:: activate(index) - Set the active item to the one given by *index*. If *index* is outside - the range of items, the closest item is activated instead. The active - item is drawn as specified by the *activestyle* option when the widget - has the input focus, and its index may be retrieved with the ``'active'`` - index. + Set the active item to the one given by *index*. + If *index* is outside the range of items, the closest item is activated + instead. + The active item is drawn as specified by the *activestyle* option when + the widget has the input focus, and its index may be retrieved with the + ``'active'`` index. .. method:: curselection() @@ -3705,11 +3900,12 @@ Widget classes .. method:: selection_anchor(index) - Set the selection anchor to the item given by *index*. If *index* refers - to a non-existent item, the closest item is used. The selection anchor - is the end of the selection that is fixed while dragging out a selection - with the mouse, and may afterwards be referred to with the ``'anchor'`` - index. :meth:`select_anchor` is an alias of :meth:`!selection_anchor`. + Set the selection anchor to the item given by *index*. + If *index* refers to a non-existent item, the closest item is used. + The selection anchor is the end of the selection that is fixed while + dragging out a selection with the mouse, and may afterwards be referred + to with the ``'anchor'`` index. + :meth:`select_anchor` is an alias of :meth:`!selection_anchor`. .. method:: select_clear(first, last=None) :no-typesetting: @@ -3717,9 +3913,9 @@ Widget classes .. method:: selection_clear(first, last=None) Deselect any of the items in the range from *first* to *last* inclusive - that are selected. The selection state of items outside this range is - not changed. :meth:`select_clear` is an alias of - :meth:`!selection_clear`. + that are selected. + The selection state of items outside this range is not changed. + :meth:`select_clear` is an alias of :meth:`!selection_clear`. .. method:: select_includes(index) :no-typesetting: @@ -3727,8 +3923,8 @@ Widget classes .. method:: selection_includes(index) Return ``True`` if the item given by *index* is currently selected, - ``False`` otherwise. :meth:`select_includes` is an alias of - :meth:`!selection_includes`. + ``False`` otherwise. + :meth:`select_includes` is an alias of :meth:`!selection_includes`. .. method:: select_set(first, last=None) :no-typesetting: @@ -3748,91 +3944,99 @@ Widget classes Query or modify the configuration options of the item given by *index*. This mirrors :meth:`~Widget.configure`, except that it applies to an - individual item rather than to the listbox as a whole. With no options, - it returns a dictionary describing the current options of the item; - otherwise it sets the given options. The supported item options are - *background*, *foreground*, *selectbackground* and *selectforeground*. + individual item rather than to the listbox as a whole. + With no options, it returns a dictionary describing the current options + of the item; otherwise it sets the given options. + The supported item options are *background*, *foreground*, + *selectbackground* and *selectforeground*. :meth:`itemconfig` is an alias of :meth:`!itemconfigure`. .. method:: scan_mark(x, y) Record *x*, *y* and the current view, for use with later - :meth:`scan_dragto` calls. This is typically bound to a mouse button - press in the widget. + :meth:`scan_dragto` calls. + This is typically bound to a mouse button press in the widget. .. method:: scan_dragto(x, y) Scroll the listbox by 10 times the difference between *x*, *y* and the - coordinates passed to the last :meth:`scan_mark` call. This is typically - bound to mouse motion events in the widget, producing the effect of - dragging the list at high speed through the window. + coordinates passed to the last :meth:`scan_mark` call. + This is typically bound to mouse motion events in the widget, producing + the effect of dragging the list at high speed through the window. .. class:: Menu(master=None, cnf={}, **kw) A :class:`!Menu` widget displays a column of entries, each of which may be a command, a checkbutton, a radiobutton, a cascade (which posts an associated - submenu) or a separator. Menus are used as the menubar of a toplevel - window, as pulldown menus posted from a cascade entry or menubutton, and as - popup menus. Inherits from :class:`Widget`. + submenu) or a separator. + Menus are used as the menubar of a toplevel window, as pulldown menus posted + from a cascade entry or menubutton, and as popup menus. + Inherits from :class:`Widget`. Many of the entry methods take an *index* argument that selects which entry - to operate on. As described in the Tk ``menu`` manual page, *index* may be a - numeric index (counting from 0 at the top), ``'active'`` (the currently - active entry), ``'end'`` or ``'last'`` (the bottommost entry), ``'none'`` (no - entry at all, written ``{}`` in Tcl), ``@y`` (the entry covering pixel - y-coordinate *y* in the menu window), or a pattern matched against the labels - of the entries from the top down. + to operate on. + As described in the Tk ``menu`` manual page, *index* may be a numeric index + (counting from 0 at the top), ``'active'`` (the currently active entry), + ``'end'`` or ``'last'`` (the bottommost entry), ``'none'`` (no entry at all, + written ``{}`` in Tcl), ``@y`` (the entry covering pixel y-coordinate *y* in + the menu window), or a pattern matched against the labels of the entries + from the top down. .. method:: add(itemType, cnf={}, **kw) - Add a new entry to the bottom of the menu. *itemType* is one of - ``'command'``, ``'cascade'``, ``'checkbutton'``, ``'radiobutton'`` or - ``'separator'`` and determines the type of the new entry; the remaining - options configure it. The :meth:`!add_command`, :meth:`!add_cascade`, - :meth:`!add_checkbutton`, :meth:`!add_radiobutton` and - :meth:`!add_separator` convenience methods call this method with the - corresponding *itemType*. + Add a new entry to the bottom of the menu. + *itemType* is one of ``'command'``, ``'cascade'``, ``'checkbutton'``, + ``'radiobutton'`` or ``'separator'`` and determines the type of the new + entry; the remaining options configure it. + The :meth:`!add_command`, :meth:`!add_cascade`, :meth:`!add_checkbutton`, + :meth:`!add_radiobutton` and :meth:`!add_separator` convenience methods + call this method with the corresponding *itemType*. .. method:: add_cascade(cnf={}, **kw) - Add a new cascade entry to the bottom of the menu. A cascade entry has an - associated submenu, given by its *menu* option, which must be a child of - this menu; posting the entry posts the submenu next to it. + Add a new cascade entry to the bottom of the menu. + A cascade entry has an associated submenu, given by its *menu* option, + which must be a child of this menu; posting the entry posts the submenu + next to it. .. method:: add_checkbutton(cnf={}, **kw) - Add a new checkbutton entry to the bottom of the menu. When invoked, a - checkbutton entry toggles between its *onvalue* and *offvalue*, storing the - result in its associated *variable*, and displays an indicator showing - whether it is selected. + Add a new checkbutton entry to the bottom of the menu. + When invoked, a checkbutton entry toggles between its *onvalue* and + *offvalue*, storing the result in its associated *variable*, and displays + an indicator showing whether it is selected. .. method:: add_command(cnf={}, **kw) - Add a new command entry to the bottom of the menu. A command entry - behaves much like a button: when it is invoked, the callback given by its - *command* option is called. + Add a new command entry to the bottom of the menu. + A command entry behaves much like a button: when it is invoked, the + callback given by its *command* option is called. .. method:: add_radiobutton(cnf={}, **kw) - Add a new radiobutton entry to the bottom of the menu. Radiobutton - entries sharing the same *variable* form a group of which only one may be - selected at a time; selecting an entry stores its *value* in the variable. + Add a new radiobutton entry to the bottom of the menu. + Radiobutton entries sharing the same *variable* form a group of which + only one may be selected at a time; selecting an entry stores its *value* + in the variable. .. method:: add_separator(cnf={}, **kw) - Add a separator to the bottom of the menu. A separator is displayed as a - horizontal dividing line and cannot be activated or invoked. + Add a separator to the bottom of the menu. + A separator is displayed as a horizontal dividing line and cannot be + activated or invoked. .. method:: insert(index, itemType, cnf={}, **kw) - Same as :meth:`add`, except that the new entry is inserted just before the - entry given by *index* instead of being appended to the end of the menu. + Same as :meth:`add`, except that the new entry is inserted just before + the entry given by *index* instead of being appended to the end of the + menu. *itemType* is one of ``'command'``, ``'cascade'``, ``'checkbutton'``, - ``'radiobutton'`` or ``'separator'``. The :meth:`!insert_command`, - :meth:`!insert_cascade`, :meth:`!insert_checkbutton`, - :meth:`!insert_radiobutton` and :meth:`!insert_separator` convenience - methods call this method with the corresponding *itemType*. + ``'radiobutton'`` or ``'separator'``. + The :meth:`!insert_command`, :meth:`!insert_cascade`, + :meth:`!insert_checkbutton`, :meth:`!insert_radiobutton` and + :meth:`!insert_separator` convenience methods call this method with the + corresponding *itemType*. .. method:: insert_cascade(index, cnf={}, **kw) @@ -3862,9 +4066,10 @@ Widget classes .. method:: delete(index1, index2=None) Delete all of the menu entries between *index1* and *index2* inclusive. - If *index2* is omitted, it defaults to *index1*, so that a single entry is - deleted. Attempts to delete a tear-off entry are ignored; remove it by - changing the *tearoff* option instead. + If *index2* is omitted, it defaults to *index1*, so that a single entry + is deleted. + Attempts to delete a tear-off entry are ignored; remove it by changing + the *tearoff* option instead. .. method:: entrycget(index, option) @@ -3878,10 +4083,10 @@ Widget classes Query or modify the configuration options of the entry given by *index*. This mirrors :meth:`~Widget.configure`, except that it applies to an - individual entry rather than to the menu as a whole. With no options, it - returns a dictionary describing the current options of the entry; - otherwise it sets the given options. :meth:`entryconfig` is an alias of - :meth:`!entryconfigure`. + individual entry rather than to the menu as a whole. + With no options, it returns a dictionary describing the current options + of the entry; otherwise it sets the given options. + :meth:`entryconfig` is an alias of :meth:`!entryconfigure`. .. method:: index(index) @@ -3896,36 +4101,38 @@ Widget classes .. method:: activate(index) - Make the entry given by *index* the active entry, redisplaying it with its - active colors, and deactivate any previously active entry. If *index* - selects no entry, or the selected entry is disabled, the menu ends up with - no active entry. + Make the entry given by *index* the active entry, redisplaying it with + its active colors, and deactivate any previously active entry. + If *index* selects no entry, or the selected entry is disabled, the menu + ends up with no active entry. .. method:: invoke(index) - Invoke the action of the entry given by *index*, as if it had been clicked. - Nothing happens if the entry is disabled. If the entry has a *command* - associated with it, the result of that command is returned; otherwise the - result is an empty string. + Invoke the action of the entry given by *index*, as if it had been + clicked. + Nothing happens if the entry is disabled. + If the entry has a *command* associated with it, the result of that + command is returned; otherwise the result is an empty string. .. method:: post(x, y) - Display the menu on the screen at the root-window coordinates *x* and *y*, - adjusting them if necessary so that the whole menu is visible. If the - *postcommand* option has been specified, it is evaluated before the menu is - posted. + Display the menu on the screen at the root-window coordinates *x* and + *y*, adjusting them if necessary so that the whole menu is visible. + If the *postcommand* option has been specified, it is evaluated before + the menu is posted. .. method:: tk_popup(x, y, entry='') - Post the menu as a popup at the root-window coordinates *x* and *y*. If - *entry* is given, the menu is positioned so that this entry is displayed - under the pointer. + Post the menu as a popup at the root-window coordinates *x* and *y*. + If *entry* is given, the menu is positioned so that this entry is + displayed under the pointer. .. method:: unpost() - Unmap the menu so that it is no longer displayed, also unposting any posted - lower-level cascaded submenu. This has no effect on Windows and macOS, - which manage the unposting of menus themselves. + Unmap the menu so that it is no longer displayed, also unposting any + posted lower-level cascaded submenu. + This has no effect on Windows and macOS, which manage the unposting of + menus themselves. .. method:: xposition(index) @@ -3942,33 +4149,35 @@ Widget classes .. class:: Menubutton(master=None, cnf={}, **kw) - A :class:`!Menubutton` widget displays a textual string, bitmap or image - and posts an associated :class:`Menu`, given by its *menu* option, when the - user presses it. Like a :class:`Label` it can show *text*, a - *textvariable*, or an *image*, and the *direction* option controls where - the menu appears relative to the button. Inherits from :class:`Widget`. + A :class:`!Menubutton` widget displays a textual string, bitmap or image and + posts an associated :class:`Menu`, given by its *menu* option, when the user + presses it. + Like a :class:`Label` it can show *text*, a *textvariable*, or an *image*, + and the *direction* option controls where the menu appears relative to the + button. + Inherits from :class:`Widget`. Refer to the Tk ``menubutton`` manual page for the full list of options. .. class:: Message(master=None, cnf={}, **kw) - A :class:`!Message` widget displays a non-interactive textual string, - given by the *text* option or linked to a variable through *textvariable*. + A :class:`!Message` widget displays a non-interactive textual string, given + by the *text* option or linked to a variable through *textvariable*. Unlike a :class:`Label`, it breaks the string into multiple lines in order to produce a given aspect ratio, choosing line breaks at word boundaries, - and it can justify the text left, centered or right. Inherits from - :class:`Widget`. Refer to the Tk ``message`` manual page for the full - list of options. + and it can justify the text left, centered or right. + Inherits from :class:`Widget`. + Refer to the Tk ``message`` manual page for the full list of options. .. class:: OptionMenu(master, variable, value, *values, **kwargs) A helper subclass of :class:`Menubutton` that displays a pop-up menu of - mutually exclusive choices. *variable* is a :class:`Variable` kept in sync - with the selection, *value* is the initial choice, and *values* are the - remaining menu entries. The keyword argument *command* may be given a - callback that is invoked with the selected value, and the keyword argument - *name* sets the Tk widget name. + mutually exclusive choices. + *variable* is a :class:`Variable` kept in sync with the selection, *value* + is the initial choice, and *values* are the remaining menu entries. + The keyword argument *command* may be given a callback that is invoked with + the selected value, and the keyword argument *name* sets the Tk widget name. .. method:: destroy() @@ -3983,31 +4192,33 @@ Widget classes A :class:`!PanedWindow` is a geometry-manager widget that arranges any number of child *panes* in a row (when *orient* is ``'horizontal'``) or a - column (when *orient* is ``'vertical'``). Each pane holds one widget, and - each pair of adjacent panes is separated by a movable *sash* that the user - can drag with the mouse to resize the widgets on either side of it. + column (when *orient* is ``'vertical'``). + Each pane holds one widget, and each pair of adjacent panes is separated by + a movable *sash* that the user can drag with the mouse to resize the widgets + on either side of it. Inherits from :class:`Widget`. - The *orient* option selects the layout direction, *sashwidth* sets the - width of each sash and *sashrelief* its relief. When *showhandle* is true - a small handle is drawn on each sash that the user can grab to drag it. + The *orient* option selects the layout direction, *sashwidth* sets the width + of each sash and *sashrelief* its relief. + When *showhandle* is true a small handle is drawn on each sash that the user + can grab to drag it. Refer to the Tk ``panedwindow`` manual page for the full list of options. .. method:: add(child, **kw) Add *child* to the panedwindow as a new pane, placed after any existing - panes. The keyword arguments specify per-pane management options for - *child*; they may be any of the options accepted by - :meth:`paneconfigure`. + panes. + The keyword arguments specify per-pane management options for *child*; + they may be any of the options accepted by :meth:`paneconfigure`. .. method:: forget(child) :no-typesetting: .. method:: remove(child) - Remove the pane containing *child* from the panedwindow. All geometry - management options for *child* are forgotten. :meth:`forget` is an - alias of :meth:`!remove`. + Remove the pane containing *child* from the panedwindow. + All geometry management options for *child* are forgotten. + :meth:`forget` is an alias of :meth:`!remove`. .. method:: panes() @@ -4017,8 +4228,8 @@ Widget classes .. method:: panecget(child, option) Return the current value of the management option *option* for the pane - containing *child*. *option* may be any value allowed by - :meth:`paneconfigure`. + containing *child*. + *option* may be any value allowed by :meth:`paneconfigure`. .. method:: paneconfig(tagOrId, cnf=None, **kw) :no-typesetting: @@ -4026,43 +4237,46 @@ Widget classes .. method:: paneconfigure(tagOrId, cnf=None, **kw) Query or modify the management options of the pane containing the widget - *tagOrId*. With no options, it returns a dictionary describing all of - the available options for the pane; given a single option name as a - string, it returns a description of that one option; otherwise it sets - the given options. The supported options include *after* and *before* - (insert the pane after or before another managed window), *height* and - *width* (the outer dimensions of the window, including any border), - *minsize* (the minimum size in the paned dimension), *padx* and *pady* - (extra space to leave on each side of the window), *sticky* (position or - stretch the window within an oversized pane, using a string of the - characters ``n``, ``s``, ``e`` and ``w``), *hide* (hide the pane while - keeping it in the list of panes) and *stretch* (how extra space is - allocated to the pane: one of ``'always'``, ``'first'``, ``'last'``, - ``'middle'`` or ``'never'``). :meth:`paneconfig` is an alias of - :meth:`!paneconfigure`. + *tagOrId*. + With no options, it returns a dictionary describing all of the available + options for the pane; given a single option name as a string, it returns + a description of that one option; otherwise it sets the given options. + The supported options include *after* and *before* (insert the pane after + or before another managed window), *height* and *width* (the outer + dimensions of the window, including any border), *minsize* (the minimum + size in the paned dimension), *padx* and *pady* (extra space to leave on + each side of the window), *sticky* (position or stretch the window within + an oversized pane, using a string of the characters ``n``, ``s``, ``e`` + and ``w``), *hide* (hide the pane while keeping it in the list of panes) + and *stretch* (how extra space is allocated to the pane: one of + ``'always'``, ``'first'``, ``'last'``, ``'middle'`` or ``'never'``). + :meth:`paneconfig` is an alias of :meth:`!paneconfigure`. .. method:: identify(x, y) Identify the panedwindow component underneath the point given by *x* and - *y*, in window coordinates. If the point is over a sash or a sash - handle, the result is a two-element tuple containing the index of the - sash or handle and a word indicating whether it is over a sash or a - handle, such as ``(0, 'sash')`` or ``(2, 'handle')``. If the point is - over any other part of the panedwindow, the result is an empty string. + *y*, in window coordinates. + If the point is over a sash or a sash handle, the result is a two-element + tuple containing the index of the sash or handle and a word indicating + whether it is over a sash or a handle, such as ``(0, 'sash')`` or + ``(2, 'handle')``. + If the point is over any other part of the panedwindow, the result is an + empty string. .. method:: sash(*args) - Query or change the position of the sashes in the panedwindow. This is - a thin wrapper around the Tk ``sash`` subcommand; the convenience + Query or change the position of the sashes in the panedwindow. + This is a thin wrapper around the Tk ``sash`` subcommand; the convenience methods :meth:`sash_coord`, :meth:`sash_mark` and :meth:`sash_place` should normally be used instead. .. method:: sash_coord(index) - Return the current x and y coordinate pair for the sash given by - *index*, which must be an integer between 0 and one less than the number - of panes in the panedwindow. The coordinates returned are those of the - top left corner of the region containing the sash. + Return the current x and y coordinate pair for the sash given by *index*, + which must be an integer between 0 and one less than the number of panes + in the panedwindow. + The coordinates returned are those of the top left corner of the region + containing the sash. .. method:: sash_mark(index) @@ -4076,10 +4290,10 @@ Widget classes .. method:: proxy(*args) Query or change the position of the sash proxy, the "ghost" sash shown - while a sash is being dragged with non-opaque resizing. This is a thin - wrapper around the Tk ``proxy`` subcommand; the convenience methods - :meth:`proxy_coord`, :meth:`proxy_forget` and :meth:`proxy_place` should - normally be used instead. + while a sash is being dragged with non-opaque resizing. + This is a thin wrapper around the Tk ``proxy`` subcommand; the + convenience methods :meth:`proxy_coord`, :meth:`proxy_forget` and + :meth:`proxy_place` should normally be used instead. .. method:: proxy_coord() @@ -4099,11 +4313,13 @@ Widget classes A :class:`!Radiobutton` widget displays a textual string, bitmap or image together with a diamond or circular indicator, and selects one choice out of - several. It has all the behavior of a simple button and, in addition, can - be selected: typically several radiobuttons share a single *variable*, and + several. + It has all the behavior of a simple button and, in addition, can be + selected: typically several radiobuttons share a single *variable*, and selecting one sets that variable to the radiobutton's *value*; each radiobutton also monitors the variable and automatically selects or - deselects itself when the variable changes. Inherits from :class:`Widget`. + deselects itself when the variable changes. + Inherits from :class:`Widget`. In addition to the standard widget options, a radiobutton accepts the options documented in the Tk ``radiobutton`` manual page, such as *variable*, *value* and *command*. @@ -4112,9 +4328,10 @@ Widget classes Do just what would happen if the user pressed the radiobutton with the mouse: select the button and invoke the associated command, if there is - one. Return the result of the command, or an empty string if no command - is associated with the radiobutton. This is ignored if the radiobutton's - state is ``disabled``. + one. + Return the result of the command, or an empty string if no command is + associated with the radiobutton. + This is ignored if the radiobutton's state is ``disabled``. .. method:: select() @@ -4124,46 +4341,50 @@ Widget classes .. method:: deselect() Deselect the radiobutton and set the associated variable to an empty - string. If this radiobutton was not currently selected, this has no - effect. + string. + If this radiobutton was not currently selected, this has no effect. .. method:: flash() Flash the radiobutton by redisplaying it several times, alternating - between the active and normal colors. At the end of the flash the - radiobutton is left in the same normal or active state as when the method - was called. This is ignored if the radiobutton's state is ``disabled``. + between the active and normal colors. + At the end of the flash the radiobutton is left in the same normal or + active state as when the method was called. + This is ignored if the radiobutton's state is ``disabled``. .. class:: Scale(master=None, cnf={}, **kw) A :class:`!Scale` widget lets the user select a numerical value by moving a - slider along a trough. It can be oriented vertically or horizontally and - can optionally display a label and the current value. Inherits from - :class:`Widget`. + slider along a trough. + It can be oriented vertically or horizontally and can optionally display a + label and the current value. + Inherits from :class:`Widget`. In addition to the standard widget options, a scale accepts the options documented in the Tk ``scale`` manual page, such as *from_*, *to*, - *resolution*, *orient*, *tickinterval*, *variable* and *command*. As - elsewhere in :mod:`!tkinter`, the leading ``-`` of the Tk option name is + *resolution*, *orient*, *tickinterval*, *variable* and *command*. + As elsewhere in :mod:`!tkinter`, the leading ``-`` of the Tk option name is dropped; *from* is spelled ``from_`` because :keyword:`from` is a Python keyword. .. method:: get() - Return the current value of the scale. The result is an integer if the - scale's *resolution* yields whole numbers, and a float otherwise. + Return the current value of the scale. + The result is an integer if the scale's *resolution* yields whole + numbers, and a float otherwise. .. method:: set(value) - Set the scale to *value*, moving the slider accordingly. This has no - effect if the scale is disabled. + Set the scale to *value*, moving the slider accordingly. + This has no effect if the scale is disabled. .. method:: coords(value=None) Return a tuple ``(x, y)`` giving the pixel coordinates, relative to the widget, of the point on the centerline of the trough that corresponds to - *value*. If *value* is omitted, the scale's current value is used. + *value*. + If *value* is omitted, the scale's current value is used. .. method:: identify(x, y) @@ -4178,10 +4399,11 @@ Widget classes A :class:`!Scrollbar` widget displays a slider and two arrows that let the user scroll an associated widget, such as a :class:`Listbox`, :class:`Text`, - :class:`Canvas` or :class:`Entry`. It is connected to the scrolled widget by - setting that widget's *xscrollcommand* or *yscrollcommand* option to the - scrollbar's :meth:`set` method, and the scrollbar's *command* option to the - scrolled widget's :meth:`~XView.xview` or :meth:`~YView.yview` method. + :class:`Canvas` or :class:`Entry`. + It is connected to the scrolled widget by setting that widget's + *xscrollcommand* or *yscrollcommand* option to the scrollbar's :meth:`set` + method, and the scrollbar's *command* option to the scrolled widget's + :meth:`~XView.xview` or :meth:`~YView.yview` method. Inherits from :class:`Widget`. .. method:: get() @@ -4192,17 +4414,19 @@ Widget classes .. method:: set(first, last) - Set the scrollbar. *first* and *last* are fractions between 0 and 1 - giving the positions of the start and end of the visible portion of the - associated document. This method is normally registered as the scrolled - widget's *xscrollcommand* or *yscrollcommand* and called by that widget. + Set the scrollbar. + *first* and *last* are fractions between 0 and 1 giving the positions of + the start and end of the visible portion of the associated document. + This method is normally registered as the scrolled widget's + *xscrollcommand* or *yscrollcommand* and called by that widget. .. method:: activate(index=None) Mark the element *index* (one of ``'arrow1'``, ``'slider'`` or - ``'arrow2'``) as active, displaying it according to the *activebackground* - and *activerelief* options. If *index* is omitted, return the name of the - currently active element, or ``None`` if no element is active. + ``'arrow2'``) as active, displaying it according to the + *activebackground* and *activerelief* options. + If *index* is omitted, return the name of the currently active element, + or ``None`` if no element is active. .. versionchanged:: 3.5 The *index* argument is now optional. @@ -4210,8 +4434,8 @@ Widget classes .. method:: delta(deltax, deltay) Return a float indicating the fractional change in the scrollbar setting - that corresponds to moving the slider by *deltax* pixels horizontally (for - horizontal scrollbars) or *deltay* pixels vertically (for vertical + that corresponds to moving the slider by *deltax* pixels horizontally + (for horizontal scrollbars) or *deltay* pixels vertically (for vertical scrollbars). .. method:: fraction(x, y) @@ -4231,22 +4455,25 @@ Widget classes A :class:`!Spinbox` widget is an :class:`Entry`-like widget with a pair of up/down arrow buttons that let the user step through a range of values in - addition to editing the value directly. The set of values may be a numeric - range given by the *from_*, *to* and *increment* options, or an explicit list - of strings given by the *values* option (which takes precedence over the - range). Each time an arrow is invoked the *command* callback, if any, is - called; the *wrap* option controls whether stepping past either end of the - range wraps around to the other end; the *format* option specifies how - numeric values are formatted; and the *validate* option enables validation of - the entered text. Inherits from :class:`Widget` and :class:`XView`. + addition to editing the value directly. + The set of values may be a numeric range given by the *from_*, *to* and + *increment* options, or an explicit list of strings given by the *values* + option (which takes precedence over the range). + Each time an arrow is invoked the *command* callback, if any, is called; the + *wrap* option controls whether stepping past either end of the range wraps + around to the other end; the *format* option specifies how numeric values + are formatted; and the *validate* option enables validation of the entered + text. + Inherits from :class:`Widget` and :class:`XView`. Many of the methods take an *index* argument identifying a character in the - spinbox's string. As described in the Tk ``spinbox`` manual page, *index* - may be a numeric index (counting from 0), ``'anchor'`` (the selection anchor - point), ``'end'`` (just after the last character), ``'insert'`` (the - character just after the insertion cursor), ``'sel.first'`` or ``'sel.last'`` - (the ends of the selection), or ``@x`` (the character covering pixel - x-coordinate *x* in the window). + spinbox's string. + As described in the Tk ``spinbox`` manual page, *index* may be a numeric + index (counting from 0), ``'anchor'`` (the selection anchor point), + ``'end'`` (just after the last character), ``'insert'`` (the character just + after the insertion cursor), ``'sel.first'`` or ``'sel.last'`` (the ends of + the selection), or ``@x`` (the character covering pixel x-coordinate *x* in + the window). .. method:: get() @@ -4254,20 +4481,20 @@ Widget classes .. method:: insert(index, s) - Insert the characters of the string *s* just before the character given by - *index*. + Insert the characters of the string *s* just before the character given + by *index*. .. method:: delete(first, last=None) - Delete one or more characters of the spinbox. *first* is the index of the - first character to delete, and *last* is the index of the character just - after the last one to delete. If *last* is omitted, a single character at - *first* is deleted. + Delete one or more characters of the spinbox. + *first* is the index of the first character to delete, and *last* is the + index of the character just after the last one to delete. + If *last* is omitted, a single character at *first* is deleted. .. method:: icursor(index) - Arrange for the insertion cursor to be displayed just before the character - given by *index*. + Arrange for the insertion cursor to be displayed just before the + character given by *index*. .. method:: index(index) @@ -4276,10 +4503,12 @@ Widget classes .. method:: bbox(index) Return a tuple of four integers ``(x, y, width, height)`` describing the - bounding box of the character given by *index*. *x* and *y* are the pixel - coordinates of the upper-left corner of the character relative to the - widget, and *width* and *height* are its size in pixels. The bounding box - may refer to a region outside the visible area of the window. + bounding box of the character given by *index*. + *x* and *y* are the pixel coordinates of the upper-left corner of the + character relative to the widget, and *width* and *height* are its size + in pixels. + The bounding box may refer to a region outside the visible area of the + window. .. method:: identify(x, y) @@ -4293,57 +4522,61 @@ Widget classes .. method:: scan(*args) - A thin wrapper around the Tk ``scan`` widget subcommand, used to implement - fast dragging of the view: ``scan('mark', x)`` records *x* and the current - view, and ``scan('dragto', x)`` adjusts the view relative to that mark. + A thin wrapper around the Tk ``scan`` widget subcommand, used to + implement fast dragging of the view: ``scan('mark', x)`` records *x* and + the current view, and ``scan('dragto', x)`` adjusts the view relative to + that mark. The :meth:`scan_mark` and :meth:`scan_dragto` methods wrap the two forms. .. method:: scan_mark(x) Record *x* and the current view in the spinbox window, for use with a - later :meth:`scan_dragto` call. This is typically associated with a mouse - button press in the widget. + later :meth:`scan_dragto` call. + This is typically associated with a mouse button press in the widget. .. method:: scan_dragto(x) Adjust the view by 10 times the difference between *x* and the *x* passed - to the last :meth:`scan_mark` call. This is typically associated with - mouse motion events, producing the effect of dragging the spinbox at high - speed through the window. + to the last :meth:`scan_mark` call. + This is typically associated with mouse motion events, producing the + effect of dragging the spinbox at high speed through the window. .. method:: selection(*args) A thin wrapper around the Tk ``selection`` widget subcommand, used to - adjust the selection within the spinbox. It has several forms depending on - the first argument, such as ``selection('adjust', index)``, - ``selection('clear')``, ``selection('element', ?elem?)``, - ``selection('from', index)``, ``selection('present')``, - ``selection('range', start, end)`` and ``selection('to', index)``. The - :meth:`selection_adjust`, :meth:`selection_clear`, + adjust the selection within the spinbox. + It has several forms depending on the first argument, such as + ``selection('adjust', index)``, ``selection('clear')``, + ``selection('element', ?elem?)``, ``selection('from', index)``, + ``selection('present')``, ``selection('range', start, end)`` and + ``selection('to', index)``. + The :meth:`selection_adjust`, :meth:`selection_clear`, :meth:`selection_element`, :meth:`selection_from`, - :meth:`selection_present`, :meth:`selection_range` and :meth:`selection_to` - methods wrap these forms. + :meth:`selection_present`, :meth:`selection_range` and + :meth:`selection_to` methods wrap these forms. .. method:: selection_adjust(index) Locate the end of the selection nearest to the character given by *index* and adjust that end of the selection to be at *index* (including but not - going beyond *index*). The other end becomes the anchor point for future - :meth:`selection_to` calls. If the selection is not currently in the - spinbox, a new selection is created to include the characters between - *index* and the most recent anchor point, inclusive. + going beyond *index*). + The other end becomes the anchor point for future :meth:`selection_to` + calls. + If the selection is not currently in the spinbox, a new selection is + created to include the characters between *index* and the most recent + anchor point, inclusive. .. method:: selection_clear() - Clear the selection if it is currently in this widget. If the selection is - not in this widget, the method has no effect. + Clear the selection if it is currently in this widget. + If the selection is not in this widget, the method has no effect. .. method:: selection_element(element=None) - Set or get the currently selected element. If *element* (one of - ``'buttonup'``, ``'buttondown'`` or ``'none'``) is given, that spin button - is selected and displayed depressed; otherwise the name of the currently - selected element is returned. + Set or get the currently selected element. + If *element* (one of ``'buttonup'``, ``'buttondown'`` or ``'none'``) is + given, that spin button is selected and displayed depressed; otherwise + the name of the currently selected element is returned. .. method:: selection_from(index) @@ -4364,22 +4597,24 @@ Widget classes .. method:: selection_range(start, end) Set the selection to include the characters starting with the one indexed - by *start* and ending with the one just before *end*. If *end* refers to - the same character as *start* or an earlier one, the selection is cleared. + by *start* and ending with the one just before *end*. + If *end* refers to the same character as *start* or an earlier one, the + selection is cleared. .. versionadded:: 3.8 .. method:: selection_to(index) - Set the selection between *index* and the anchor point. If *index* is - before the anchor point, the selection runs from *index* up to but not - including the anchor point; if it is after, the selection runs from the - anchor point up to but not including *index*; if it is the same, nothing - happens. The anchor point is the one set by the most recent - :meth:`selection_from` or :meth:`selection_adjust` call. If the selection - is not in this widget, a new selection is created using the most recent - anchor point. + Set the selection between *index* and the anchor point. + If *index* is before the anchor point, the selection runs from *index* up + to but not including the anchor point; if it is after, the selection runs + from the anchor point up to but not including *index*; if it is the same, + nothing happens. + The anchor point is the one set by the most recent :meth:`selection_from` + or :meth:`selection_adjust` call. + If the selection is not in this widget, a new selection is created using + the most recent anchor point. .. versionadded:: 3.8 @@ -4387,60 +4622,66 @@ Widget classes .. class:: Text(master=None, cnf={}, **kw) - A :class:`!Text` widget displays and edits multi-line text. Portions of the - text may be styled with **tags**, particular positions may be annotated with - floating **marks**, and arbitrary images and other widgets may be embedded - in the text. The widget also provides an unlimited undo/redo mechanism and - supports peer widgets that share the same underlying data. Inherits from - :class:`Widget`, :class:`XView` and :class:`YView`, so the view can be - scrolled horizontally and vertically with :meth:`~XView.xview` and - :meth:`~YView.yview`. Refer to the Tk ``text`` manual page for the full - list of options. + A :class:`!Text` widget displays and edits multi-line text. + Portions of the text may be styled with **tags**, particular positions may + be annotated with floating **marks**, and arbitrary images and other widgets + may be embedded in the text. + The widget also provides an unlimited undo/redo mechanism and supports peer + widgets that share the same underlying data. + Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the + view can be scrolled horizontally and vertically with :meth:`~XView.xview` + and :meth:`~YView.yview`. + Refer to the Tk ``text`` manual page for the full list of options. Most of the methods take one or more *index* arguments that identify a - position within the text. As described in the Tk ``text`` manual page, an - index is a string consisting of a base, optionally followed by one or more - modifiers. The base may be ``'line.char'`` (line *line*, character *char*, - where lines are counted from 1 and characters within a line from 0; - ``'line.end'`` refers to the newline ending the line), ``'end'`` (the - position just after the last newline), the name of a mark, ``'tag.first'`` - or ``'tag.last'`` (the first character tagged with *tag*, or the position - just after the last such character), the name of an embedded image or - window, or ``@x,y`` (the character covering pixel coordinates *x*, *y* in - the widget). A modifier such as ``'+5 chars'``, ``'-3 lines'``, - ``'linestart'``, ``'lineend'``, ``'wordstart'`` or ``'wordend'`` adjusts the - index relative to its base; several modifiers may be combined and are - applied from left to right, for example ``'insert wordstart - 1 c'``. + position within the text. + As described in the Tk ``text`` manual page, an index is a string consisting + of a base, optionally followed by one or more modifiers. + The base may be ``'line.char'`` (line *line*, character *char*, where lines + are counted from 1 and characters within a line from 0; ``'line.end'`` + refers to the newline ending the line), ``'end'`` (the position just after + the last newline), the name of a mark, ``'tag.first'`` or ``'tag.last'`` + (the first character tagged with *tag*, or the position just after the last + such character), the name of an embedded image or window, or ``@x,y`` (the + character covering pixel coordinates *x*, *y* in the widget). + A modifier such as ``'+5 chars'``, ``'-3 lines'``, ``'linestart'``, + ``'lineend'``, ``'wordstart'`` or ``'wordend'`` adjusts the index relative + to its base; several modifiers may be combined and are applied from left to + right, for example ``'insert wordstart - 1 c'``. .. method:: insert(index, chars, *args) Insert the string *chars* just before the character at *index* (if - *index* is ``'end'``, just before the final newline). By default the new - text inherits any tags present on both sides of the insertion point. If - *args* is given, it consists of alternating *tagList*, *chars* values: the - preceding *chars* receives exactly the tags listed (a tag list may be a - single tag name or a sequence of names), overriding the surrounding tags. + *index* is ``'end'``, just before the final newline). + By default the new text inherits any tags present on both sides of the + insertion point. + If *args* is given, it consists of alternating *tagList*, *chars* values: + the preceding *chars* receives exactly the tags listed (a tag list may be + a single tag name or a sequence of names), overriding the surrounding + tags. .. method:: delete(index1, index2=None) Delete the range of characters from *index1* up to but not including - *index2*. If *index2* is omitted, the single character at *index1* is - deleted. The widget always keeps a newline as its last character, so a - deletion that would remove it is adjusted accordingly. + *index2*. + If *index2* is omitted, the single character at *index1* is deleted. + The widget always keeps a newline as its last character, so a deletion + that would remove it is adjusted accordingly. .. method:: replace(index1, index2, chars, *args) Replace the range of characters from *index1* up to but not including - *index2* with *chars*. This is equivalent to a :meth:`delete` followed by - an :meth:`insert` at *index1*; *args* is interpreted as for - :meth:`insert`. + *index2* with *chars*. + This is equivalent to a :meth:`delete` followed by an :meth:`insert` at + *index1*; *args* is interpreted as for :meth:`insert`. .. versionadded:: 3.3 .. method:: get(index1, index2=None) Return the text from *index1* up to but not including *index2* as a - string. If *index2* is omitted, return the single character at *index1*. + string. + If *index2* is omitted, return the single character at *index1*. Embedded images and windows are omitted from the result. .. method:: index(index) @@ -4457,15 +4698,16 @@ Widget classes .. method:: count(index1, index2, *options, return_ints=False) Count the number of items of the requested kinds between *index1* and - *index2*; the count is negative if *index1* is after *index2*. Each of - *options* names a kind of item to count: ``'chars'``, ``'displaychars'``, - ``'displayindices'``, ``'displaylines'``, ``'indices'``, ``'lines'``, - ``'xpixels'`` or ``'ypixels'`` (the default, used when no option is given, - is ``'indices'``). The pseudo-option ``'update'`` forces any out-of-date - layout information to be recalculated before the following options are - evaluated. When *return_ints* is true and a single counting option is - given, return a plain integer; otherwise return a tuple with one integer - per counting option (or ``None`` if the result is empty). + *index2*; the count is negative if *index1* is after *index2*. + Each of *options* names a kind of item to count: ``'chars'``, + ``'displaychars'``, ``'displayindices'``, ``'displaylines'``, + ``'indices'``, ``'lines'``, ``'xpixels'`` or ``'ypixels'`` (the default, + used when no option is given, is ``'indices'``). + The pseudo-option ``'update'`` forces any out-of-date layout information + to be recalculated before the following options are evaluated. + When *return_ints* is true and a single counting option is given, return + a plain integer; otherwise return a tuple with one integer per counting + option (or ``None`` if the result is empty). .. versionadded:: 3.3 @@ -4475,10 +4717,10 @@ Widget classes .. method:: see(index) - Adjust the view so that the character given by *index* is visible. If it - is already visible the method has no effect; if it is a short distance out - of view the widget scrolls just enough to bring it to the nearest edge, - otherwise it scrolls to center *index* in the window. + Adjust the view so that the character given by *index* is visible. + If it is already visible the method has no effect; if it is a short + distance out of view the widget scrolls just enough to bring it to the + nearest edge, otherwise it scrolls to center *index* in the window. .. method:: bbox(index) @@ -4491,19 +4733,19 @@ Widget classes Return a tuple ``(x, y, width, height, baseline)`` describing the display line that contains *index*: the first four values give the bounding box of the line in pixels and *baseline* gives the offset of the baseline - measured down from the top of the area. Return ``None`` if that display - line is not visible on the screen. + measured down from the top of the area. + Return ``None`` if that display line is not visible on the screen. .. method:: mark_set(markName, index) - Set the mark named *markName* to the position just before the character at - *index*, creating the mark if it does not already exist. A mark created - this way has right gravity by default. + Set the mark named *markName* to the position just before the character + at *index*, creating the mark if it does not already exist. + A mark created this way has right gravity by default. .. method:: mark_unset(*markNames) - Remove each of the marks named in *markNames*. The special ``insert`` and - ``current`` marks may not be removed. + Remove each of the marks named in *markNames*. + The special ``insert`` and ``current`` marks may not be removed. .. method:: mark_names() @@ -4512,36 +4754,39 @@ Widget classes .. method:: mark_gravity(markName, direction=None) If *direction* is omitted, return the gravity of mark *markName*, either - ``'left'`` or ``'right'``. Otherwise set its gravity to *direction*. The - gravity determines on which side of the mark text inserted at the mark's - position appears: a mark with right gravity (the default) stays to the - right of such text. + ``'left'`` or ``'right'``. + Otherwise set its gravity to *direction*. + The gravity determines on which side of the mark text inserted at the + mark's position appears: a mark with right gravity (the default) stays to + the right of such text. .. method:: mark_next(index) Return the name of the first mark at or after *index*, or ``None`` if - there is none. When *index* is the name of a mark, the search starts just - after that mark. + there is none. + When *index* is the name of a mark, the search starts just after that + mark. .. method:: mark_previous(index) Return the name of the last mark at or before *index*, or ``None`` if - there is none. When *index* is the name of a mark, the search starts just - before that mark. + there is none. + When *index* is the name of a mark, the search starts just before that + mark. .. method:: tag_add(tagName, index1, *args) Add the tag *tagName* to the range of characters from *index1* up to but - not including the next index in *args*. Further pairs of indices may - follow in *args* to tag additional ranges; a trailing single index tags - just the character at that index. + not including the next index in *args*. + Further pairs of indices may follow in *args* to tag additional ranges; a + trailing single index tags just the character at that index. .. method:: tag_remove(tagName, index1, index2=None) Remove the tag *tagName* from the characters from *index1* up to but not - including *index2* (or from the single character at *index1* if *index2* is - omitted). The tag itself continues to exist even if no characters carry - it. + including *index2* (or from the single character at *index1* if *index2* + is omitted). + The tag itself continues to exist even if no characters carry it. .. method:: tag_delete(*tagNames) @@ -4553,15 +4798,17 @@ Widget classes .. method:: tag_configure(tagName, cnf=None, **kw) - Query or modify the configuration options of the tag *tagName*. This - mirrors :meth:`~Widget.configure`, except that it applies to a tag rather - than to the widget as a whole: with no options it returns a dictionary - describing the current options, otherwise it sets the given options. + Query or modify the configuration options of the tag *tagName*. + This mirrors :meth:`~Widget.configure`, except that it applies to a tag + rather than to the widget as a whole: with no options it returns a + dictionary describing the current options, otherwise it sets the given + options. Supported tag options control the appearance of the tagged text and include *background*, *foreground*, *font*, *justify*, *underline*, - *overstrike*, *relief*, *borderwidth*, the margin and spacing options, and - *elide* (whether the text is hidden). Defining a tag this way also gives - it a priority higher than any existing tag. + *overstrike*, *relief*, *borderwidth*, the margin and spacing options, + and *elide* (whether the text is hidden). + Defining a tag this way also gives it a priority higher than any existing + tag. :meth:`tag_config` is an alias of :meth:`!tag_configure`. @@ -4574,33 +4821,36 @@ Widget classes If *index* is omitted, return a tuple of the names of all tags defined in the widget; otherwise return only the names of the tags applied to the - character at *index*. The names are ordered from lowest to highest - priority. + character at *index*. + The names are ordered from lowest to highest priority. .. method:: tag_ranges(tagName) Return a tuple of indices describing all ranges of text tagged with - *tagName*. The result alternates start and end indices, so that elements - ``2*i`` and ``2*i+1`` bound the *i*-th range. + *tagName*. + The result alternates start and end indices, so that elements ``2*i`` and + ``2*i+1`` bound the *i*-th range. .. method:: tag_nextrange(tagName, index1, index2=None) - Search forward from *index1* (up to *index2* if given) for the first range - of characters tagged with *tagName*, and return a two-element tuple of its - start and end indices, or an empty tuple if there is no such range. + Search forward from *index1* (up to *index2* if given) for the first + range of characters tagged with *tagName*, and return a two-element tuple + of its start and end indices, or an empty tuple if there is no such + range. .. method:: tag_prevrange(tagName, index1, index2=None) Search backward from *index1* (down to *index2* if given) for the nearest preceding range of characters tagged with *tagName*, and return a - two-element tuple of its start and end indices, or an empty tuple if there - is no such range. + two-element tuple of its start and end indices, or an empty tuple if + there is no such range. .. method:: tag_raise(tagName, aboveThis=None) Raise the priority of tag *tagName* so that it is just above the priority of *aboveThis*, or to the highest priority of all tags if *aboveThis* is - omitted. When the display options of overlapping tags conflict, the + omitted. + When the display options of overlapping tags conflict, the higher-priority tag wins. .. method:: tag_lower(tagName, belowThis=None) @@ -4612,16 +4862,19 @@ Widget classes .. method:: tag_bind(tagName, sequence, func, add=None) Bind the event *sequence* on characters tagged with *tagName* to the - callback *func*, so that *func* is invoked when that event occurs over such - a character. If *add* is true the binding is added alongside any existing - bindings for *sequence*, otherwise it replaces them. Works like - :meth:`~Misc.bind` and returns the identifier of the new binding. + callback *func*, so that *func* is invoked when that event occurs over + such a character. + If *add* is true the binding is added alongside any existing bindings for + *sequence*, otherwise it replaces them. + Works like :meth:`~Misc.bind` and returns the identifier of the new + binding. .. method:: tag_unbind(tagName, sequence, funcid=None) Remove the bindings of the event *sequence* on characters tagged with - *tagName*. If *funcid* is given, only that binding (as returned by - :meth:`tag_bind`) is removed and its callback is unregistered. + *tagName*. + If *funcid* is given, only that binding (as returned by :meth:`tag_bind`) + is removed and its callback is unregistered. .. versionchanged:: 3.13 If *funcid* is given, only that callback is unbound. @@ -4631,9 +4884,10 @@ Widget classes Embed an image at *index* and return the name assigned to this image instance, which may then be used as an index or passed to the other - ``image_*`` methods. The options, given in *cnf* and *kw*, include - *image* (the Tk image to display), *name* (a base name for the instance), - *align*, *padx* and *pady*. + ``image_*`` methods. + The options, given in *cnf* and *kw*, include *image* (the Tk image to + display), *name* (a base name for the instance), *align*, *padx* and + *pady*. .. method:: image_cget(index, option) @@ -4651,10 +4905,11 @@ Widget classes .. method:: window_create(index, cnf={}, **kw) - Embed a window (any widget) at *index*. The options, given in *cnf* and - *kw*, include *window* (the widget to embed), *create* (a callback that - creates the widget on demand), *align*, *stretch*, *padx* and *pady*. The - embedded widget must be a descendant of the text widget's parent. + Embed a window (any widget) at *index*. + The options, given in *cnf* and *kw*, include *window* (the widget to + embed), *create* (a callback that creates the widget on demand), *align*, + *stretch*, *padx* and *pady*. + The embedded widget must be a descendant of the text widget's parent. .. method:: window_cget(index, option) @@ -4679,30 +4934,35 @@ Widget classes Low-level wrapper around the Tk ``edit`` widget command that controls the undo/redo mechanism and the modified flag; *args* is the ``edit`` - subcommand and its arguments. The :meth:`!edit_\*` methods below are - thin wrappers around it and are usually more convenient. + subcommand and its arguments. + The :meth:`!edit_\*` methods below are thin wrappers around it and are + usually more convenient. .. method:: edit_modified(arg=None) If *arg* is omitted, return the current state of the modified flag as ``0`` or ``1``; the flag is set automatically whenever the text is - inserted or deleted. Otherwise set the flag to the boolean *arg*. + inserted or deleted. + Otherwise set the flag to the boolean *arg*. .. method:: edit_undo() Undo the most recent edit action, that is, all the inserts and deletes recorded on the undo stack since the previous separator, and move it to - the redo stack. Raises :exc:`TclError` if the undo stack is empty. Has - no effect unless the *undo* option is true. Since Tk 9.0, returns a tuple - of indices delimiting the ranges of text that were changed. + the redo stack. + Raises :exc:`TclError` if the undo stack is empty. + Has no effect unless the *undo* option is true. + Since Tk 9.0, returns a tuple of indices delimiting the ranges of text + that were changed. .. method:: edit_redo() Reapply the most recently undone edit action, provided no further edits - have been made since, and move it back to the undo stack. Raises - :exc:`TclError` if the redo stack is empty. Has no effect unless the - *undo* option is true. Since Tk 9.0, returns a tuple of indices delimiting - the ranges of text that were changed. + have been made since, and move it back to the undo stack. + Raises :exc:`TclError` if the redo stack is empty. + Has no effect unless the *undo* option is true. + Since Tk 9.0, returns a tuple of indices delimiting the ranges of text + that were changed. .. method:: edit_reset() @@ -4711,24 +4971,27 @@ Widget classes .. method:: edit_separator() Push a separator onto the undo stack, marking a boundary between edit - actions for undo and redo. Has no effect unless the *undo* option is - true. Separators are inserted automatically when the *autoseparators* - option is true. + actions for undo and redo. + Has no effect unless the *undo* option is true. + Separators are inserted automatically when the *autoseparators* option is + true. .. method:: search(pattern, index, stopindex=None, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, *, nolinestop=None, strictlimits=None) - Search for *pattern* starting at *index* and return the index of the first - character of the first match, or an empty string if there is no match. + Search for *pattern* starting at *index* and return the index of the + first character of the first match, or an empty string if there is no + match. Searching stops at *stopindex* if given; otherwise it wraps around the - ends of the text until the starting position is reached again. The - following boolean keyword flags control the search: *forwards* or + ends of the text until the starting position is reached again. + The following boolean keyword flags control the search: *forwards* or *backwards* select the direction (forward is the default); *exact* (the default) or *regexp* select literal or regular-expression matching; *nocase* makes the match case-insensitive; *elide* causes hidden text to be searched as well; *nolinestop* (regexp only) lets ``.`` and ``[^`` match newlines; and *strictlimits* requires the whole match to lie within - *index* and *stopindex*. If *count* is a :class:`Variable`, the number of - index positions in the match is stored in it. + *index* and *stopindex*. + If *count* is a :class:`Variable`, the number of index positions in the + match is stored in it. .. versionchanged:: 3.15 Added the *nolinestop* and *strictlimits* parameters. @@ -4736,11 +4999,13 @@ Widget classes .. method:: search_all(pattern, index, stopindex=None, *, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, nolinestop=None, overlap=None, strictlimits=None) - Like :meth:`search`, but find every match in the searched range and return - a tuple of the starting indices of all matches (empty if there are none). + Like :meth:`search`, but find every match in the searched range and + return a tuple of the starting indices of all matches (empty if there are + none). By default overlapping matches are not reported; passing a true *overlap* - returns every match that is not wholly contained in another. If *count* - is a :class:`Variable`, it receives a list with one element per match. + returns every match that is not wholly contained in another. + If *count* is a :class:`Variable`, it receives a list with one element + per match. .. versionadded:: 3.15 @@ -4748,42 +5013,45 @@ Widget classes .. method:: scan_mark(x, y) Record *x*, *y* and the current view, for use with later - :meth:`scan_dragto` calls. This is typically bound to a mouse button - press in the widget. + :meth:`scan_dragto` calls. + This is typically bound to a mouse button press in the widget. .. method:: scan_dragto(x, y) Scroll the widget by 10 times the difference between *x*, *y* and the - coordinates passed to the last :meth:`scan_mark` call. This is typically - bound to mouse motion events, producing the effect of dragging the text at - high speed through the window. + coordinates passed to the last :meth:`scan_mark` call. + This is typically bound to mouse motion events, producing the effect of + dragging the text at high speed through the window. .. method:: debug(boolean=None) - If *boolean* is omitted, return whether internal consistency checks of the - B-tree data structure are enabled. Otherwise enable or disable them. The - setting is shared by all text widgets and may noticeably slow down widgets - holding large amounts of text. + If *boolean* is omitted, return whether internal consistency checks of + the B-tree data structure are enabled. + Otherwise enable or disable them. + The setting is shared by all text widgets and may noticeably slow down + widgets holding large amounts of text. .. method:: dump(index1, index2=None, command=None, **kw) Return the contents of the widget from *index1* up to but not including *index2* (or just the segment at *index1* if *index2* is omitted), - including text and information about marks, tags, images and windows. The - result is a list of ``(key, value, index)`` triples, where *key* is one of - ``'text'``, ``'mark'``, ``'tagon'``, ``'tagoff'``, ``'image'`` or - ``'window'``. By default all kinds are reported; passing any of the - keyword arguments *all*, *text*, *mark*, *tag*, *image* or *window* as true - restricts the dump to the selected kinds. If *command* is given, it is - called once per triple with the three values as arguments and nothing is - returned. + including text and information about marks, tags, images and windows. + The result is a list of ``(key, value, index)`` triples, where *key* is + one of ``'text'``, ``'mark'``, ``'tagon'``, ``'tagoff'``, ``'image'`` or + ``'window'``. + By default all kinds are reported; passing any of the keyword arguments + *all*, *text*, *mark*, *tag*, *image* or *window* as true restricts the + dump to the selected kinds. + If *command* is given, it is called once per triple with the three values + as arguments and nothing is returned. .. method:: peer_create(newPathName, cnf={}, **kw) Create a peer text widget with the path name *newPathName* that shares this widget's underlying data (text, marks, tags, images and the undo - stack). Changes made through any peer are reflected in all of them. By - default the peer covers the same lines as this widget; standard text + stack). + Changes made through any peer are reflected in all of them. + By default the peer covers the same lines as this widget; standard text options, including *startline* and *endline*, may be given to override this. @@ -4791,15 +5059,16 @@ Widget classes .. method:: peer_names() - Return a tuple of the path names of this widget's peers, not including the - widget itself. + Return a tuple of the path names of this widget's peers, not including + the widget itself. .. versionadded:: 3.3 .. method:: yview_pickplace(*what) - Adjust the view so that the location given by *what* is visible. This is - an obsolete equivalent of :meth:`see`, which should be used instead. + Adjust the view so that the location given by *what* is visible. + This is an obsolete equivalent of :meth:`see`, which should be used + instead. Variable classes @@ -4807,18 +5076,20 @@ Variable classes .. class:: Variable(master=None, value=None, name=None) - The base class for the Tk variable wrappers. A Tk variable is a value - stored in the Tcl interpreter that can be linked to widgets through their - *variable* or *textvariable* options (see :ref:`coupling-widget-variables`), - so that changes propagate both ways: updating the variable updates every - widget bound to it, and a user editing such a widget updates the variable. + The base class for the Tk variable wrappers. + A Tk variable is a value stored in the Tcl interpreter that can be linked to + widgets through their *variable* or *textvariable* options (see + :ref:`coupling-widget-variables`), so that changes propagate both ways: + updating the variable updates every widget bound to it, and a user editing + such a widget updates the variable. *master* is the widget whose Tcl interpreter owns the variable; if omitted, - the default root window is used. *value* is the initial value; if omitted, - a type-specific default is used. *name* is the name of the variable in the - Tcl interpreter; if omitted, a unique name of the form ``'PY_VARnum'`` is - generated. If *name* matches an existing variable and *value* is omitted, - the existing value is retained. + the default root window is used. + *value* is the initial value; if omitted, a type-specific default is used. + *name* is the name of the variable in the Tcl interpreter; if omitted, a + unique name of the form ``'PY_VARnum'`` is generated. + If *name* matches an existing variable and *value* is omitted, the existing + value is retained. In most cases you should use one of the typed subclasses below -- :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` or @@ -4830,9 +5101,9 @@ Variable classes .. method:: get() - Return the current value of the variable. For the base class the value - is returned as a string; the typed subclasses convert it to the - appropriate Python type. + Return the current value of the variable. + For the base class the value is returned as a string; the typed + subclasses convert it to the appropriate Python type. .. method:: initialize(value) :no-typesetting: @@ -4847,8 +5118,9 @@ Variable classes .. method:: trace_add(mode, callback) Register *callback* to be called when the variable is accessed according - to *mode*. *mode* is one of the strings ``'array'``, ``'read'``, - ``'write'`` or ``'unset'``, or a list or tuple of such strings. + to *mode*. + *mode* is one of the strings ``'array'``, ``'read'``, ``'write'`` or + ``'unset'``, or a list or tuple of such strings. When triggered, *callback* is called with three arguments: the name of the Tcl variable, an index (or an empty string if the variable is not an @@ -4861,9 +5133,9 @@ Variable classes .. method:: trace_remove(mode, cbname) - Remove a trace callback from the variable. *mode* must match the *mode* - that was passed to :meth:`trace_add`, and *cbname* is the callback name - returned by :meth:`trace_add`. + Remove a trace callback from the variable. + *mode* must match the *mode* that was passed to :meth:`trace_add`, and + *cbname* is the callback name returned by :meth:`trace_add`. .. versionadded:: 3.6 @@ -4881,9 +5153,10 @@ Variable classes .. method:: trace_variable(mode, callback) Register *callback* to be called when the variable is accessed according - to *mode*. *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for - read, write or unset. Return the internal name of the registered - callback. + to *mode*. + *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for read, write + or unset. + Return the internal name of the registered callback. .. deprecated:: 3.6 Use :meth:`trace_add` instead. This method wraps a Tcl feature that @@ -4910,8 +5183,8 @@ Variable classes .. class:: StringVar(master=None, value=None, name=None) - A :class:`Variable` subclass that holds a string. The default value is - ``''``. + A :class:`Variable` subclass that holds a string. + The default value is ``''``. .. method:: get() @@ -4920,8 +5193,8 @@ Variable classes .. class:: IntVar(master=None, value=None, name=None) - A :class:`Variable` subclass that holds an integer. The default value is - ``0``. + A :class:`Variable` subclass that holds an integer. + The default value is ``0``. .. method:: get() @@ -4930,8 +5203,8 @@ Variable classes .. class:: DoubleVar(master=None, value=None, name=None) - A :class:`Variable` subclass that holds a float. The default value is - ``0.0``. + A :class:`Variable` subclass that holds a float. + The default value is ``0.0``. .. method:: get() @@ -4940,13 +5213,14 @@ Variable classes .. class:: BooleanVar(master=None, value=None, name=None) - A :class:`Variable` subclass that holds a boolean. The default value is - ``False``. + A :class:`Variable` subclass that holds a boolean. + The default value is ``False``. .. method:: get() - Return the value of the variable as a :class:`bool`. Raise a - :exc:`ValueError` if the value cannot be interpreted as a boolean. + Return the value of the variable as a :class:`bool`. + Raise a :exc:`ValueError` if the value cannot be interpreted as a + boolean. .. method:: initialize(value) :no-typesetting: @@ -4964,12 +5238,13 @@ Image classes .. class:: Image(imgtype, name=None, cnf={}, master=None, **kw) - Base class for Tk images. *imgtype* is the Tk image type, one of - ``'photo'`` or ``'bitmap'``. An image is a named object that can be - displayed by widgets through their *image* option; deleting all references - to the :class:`!Image` object deletes the underlying Tk image. Usually you - create a :class:`PhotoImage` or :class:`BitmapImage` rather than an - :class:`!Image` directly. + Base class for Tk images. + *imgtype* is the Tk image type, one of ``'photo'`` or ``'bitmap'``. + An image is a named object that can be displayed by widgets through their + *image* option; deleting all references to the :class:`!Image` object + deletes the underlying Tk image. + Usually you create a :class:`PhotoImage` or :class:`BitmapImage` rather than + an :class:`!Image` directly. The image's configuration options are given by *cnf* and *kw* and may be queried and changed later with the mapping protocol (using ``image[key]``) @@ -4980,8 +5255,9 @@ Image classes .. method:: configure(**kw) - Modify one or more configuration options of the image. The valid options - depend on the image type; see :class:`PhotoImage` and :class:`BitmapImage`. + Modify one or more configuration options of the image. + The valid options depend on the image type; see :class:`PhotoImage` and + :class:`BitmapImage`. :meth:`config` is an alias of :meth:`!configure`. .. method:: height() @@ -4994,16 +5270,17 @@ Image classes .. method:: type() - Return the type of the image, that is the value of *imgtype* with which it - was created (for example ``'photo'`` or ``'bitmap'``). + Return the type of the image, that is the value of *imgtype* with which + it was created (for example ``'photo'`` or ``'bitmap'``). .. class:: PhotoImage(name=None, cnf={}, master=None, **kw) A full-color image (the Tk ``photo`` image type), stored internally with a - varying degree of transparency per pixel. It can read and write GIF, - PPM/PGM and (in Tk 8.6 and later) PNG files, read SVG files (in Tk 9.0 and - later), and be drawn in widgets. Inherits from :class:`Image`. + varying degree of transparency per pixel. + It can read and write GIF, PPM/PGM and (in Tk 8.6 and later) PNG files, read + SVG files (in Tk 9.0 and later), and be drawn in widgets. + Inherits from :class:`Image`. The configuration options include *data* (the image contents as a string), *file* (the name of a file to read the contents from), *format* (the name of @@ -5012,9 +5289,9 @@ Image classes .. method:: blank() - Blank the image; that is, set the entire image to have no data, so that it - is displayed as transparent and the background of whatever window it is - displayed in shows through. + Blank the image; that is, set the entire image to have no data, so that + it is displayed as transparent and the background of whatever window it + is displayed in shows through. .. method:: cget(option) @@ -5024,18 +5301,20 @@ Image classes Return a new :class:`PhotoImage` with a copy of this image. - *from_coords* specifies a rectangular sub-region of the source image to be - copied. It must be a tuple or a list of 1 to 4 integers - ``(x1, y1, x2, y2)``. ``(x1, y1)`` and ``(x2, y2)`` specify diagonally - opposite corners of the rectangle. If *x2* and *y2* are not specified, - they default to the bottom-right corner of the source image. The pixels - copied include the left and top edges of the rectangle but not the bottom - or right edges. If *from_coords* is not given, the whole source image is - copied. - - If *zoom* or *subsample* are specified, the image is transformed as in the - :meth:`zoom` or :meth:`subsample` methods. The value must be a single - integer or a pair of integers. + *from_coords* specifies a rectangular sub-region of the source image to + be copied. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. + ``(x1, y1)`` and ``(x2, y2)`` specify diagonally opposite corners of the + rectangle. + If *x2* and *y2* are not specified, they default to the bottom-right + corner of the source image. + The pixels copied include the left and top edges of the rectangle but not + the bottom or right edges. + If *from_coords* is not given, the whole source image is copied. + + If *zoom* or *subsample* are specified, the image is transformed as in + the :meth:`zoom` or :meth:`subsample` methods. + The value must be a single integer or a pair of integers. .. versionchanged:: 3.13 Added the *from_coords*, *zoom* and *subsample* parameters. @@ -5046,35 +5325,36 @@ Image classes compositingrule=None) Copy a region from *sourceImage* (which must be a :class:`PhotoImage`) - into this image, possibly with pixel zooming and/or subsampling. If no - options are specified, the whole of *sourceImage* is copied into this - image, starting at coordinates ``(0, 0)``. + into this image, possibly with pixel zooming and/or subsampling. + If no options are specified, the whole of *sourceImage* is copied into + this image, starting at coordinates ``(0, 0)``. - *from_coords* specifies a rectangular sub-region of the source image to be - copied, as in the :meth:`copy` method. + *from_coords* specifies a rectangular sub-region of the source image to + be copied, as in the :meth:`copy` method. *to* specifies a rectangular sub-region of the destination image to be - affected. It must be a tuple or a list of 1 to 4 integers - ``(x1, y1, x2, y2)``. If *x2* and *y2* are not specified, they default to - ``(x1, y1)`` plus the size of the source region (after subsampling and - zooming, if specified). If *x2* and *y2* are specified, the source region - is replicated if necessary to fill the destination region in a tiled - fashion. + affected. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. + If *x2* and *y2* are not specified, they default to ``(x1, y1)`` plus the + size of the source region (after subsampling and zooming, if specified). + If *x2* and *y2* are specified, the source region is replicated if + necessary to fill the destination region in a tiled fashion. If *shrink* is true, the size of the destination image is reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. - If *zoom* or *subsample* are specified, the image is transformed as in the - :meth:`zoom` or :meth:`subsample` methods. The value must be a single - integer or a pair of integers. + If *zoom* or *subsample* are specified, the image is transformed as in + the :meth:`zoom` or :meth:`subsample` methods. + The value must be a single integer or a pair of integers. - *compositingrule* specifies how transparent pixels in the source image are - combined with the destination image. With ``'overlay'`` (the default), - the old contents of the destination image remain visible, as if the source - image were printed on a piece of transparent film and placed over the top - of the destination. With ``'set'``, the old contents of the destination - image are discarded and the source image is used as-is. + *compositingrule* specifies how transparent pixels in the source image + are combined with the destination image. + With ``'overlay'`` (the default), the old contents of the destination + image remain visible, as if the source image were printed on a piece of + transparent film and placed over the top of the destination. + With ``'set'``, the old contents of the destination image are discarded + and the source image is used as-is. .. versionadded:: 3.13 @@ -5084,18 +5364,18 @@ Image classes Return the image data. - *format* specifies the name of the image file format handler to use. If - it is not given, the data is returned as a tuple (one element per row) of - strings containing space-separated (one element per pixel/column) colors - in ``#RRGGBB`` format. + *format* specifies the name of the image file format handler to use. + If it is not given, the data is returned as a tuple (one element per row) + of strings containing space-separated (one element per pixel/column) + colors in ``#RRGGBB`` format. *from_coords* specifies a rectangular region of the image to be returned. - It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. If - only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` to - the bottom-right corner of the image. If all four coordinates are given, - they specify diagonally opposite corners of the region, including - ``(x1, y1)`` and excluding ``(x2, y2)``. If *from_coords* is not given, - the whole image is returned. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. + If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` + to the bottom-right corner of the image. + If all four coordinates are given, they specify diagonally opposite + corners of the region, including ``(x1, y1)`` and excluding ``(x2, y2)``. + If *from_coords* is not given, the whole image is returned. If *background* is specified, the data does not contain any transparency information; in all transparent pixels the color is replaced by the @@ -5120,10 +5400,11 @@ Image classes example ``"{red green} {blue yellow}"``). *to* specifies the coordinates of the region of the image into which the - data are copied. It must be a tuple or a list of 2 or 4 integers - ``(x1, y1)`` or ``(x1, y1, x2, y2)`` giving the top-left corner, and - optionally the bottom-right corner, of the region. The default position - is ``(0, 0)``. + data are copied. + It must be a tuple or a list of 2 or 4 integers ``(x1, y1)`` or + ``(x1, y1, x2, y2)`` giving the top-left corner, and optionally the + bottom-right corner, of the region. + The default position is ``(0, 0)``. .. method:: read(filename, format=None, *, from_coords=None, to=None, \ shrink=False) @@ -5132,16 +5413,19 @@ Image classes *format* specifies the format of the image data in the file. - *from_coords* specifies a rectangular sub-region of the image file data to - be copied to the destination image. It must be a tuple or a list of 1 to - 4 integers ``(x1, y1, x2, y2)``. If only *x1* and *y1* are specified, the - region extends from ``(x1, y1)`` to the bottom-right corner of the image - in the file. If all four coordinates are given, they specify diagonally - opposite corners of the region. If *from_coords* is not given, the whole - of the image in the file is read. + *from_coords* specifies a rectangular sub-region of the image file data + to be copied to the destination image. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. + If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` + to the bottom-right corner of the image in the file. + If all four coordinates are given, they specify diagonally opposite + corners of the region. + If *from_coords* is not given, the whole of the image in the file is + read. - *to* specifies the coordinates of the top-left corner of the region of the - image into which the data are read. The default is ``(0, 0)``. + *to* specifies the coordinates of the top-left corner of the region of + the image into which the data are read. + The default is ``(0, 0)``. If *shrink* is true, the size of the image is reduced, if necessary, so that the region into which the file data are read is at the bottom-right @@ -5153,11 +5437,12 @@ Image classes .. method:: subsample(x, y='', *, from_coords=None) Return a new :class:`PhotoImage` based on this image but using only every - *x*-th pixel in the X direction and every *y*-th pixel in the Y direction. + *x*-th pixel in the X direction and every *y*-th pixel in the Y + direction. If *y* is not given, it defaults to the same value as *x*. - *from_coords* specifies a rectangular sub-region of the source image to be - copied, as in the :meth:`copy` method. + *from_coords* specifies a rectangular sub-region of the source image to + be copied, as in the :meth:`copy` method. .. versionchanged:: 3.13 Added the *from_coords* parameter. @@ -5173,8 +5458,8 @@ Image classes .. method:: transparency_set(x, y, boolean) - Make the pixel at coordinates (*x*, *y*) fully transparent if *boolean* is - true, fully opaque otherwise. + Make the pixel at coordinates (*x*, *y*) fully transparent if *boolean* + is true, fully opaque otherwise. .. versionadded:: 3.8 @@ -5184,15 +5469,16 @@ Image classes Write image data from the image to the file named *filename*. - *format* specifies the name of the image file format handler to use. If - it is not given, the format is guessed from the file extension. + *format* specifies the name of the image file format handler to use. + If it is not given, the format is guessed from the file extension. *from_coords* specifies a rectangular region of the image to be written. - It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. If - only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` to - the bottom-right corner of the image. If all four coordinates are given, - they specify diagonally opposite corners of the region. If *from_coords* - is not given, the whole image is written. + It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. + If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` + to the bottom-right corner of the image. + If all four coordinates are given, they specify diagonally opposite + corners of the region. + If *from_coords* is not given, the whole image is written. If *background* is specified, the data does not contain any transparency information; in all transparent pixels the color is replaced by the @@ -5208,11 +5494,11 @@ Image classes .. method:: zoom(x, y='', *, from_coords=None) Return a new :class:`PhotoImage` with this image magnified by a factor of - *x* in the X direction and *y* in the Y direction. If *y* is not given, - it defaults to the same value as *x*. + *x* in the X direction and *y* in the Y direction. + If *y* is not given, it defaults to the same value as *x*. - *from_coords* specifies a rectangular sub-region of the source image to be - copied, as in the :meth:`copy` method. + *from_coords* specifies a rectangular sub-region of the source image to + be copied, as in the :meth:`copy` method. .. versionchanged:: 3.13 Added the *from_coords* parameter. @@ -5223,15 +5509,17 @@ Image classes A two-color image (the Tk ``bitmap`` image type) created from an X11 bitmap. Each pixel displays a foreground color, a background color, or nothing - (producing a transparent effect). Inherits from :class:`Image`. + (producing a transparent effect). + Inherits from :class:`Image`. The configuration options are *data* or *file* (the source bitmap, given as a string in X11 bitmap format or as the name of a file in that format), *maskdata* or *maskfile* (the mask bitmap, in the same forms), and - *foreground* and *background* (the two colors). For pixels where the mask is - zero the image displays nothing; for other pixels it displays the foreground - color where the source is one and the background color where the source is - zero. If *background* is set to an empty string, the background pixels are + *foreground* and *background* (the two colors). + For pixels where the mask is zero the image displays nothing; for other + pixels it displays the foreground color where the source is one and the + background color where the source is zero. + If *background* is set to an empty string, the background pixels are transparent. :class:`!BitmapImage` has no methods of its own beyond those inherited from @@ -5244,10 +5532,12 @@ Other classes .. class:: Event() A container for the attributes of an event passed to a callback bound with - :meth:`Misc.bind`. An :class:`!Event` instance has the following attributes, - each corresponding to a field of the underlying Tk event; depending on the - event type, some attributes may be set to the string ``'??'`` to indicate - that they are not meaningful. See :ref:`bindings-and-events`. + :meth:`Misc.bind`. + An :class:`!Event` instance has the following attributes, each corresponding + to a field of the underlying Tk event; depending on the event type, some + attributes may be set to the string ``'??'`` to indicate that they are not + meaningful. + See :ref:`bindings-and-events`. .. attribute:: serial @@ -5322,26 +5612,28 @@ Other classes .. attribute:: user_data The data string of a virtual event, as passed to the *data* option of - :meth:`Misc.event_generate`. It is ``'??'`` for non-virtual events. + :meth:`Misc.event_generate`. + It is ``'??'`` for non-virtual events. .. versionadded:: 3.15 .. attribute:: detail - A fixed detail string for ``Enter``, ``Leave``, ``FocusIn``, - ``FocusOut`` and ``ConfigureRequest`` events (see the Tcl/Tk - documentation). It is ``'??'`` for other events. + A fixed detail string for ``Enter``, ``Leave``, ``FocusIn``, ``FocusOut`` + and ``ConfigureRequest`` events (see the Tcl/Tk documentation). + It is ``'??'`` for other events. .. versionadded:: 3.15 .. class:: EventType(*values) - An :class:`enum.StrEnum` enumerating the Tk event types, used as the value of - :attr:`Event.type`. Its members include, among others, ``KeyPress``, - ``KeyRelease``, ``ButtonPress``, ``ButtonRelease``, ``Motion``, ``Enter``, - ``Leave``, ``FocusIn``, ``FocusOut``, ``Configure``, ``Map``, ``Unmap``, - ``Expose``, ``Destroy`` and ``MouseWheel``. + An :class:`enum.StrEnum` enumerating the Tk event types, used as the value + of :attr:`Event.type`. + Its members include, among others, ``KeyPress``, ``KeyRelease``, + ``ButtonPress``, ``ButtonRelease``, ``Motion``, ``Enter``, ``Leave``, + ``FocusIn``, ``FocusOut``, ``Configure``, ``Map``, ``Unmap``, ``Expose``, + ``Destroy`` and ``MouseWheel``. .. versionadded:: 3.6 @@ -5350,10 +5642,12 @@ Other classes .. class:: CallWrapper(func, subst, widget) Internal helper that wraps a Python callback so that it can be invoked from - Tcl. *func* is the Python function, *subst* is an optional function that + Tcl. + *func* is the Python function, *subst* is an optional function that pre-processes the Tcl arguments, and *widget* is the widget used for error - reporting. Instances are created automatically by :meth:`Misc.register`; this - class is not normally used directly. + reporting. + Instances are created automatically by :meth:`Misc.register`; this class is + not normally used directly. Module-level functions @@ -5361,30 +5655,34 @@ Module-level functions .. function:: NoDefaultRoot() - Inhibit the creation of an implicit default root window. Afterwards - :mod:`!tkinter` no longer creates a shared default root automatically, and - operations that rely on one --- such as constructing a widget without an - explicit *master* --- raise a :exc:`RuntimeError`. Call this early in larger - applications to make the root window explicit. + Inhibit the creation of an implicit default root window. + Afterwards :mod:`!tkinter` no longer creates a shared default root + automatically, and operations that rely on one --- such as constructing a + widget without an explicit *master* --- raise a :exc:`RuntimeError`. + Call this early in larger applications to make the root window explicit. .. function:: mainloop(n=0) Run the Tk main event loop on the default root window until all windows are - destroyed. Equivalent to calling :meth:`Misc.mainloop` on the default root. + destroyed. + Equivalent to calling :meth:`Misc.mainloop` on the default root. .. function:: getboolean(s) Convert the Tcl boolean string *s* (one of ``'1'``, ``'true'``, ``'yes'``, - ``'on'`` and similar, or their false counterparts) to a Python :class:`bool`. + ``'on'`` and similar, or their false counterparts) to a Python + :class:`bool`. Raise :exc:`TclError` for an invalid value. .. function:: getdouble(s) - Convert *s* to a floating-point number. This is the built-in :class:`float`. + Convert *s* to a floating-point number. + This is the built-in :class:`float`. .. function:: getint(s) - Convert *s* to an integer. This is the built-in :class:`int`. + Convert *s* to an integer. + This is the built-in :class:`int`. .. function:: image_names() @@ -5536,8 +5834,8 @@ and :mod:`tkinter.constants` namespaces. .. data:: FIRST LAST - Values for the *arrow* option of :class:`Canvas` line items, indicating which - ends have arrowheads. + Values for the *arrow* option of :class:`Canvas` line items, indicating + which ends have arrowheads. .. data:: MOVETO SCROLL diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst index f206bdb59d6583e..6870baf17ceb9fc 100644 --- a/Doc/library/tkinter.scrolledtext.rst +++ b/Doc/library/tkinter.scrolledtext.rst @@ -14,9 +14,10 @@ the "right thing." Using the :class:`ScrolledText` class is a lot easier than 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:`Pack`, :class:`Grid` and :class:`Place` geometry managers -are acquired from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to -be used directly to achieve most normal geometry management behavior. +methods of the :class:`Pack`, :class:`Grid` and :class:`Place` geometry +managers are acquired from the :class:`Frame` object. +This allows the :class:`ScrolledText` widget to be used directly to achieve +most normal geometry management behavior. Should more specific control be necessary, the following attributes are available: diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index 8f3a9e3dea38e11..00e372abbd98ab9 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -652,8 +652,9 @@ ttk.Notebook select that tab. Multiple notebooks in a single toplevel may be enabled for traversal, - including nested notebooks. However, notebook traversal only works - properly if all panes are direct children of the notebook. + including nested notebooks. + However, notebook traversal only works properly if all panes are direct + children of the notebook. Progressbar @@ -856,12 +857,13 @@ This widget accepts the following specific options: .. note:: - Tk 9.0 added several :class:`Treeview` features. The *selectmode* option - gained the values ``"single"`` and ``"multiple"``; the new widget options - *selecttype* (``"item"`` or ``"cell"`` selection), *striped* (zebra-striped - rows), and *titlecolumns* / *titleitems* (columns or rows frozen against - scrolling) were introduced; and items gained a *hidden* option. Tk 9.1 - added the *rowheight* and *headingheight* options. + Tk 9.0 added several :class:`Treeview` features. + The *selectmode* option gained the values ``"single"`` and ``"multiple"``; + the new widget options *selecttype* (``"item"`` or ``"cell"`` selection), + *striped* (zebra-striped rows), and *titlecolumns* / *titleitems* (columns + or rows frozen against scrolling) were introduced; and items gained a + *hidden* option. + Tk 9.1 added the *rowheight* and *headingheight* options. Item Options @@ -1260,8 +1262,8 @@ ttk.Treeview .. method:: tag_has(tagname, item=None) If *item* is specified, returns ``True`` if the specified *item* has the - given *tagname* and ``False`` otherwise. Otherwise, returns a tuple of all - items that have the specified tag. + given *tagname* and ``False`` otherwise. + Otherwise, returns a tuple of all items that have the specified tag. Availability: Tk 8.6 @@ -1625,16 +1627,16 @@ The valid options/values are: Additional widgets ------------------ -The following themed widgets complete the :mod:`tkinter.ttk` widget set. Each -is the themed counterpart of the like-named classic :mod:`tkinter` widget and -inherits the common methods of :class:`Widget`. +The following themed widgets complete the :mod:`tkinter.ttk` widget set. +Each is the themed counterpart of the like-named classic :mod:`tkinter` widget +and inherits the common methods of :class:`Widget`. .. class:: Button(master=None, **kw) Ttk :class:`Button` widget, displays a textual label and/or image, and - evaluates a command when pressed. It is the themed counterpart of - :class:`tkinter.Button` and inherits the common widget methods from - :class:`Widget`. + evaluates a command when pressed. + It is the themed counterpart of :class:`tkinter.Button` and inherits the + common widget methods from :class:`Widget`. .. method:: invoke() @@ -1644,9 +1646,9 @@ inherits the common methods of :class:`Widget`. .. class:: Checkbutton(master=None, **kw) Ttk :class:`Checkbutton` widget, used to control a Boolean variable that is - toggled on and off. It is the themed counterpart of - :class:`tkinter.Checkbutton` and inherits the common widget methods from - :class:`Widget`. + toggled on and off. + It is the themed counterpart of :class:`tkinter.Checkbutton` and inherits + the common widget methods from :class:`Widget`. .. method:: invoke() @@ -1657,9 +1659,10 @@ inherits the common methods of :class:`Widget`. .. class:: Entry(master=None, widget=None, **kw) Ttk :class:`Entry` widget, displays a one-line text string and allows the - user to edit it. It is the themed counterpart of :class:`tkinter.Entry` and - inherits the common widget methods from :class:`Widget` as well as the - editing methods from :class:`tkinter.Entry`. + user to edit it. + It is the themed counterpart of :class:`tkinter.Entry` and inherits the + common widget methods from :class:`Widget` as well as the editing methods + from :class:`tkinter.Entry`. .. method:: bbox(index) @@ -1673,55 +1676,58 @@ inherits the common methods of :class:`Widget`. .. method:: validate() - Force validation of the entry and return ``True`` if validation succeeded, - and ``False`` otherwise. + Force validation of the entry and return ``True`` if validation + succeeded, and ``False`` otherwise. .. class:: Frame(master=None, **kw) Ttk :class:`Frame` widget, a container used to group and lay out other - widgets. It is the themed counterpart of :class:`tkinter.Frame` and inherits - the common widget methods from :class:`Widget`. + widgets. + It is the themed counterpart of :class:`tkinter.Frame` and inherits the + common widget methods from :class:`Widget`. .. class:: Label(master=None, **kw) - Ttk :class:`Label` widget, displays a textual label and/or image. It is the - themed counterpart of :class:`tkinter.Label` and inherits the common widget - methods from :class:`Widget`. + Ttk :class:`Label` widget, displays a textual label and/or image. + It is the themed counterpart of :class:`tkinter.Label` and inherits the + common widget methods from :class:`Widget`. .. class:: Labelframe(master=None, **kw) Ttk :class:`Labelframe` widget, a container that draws a border and a title - label around its contents. It is the themed counterpart of - :class:`tkinter.LabelFrame` and inherits the common widget methods from - :class:`Widget`. + label around its contents. + It is the themed counterpart of :class:`tkinter.LabelFrame` and inherits the + common widget methods from :class:`Widget`. .. class:: Menubutton(master=None, **kw) Ttk :class:`Menubutton` widget, displays a textual label and/or image, and - pops up a menu when pressed. It is the themed counterpart of - :class:`tkinter.Menubutton` and inherits the common widget methods from - :class:`Widget`. + pops up a menu when pressed. + It is the themed counterpart of :class:`tkinter.Menubutton` and inherits the + common widget methods from :class:`Widget`. .. class:: OptionMenu(master, variable, default=None, *values, **kwargs) Ttk :class:`OptionMenu` widget, a :class:`Menubutton` that pops up a menu of - mutually exclusive choices. *variable* is the variable that tracks the - currently selected value, *default* is the value to set initially, and - *values* are the entries to 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. + mutually exclusive choices. + *variable* is the variable that tracks the currently selected value, + *default* is the value to set initially, and *values* are the entries to + 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. .. method:: set_menu(default=None, *values) - Replace the entries of the menu with *values*. If *default* is given, - also set it as the current value of the *variable*. + Replace the entries of the menu with *values*. + If *default* is given, also set it as the current value of the + *variable*. .. method:: destroy() @@ -1735,18 +1741,21 @@ inherits the common methods of :class:`Widget`. .. class:: Panedwindow(master=None, **kw) Ttk :class:`Panedwindow` widget, displays a number of subwindows stacked - either vertically or horizontally. The user may adjust the relative sizes of - the subwindows by dragging the sash between panes. It is the themed - counterpart of :class:`tkinter.PanedWindow` and inherits the common widget - methods from :class:`Widget`, as well as the :meth:`!add` and :meth:`!panes` - methods from :class:`tkinter.PanedWindow`. + either vertically or horizontally. + The user may adjust the relative sizes of the subwindows by dragging the + sash between panes. + It is the themed counterpart of :class:`tkinter.PanedWindow` and inherits + the common widget methods from :class:`Widget`, as well as the :meth:`!add` + and :meth:`!panes` methods from :class:`tkinter.PanedWindow`. .. method:: insert(pos, child, **kw) - Insert a pane containing *child* at the position *pos*. *pos* is either - the string ``'end'``, an integer index, or the name of a managed - subwindow. If *child* is already managed by the paned window, move it to - the specified position. Any keyword arguments set pane options. + Insert a pane containing *child* at the position *pos*. + *pos* is either the string ``'end'``, an integer index, or the name of a + managed subwindow. + If *child* is already managed by the paned window, move it to the + specified position. + Any keyword arguments set pane options. .. method:: forget(child) @@ -1756,26 +1765,28 @@ inherits the common methods of :class:`Widget`. .. method:: pane(pane, option=None, **kw) Query or modify the options of the specified *pane*, where *pane* is - either an integer index or the name of a managed subwindow. If no - arguments are given, return a dictionary of the pane option values. If - *option* is specified, return the value of that option. Otherwise, set - the options given as keyword arguments to their corresponding values. + either an integer index or the name of a managed subwindow. + If no arguments are given, return a dictionary of the pane option values. + If *option* is specified, return the value of that option. + Otherwise, set the options given as keyword arguments to their + corresponding values. .. method:: sashpos(index, newpos=None) If *newpos* is specified, set the position of sash number *index* and - return its new position. This may adjust the positions of adjacent sashes - to ensure that positions are monotonically increasing; positions are also - constrained to be between 0 and the total size of the widget. If *newpos* - is omitted, return the current position of the sash. + return its new position. + This may adjust the positions of adjacent sashes to ensure that positions + are monotonically increasing; positions are also constrained to be + between 0 and the total size of the widget. + If *newpos* is omitted, return the current position of the sash. .. class:: Radiobutton(master=None, **kw) Ttk :class:`Radiobutton` widget, used as part of a group to control a single - shared variable by selecting one of several mutually exclusive values. It is - the themed counterpart of :class:`tkinter.Radiobutton` and inherits the - common widget methods from :class:`Widget`. + shared variable by selecting one of several mutually exclusive values. + It is the themed counterpart of :class:`tkinter.Radiobutton` and inherits + the common widget methods from :class:`Widget`. .. method:: invoke() @@ -1786,14 +1797,14 @@ inherits the common methods of :class:`Widget`. .. class:: Scale(master=None, **kw) Ttk :class:`Scale` widget, displays a slider that lets the user select a - numeric value from a range by moving the slider along a trough. It is the - themed counterpart of :class:`tkinter.Scale` and inherits the common widget - methods from :class:`Widget`. + numeric value from a range by moving the slider along a trough. + It is the themed counterpart of :class:`tkinter.Scale` and inherits the + common widget methods from :class:`Widget`. .. method:: configure(cnf=None, **kw) - Modify or query the widget options, like :meth:`Widget.configure`. In - addition, this method clips the ``from`` and ``to`` values so that the + Modify or query the widget options, like :meth:`Widget.configure`. + In addition, this method clips the ``from`` and ``to`` values so that the current value stays within the range defined by them. .. versionchanged:: 3.9 @@ -1802,24 +1813,26 @@ inherits the common methods of :class:`Widget`. .. method:: get(x=None, y=None) - Return the current value of the scale. If *x* and *y* are given, return - the value corresponding to the pixel coordinate *x*, *y* instead. + Return the current value of the scale. + If *x* and *y* are given, return the value corresponding to the pixel + coordinate *x*, *y* instead. .. class:: Scrollbar(master=None, **kw) Ttk :class:`Scrollbar` widget, controls the viewport of an associated scrollable widget such as a :class:`Treeview`, :class:`Entry` or - :class:`tkinter.Text`. It is the themed counterpart of - :class:`tkinter.Scrollbar` and inherits the common widget methods from - :class:`Widget`, as well as the :meth:`!set` and :meth:`!get` methods from - :class:`tkinter.Scrollbar`. + :class:`tkinter.Text`. + It is the themed counterpart of :class:`tkinter.Scrollbar` and inherits the + common widget methods from :class:`Widget`, as well as the :meth:`!set` and + :meth:`!get` methods from :class:`tkinter.Scrollbar`. .. class:: Separator(master=None, **kw) Ttk :class:`Separator` widget, displays a horizontal or vertical separator - line. It has no direct counterpart in :mod:`tkinter` and inherits the common + line. + It has no direct counterpart in :mod:`tkinter` and inherits the common widget methods from :class:`Widget`. @@ -1827,16 +1840,17 @@ inherits the common methods of :class:`Widget`. Ttk :class:`Sizegrip` widget, displays a grip that allows the user to resize the containing toplevel window by pressing and dragging the grip, typically - placed in the bottom-right corner. It has no direct counterpart in - :mod:`tkinter` and inherits the common widget methods from :class:`Widget`. + placed in the bottom-right corner. + It has no direct counterpart in :mod:`tkinter` and inherits the common + widget methods from :class:`Widget`. .. class:: LabeledScale(master=None, variable=None, from_=0, to=10, **kw) A :class:`Frame` containing a :class:`Scale` and a :class:`Label` that shows - the scale's current value. *variable* is the :class:`IntVar` tracked by the - scale (one is created if it is not given), and *from_* and *to* define the - range of the scale. + the scale's current value. + *variable* is the :class:`IntVar` tracked by the scale (one is created if it + is not given), and *from_* and *to* define the range of the scale. .. method:: destroy() @@ -1862,11 +1876,13 @@ Utility functions .. function:: tclobjs_to_py(adict) Return a copy of the dictionary *adict* in which any Tcl object values have - been converted to their Python equivalents. This is a helper used - internally to post-process the option dictionaries returned by Tk. + been converted to their Python equivalents. + This is a helper used internally to post-process the option dictionaries + returned by Tk. .. function:: setup_master(master=None) - Return a master widget to use as the parent of a new widget. If *master* is - ``None``, the default root window is used, creating it if necessary. This is - a helper used internally when constructing widgets. + Return a master widget to use as the parent of a new widget. + If *master* is ``None``, the default root window is used, creating it if + necessary. + This is a helper used internally when constructing widgets. From 19f6605f69dbad248ca4d7694a65ccc8fdf146d1 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 11:50:20 +0300 Subject: [PATCH 06/18] gh-59551: Describe wm_ aliases like other tkinter aliases Use the standard "``wm_X`` is an alias of X" wording for the window-manager methods instead of the bespoke "the wm_-prefixed spelling is an equivalent alias" note. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.rst | 93 ++++++++++++++--------------------------- 1 file changed, 31 insertions(+), 62 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 988363e9ebd6e80..1041e2323295090 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -2324,8 +2324,7 @@ Base and mixin classes 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_aspect`) is an equivalent - alias. + :meth:`wm_aspect` is an alias of :meth:`!aspect`. .. method:: wm_attributes(*args, return_python_dict=False, **kwargs) :no-typesetting: @@ -2343,8 +2342,7 @@ Base and mixin classes ``-topmost``, while Windows, macOS and X11 each add further options. On X11 changes are applied asynchronously, so a queried value may not yet reflect the most recent request. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_attributes`) is an - equivalent alias. + :meth:`wm_attributes` is an alias of :meth:`!attributes`. .. versionchanged:: 3.13 A single attribute may now be queried by name without the leading @@ -2362,8 +2360,7 @@ Base and mixin classes for use by the window or session manager. An empty string deletes the property. With no argument, return the last name set, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_client`) is an equivalent - alias. + :meth:`wm_client` is an alias of :meth:`!client`. .. method:: wm_colormapwindows(*wlist) :no-typesetting: @@ -2376,8 +2373,7 @@ Base and mixin classes order is a priority order for installing colormaps). With no arguments, return the list of windows currently named in the property. - The ``wm_``-prefixed spelling (e.g. ``wm_colormapwindows``) is an - equivalent alias. + :meth:`wm_colormapwindows` is an alias of :meth:`!colormapwindows`. .. method:: wm_command(value=None) :no-typesetting: @@ -2389,8 +2385,7 @@ Base and mixin classes command used to invoke the application. An empty string deletes the property. With no argument, return the last value set, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_command`) is an equivalent - alias. + :meth:`wm_command` is an alias of :meth:`!command`. .. method:: wm_deiconify() :no-typesetting: @@ -2401,8 +2396,7 @@ Base and mixin classes If the window has never been mapped, this ensures it appears de-iconified when it is first mapped. On Windows the window is also raised and given the focus. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_deiconify`) is an - equivalent alias. + :meth:`wm_deiconify` is an alias of :meth:`!deiconify`. .. method:: wm_focusmodel(model=None) :no-typesetting: @@ -2417,8 +2411,7 @@ Base and mixin classes With no argument, return the current model. The default is ``'passive'``, which is what the :meth:`!focus` command assumes. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_focusmodel`) is an - equivalent alias. + :meth:`wm_focusmodel` is an alias of :meth:`!focusmodel`. .. method:: wm_forget(window) :no-typesetting: @@ -2430,8 +2423,7 @@ Base and mixin classes A :class:`Toplevel` is then treated like a :class:`Frame`, although its ``-menu`` configuration is remembered and the menu reappears if the widget is managed again. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_forget`) is an equivalent - alias. + :meth:`wm_forget` is an alias of :meth:`!forget`. .. versionadded:: 3.3 @@ -2444,8 +2436,7 @@ Base and mixin classes decorative frame containing the window, if the window manager has reparented it into such a frame; otherwise return the identifier of the window itself. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_frame`) is an equivalent - alias. + :meth:`wm_frame` is an alias of :meth:`!frame`. .. method:: wm_geometry(newGeometry=None) :no-typesetting: @@ -2462,8 +2453,7 @@ Base and mixin classes revert to its natural size. With no argument, return the current geometry as a string of the form ``'200x200+10+10'``. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_geometry`) is an equivalent - alias. + :meth:`wm_geometry` is an alias of :meth:`!geometry`. .. method:: wm_grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) :no-typesetting: @@ -2478,8 +2468,7 @@ Base and mixin classes 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_grid`) is an equivalent - alias. + :meth:`wm_grid` is an alias of :meth:`!grid`. .. method:: wm_group(pathName=None) :no-typesetting: @@ -2493,8 +2482,7 @@ Base and mixin classes An empty string removes the window from any group. With no argument, return the path name of the current group leader, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_group`) is an equivalent - alias. + :meth:`wm_group` is an alias of :meth:`!group`. .. method:: wm_iconbitmap(bitmap=None, default=None) :no-typesetting: @@ -2508,8 +2496,7 @@ Base and mixin classes string. On Windows the *default* argument names an icon (for example an ``.ico`` file) applied to all top-level windows that have no icon of their own. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconbitmap`) is an - equivalent alias. + :meth:`wm_iconbitmap` is an alias of :meth:`!iconbitmap`. .. method:: wm_iconify() :no-typesetting: @@ -2519,8 +2506,7 @@ Base and mixin classes Iconify the window. If the window has not yet been mapped for the first time, arrange for it to appear in the iconified state when it is eventually mapped. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconify`) is an equivalent - alias. + :meth:`wm_iconify` is an alias of :meth:`!iconify`. .. method:: wm_iconmask(bitmap=None) :no-typesetting: @@ -2534,8 +2520,7 @@ Base and mixin classes An empty string cancels the current mask. With no argument, return the name of the current icon mask, or an empty string. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconmask`) is an equivalent - alias. + :meth:`wm_iconmask` is an alias of :meth:`!iconmask`. .. method:: wm_iconname(newName=None) :no-typesetting: @@ -2547,8 +2532,7 @@ Base and mixin classes With no argument, return the current icon name, or an empty string if none has been set (in which case the window manager normally displays the window's title). - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconname`) is an equivalent - alias. + :meth:`wm_iconname` is an alias of :meth:`!iconname`. .. method:: wm_iconphoto(default=False, *images) :no-typesetting: @@ -2564,8 +2548,7 @@ Base and mixin classes If *default* is true, the icon is also applied to all top-level windows created in the future. On macOS only the first image is used. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconphoto`) is an - equivalent alias. + :meth:`wm_iconphoto` is an alias of :meth:`!iconphoto`. .. versionadded:: 3.3 @@ -2579,8 +2562,7 @@ Base and mixin classes 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. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconposition`) is an - equivalent alias. + :meth:`wm_iconposition` is an alias of :meth:`!iconposition`. .. method:: wm_iconwindow(pathName=None) :no-typesetting: @@ -2595,8 +2577,7 @@ Base and mixin classes empty string. Not all window managers support icon windows, and the concept is meaningless on non-X11 platforms. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_iconwindow`) is an - equivalent alias. + :meth:`wm_iconwindow` is an alias of :meth:`!iconwindow`. .. method:: wm_manage(widget) :no-typesetting: @@ -2607,8 +2588,7 @@ Base and mixin classes manager with a title bar and so on. Only :class:`Frame`, :class:`LabelFrame` and :class:`Toplevel` widgets may be used; passing any other widget type raises an error. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_manage`) is an equivalent - alias. + :meth:`wm_manage` is an alias of :meth:`!manage`. .. versionadded:: 3.3 @@ -2624,8 +2604,7 @@ Base and mixin classes With no arguments, return a tuple of the current maximum width and height. The maximum size defaults to the size of the screen. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_maxsize`) is an equivalent - alias. + :meth:`wm_maxsize` is an alias of :meth:`!maxsize`. .. method:: wm_minsize(width=None, height=None) :no-typesetting: @@ -2639,8 +2618,7 @@ Base and mixin classes With no arguments, return a tuple of the current minimum width and height. The minimum size defaults to one pixel in each dimension. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_minsize`) is an equivalent - alias. + :meth:`wm_minsize` is an alias of :meth:`!minsize`. .. method:: wm_overrideredirect(boolean=None) :no-typesetting: @@ -2654,8 +2632,7 @@ Base and mixin classes With no argument, return a boolean indicating whether the flag is set. The flag is reliably honored only when the window is first mapped or remapped from the withdrawn state. - The ``wm_``-prefixed spelling (e.g. ``wm_overrideredirect``) is an - equivalent alias. + :meth:`wm_overrideredirect` is an alias of :meth:`!overrideredirect`. .. method:: wm_positionfrom(who=None) :no-typesetting: @@ -2670,8 +2647,7 @@ Base and mixin classes has been set. Tk automatically sets the source to ``'user'`` when :meth:`geometry` is called, unless it has been set explicitly to ``'program'``. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_positionfrom`) is an - equivalent alias. + :meth:`wm_positionfrom` is an alias of :meth:`!positionfrom`. .. method:: wm_protocol(name=None, func=None) :no-typesetting: @@ -2689,8 +2665,7 @@ Base and mixin classes an empty string if none is set (the default ``WM_DELETE_WINDOW`` handler is not reported); with no arguments, return a tuple of the protocols that currently have handlers. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_protocol`) is an equivalent - alias. + :meth:`wm_protocol` is an alias of :meth:`!protocol`. .. method:: wm_resizable(width=None, height=None) :no-typesetting: @@ -2703,8 +2678,7 @@ Base and mixin classes With no arguments, return a tuple of two ``0``/``1`` values indicating whether each dimension is currently resizable. By default a window is resizable in both dimensions. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_resizable`) is an - equivalent alias. + :meth:`wm_resizable` is an alias of :meth:`!resizable`. .. method:: wm_sizefrom(who=None) :no-typesetting: @@ -2717,8 +2691,7 @@ Base and mixin classes the current source. With no argument, return the current source, or an empty string if none has been set. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_sizefrom`) is an equivalent - alias. + :meth:`wm_sizefrom` is an alias of :meth:`!sizefrom`. .. method:: wm_state(newstate=None) :no-typesetting: @@ -2732,8 +2705,7 @@ Base and mixin classes ``'iconic'`` refers to a window that has been iconified, while ``'icon'`` refers to a window serving as the icon for another window (see :meth:`iconwindow`); the ``'icon'`` state cannot be set. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_state`) is an equivalent - alias. + :meth:`wm_state` is an alias of :meth:`!state`. .. method:: wm_title(string=None) :no-typesetting: @@ -2744,8 +2716,7 @@ Base and mixin classes display in the window's title bar. With no argument, return the current title. The title defaults to the window's name. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_title`) is an equivalent - alias. + :meth:`wm_title` is an alias of :meth:`!title`. .. method:: wm_transient(master=None) :no-typesetting: @@ -2761,8 +2732,7 @@ Base and mixin classes A transient window mirrors state changes in its master and may be decorated differently by the window manager; it is an error to make a window a transient of itself. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_transient`) is an - equivalent alias. + :meth:`wm_transient` is an alias of :meth:`!transient`. .. method:: wm_withdraw() :no-typesetting: @@ -2776,8 +2746,7 @@ Base and mixin classes It is sometimes necessary to withdraw a window and then re-map it (for example with :meth:`deiconify`) to make some window managers notice changes to window attributes. - The ``wm_``-prefixed spelling (e.g. :meth:`wm_withdraw`) is an equivalent - alias. + :meth:`wm_withdraw` is an alias of :meth:`!withdraw`. .. class:: Pack() From 2935f8157b1033b4ba095568a2a3a57e288db729 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 11:55:07 +0300 Subject: [PATCH 07/18] gh-59551: Remove docs for internal ttk helpers Undocument the tclobjs_to_py() and setup_master() utility functions, which are internal helpers rather than public API. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.ttk.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index 00e372abbd98ab9..be6349126e7b14c 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -1868,21 +1868,3 @@ and inherits the common methods of :class:`Widget`. Alias of :class:`Panedwindow`, kept for naming compatibility with :class:`tkinter.PanedWindow`. - - -Utility functions ------------------ - -.. function:: tclobjs_to_py(adict) - - Return a copy of the dictionary *adict* in which any Tcl object values have - been converted to their Python equivalents. - This is a helper used internally to post-process the option dictionaries - returned by Tk. - -.. function:: setup_master(master=None) - - Return a master widget to use as the parent of a new widget. - If *master* is ``None``, the default root window is used, creating it if - necessary. - This is a helper used internally when constructing widgets. From d126ff1b6415bbbac84b404bdc2df56872b39874 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 12:32:45 +0300 Subject: [PATCH 08/18] gh-59551: Fix broken cross-references in tkinter docs Qualify references that did not resolve: the geometry/Frame classes in scrolledtext, Button.invoke in tkinter.rst, and Scrollbar.set, the Widget.configure methods (documented on Misc) and IntVar in ttk. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.rst | 2 +- Doc/library/tkinter.scrolledtext.rst | 7 ++++--- Doc/library/tkinter.ttk.rst | 30 +++++++++++++++++----------- 3 files changed, 23 insertions(+), 16 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 1041e2323295090..1720436d72d3e64 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -511,7 +511,7 @@ name of a method to call). In the official Tcl/Tk reference documentation, you'll find most operations that look like method calls on the man page for a specific widget (e.g., -you'll find the :meth:`invoke` method on the +you'll find the :meth:`~tkinter.ttk.Button.invoke` method on the `ttk::button `_ man page), while functions that take a widget as a parameter often have their own man page (e.g., diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst index 6870baf17ceb9fc..4ae86e21f026cdc 100644 --- a/Doc/library/tkinter.scrolledtext.rst +++ b/Doc/library/tkinter.scrolledtext.rst @@ -13,9 +13,10 @@ 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 text widget and scrollbar are packed together in a :class:`Frame`, and the -methods of the :class:`Pack`, :class:`Grid` and :class:`Place` geometry -managers are acquired from the :class:`Frame` object. +The text widget and scrollbar are packed together in a :class:`~tkinter.Frame`, +and the methods of the :class:`~tkinter.Pack`, :class:`~tkinter.Grid` and +:class:`~tkinter.Place` geometry managers are acquired from the +:class:`~tkinter.Frame` object. This allows the :class:`ScrolledText` widget to be used directly to achieve most normal geometry management behavior. diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index be6349126e7b14c..72b06f4e5305e6c 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -150,9 +150,9 @@ scrollbar. | | calls the *xscrollcommand* callback. | | | | | | Usually this option consists of the method | -| | :meth:`Scrollbar.set` of some scrollbar. This will cause| -| | the scrollbar to be updated whenever the view in the | -| | window changes. | +| | :meth:`Scrollbar.set ` of some | +| | scrollbar. This will cause the scrollbar to be updated | +| | whenever the view in the window changes. | +----------------+---------------------------------------------------------+ | yscrollcommand | Used to communicate with vertical scrollbars. | | | For some more information, see above. | @@ -261,7 +261,8 @@ ttk.Widget ^^^^^^^^^^ Besides the methods described below, the :class:`ttk.Widget` supports the -methods :meth:`tkinter.Widget.cget` and :meth:`tkinter.Widget.configure`. +methods :meth:`tkinter.Widget.cget` and +:meth:`tkinter.Widget.configure `. .. class:: Widget @@ -298,8 +299,9 @@ The :class:`ttk.Combobox` widget combines a text field with a pop-down list of values. This widget is a subclass of :class:`Entry`. Besides the methods inherited from :class:`Widget`: :meth:`Widget.cget`, -:meth:`Widget.configure`, :meth:`Widget.identify`, :meth:`Widget.instate` -and :meth:`Widget.state`, and the following inherited from :class:`Entry`: +:meth:`Widget.configure `, :meth:`Widget.identify`, +:meth:`Widget.instate` and :meth:`Widget.state`, and the following inherited +from :class:`Entry`: :meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`, :meth:`Entry.index`, :meth:`Entry.insert`, :meth:`Entry.selection`, :meth:`Entry.xview`, it has some other methods, described at @@ -391,8 +393,9 @@ and decrement arrows. It can be used for numbers or lists of string values. This widget is a subclass of :class:`Entry`. Besides the methods inherited from :class:`Widget`: :meth:`Widget.cget`, -:meth:`Widget.configure`, :meth:`Widget.identify`, :meth:`Widget.instate` -and :meth:`Widget.state`, and the following inherited from :class:`Entry`: +:meth:`Widget.configure `, :meth:`Widget.identify`, +:meth:`Widget.instate` and :meth:`Widget.state`, and the following inherited +from :class:`Entry`: :meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`, :meth:`Entry.index`, :meth:`Entry.insert`, :meth:`Entry.xview`, it has some other methods, described at :class:`ttk.Spinbox`. @@ -1803,12 +1806,14 @@ and inherits the common methods of :class:`Widget`. .. method:: configure(cnf=None, **kw) - Modify or query the widget options, like :meth:`Widget.configure`. + Modify or query the widget options, like + :meth:`Widget.configure `. In addition, this method clips the ``from`` and ``to`` values so that the current value stays within the range defined by them. .. versionchanged:: 3.9 - Now returns the configuration value, like :meth:`Widget.configure`. + Now returns the configuration value, like + :meth:`Widget.configure `. .. method:: get(x=None, y=None) @@ -1849,8 +1854,9 @@ and inherits the common methods of :class:`Widget`. A :class:`Frame` containing a :class:`Scale` and a :class:`Label` that shows the scale's current value. - *variable* is the :class:`IntVar` tracked by the scale (one is created if it - is not given), and *from_* and *to* define the range of the scale. + *variable* is the :class:`~tkinter.IntVar` tracked by the scale (one is + created if it is not given), and *from_* and *to* define the range of the + scale. .. method:: destroy() From c784350c63133b181c3b146e0bd5cabb98e3fad9 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 14:43:06 +0300 Subject: [PATCH 09/18] gh-59551: Fix cross-references in the tkinter documentation Restore the ``tkinter`` module context after the _tkinter entry in the "Additional modules" list (it was leaking until the Reference section), and qualify the bare method and attribute names used in the introductory prose so they resolve. Redirect the Widget.cget(), Widget.configure() and Widget.bind() references to the Misc methods where those are documented, add the missing Listbox.itemconfig alias anchor, document the TclError exception, and drop the markup from references that have no target (tkinter.constants and the X11 cursor name XC_hand2). Doc/library/tkinter.rst and Doc/library/tkinter.scrolledtext.rst are now free of nitpick warnings and are removed from Doc/tools/.nitignore. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.rst | 141 +++++++++++++++++++++++----------------- Doc/tools/.nitignore | 2 - 2 files changed, 81 insertions(+), 62 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 1720436d72d3e64..707e32d114c3874 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -158,7 +158,7 @@ the modern themed widget set and API:: instead of it being created as an independent toplevel window. *id* must be specified in the same way as the value for the -use option for toplevel widgets (that is, it has a form like that returned by - :meth:`winfo_id`). + :meth:`~Misc.winfo_id`). Note that on some platforms this will only work correctly if *id* refers to a Tk frame or toplevel that has its -container option enabled. @@ -179,13 +179,15 @@ the modern themed widget set and API:: .. attribute:: master - The widget object that contains this widget. For :class:`Tk`, the - :attr:`!master` is :const:`None` because it is the main window. The terms - *master* and *parent* are similar and sometimes used interchangeably - as argument names; however, calling :meth:`winfo_parent` returns a - string of the widget name whereas :attr:`!master` returns the object. - *parent*/*child* reflects the tree-like relationship while - *master* (or *container*)/*content* reflects the container structure. + The widget object that contains this widget. + For :class:`Tk`, the :attr:`!master` is :const:`None` because it is the + main window. + The terms *master* and *parent* are similar and sometimes used + interchangeably as argument names; however, calling + :meth:`~Misc.winfo_parent` returns a string of the widget name whereas + :attr:`!master` returns the object. + *parent*/*child* reflects the tree-like relationship while *master* (or + *container*)/*content* reflects the container structure. .. attribute:: children @@ -226,13 +228,15 @@ the modern themed widget set and API:: .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) - The :func:`Tcl` function is a factory function which creates an object much like - that created by the :class:`Tk` class, except that it does not initialize the Tk - subsystem. This is most often useful when driving the Tcl interpreter in an - environment where one doesn't want to create extraneous toplevel windows, or - where one cannot (such as Unix/Linux systems without an X server). An object - created by the :func:`Tcl` object can have a Toplevel window created (and the Tk - subsystem initialized) by calling its :meth:`loadtk` method. + The :func:`Tcl` function is a factory function which creates an object much + like that created by the :class:`Tk` class, except that it does not + initialize the Tk subsystem. + This is most often useful when driving the Tcl interpreter in an environment + where one doesn't want to create extraneous toplevel windows, or where one + cannot (such as Unix/Linux systems without an X server). + An object created by the :func:`Tcl` object can have a Toplevel window + created (and the Tk subsystem initialized) by calling its :meth:`~Tk.loadtk` + method. The modules that provide Tk support include: @@ -281,7 +285,7 @@ Additional modules: Python's Integrated Development and Learning Environment (IDLE). Based on :mod:`!tkinter`. -:mod:`tkinter.constants` +:mod:`!tkinter.constants` Symbolic constants that can be used in place of strings when passing various parameters to Tkinter calls. Automatically imported by the main :mod:`!tkinter` module. @@ -293,6 +297,8 @@ Additional modules: :mod:`turtle` Turtle graphics in a Tk window. +.. currentmodule:: tkinter + Tkinter Life Preserver ---------------------- @@ -337,12 +343,13 @@ The following line creates a frame widget, which in this case will contain a label and a button we'll create next. The frame is fit inside the root window. -The next line creates a label widget holding a static text string. The -:meth:`grid` method is used to specify the relative layout (position) of the -label within its containing frame widget, similar to how tables in HTML work. +The next line creates a label widget holding a static text string. +The :meth:`~Grid.grid` method is used to specify the relative layout (position) +of the label within its containing frame widget, similar to how tables in HTML +work. -A button widget is then created, and placed to the right of the label. When -pressed, it will call the :meth:`destroy` method of the root window. +A button widget is then created, and placed to the right of the label. +When pressed, it will call the :meth:`~Misc.destroy` method of the root window. Finally, the :meth:`mainloop` method puts everything on the display, and responds to user input until the program terminates. @@ -449,9 +456,9 @@ interactive Python shell or with :func:`print`, can help you identify what you need. To find out what configuration options are available on any widget, call its -:meth:`configure` method, which returns a dictionary containing a variety of -information about each object, including its default and current values. Use -:meth:`keys` to get just the names of each option. +:meth:`~Misc.configure` method, which returns a dictionary containing a variety +of information about each object, including its default and current values. +Use :meth:`~Misc.keys` to get just the names of each option. :: @@ -523,7 +530,8 @@ You'll find many common options and methods in the pages, while others are found in the man page for a specific widget class. You'll also find that many Tkinter methods have compound names, e.g., -:func:`winfo_x`, :func:`winfo_height`, :func:`winfo_viewable`. +:meth:`~Misc.winfo_x`, :meth:`~Misc.winfo_height`, +:meth:`~Misc.winfo_viewable`. You'd find documentation for all of these in the `winfo `_ man page. @@ -554,14 +562,16 @@ from a thread other than the one that created the :class:`Tk` object, an event is posted to the interpreter's event queue, and when executed, the result is returned to the calling Python thread. -Tcl/Tk applications are normally event-driven, meaning that after initialization, -the interpreter runs an event loop (i.e. :func:`Tk.mainloop`) and responds to events. -Because it is single-threaded, event handlers must respond quickly, otherwise they -will block other events from being processed. To avoid this, any long-running -computations should not run in an event handler, but are either broken into smaller -pieces using timers, or run in another thread. This is different from many GUI -toolkits where the GUI runs in a completely separate thread from all application -code including event handlers. +Tcl/Tk applications are normally event-driven, meaning that after +initialization, the interpreter runs an event loop (i.e. +:meth:`Tk.mainloop `) and responds to events. +Because it is single-threaded, event handlers must respond quickly, otherwise +they will block other events from being processed. +To avoid this, any long-running computations should not run in an event +handler, but are either broken into smaller pieces using timers, or run in +another thread. +This is different from many GUI toolkits where the GUI runs in a completely +separate thread from all application code including event handlers. If the Tcl interpreter is not running the event loop and processing events, any :mod:`!tkinter` calls made from threads other than the one running the Tcl @@ -633,11 +643,11 @@ document. Some options don't apply to some kinds of widgets. Whether a given widget responds to a particular option depends on the class of the widget; buttons have a ``command`` option, labels do not. -The options supported by a given widget are listed in that widget's man page, or -can be queried at runtime by calling the :meth:`config` method without -arguments, or by calling the :meth:`keys` method on that widget. The return -value of these calls is a dictionary whose key is the name of the option as a -string (for example, ``'relief'``) and whose values are 5-tuples. +The options supported by a given widget are listed in that widget's man page, +or can be queried at runtime by calling the :meth:`~Misc.config` method without +arguments, or by calling the :meth:`~Misc.keys` method on that widget. +The return value of these calls is a dictionary whose key is the name of the +option as a string (for example, ``'relief'``) and whose values are 5-tuples. Some options, like ``bg`` are synonyms for common options with long names (``bg`` is shorthand for "background"). Passing the ``config()`` method the name @@ -691,10 +701,11 @@ Additionally, the arrangement is dynamically adjusted to accommodate incremental changes to the configuration, once it is packed. Note that widgets do not appear until they have had their geometry specified -with a geometry manager. It's a common early mistake to leave out the geometry -specification, and then be surprised when the widget is created but nothing -appears. A widget will appear only after it has had, for example, the packer's -:meth:`pack` method applied to it. +with a geometry manager. +It's a common early mistake to leave out the geometry specification, and then +be surprised when the widget is created but nothing appears. +A widget will appear only after it has had, for example, the packer's +:meth:`~Pack.pack` method applied to it. The pack() method can be called with keyword-option/value pairs that control where the widget is to appear within its container, and how it is to behave when @@ -749,10 +760,11 @@ defined in :mod:`!tkinter`. There are many useful subclasses of Variable already defined: :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and -:class:`BooleanVar`. To read the current value of such a variable, call the -:meth:`get` method on it, and to change its value you call the :meth:`!set` -method. If you follow this protocol, the widget will always track the value of -the variable, with no further intervention on your part. +:class:`BooleanVar`. +To read the current value of such a variable, call the :meth:`~Variable.get` +method on it, and to change its value you call the :meth:`!set` method. +If you follow this protocol, the widget will always track the value of the +variable, with no further intervention on your part. For example:: @@ -799,12 +811,12 @@ subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods directly. To get at the toplevel window that contains a given widget, you can often just -refer to the widget's :attr:`master`. +refer to the widget's :attr:`~Tk.master`. Of course if the widget has been packed inside of a frame, the :attr:`!master` won't represent a toplevel window. To get at the toplevel window that contains an arbitrary widget, you can call -the :meth:`winfo_toplevel` method. -There is also a :meth:`_root` method; it begins with an underscore to denote +the :meth:`~Misc.winfo_toplevel` method. +There is also a :meth:`!_root` method; it begins with an underscore to denote the fact that this function is part of the implementation, and not an interface to Tk functionality. It returns the application's root window rather than the nearest enclosing @@ -866,7 +878,7 @@ color cursor The standard X cursor names from :file:`cursorfont.h` can be used, without the - ``XC_`` prefix. For example to get a hand cursor (:const:`XC_hand2`), use the + ``XC_`` prefix. For example to get a hand cursor (``XC_hand2``), use the string ``"hand2"``. You can also specify a bitmap and mask file of your own. See page 179 of Ousterhout's book. @@ -1117,6 +1129,11 @@ This section documents the classes, methods, functions and constants of the Most of them wrap Tcl/Tk commands; consult the official Tcl/Tk manual pages for the full list of widget options and further details. +.. exception:: TclError + + The exception raised when a call into the Tcl interpreter fails, for example + when a widget is given an unknown option or an invalid value. + Base and mixin classes ^^^^^^^^^^^^^^^^^^^^^^ @@ -3272,7 +3289,7 @@ Widget classes Return the current value of the configuration option *option* for the item given by *tagOrId* (the lowest matching item if it matches several). - This is like :meth:`~Widget.cget` but applies to an individual item. + This is like :meth:`~Misc.cget` but applies to an individual item. .. method:: itemconfig(tagOrId, cnf=None, **kw) :no-typesetting: @@ -3281,7 +3298,7 @@ Widget classes Query or modify the configuration options of the items given by *tagOrId*. - This mirrors :meth:`~Widget.configure`, except that it applies to + This mirrors :meth:`~Misc.configure`, except that it applies to individual items rather than to the canvas as a whole. With no options, it returns a dictionary describing the current options of the first matching item; otherwise it sets the given options on every @@ -3431,8 +3448,9 @@ Widget classes Bind the callback *func* to the event *sequence* for all items given by *tagOrId*, so that *func* is invoked whenever that event occurs for one of the items. - This is like :meth:`Widget.bind` but operates on canvas items rather than - on whole widgets; only mouse, keyboard and virtual events may be bound. + This is like :meth:`Widget.bind ` but operates on canvas items + rather than on whole widgets; only mouse, keyboard and virtual events may + be bound. Mouse events are directed to the current item and keyboard events to the focus item (see :meth:`focus`). If *add* is true the new binding is added to any existing bindings for @@ -3909,10 +3927,13 @@ Widget classes Return the current value of the configuration option *option* for the item given by *index*. + .. method:: itemconfig(index, cnf=None, **kw) + :no-typesetting: + .. method:: itemconfigure(index, cnf=None, **kw) Query or modify the configuration options of the item given by *index*. - This mirrors :meth:`~Widget.configure`, except that it applies to an + This mirrors :meth:`~Misc.configure`, except that it applies to an individual item rather than to the listbox as a whole. With no options, it returns a dictionary describing the current options of the item; otherwise it sets the given options. @@ -4051,7 +4072,7 @@ Widget classes .. method:: entryconfigure(index, cnf=None, **kw) Query or modify the configuration options of the entry given by *index*. - This mirrors :meth:`~Widget.configure`, except that it applies to an + This mirrors :meth:`~Misc.configure`, except that it applies to an individual entry rather than to the menu as a whole. With no options, it returns a dictionary describing the current options of the entry; otherwise it sets the given options. @@ -4768,7 +4789,7 @@ Widget classes .. method:: tag_configure(tagName, cnf=None, **kw) Query or modify the configuration options of the tag *tagName*. - This mirrors :meth:`~Widget.configure`, except that it applies to a tag + This mirrors :meth:`~Misc.configure`, except that it applies to a tag rather than to the widget as a whole: with no options it returns a dictionary describing the current options, otherwise it sets the given options. @@ -4866,7 +4887,7 @@ Widget classes .. method:: image_configure(index, cnf=None, **kw) Query or modify the configuration options of the embedded image at - *index*, like :meth:`~Widget.configure` but applied to that image. + *index*, like :meth:`~Misc.configure` but applied to that image. .. method:: image_names() @@ -4891,7 +4912,7 @@ Widget classes .. method:: window_configure(index, cnf=None, **kw) Query or modify the configuration options of the embedded window at - *index*, like :meth:`~Widget.configure` but applied to that window. + *index*, like :meth:`~Misc.configure` but applied to that window. :meth:`window_config` is an alias of :meth:`!window_configure`. @@ -5666,7 +5687,7 @@ Constants ^^^^^^^^^ The following symbolic constants are available in both the :mod:`!tkinter` -and :mod:`tkinter.constants` namespaces. +and :mod:`!tkinter.constants` namespaces. .. data:: TRUE YES diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index aa08f7acb99197a..83aedb2874f1204 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -26,8 +26,6 @@ Doc/library/socket.rst Doc/library/ssl.rst Doc/library/termios.rst Doc/library/test.rst -Doc/library/tkinter.rst -Doc/library/tkinter.scrolledtext.rst Doc/library/tkinter.ttk.rst Doc/library/urllib.parse.rst Doc/library/urllib.request.rst From f3d9376018a52dcd00ef7de7355f10aa3ea71c70 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 17 Jun 2026 15:28:16 +0300 Subject: [PATCH 10/18] gh-59551: Fix the remaining cross-references in the ttk documentation Resolve every nitpick reference warning in tkinter.ttk.rst: * give the ``ttk``-prefixed class references an explicit target while keeping their displayed names, and de-link the bare ``ttk`` module references; * qualify the methods inherited by the themed widgets -- the Widget methods and winfo_class() to Misc, the Entry methods to the base Entry, and grid() to the geometry-manager mix-in -- shown by their bare names in the inherited-method lists; * point the selection and xview method families at Entry.selection_adjust and XView.xview. Reflow the touched paragraphs using semantic line breaks, and drop tkinter.ttk.rst from Doc/tools/.nitignore now that it is warning-free. Co-Authored-By: Claude Opus 4.8 (1M context) --- Doc/library/tkinter.ttk.rst | 113 +++++++++++++++++++----------------- Doc/tools/.nitignore | 1 - 2 files changed, 61 insertions(+), 53 deletions(-) diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index 72b06f4e5305e6c..8b4c968f2de7193 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -46,12 +46,12 @@ That code causes several :mod:`!tkinter.ttk` widgets (:class:`Button`, :class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`) to automatically replace the Tk widgets. -This has the direct benefit of using the new widgets which gives a better -look and feel across platforms; however, the replacement widgets are not -completely compatible. The main difference is that widget options such as -"fg", "bg" and others related to widget styling are no -longer present in Ttk widgets. Instead, use the :class:`ttk.Style` class -for improved styling effects. +This has the direct benefit of using the new widgets which gives a better look +and feel across platforms; however, the replacement widgets are not completely +compatible. +The main difference is that widget options such as "fg", "bg" and others +related to widget styling are no longer present in Ttk widgets. +Instead, use the :class:`ttk.Style