Skip to content

gh-143754: Modernize Tkinter docs #143841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
serhiy-storchaka wants to merge 1 commit into
base: main
Choose a base branch
from
+58 −47
Open

gh-143754: Modernize Tkinter docs #143841

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions Doc/library/tkinter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,13 +176,13 @@

.. attribute:: master

The widget object that contains this widget. For :class:`Tk`, the

Check warning on line 179 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: winfo_parent [ref.meth]
*master* is :const:`None` because it is the main window. The terms
: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.
string of the widget name whereas :attr:`!master` returns the object.
*parent*/*child* reflects the tree-like relationship while
*master*/*slave* reflects the container structure.
*master* (or *container*)/*content* reflects the container structure.

.. attribute:: children

Expand Down Expand Up @@ -638,15 +638,15 @@
.. index:: single: packing (widgets)

The packer is one of Tk's geometry-management mechanisms. Geometry managers
are used to specify the relative positioning of widgets within their container -
their mutual *master*. In contrast to the more cumbersome *placer* (which is
are used to specify the relative positioning of widgets within their container.
In contrast to the more cumbersome *placer* (which is
used less commonly, and we do not cover here), the packer takes qualitative
relationship specification - *above*, *to the left of*, *filling*, etc - and
works everything out to determine the exact placement coordinates for you.

The size of any *master* widget is determined by the size of the "slave widgets"
inside. The packer is used to control where slave widgets appear inside the
master into which they are packed. You can pack widgets into frames, and frames
The size of any container widget is determined by the size of the "content widgets"
inside. The packer is used to control where content widgets appear inside the
container into which they are packed. You can pack widgets into frames, and frames
into other frames, in order to achieve the kind of layout you desire.
Additionally, the arrangement is dynamically adjusted to accommodate incremental
changes to the configuration, once it is packed.
Expand All @@ -673,7 +673,7 @@
see the man pages and page 183 of John Ousterhout's book.

anchor
Anchor type. Denotes where the packer is to place each slave in its parcel.
Anchor type. Denotes where the packer is to place each content in its parcel.

expand
Boolean, ``0`` or ``1``.
Expand All @@ -682,10 +682,10 @@
Legal values: ``'x'``, ``'y'``, ``'both'``, ``'none'``.

ipadx and ipady
A distance - designating internal padding on each side of the slave widget.
A distance - designating internal padding on each side of the content.

padx and pady
A distance - designating external padding on each side of the slave widget.
A distance - designating external padding on each side of the content.

side
Legal values are: ``'left'``, ``'right'``, ``'top'``, ``'bottom'``.
Expand Down Expand Up @@ -757,9 +757,9 @@
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

Check warning on line 760 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: _root [ref.meth]

Check warning on line 760 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:attr reference target not found: master [ref.attr]
refer to the widget's master. Of course if the widget has been packed inside of
a frame, the master won't represent a toplevel window. To get at the 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:`_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.
Expand Down
79 changes: 45 additions & 34 deletions Lib/tkinter/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1867,15 +1867,15 @@ def __repr__(self):
return '<%s.%s object %s>' % (
self.__class__.__module__, self.__class__.__qualname__, self._w)

# Pack methods that apply to the master
# Pack methods that apply to the container widget
_noarg_ = ['_noarg_']

def pack_propagate(self, flag=_noarg_):
"""Set or get the status for propagation of geometry information.

A boolean argument specifies whether the geometry information
of the slaves will determine the size of this widget. If no argument
is given the current setting will be returned.
A boolean argument specifies whether the size of this container will
be determined by the geometry information of its content.
If no argument is given the current setting will be returned.
"""
if flag is Misc._noarg_:
return self._getboolean(self.tk.call(
Expand All @@ -1886,28 +1886,28 @@ def pack_propagate(self, flag=_noarg_):
propagate = pack_propagate

def pack_slaves(self):
"""Return a list of all slaves of this widget
in its packing order."""
"""Returns a list of all of the content widgets in the packing order
for this container."""
return [self._nametowidget(x) for x in
self.tk.splitlist(
self.tk.call('pack', 'slaves', self._w))]

slaves = pack_slaves

# Place method that applies to the master
# Place method that applies to the container widget
def place_slaves(self):
"""Return a list of all slaves of this widget
in its packing order."""
"""Returns a list of all the content widgets for which this widget is
the container."""
return [self._nametowidget(x) for x in
self.tk.splitlist(
self.tk.call(
'place', 'slaves', self._w))]

# Grid methods that apply to the master
# Grid methods that apply to the container widget

def grid_anchor(self, anchor=None): # new in Tk 8.5
"""The anchor value controls how to place the grid within the
master when no row/column has any weight.
container widget when no row/column has any weight.

The default anchor is nw."""
self.tk.call('grid', 'anchor', self._w, anchor)
Expand All @@ -1924,7 +1924,7 @@ def grid_bbox(self, column=None, row=None, col2=None, row2=None):
starts at that cell.

The returned integers specify the offset of the upper left
corner in the master widget and the width and height.
corner in the container widget and the width and height.
"""
args = ('grid', 'bbox', self._w)
if column is not None and row is not None:
Expand Down Expand Up @@ -1982,7 +1982,7 @@ def grid_columnconfigure(self, index, cnf={}, **kw):

def grid_location(self, x, y):
"""Return a tuple of column and row which identify the cell
at which the pixel at position X and Y inside the master
at which the pixel at position X and Y inside the container
widget is located."""
return self._getints(
self.tk.call(
Expand All @@ -1991,9 +1991,9 @@ def grid_location(self, x, y):
def grid_propagate(self, flag=_noarg_):
"""Set or get the status for propagation of geometry information.

A boolean argument specifies whether the geometry information
of the slaves will determine the size of this widget. If no argument
is given, the current setting will be returned.
A boolean argument specifies whether the size of this container will
be determined by the geometry information of its content.
If no argument is given the current setting will be returned.
"""
if flag is Misc._noarg_:
return self._getboolean(self.tk.call(
Expand All @@ -2019,8 +2019,13 @@ def grid_size(self):
size = grid_size

def grid_slaves(self, row=None, column=None):
"""Return a list of all slaves of this widget
in its packing order."""
"""Returns a list of the content widgets.

If no arguments are supplied, a list of all of the content in this
container widget is returned, most recently managed first.
If ROW or COLUMN is specified, only the content in the row or
column is returned.
"""
args = ()
if row is not None:
args = args + ('-row', row)
Expand Down Expand Up @@ -2606,8 +2611,8 @@ def pack_configure(self, cnf={}, **kw):
before=widget - pack it before you will pack widget
expand=bool - expand widget if parent size grows
fill=NONE or X or Y or BOTH - fill widget if widget grows
in=master - use master to contain this widget
in_=master - see 'in' option description
in=container - use the container widget to contain this widget
in_=container - see 'in' option description
ipadx=amount - add internal padding in x direction
ipady=amount - add internal padding in y direction
padx=amount - add padding in x direction
Expand Down Expand Up @@ -2646,25 +2651,31 @@ class Place:

def place_configure(self, cnf={}, **kw):
"""Place a widget in the parent widget. Use as options:
in=master - master relative to which the widget is placed
in_=master - see 'in' option description
x=amount - locate anchor of this widget at position x of master
y=amount - locate anchor of this widget at position y of master
in=container - the container widget relative to which this widget is
placed
in_=container - see 'in' option description
x=amount - locate anchor of this widget at position x of the
container widget
y=amount - locate anchor of this widget at position y of the
container widget
relx=amount - locate anchor of this widget between 0.0 and 1.0
relative to width of master (1.0 is right edge)
relative to width of the container widget (1.0 is
right edge)
rely=amount - locate anchor of this widget between 0.0 and 1.0
relative to height of master (1.0 is bottom edge)
anchor=NSEW (or subset) - position anchor according to given direction
relative to height of the container widget (1.0 is
bottom edge)
anchor=NSEW (or subset) - position anchor according to given
direction
width=amount - width of this widget in pixel
height=amount - height of this widget in pixel
relwidth=amount - width of this widget between 0.0 and 1.0
relative to width of master (1.0 is the same width
as the master)
relative to width of the container widget (1.0 is
the same width as the container widget)
relheight=amount - height of this widget between 0.0 and 1.0
relative to height of master (1.0 is the same
height as the master)
relative to height of the container widget (1.0
is the same height as the container widget)
bordermode="inside" or "outside" - whether to take border width of
master widget into account
the container widget into account
"""
self.tk.call(
('place', 'configure', self._w)
Expand Down Expand Up @@ -2700,8 +2711,8 @@ def grid_configure(self, cnf={}, **kw):
"""Position a widget in the parent widget in a grid. Use as options:
column=number - use cell identified with given column (starting with 0)
columnspan=number - this widget will span several columns
in=master - use master to contain this widget
in_=master - see 'in' option description
in=container - use the container widget to contain this widget
in_=container - see 'in' option description
ipadx=amount - add internal padding in x direction
ipady=amount - add internal padding in y direction
padx=amount - add padding in x direction
Expand Down
Loading