Index: Doc/library/idle.rst =================================================================== --- Doc/library/idle.rst (revision 63376) +++ Doc/library/idle.rst (working copy) @@ -10,11 +10,11 @@ single: Python Editor single: Integrated Development Environment -IDLE is the Python IDE built with the :mod:`Tkinter` GUI toolkit. +IDLE is the Python IDE built with the :mod:`tkinter` GUI toolkit. IDLE has the following features: -* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit +* coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit * cross-platform: works on Windows and Unix (on Mac OS, there are currently problems with Tcl/Tk) Index: Doc/library/tkinter.rst =================================================================== --- Doc/library/tkinter.rst (revision 63376) +++ Doc/library/tkinter.rst (working copy) @@ -1,16 +1,18 @@ -:mod:`Tkinter` --- Python interface to Tcl/Tk +:mod:`tkinter` --- Python interface to Tcl/Tk ============================================= -.. module:: Tkinter +.. module:: tkinter :synopsis: Interface to Tcl/Tk for graphical user interfaces .. moduleauthor:: Guido van Rossum -The :mod:`Tkinter` module ("Tk interface") is the standard Python interface to -the Tk GUI toolkit. Both Tk and :mod:`Tkinter` are available on most Unix +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 and Macintosh systems. (Tk itself is not part of Python; it is maintained at ActiveState.) +.. versionchanged:: 2.6 + ``tkinter`` is now a package, previously there was a ``Tkinter`` module. .. seealso:: @@ -34,23 +36,23 @@ Tkinter Modules --------------- -Most of the time, the :mod:`Tkinter` module is all you really need, but a number +Most of the time, the :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. The two most important modules are the :mod:`Tkinter` module -itself, and a module called :mod:`Tkconstants`. The former automatically imports -the latter, so to use Tkinter, all you need to do is to import one module:: +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 + import tkinter Or, more often:: - from Tkinter import * + from tkinter import * .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1) @@ -79,34 +81,60 @@ Other modules that provide Tk support include: -:mod:`ScrolledText` +:mod:`tkinter.scrolledtext` Text widget with a vertical scroll bar built in. -:mod:`tkColorChooser` + .. versionchanged:: 2.6 + Renamed from ``ScrolledText``. + +:mod:`tkinter.colorchooser` Dialog to let the user choose a color. -:mod:`tkCommonDialog` + .. versionchanged:: 2.6 + Renamed from ``tkColorChooser``. + +:mod:`commondialog` Base class for the dialogs defined in the other modules listed here. -:mod:`tkFileDialog` + .. versionchanged:: 2.6 + Renamed from ``tkCommonDialog``. + +:mod:`filedialog` Common dialogs to allow the user to specify a file to open or save. -:mod:`tkFont` + .. versionchanged:: 2.6 + Renamed from ``tkFileDialog``. + +:mod:`tkinter.font` Utilities to help work with fonts. -:mod:`tkMessageBox` + .. versionchanged:: 2.6 + Renamed from ``tkFont``. + +:mod:`tkinter.messagebox` Access to standard Tk dialog boxes. -:mod:`tkSimpleDialog` + .. versionchanged:: 2.6 + Renamed from ``tkMessageBox``. + +:mod:`tkinter.simpledialog` Basic dialogs and convenience functions. -:mod:`Tkdnd` - Drag-and-drop support for :mod:`Tkinter`. This is experimental and should become - deprecated when it is replaced with the Tk DND. + .. versionchanged:: 2.6 + Renamed from ``tkSimpleDialog``. -:mod:`turtle` +:mod:`tkinter.dnd` + Drag-and-drop support for :mod:`tkinter`. This is experimental and should + become deprecated when it is replaced with the Tk DND. + + .. versionchanged:: 2.6 + Renamed from ``Tkdnd``. + +:mod:`tkinter.turtle` Turtle graphics in a Tk window. + .. versionchanged:: 2.6 + Renamed from ``turtle``. Tkinter Life Preserver ---------------------- @@ -145,7 +173,7 @@ When trying to answer questions of the form "how do I do blah", it is often best to find out how to do"blah" in straight Tk, and then convert this back into the -corresponding :mod:`Tkinter` call. Python programmers can often guess at the +corresponding :mod:`tkinter` call. Python programmers can often guess at the correct Python command by looking at the Tk documentation. This means that in order to use Tkinter, you will have to know a little bit about Tk. This document can't fulfill that role, so the best we can do is point you to the best @@ -161,8 +189,8 @@ the novice. The book is not exhaustive, and for many details it defers to the man pages. -* :file:`Tkinter.py` is a last resort for most, but can be a good place to go - when nothing else makes sense. +* :file:`tkinter/__init__.py` is a last resort for most, but can be a good + place to go when nothing else makes sense. .. seealso:: @@ -182,7 +210,7 @@ :: - from Tkinter import * + from tkinter import * class Application(Frame): def say_hi(self): @@ -236,7 +264,7 @@ To make use of this reference material, there will be times when you will need to know how to read short passages of Tk and how to identify the various parts of a Tk command. (See section :ref:`tkinter-basic-mapping` for the -:mod:`Tkinter` equivalents of what's below.) +:mod:`tkinter` equivalents of what's below.) Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are just lists of tokens separated by spaces. A Tk widget is just its *class*, the *options* @@ -324,9 +352,9 @@ To give a widget to the packer (geometry manager), you call pack with optional arguments. In Tkinter, the Pack class holds all this functionality, and the various forms of the pack command are implemented as methods. All widgets in -:mod:`Tkinter` are subclassed from the Packer, and so inherit all the packing -methods. See the :mod:`Tix` module documentation for additional information on -the Form geometry manager. :: +:mod:`tkinter` are subclassed from the Packer, and so inherit all the packing +methods. See the :mod:`tkinter.tix` module documentation for additional +information on the Form geometry manager. :: pack .fred -side left =====> fred.pack(side = "left") @@ -337,11 +365,11 @@ From the top down: Your App Here (Python) - A Python application makes a :mod:`Tkinter` call. + A Python application makes a :mod:`tkinter` call. -Tkinter (Python Module) +tkinter (Python Package) This call (say, for example, creating a button widget), is implemented in the - *Tkinter* module, which is written in Python. This Python function will parse + *tkinter* package, which is written in Python. This Python function will parse the commands and the arguments and convert them into a form that makes them look as if they had come from a Tk script instead of a Python script. @@ -353,8 +381,8 @@ This C function is able to make calls into other C modules, including the C functions that make up the Tk library. Tk is implemented in C and some Tcl. The Tcl part of the Tk widgets is used to bind certain default behaviors to - widgets, and is executed once at the point where the Python :mod:`Tkinter` - module is imported. (The user never sees this stage). + widgets, and is executed once at the point where the Python :mod:`tkinter` + package is imported. (The user never sees this stage). Tk (C) The Tk part of the Tk Widgets implement the final mapping to ... @@ -510,11 +538,11 @@ ``value``. This connection works both ways: if the variable changes for any reason, the widget it's connected to will be updated to reflect the new value. -Unfortunately, in the current implementation of :mod:`Tkinter` it is not +Unfortunately, in the current implementation of :mod:`tkinter` it is not possible to hand over an arbitrary Python variable to a widget through a ``variable`` or ``textvariable`` option. The only kinds of variables for which this works are variables that are subclassed from a class called Variable, -defined in the :mod:`Tkinter` module. +defined in the :mod:`tkinter`. There are many useful subclasses of Variable already defined: :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and @@ -558,7 +586,7 @@ In Tk, there is a utility command, ``wm``, for interacting with the window manager. Options to the ``wm`` command allow you to control things like titles, -placement, icon bitmaps, and the like. In :mod:`Tkinter`, these commands have +placement, icon bitmaps, and the like. In :mod:`tkinter`, these commands have been implemented as methods on the :class:`Wm` class. Toplevel widgets are subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods directly. @@ -572,7 +600,7 @@ Here are some examples of typical usage:: - from Tkinter import * + from tkinter import * class App(Frame): def __init__(self, master=None): Frame.__init__(self, master) @@ -733,7 +761,7 @@ Entry widget indexes (index, view index, etc.) Entry widgets have options that refer to character positions in the text being - displayed. You can use these :mod:`Tkinter` functions to access these special + displayed. You can use these :mod:`tkinter` functions to access these special points in text widgets: AtEnd() @@ -785,7 +813,7 @@ ^^^^^^ Bitmap/Pixelmap images can be created through the subclasses of -:class:`Tkinter.Image`: +:class:`tkinter.Image`: * :class:`BitmapImage` can be used for X11 bitmap data. Index: Doc/library/tk.rst =================================================================== --- Doc/library/tk.rst (revision 63376) +++ Doc/library/tk.rst (working copy) @@ -12,19 +12,20 @@ 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` module, and its extension, the :mod:`Tix` module. +using the :mod:`tkinter` package, and its extension, the :mod:`tkinter.tix` +module. -The :mod:`Tkinter` module 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 +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 +: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 +: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, +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. @@ -32,9 +33,9 @@ .. toctree:: tkinter.rst - tix.rst - scrolledtext.rst - turtle.rst + tkinter.tix.rst + tkinter.scrolledtext.rst + tkinter.turtle.rst idle.rst othergui.rst Index: Doc/library/turtle.rst =================================================================== --- Doc/library/turtle.rst (revision 63376) +++ Doc/library/turtle.rst (working copy) @@ -1,8 +1,8 @@ -:mod:`turtle` --- Turtle graphics for Tk -======================================== +:mod:`tkinter.turtle` --- Turtle graphics for Tk +================================================ -.. module:: turtle +.. module:: tkinter.turtle :platform: Tk :synopsis: An environment for turtle graphics. .. moduleauthor:: Guido van Rossum @@ -11,14 +11,17 @@ .. sectionauthor:: Moshe Zadka -The :mod:`turtle` module provides turtle graphics primitives, in both an -object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for +The :mod:`tkinter.turtle` module provides turtle graphics primitives, in both an +object-oriented and procedure-oriented ways. Because it uses :mod:`tkinter` for the underlying graphics, it needs a version of python installed with Tk support. +.. versionchanged:: 2.6 + Renamed from ``turtle``. + The procedural interface uses a pen and a canvas which are automagically created when any of the functions are called. -The :mod:`turtle` module defines the following functions: +The :mod:`tkinter.turtle` module defines the following functions: .. function:: degrees() Index: Doc/library/scrolledtext.rst =================================================================== --- Doc/library/scrolledtext.rst (revision 63376) +++ Doc/library/scrolledtext.rst (working copy) @@ -1,18 +1,21 @@ -:mod:`ScrolledText` --- Scrolled Text Widget -============================================ +:mod:`tkinter.scrolledtext` --- Scrolled Text Widget +==================================================== -.. module:: ScrolledText +.. module:: tkinter.scrolledtext :platform: Tk :synopsis: Text widget with a vertical scroll bar. .. sectionauthor:: Fred L. Drake, Jr. -The :mod:`ScrolledText` module provides a class of the same name which +The :mod:`tkinter.scrolledtext` module provides a class of the same name which implements a basic text widget which has a vertical scroll bar configured to do the "right thing." Using the :class:`ScrolledText` class is a lot easier than setting up a text widget and scroll bar directly. The constructor is the same -as that of the :class:`Tkinter.Text` class. +as that of the :class:`tkinter.Text` class. +.. versionchanged:: 2.6 + Renamed from ``ScrolledText``. + The text widget and scrollbar are packed together in a :class:`Frame`, and the methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to Index: Doc/library/othergui.rst =================================================================== --- Doc/library/othergui.rst (revision 63376) +++ Doc/library/othergui.rst (working copy) @@ -3,13 +3,13 @@ Other Graphical User Interface Packages ======================================= -There are an number of extension widget sets to :mod:`Tkinter`. +There are an number of extension widget sets to :mod:`tkinter`. .. seealso:: `Python megawidgets `_ is a toolkit for building high-level compound widgets in Python using the - :mod:`Tkinter` module. It consists of a set of base classes and a library of + :mod:`tkinter` package. It consists of a set of base classes and a library of flexible and extensible megawidgets built on this foundation. These megawidgets include notebooks, comboboxes, selection widgets, paned widgets, scrolled widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the Index: Doc/library/tix.rst =================================================================== --- Doc/library/tix.rst (revision 63376) +++ Doc/library/tix.rst (working copy) @@ -1,20 +1,21 @@ -:mod:`Tix` --- Extension widgets for Tk -======================================= +:mod:`tkinter.tix` --- Extension widgets for Tk +=============================================== -.. module:: Tix +.. module:: tkinter.tix :synopsis: Tk Extension Widgets for Tkinter .. sectionauthor:: Mike Clarkson .. index:: single: Tix -The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set -of widgets. Although the standard Tk library has many useful widgets, they are -far from complete. The :mod:`Tix` library provides most of the commonly needed -widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, -:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. -:mod:`Tix` also includes many more widgets that are generally useful in a wide -range of applications: :class:`NoteBook`, :class:`FileEntry`, +The :mod:`tkinter.tix` (Tk Interface Extension) module provides an additional +rich set of widgets. Although the standard Tk library has many useful widgets, +they are far from complete. The :mod:`tkinter.tix` library provides most of the +commonly needed widgets that are missing from standard Tk: :class:`HList`, +:class:`ComboBox`, :class:`Control` (a.k.a. SpinBox) and an assortment of +scrollable widgets. +:mod:`tkinter.tix` also includes many more widgets that are generally useful in +a wide range of applications: :class:`NoteBook`, :class:`FileEntry`, :class:`PanedWindow`, etc; there are more than 40 of them. With all these new widgets, you can introduce new interaction techniques into @@ -22,6 +23,8 @@ design your application by choosing the most appropriate widgets to match the special needs of your application and users. +.. versionchanged:: 2.6 + Renamed from ``Tix``. .. seealso:: @@ -50,27 +53,27 @@ Toplevel widget of Tix which represents mostly the main window of an application. It has an associated Tcl interpreter. - Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` - module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all - you need to do is to import one module. In general, you can just import - :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with - :class:`Tix.Tk`:: + Classes in the :mod:`tkinter.tix` module subclasses the classes in the + :mod:`tkinter`. The former imports the latter, so to use :mod:`tkinter.tix` + with Tkinter, all you need to do is to import one module. In general, you + can just import :mod:`tkinter.tix`, and replace the toplevel call to + :class:`tkinter.Tk` with :class:`tix.Tk`:: - import Tix - from Tkconstants import * - root = Tix.Tk() + from tkinter import tix + from tkinter.constants import * + root = tix.Tk() -To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually +To use :mod:`tkinter.tix`, you must have the Tix widgets installed, usually alongside your installation of the Tk widgets. To test your installation, try the following:: - import Tix - root = Tix.Tk() + from tkinter import tix + root = tix.Tk() root.tk.eval('package require Tix') If this fails, you have a Tk installation problem which must be resolved before proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the -installed :mod:`Tix` library directory, and make sure you have the dynamic +installed Tix library directory, and make sure you have the dynamic object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same directory that contains your Tk dynamic object library (:file:`tk8183.dll` or :file:`libtk8183.so`). The directory with the dynamic object library should also @@ -85,8 +88,8 @@ `Tix `_ introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a -demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the -standard distribution. +demo of all the :mod:`tkinter.tix` widgets in the :file:`Demo/tix` directory of +the standard distribution. .. The Python sample code is still being added to Python, hence commented out @@ -434,11 +437,11 @@ Image Types ^^^^^^^^^^^ -The :mod:`Tix` module adds: +The :mod:`tkinter.tix` module adds: * `pixmap `_ - capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images - from XPM files. + capabilities to all :mod:`tkinter.tix` and :mod:`tkinter` widgets to create + color images from XPM files. .. Python Demo of: .. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} @@ -478,7 +481,7 @@ Form Geometry Manager ^^^^^^^^^^^^^^^^^^^^^ -In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: +In addition, :mod:`tkinter.tix` augments :mod:`tkinter` by providing: .. class:: Form()