Doc changes for the big Tkinter rename.

This commit is contained in:
Georg Brandl 2008-05-16 17:37:53 +00:00
parent cd174da82f
commit c21cd7e7ec
7 changed files with 156 additions and 92 deletions

View File

@ -10,11 +10,11 @@ IDLE
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)

View File

@ -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 <http://pmw.sourceforge.net/>`_
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

View File

@ -12,19 +12,20 @@ Graphical User Interfaces with 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` 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 @@ alternatives, see the :ref:`other-gui-packages` section.
.. toctree::
tkinter.rst
tix.rst
scrolledtext.rst
turtle.rst
tkinter.tix.rst
tkinter.scrolledtext.rst
tkinter.turtle.rst
idle.rst
othergui.rst

View File

@ -1,16 +1,26 @@
:mod:`Tkinter` --- Python interface to Tcl/Tk
:mod:`tkinter` --- Python interface to Tcl/Tk
=============================================
.. module:: Tkinter
:synopsis: Old name for the tkinter module.
.. module:: tkinter
:synopsis: Interface to Tcl/Tk for graphical user interfaces
.. moduleauthor:: Guido van Rossum <guido@Python.org>
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.)
.. note::
The :mod:`Tkinter` module has been renamed to a :mod:`tkinter` package in
Python 3.0. All other Tkinter-related modules have been moved to submodules
within that package (see their individual descriptions).
All modules are importable under both names in Python 2.6 and the rest of the
2.x series.
.. seealso::
@ -34,23 +44,23 @@ of Python; it is maintained at ActiveState.)
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,41 +89,67 @@ Or, more often::
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
----------------------
.. sectionauthor:: Matt Conway
This section is not designed to be an exhaustive tutorial on either Tk or
Tkinter. Rather, it is intended as a stop gap, providing some introductory
orientation on the system.
@ -145,7 +181,7 @@ handy reference.
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 +197,8 @@ documentation that exists. Here are some hints:
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 +218,7 @@ A Simple Hello World Program
::
from Tkinter import *
from tkinter import *
class Application(Frame):
def say_hi(self):
@ -236,7 +272,7 @@ Notes:
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 +360,9 @@ module. ::
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 +373,11 @@ How Tk and Tkinter are Related
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 +389,8 @@ Tk Widgets (C and Tcl)
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 +546,11 @@ options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and
``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 +594,7 @@ The Window Manager
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 +608,7 @@ part of the implementation, and not an interface to Tk functionality.
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 +769,7 @@ Entry widget, or to particular menu items in a Menu widget.
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 +821,7 @@ Images
^^^^^^
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.

View File

@ -1,17 +1,27 @@
:mod:`ScrolledText` --- Scrolled Text Widget
============================================
:mod:`tkinter.scrolledtext` --- Scrolled Text Widget
====================================================
.. module:: ScrolledText
:synopsis: Old name for the tkinter.scrolledtext module.
.. module:: tkinter.scrolledtext
:platform: Tk
:synopsis: Text widget with a vertical scroll bar.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. note::
The :mod:`ScrolledText` module has been renamed to
:mod:`tkinter.scrolledtext` in Python 3.0. It is importable under both names
in Python 2.6 and the rest of the 2.x series.
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

View File

@ -1,20 +1,28 @@
:mod:`Tix` --- Extension widgets for Tk
=======================================
:mod:`tkinter.tix` --- Extension widgets for Tk
===============================================
.. module:: Tix
:synopsis: Old name for the tkinter.tix module.
.. module:: tkinter.tix
:synopsis: Tk Extension Widgets for Tkinter
.. sectionauthor:: Mike Clarkson <mikeclarkson@users.sourceforge.net>
.. note::
The :mod:`Tix` module has been renamed to :mod:`tkinter.tix` in Python 3.0.
It is importable under both names in Python 2.6 and the rest of the 2.x
series.
.. 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,7 +30,6 @@ applications, creating more useful and more intuitive user interfaces. You can
design your application by choosing the most appropriate widgets to match the
special needs of your application and users.
.. seealso::
`Tix Homepage <http://tix.sourceforge.net/>`_
@ -50,27 +57,27 @@ Using Tix
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 +92,8 @@ Tix Widgets
`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_
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 +441,11 @@ Manager Widgets
Image Types
^^^^^^^^^^^
The :mod:`Tix` module adds:
The :mod:`tkinter.tix` module adds:
* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_
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 +485,7 @@ Miscellaneous Widgets
Form Geometry Manager
^^^^^^^^^^^^^^^^^^^^^
In addition, :mod:`Tix` augments :mod:`Tkinter` by providing:
In addition, :mod:`tkinter.tix` augments :mod:`tkinter` by providing:
.. class:: Form()

View File

@ -1,24 +1,34 @@
:mod:`turtle` --- Turtle graphics for Tk
========================================
:mod:`tkinter.turtle` --- Turtle graphics for Tk
================================================
.. module:: turtle
:synopsis: Old name for the tkinter.turtle module.
.. module:: tkinter.turtle
:platform: Tk
:synopsis: An environment for turtle graphics.
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. note::
The :mod:`turtle` module has been renamed to :mod:`tkinter.turtle` in Python
3.0. It is importable under both names in Python 2.6 and the rest of the 2.x
series.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
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()