Commit 9514c71

.. sectionauthor:: Matt Conway

Tkinter. Rather, it is intended as a stop gap, providing some introductory

orientation on the system.

Credits:

* Tk was written by John Ousterhout while at Berkeley.

* Tkinter was written by Steen Lumholt and Guido van Rossum.

* This Life Preserver was written by Matt Conway at the University of Virginia.

* The HTML rendering, and some liberal editing, was produced from a FrameMaker

version by Ken Manheimer.

* Fredrik Lundh elaborated and revised the class interface descriptions, to get

them current with Tk 4.2.

* Mike Clarkson converted the documentation to LaTeX, and compiled the User

Interface chapter of the reference manual.

How To Use This Section

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

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

documentation that exists. Here are some hints:

* The authors strongly suggest getting a copy of the Tk man pages.

Specifically, the man pages in the ``manN`` directory are most useful.

The ``man3`` man pages describe the C interface to the Tk library and thus

are not especially helpful for script writers.

* Addison-Wesley publishes a book called Tcl and the Tk Toolkit by John

Ousterhout (ISBN 0-201-63337-X) which is a good introduction to Tcl and Tk for

the novice. The book is not exhaustive, and for many details it defers to the

man pages.

* :file:`tkinter/__init__.py` is a last resort for most, but can be a good

place to go when nothing else makes sense.

A Simple Hello World Program

::

A (Very) Quick Look at Tcl/Tk

The class hierarchy looks complicated, but in actual practice, application

programmers almost always refer to the classes at the very bottom of the

hierarchy.

Notes:

* These classes are provided for the purposes of organizing certain functions

under one namespace. They aren't meant to be instantiated independently.

* The :class:`Tk` class is meant to be instantiated only once in an application.

Application programmers need not instantiate one explicitly, the system creates

one whenever any of the other classes are instantiated.

* The :class:`Widget` class is not meant to be instantiated, it is meant only

for subclassing to make "real" widgets (in C++, this is called an 'abstract

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.)

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*

that help configure it, and the *actions* that make it do useful things.

To make a widget in Tk, the command is always of the form::

*classCommand*

denotes which kind of widget to make (a button, a label, a menu...)

.. index:: single: . (dot); in Tkinter

*newPathname*

is the new name for this widget. All names in Tk must be unique. To help

enforce this, widgets in Tk are named with *pathnames*, just like files in a

file system. The top level widget, the *root*, is called ``.`` (period) and

children are delimited by more periods. For example,

``.myApp.controlPanel.okButton`` might be the name of a widget.

*options*

configure the widget's appearance and in some cases, its behavior. The options

come in the form of a list of flags and values. Flags are preceded by a '-',

like Unix shell command flags, and values are put in quotes if they are more

than one word.

For example::

Once created, the pathname to the widget becomes a new command. This new

*widget command* is the programmer's handle for getting the new widget to

perform some *action*. In C, you'd express this as someAction(fred,

someOptions), in C++, you would express this as fred.someAction(someOptions),

and in Tk, you say::

Note that the object name, ``.fred``, starts with a dot.

As you'd expect, the legal values for *someAction* will depend on the widget's

class: ``.fred disable`` works if fred is a button (fred gets greyed out), but

does not work if fred is a label (disabling of labels is not supported in Tk).

The legal values of *someOptions* is action dependent. Some actions, like

``disable``, require no arguments, others, like a text-entry box's ``delete``

command, would need arguments to specify what range of text to delete.

.. _tkinter-basic-mapping:

Mapping Basic Tk into Tkinter

Class commands in Tk correspond to class constructors in Tkinter. ::

The master of an object is implicit in the new name given to it at creation

The configuration options in Tk are given in lists of hyphened tags followed by

values. In Tkinter, options are specified as keyword-arguments in the instance

constructor, and keyword-args for configure calls or as instance indices, in

dictionary style, for established instances. See section

:ref:`tkinter-setting-options` on setting options. ::

In Tk, to perform an action on a widget, use the widget name as a command, and

follow it with an action name, possibly with arguments (options). In Tkinter,

you call methods on the class instance to invoke actions on the widget. The

actions (methods) that a given widget can perform are listed in

:file:`tkinter/__init__.py`. ::

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:`tkinter.tix` module documentation for additional

information on the Form geometry manager. ::