From 79b195a9028fd7bf6e8186dfced0fad6a41e87fa Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sat, 19 May 2018 23:33:33 +0300 Subject: [PATCH 01/24] * Reduce the index page to a summary like the other ones --- Doc/library/tk.rst | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst index 95cd1c7712e7c9..3886be0a590a08 100644 --- a/Doc/library/tk.rst +++ b/Doc/library/tk.rst @@ -10,25 +10,8 @@ Graphical User Interfaces with Tk single: Tkinter single: Tk -Tk/Tcl has long been an integral part of Python. It provides a robust and -platform independent windowing toolkit, that is available to Python programmers -using the :mod:`tkinter` package, and its extension, the :mod:`tkinter.tix` and -the :mod:`tkinter.ttk` modules. - -The :mod:`tkinter` package is a thin object-oriented layer on top of Tcl/Tk. To -use :mod:`tkinter`, you don't need to write Tcl code, but you will need to -consult the Tk documentation, and occasionally the Tcl documentation. -:mod:`tkinter` is a set of wrappers that implement the Tk widgets as Python -classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe -mechanism which allows Python and Tcl to interact. - -:mod:`tkinter`'s chief virtues are that it is fast, and that it usually comes -bundled with Python. Although its standard documentation is weak, good -material is available, which includes: references, tutorials, a book and -others. :mod:`tkinter` is also famous for having an outdated look and feel, -which has been vastly improved in Tk 8.5. Nevertheless, there are many other -GUI libraries that you could be interested in. For more information about -alternatives, see the :ref:`other-gui-packages` section. +The modules described in this chapter allow writing graphical user interfaces +for your program using the Tcl/Tk platform-independent windowing toolkit. .. toctree:: From 6338ba1b356cfbf3447d1c2bb434e2e965eed889 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 20 May 2018 00:33:50 +0300 Subject: [PATCH 02/24] * move seealso to the bottom * insistent terminology: Tcl/Tk rather than Tk * https://bugs.python.org/issue33479#msg316492 0. Intro: +supported Tcl/Tk versions and the two flavors; the fact that Tkinter adds its own logic, and the Tkinter doc concentrates on that logic --- Doc/library/tkinter.rst | 94 ++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index d9c1c35aa294bd..19b687faa67b3b 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -11,59 +11,14 @@ -------------- The :mod:`tkinter` package ("Tk interface") is the standard Python interface to -the Tk GUI toolkit. Both Tk and :mod:`tkinter` are available on most Unix -platforms, as well as on Windows systems. (Tk itself is not part of Python; it -is maintained at ActiveState.) +the Tcl/Tk GUI toolkit. Tcl/Tk and :mod:`tkinter` are available on most Unix +platforms, as well as on Windows systems. Running ``python -m tkinter`` from the command line should open a window demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is properly installed on your system, and also showing what version of Tcl/Tk is installed, so you can read the Tcl/Tk documentation specific to that version. -.. seealso:: - - Tkinter documentation: - - `Python Tkinter Resources `_ - The Python Tkinter Topic Guide provides a great deal of information on using Tk - from Python and links to other sources of information on Tk. - - `TKDocs `_ - Extensive tutorial plus friendlier widget pages for some of the widgets. - - `Tkinter reference: a GUI for Python `_ - On-line reference material. - - `Tkinter docs from effbot `_ - Online reference for tkinter supported by effbot.org. - - `Programming Python `_ - Book by Mark Lutz, has excellent coverage of Tkinter. - - `Modern Tkinter for Busy Python Developers `_ - Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter. - - `Python and Tkinter Programming `_ - Book by John Grayson (ISBN 1-884777-81-3). - - Tcl/Tk documentation: - - `Tk commands `_ - Most commands are available as :mod:`tkinter` or :mod:`tkinter.ttk` classes. - Change '8.6' to match the version of your Tcl/Tk installation. - - `Tcl/Tk recent man pages `_ - Recent Tcl/Tk manuals on www.tcl.tk. - - `ActiveState Tcl Home Page `_ - The Tk/Tcl development is largely taking place at ActiveState. - - `Tcl and the Tk Toolkit `_ - Book by John Ousterhout, the inventor of Tcl. - - `Practical Programming in Tcl and Tk `_ - Brent Welch's encyclopedic book. - Tkinter Modules --------------- @@ -858,3 +813,48 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``. EXCEPTION Constants used in the *mask* arguments. + +.. seealso:: + + Tkinter documentation: + + `Python Tkinter Resources `_ + The Python Tkinter Topic Guide provides a great deal of information on using Tk + from Python and links to other sources of information on Tk. + + `TKDocs `_ + Extensive tutorial plus friendlier widget pages for some of the widgets. + + `Tkinter reference: a GUI for Python `_ + On-line reference material. + + `Tkinter docs from effbot `_ + Online reference for tkinter supported by effbot.org. + + `Programming Python `_ + Book by Mark Lutz, has excellent coverage of Tkinter. + + `Modern Tkinter for Busy Python Developers `_ + Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter. + + `Python and Tkinter Programming `_ + Book by John Grayson (ISBN 1-884777-81-3). + + Tcl/Tk documentation: + + `Tk commands `_ + Most commands are available as :mod:`tkinter` or :mod:`tkinter.ttk` classes. + Change '8.6' to match the version of your Tcl/Tk installation. + + `Tcl/Tk recent man pages `_ + Recent Tcl/Tk manuals on www.tcl.tk. + + `ActiveState Tcl Home Page `_ + The Tk/Tcl development is largely taking place at ActiveState. + + `Tcl and the Tk Toolkit `_ + Book by John Ousterhout, the inventor of Tcl. + + `Practical Programming in Tcl and Tk `_ + Brent Welch's encyclopedic book. + From 02f712eb60c72f1e722b9951b2eeb08e3ce21aa2 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 20 May 2018 00:39:20 +0300 Subject: [PATCH 03/24] more 0. intro --- Doc/library/tkinter.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 19b687faa67b3b..a83aeacbd752a3 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -19,6 +19,16 @@ demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is properly installed on your system, and also showing what version of Tcl/Tk is installed, so you can read the Tcl/Tk documentation specific to that version. +Tkinter supports a range of Tcl/Tk versions, built either with or +without thread support. The official Python binary release bundles Tcl/Tk 8.6 +threaded. See the source code for the underlying :mode:`_tkinter` C module +for more information about supported versions. + +Tkinter is not a thin wrapper, it adds a fair amount of own logic to +make the experience more pythonic. This documentation will concentrate on this +added and changed logic and refer to the official Tcl/Tk documentation for +details that are unchanged. + Tkinter Modules --------------- From e68e1363fa37ef7e76b71a05463f408c1ea1b683 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 20 May 2018 00:49:58 +0300 Subject: [PATCH 04/24] https://bugs.python.org/issue33479#msg316492 1. Architecture. --- Doc/library/tkinter.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index a83aeacbd752a3..23035ba08a34d0 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -30,6 +30,45 @@ added and changed logic and refer to the official Tcl/Tk documentation for details that are unchanged. +Architecture +------------ + +Unlike most other GUI toolkits, Tcl/Tk is not a monolithic product providing a +consolidated API. Instead, it's a bundle of libraries, each with its +separate functionality and documentation. + +Tcl + Tcl is a dynamic interpreted programming language. Though it can be used + as a general-purpose programming language, it's primary developed to be and + used as an embedded scripting engine for applications (same as Lua) and as + an interface to the Tk toolkit. The Tcl engine library has a C interface to + create and operate interpreter instances, run Tcl commands and scripts with + them and add custom commands that can be implemented in either Tcl or C. + It also implements a per-interpreter event queue. An interpreter + instance has a single stream of execution. Each :class:`Tk` object embeds + its own interpreter instance. Though :mod:`_tkinter` allows to + execute entire Tcl scripts, the Python bindings typically only invoke single + commands. + +Tk + Tk is a Tcl module implemented in C that adds custom commands to create and + manipulate GUI widgets. The interpreter's event queue is used to generate + and process events for all widgets created by it. + Tcl can be used without Tk (and Tk needs to be explicitly loaded to make it + available; :mod:`tkinter` does this automatically), though they are + typically provided together, "Tcl/Tk" being the name for the bundle. + Tk also implements the Themed Tk (Ttk) family of widgets, though `tkinter` + provides Python bindings for them in a separate module, :mod:`tkinter.ttk`. + Tk has its own C interface that duplicates the custom Tcl commands though + `tkinter` mostly uses the latter. + +Tix + `Tix` is a + third-party Tcl module, an addon for Tk that adds several new widgets. + `tkinter.tix` provides bindings for it, and official Python binary releases + come with it bundled. It's deprecated in favor of Ttk. + + Tkinter Modules --------------- From 1de7f35eb1f03554bd82de8db477aadb911f5089 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 20 May 2018 05:45:35 +0300 Subject: [PATCH 05/24] 1. Architecture -- Tkinter modules --- Doc/library/tkinter.rst | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 23035ba08a34d0..3fcc9419fa293f 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -44,10 +44,9 @@ Tcl an interface to the Tk toolkit. The Tcl engine library has a C interface to create and operate interpreter instances, run Tcl commands and scripts with them and add custom commands that can be implemented in either Tcl or C. - It also implements a per-interpreter event queue. An interpreter - instance has a single stream of execution. Each :class:`Tk` object embeds - its own interpreter instance. Though :mod:`_tkinter` allows to - execute entire Tcl scripts, the Python bindings typically only invoke single + It also implements a per-interpreter event queue. Each :class:`Tk` object + embeds its own interpreter instance. Though :mod:`_tkinter` allows to + execute entire Tcl scripts, the Python bindings typically only run single commands. Tk @@ -70,12 +69,20 @@ Tix Tkinter Modules ---------------- +^^^^^^^^^^^^^^^ + +:mod:`tkinter` has the core functionality and the regular Tk widgets. +Unless you're using the additional widgets, this will be all +that you really need. -Most of the time, :mod:`tkinter` is all you really need, but a number of -additional modules are available as well. The Tk interface is located in a -binary module named :mod:`_tkinter`. This module contains the low-level -interface to Tk, and should never be used directly by application programmers. +:mod:`tkinter.ttk` and :mod:`tkinter.tix` have classes for extra +widgets from those families. Ttk is intended to be the new standard widget +set with a more modern look, but as of this writing, it doesn't yet have +replacements for all the classical widgets. + +The Tk interface is located in a C module named :mod:`_tkinter`. +This module directly interfaces with Tcl/Tk via their C interfaces and +shouldn't be used directly by application programmers save for a few functions. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter. @@ -90,6 +97,9 @@ Or, more often:: from tkinter import * + +Module contents +--------------- .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1) From 6a7f4e84f15841d8ce747e0419ceddca957d5390 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Wed, 23 May 2018 00:39:40 +0300 Subject: [PATCH 06/24] 2. Threading model --- Doc/library/tkinter.rst | 43 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 3fcc9419fa293f..f47f18446c5464 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -97,6 +97,49 @@ Or, more often:: from tkinter import * + +Threading model +--------------- + +A Tcl interpreter has one stream of execution and, unlike most other GUI +toolkits, doesn't provide a blocking event loop. +Instead, Tcl code is supposed to pump the event queue regularly at strategic +moments -- after an action that triggers an event, before a later action that +needs the result of that event. As such, all Tcl commands are designed to work +without an event loop running, only event handlers will not be executed +until the queue is processed. This allows to work completely in one thread, +i.e. even in environments that have no thread support at all. + +This is in stark constrast to the execution model for most other GUI toolkits: +a dedicated OS thread (usually called the "UI thread") runs the GUI event loop +constantly, and other threads send work items to it -- either complete with +payload reference, or as agreed-upon "events" which result in it executing a +predefined "event handler". +Likewise, for any lengthy tasks, the UI thread can launch worker threads that +report back on their progress via the same event queue. + +Tkinter gives the best of both worlds. It presents the "modern" multithreaded +GUI model as the primary mode of execution while retaining the freedom and +flexibility of Tcl's one. Any calls can be made from any threads, only +subject to Tcl's architectural restictions: + +* For nonthreaded Tcl, all Tcl calls are wrapped with a global lock. So, + any calls can be made from any threads, but under the hood, only one + is active at a time. + +* A threaded Tcl interpreter instance, when created, becomes tied to the + creating OS thread ("the interpreter thread"). Tcl mandates that all calls + to the instance must come from this thread, except special inter-thread + communication APIs. Tkinter implements calls from outside the interpreter + thread by posting an event to the interpreter's queue that would run the + necessary commands, then waits for result. As such: + + * To make calls from outside the interpreter queue, :func:`mainloop` + must be running in the interpreter queue. Otherwise, a + :class:`RuntimeError` is raised. + + * A few select functions can only be called from the interpreter thread. + Module contents --------------- From c8f3bca50f175fd7c523267029431bb06d8aea17 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Thu, 24 May 2018 07:26:57 +0300 Subject: [PATCH 07/24] start documenting contents --- Doc/library/tkinter.rst | 159 ++++++++++++++++++++++++++++++++++------ 1 file changed, 138 insertions(+), 21 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index f47f18446c5464..06ae6fb821641a 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -106,7 +106,7 @@ toolkits, doesn't provide a blocking event loop. Instead, Tcl code is supposed to pump the event queue regularly at strategic moments -- after an action that triggers an event, before a later action that needs the result of that event. As such, all Tcl commands are designed to work -without an event loop running, only event handlers will not be executed +without an event loop running -- only event handlers will not be executed until the queue is processed. This allows to work completely in one thread, i.e. even in environments that have no thread support at all. @@ -118,21 +118,22 @@ predefined "event handler". Likewise, for any lengthy tasks, the UI thread can launch worker threads that report back on their progress via the same event queue. -Tkinter gives the best of both worlds. It presents the "modern" multithreaded -GUI model as the primary mode of execution while retaining the freedom and -flexibility of Tcl's one. Any calls can be made from any threads, only -subject to Tcl's architectural restictions: +Tkinter strives to provide the best of both worlds. The "moderm" multithreaded +GUI model is the primary mode of execution, but pumping messages manually +instead is also supported. What is more important, any Tkinter calls can be +made from any Python threads, only subject to Tcl's architectural restictions: -* For nonthreaded Tcl, all Tcl calls are wrapped with a global lock. So, - any calls can be made from any threads, but under the hood, only one - is active at a time. +* A nonthreaded Tcl doesn't know anything about threads, so all Tcl calls are + wrapped with a global lock to enforce sequential access. + Any Tkinter calls can be made from any threads, but under the hood, only one + is active at any moment. * A threaded Tcl interpreter instance, when created, becomes tied to the creating OS thread ("the interpreter thread"). Tcl mandates that all calls - to the instance must come from this thread, except special inter-thread + to the instance must come from this thread, save for special inter-thread communication APIs. Tkinter implements calls from outside the interpreter - thread by posting an event to the interpreter's queue that would run the - necessary commands, then waits for result. As such: + thread by posting an event to the interpreter's queue, then waits for the + result of its processing. As such: * To make calls from outside the interpreter queue, :func:`mainloop` must be running in the interpreter queue. Otherwise, a @@ -144,24 +145,140 @@ subject to Tcl's architectural restictions: Module contents --------------- -.. 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: +.. attribute:: TclVersion +.. attribute:: TkVersion + Tcl and Tk library versions used, as floating-point numbers + + .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) - 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 - subsystem. This is most often useful when driving the Tcl interpreter in an + A factory function which creates an instance of the :class:`Tk` class, + except that it sets `useTk` to `0` by default, thus not creating a top-level + widget. This is useful when driving the Tcl interpreter in an environment where one doesn't want to create extraneous toplevel windows, or where one cannot (such as Unix/Linux systems without an X server). An object created by the :func:`Tcl` object can have a Toplevel window created (and the Tk subsystem initialized) by calling its :meth:`loadtk` method. + All arguments are the same as in `Tk` constructor. + + +.. class:: TclError + + An exception raised for an error returned by a Tcl interpreter. + + +.. attribute:: wantobjects = 1 + + Whether Tcl call results in new Tk objects should be converted from Tcl + types to Python types. An integer, any nonzero value means "true". + If not set, string representations of Tcl objects are returned. + + +.. attribute:: READABLE +.. attribute:: WRITABLE +.. attribute:: EXCEPTION + + Constants used for the *mask* parameter of :func:`createfilehandler`. + + +.. class:: EventType + + A enumeration of known + `Tk event types `_, + used for :attr:`Event`'s *type* attribute. + + +.. class:: Event + + Container for the properties of a Tcl event. + + If a callback function is registered using :func:`bind`, + :func:`bind_all`, :func:`bind_class`, or :func:`tag_bind`, + the callback is called with an :class:`Event` as the first argument. + + Will have the same fields as the corresponding + `Tk event``_ + plus a *type* field that will contain an :class:`EventType` + or a string with a number as returned by Tcl if the event type is unknown. + + +.. function:: NoDefaultRoot() + + Unset the current default root widget and do not use newly-created + :class:`Tk` instances to set it. + + By default, the first :class:`Tk` created when the default root is unset + becomes the default root, and stays it until it's destroyed. Whenever a + :class:`Widget` or other entity that requires a parent/master widget + is created, and that parent is not specified, the default root is used. + If the default root is not set, such a call will fail. + + +.. class:: Variable(master=None, value=None, name=None) + + Represent a Tcl global variable bound to *master* widget's value via the + `textVariable option + `_. + + *master* is the widget to bind the variable to. + *value* is an optional initial value + +StringVar +IntVar +DoubleVar +BooleanVar +mainloop +getint +getdouble +getboolean +Misc +CallWrapper +XView +YView +Wm +Tk +Tcl +Pack +Place +Grid +BaseWidget +Widget +Toplevel +Button +Canvas +Checkbutton +Entry +Frame +Label +Listbox +Menu +Menubutton +Message +Radiobutton +Scale +Scrollbar +Text +OptionMenu +Image +PhotoImage +BitmapImage +image_names +image_types +Spinbox +LabelFrame +PanedWindow + +.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1) + + The :class:`Tk` class encapsulates 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: + + Other modules that provide Tk support include: From 6cdcb9e2858ab8b2417ebcd771dd0ef9361b8878 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Fri, 25 May 2018 12:14:39 +0300 Subject: [PATCH 08/24] * queue is per-thread --- Doc/library/tkinter.rst | 52 ++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 06ae6fb821641a..3b9cf9c0412881 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -21,7 +21,7 @@ installed, so you can read the Tcl/Tk documentation specific to that version. Tkinter supports a range of Tcl/Tk versions, built either with or without thread support. The official Python binary release bundles Tcl/Tk 8.6 -threaded. See the source code for the underlying :mode:`_tkinter` C module +threaded. See the source code for the :mode:`_tkinter` module for more information about supported versions. Tkinter is not a thin wrapper, it adds a fair amount of own logic to @@ -35,7 +35,7 @@ Architecture Unlike most other GUI toolkits, Tcl/Tk is not a monolithic product providing a consolidated API. Instead, it's a bundle of libraries, each with its -separate functionality and documentation. +distinct functionality and separate documentation. Tcl Tcl is a dynamic interpreted programming language. Though it can be used @@ -44,10 +44,11 @@ Tcl an interface to the Tk toolkit. The Tcl engine library has a C interface to create and operate interpreter instances, run Tcl commands and scripts with them and add custom commands that can be implemented in either Tcl or C. - It also implements a per-interpreter event queue. Each :class:`Tk` object - embeds its own interpreter instance. Though :mod:`_tkinter` allows to - execute entire Tcl scripts, the Python bindings typically only run single - commands. + It also implements a per-thread event queue (see `Threading model`_ for + details). + Each :class:`Tk` object embeds its own interpreter instance. + Though :mod:`_tkinter` allows to execute entire Tcl scripts, the Python + bindings typically only run single commands. Tk Tk is a Tcl module implemented in C that adds custom commands to create and @@ -62,7 +63,7 @@ Tk `tkinter` mostly uses the latter. Tix - `Tix` is a + `Tix`_ is a third-party Tcl module, an addon for Tk that adds several new widgets. `tkinter.tix` provides bindings for it, and official Python binary releases come with it bundled. It's deprecated in favor of Ttk. @@ -71,8 +72,8 @@ Tix Tkinter Modules ^^^^^^^^^^^^^^^ -:mod:`tkinter` has the core functionality and the regular Tk widgets. -Unless you're using the additional widgets, this will be all +:mod:`tkinter` has the core functionality and the bindings for regular Tk +widgets. Unless you're using the additional widgets, this will be all that you really need. :mod:`tkinter.ttk` and :mod:`tkinter.tix` have classes for extra @@ -80,23 +81,12 @@ widgets from those families. Ttk is intended to be the new standard widget set with a more modern look, but as of this writing, it doesn't yet have replacements for all the classical widgets. -The Tk interface is located in a C module named :mod:`_tkinter`. +The core Tcl/Tk interface is located in a C module named :mod:`_tkinter`. This module directly interfaces with Tcl/Tk via their C interfaces and shouldn't be used directly by application programmers save for a few functions. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter. -In addition to the Tk interface module, :mod:`tkinter` includes a number of -Python modules, :mod:`tkinter.constants` being one of the most important. -Importing :mod:`tkinter` will automatically import :mod:`tkinter.constants`, -so, usually, to use Tkinter all you need is a simple import statement:: - - import tkinter - -Or, more often:: - - from tkinter import * - Threading model --------------- @@ -118,7 +108,7 @@ predefined "event handler". Likewise, for any lengthy tasks, the UI thread can launch worker threads that report back on their progress via the same event queue. -Tkinter strives to provide the best of both worlds. The "moderm" multithreaded +Tkinter strives to provide the best of both worlds. The "modern" multithreaded GUI model is the primary mode of execution, but pumping messages manually instead is also supported. What is more important, any Tkinter calls can be made from any Python threads, only subject to Tcl's architectural restictions: @@ -141,7 +131,21 @@ made from any Python threads, only subject to Tcl's architectural restictions: * A few select functions can only be called from the interpreter thread. - +Tcl event queue is per-thread rather than per-interpreter. For nonthreaded Tcl, +there's only one global queue shared by all interpreters; for threaded Tcl, +one queue per OS thread that's shared by all interpreters bound to that thread. +So, when an event processing function like :func:`Tk.mainloop` is called, it +will process events not only for the calling :class:`Tk` instance +but for all whose interpreters share the queue. +Events handlers will be called within the same Tcl interpreter that they were +bound to as per the `bind `_ man +page, but any exceptions will be raised from the event processing function. +There's no harm in calling :func:`mainloop` for two :class:`Tk`s at the same +time: with nonthreaded Tcl, they will take turns handling events, and with +threaded Tcl, this is only allowed if the :class:`Tk`s are associated with +different threads anyway. + + Module contents --------------- @@ -218,7 +222,7 @@ Module contents .. class:: Variable(master=None, value=None, name=None) - Represent a Tcl global variable bound to *master* widget's value via the + Represents a Tcl global variable bound to *master* widget's value via the `textVariable option `_. From 35521e84721c808d5d59960a9ca0801779ca617d Mon Sep 17 00:00:00 2001 From: Mark Roseman Date: Wed, 30 May 2018 09:51:19 -0700 Subject: [PATCH 09/24] update Tcl/Tk resource URLs and verbiage --- Doc/library/tkinter.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 3b9cf9c0412881..f065a34008b951 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -1058,7 +1058,7 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``. Book by Mark Lutz, has excellent coverage of Tkinter. `Modern Tkinter for Busy Python Developers `_ - Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter. + Book by Mark Roseman about building attractive and modern graphical user interfaces with Python and Tkinter. `Python and Tkinter Programming `_ Book by John Grayson (ISBN 1-884777-81-3). @@ -1070,12 +1070,12 @@ use raw reads or ``os.read(file.fileno(), maxbytecount)``. Change '8.6' to match the version of your Tcl/Tk installation. `Tcl/Tk recent man pages `_ - Recent Tcl/Tk manuals on www.tcl.tk. + Recent Tcl/Tk manuals on www.tcl.tk, which also hosts core development. - `ActiveState Tcl Home Page `_ - The Tk/Tcl development is largely taking place at ActiveState. + `ActiveState Tcl Home Page `_ + Precompiled binaries of current versions of Tcl/Tk. - `Tcl and the Tk Toolkit `_ + `Tcl and the Tk Toolkit `_ Book by John Ousterhout, the inventor of Tcl. `Practical Programming in Tcl and Tk `_ From 77c674b374e550e07564f243783843a42433b518 Mon Sep 17 00:00:00 2001 From: Mark Roseman Date: Wed, 30 May 2018 11:52:48 -0700 Subject: [PATCH 10/24] small rewording/reorganization of architecture and modules sections --- Doc/library/tkinter.rst | 84 +++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 45 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index f065a34008b951..64ff943f8e4da8 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -12,7 +12,7 @@ The :mod:`tkinter` package ("Tk interface") is the standard Python interface to the Tcl/Tk GUI toolkit. Tcl/Tk and :mod:`tkinter` are available on most Unix -platforms, as well as on Windows systems. +platforms (including macOS), as well as on Windows systems. Running ``python -m tkinter`` from the command line should open a window demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is @@ -24,68 +24,62 @@ without thread support. The official Python binary release bundles Tcl/Tk 8.6 threaded. See the source code for the :mode:`_tkinter` module for more information about supported versions. -Tkinter is not a thin wrapper, it adds a fair amount of own logic to -make the experience more pythonic. This documentation will concentrate on this -added and changed logic and refer to the official Tcl/Tk documentation for -details that are unchanged. +Tkinter is not a thin wrapper, but adds a fair amount of its own logic to +make the experience more pythonic. This documentation will concentrate on these +additions and changes, and refer to the official Tcl/Tk documentation for +descriptions of underlying features. Architecture ------------ -Unlike most other GUI toolkits, Tcl/Tk is not a monolithic product providing a -consolidated API. Instead, it's a bundle of libraries, each with its -distinct functionality and separate documentation. +Tkinter provides a unified interface to several separate and distinct libraries. Tcl - Tcl is a dynamic interpreted programming language. Though it can be used - as a general-purpose programming language, it's primary developed to be and - used as an embedded scripting engine for applications (same as Lua) and as - an interface to the Tk toolkit. The Tcl engine library has a C interface to - create and operate interpreter instances, run Tcl commands and scripts with - them and add custom commands that can be implemented in either Tcl or C. - It also implements a per-thread event queue (see `Threading model`_ for - details). - Each :class:`Tk` object embeds its own interpreter instance. - Though :mod:`_tkinter` allows to execute entire Tcl scripts, the Python - bindings typically only run single commands. + Like Python, Tcl is a dynamic interpreted programming language. It is most + commonly used by C applications to embed a scripting language, or as an + interface to the Tk toolkit. The Tcl library has a C interface to + create and manage one or more instances of a Tcl interpreter, run Tcl + commands and scripts in those instances, and add custom commands + implemented in either Tcl or C. Each interpreter instance also provides + an event queue, used for I/O, timers, and by modules. Tk - Tk is a Tcl module implemented in C that adds custom commands to create and - manipulate GUI widgets. The interpreter's event queue is used to generate - and process events for all widgets created by it. - Tcl can be used without Tk (and Tk needs to be explicitly loaded to make it - available; :mod:`tkinter` does this automatically), though they are - typically provided together, "Tcl/Tk" being the name for the bundle. - Tk also implements the Themed Tk (Ttk) family of widgets, though `tkinter` - provides Python bindings for them in a separate module, :mod:`tkinter.ttk`. - Tk has its own C interface that duplicates the custom Tcl commands though - `tkinter` mostly uses the latter. + Tk is a module that can be loaded into a Tcl interpreter instance. It adds + Tcl commands (implemented in C) to create and manipulate GUI widgets. Each + :class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into + it. Tk's widgets are very customizable, though at the cost of a dated appearance. + Tk uses the interpreter's event queue to generate and process GUI events. Note + that unlike some GUI libraries, each interpreter uses only a single thread, + which has implications for :mod:`tkinter` users (see `Threading model`_). + +Ttk + Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better + appearance on different platforms than many of the classic Tk widgets. + Ttk is distributed as part of Tk, starting with Tk version 8.5. Python + bindings are provided in a separate module, :mod:`tkinter.ttk`. Tix - `Tix`_ is a - third-party Tcl module, an addon for Tk that adds several new widgets. - `tkinter.tix` provides bindings for it, and official Python binary releases - come with it bundled. It's deprecated in favor of Ttk. + `Tix`_ is an older + third-party Tcl module, adding several new widgets to Tk. Python bindings + are found in :mod:`tkinter.tix`. It has been deprecated in favor of Ttk. Tkinter Modules ^^^^^^^^^^^^^^^ -:mod:`tkinter` has the core functionality and the bindings for regular Tk -widgets. Unless you're using the additional widgets, this will be all -that you really need. +Most applications will directly use the features provided by :mod:`tkinter`. +Unless compatibility with very old versions of Tcl/Tk is required, Ttk widgets +found in :mod:`tkinter.ttk` should also be favoured over their classic Tk +counterparts. -:mod:`tkinter.ttk` and :mod:`tkinter.tix` have classes for extra -widgets from those families. Ttk is intended to be the new standard widget -set with a more modern look, but as of this writing, it doesn't yet have -replacements for all the classical widgets. +The :mod:`_tkinter` module provides low-level access to Tcl interpreters in Python, +using the C interface to the Tcl library. It should rarely be used directly by +application programmers. It may be needed to access features in very new versions +of Tcl/Tk without an existing Python binding, though this reduces compatibility. +It is usually a shared library (or DLL) but may be statically linked with the +Python interpreter. -The core Tcl/Tk interface is located in a C module named :mod:`_tkinter`. -This module directly interfaces with Tcl/Tk via their C interfaces and -shouldn't be used directly by application programmers save for a few functions. -It is usually a shared library (or DLL), but might in some cases be statically -linked with the Python interpreter. Threading model From 61c23d2706371aeb429e40335c59035eff961733 Mon Sep 17 00:00:00 2001 From: Mark Roseman Date: Wed, 30 May 2018 13:29:08 -0700 Subject: [PATCH 11/24] rewrite threading model section to separate normal use from potential traps --- Doc/library/tkinter.rst | 107 +++++++++++++++++++--------------------- 1 file changed, 51 insertions(+), 56 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 64ff943f8e4da8..2cc48d5c8e8406 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -41,15 +41,15 @@ Tcl interface to the Tk toolkit. The Tcl library has a C interface to create and manage one or more instances of a Tcl interpreter, run Tcl commands and scripts in those instances, and add custom commands - implemented in either Tcl or C. Each interpreter instance also provides - an event queue, used for I/O, timers, and by modules. + implemented in either Tcl or C. Tcl provides for an event queue, used + for I/O, timers, and by modules. Tk Tk is a module that can be loaded into a Tcl interpreter instance. It adds Tcl commands (implemented in C) to create and manipulate GUI widgets. Each :class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into it. Tk's widgets are very customizable, though at the cost of a dated appearance. - Tk uses the interpreter's event queue to generate and process GUI events. Note + Tk uses Tcl's event queue to generate and process GUI events. Note that unlike some GUI libraries, each interpreter uses only a single thread, which has implications for :mod:`tkinter` users (see `Threading model`_). @@ -85,59 +85,54 @@ Python interpreter. Threading model --------------- -A Tcl interpreter has one stream of execution and, unlike most other GUI -toolkits, doesn't provide a blocking event loop. -Instead, Tcl code is supposed to pump the event queue regularly at strategic -moments -- after an action that triggers an event, before a later action that -needs the result of that event. As such, all Tcl commands are designed to work -without an event loop running -- only event handlers will not be executed -until the queue is processed. This allows to work completely in one thread, -i.e. even in environments that have no thread support at all. - -This is in stark constrast to the execution model for most other GUI toolkits: -a dedicated OS thread (usually called the "UI thread") runs the GUI event loop -constantly, and other threads send work items to it -- either complete with -payload reference, or as agreed-upon "events" which result in it executing a -predefined "event handler". -Likewise, for any lengthy tasks, the UI thread can launch worker threads that -report back on their progress via the same event queue. - -Tkinter strives to provide the best of both worlds. The "modern" multithreaded -GUI model is the primary mode of execution, but pumping messages manually -instead is also supported. What is more important, any Tkinter calls can be -made from any Python threads, only subject to Tcl's architectural restictions: - -* A nonthreaded Tcl doesn't know anything about threads, so all Tcl calls are - wrapped with a global lock to enforce sequential access. - Any Tkinter calls can be made from any threads, but under the hood, only one - is active at any moment. - -* A threaded Tcl interpreter instance, when created, becomes tied to the - creating OS thread ("the interpreter thread"). Tcl mandates that all calls - to the instance must come from this thread, save for special inter-thread - communication APIs. Tkinter implements calls from outside the interpreter - thread by posting an event to the interpreter's queue, then waits for the - result of its processing. As such: - - * To make calls from outside the interpreter queue, :func:`mainloop` - must be running in the interpreter queue. Otherwise, a - :class:`RuntimeError` is raised. - - * A few select functions can only be called from the interpreter thread. - -Tcl event queue is per-thread rather than per-interpreter. For nonthreaded Tcl, -there's only one global queue shared by all interpreters; for threaded Tcl, -one queue per OS thread that's shared by all interpreters bound to that thread. -So, when an event processing function like :func:`Tk.mainloop` is called, it -will process events not only for the calling :class:`Tk` instance -but for all whose interpreters share the queue. -Events handlers will be called within the same Tcl interpreter that they were -bound to as per the `bind `_ man -page, but any exceptions will be raised from the event processing function. -There's no harm in calling :func:`mainloop` for two :class:`Tk`s at the same -time: with nonthreaded Tcl, they will take turns handling events, and with -threaded Tcl, this is only allowed if the :class:`Tk`s are associated with -different threads anyway. +Python and Tcl/Tk have very different threading models, which :mod:`tkinter` +tries to bridge. If you use threads, you may need to be aware of this. + +A Python interpreter may have many threads associated with it. In Tcl, multiple +threads can be created, but each thread has a separate Tcl interpreter instance +associated with it. Threads can also create more than one interpreter instance, +though each interpreter instance can be used only by the one thread that created it. + +Each :class:`Tk` object created by :mod:`tkinter` contains a Tcl interpreter. +It also keeps track of which thread created that interpreter. Calls to +:mod:`tkinter` can be made from any Python thread. Internally, if a call comes +from a thread other than the one that created the :class:`Tk` object, an event +is posted to the interpreter's event queue, and when executed, the result is +returned to the calling Python thread. + +Tcl/Tk applications are normally event-driven, meaning that after initialization, +the interpreter runs an event loop (i.e. :func:`Tk.mainloop`) and responds to events. +Because it is single-threaded, event handlers must respond quickly, otherwise they +will block other events from being processed. To avoid this, any long-running +computations should not run in an event handler, but are either broken into smaller +pieces using timers, or run in another thread. This is different from many GUI +toolkits where the GUI runs in a completely separate thread from all application +code including event handlers. + +If the Tcl interpreter is not running the event loop and processing events, any +:mod:`tkinter` calls made from threads other than the one running the Tcl +interpreter will fail. + +A number of special cases exist: + + * Tcl/Tk libraries can be built so they are not thread-aware. In this case, + :mod:`tkinter` calls the library from the originating Python thread, even + if this is different than the thread that created the Tcl interpreter. A global + lock ensures only one call occurs at a time. + + * While :mod:`tkinter` allows you to create more than one instance of a :class:`Tk` + object (with it's own interpreter), all interpreters that are part of the same + thread share a common event queue, which gets ugly fast. In practice, don't create + more than one instance of :class:`Tk` at a time. Otherwise, it's best to create + them in separate threads and ensure you're running a thread-aware Tcl/Tk build. + + * Blocking event handlers are not the only way to prevent the Tcl interpreter from + reentering the event loop. It is even possible to run multiple nested event loops + or abandon the event loop entirely. If you're doing anything tricky when it comes + to events or threads, be aware of these possibilities. + + * There are a few select :mod:`tkinter` functions that presently work only when + called from the thread that created the Tcl interpreter. Module contents From 5a80739b17578925aec58305cde7e208cc58358f Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 04:09:54 +0300 Subject: [PATCH 12/24] https://github.com/python/cpython/pull/7287#discussion_r192545213 --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..b136dc9becf771 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -12,7 +12,7 @@ The :mod:`tkinter` package ("Tk interface") is the standard Python interface to the Tcl/Tk GUI toolkit. Tcl/Tk and :mod:`tkinter` are available on most Unix -platforms (including macOS), as well as on Windows systems. +platforms, including macOS, as well as on Windows systems. Running ``python -m tkinter`` from the command line should open a window demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is From 77b711eeb9c5332d039b68e411c9304f8ea081d7 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 04:24:50 +0300 Subject: [PATCH 13/24] https://github.com/python/cpython/pull/7287#discussion_r192545445 --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..34d6d9cd9eb776 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -27,7 +27,7 @@ for more information about supported versions. Tkinter is not a thin wrapper, but adds a fair amount of its own logic to make the experience more pythonic. This documentation will concentrate on these additions and changes, and refer to the official Tcl/Tk documentation for -descriptions of underlying features. +details that are unchanged. Architecture From c11080ddb97152c940353d0f32f4b205190fd9c0 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 04:40:38 +0300 Subject: [PATCH 14/24] https://github.com/python/cpython/pull/7287#discussion_r192545697 --- Doc/library/tkinter.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..be20a6dd9290f1 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -33,7 +33,9 @@ descriptions of underlying features. Architecture ------------ -Tkinter provides a unified interface to several separate and distinct libraries. +Tcl/Tk is not a single library but rather consists of a few distinct + modules, each with a separate functionality and its own official +documentation. Tcl Like Python, Tcl is a dynamic interpreted programming language. It is most From d270dab16f58cffdadc72beaa22bd8a1d886e46c Mon Sep 17 00:00:00 2001 From: native-api Date: Sun, 3 Jun 2018 05:03:28 +0300 Subject: [PATCH 15/24] mention Tix as it adds more complexity to the architecture --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index be20a6dd9290f1..c39844114346ad 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -35,7 +35,7 @@ Architecture Tcl/Tk is not a single library but rather consists of a few distinct modules, each with a separate functionality and its own official -documentation. +documentation. Python binary release also ships an add-on module with it. Tcl Like Python, Tcl is a dynamic interpreted programming language. It is most From 0bd73e2799ef17505b6132b5a1a36f8ca6c46506 Mon Sep 17 00:00:00 2001 From: native-api Date: Sun, 3 Jun 2018 05:05:53 +0300 Subject: [PATCH 16/24] spec --- Doc/library/tkinter.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index c39844114346ad..369b3552f298d9 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -35,7 +35,8 @@ Architecture Tcl/Tk is not a single library but rather consists of a few distinct modules, each with a separate functionality and its own official -documentation. Python binary release also ships an add-on module with it. +documentation. Python binary release also ships an add-on module +together with it. Tcl Like Python, Tcl is a dynamic interpreted programming language. It is most From e8d124aad8ed940d6573e4486b3e16752e30efd0 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 05:46:08 +0300 Subject: [PATCH 17/24] https://github.com/python/cpython/pull/7287#discussion_r192545744 --- Doc/library/tkinter.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..ab4e378e975fd0 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -36,8 +36,9 @@ Architecture Tkinter provides a unified interface to several separate and distinct libraries. Tcl - Like Python, Tcl is a dynamic interpreted programming language. It is most - commonly used by C applications to embed a scripting language, or as an + Tcl is a dynamic interpreted programming language, just like Python. Though + it can be used on its own as a general-purpose programming language, it is + most commonly embedded into C applications as a scripting engine or an interface to the Tk toolkit. The Tcl library has a C interface to create and manage one or more instances of a Tcl interpreter, run Tcl commands and scripts in those instances, and add custom commands From 0961c387cbae23e8a2e7a39d7b1c75e6b6507462 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 09:40:42 +0300 Subject: [PATCH 18/24] https://github.com/python/cpython/pull/7287#discussion_r192545829 --- Doc/library/tkinter.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..174dc2fd280f6e 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -41,8 +41,10 @@ Tcl interface to the Tk toolkit. The Tcl library has a C interface to create and manage one or more instances of a Tcl interpreter, run Tcl commands and scripts in those instances, and add custom commands - implemented in either Tcl or C. Tcl provides for an event queue, used - for I/O, timers, and by modules. + implemented in either Tcl or C. Each interpreter has an event queue, + and there are facilities to send events to it and process them. + Unlike Python, a Tcl interpreter instance only has one + stream of execution (see `Threading model`_ for details). Tk Tk is a module that can be loaded into a Tcl interpreter instance. It adds From f91ff5d711d6b1800a30e87057ae64d92faed152 Mon Sep 17 00:00:00 2001 From: native-api Date: Sun, 3 Jun 2018 09:59:47 +0300 Subject: [PATCH 19/24] more specific --- Doc/library/tkinter.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 174dc2fd280f6e..2300f196214a24 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -43,8 +43,9 @@ Tcl commands and scripts in those instances, and add custom commands implemented in either Tcl or C. Each interpreter has an event queue, and there are facilities to send events to it and process them. - Unlike Python, a Tcl interpreter instance only has one - stream of execution (see `Threading model`_ for details). + Unlike Python, Tcl's execution model is designed around cooperative + multitasking, and Tkinter bridges this difference + (see `Threading model`_ for details). Tk Tk is a module that can be loaded into a Tcl interpreter instance. It adds From 4b9152e52d64f30296877c1f02cee7f55fc3f271 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 10:26:50 +0300 Subject: [PATCH 20/24] https://github.com/python/cpython/pull/7287#discussion_r192545899 https://github.com/python/cpython/pull/7287#discussion_r192545929 --- Doc/library/tkinter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..217a7ca3e339f0 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -45,8 +45,8 @@ Tcl for I/O, timers, and by modules. Tk - Tk is a module that can be loaded into a Tcl interpreter instance. It adds - Tcl commands (implemented in C) to create and manipulate GUI widgets. Each + Tk is a `Tcl package `_ implemented in C + that adds custom commands to create and manipulate GUI widgets. Each :class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into it. Tk's widgets are very customizable, though at the cost of a dated appearance. Tk uses Tcl's event queue to generate and process GUI events. Note From 7281922795fc83683036ec02198dc7925985c381 Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 10:50:12 +0300 Subject: [PATCH 21/24] https://github.com/python/cpython/pull/7287#discussion_r192545996 --- Doc/library/tkinter.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..bae42ca6f4cdfc 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -49,9 +49,7 @@ Tk Tcl commands (implemented in C) to create and manipulate GUI widgets. Each :class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into it. Tk's widgets are very customizable, though at the cost of a dated appearance. - Tk uses Tcl's event queue to generate and process GUI events. Note - that unlike some GUI libraries, each interpreter uses only a single thread, - which has implications for :mod:`tkinter` users (see `Threading model`_). + Tk uses Tcl's event queue to generate and process GUI events. Ttk Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better From 7fdbef3644c910fdef0997f61ddfcafbf3594a9d Mon Sep 17 00:00:00 2001 From: Ivan Pozdeev Date: Sun, 3 Jun 2018 14:35:14 +0300 Subject: [PATCH 22/24] https://github.com/python/cpython/pull/7287#discussion_r192546347 --- Doc/library/tkinter.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 2cc48d5c8e8406..028524e0d8a1ca 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -60,9 +60,10 @@ Ttk bindings are provided in a separate module, :mod:`tkinter.ttk`. Tix - `Tix`_ is an older - third-party Tcl module, adding several new widgets to Tk. Python bindings - are found in :mod:`tkinter.tix`. It has been deprecated in favor of Ttk. + `Tix`_ is a + third-party Tcl package, an add-on for Tk that adds several new widgets. + Python bindings are found in the :mod:`tkinter.tix` module. + It's deprecated in favor of Ttk. Tkinter Modules From 4f5218c98aceb038f05a370ce5a0fd72bceed3ba Mon Sep 17 00:00:00 2001 From: Mark Roseman Date: Sun, 3 Jun 2018 06:48:32 -0700 Subject: [PATCH 23/24] plural releases --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 369b3552f298d9..b519b79fd6d05b 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -35,7 +35,7 @@ Architecture Tcl/Tk is not a single library but rather consists of a few distinct modules, each with a separate functionality and its own official -documentation. Python binary release also ships an add-on module +documentation. Python's binary releases also ship an add-on module together with it. Tcl From 71a934d86e3742d5aa9e224bd3611e6b1a1d6f21 Mon Sep 17 00:00:00 2001 From: Mark Roseman Date: Sun, 3 Jun 2018 07:22:21 -0700 Subject: [PATCH 24/24] put back 'older' for tix Despite the "code does not rust", UI certainly does with respect to visual integration into modern applications. While an API may stay functional, if it says "gimme a Widget X" and what comes up is some ugly piece of crap that doesn't fit in with the rest of the UI, it's not meeting the programmer's expectations. I'd prefer a flashing 'warning' light, a phrase like 'virtually abandoned', etc. but I'd settle for 'older'. Something needs to be there. --- Doc/library/tkinter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 028524e0d8a1ca..61f0609a23d716 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -60,7 +60,7 @@ Ttk bindings are provided in a separate module, :mod:`tkinter.ttk`. Tix - `Tix`_ is a + `Tix`_ is an older third-party Tcl package, an add-on for Tk that adds several new widgets. Python bindings are found in the :mod:`tkinter.tix` module. It's deprecated in favor of Ttk.