From fdc96edc24d30c8f2a1fb5191def2bcb9d9b4dfc Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Sun, 10 Dec 2017 19:14:14 -0500 Subject: [PATCH 1/7] bpo-13553: Document tkinter.Tk args --- Doc/library/tkinter.rst | 34 +++++++++++++++---- .../2017-12-10-19-13-39.bpo-13553.gQbZs4.rst | 1 + 2 files changed, 28 insertions(+), 7 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2017-12-10-19-13-39.bpo-13553.gQbZs4.rst diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index f222fe6f8b2053..934eb639fe4762 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -67,13 +67,33 @@ Or, more often:: from tkinter import * -.. 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: +.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1, sync=0, use=None) + + Return a toplevel Tk widget, which is usually the main window of an + application. 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* + Sets the DISPLAY environmental variable. (X11 only) + *baseName* + Reads the profile file :file:`baseName.tcl` into the Tcl interpreter and + calls ``exec`` on the contents of :file:`baseName.py`. + *className* + Name of the widget class. Used as a profile file name + (:file:`className.tcl` and :file:`className.py` load before the + *baseName* files), and also used as the name with which Tcl is + invoked (*argv0* in *interp*). + *useTk* + If True, initialize the Tk subsystem. :func:`Tcl` sets this to False. + *sync* + If True, execute all X server commands synchronously, so that errors are + reported immediately. + *use* + Specifies that the main window for the application is to be embedded in + the window whose identifier is given, instead of being created as an + independent toplevel window. .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) diff --git a/Misc/NEWS.d/next/Documentation/2017-12-10-19-13-39.bpo-13553.gQbZs4.rst b/Misc/NEWS.d/next/Documentation/2017-12-10-19-13-39.bpo-13553.gQbZs4.rst new file mode 100644 index 00000000000000..23d3c1555e3707 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2017-12-10-19-13-39.bpo-13553.gQbZs4.rst @@ -0,0 +1 @@ +Document tkinter.Tk args. From 35c64653754fc978b18024fecc9ceddb23bd8b35 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Mon, 11 Dec 2017 18:44:13 -0500 Subject: [PATCH 2/7] Changes suggested by Serhiy. --- Doc/library/tkinter.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 934eb639fe4762..36d40d6d0562de 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -67,28 +67,29 @@ Or, more often:: from tkinter import * -.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1, sync=0, use=None) +.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None) - Return a toplevel Tk widget, which is usually the main window of an - application. Each instance has its own associated Tcl interpreter. + Toplevel Tk widget, which is usually the main window of an application. + 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* - Sets the DISPLAY environmental variable. (X11 only) + Sets the :envvar:`DISPLAY` environmental variable. (X11 only) *baseName* - Reads the profile file :file:`baseName.tcl` into the Tcl interpreter and - calls ``exec`` on the contents of :file:`baseName.py`. + Reads the profile file :file:`{baseName}.tcl` into the Tcl interpreter + and calls :func:`exec` on the contents of :file:`{baseName}.py`. *className* Name of the widget class. Used as a profile file name - (:file:`className.tcl` and :file:`className.py` load before the + (:file:`{className}.tcl` and :file:`{className}.py` load before the *baseName* files), and also used as the name with which Tcl is invoked (*argv0* in *interp*). *useTk* - If True, initialize the Tk subsystem. :func:`Tcl` sets this to False. + If ``True``, initialize the Tk subsystem. :func:`Tcl` sets this to + ``False``. *sync* - If True, execute all X server commands synchronously, so that errors are + If ``True``, execute all X server commands synchronously, so that errors are reported immediately. *use* Specifies that the main window for the application is to be embedded in @@ -96,7 +97,7 @@ Or, more often:: independent toplevel window. -.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) +.. 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 From df696bb123fa2c0a213b9a1acc6c523bfc3a44a5 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Tue, 12 Dec 2017 15:52:13 -0500 Subject: [PATCH 3/7] Additional changes --- Doc/library/tkinter.rst | 44 ++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 36d40d6d0562de..243048f2bc81c5 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -69,32 +69,44 @@ Or, more often:: .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None) - Toplevel Tk widget, which is usually the main window of an application. - Each instance has its own associated Tcl interpreter. + Construct a toplevel Tk widget, which is usually the main window of an + application. 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* - Sets the :envvar:`DISPLAY` environmental variable. (X11 only) + When given (as a string), sets the :envvar:`DISPLAY` environmental + variable. (X11 only) *baseName* - Reads the profile file :file:`{baseName}.tcl` into the Tcl interpreter - and calls :func:`exec` on the contents of :file:`{baseName}.py`. + Name of the profile file used in :meth:`readprofile`. By default, + *baseName* is derived from the program name (``sys.argv[0]``). *className* - Name of the widget class. Used as a profile file name - (:file:`{className}.tcl` and :file:`{className}.py` load before the - *baseName* files), and also used as the name with which Tcl is - invoked (*argv0* in *interp*). + 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*). *useTk* - If ``True``, initialize the Tk subsystem. :func:`Tcl` sets this to - ``False``. + If ``True``, initialize the Tk subsystem. The :func:`tkinter.Tcl() ` + function sets this to ``False``. *sync* - If ``True``, execute all X server commands synchronously, so that errors are - reported immediately. + If ``True``, execute all X server commands synchronously, so that errors + are reported immediately. *use* - Specifies that the main window for the application is to be embedded in - the window whose identifier is given, instead of being created as an - independent toplevel window. + Specifies the *id* of the main window in which to embed the application, + instead of it being created as an independent toplevel window. *id* must + 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. + + .. method:: readprofile(self, baseName, className) + + 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`. .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) From 0f468bcef13d1c6cea089d1bef48a21893bb9eb2 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Thu, 14 Dec 2017 18:21:59 -0500 Subject: [PATCH 4/7] Add attributes and remove readprofile --- Doc/library/tkinter.rst | 44 ++++++++++++++++++++++++++++++----------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 243048f2bc81c5..4b26222ae541cb 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -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: @@ -79,11 +80,11 @@ Or, more often:: When given (as a string), sets the :envvar:`DISPLAY` environmental variable. (X11 only) *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*). *useTk* If ``True``, initialize the Tk subsystem. The :func:`tkinter.Tcl() ` function sets this to ``False``. @@ -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 + provides access to the C methods and attributes, including 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 descendents of this widget as a :class:`dict` with the child widget + names as the keys and the child instance objects as the values. .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) From c25db70ca2dab6da6c9ae532e7daad1ac2272072 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Thu, 14 Dec 2017 18:31:58 -0500 Subject: [PATCH 5/7] Modify readprofile docstring for file names. --- Lib/tkinter/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py index deea791831ed66..be52e79913f4e7 100644 --- a/Lib/tkinter/__init__.py +++ b/Lib/tkinter/__init__.py @@ -2059,9 +2059,9 @@ def destroy(self): if _support_default_root and _default_root is 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 From 90684066f318e51982ff24fee846954d0c730362 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Fri, 22 Dec 2017 17:18:14 -0500 Subject: [PATCH 6/7] Remove reference to C methods --- Doc/library/tkinter.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 4b26222ae541cb..408f451ce5d5d6 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -77,7 +77,7 @@ Or, more often:: However, the following keyword arguments are currently recognized: *screenName* - When given (as a string), sets the :envvar:`DISPLAY` environmental + When given (as a string), sets the :envvar:`DISPLAY` environment variable. (X11 only) *baseName* Name of the profile file. By default, *baseName* is derived from the @@ -105,15 +105,15 @@ Or, more often:: :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 + profile files is the :envvar:`HOME` environment variable or, if that isn't defined, then :attr:`os.curdir`. .. attribute:: tk - The ``_tkinter.tkapp`` object created by instantiating :class:`Tk`. This - provides access to the C methods and attributes, including the Tcl - interpreter. Each widget that is attached the same instance of - :class:`Tk` has the same value for its :attr:`tk` attribute. + 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 From 005484437289af71ba8ec49a1f8d97e1ee32d838 Mon Sep 17 00:00:00 2001 From: Cheryl Sabella Date: Tue, 5 Jun 2018 11:39:14 -0400 Subject: [PATCH 7/7] Additional changes per review --- Doc/library/tkinter.rst | 9 +++++---- Lib/tkinter/__init__.py | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 408f451ce5d5d6..e49fa90d545cb6 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -90,9 +90,9 @@ Or, more often:: function sets this to ``False``. *sync* If ``True``, execute all X server commands synchronously, so that errors - are reported immediately. + are reported immediately. Can be used for debugging. (X11 only) *use* - Specifies the *id* of the main window in which to embed the application, + Specifies the *id* of the window in which to embed the application, instead of it being created as an independent toplevel window. *id* must 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 @@ -127,8 +127,9 @@ Or, more often:: .. 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. + 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. .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py index be52e79913f4e7..5b383d54631b1e 100644 --- a/Lib/tkinter/__init__.py +++ b/Lib/tkinter/__init__.py @@ -1855,7 +1855,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."""