Skip to content

bpo-13553: Document tkinter.Tk args #4786

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

Merged
JelleZijlstra merged 8 commits into from
May 10, 2022
Merged

bpo-13553: Document tkinter.Tk args #4786

Changes from 1 commit
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
Prev Previous commit
Next Next commit
Add attributes and remove readprofile
  • Loading branch information
@csabella
csabella committed Dec 14, 2017
commit 0f468bcef13d1c6cea089d1bef48a21893bb9eb2
44 changes: 33 additions & 11 deletions Doc/library/tkinter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ Or, more often::
.. 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. Each instance has its own associated Tcl interpreter.
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:
Expand All @@ -79,11 +80,11 @@ Or, more often::
When given (as a string), sets the :envvar:`DISPLAY` environmental
variable. (X11 only)
Comment thread
JulienPalard marked this conversation as resolved.
*baseName*
Name of the profile file used in :meth:`readprofile`. By default,
*baseName* is derived from the program name (``sys.argv[0]``).
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 in :meth:`readprofile`
and used as the name with which Tcl is invoked (*argv0* in *interp*).
Name of the widget class. Used as a profile file and also as the name
with which Tcl is invoked (*argv0* in *interp*).

@roseman roseman Jun 4, 2018

Copy link
Copy Markdown
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.

@csabella csabella Jun 5, 2018

Copy link
Copy Markdown
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.

@roseman roseman Jun 5, 2018

Copy link
Copy Markdown
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``.
Expand All @@ -100,13 +101,34 @@ Or, more often::
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.

.. method:: readprofile(self, baseName, className)
: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` environmental variable or, if that
isn't defined, then :attr:`os.curdir`.

Read the profile files, :file:`.{className}.tcl` and
:file:`.{baseName}.tcl`, into the Tcl interpreter and call :func:`exec`
on the contents of :file:`.{className}.py` and :file:`.{baseName}.py`.
The path for the profile files is the :envvar:`HOME` environmental
variable or, if that isn't defined, then :attr:`os.curdir`.
.. attribute:: tk

The ``_tkinter.tkapp`` object created by instantiating :class:`Tk`. This
Comment thread
JulienPalard marked this conversation as resolved.
Outdated
provides access to the C methods and attributes, including the Tcl
Comment thread
willingc marked this conversation as resolved.
Outdated
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 descendents of this widget as a :class:`dict` with the child widget
names as the keys and the child instance objects as the values.
Comment thread
willingc marked this conversation as resolved.
Outdated

@vstinner vstinner Dec 12, 2017

Copy link
Copy Markdown
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.

@csabella csabella Dec 12, 2017

Copy link
Copy Markdown
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)
Expand Down