Tkinter chapter, contributed by Mike Clarkson. Based in part on the "Tkinter
Life Preserver" by Matt Conway.
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}