Skip to content
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

Jump to bottom

bpo-13553: Document tkinter.Tk args #4786

Merged
merged 8 commits into from
May 10, 2022
Merged

bpo-13553: Document tkinter.Tk args #4786

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fdc96ed
bpo-13553: Document tkinter.Tk args
csabella Dec 11, 2017
35c6465
Changes suggested by Serhiy.
csabella Dec 11, 2017
df696bb
Additional changes
csabella Dec 12, 2017
0f468bc
Add attributes and remove readprofile
csabella Dec 14, 2017
c25db70
Modify readprofile docstring for file names.
csabella Dec 14, 2017
9068406
Remove reference to C methods
csabella Dec 22, 2017
0054844
Additional changes per review
csabella Jun 5, 2018
57553df
Merge branch 'main' into bpo13553
JelleZijlstra May 8, 2022
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
76 changes: 66 additions & 10 deletions Doc/library/tkinter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,16 +124,72 @@ the modern themed widget set and API::
from tkinter import ttk


.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)

The :class:`Tk` class is instantiated without arguments. This creates a toplevel
widget of Tk which usually is the main window of an application. Each instance
has its own associated Tcl interpreter.

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


.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)
.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construct a toplevel Tk widget, which is usually the main window of an
application, and initialize a Tcl interpreter for this widget. Each
instance has its own associated Tcl interpreter.

The :class:`Tk` class is typically instantiated using all default values.
However, the following keyword arguments are currently recognized:

*screenName*
When given (as a string), sets the :envvar:`DISPLAY` environment
variable. (X11 only)
JulienPalard marked this conversation as resolved.
Show resolved Hide resolved
*baseName*
Name of the profile file. By default, *baseName* is derived from the
program name (``sys.argv[0]``).
*className*
Name of the widget class. Used as a profile file and also as the name
with which Tcl is invoked (*argv0* in *interp*).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So about baseName and className...

My understanding is that className is the equivalent of wish's "-name" option. So this provides the default title for the root window, the class of the root window (which can be used in bindings and option database), and would be what is returned by "tk appname" (sometimes used for inter-application communication).

It appears that baseName isn't passed into Tcl/Tk at all.

About those profile files that can be read in... does anyone know what they're intended to be used for, if they've ever been documented, and if they're actually used at all? It reads like a per-application 'automatically inject your own code' which seems a bit strange.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried out specifying className on a call and it seems to lower case the first letter:

root = tkinter.Tk(className='TEST')

creates a window with the name tEST and root.tk.call('tk', 'appname') returns tEST. Should I document that behavior? Since fileName in the wish documentation is used to find the script, I think it might be lowercased for that reason?

Looking through the documentation, it looks like interp is used for inter-application communication, which is the value stored in Tk.tk.

tk appname ?newName?
    If newName is not specified, this command returns the name of the application (the name
    that may be used in **send** commands to communicate with the application)

However, the send command in tkinter has:

    def send(self, interp, cmd, *args):
        """Send Tcl command CMD to different interpreter INTERP to be executed."""
        return self.tk.call(('send', interp, cmd) + args)

As far as the profile files, there was a security patch in the past.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why the first letter is lowercased - it's Tkinter that's doing it, though for what reason I can't guess. From the Tcl side it's perfectly ok with the first letter of argv0 capitalized. My instinct therefore is not to document it.

Note that the classname for the window will lowercase everything except for uppercasing the first letter, e.g. "Test" with your example. I think the first letter uppercase is used for user class names vs. builtin ones like 'button' etc. I was playing around with different things using this:

r = Tk(className='TEST')
print(r.call('tk','appname'))
print(r.wm_title())
print(r.bindtags())
print(sys.argv[0])

I'd suggest not documenting this conversion either. Anyone who needs to get the exact capitalization of the classname will know how to get it through introspection. I also don't imagine that 'send' would be used much by Tkinter apps (it was a useful thing a long while ago, not so much now).

Any suggestions how to proceed with regard to the readprofile() thing, i.e. what on earth it is for and if it should still be there? @serhiy-storchaka ?

*useTk*
If ``True``, initialize the Tk subsystem. The :func:`tkinter.Tcl() <Tcl>`
function sets this to ``False``.
*sync*
If ``True``, execute all X server commands synchronously, so that errors
are reported immediately. Can be used for debugging. (X11 only)
*use*
Specifies the *id* of the window in which to embed the application,
instead of it being created as an independent toplevel window. *id* must
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be "Specifies the id of the window". This whole piece was used for application embedding (think web browser plugins). Therefore, it would be almost always the case that you'd embed inside a specific subwindow somewhere, not directly in the "main" window of the application (which I'd read as toplevel)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you. I think I had taken this from the wish man page and unintentionally changed the meaning slightly with my edit.

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

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.

:class:`Tk` reads and interprets profile files, named
:file:`.{className}.tcl` and :file:`.{baseName}.tcl`, into the Tcl
interpreter and calls :func:`exec` on the contents of
:file:`.{className}.py` and :file:`.{baseName}.py`. The path for the
profile files is the :envvar:`HOME` environment variable or, if that
isn't defined, then :attr:`os.curdir`.

.. attribute:: tk

The Tk application object created by instantiating :class:`Tk`. This
provides access to the Tcl interpreter. Each widget that is attached
the same instance of :class:`Tk` has the same value for its :attr:`tk`
attribute.

.. attribute:: master

The widget object that contains this widget. For :class:`Tk`, the
*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*/*slave* reflects the container structure.

.. attribute:: children

The immediate descendants of this widget as a :class:`dict` with the
child widget names as the keys and the child instance objects as the
values.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we are documenting the Tk class. Would it be worth it to document Tk attributes? master, children and tk.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current page reads more like a 'getting started' or 'how to', so I wasn't sure how much detail to add. I know there's a separate bug issue where Terry figured out the difference between master and parent, so maybe it would be worthwhile to include that here?


.. 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
Expand Down
8 changes: 4 additions & 4 deletions Lib/tkinter/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2126,7 +2126,7 @@ def wm_iconbitmap(self, bitmap=None, default=None):
the bitmap if None is given.

Under Windows, the DEFAULT parameter can be used to set the icon
for the widget and any descendents that don't have an icon set
for the widget and any descendants that don't have an icon set
explicitly. DEFAULT can be the relative path to a .ico file
(example: root.iconbitmap(default='myicon.ico') ). See Tk
documentation for more information."""
Expand Down Expand Up @@ -2372,9 +2372,9 @@ def destroy(self):
_default_root = None

def readprofile(self, baseName, className):
"""Internal function. It reads BASENAME.tcl and CLASSNAME.tcl into
the Tcl Interpreter and calls exec on the contents of BASENAME.py and
CLASSNAME.py if such a file exists in the home directory."""
"""Internal function. It reads .BASENAME.tcl and .CLASSNAME.tcl into
the Tcl Interpreter and calls exec on the contents of .BASENAME.py and
.CLASSNAME.py if such a file exists in the home directory."""
import os
if 'HOME' in os.environ: home = os.environ['HOME']
else: home = os.curdir
Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Documentation/2017-12-10-19-13-39.bpo-13553.gQbZs4.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document tkinter.Tk args.