diff options
| -rw-r--r-- | Doc/lib/tkinter.tex | 1674 |
1 files changed, 1674 insertions, 0 deletions
diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex new file mode 100644 index 0000000000..78c359d116 --- /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} |