gh-86726: Document more tkinter.Tk methods by Hpmason · Pull Request #23689 · python/cpython · GitHub

Added most (not all) of the methods for the Tk class.
This also includes parent class methods from the WM and Misc classes in the same module.

Descriptions taken from source code docstrings.

Issue: Improve Tkinter Documentation #86726

This PR is stale because it has been open for 30 days with no activity.

Spelling: inherited; omitted

Suggested change

      
               Methods inheritted from :class:`Misc` parent class (some methods ommited):
          
               Methods inherited from :class:`!Misc` parent class (some methods omited):

Made spelling fixes; Added ! to Misc since there is not such doc section.

all descendant widgets [without the trailing s]

Suggested change

      
                  Destroy this and all descendants widgets. This will
          
                  Destroy this and all descendant widgets. This will

Lowercase t for tkinter?

3.x module name is tkinter (was Tkinter before)

Suggested change

      
            Added most (not all) of the methods for the `Tkinter.Tk` class.
          
            Added most (not all) of the methods for the `tkinter.Tk` class.

Parameter names are normally marked up in italics rather than all caps, i.e. *Ms* and *Func* in this case. See my createfilehandler entry at the bottom, or the other Python RST documentation files for examples.

Suggested change

      
                  MS specifies the time in milliseconds. FUNC gives the
          
                  *Ms* specifies the time in milliseconds. *Func* is the function

This is more of a complaint about the original docstring, but the if suggests the function may not be called. I would drop it and write "Call func once the main loop has no event . . ."

The suggestion should have been attached to the previous line. To implement the suggestion, I have to attach it there.

I guess this line could be removed

No. There are attributes common to all systems, 1 common to Windows and Mac, and specific ones for each system. Revision needed. https://www.tcl.tk/man/tcl8.6/TkCmd/wm.html

Copy and paste mistake?

Would be nice to mark up or otherwise differentiate the variables from the syntax. E.g. the TK manual uses italic width, height, x and y.

Minimal change:

Suggested change

      
                  Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return
          
                  Set geometry to *newGeometry* of the form =widthxheight+x+y. Return

Apostrophe for window manager's

Suggested change

      
                  The window will be decorated with the window managers title bar,
          
                  The window will be decorated with the window manager's title bar,

Spelling: width

Suggested change

      
               .. method:: resizable(widht=None, height=None)
          
               .. method:: resizable(width=None, height=None)

The doc for a particular widget should have none of the inherited methods and all of the added methods. The inherited methods should be documented and listed just once and referenced from each widget. The NMT Shipman docs called the inherited methods (at least those in Misc) 'Universal methods'. We need similar redundancy avoidance in our docs.

@Hpmason Martin made numberous specific suggestions. Do you plan to respond, or was this a one-shot contribution?

@vadmium If you had used the 'Insert a suggestion' feature, the first icon on the top row of icons, then I believe I as well as OP Hpmason could just clisk 'Accept' for each one.

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Sorry, I have been busy with work and have not had the chance to go over the suggested edits.
I saw that markroseman on the issue tracker suggested some good changes. I would don't see myself having the time to making those, and would be more than happy to let him take over if he wants to work on those changes.

@Hpmason Please do not delete your branch if you have not yet. Serhiy, the main tkinter maintainer, just indicated an interest in reviewing this. He, with a review from me, merge another tkinter doc patch a day or two ago. With him involved, it am going to review and check the existing suggestions.

Suggested change

      
                  Call FUNC once if the Tcl main loop has no event to
          
                  Call *func* the next time the Tcl main loop has no event to

Suggested change

given as first parameter.

This line is merged into the previous line by my previous suggestion.

Suggested change

      
                  Identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle` must be
          
                  This is the identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle`.

Note: at least on Windows, there is only one clipboard, even when there are multiple screens.

Suggested change

      
                  Retrieve data from the clipboard on window's display.
          
                  The window keyword defaults to the root window of the Tkinter
          
                  application.
          
                  The type keyword specifies the form in which the data is
          
                  Return data from the clipboard.
          
                  The *window* keyword defaults to the root window of the Tkinter
          
                  application.  The *type* keyword specifies the form in which the data is

I think "Tk clipboard" should be explained.

Suggested change

      
                  Return widget which has currently the grab in this application
          
                  Return the widget that currently has the grab in this application

Suggested change

      
                  Return owner of X selection.
          
                  Return the owner of the X selection.

Suggested change

      
                  Return geometry string for this widget in the form "widthxheight+X+Y".
          
                  Return the geometry string for this widget in the form "widthxheight+X+Y".

Suggested change

      
                  Return width of this widget.
          
                  Return the width of this widget.

Return the identifier? Return an identifier? Omit 'ID'?

Suggested change

      
                  Return the number of pixels of the height of the screen of this widget
          
                  in pixel.
          
                  Return the height of the screen of this widget in pixels.

Suggested change

      
                  Return the number of pixels of the width of the screen of
          
                  this widget in pixel.
          
                  Return the width of the screen of this widget in pixels.

Suggested change

      
                  ButtonPress, Button, Expose, Motion, ButtonRelease
          
                  FocusIn, MouseWheel, Circulate, FocusOut, Property,
          
                  Colormap, Gravity Reparent, Configure, KeyPress, Key,
          
                  Unmap, Deactivate, KeyRelease Visibility, Destroy,
          
                  ButtonPress, Button, Expose, Motion, ButtonRelease,
          
                  FocusIn, MouseWheel, Circulate, FocusOut, Property,
          
                  Colormap, Gravity, Reparent, Configure, KeyPress, Key,
          
                  Unmap, Deactivate, KeyRelease, Visibility, Destroy,

Suggested change

      
                  Store VALUE in WM_COMMAND property. It is the command
          
                  which shall be used to invoke the application. Return current
          
                  command if VALUE is None.
          
                  Deiconify this widget. If it was never mapped it will not be mapped.
          
                  On Windows it will raise this widget and give it the focus.

Pasted.

Suggested change

      
               .. method:: iconphoto(defualt=False, *args)
          
               .. method:: iconphoto(default=False, *args)

The misspelling is NOT in the signature.

Not needed for blurb, as oposed to checkin message.

Suggested change


	Descriptions taken from source code docstrings.

In this review, I implemented nearly all of vadmium's suggestions. Some appear attached to his suggestions, others appear separately because he only attached comments to 1 line and not necessarily the one that needed change. It would probably be easier to review my suggestions on the 'file' page where they should be in order.

Serhiy, I left suggestions for you to review and merge (click button) and resolve (click other button if needed). Some of these changes should be propagated back to the docstrings. You can decide which.

Once these are all resolved, I can look through again.

I currently work on alternative PR. While this PR copies from docstrings to the documentation, I copy directly from Tk docs. Docstrings are less detailed and may be outdated, as they were based on old Tk docs.

@Hpmason Please do not delete your branch if you have not yet. ...

Sorry, I saw the merge to sync with the main branch and assumed it was some sort of bulk change, so I had closed this MR since it is outdated. I can apply the changes suggested to let this move along, though it sounds like Serhiy is working on a more updated version that more closely matches the Tk docs.

Yes, leave this alone for now. Thanks for the effort.

This PR is stale because it has been open for 30 days with no activity.

Superseded by #151579.

bpo-42560: Add more tkinter documentation

b8373de

the-knights-who-say-ni added the CLA not signed label Dec 8, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Dec 8, 2020

blurb-it Bot and others added 2 commits December 8, 2020 02:47

📜🤖 Added by blurb_it.

d635ae3

bpo-42560: trim trailing whitespace in tkinter.rst

c07ea8f

the-knights-who-say-ni added CLA signed and removed CLA not signed labels Dec 9, 2020

github-actions Bot added the stale Stale PR or inactive for long period of time. label Jan 9, 2021

vadmium reviewed Jul 4, 2021

View reviewed changes

python deleted a comment from the-knights-who-say-ni Aug 12, 2021

terryjreedy changed the title bpo-42560: Add more tkinter documentation bpo-42560: Document more tkinter.Tk methods Aug 12, 2021

terryjreedy requested changes Aug 12, 2021

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Aug 12, 2021

ezio-melotti removed the CLA signed label Jul 13, 2022

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Aug 2, 2022

serhiy-storchaka self-requested a review November 2, 2023 18:27

Merge branch 'main' into fix-issue-42560

4f58cba

Hpmason closed this Nov 2, 2023

terryjreedy reopened this Nov 3, 2023

terryjreedy changed the title bpo-42560: Document more tkinter.Tk methods gh-86726: Document more tkinter.Tk methods Nov 3, 2023

terryjreedy reviewed Nov 3, 2023

View reviewed changes

hpmason mannequin mentioned this pull request Nov 3, 2023

Improve Tkinter Documentation #86726

Closed

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 8, 2026

serhiy-storchaka closed this Jun 18, 2026


		.. FIXME: The following keyword arguments are currently recognized:

		Methods inheritted from :class:`Misc` parent class (some methods ommited):

	Methods inheritted from :class:`Misc` parent class (some methods ommited):
	Methods inherited from :class:`!Misc` parent class (some methods omited):


		.. method:: destroy()

		Destroy this and all descendants widgets. This will

	Destroy this and all descendants widgets. This will
	Destroy this and all descendant widgets. This will

		@@ -0,0 +1,4 @@
		Added most (not all) of the methods for the `Tkinter.Tk` class.


		Call function once after given time.

		MS specifies the time in milliseconds. FUNC gives the

	MS specifies the time in milliseconds. FUNC gives the
	Ms specifies the time in milliseconds. Func is the function

+                 .. method:: after_idle(func, *args)
+                    Call FUNC once if the Tcl main loop has no event to
+                    process.

+                    whether this is a topmost window (displays above all other
+                    windows).
+                    On Macintosh, XXXXX


		.. method:: geometry(newGeometry=None)

		Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return

	Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return
	Set geometry to newGeometry of the form =widthxheight+x+y. Return

+                 .. method:: manage(widget)
+                    The widget specified will become a stand alone top-level window.
+                    The window will be decorated with the window managers title bar,

	The window will be decorated with the window managers title bar,
	The window will be decorated with the window manager's title bar,

+                    Return the function bound to NAME if None is given. NAME could be
+                    e.g. "WM_SAVE_YOURSELF" or "WM_DELETE_WINDOW".
+                 .. method:: resizable(widht=None, height=None)

	.. method:: resizable(widht=None, height=None)
	.. method:: resizable(width=None, height=None)


		.. method:: after_idle(func, *args)

		Call FUNC once if the Tcl main loop has no event to

	Call FUNC once if the Tcl main loop has no event to
	Call func the next time the Tcl main loop has no event to

+                    Cancel scheduling of function identified with ID.
+                    Identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle` must be
+                    given as first parameter.


		Cancel scheduling of function identified with ID.

		Identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle` must be

	Identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle` must be
	This is the identifier returned by :meth:`~Tk.after` or :meth:`~Tk.after_idle`.

gh-86726: Document more tkinter.Tk methods by Hpmason · Pull Request #23689 · python/cpython · GitHub

Repository navigation

gh-86726: Document more tkinter.Tk methods - #23689

gh-86726: Document more tkinter.Tk methods#23689Hpmason wants to merge 4 commits intopython:mainpython/cpython:mainfrom Hpmason:fix-issue-42560Hpmason/cpython:fix-issue-42560Copy head branch name to clipboard

Conversation

Hpmason commented Dec 8, 2020 • edited by terryjreedy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jan 9, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terryjreedy Nov 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terryjreedy left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Aug 12, 2021

Uh oh!

Hpmason commented Aug 12, 2021

Uh oh!

terryjreedy commented Nov 3, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

terryjreedy Nov 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

gh-86726: Document more tkinter.Tk methods#23689
Hpmason wants to merge 4 commits into
python:mainfrom
Hpmason:fix-issue-42560

Hpmason commented Dec 8, 2020 •
edited by terryjreedy
Loading

terryjreedy Nov 3, 2023 •
edited
Loading

terryjreedy Nov 3, 2023 •
edited
Loading

terryjreedy Nov 3, 2023 •
edited
Loading


		.. method:: clipboard_clear(**kw)

		Clear the data in the Tk clipboard.


		.. method:: grab_current()

		Return widget which has currently the grab in this application

	Return widget which has currently the grab in this application
	Return the widget that currently has the grab in this application


		.. method:: selection_own_get(**kw)

		Return owner of X selection.

	Return owner of X selection.
	Return the owner of the X selection.


		.. method:: winfo_geometry()

		Return geometry string for this widget in the form "widthxheight+X+Y".

	Return geometry string for this widget in the form "widthxheight+X+Y".
	Return the geometry string for this widget in the form "widthxheight+X+Y".

	Return width of this widget.
	Return the width of this widget.

		Return the number of pixels of the height of the screen of this widget
		in pixel.

	Return the number of pixels of the height of the screen of this widget
	in pixel.
	Return the height of the screen of this widget in pixels.