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:: diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index d9c1c35aa294bd..29b4522d17a6fd 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -11,100 +11,273 @@ -------------- 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, 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 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: +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 :mode:`_tkinter` module +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 +details that are unchanged. + + +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's binary releases also ship an add-on module +together with it. + +Tcl + 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 + 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, Tcl's execution model is designed around cooperative + multitasking, and Tkinter bridges this difference + (see `Threading model`_ for details). + +Tk + 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. + +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 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. - `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. +Tkinter Modules +^^^^^^^^^^^^^^^ - `ActiveState Tcl Home Page `_ - The Tk/Tcl development is largely taking place at ActiveState. +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. - `Tcl and the Tk Toolkit `_ - Book by John Ousterhout, the inventor of Tcl. +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. - `Practical Programming in Tcl and Tk `_ - Brent Welch's encyclopedic book. -Tkinter Modules +Threading model --------------- -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. -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 +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 +--------------- -Or, more often:: - from tkinter import * +.. attribute:: TclVersion +.. attribute:: TkVersion + Tcl and Tk library versions used, as floating-point numbers + + +.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) + 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) + + Represents 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 is instantiated without arguments. This creates a toplevel + 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: -.. 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 - 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. Other modules that provide Tk support include: @@ -858,3 +1031,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 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). + + 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, which also hosts core development. + + `ActiveState Tcl Home Page `_ + Precompiled binaries of current versions of Tcl/Tk. + + `Tcl and the Tk Toolkit `_ + Book by John Ousterhout, the inventor of Tcl. + + `Practical Programming in Tcl and Tk `_ + Brent Welch's encyclopedic book. +