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

Hpmason · 2020-12-08T02:42:00Z

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

github-actions · 2021-01-09T00:44:22Z

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

vadmium · 2021-07-04T05:06:15Z

Doc/library/tkinter.rst

@@ -95,6 +95,568 @@ Or, more often::

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

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


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.

vadmium · 2021-07-04T05:07:46Z

Doc/library/tkinter.rst

+
+   .. method:: destroy()
+
+      Destroy this and all descendants widgets. This will


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

vadmium · 2021-07-04T05:23:46Z

Misc/NEWS.d/next/Documentation/2020-12-08-02-47-08.bpo-42560.Pvk107.rst

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


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.

vadmium · 2021-07-04T05:33:49Z

Doc/library/tkinter.rst

+
+      Call function once after given time.
+
+      MS specifies the time in milliseconds. FUNC gives the


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

vadmium · 2021-07-04T05:39:22Z

Doc/library/tkinter.rst

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


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.

vadmium · 2021-07-04T06:56:31Z

Doc/library/tkinter.rst

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


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

vadmium · 2021-07-04T06:58:55Z

Doc/library/tkinter.rst

+
+      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.


Copy and paste mistake?

vadmium · 2021-07-04T07:03:18Z

Doc/library/tkinter.rst

+
+   .. method:: geometry(newGeometry=None)
+
+      Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return


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

vadmium · 2021-07-04T07:09:45Z

Doc/library/tkinter.rst

+   .. 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,


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,

vadmium · 2021-07-04T07:12:31Z

Doc/library/tkinter.rst

+      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)


Spelling: width

Suggested change

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

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

terryjreedy

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.

bedevere-bot · 2021-08-12T16:08:45Z

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.

Hpmason · 2021-08-12T17:41:33Z

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.

terryjreedy · 2023-11-03T00:20:43Z

@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.

terryjreedy · 2023-11-03T00:41:49Z

Doc/library/tkinter.rst

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


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

terryjreedy · 2023-11-03T00:47:05Z

Doc/library/tkinter.rst

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


Suggested change

given as first parameter.

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

terryjreedy · 2023-11-03T00:48:26Z

Doc/library/tkinter.rst

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


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`.

terryjreedy · 2023-11-03T01:09:05Z

Doc/library/tkinter.rst

+      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


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

terryjreedy · 2023-11-03T01:55:04Z

Doc/library/tkinter.rst

+
+   .. method:: clipboard_clear(**kw)
+
+      Clear the data in the Tk clipboard.


I think "Tk clipboard" should be explained.

terryjreedy · 2023-11-03T01:56:26Z

Doc/library/tkinter.rst

+
+   .. method:: grab_current()
+
+      Return widget which has currently the grab in this application


Suggested change

Return widget which has currently the grab in this application

Return the widget that currently has the grab in this application

terryjreedy · 2023-11-03T02:07:56Z

Doc/library/tkinter.rst

+
+   .. method:: selection_own_get(**kw)
+
+      Return owner of X selection.


Suggested change

Return owner of X selection.

Return the owner of the X selection.

terryjreedy · 2023-11-03T02:09:38Z

Doc/library/tkinter.rst

+
+   .. method:: winfo_geometry()
+
+      Return geometry string for this widget in the form "widthxheight+X+Y".


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".

terryjreedy · 2023-11-03T02:10:21Z

Doc/library/tkinter.rst

+
+   .. method:: winfo_width()
+
+      Return width of this widget.


Suggested change

Return width of this widget.

Return the width of this widget.

terryjreedy · 2023-11-03T02:11:33Z

Doc/library/tkinter.rst

+
+   .. method:: winfo_id()
+
+      Return identifier ID for this widget.


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

terryjreedy · 2023-11-03T02:14:14Z

Doc/library/tkinter.rst

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


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.

terryjreedy · 2023-11-03T02:14:40Z

Doc/library/tkinter.rst

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


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.

terryjreedy · 2023-11-03T02:18:39Z

Doc/library/tkinter.rst

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


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,

terryjreedy · 2023-11-03T02:33:01Z

Doc/library/tkinter.rst

+      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.


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.

terryjreedy · 2023-11-03T02:36:27Z

Doc/library/tkinter.rst

+      Set the name of the icon for this widget. Return the name if
+      None is given.
+
+   .. method:: iconphoto(defualt=False, *args)


Suggested change

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

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

The misspelling is NOT in the signature.

terryjreedy · 2023-11-03T02:41:39Z

Misc/NEWS.d/next/Documentation/2020-12-08-02-47-08.bpo-42560.Pvk107.rst

+
+Descriptions taken from source code docstrings.


Not needed for blurb, as oposed to checkin message.

Suggested change

Descriptions taken from source code docstrings.

terryjreedy · 2023-11-03T02:50:41Z

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.

serhiy-storchaka · 2023-11-03T06:57:41Z

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 · 2023-11-04T04:05:25Z

@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.

terryjreedy · 2023-11-04T07:04:23Z

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

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

Open

		@@ -95,6 +95,568 @@ Or, more often::

		.. 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:: 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

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

	.. 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

	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`.


		.. 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.

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

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!

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:: 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.

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

	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.

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