From 7b01ee18880ea04a000081406cb50b9291c939f3 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 13 Oct 2026 13:05:53 +0300 Subject: [PATCH 1/2] gh-159308: Improve the documentation of the Tk option data types in Tkinter Fix inaccurate descriptions of the color, wrap, boolean, bitmap, callback, font, region and anchor types, and remove the obsolete "geometry" type: there is no such widget option. Add the compound, orient, padding and state types. Fix also several minor errors in the reference. --- Doc/library/tkinter.rst | 131 +++++++++++++++++++++++++++++++--------- 1 file changed, 102 insertions(+), 29 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index a6a30928ce83d2..7f491f1ecb58eb 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -773,34 +773,76 @@ Tk option data types Many widget options documented in the reference accept values of a small number of common types, described here. +The standard options and their types are described in the +:manpage:`options(3tk)` manual page. anchor Legal values are points of the compass: ``"n"``, ``"ne"``, ``"e"``, ``"se"``, ``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``. + The *labelanchor* option of :class:`LabelFrame` and + :class:`ttk.LabelFrame ` + accepts also ``"en"``, ``"es"``, ``"wn"`` and ``"ws"``. + The *sticky* option of the grid geometry manager accepts a combination + of the compass directions, such as ``"nsew"``, or an empty string. bitmap 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"``. + ``'questhead'``, ``'question'``, ``'warning'``. + On macOS the following bitmaps are available as well: + ``'application'``, ``'accessory'``, ``'folder'``, ``'pfolder'``, + ``'trash'``, ``'floppy'``, ``'ramdisk'``, ``'cdrom'``, ``'preferences'``, + ``'querydoc'``, ``'stop'``, ``'note'`` and ``'caution'``. + To specify an X bitmap file, 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"``. + You can pass the integers 0 or 1, ``True`` or ``False``, or the strings + ``"0"``, ``"1"``, ``"yes"``, ``"no"``, ``"true"``, ``"false"``, ``"on"`` + or ``"off"``. + The strings are matched ignoring case, + and an unambiguous prefix, such as ``"t"``, is enough. + Any non-zero integer means true. callback - This is any Python function that takes no arguments. For example:: + This is any callable object. + Most callbacks take no arguments. For example:: def print_it(): print("hi there") fred["command"] = print_it + Some options call it with arguments, + such as the *command* option of :class:`Scale`, + which is called with the new value. + color - Colors can be given as the names of X colors in the rgb.txt file, or as strings - representing RGB values in 4 bit: ``"#RGB"``, 8 bit: ``"#RRGGBB"``, 12 bit: - ``"#RRRGGGBBB"``, or 16 bit: ``"#RRRRGGGGBBBB"`` ranges, where R,G,B here - represent any legal hex digit. See the :manpage:`colors(3tk)` man page for - the list of named colors. + Colors can be given as symbolic names, such as ``"red"`` or ``"light blue"``, + or as strings representing RGB values in 4 bit: ``"#RGB"``, 8 bit: + ``"#RRGGBB"``, 12 bit: ``"#RRRGGGBBB"``, or 16 bit: ``"#RRRRGGGGBBBB"`` + ranges, where R,G,B here represent any legal hex digit. + Tk provides a portable set of symbolic names available on all platforms; + they are matched ignoring case and spaces, + so ``"light blue"``, ``"Light Blue"`` and ``"lightblue"`` + are the same color. + The full list of names, including the platform-specific names + of the current system colors + (for example ``"systemButtonFace"`` on Windows + or ``"systemWindowBody"`` on macOS), + is given in the :manpage:`colors(3tk)` manual page. + :meth:`~tkinter.Misc.winfo_rgb` returns + the red, green and blue components of a color. + +compound + Determines how to combine an image and a text displayed in a widget. + Legal values are ``"none"`` (display the image if there is one, + otherwise the text), ``"text"``, ``"image"``, + ``"center"`` (display the text in the center of the image) and + ``"top"``, ``"bottom"``, ``"left"``, ``"right"`` + (display the image above, below, to the left of or to the right + of the text). + The themed widgets accept all these values, + the classic widgets all except ``"text"`` and ``"image"``. cursor The name of the mouse cursor to display while the pointer is over the widget. @@ -836,19 +878,32 @@ font ``(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 - measured in pixels for most widgets (in characters for widgets displaying text). - For example: ``fred["geometry"] = "200x100"``. + The name of a named font, such as ``"TkDefaultFont"``, + a :class:`tkinter.font.Font` instance, + or, on X11, an XLFD font name can be used as well. justify Legal values are the strings: ``"left"``, ``"center"``, and ``"right"``. +orient + Legal values are ``"horizontal"`` and ``"vertical"``. + +padding + This is a legal distance (see above), applied on all sides, + or a sequence of up to four distances + specifying the left, top, right and bottom padding. + If fewer than four are specified, + the bottom padding defaults to the top one, + the right one to the left one, and the top one to the left one. + It is only supported by the themed widgets. + region - This is a string with four space-delimited elements, each of which is a legal - distance (see above). For example: ``"2 3 4 5"`` and ``"3i 2i 4.5i 2i"`` and - ``"3c 2c 4c 10.43c"`` are all legal regions. + Used for the *scrollregion* option of :class:`Canvas`. + This is a string with four space-delimited elements, + each of which is a legal distance (see above), + or a sequence of four such elements. + For example: ``"2 3 4 5"``, ``(2, 3, 4, 5)``, ``"3i 2i 4.5i 2i"`` and + ``"3c 2c 4c 10.43c"`` are all legal regions. relief Determines what the border style of a widget will be. Legal values are: @@ -859,8 +914,19 @@ scrollcommand This is almost always the :meth:`!set` method of some scrollbar widget, but can be any widget method that takes a single argument. +state + Legal values are ``"normal"``, ``"disabled"`` and, depending on the widget, + also ``"active"``, ``"hidden"`` (for :class:`Canvas` items) + or ``"readonly"`` (for :class:`Entry`, :class:`Spinbox` + and the themed widgets). + The themed widgets have in addition a more general set of states, + which is manipulated with + :meth:`ttk.Widget.state `. + wrap - Must be one of: ``"none"``, ``"char"``, or ``"word"``. + Must be one of ``"none"``, ``"char"`` or ``"word"`` + for the :class:`Text` widget and its tags; + for a tag an empty string means to use the widget's value. .. _Bindings-and-Events: @@ -1110,7 +1176,7 @@ Base and mixin classes 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'``. + ``'true'``, ``'false'``, ``'on'`` and ``'off'``. Raise :exc:`ValueError` if *s* is not a valid boolean. .. method:: getdouble(s) @@ -2143,6 +2209,9 @@ Base and mixin classes Return the geometry of the widget, in the form ``widthxheight+x+y``. All dimensions are in pixels. + The position is relative to the parent widget; + use :meth:`winfo_rootx` and :meth:`winfo_rooty` + for the position on the screen. An offset can be negative; see :meth:`~Wm.geometry`. .. method:: winfo_height() @@ -3369,6 +3438,8 @@ Base and mixin classes 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. + The :class:`Text` widget accepts also ``'pixels'``, + and then *number* can be a screen distance, such as ``'1i'``. .. class:: YView() @@ -3399,6 +3470,8 @@ Base and mixin classes 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. + The :class:`Text` widget accepts also ``'pixels'``, + and then *number* can be a screen distance, such as ``'1i'``. .. class:: BaseWidget(master, widgetName, cnf={}, kw={}, extra=()) @@ -3828,8 +3901,7 @@ Widget classes .. note:: - Tk 8.6 added the *angle* option and Tk 9.0 added the *underline* - option for ``text`` items. + Tk 8.6 added the *angle* option for ``text`` items. .. method:: coords(tagOrId) coords(tagOrId, coordList, /) @@ -5226,10 +5298,10 @@ Widget classes *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. + boolean *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`. With a non-integer *increment*, see :ref:`numeric values and the locale @@ -5631,7 +5703,7 @@ Widget classes baseline, for superscripts and subscripts. *underline* - Whether to underline the text. + Whether to underline the text (a boolean). *underlinefg* The color of the underline; it defaults to the text color. @@ -5789,7 +5861,8 @@ Widget classes 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 boolean *stretch* (whether the widget is stretched vertically to the + height of the line), *padx* and *pady*. The embedded widget must be a descendant of the text widget's parent. .. method:: window_cget(index, option) @@ -6665,7 +6738,7 @@ Module-level functions 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. + Raise :exc:`ValueError` for an invalid value. .. function:: getdouble(s) From baeed7b422225c92e7066035d06e00751d036a05 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 13 Oct 2026 21:26:31 +0300 Subject: [PATCH 2/2] Update Doc/library/tkinter.rst Co-authored-by: Terry Jan Reedy --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 7f491f1ecb58eb..abad59b0ad86cf 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -842,7 +842,7 @@ compound (display the image above, below, to the left of or to the right of the text). The themed widgets accept all these values, - the classic widgets all except ``"text"`` and ``"image"``. + the classic widgets accept all except ``"text"`` and ``"image"``. cursor The name of the mouse cursor to display while the pointer is over the widget.