Tkinter chapter, contributed by Mike Clarkson. Based in part on the "Tkinter

Life Preserver" by Matt Conway.

1 files changed, 1674 insertions, 0 deletions

diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex
new file mode 100644
index 0000000..78c359d
--- /dev/null
+++ b/Doc/lib/tkinter.tex
@@ -0,0 +1,1674 @@
+\chapter{Graphical User Interface Modules \label{gui}}
+
+\index{GUI}
+\index{Graphical User Interface}
+\index{Tkinter}
+\index{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 \refmodule{Tkinter} module, and its
+extension, the \refmodule{Tix} module.
+
+\refmodule{Tkinter} is a thin object--oriented layer on top of
+Tcl/Tk. To use \refmodule{Tkinter}, you don't need to write Tcl code,
+but you will need to consult the Tk documentation, and occasionally
+the Tcl documentation.  \refmodule{Tkinter} is a set of wrappers that
+implement the Tk widgets as Python classes.  In addition, the internal
+module \module{\_tkinter} provides a threadsafe mechanism which allows
+Python and Tcl to interact.
+
+\refmodule{Tkinter} is not the only GUI for Python, but is however the
+most commonly used one; see section~\ref{other-gui-modules},
+``Other User Interface Modules and Packages'' for more information on
+other GUI toolkits for Python.
+
+% Other sections I have in mind are
+% Tkinter internals
+% Freezing Tkinter applications
+
+\localmoduletable
+
+
+\section{Tkinter \label{tkinter}}
+\index{Tkinter}
+\sectionauthor{Fredrik Lundh}{fredrik@effbot.org}
+
+\index{Tkinter}
+
+\declaremodule{standard}{Tkinter}
+\modulesynopsis{Interface to Tcl/Tk for graphical user interfaces}
+\moduleauthor{Guido van Rossum}{guido@Python.org}
+
+The \module{Tkinter} module (``Tk interface'') is the standard Python
+interface to the Tk GUI toolkit, now maintained at ActiveState.  Both
+Tk and \module{Tkinter} are available on most Unix platforms, as well
+as on Windows and Macintosh systems.
+
+\begin{seealso}
+\seetitle[http://www.python.org/topics/tkinter/]
+         {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.}
+
+\seetitle[http://www.pythonware.com/library/an-introduction-to-tkinter.htm]
+         {An Introduction to Tkinter}
+         {Fredrik Lundh's on-line reference material.}
+
+\seetitle[http://www.nmt.edu/tcc/help/pubs/lang.html]
+         {Tkinter reference: a GUI for Python}
+         {On-line reference material.}
+        
+\seetitle[http://jtkinter.sourceforge.net]
+         {Tkinter for JPython}
+         {The Jython interface to Tkinter.}
+
+\seetitle[http://www.amazon.com/exec/obidos/ASIN/1884777813]
+         {Python and Tkinter Programming}
+         {The book by John Grayson (ISBN 1-884777-81-3).}
+\end{seealso}
+
+
+\subsection{Tkinter Modules}
+
+\refmodule{Tkinter} consists of a number of modules. The Tk interface
+is located in a binary module named \module{_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, \refmodule{Tkinter} includes a
+number of Python modules. The two most important modules are the
+\refmodule{Tkinter} module itself, and a module called
+\module{Tkconstants}. The former automatically imports the latter, so
+to use Tkinter, all you need to do is to import one module:
+
+\begin{verbatim}
+import Tkinter
+\end{verbatim}
+
+Or, more often:
+
+\begin{verbatim}
+from Tkinter import *
+\end{verbatim}
+
+\begin{classdesc}{Tk}{screenName=None, baseName=None, className='Tk'}
+The \class{Tk} class is instantiated without arguments.
+This creates a toplevel widget of Tk which usually is the main window
+of an appliation. Each instance has its own associated Tcl interpreter.
+% FIXME: The following keyword arguments are currently recognized:
+\end{classdesc}
+
+Other modules that provide Tk support include:
+
+\begin{description}
+% \declaremodule{standard}{Tkconstants}
+% \modulesynopsis{Constants used by Tkinter}
+% FIXME 
+
+\item[\module{Tkdnd}]
+Drag-and-drop support for \refmodule{Tkinter}.
+This is experimental and should become deprecated when it is replaced 
+with the Tk DND.
+
+\item[\refmodule{turtle}]
+Turtle graphics in a Tk window.
+
+\end{description}
+
+\subsection{Tkinter Life Preserver}
+\index{Tkinter}
+
+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.
+
+Credits:
+\begin{itemize}
+\item   Tkinter was written by Steen Lumholt and Guido van Rossum.
+\item   Tk was written by John Ousterhout while at Berkeley.
+\item   This Life Preserver was written by Matt Conway at
+the University of Virginia.
+\item   The html rendering, and some liberal editing, was
+produced from a FrameMaker version by Ken Manheimer.
+\item   Fredrik Lundh elaborated and revised the class interface descriptions,
+to get them current with Tk 4.2.
+\item  Mike Clarkson converted the documentation to \LaTeX, and compiled the 
+User Interface chapter of the reference manual.
+\end{itemize}
+
+
+\subsubsection{How To Use This Section}
+
+This section is designed in two parts: the first half (roughly) covers
+background material, while the second half can be taken to the
+keyboard as a 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 \refmodule{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:
+
+\begin{itemize}
+\item   The authors strongly suggest getting a copy of the Tk man
+pages. Specifically, the man pages in the \code{mann} directory are most
+useful. The \code{man3} man pages describe the C interface to the Tk
+library and thus are not especially helpful for script writers.  
+
+\item   Addison-Wesley publishes a book called \citetitle{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. 
+
+\item   \file{Tkinter.py} is a last resort for most, but can be a good
+place to go when nothing else makes sense.  
+\end{itemize}
+
+\begin{seealso}
+\seetitle[http://tcl.activestate.com/]
+        {ActiveState Tcl Home Page}
+        {The Tk/Tcl development is largely taking place at
+         ActiveState.}
+\seetitle[http://www.amazon.com/exec/obidos/ASIN/020163337X]
+        {Tcl and the Tk Toolkit}
+        {The book by John Ousterhout, the inventor of Tcl .}
+\seetitle[http://www.amazon.com/exec/obidos/ASIN/0130220280]
+        {Practical Programming in Tcl and Tk}
+        {Brent Welch's encyclopedic book.}
+\end{seealso}
+
+
+\subsubsection{A Simple Hello World Program} % HelloWorld.html
+
+%begin{latexonly}
+%\begin{figure}[hbtp]
+%\centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}}
+%\vspace{.5cm}
+%\caption{HelloWorld gadget image}
+%\end{figure}
+%See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and
+%\ulink{summary}{classes/HelloWorld-summary.html}.
+%end{latexonly}
+
+
+\begin{verbatim}
+from Tkinter import *                                                    1
+                                                                         2
+class Application(Frame):                                                3
+    def say_hi(self):                                                    4
+        print "hi there, everyone!"                                      5
+                                                                         6
+    def createWidgets(self):                                             7
+        self.QUIT = Button(self)                                         8
+        self.QUIT["text"] = "QUIT"                                       9
+        self.QUIT["fg"]   = "red"                                       10
+        self.QUIT["command"] =  self.quit                               11
+                                                                        12
+        self.QUIT.pack({"side": "left"})                                13
+                                                                        14
+        self.hi_there = Button(self)                                    15
+        self.hi_there["text"] = "Hello",                                16
+        self.hi_there["command"] = self.say_hi                          17
+                                                                        18
+        self.hi_there.pack({"side": "left"})                            19
+                                                                        20
+                                                                        21
+    def __init__(self, master=None):                                    22
+        Frame.__init__(self, master)                                    23
+            self.pack()                                                 24
+        self.createWidgets()                                            25
+                                                                        26
+app = Application()                                                     27
+app.mainloop()                                                          28
+\end{verbatim}
+
+\ifhtml
+\subsection{An Overview of The Tkinter Classes} % TkClassHier.html
+
+%begin{latexonly}
+%\begin{figure}[hbtp]
+%\centerline{\epsfig{file=TkClassHier.gif,width=.9\textwidth}}
+%\caption{Class Hierarchy Image}
+%\end{figure}
+%end{latexonly}
+
+The class hierarchy looks complicated, but in actual practice,
+application programmers almost always refer to the classes at the very
+bottom of the hierarchy. 
+
+Here are links to the interfaces for each of the concrete widgets:
+
+\begin{itemize}
+\item   \citetitle[classes/ClassButton.html]{Button}  
+\item   \citetitle[classes/ClassCanvas.html]{Canvas} 
+\item   \citetitle[classes/ClassCheckbutton.html]{Checkbutton} 
+\item   \citetitle[classes/ClassEntry.html]{Entry} 
+\item   \citetitle[classes/ClassFrame.html]{Frame} 
+\item   \citetitle[classes/ClassLabel.html]{Label} 
+\item   \citetitle[classes/ClassListbox.html]{Listbox} 
+\item   \citetitle[classes/ClassMenu.html]{Menu} 
+\item   \citetitle[classes/ClassMenubutton.html]{Menubutton}  
+\item   \citetitle[classes/ClassMessage.html]{Message}  
+\item   \citetitle[classes/ClassMisc.html]{*Misc} 
+\item   \citetitle[classes/ClassPacker.html]{*Pack} 
+\item   \citetitle[classes/ClassPlacer.html]{*Place}  
+\item   \citetitle[classes/ClassRadiobutton.html]{Radiobutton}  
+\item   \citetitle[classes/ClassScale.html]{Scale}  
+\item   \citetitle[classes/ClassScrollbar.html]{Scrollbar} 
+\item   \citetitle[classes/ClassText.html]{Text} 
+\item   \citetitle[classes/ClassTk.html]{**Tk} 
+\item   \citetitle[classes/ClassToplevel.html]{Toplevel}  
+\item   \citetitle[classes/ClassWidget.html]{***Widget}  
+\item   \citetitle[classes/ClassWm.html]{*Wm} 
+\end{itemize}
+
+
+Notes:
+\begin{itemize}
+\item   These classes are provided for the purposes of
+organizing certain functions under one namespace. They aren't meant to
+be instantiated independently.
+\item    The 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.
+\item    The 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 class')
+\end{itemize}
+\fi
+
+
+\subsection{A (Very) Quick Look at Tcl/Tk} % BriefTclTk.html
+
+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 \ref{tkinter-basic-mapping} for the
+\refmodule{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
+\emph{class}, the \emph{options} that help configure it, and the
+\emph{actions} that make it do useful things. 
+
+To make a widget in Tk, the command is always of the form: 
+
+\begin{verbatim}
+                classCommand newPathname options
+\end{verbatim}
+
+\begin{description}
+\item[\var{classCommand}]
+denotes which kind of widget to make (a button, a label, a menu...)
+
+\item[\var{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 \emph{pathnames}, just
+like files in a file system.  The top level widget, the \emph{root},
+is called \code{.} (period) and children are delimited by more
+periods.  For example, \code{.myApp.controlPanel.okButton} might be
+the name of a widget.
+
+\item[\var{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 proceeded by a `-', like unix shell command flags, and
+values are put in quotes if they are more than one word.
+\end{description}
+
+For example: 
+
+\begin{verbatim}
+    button   .fred   -fg red -text "hi there"
+       ^       ^     \_____________________/
+       |       |                |
+     class    new            options
+    command  widget  (-opt val -opt val ...)
+\end{verbatim} 
+
+Once created, the pathname to the widget becomes a new command.  This
+new \var{widget command} is the programmer's handle for getting the new
+widget to perform some \var{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: 
+
+\begin{verbatim}
+    .fred someAction someOptions 
+\end{verbatim} 
+
+Note that the object name, \code{.fred}, starts with a dot.
+
+As you'd expect, the legal values for \var{someAction} will depend on
+the widget's class: \code{.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 \var{someOptions} is action dependent.  Some
+actions, like \code{disable}, require no arguments, others, like
+a text-entry box's \code{delete} command, would need arguments
+to specify what range of text to delete.  
+
+
+\subsection{Mapping Basic Tk into Tkinter
+            \label{tkinter-basic-mapping}}
+
+Class commands in Tk correspond to class constructors in Tkinter.
+
+\begin{verbatim}
+    button .fred                =====>  fred = Button()
+\end{verbatim}
+
+The master of an object is implicit in the new name given to it at
+creation time.  In Tkinter, masters are specified explicitly.
+
+\begin{verbatim}
+    button .panel.fred          =====>  fred = Button(panel)
+\end{verbatim}
+
+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 \ref{tkinter-setting-options}
+on setting options. 
+
+\begin{verbatim}
+    button .fred -fg red        =====>  fred = Button(panel, fg = "red")
+    .fred configure -fg red     =====>  fred["fg"] = red
+                                OR ==>  fred.config(fg = "red")
+\end{verbatim}
+
+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 the Tkinter.py module.
+
+\begin{verbatim}
+    .fred invoke                =====>  fred.invoke()
+\end{verbatim}
+
+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 \refmodule{Tkinter} are
+subclassed from the Packer, and so inherit all the packing
+methods. See the \refmodule{Tix} module documentation for additional
+information on the Form geometry manager.
+
+\begin{verbatim}
+    pack .fred -side left       =====>  fred.pack(side = "left")
+\end{verbatim}
+
+
+\subsection{How Tk and Tkinter are Related} % Relationship.html
+
+From the top down:
+\begin{description}
+\item[\b{Your App Here (Python)}]
+A Python application makes a \refmodule{Tkinter} call.
+
+\item[\b{Tkinter (Python Module)}]
+This call (say, for example, creating a button widget), is
+implemented in the \emph{Tkinter} module, 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.
+
+\item[\b{tkinter (C)}]
+These commands and their arguments will be passed to a C function
+in the \emph{tkinter} - note the lowercase - extension module.
+
+\item[\b{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 \refmodule{Tkinter} module is
+imported. (The user never sees this stage).
+
+\item[\b{Tk (C)}]
+The Tk part of the Tk Widgets implement the final mapping to ...
+
+\item[\b{Xlib (C)}]
+the Xlib library to draw graphics on the screen.
+\end{description}
+
+
+\subsection{Handy Reference}
+
+\subsubsection{Setting Options
+               \label{tkinter-setting-options}}
+
+Options control things like the color and border width of a widget.
+Options can be set in three ways:
+
+\begin{description}
+\item[At object creation time, using keyword arguments]:
+\begin{verbatim}
+fred = Button(self, fg = "red", bg = "blue")
+\end{verbatim}
+\item[After object creation, treating the option name like a dictionary index]:
+\begin{verbatim}
+fred["fg"] = "red"
+fred["bg"] = "blue"
+\end{verbatim}
+\item[Use the config() method to update multiple attrs subesequent to
+object creation]:
+\begin{verbatim}
+fred.config(fg = "red", bg = "blue")
+\end{verbatim}
+\end{description}
+
+For a complete explanation of a given option and its behavior, see the
+Tk man pages for the widget in question.
+
+Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC
+OPTIONS" for each widget.  The former is a list of options that are
+common to many widgets, the latter are the options that are
+ideosyncratic to that particular widget.  The Standard Options are
+documented on the \manpage{options}{3} man page.
+
+No distinction between standard and widget-specific options is made in
+this document.  Some options don't apply to some kinds of widgets.
+Whether a given widget responds to a particular option depends on the
+class of the widget; buttons have a \code{command} option, labels do not. 
+
+The options supported by a given widget are listed in that widget's
+man page, or can be queried at runtime by calling the
+\kbd{config()} method with arguments, or by calling the keys()
+method on that widget. The return value of these calls is a dictionary
+whose key is the name of the option (e.g. \kbd{relief}) and whose
+values are 5 tuples. 
+
+(Some options, like \kbd{bg} are synonyms for common options with
+hard-to-type names (\kbd{bg} is shorthand for "background"). 
+Passing the \kbd{config()} method the name of a
+shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple
+passed back will contain the name of the synonym ``real''
+option. (\kbd{bg}, \kbd{background}))
+
+\begin{tableiii}{c|l|l}{textrm}{Index}{Meaning}{Example}
+  \lineiii{0}{option name}                       {\code{'relief'}}
+  \lineiii{1}{option name for database lookup}   {\code{'relief'}}
+  \lineiii{2}{option class for database lookup}  {\code{'Relief'}}
+  \lineiii{3}{default value}                     {\code{'raised'}}
+  \lineiii{4}{current value}                     {\code{'groove'}}
+\end{tableiii}
+
+
+Example:
+
+\begin{verbatim}
+>>> print fred.config()
+{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
+\end{verbatim}
+
+Of course, the dictionary printed will include all the options
+available and their values.  This is meant only as an example.
+
+
+\subsubsection{The Packer} % Packer.html
+\index{packing (widgets)}
+
+The packer is one of Tk's geometry-management mechanisms.  See also
+\citetitle[classes/ClassPacker.html]{the Packer class interface}.
+
+Geometry managers are used to specify the relative positioning of the
+positioning of widgets within their container - their mutual
+\emph{master}.  In contrast to the more cumbersome \emph{placer}
+(which is used less commonly, and we do not cover here), the packer
+takes qualitative relationship specification - \emph{above}, \emph{to
+the left of}, \emph{filling}, etc - and works everything out to
+determine the exact placement coordinates for you. 
+
+The size of any \emph{master} widget is determined by the size of
+the "slave widgets" inside.  The packer is used to control where slave
+widgets appear inside the master into which they are packed.  You can
+pack widgets into frames, and frames into other frames, in order to
+achieve the kind of layout you desire.  Additionally, the arrangement
+is dynamically adjusted to accomodate incremental changes to the
+configuration, once it is packed.
+
+Note that widgets do not appear until they have had their geometry
+specified with a geometry manager.  It's a common early mistake to
+leave out the geometry specification, and then be surprised when the
+widget is created but nothing appears.  A widget will appear only
+after it has had, for example, the packer's \method{pack()} method
+applied to it.
+
+The pack() method can be called with keyword-option/value pairs that
+control where the widget is to appear within its container, and how it
+is to behave when the main application window is resized.  Here are
+some examples:
+
+\begin{verbatim}
+    fred.pack()                     # defaults to side = "top"
+    fred.pack(side = "left")
+    fred.pack(expand = 1)
+\end{verbatim}
+
+
+\subsubsection{Packer Options}
+
+For more extensive information on the packer and the options that it
+can take, see the man pages and page 183 of John Ousterhout's book.
+
+\begin{description}
+\item[\b{anchor }]
+Anchor type.  Denotes where the packer is to place each slave in its
+parcel.
+
+\item[\b{expand}]
+Boolean, \code{0} or \code{1}.
+
+\item[\b{fill}]
+Legal values: \code{'x'}, \code{'y'}, \code{'both'}, \code{'none'}.
+
+\item[\b{ipadx} and \b{ipady}]
+A distance - designating internal padding on each side of the slave
+widget.
+
+\item[\b{padx} and \b{pady}]
+A distance - designating external padding on each side of the slave
+widget.
+
+\item[\b{side}]
+Legal values are: \code{'left'}, \code{'right'}, \code{'top'},
+\code{'bottom'}.
+\end{description}
+
+
+\subsubsection{Coupling Widget Variables} % VarCouplings.html
+
+The current-value setting of some widgets (like text entry widgets)
+can be connected directly to application variables by using special
+options.  These options are \code{variable}, \code{textvariable},
+\code{onvalue}, \code{offvalue}, and \code{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 \refmodule{Tkinter} it is
+not possible to hand over an arbitrary Python variable to a widget
+through a \code{variable} or \code{textvariable} option.  The only
+kinds of variables for which this works are variables that are
+subclassed from a class called Variable, defined in the
+\refmodule{Tkinter} module.
+
+There are many useful subclasses of Variable already defined:
+\class{StringVar}, \class{IntVar}, \class{DoubleVar}, and
+\class{BooleanVar}.  To read the current value of such a variable,
+call the \method{get()} method on
+it, and to change its value you call the \method{set()} method.  If
+you follow this protocol, the widget will always track the value of
+the variable, with no further intervention on your part.
+
+For example: 
+\begin{verbatim}
+class App(Frame):
+    def __init__(self, master=None):
+        Frame.__init__(self, master)
+        self.pack()
+        
+        self.entrythingy = Entry()
+        self.entrythingy.pack()
+        
+        self.button.pack()
+        # here is the application variable
+        self.contents = StringVar()
+        # set it to some value
+        self.contents.set("this is a variable")
+        # tell the entry widget to watch this variable
+        self.entrythingy["textvariable"] = self.contents
+        
+        # and here we get a callback when the user hits return.
+        # we will have the program print out the value of the
+        # application variable when the user hits return
+        self.entrythingy.bind('<Key-Return>',
+                              self.print_contents)
+
+    def print_contents(self, event):
+        print "hi. contents of entry is now ---->", \
+              self.contents.get()
+\end{verbatim}
+
+
+\subsubsection{The Window Manager} % WindowMgr.html
+\index{window manager (widgets)}
+
+In Tk, there is a utility command, \code{wm}, for interacting with the
+window manager.  Options to the \code{wm} command allow you to control
+things like titles, placement, icon bitmaps, and the like.  In
+\refmodule{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.
+
+%See also \citetitle[classes/ClassWm.html]{the Wm class interface}.
+
+To get at the toplevel window that contains a given widget, you can
+often just refer to the widget's master.  Of course if the widget has
+been packed inside of a frame, the master won't represent a toplevel
+window.  To get at the toplevel window that contains an arbitrary
+widget, you can call the \method{_root()} method.  This
+method begins with an underscore to denote the fact that this function
+is part of the implementation, and not an interface to Tk functionality.
+
+Here are some examples of typical usage:
+
+\begin{verbatim}
+import Tkinter
+class App(Frame):
+    def __init__(self, master=None):
+        Frame.__init__(self, master)
+        self.pack()
+
+
+# create the application
+myapp = App()
+
+#
+# here are method calls to the window manager class
+#
+myapp.master.title("My Do-Nothing Application")
+myapp.master.maxsize(1000, 400)
+
+# start the program
+myapp.mainloop()
+\end{verbatim}
+
+
+\subsubsection{Tk Option Data Types} % OptionTypes.html
+
+\index{Tk Option Data Types}
+
+\begin{description}
+\item[anchor]
+Legal values are points of the compass: \code{"n"},
+\code{"ne"}, \code{"e"}, \code{"se"}, \code{"s"},
+\code{"sw"}, \code{"w"}, \code{"nw"}, and also
+\code{"center"}.
+
+\item[bitmap]
+There are eight built-in, named bitmaps: \code{'error'}, \code{'gray25'},
+\code{'gray50'}, \code{'hourglass'}, \code{'info'}, \code{'questhead'},
+\code{'question'}, \code{'warning'}.  To specify an X bitmap
+filename, give the full path to the file, preceded with an \code{@},
+as in \code{"@/usr/contrib/bitmap/gumby.bit"}.
+
+\item[boolean]
+You can pass integers 0 or 1 or the stings \code{"yes"} or \code{"no"} .
+
+\item[callback]
+This is any Python function that takes no arguments.  For example: 
+\begin{verbatim}
+    def print_it():
+            print "hi there"
+    fred["command"] = print_it
+\end{verbatim}
+
+\item[color]
+Colors can be given as the names of X colors in the rgb.txt file,
+or as strings representing RGB values in 4 bit: \code{"\#RGB"}, 8
+bit: \code{"\#RRGGBB"}, 12 bit" \code{"\#RRRGGGBBB"}, or 16 bit
+\code{"\#RRRRGGGGBBBB"} ranges, where R,G,B here represent any
+legal hex digit.  See page 160 of Ousterhout's book for details.  
+
+\item[cursor]
+The standard X cursor names from \file{cursorfont.h} can be used,
+without the \code{XC_} prefix.  For example to get a hand cursor
+(\constant{XC_hand2}), use the string \code{"hand2"}.  You can also
+specify a bitmap and mask file of your own.  See page 179 of
+Ousterhout's book.
+
+\item[distance]
+Screen distances can be specified in either pixels or absolute
+distances.  Pixels are given as numbers and absolute distances as
+strings, with the trailing character denoting units: \code{c}
+for centimeters, \code{i} for inches, \code{m} for millimeters,
+\code{p} for printer's points.  For example, 3.5 inches is expressed
+as \code{"3.5i"}.
+
+\item[font]
+Tk uses a list font name format, such as \code{\{courier 10 bold\}}.
+Font sizes with positive numbers are measured in points;
+sizes with negative numbers are measured in pixels.
+
+\item[geometry]
+This is a string of the form \samp{\var{width}x\var{height}}, where
+width and height are measured in pixels for most widgets (in
+characters for widgets displaying text).  For example:
+\code{fred["geometry"] = "200x100"}.
+
+\item[justify]
+Legal values are the strings: \code{"left"},
+\code{"center"}, \code{"right"}, and \code{"fill"}.
+
+\item[region]
+This is a string with four space-delimited elements, each of
+which is a legal distance (see above).  For example: \code{"2 3 4
+5"} and \code{"3i 2i 4.5i 2i"} and \code{"3c 2c 4c 10.43c"} 
+are all legal regions.
+
+\item[relief]
+Determines what the border style of a widget will be.  Legal
+values are: \code{"raised"}, \code{"sunken"},
+\code{"flat"}, \code{"groove"}, and \code{"ridge"}.
+
+\item[scrollcommand]
+This is almost always the \method{set()} method of some scrollbar
+widget, but can be any widget method that takes a single argument.  
+Refer to the file \file{Demo/tkinter/matt/canvas-with-scrollbars.py}
+in the Python source distribution for an example.
+
+\item[wrap:]
+Must be one of: \code{"none"}, \code{"char"}, or \code{"word"}.
+\end{description}
+
+
+\subsubsection{Bindings and Events} % Bindings.html
+
+\index{bind (widgets)}
+\index{events (widgets)}
+
+The bind method from the widget command allows you to watch for
+certain events and to have a callback function trigger when that event
+type occurs.  The form of the bind method is:
+
+\begin{verbatim}
+    def bind(self, sequence, func, add=''):
+\end{verbatim}
+where:
+
+\begin{description}
+\item[sequence]
+is a string that denotes the target kind of event.  (See the bind
+man page and page 201 of John Ousterhout's book for details).
+
+\item[func]
+is a Python function, taking one argument, to be invoked when the
+event occurs.  An Event instance will be passed as the argument.
+(Functions deployed this way are commonly known as \var{callbacks}.)
+
+\item[add]
+is optional, either \samp{} or \samp{+}.  Passing an empty string
+denotes that this binding is to replace any other bindings that this
+event is associated with.  Preceeding with a \samp{+} means that this
+function is to be added to the list of functions bound to this event type.
+\end{description}
+
+For example:
+\begin{verbatim}
+    def turnRed(self, event):
+        event.widget["activeforeground"] = "red"
+
+    self.button.bind("<Enter>", self.turnRed)
+\end{verbatim}
+
+Notice how the widget field of the event is being accesed in the
+\method{turnRed()} callback.  This field contains the widget that
+caught the X event.  The following table lists the other event fields
+you can access, and how they are denoted in Tk, which can be useful
+when referring to the Tk man pages.
+
+\begin{verbatim}
+Tk      Tkinter Event Field             Tk      Tkinter Event Field 
+--      -------------------             --      -------------------
+%f      focus                           %A      char
+%h      height                          %E      send_event
+%k      keycode                         %K      keysym
+%s      state                           %N      keysym_num
+%t      time                            %T      type
+%w      width                           %W      widget
+%x      x                               %X      x_root
+%y      y                               %Y      y_root
+\end{verbatim}
+
+
+\subsubsection{The index Parameter} % Index.html
+
+A number of widgets require``index'' parameters to be passed.  These
+are used to point at a specific place in a Text widget, or to
+particular characters in an Entry widget, or to particular menu items
+in a Menu widget.
+
+\begin{description}
+\item[\b{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 \refmodule{Tkinter} functions
+to access these special points in text widgets:
+\begin{description}
+\item[AtEnd()]
+refers to the last position in the text
+\item[AtInsert()]
+refers to the point where the text cursor is
+\item[AtSelFirst()]
+indicates the beginning point of the selected text
+\item[AtSelLast()]
+denotes the last point of the selected text and finally
+\item[At(x, y=None)]
+refers to the character at pixel location x, y (with y not used
+in the case of a text entry widget, which is one line of text).
+\end{description}
+
+\item[\b{Text widget indexes}]
+The index notation for Text widgets is very rich and is best described
+in the Tk man pages.
+
+\item[\b{Menu indexes (menu.invoke(), menu.entryconfig(), etc.)}]
+
+Some options and methods for menus manipulate specific menu entries.
+Anytime a menu index is needed for an option or a parameter, you may
+pass in: 
+\begin{itemize}
+\item   an integer which refers to the numeric position of the entry in
+the widget, counted from the top, starting with 0; 
+\item   the string \code{'active'}, which refers to the menu position that is
+currently under the cursor;
+\item   the string \code{"last"} which refers to the last menu
+item;  
+\item   An integer preceded by \code{@}, as in \code{@6}, where the integer is
+interpreted as a y pixel coordinate in the menu's coordinate system;
+\item   the string \code{"none"}, which indicates no menu entry at all, most
+often used with menu.activate() to deactivate all entries, and
+finally,
+\item   a text string that is pattern matched against the label of the
+menu entry, as scanned from the top of the menu to the bottom.  Note
+that this index type is considered after all the others, which means
+that matches for menu items labelled \code{last}, \code{active}, or
+\code{none} may be interpreted as the above literals, instead.
+\end{itemize}
+\end{description}
+
+
+\section{Tix \label{tix-widgets}}
+
+\index{Tix}
+
+\declaremodule{standard}{Tix}
+\modulesynopsis{Tk Extension Widgets for Tkinter}
+\sectionauthor{Mike Clarkson}{mikeclarkson@users.sourceforge.net}
+
+The \module{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 \module{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. \module{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 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. 
+
+\begin{seealso}
+\seetitle[http://tix.sourceforge.net/]
+        {Tix Homepage}
+        {See the home page for \module{Tix}.}
+\seetitle[http://tix.sourceforge.net/dist/current/man/]
+        {Tix Man Pages}
+        {On-line version of the man pages and reference material.}
+\seetitle[http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]
+        {Tix Programming Guide}
+        {On-line version of the programmer's reference material.}
+\seetitle[http://tix.sourceforge.net/Tide/]
+        {Tix Development Applications}
+        {Tix applications for development of Tix and Tkinter programs.
+         Tide applications work under Tk or Tkinter, and include
+         \program{TixInspect}, an inspector to remotely modify and
+         debug Tix/Tk/Tkinter applications.}
+\end{seealso}
+
+
+\subsection{Using Tix}
+
+\begin{classdesc}{Tix}{screenName=None, baseName=None, className='Tix'}
+    Toplevel widget of Tix which represents mostly the main window
+    of an application. It has an associated Tcl interpreter.
+
+The \refmodule{Tix} interface module subclasses the \refmodule{Tkinter}
+module. The former imports the latter, so to use \refmodule{Tix} with
+Tkinter, all you need to do is to import one module. In general, you
+can just import Tix, and replace the toplevel call
+to \class{Tkinter.Tk} with \class{Tix.Tk}:
+\begin{verbatim}
+import Tix
+from Tkconstants import *
+root = Tix.Tk()
+\end{verbatim}
+\end{classdesc}
+
+To use \refmodule{Tix}, you must have the \refmodule{Tix} widgets installed,
+usually alongside your installation of the Tk widgets.
+To test your installation, try the following:
+\begin{verbatim}
+import Tix
+root = Tix.Tk()
+root.tk.eval('package require Tix')
+\end{verbatim}
+
+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 \refmodule{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 have a file
+called \file{pkgIndex.tcl} (case sensitive), which contains the line:
+
+\begin{verbatim}
+package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
+\end{verbatim} % $ <-- bow to font-lock
+
+
+\subsection{Tix Widgets}
+
+\ulink{Tix}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm}
+introduces over 40 widget classes to the \refmodule{Tkinter} 
+repertoire.  There is a demo of all the \refmodule{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
+
+
+\subsubsection{Basic Widgets}
+
+\index{Balloon widget}
+\begin{classdesc}{Balloon}{}
+A \ulink{Balloon}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm} that pops
+up over a widget to provide help.  When the user moves the cursor
+inside a widget to which a Balloon widget has been bound, a small
+pop-up window with a descriptive message will be shown on the screen.
+\end{classdesc}
+
+% Python Demo of: \ulink{ Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
+
+\index{ButtonBox widget}
+\begin{classdesc}{ButtonBox}{}
+The \ulink{ButtonBox}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm} widget
+creates a box of buttons, such as is commonly used for \code{Ok Cancel}.
+\end{classdesc}
+
+% Python Demo of: \ulink{ ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
+
+\index{ComboBox widget}
+\begin{classdesc}{ComboBox}{}
+The \ulink{ComboBox}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm} widget is
+similar to the combo box control in MS Windows. The user can select a
+choice by either typing in the entry subwdget or selecting from the
+listbox subwidget.
+\end{classdesc}
+
+% Python Demo of: \ulink{ ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
+
+\index{Control widget}
+\begin{classdesc}{Control}{}
+The \ulink{Control}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm} widget is
+also known as the \class{SpinBox} widget. The user can adjust the value
+by pressing the two arrow buttons or by entering the value directly
+into the entry. The new value will be checked against the user-defined
+upper and lower limits.
+\end{classdesc}
+
+% Python Demo of: \ulink{ Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
+
+\index{LabelEntry widget}
+\begin{classdesc}{LabelEntry}{}
+The \ulink{LabelEntry}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm} widget
+packages an entry widget and a label into one mega widget. It can be
+used be used to simplify the creation of ``entry-form'' type of interface.
+\end{classdesc}
+
+% Python Demo of:
+% \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
+
+\index{LabelFrame widget}
+\begin{classdesc}{LabelFrame}{}
+The \ulink{LabelFrame}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm} widget
+packages a frame widget and a label into one mega widget. To create
+widgets inside a LabelFrame widget, one creates the new widgets
+relative to the \member{frame} subwidget and manage them inside the
+\member{frame} subwidget.
+\end{classdesc}
+
+% Python Demo of:
+% \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
+
+\index{Meter widget}
+\begin{classdesc}{Meter}{}
+The \ulink{Meter}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm} widget can
+be used to show the progress of a background job which may take a long
+time to execute.
+\end{classdesc}
+
+% Python Demo of:
+% \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
+
+\index{OptionMenu widget}
+\begin{classdesc}{OptionMenu}{}
+The \ulink{OptionMenu}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm} creates a
+menu button of options.
+\end{classdesc}
+
+% Python Demo of: \ulink{ OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
+
+\index{PopupMenu widget}
+\begin{classdesc}{PopupMenu}{}
+The \ulink{PopupMenu}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm} widget can
+be used as a replacement of the \code{tk_popup} command. The advantage
+of the \refmodule{Tix} PopupMenu widget is it requires less application
+code to manipulate.
+\end{classdesc}
+
+% Python Demo of: \ulink{ PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
+
+\index{Select widget}
+\begin{classdesc}{Select}{}
+The \ulink{Select}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm} widget is a
+container of button subwidgets. It can be used to provide radio-box or
+check-box style of selection options for the user.
+\end{classdesc}
+
+% Python Demo of: \ulink{ Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
+
+\index{StdButtonBox widget}
+\begin{classdesc}{StdButtonBox}{}
+The \ulink{StdButtonBox}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm} widget is a
+group of Standard buttons for Motif-like dialog boxes.
+\end{classdesc}
+
+% Python Demo of: \ulink{ StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
+
+
+\subsubsection{File Selectors}
+
+\index{DirList widget}
+\begin{classdesc}{DirList}{}
+The \ulink{DirList}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget
+displays a list view of a directory, its previous directories and its
+sub-directories. The user can choose one of the directories displayed
+in the list or change to another directory.
+\end{classdesc}
+
+% Python Demo of: \ulink{ DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
+
+\index{DirTree widget}
+\begin{classdesc}{DirTree}{}
+The \ulink{DirTree}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm} widget
+displays a tree view of a directory, its previous directories and its
+sub-directories. The user can choose one of the directories displayed
+in the list or change to another directory.
+\end{classdesc}
+
+% Python Demo of: \ulink{ DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
+
+\index{DirSelectDialog widget}
+\begin{classdesc}{DirSelectDialog}{}
+The \ulink{DirSelectDialog}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm} widget
+presents the directories in the file system in a dialog window. The
+user can use this dialog window to navigate through the file system to
+select the desired directory.
+\end{classdesc}
+
+% Python Demo of: \ulink{ DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
+
+\index{DirSelectBox widget}
+\begin{classdesc}{DirSelectBox}{}
+The \class{DirSelectBox} is similar
+to the standard Motif(TM) directory-selection box. It is generally used for
+the user to choose a directory. DirSelectBox stores the directories mostly
+recently selected into a ComboBox widget so that they can be quickly
+selected again.
+\end{classdesc}
+
+\index{ExFileSelectBox widget}
+\begin{classdesc}{ExFileSelectBox}{}
+The \ulink{ExFileSelectBox}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm} widget is
+usually embedded in a tixExFileSelectDialog widget. It provides an
+convenient method for the user to select files. The style of the
+ExFileSelectBox widget is very similar to the standard file dialog in
+MS Windows 3.1.
+\end{classdesc}
+
+% Python Demo of: \ulink{ ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
+
+\index{FileSelectBox widget}
+\begin{classdesc}{FileSelectBox}{}
+The \ulink{FileSelectBox}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm} is similar
+to the standard Motif(TM) file-selection box. It is generally used for
+the user to choose a file. FileSelectBox stores the files mostly
+recently selected into a ComboBox widget so that they can be quickly
+selected again.
+\end{classdesc}
+
+% Python Demo of: \ulink{ FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
+
+\index{FileEntry widget}
+\begin{classdesc}{FileEntry}{}
+The \ulink{FileEntry}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm} widget can
+be used to input a filename. The user can type in the filename
+manually. Alternatively, the user can press the button widget that
+sits next to the entry, which will bring up a file selection dialog.
+\end{classdesc}
+
+% Python Demo of: \ulink{ FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
+
+
+\subsubsection{Hierachical ListBox}
+
+\index{HList widget}
+\begin{classdesc}{HList}{}
+The \ulink{HList}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm} widget can be
+used to display any data that have a hierarchical structure, for
+example, file system directory trees. The list entries are indented
+and connected by branch lines according to their places in the hierachy.
+\end{classdesc}
+
+% Python Demo of: \ulink{ HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
+
+\index{CheckList widget}
+\begin{classdesc}{CheckList}{}
+The \ulink{CheckList}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm} widget
+displays a list of items to be selected by the user. CheckList acts
+similarly to the Tk checkbutton or radiobutton widgets, except it is
+capable of handling many more items than checkbuttons or radiobuttons.
+\end{classdesc}
+
+% Python Demo of: \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
+% Python Demo of: \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
+% Python Demo of: \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
+
+
+\index{Tree widget}
+\begin{classdesc}{Tree}{}
+The \ulink{Tree}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm} widget can be
+used to display hierachical data in a tree form. The user can adjust
+the view of the tree by opening or closing parts of the tree.
+\end{classdesc}
+
+% Python Demo of: \ulink{ Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
+
+% Python Demo of: \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
+
+
+\subsubsection{Tabular ListBox}
+
+\index{TList widget}
+\begin{classdesc}{TList}{}
+The \ulink{TList}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm} widget can be
+used to display data in a tabular format. The list entries of a TList
+widget are similar to the entries in the Tk listbox widget. The main
+differences are (1) the TList widget can display the list entries in a
+two dimensional format and (2) you can use graphical images as well as
+multiple colors and fonts for the list entries.
+\end{classdesc}
+
+% Python Demo of: \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
+% Python Demo of: \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
+
+% Grid has yet to be added to Python
+% \subsubsection{Grid Widget}
+% % Python Demo of: \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
+% % Python Demo of: \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
+% % Python Demo of: \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
+
+
+\subsubsection{Manager Widgets}
+
+\index{PanedWindow widget}
+\begin{classdesc}{PanedWindow}{}
+The \ulink{PanedWindow}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm} widget
+allows the user to interactively manipulate the sizes of several
+panes. The panes can be arranged either vertically or horizontally.The
+user changes the sizes of the panes by dragging the resize handle
+between two panes.
+\end{classdesc}
+
+% Python Demo of: \ulink{ PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
+
+\index{ListNoteBook widget}
+\begin{classdesc}{ListNoteBook}{}
+The \ulink{ListNoteBook}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm} widget is
+very similar to the TixNoteBook widget: it can be used to display many
+windows in a limited space using a notebook metaphor. The notebook is
+divided into a stack of pages (windows). At one time only one of these
+pages can be shown. The user can navigate through these pages by
+choosing the name of the desired page in the \member{hlist} subwidget.
+\end{classdesc}
+
+% Python Demo of: \ulink{ ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
+
+
+\index{NoteBook widget}
+\begin{classdesc}{NoteBook}{}
+The \ulink{NoteBook}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm} widget can
+be used to display many windows in a limited space using a notebook
+metaphor. The notebook is divided into a stack of pages. At one time
+only one of these pages can be shown. The user can navigate through
+these pages by choosing the visual ``tabs'' at the top of the NoteBook widget.
+\end{classdesc}
+
+% Python Demo of: \ulink{ NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
+
+
+% \subsubsection{Scrolled Widgets}
+% Python Demo of: \ulink{ ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
+% Python Demo of: \ulink{ ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
+% Python Demo of: \ulink{ ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
+% Python Demo of: \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
+
+
+\subsubsection{Image Types}
+
+The \refmodule{Tix} module adds:
+\begin{itemize}
+\item 
+\ulink{pixmap}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm} capabilities
+to all \refmodule{Tix} and \refmodule{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}
+
+% Python Demo of: \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
+
+\item
+\ulink{Compound}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.html} image
+types can be used to create images that consists of multiple
+horizontal lines; each line is composed of a series of items (texts,
+bitmaps, images or spaces) arranged from left to right. For example, a
+compound image can be used to display a bitmap and a text string
+simutaneously in a Tk \class{Button} widget.
+
+% Python Demo of: \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
+
+% Python Demo of: \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
+
+% Python Demo of: \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
+
+% Python Demo of: \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
+\end{itemize}
+
+
+\subsubsection{Miscellaneous Widgets}
+
+\index{InputOnly widget}
+\begin{classdesc}{InputOnly}{}
+The \ulink{InputOnly}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm} widgets are
+to accept inputs from the user, which can be done with the \code{bind}
+command (\UNIX{} only).
+\end{classdesc}
+
+\subsubsection{Form Geometry Manager}
+
+In addition, \refmodule{Tix} augments \refmodule{Tkinter} by providing:
+\index{Form widget class}
+\begin{classdesc}{Form}{}
+The \ulink{Form}
+{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm} geometry
+manager based on attachment rules for all Tk widgets.
+\end{classdesc}
+
+
+%begin{latexonly}
+%\subsection{Tix Class Structure}
+%
+%\begin{figure}[hbtp]
+%\centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}}
+%\vspace{.5cm}
+%\caption{The Class Hierarchy of Tix Widgets}
+%\end{figure}
+%end{latexonly}
+
+
+\section{Other User Interface Modules and Packages
+         \label{other-gui-modules}}
+
+
+There are an number of extension widget sets to \refmodule{Tkinter}.
+
+\begin{seealso}
+\seetitle[http://pmw.sourceforge.net/]{Python megawidgets}{is a
+toolkit for building high-level compound widgets in Python using the
+\refmodule{Tkinter} module.  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 busy, graph, stripchart, tabset
+and vector commands are be available.
+
+The initial ideas for Pmw were taken from the Tk \code{itcl}
+extensions \code{[incr Tk]} by Michael McLennan and \code{[incr
+Widgets]} by Mark Ulferts. Several of the megawidgets are direct
+translations from the itcl to Python. It offers most of the range of
+widgets that \code{[incr Widgets]} does, and is almost as complete as
+Tix, lacking however Tix's fast \class{HList} widget for drawing trees.
+}
+\seetitle[http://tkinter.effbot.org]{Tkinter3000}{
+is a Widget Construction Kit that allows you to write new Tkinter
+widgets in Python using Mixins. It is built on top of Tkinter,
+and does not offer the extended range of widgets that \refmodule{Tix} does,
+but does allow a form of  building mega-widgets. The project is
+still in the early stages.
+}
+\end{seealso}
+
+
+\refmodule{Tkinter} is not the only GUI for Python, but is however the
+most commonly used one.
+
+\begin{seealso}
+\seetitle[http://www.wxwindows.org]{wxWindows}{
+is a GUI toolkit that combines the most attractive attributes of Qt,
+Tk, Motif, and GTK+ in one powerful and efficient package. It is
+implemented in C++. wxWindows supports two flavors of Unix
+implementation: GTK+ and Motif, and under Windows, it has a standard
+Microsoft Foundation Classes (MFC) appearance, because it uses Win32
+widgets.  There is a Python class wrapper, independent of Tkinter.
+
+wxWindows is much richer in widgets than \refmodule{Tkinter}, with its
+help system, sophisticated HTML and image viewers, and other
+specialized widgets, extensive documentation, and printing capabilities.
+}
+\seetitle[http://www.thekompany.com]{PyKDE}{
+PyKDE is a SIP wrapped interface to the Qt toolkit.
+The Qt C++ toolkit lies at the heart of the KDE desktop, and the
+Qt toolkit allows very tight integration with KDE, and also Windows
+portability. SIP is a tool for generating bindings for \Cpp{} libraries
+as Python classes, and is specifically designed for Python.
+}
+\seetitle[http://fxpy.sourceforge.net/]{FXPy}{
+is a Python extension module which provides an interface to the 
+\citetitle[http://www.cfdrc.com/FOX/fox.html]{FOX} GUI.
+FOX is a C++ based Toolkit for developing Graphical User Interfaces
+easily and effectively. It offers a wide, and growing, collection of
+Controls, and provides state of the art facilities such as drag and
+drop, selection, as well as OpenGL widgets for 3D graphical
+manipulation.  FOX also implements icons, images, and user-convenience
+features such as status line help, and tooltips.  
+
+Even though FOX offers a large collection of Controls already, FOX
+leverages C++ to allow programmers to easily build additional Controls
+and GUI elements, simply by taking existing controls, and creating a
+derived class which simply adds or redefines the desired behavior.
+}
+\seetitle[http://www.daa.com.au/\~james/pygtk/]{PyGTK}{
+is a set of bindings for the \ulink{GTK}{http://www.gtk.org/} widget set.
+It provides an object oriented interface that is slightly higher
+level than the C one. It automatically does all the type casting and
+reference counting that you would have to do normally with the C
+API. There are also \ulink{bindings}{http://www.daa.com.au/\~james/gnome/}
+to  \ulink{GNOME}{http://www.gnome.org}, and a 
+\ulink{tutorial}
+{http://laguna.fmedic.unam.mx/\~daniel/pygtutorial/pygtutorial/index.html}
+is available.
+}
+\end{seealso}
+
+% XXX Reference URLs that compare the different UI packages
+
+
+\section{Idle \label{idle}}
+
+%\declaremodule{standard}{idle}
+%\modulesynopsis{A Python Integrated Developement Environment}
+\moduleauthor{Guido van Rossum}{guido@Python.org}
+
+Idle is the Python IDE built with the \refmodule{Tkinter} GUI toolkit.  
+\index{Idle}
+\index{Python Editor}
+\index{Integrated Developement Environment}
+
+
+IDLE has the following features:
+
+\begin{itemize}
+\item   coded in 100\% pure Python, using the \refmodule{Tkinter} GUI toolkit
+
+\item   cross-platform: works on Windows and \UNIX{} (on Mac OS, there are
+currently problems with Tcl/Tk)
+
+\item   multi-window text editor with multiple undo, Python colorizing
+and many other features, e.g. smart indent and call tips
+
+\item   Python shell window (a.k.a. interactive interpreter)
+
+\item   debugger (not complete, but you can set breakpoints, view  and step)
+\end{itemize}
+
+
+\subsection{Menus}
+
+\subsubsection{File menu}
+
+\begin{description}
+\item[New window]     create a new editing window
+\item[Open...]        open an existing file
+\item[Open module...] open an existing module (searches sys.path)
+\item[Class browser]  show classes and methods in current file
+\item[Path browser]   show sys.path directories, modules, classes and methods
+\end{description}
+\index{Class browser}
+\index{Path browser}
+
+\begin{description}
+\item[Save]   save current window to the associated file (unsaved
+windows have a * before and after the window title)
+
+\item[Save As...]     save current window to new file, which becomes
+the associated file
+\item[Save Copy As...]        save current window to different file
+without changing the associated file
+\end{description}
+
+\begin{description}
+\item[Close]  close current window (asks to save if unsaved)
+\item[Exit]   close all windows and quit IDLE (asks to save if unsaved)
+\end{description}
+
+
+\subsubsection{Edit menu}
+
+\begin{description}
+\item[Undo]   Undo last change to current window (max 1000 changes)
+\item[Redo]   Redo last undone change to current window
+\end{description}
+
+\begin{description}
+\item[Cut]    Copy selection into system-wide clipboard; then delete selection
+\item[Copy]   Copy selection into system-wide clipboard
+\item[Paste]  Insert system-wide clipboard into window
+\item[Select All]     Select the entire contents of the edit buffer
+\end{description}
+
+\begin{description}
+\item[Find...]        Open a search dialog box with many options
+\item[Find again]     Repeat last search
+\item[Find selection] Search for the string in the selection
+\item[Find in Files...]       Open a search dialog box for searching files
+\item[Replace...]     Open a search-and-replace dialog box
+\item[Go to line]     Ask for a line number and show that line
+\end{description}
+
+\begin{description}
+\item[Indent region]  Shift selected lines right 4 spaces
+\item[Dedent region]  Shift selected lines left 4 spaces
+\item[Comment out region]     Insert \#\# in front of selected lines
+\item[Uncomment region]       Remove leading \# or \#\# from selected lines
+\item[Tabify region]  Turns \emph{leading} stretches of spaces into tabs
+\item[Untabify region]        Turn \emph{all} tabs into the right number of spaces
+\item[Expand word]    Expand the word you have typed to match another
+                word in the same buffer; repeat to get a different expansion
+\item[Format Paragraph]       Reformat the current blank-line-separated paragraph
+\end{description}
+
+\begin{description}
+\item[Import module]  Import or reload the current module
+\item[Run script]     Execute the current file in the __main__ namespace
+\end{description}
+
+\index{Import module}
+\index{Run script}
+
+
+\subsubsection{Windows menu}
+
+\begin{description}
+\item[Zoom Height]    toggles the window between normal size (24x80)
+        and maximum height.
+\end{description}
+
+The rest of this menu lists the names of all open windows; select one
+to bring it to the foreground (deiconifying it if necessary).
+
+
+\subsubsection{Debug menu (in the Python Shell window only)}
+
+\begin{description}
+\item[Go to file/line]        look around the insert point for a filename
+                and linenumber, open the file, and show the line.
+\item[Open stack viewer]      show the stack traceback of the last exception
+\item[Debugger toggle]        Run commands in the shell under the debugger
+\item[JIT Stack viewer toggle]        Open stack viewer on traceback
+\end{description}
+
+\index{stack viewer}
+\index{debugger}
+
+
+\subsection{Basic editing and navigation}
+
+\begin{itemize}
+\item   \kbd{Backspace} deletes to the left; \kbd{Del} deletes to the right
+\item   Arrow keys and \kbd{Page Up}/\kbd{Page Down} to move around
+\item   \kbd{Home}/\kbd{End} go to begin/end of line
+\item   \kbd{C-Home}/\kbd{C-End} go to begin/end of file
+\item   Some \program{Emacs} bindings may also work, including \kbd{C-B},
+        \kbd{C-P}, \kbd{C-A}, \kbd{C-E}, \kbd{C-D}, \kbd{C-L}
+\end{itemize}
+
+
+\subsubsection{Automatic indentation}
+
+After a block-opening statement, the next line is indented by 4 spaces
+(in the Python Shell window by one tab).  After certain keywords
+(break, return etc.) the next line is dedented.  In leading
+indentation, \kbd{Backspace} deletes up to 4 spaces if they are there.
+\kbd{Tab} inserts 1-4 spaces (in the Python Shell window one tab).
+See also the indent/dedent region commands in the edit menu.
+
+
+\subsubsection{Python Shell window}
+
+\begin{itemize}
+\item   \kbd{C-C} interrupts executing command
+\item   \kbd{C-D} sends end-of-file; closes window if typed at
+a \samp{>>>~} prompt
+\end{itemize}
+
+\begin{itemize}
+\item   Alt-p retrieves previous command matching what you have typed
+\item   Alt-n retrieves next
+\item   \kbd{Return} while on any previous command retrieves that command
+\item   Alt-/ (Expand word) is also useful here
+\end{itemize}
+
+\index{indentation}
+
+
+\subsection{Syntax colors}
+
+The coloring is applied in a background ``thread,'' so you may
+occasionally see uncolorized text.  To change the color
+scheme, edit the \code{[Colors]} section in \file{config.txt}.
+
+\begin{description}
+\item[Python syntax colors:]
+
+\begin{description}
+\item[Keywords]       orange
+\item[Strings ]       green
+\item[Comments]       red
+\item[Definitions]    blue
+\end{description}
+
+\item[Shell colors:]
+\begin{description}
+\item[Console output] brown
+\item[stdout]         blue
+\item[stderr]       dark green
+\item[stdin]       black
+\end{description}
+\end{description}
+
+
+\subsubsection{Command line usage}
+
+\begin{verbatim}
+idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
+
+-c command  run this command
+-d          enable debugger
+-e          edit mode; arguments are files to be edited
+-s          run $IDLESTARTUP or $PYTHONSTARTUP first
+-t title    set title of shell window
+\end{verbatim}
+
+If there are arguments:
+
+\begin{enumerate}
+\item   If \programopt{-e} is used, arguments are files opened for
+        editing and \code{sys.argv} reflects the arguments passed to
+        IDLE itself.
+
+\item   Otherwise, if \programopt{-c} is used, all arguments are
+        placed in \code{sys.argv[1:...]}, with \code{sys.argv[0]} set
+        to \code{'-c'}.
+
+\item   Otherwise, if neither \programopt{-e} nor \programopt{-c} is
+        used, the first argument is a script which is executed with
+        the remaining arguments in \code{sys.argv[1:...]}  and
+        \code{sys.argv[0]} set to the script name.  If the script name
+        is '-', no script is executed but an interactive Python
+        session is started; the arguments are still available in
+        \code{sys.argv}.
+\end{enumerate}