blob: ba1bcc1f518957f3a090290b63a8b6cdddf9c1a1 [file] [log] [blame]
Fred Drake10cd3152001-11-30 18:17:24 +00001\chapter{Graphical User Interfaces with Tk \label{tkinter}}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00002
3\index{GUI}
4\index{Graphical User Interface}
5\index{Tkinter}
6\index{Tk}
7
8Tk/Tcl has long been an integral part of Python. It provides a robust
9and platform independent windowing toolkit, that is available to
10Python programmers using the \refmodule{Tkinter} module, and its
11extension, the \refmodule{Tix} module.
12
Fred Drake666ca802001-11-16 06:02:55 +000013The \refmodule{Tkinter} module is a thin object--oriented layer on top of
Fred Drake7cf4e5b2001-11-15 17:22:04 +000014Tcl/Tk. To use \refmodule{Tkinter}, you don't need to write Tcl code,
15but you will need to consult the Tk documentation, and occasionally
16the Tcl documentation. \refmodule{Tkinter} is a set of wrappers that
17implement the Tk widgets as Python classes. In addition, the internal
18module \module{\_tkinter} provides a threadsafe mechanism which allows
19Python and Tcl to interact.
20
Fred Drake666ca802001-11-16 06:02:55 +000021Tk is not the only GUI for Python, but is however the most commonly
22used one; see section~\ref{other-gui-modules}, ``Other User Interface
23Modules and Packages,'' for more information on other GUI toolkits for
24Python.
Fred Drake7cf4e5b2001-11-15 17:22:04 +000025
26% Other sections I have in mind are
27% Tkinter internals
28% Freezing Tkinter applications
29
30\localmoduletable
31
32
Fred Drakec66ff202001-11-16 01:05:27 +000033\section{\module{Tkinter} ---
34 Python interface to Tcl/Tk}
Fred Drake7cf4e5b2001-11-15 17:22:04 +000035
36\declaremodule{standard}{Tkinter}
37\modulesynopsis{Interface to Tcl/Tk for graphical user interfaces}
38\moduleauthor{Guido van Rossum}{guido@Python.org}
39
40The \module{Tkinter} module (``Tk interface'') is the standard Python
41interface to the Tk GUI toolkit, now maintained at ActiveState. Both
Fred Drakec37b65e2001-11-28 07:26:15 +000042Tk and \module{Tkinter} are available on most \UNIX{} platforms, as well
Fred Drake7cf4e5b2001-11-15 17:22:04 +000043as on Windows and Macintosh systems.
44
45\begin{seealso}
46\seetitle[http://www.python.org/topics/tkinter/]
47 {Python Tkinter Resources}
48 {The Python Tkinter Topic Guide provides a great
49 deal of information on using Tk from Python and links to
50 other sources of information on Tk.}
51
52\seetitle[http://www.pythonware.com/library/an-introduction-to-tkinter.htm]
53 {An Introduction to Tkinter}
54 {Fredrik Lundh's on-line reference material.}
55
56\seetitle[http://www.nmt.edu/tcc/help/pubs/lang.html]
57 {Tkinter reference: a GUI for Python}
58 {On-line reference material.}
59
60\seetitle[http://jtkinter.sourceforge.net]
61 {Tkinter for JPython}
62 {The Jython interface to Tkinter.}
63
64\seetitle[http://www.amazon.com/exec/obidos/ASIN/1884777813]
65 {Python and Tkinter Programming}
66 {The book by John Grayson (ISBN 1-884777-81-3).}
67\end{seealso}
68
69
70\subsection{Tkinter Modules}
71
Fred Drake666ca802001-11-16 06:02:55 +000072Most of the time, the \refmodule{Tkinter} module is all you really
73need, but a number of additional modules are available as well. The
74Tk interface is located in a binary module named \module{_tkinter}.
75This module contains the low-level interface to Tk, and should never
76be used directly by application programmers. It is usually a shared
77library (or DLL), but might in some cases be statically linked with
78the Python interpreter.
Fred Drake7cf4e5b2001-11-15 17:22:04 +000079
80In addition to the Tk interface module, \refmodule{Tkinter} includes a
81number of Python modules. The two most important modules are the
82\refmodule{Tkinter} module itself, and a module called
83\module{Tkconstants}. The former automatically imports the latter, so
84to use Tkinter, all you need to do is to import one module:
85
86\begin{verbatim}
87import Tkinter
88\end{verbatim}
89
90Or, more often:
91
92\begin{verbatim}
93from Tkinter import *
94\end{verbatim}
95
96\begin{classdesc}{Tk}{screenName=None, baseName=None, className='Tk'}
97The \class{Tk} class is instantiated without arguments.
98This creates a toplevel widget of Tk which usually is the main window
99of an appliation. Each instance has its own associated Tcl interpreter.
100% FIXME: The following keyword arguments are currently recognized:
101\end{classdesc}
102
103Other modules that provide Tk support include:
104
105\begin{description}
106% \declaremodule{standard}{Tkconstants}
107% \modulesynopsis{Constants used by Tkinter}
108% FIXME
109
Fred Drake1a763862001-12-03 21:18:30 +0000110\item[\refmodule{ScrolledText}]
111Text widget with a vertical scroll bar built in.
112
Fred Drakec66ff202001-11-16 01:05:27 +0000113\item[\module{tkColorChooser}]
114Dialog to let the user choose a color.
115
116\item[\module{tkCommonDialog}]
Fred Drake04677752001-11-30 19:24:49 +0000117Base class for the dialogs defined in the other modules listed here.
Fred Drakec66ff202001-11-16 01:05:27 +0000118
119\item[\module{tkFileDialog}]
120Common dialogs to allow the user to specify a file to open or save.
121
122\item[\module{tkFont}]
123Utilities to help work with fonts.
124
125\item[\module{tkMessageBox}]
126Access to standard Tk dialog boxes.
127
128\item[\module{tkSimpleDialog}]
129Basic dialogs and convenience functions.
130
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000131\item[\module{Tkdnd}]
132Drag-and-drop support for \refmodule{Tkinter}.
133This is experimental and should become deprecated when it is replaced
134with the Tk DND.
135
136\item[\refmodule{turtle}]
137Turtle graphics in a Tk window.
138
139\end{description}
140
141\subsection{Tkinter Life Preserver}
Fred Drakec66ff202001-11-16 01:05:27 +0000142\sectionauthor{Matt Conway}{}
143% Converted to LaTeX by Mike Clarkson.
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000144
145This section is not designed to be an exhaustive tutorial on either
146Tk or Tkinter. Rather, it is intended as a stop gap, providing some
147introductory orientation on the system.
148
149Credits:
150\begin{itemize}
151\item Tkinter was written by Steen Lumholt and Guido van Rossum.
152\item Tk was written by John Ousterhout while at Berkeley.
153\item This Life Preserver was written by Matt Conway at
154the University of Virginia.
155\item The html rendering, and some liberal editing, was
156produced from a FrameMaker version by Ken Manheimer.
157\item Fredrik Lundh elaborated and revised the class interface descriptions,
158to get them current with Tk 4.2.
159\item Mike Clarkson converted the documentation to \LaTeX, and compiled the
160User Interface chapter of the reference manual.
161\end{itemize}
162
163
164\subsubsection{How To Use This Section}
165
166This section is designed in two parts: the first half (roughly) covers
167background material, while the second half can be taken to the
168keyboard as a handy reference.
169
170When trying to answer questions of the form ``how do I do blah'', it
171is often best to find out how to do``blah'' in straight Tk, and then
172convert this back into the corresponding \refmodule{Tkinter} call.
173Python programmers can often guess at the correct Python command by
174looking at the Tk documentation. This means that in order to use
175Tkinter, you will have to know a little bit about Tk. This document
176can't fulfill that role, so the best we can do is point you to the
177best documentation that exists. Here are some hints:
178
179\begin{itemize}
180\item The authors strongly suggest getting a copy of the Tk man
181pages. Specifically, the man pages in the \code{mann} directory are most
182useful. The \code{man3} man pages describe the C interface to the Tk
183library and thus are not especially helpful for script writers.
184
185\item Addison-Wesley publishes a book called \citetitle{Tcl and the
186Tk Toolkit} by John Ousterhout (ISBN 0-201-63337-X) which is a good
187introduction to Tcl and Tk for the novice. The book is not
188exhaustive, and for many details it defers to the man pages.
189
190\item \file{Tkinter.py} is a last resort for most, but can be a good
191place to go when nothing else makes sense.
192\end{itemize}
193
194\begin{seealso}
195\seetitle[http://tcl.activestate.com/]
196 {ActiveState Tcl Home Page}
197 {The Tk/Tcl development is largely taking place at
198 ActiveState.}
199\seetitle[http://www.amazon.com/exec/obidos/ASIN/020163337X]
200 {Tcl and the Tk Toolkit}
201 {The book by John Ousterhout, the inventor of Tcl .}
202\seetitle[http://www.amazon.com/exec/obidos/ASIN/0130220280]
203 {Practical Programming in Tcl and Tk}
204 {Brent Welch's encyclopedic book.}
205\end{seealso}
206
207
208\subsubsection{A Simple Hello World Program} % HelloWorld.html
209
210%begin{latexonly}
211%\begin{figure}[hbtp]
212%\centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}}
213%\vspace{.5cm}
214%\caption{HelloWorld gadget image}
215%\end{figure}
216%See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and
217%\ulink{summary}{classes/HelloWorld-summary.html}.
218%end{latexonly}
219
220
221\begin{verbatim}
222from Tkinter import * 1
223 2
224class Application(Frame): 3
225 def say_hi(self): 4
226 print "hi there, everyone!" 5
227 6
228 def createWidgets(self): 7
229 self.QUIT = Button(self) 8
230 self.QUIT["text"] = "QUIT" 9
231 self.QUIT["fg"] = "red" 10
232 self.QUIT["command"] = self.quit 11
233 12
234 self.QUIT.pack({"side": "left"}) 13
235 14
236 self.hi_there = Button(self) 15
237 self.hi_there["text"] = "Hello", 16
238 self.hi_there["command"] = self.say_hi 17
239 18
240 self.hi_there.pack({"side": "left"}) 19
241 20
242 21
243 def __init__(self, master=None): 22
244 Frame.__init__(self, master) 23
245 self.pack() 24
246 self.createWidgets() 25
247 26
248app = Application() 27
249app.mainloop() 28
250\end{verbatim}
251
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000252
Fred Drakeb22c6722001-12-03 06:12:23 +0000253\subsection{A (Very) Quick Look at Tcl/Tk} % BriefTclTk.html
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000254
255The class hierarchy looks complicated, but in actual practice,
256application programmers almost always refer to the classes at the very
257bottom of the hierarchy.
258
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000259Notes:
260\begin{itemize}
261\item These classes are provided for the purposes of
262organizing certain functions under one namespace. They aren't meant to
263be instantiated independently.
Fred Drakeb22c6722001-12-03 06:12:23 +0000264
265\item The \class{Tk} class is meant to be instantiated only once in
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000266an application. Application programmers need not instantiate one
267explicitly, the system creates one whenever any of the other classes
268are instantiated.
Fred Drakeb22c6722001-12-03 06:12:23 +0000269
270\item The \class{Widget} class is not meant to be instantiated, it
271is meant only for subclassing to make ``real'' widgets (in \Cpp, this
272is called an `abstract class').
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000273\end{itemize}
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000274
275To make use of this reference material, there will be times when you
276will need to know how to read short passages of Tk and how to identify
277the various parts of a Tk command.
Fred Drake666ca802001-11-16 06:02:55 +0000278(See section~\ref{tkinter-basic-mapping} for the
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000279\refmodule{Tkinter} equivalents of what's below.)
280
281Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are
282just lists of tokens separated by spaces. A Tk widget is just its
283\emph{class}, the \emph{options} that help configure it, and the
284\emph{actions} that make it do useful things.
285
286To make a widget in Tk, the command is always of the form:
287
288\begin{verbatim}
289 classCommand newPathname options
290\end{verbatim}
291
292\begin{description}
293\item[\var{classCommand}]
294denotes which kind of widget to make (a button, a label, a menu...)
295
296\item[\var{newPathname}]
297is the new name for this widget. All names in Tk must be unique. To
298help enforce this, widgets in Tk are named with \emph{pathnames}, just
299like files in a file system. The top level widget, the \emph{root},
300is called \code{.} (period) and children are delimited by more
301periods. For example, \code{.myApp.controlPanel.okButton} might be
302the name of a widget.
303
304\item[\var{options} ]
305configure the widget's appearance and in some cases, its
306behavior. The options come in the form of a list of flags and values.
307Flags are proceeded by a `-', like unix shell command flags, and
308values are put in quotes if they are more than one word.
309\end{description}
310
311For example:
312
313\begin{verbatim}
314 button .fred -fg red -text "hi there"
315 ^ ^ \_____________________/
316 | | |
317 class new options
318 command widget (-opt val -opt val ...)
319\end{verbatim}
320
321Once created, the pathname to the widget becomes a new command. This
322new \var{widget command} is the programmer's handle for getting the new
323widget to perform some \var{action}. In C, you'd express this as
Fred Drakec66ff202001-11-16 01:05:27 +0000324someAction(fred, someOptions), in \Cpp, you would express this as
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000325fred.someAction(someOptions), and in Tk, you say:
326
327\begin{verbatim}
328 .fred someAction someOptions
329\end{verbatim}
330
331Note that the object name, \code{.fred}, starts with a dot.
332
333As you'd expect, the legal values for \var{someAction} will depend on
334the widget's class: \code{.fred disable} works if fred is a
335button (fred gets greyed out), but does not work if fred is a label
336(disabling of labels is not supported in Tk).
337
338The legal values of \var{someOptions} is action dependent. Some
339actions, like \code{disable}, require no arguments, others, like
340a text-entry box's \code{delete} command, would need arguments
341to specify what range of text to delete.
342
343
344\subsection{Mapping Basic Tk into Tkinter
345 \label{tkinter-basic-mapping}}
346
347Class commands in Tk correspond to class constructors in Tkinter.
348
349\begin{verbatim}
350 button .fred =====> fred = Button()
351\end{verbatim}
352
353The master of an object is implicit in the new name given to it at
354creation time. In Tkinter, masters are specified explicitly.
355
356\begin{verbatim}
357 button .panel.fred =====> fred = Button(panel)
358\end{verbatim}
359
360The configuration options in Tk are given in lists of hyphened tags
361followed by values. In Tkinter, options are specified as
362keyword-arguments in the instance constructor, and keyword-args for
363configure calls or as instance indices, in dictionary style, for
Fred Drake666ca802001-11-16 06:02:55 +0000364established instances. See section~\ref{tkinter-setting-options} on
365setting options.
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000366
367\begin{verbatim}
368 button .fred -fg red =====> fred = Button(panel, fg = "red")
369 .fred configure -fg red =====> fred["fg"] = red
370 OR ==> fred.config(fg = "red")
371\end{verbatim}
372
373In Tk, to perform an action on a widget, use the widget name as a
374command, and follow it with an action name, possibly with arguments
375(options). In Tkinter, you call methods on the class instance to
376invoke actions on the widget. The actions (methods) that a given
377widget can perform are listed in the Tkinter.py module.
378
379\begin{verbatim}
380 .fred invoke =====> fred.invoke()
381\end{verbatim}
382
383To give a widget to the packer (geometry manager), you call pack with
384optional arguments. In Tkinter, the Pack class holds all this
385functionality, and the various forms of the pack command are
386implemented as methods. All widgets in \refmodule{Tkinter} are
387subclassed from the Packer, and so inherit all the packing
388methods. See the \refmodule{Tix} module documentation for additional
389information on the Form geometry manager.
390
391\begin{verbatim}
392 pack .fred -side left =====> fred.pack(side = "left")
393\end{verbatim}
394
395
396\subsection{How Tk and Tkinter are Related} % Relationship.html
397
Fred Drake666ca802001-11-16 06:02:55 +0000398\note{This was derived from a graphical image; the image will be used
399 more directly in a subsequent version of this document.}
400
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000401From the top down:
402\begin{description}
403\item[\b{Your App Here (Python)}]
404A Python application makes a \refmodule{Tkinter} call.
405
406\item[\b{Tkinter (Python Module)}]
407This call (say, for example, creating a button widget), is
408implemented in the \emph{Tkinter} module, which is written in
409Python. This Python function will parse the commands and the
410arguments and convert them into a form that makes them look as if they
411had come from a Tk script instead of a Python script.
412
413\item[\b{tkinter (C)}]
414These commands and their arguments will be passed to a C function
415in the \emph{tkinter} - note the lowercase - extension module.
416
417\item[\b{Tk Widgets} (C and Tcl)]
418This C function is able to make calls into other C modules,
419including the C functions that make up the Tk library. Tk is
420implemented in C and some Tcl. The Tcl part of the Tk widgets is used
421to bind certain default behaviors to widgets, and is executed once at
422the point where the Python \refmodule{Tkinter} module is
423imported. (The user never sees this stage).
424
425\item[\b{Tk (C)}]
426The Tk part of the Tk Widgets implement the final mapping to ...
427
428\item[\b{Xlib (C)}]
429the Xlib library to draw graphics on the screen.
430\end{description}
431
432
433\subsection{Handy Reference}
434
435\subsubsection{Setting Options
436 \label{tkinter-setting-options}}
437
438Options control things like the color and border width of a widget.
439Options can be set in three ways:
440
441\begin{description}
442\item[At object creation time, using keyword arguments]:
443\begin{verbatim}
444fred = Button(self, fg = "red", bg = "blue")
445\end{verbatim}
446\item[After object creation, treating the option name like a dictionary index]:
447\begin{verbatim}
448fred["fg"] = "red"
449fred["bg"] = "blue"
450\end{verbatim}
451\item[Use the config() method to update multiple attrs subesequent to
452object creation]:
453\begin{verbatim}
454fred.config(fg = "red", bg = "blue")
455\end{verbatim}
456\end{description}
457
458For a complete explanation of a given option and its behavior, see the
459Tk man pages for the widget in question.
460
461Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC
462OPTIONS" for each widget. The former is a list of options that are
463common to many widgets, the latter are the options that are
464ideosyncratic to that particular widget. The Standard Options are
465documented on the \manpage{options}{3} man page.
466
467No distinction between standard and widget-specific options is made in
468this document. Some options don't apply to some kinds of widgets.
469Whether a given widget responds to a particular option depends on the
470class of the widget; buttons have a \code{command} option, labels do not.
471
472The options supported by a given widget are listed in that widget's
473man page, or can be queried at runtime by calling the
474\kbd{config()} method with arguments, or by calling the keys()
475method on that widget. The return value of these calls is a dictionary
476whose key is the name of the option (e.g. \kbd{relief}) and whose
477values are 5 tuples.
478
479(Some options, like \kbd{bg} are synonyms for common options with
480hard-to-type names (\kbd{bg} is shorthand for "background").
481Passing the \kbd{config()} method the name of a
482shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple
483passed back will contain the name of the synonym ``real''
484option. (\kbd{bg}, \kbd{background}))
485
486\begin{tableiii}{c|l|l}{textrm}{Index}{Meaning}{Example}
487 \lineiii{0}{option name} {\code{'relief'}}
488 \lineiii{1}{option name for database lookup} {\code{'relief'}}
489 \lineiii{2}{option class for database lookup} {\code{'Relief'}}
490 \lineiii{3}{default value} {\code{'raised'}}
491 \lineiii{4}{current value} {\code{'groove'}}
492\end{tableiii}
493
494
495Example:
496
497\begin{verbatim}
498>>> print fred.config()
499{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
500\end{verbatim}
501
502Of course, the dictionary printed will include all the options
503available and their values. This is meant only as an example.
504
505
506\subsubsection{The Packer} % Packer.html
507\index{packing (widgets)}
508
509The packer is one of Tk's geometry-management mechanisms. See also
510\citetitle[classes/ClassPacker.html]{the Packer class interface}.
511
512Geometry managers are used to specify the relative positioning of the
513positioning of widgets within their container - their mutual
514\emph{master}. In contrast to the more cumbersome \emph{placer}
515(which is used less commonly, and we do not cover here), the packer
516takes qualitative relationship specification - \emph{above}, \emph{to
517the left of}, \emph{filling}, etc - and works everything out to
518determine the exact placement coordinates for you.
519
520The size of any \emph{master} widget is determined by the size of
521the "slave widgets" inside. The packer is used to control where slave
522widgets appear inside the master into which they are packed. You can
523pack widgets into frames, and frames into other frames, in order to
524achieve the kind of layout you desire. Additionally, the arrangement
525is dynamically adjusted to accomodate incremental changes to the
526configuration, once it is packed.
527
528Note that widgets do not appear until they have had their geometry
529specified with a geometry manager. It's a common early mistake to
530leave out the geometry specification, and then be surprised when the
531widget is created but nothing appears. A widget will appear only
532after it has had, for example, the packer's \method{pack()} method
533applied to it.
534
535The pack() method can be called with keyword-option/value pairs that
536control where the widget is to appear within its container, and how it
537is to behave when the main application window is resized. Here are
538some examples:
539
540\begin{verbatim}
541 fred.pack() # defaults to side = "top"
542 fred.pack(side = "left")
543 fred.pack(expand = 1)
544\end{verbatim}
545
546
547\subsubsection{Packer Options}
548
549For more extensive information on the packer and the options that it
550can take, see the man pages and page 183 of John Ousterhout's book.
551
552\begin{description}
553\item[\b{anchor }]
554Anchor type. Denotes where the packer is to place each slave in its
555parcel.
556
557\item[\b{expand}]
558Boolean, \code{0} or \code{1}.
559
560\item[\b{fill}]
561Legal values: \code{'x'}, \code{'y'}, \code{'both'}, \code{'none'}.
562
563\item[\b{ipadx} and \b{ipady}]
564A distance - designating internal padding on each side of the slave
565widget.
566
567\item[\b{padx} and \b{pady}]
568A distance - designating external padding on each side of the slave
569widget.
570
571\item[\b{side}]
572Legal values are: \code{'left'}, \code{'right'}, \code{'top'},
573\code{'bottom'}.
574\end{description}
575
576
577\subsubsection{Coupling Widget Variables} % VarCouplings.html
578
579The current-value setting of some widgets (like text entry widgets)
580can be connected directly to application variables by using special
581options. These options are \code{variable}, \code{textvariable},
582\code{onvalue}, \code{offvalue}, and \code{value}. This
583connection works both ways: if the variable changes for any reason,
584the widget it's connected to will be updated to reflect the new value.
585
586Unfortunately, in the current implementation of \refmodule{Tkinter} it is
587not possible to hand over an arbitrary Python variable to a widget
588through a \code{variable} or \code{textvariable} option. The only
589kinds of variables for which this works are variables that are
590subclassed from a class called Variable, defined in the
591\refmodule{Tkinter} module.
592
593There are many useful subclasses of Variable already defined:
594\class{StringVar}, \class{IntVar}, \class{DoubleVar}, and
595\class{BooleanVar}. To read the current value of such a variable,
596call the \method{get()} method on
597it, and to change its value you call the \method{set()} method. If
598you follow this protocol, the widget will always track the value of
599the variable, with no further intervention on your part.
600
601For example:
602\begin{verbatim}
603class App(Frame):
604 def __init__(self, master=None):
605 Frame.__init__(self, master)
606 self.pack()
607
608 self.entrythingy = Entry()
609 self.entrythingy.pack()
610
611 self.button.pack()
612 # here is the application variable
613 self.contents = StringVar()
614 # set it to some value
615 self.contents.set("this is a variable")
616 # tell the entry widget to watch this variable
617 self.entrythingy["textvariable"] = self.contents
618
619 # and here we get a callback when the user hits return.
620 # we will have the program print out the value of the
621 # application variable when the user hits return
622 self.entrythingy.bind('<Key-Return>',
623 self.print_contents)
624
625 def print_contents(self, event):
626 print "hi. contents of entry is now ---->", \
627 self.contents.get()
628\end{verbatim}
629
630
631\subsubsection{The Window Manager} % WindowMgr.html
632\index{window manager (widgets)}
633
634In Tk, there is a utility command, \code{wm}, for interacting with the
635window manager. Options to the \code{wm} command allow you to control
636things like titles, placement, icon bitmaps, and the like. In
637\refmodule{Tkinter}, these commands have been implemented as methods
638on the \class{Wm} class. Toplevel widgets are subclassed from the
639\class{Wm} class, and so can call the \class{Wm} methods directly.
640
641%See also \citetitle[classes/ClassWm.html]{the Wm class interface}.
642
643To get at the toplevel window that contains a given widget, you can
644often just refer to the widget's master. Of course if the widget has
645been packed inside of a frame, the master won't represent a toplevel
646window. To get at the toplevel window that contains an arbitrary
647widget, you can call the \method{_root()} method. This
648method begins with an underscore to denote the fact that this function
649is part of the implementation, and not an interface to Tk functionality.
650
651Here are some examples of typical usage:
652
653\begin{verbatim}
654import Tkinter
655class App(Frame):
656 def __init__(self, master=None):
657 Frame.__init__(self, master)
658 self.pack()
659
660
661# create the application
662myapp = App()
663
664#
665# here are method calls to the window manager class
666#
667myapp.master.title("My Do-Nothing Application")
668myapp.master.maxsize(1000, 400)
669
670# start the program
671myapp.mainloop()
672\end{verbatim}
673
674
675\subsubsection{Tk Option Data Types} % OptionTypes.html
676
677\index{Tk Option Data Types}
678
679\begin{description}
680\item[anchor]
681Legal values are points of the compass: \code{"n"},
682\code{"ne"}, \code{"e"}, \code{"se"}, \code{"s"},
683\code{"sw"}, \code{"w"}, \code{"nw"}, and also
684\code{"center"}.
685
686\item[bitmap]
687There are eight built-in, named bitmaps: \code{'error'}, \code{'gray25'},
688\code{'gray50'}, \code{'hourglass'}, \code{'info'}, \code{'questhead'},
689\code{'question'}, \code{'warning'}. To specify an X bitmap
690filename, give the full path to the file, preceded with an \code{@},
691as in \code{"@/usr/contrib/bitmap/gumby.bit"}.
692
693\item[boolean]
694You can pass integers 0 or 1 or the stings \code{"yes"} or \code{"no"} .
695
696\item[callback]
697This is any Python function that takes no arguments. For example:
698\begin{verbatim}
699 def print_it():
700 print "hi there"
701 fred["command"] = print_it
702\end{verbatim}
703
704\item[color]
705Colors can be given as the names of X colors in the rgb.txt file,
706or as strings representing RGB values in 4 bit: \code{"\#RGB"}, 8
707bit: \code{"\#RRGGBB"}, 12 bit" \code{"\#RRRGGGBBB"}, or 16 bit
708\code{"\#RRRRGGGGBBBB"} ranges, where R,G,B here represent any
709legal hex digit. See page 160 of Ousterhout's book for details.
710
711\item[cursor]
712The standard X cursor names from \file{cursorfont.h} can be used,
713without the \code{XC_} prefix. For example to get a hand cursor
714(\constant{XC_hand2}), use the string \code{"hand2"}. You can also
715specify a bitmap and mask file of your own. See page 179 of
716Ousterhout's book.
717
718\item[distance]
719Screen distances can be specified in either pixels or absolute
720distances. Pixels are given as numbers and absolute distances as
721strings, with the trailing character denoting units: \code{c}
722for centimeters, \code{i} for inches, \code{m} for millimeters,
723\code{p} for printer's points. For example, 3.5 inches is expressed
724as \code{"3.5i"}.
725
726\item[font]
727Tk uses a list font name format, such as \code{\{courier 10 bold\}}.
728Font sizes with positive numbers are measured in points;
729sizes with negative numbers are measured in pixels.
730
731\item[geometry]
732This is a string of the form \samp{\var{width}x\var{height}}, where
733width and height are measured in pixels for most widgets (in
734characters for widgets displaying text). For example:
735\code{fred["geometry"] = "200x100"}.
736
737\item[justify]
738Legal values are the strings: \code{"left"},
739\code{"center"}, \code{"right"}, and \code{"fill"}.
740
741\item[region]
742This is a string with four space-delimited elements, each of
743which is a legal distance (see above). For example: \code{"2 3 4
7445"} and \code{"3i 2i 4.5i 2i"} and \code{"3c 2c 4c 10.43c"}
745are all legal regions.
746
747\item[relief]
748Determines what the border style of a widget will be. Legal
749values are: \code{"raised"}, \code{"sunken"},
750\code{"flat"}, \code{"groove"}, and \code{"ridge"}.
751
752\item[scrollcommand]
753This is almost always the \method{set()} method of some scrollbar
754widget, but can be any widget method that takes a single argument.
755Refer to the file \file{Demo/tkinter/matt/canvas-with-scrollbars.py}
756in the Python source distribution for an example.
757
758\item[wrap:]
759Must be one of: \code{"none"}, \code{"char"}, or \code{"word"}.
760\end{description}
761
762
763\subsubsection{Bindings and Events} % Bindings.html
764
765\index{bind (widgets)}
766\index{events (widgets)}
767
768The bind method from the widget command allows you to watch for
769certain events and to have a callback function trigger when that event
770type occurs. The form of the bind method is:
771
772\begin{verbatim}
773 def bind(self, sequence, func, add=''):
774\end{verbatim}
775where:
776
777\begin{description}
778\item[sequence]
779is a string that denotes the target kind of event. (See the bind
780man page and page 201 of John Ousterhout's book for details).
781
782\item[func]
783is a Python function, taking one argument, to be invoked when the
784event occurs. An Event instance will be passed as the argument.
785(Functions deployed this way are commonly known as \var{callbacks}.)
786
787\item[add]
788is optional, either \samp{} or \samp{+}. Passing an empty string
789denotes that this binding is to replace any other bindings that this
790event is associated with. Preceeding with a \samp{+} means that this
791function is to be added to the list of functions bound to this event type.
792\end{description}
793
794For example:
795\begin{verbatim}
796 def turnRed(self, event):
797 event.widget["activeforeground"] = "red"
798
799 self.button.bind("<Enter>", self.turnRed)
800\end{verbatim}
801
802Notice how the widget field of the event is being accesed in the
803\method{turnRed()} callback. This field contains the widget that
804caught the X event. The following table lists the other event fields
805you can access, and how they are denoted in Tk, which can be useful
806when referring to the Tk man pages.
807
808\begin{verbatim}
809Tk Tkinter Event Field Tk Tkinter Event Field
810-- ------------------- -- -------------------
811%f focus %A char
812%h height %E send_event
813%k keycode %K keysym
814%s state %N keysym_num
815%t time %T type
816%w width %W widget
817%x x %X x_root
818%y y %Y y_root
819\end{verbatim}
820
821
822\subsubsection{The index Parameter} % Index.html
823
824A number of widgets require``index'' parameters to be passed. These
825are used to point at a specific place in a Text widget, or to
826particular characters in an Entry widget, or to particular menu items
827in a Menu widget.
828
829\begin{description}
830\item[\b{Entry widget indexes (index, view index, etc.)}]
831Entry widgets have options that refer to character positions in the
832text being displayed. You can use these \refmodule{Tkinter} functions
833to access these special points in text widgets:
Fred Drake666ca802001-11-16 06:02:55 +0000834
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000835\begin{description}
836\item[AtEnd()]
837refers to the last position in the text
Fred Drake666ca802001-11-16 06:02:55 +0000838
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000839\item[AtInsert()]
840refers to the point where the text cursor is
Fred Drake666ca802001-11-16 06:02:55 +0000841
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000842\item[AtSelFirst()]
843indicates the beginning point of the selected text
Fred Drake666ca802001-11-16 06:02:55 +0000844
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000845\item[AtSelLast()]
846denotes the last point of the selected text and finally
Fred Drake666ca802001-11-16 06:02:55 +0000847
848\item[At(x\optional{, y})]
849refers to the character at pixel location \var{x}, \var{y} (with
850\var{y} not used in the case of a text entry widget, which contains a
851single line of text).
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000852\end{description}
853
854\item[\b{Text widget indexes}]
855The index notation for Text widgets is very rich and is best described
856in the Tk man pages.
857
858\item[\b{Menu indexes (menu.invoke(), menu.entryconfig(), etc.)}]
859
860Some options and methods for menus manipulate specific menu entries.
861Anytime a menu index is needed for an option or a parameter, you may
862pass in:
863\begin{itemize}
864\item an integer which refers to the numeric position of the entry in
865the widget, counted from the top, starting with 0;
866\item the string \code{'active'}, which refers to the menu position that is
867currently under the cursor;
868\item the string \code{"last"} which refers to the last menu
869item;
870\item An integer preceded by \code{@}, as in \code{@6}, where the integer is
871interpreted as a y pixel coordinate in the menu's coordinate system;
872\item the string \code{"none"}, which indicates no menu entry at all, most
873often used with menu.activate() to deactivate all entries, and
874finally,
875\item a text string that is pattern matched against the label of the
876menu entry, as scanned from the top of the menu to the bottom. Note
877that this index type is considered after all the others, which means
878that matches for menu items labelled \code{last}, \code{active}, or
879\code{none} may be interpreted as the above literals, instead.
880\end{itemize}
881\end{description}
882
883
Fred Drakec66ff202001-11-16 01:05:27 +0000884\section{\module{Tix} ---
885 Extension widgets for Tk}
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000886
887\declaremodule{standard}{Tix}
888\modulesynopsis{Tk Extension Widgets for Tkinter}
889\sectionauthor{Mike Clarkson}{mikeclarkson@users.sourceforge.net}
890
Fred Drakec66ff202001-11-16 01:05:27 +0000891\index{Tix}
892
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000893The \module{Tix} (Tk Interface Extension) module provides an
894additional rich set of widgets. Although the standard Tk library has
895many useful widgets, they are far from complete. The \module{Tix}
896library provides most of the commonly needed widgets that are missing
897from standard Tk: \class{HList}, \class{ComboBox}, \class{Control}
898(a.k.a. SpinBox) and an assortment of scrollable widgets. \module{Tix}
899also includes many more widgets that are generally useful in a wide
900range of applications: \class{NoteBook}, \class{FileEntry},
901\class{PanedWindow}, etc; there are more than 40 of them.
902
903With all these new widgets, you can introduce new interaction
904techniques into applications, creating more useful and more intuitive
905user interfaces. You can design your application by choosing the most
906appropriate widgets to match the special needs of your application and
907users.
908
909\begin{seealso}
910\seetitle[http://tix.sourceforge.net/]
911 {Tix Homepage}
912 {See the home page for \module{Tix}.}
913\seetitle[http://tix.sourceforge.net/dist/current/man/]
914 {Tix Man Pages}
915 {On-line version of the man pages and reference material.}
916\seetitle[http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]
917 {Tix Programming Guide}
918 {On-line version of the programmer's reference material.}
919\seetitle[http://tix.sourceforge.net/Tide/]
920 {Tix Development Applications}
921 {Tix applications for development of Tix and Tkinter programs.
922 Tide applications work under Tk or Tkinter, and include
923 \program{TixInspect}, an inspector to remotely modify and
924 debug Tix/Tk/Tkinter applications.}
925\end{seealso}
926
927
928\subsection{Using Tix}
929
Fred Drake666ca802001-11-16 06:02:55 +0000930\begin{classdesc}{Tix}{screenName\optional{, baseName\optional{, className}}}
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000931 Toplevel widget of Tix which represents mostly the main window
932 of an application. It has an associated Tcl interpreter.
933
Fred Drake666ca802001-11-16 06:02:55 +0000934Classes in the \refmodule{Tix} module subclasses the classes in the
935\refmodule{Tkinter} module. The former imports the latter, so to use
936\refmodule{Tix} with Tkinter, all you need to do is to import one
937module. In general, you can just import \refmodule{Tix}, and replace
938the toplevel call to \class{Tkinter.Tk} with \class{Tix.Tk}:
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000939\begin{verbatim}
940import Tix
941from Tkconstants import *
942root = Tix.Tk()
943\end{verbatim}
944\end{classdesc}
945
946To use \refmodule{Tix}, you must have the \refmodule{Tix} widgets installed,
947usually alongside your installation of the Tk widgets.
948To test your installation, try the following:
949\begin{verbatim}
950import Tix
951root = Tix.Tk()
952root.tk.eval('package require Tix')
953\end{verbatim}
954
955If this fails, you have a Tk installation problem which must be
956resolved before proceeding. Use the environment variable \envvar{TIX_LIBRARY}
957to point to the installed \refmodule{Tix} library directory, and
958make sure you have the dynamic object library (\file{tix8183.dll} or
959\file{libtix8183.so}) in the same directory that contains your Tk
960dynamic object library (\file{tk8183.dll} or \file{libtk8183.so}). The
961directory with the dynamic object library should also have a file
962called \file{pkgIndex.tcl} (case sensitive), which contains the line:
963
964\begin{verbatim}
965package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
966\end{verbatim} % $ <-- bow to font-lock
967
968
969\subsection{Tix Widgets}
970
971\ulink{Tix}
972{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm}
973introduces over 40 widget classes to the \refmodule{Tkinter}
974repertoire. There is a demo of all the \refmodule{Tix} widgets in the
975\file{Demo/tix} directory of the standard distribution.
976
977
978% The Python sample code is still being added to Python, hence commented out
979
980
981\subsubsection{Basic Widgets}
982
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000983\begin{classdesc}{Balloon}{}
984A \ulink{Balloon}
Fred Drakec66ff202001-11-16 01:05:27 +0000985{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm}
986that pops up over a widget to provide help. When the user moves the
987cursor inside a widget to which a Balloon widget has been bound, a
988small pop-up window with a descriptive message will be shown on the
989screen.
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000990\end{classdesc}
991
Fred Drakec66ff202001-11-16 01:05:27 +0000992% Python Demo of:
993% \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000994
Fred Drake7cf4e5b2001-11-15 17:22:04 +0000995\begin{classdesc}{ButtonBox}{}
996The \ulink{ButtonBox}
Fred Drakec66ff202001-11-16 01:05:27 +0000997{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm}
998widget creates a box of buttons, such as is commonly used for \code{Ok
999Cancel}.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001000\end{classdesc}
1001
Fred Drakec66ff202001-11-16 01:05:27 +00001002% Python Demo of:
1003% \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001004
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001005\begin{classdesc}{ComboBox}{}
1006The \ulink{ComboBox}
Fred Drakec66ff202001-11-16 01:05:27 +00001007{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm}
1008widget is similar to the combo box control in MS Windows. The user can
1009select a choice by either typing in the entry subwdget or selecting
1010from the listbox subwidget.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001011\end{classdesc}
1012
Fred Drakec66ff202001-11-16 01:05:27 +00001013% Python Demo of:
1014% \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001015
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001016\begin{classdesc}{Control}{}
1017The \ulink{Control}
Fred Drakec66ff202001-11-16 01:05:27 +00001018{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm}
1019widget is also known as the \class{SpinBox} widget. The user can
1020adjust the value by pressing the two arrow buttons or by entering the
1021value directly into the entry. The new value will be checked against
1022the user-defined upper and lower limits.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001023\end{classdesc}
1024
Fred Drakec66ff202001-11-16 01:05:27 +00001025% Python Demo of:
1026% \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001027
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001028\begin{classdesc}{LabelEntry}{}
1029The \ulink{LabelEntry}
Fred Drakec66ff202001-11-16 01:05:27 +00001030{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm}
1031widget packages an entry widget and a label into one mega widget. It
1032can be used be used to simplify the creation of ``entry-form'' type of
1033interface.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001034\end{classdesc}
1035
1036% Python Demo of:
1037% \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
1038
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001039\begin{classdesc}{LabelFrame}{}
1040The \ulink{LabelFrame}
Fred Drakec66ff202001-11-16 01:05:27 +00001041{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm}
1042widget packages a frame widget and a label into one mega widget. To
1043create widgets inside a LabelFrame widget, one creates the new widgets
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001044relative to the \member{frame} subwidget and manage them inside the
1045\member{frame} subwidget.
1046\end{classdesc}
1047
1048% Python Demo of:
1049% \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
1050
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001051\begin{classdesc}{Meter}{}
1052The \ulink{Meter}
Fred Drakec66ff202001-11-16 01:05:27 +00001053{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm}
1054widget can be used to show the progress of a background job which may
1055take a long time to execute.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001056\end{classdesc}
1057
1058% Python Demo of:
1059% \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
1060
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001061\begin{classdesc}{OptionMenu}{}
1062The \ulink{OptionMenu}
Fred Drakec66ff202001-11-16 01:05:27 +00001063{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm}
1064creates a menu button of options.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001065\end{classdesc}
1066
Fred Drakec66ff202001-11-16 01:05:27 +00001067% Python Demo of:
1068% \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001069
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001070\begin{classdesc}{PopupMenu}{}
1071The \ulink{PopupMenu}
Fred Drakec66ff202001-11-16 01:05:27 +00001072{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm}
1073widget can be used as a replacement of the \code{tk_popup}
1074command. The advantage of the \refmodule{Tix} \class{PopupMenu} widget
1075is it requires less application code to manipulate.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001076\end{classdesc}
1077
Fred Drakec66ff202001-11-16 01:05:27 +00001078% Python Demo of:
1079% \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001080
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001081\begin{classdesc}{Select}{}
1082The \ulink{Select}
Fred Drakec66ff202001-11-16 01:05:27 +00001083{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm}
1084widget is a container of button subwidgets. It can be used to provide
1085radio-box or check-box style of selection options for the user.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001086\end{classdesc}
1087
Fred Drakec66ff202001-11-16 01:05:27 +00001088% Python Demo of:
1089% \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001090
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001091\begin{classdesc}{StdButtonBox}{}
1092The \ulink{StdButtonBox}
Fred Drakec66ff202001-11-16 01:05:27 +00001093{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm}
1094widget is a group of standard buttons for Motif-like dialog boxes.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001095\end{classdesc}
1096
Fred Drakec66ff202001-11-16 01:05:27 +00001097% Python Demo of:
1098% \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001099
1100
1101\subsubsection{File Selectors}
1102
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001103\begin{classdesc}{DirList}{}
1104The \ulink{DirList}
1105{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget
1106displays a list view of a directory, its previous directories and its
1107sub-directories. The user can choose one of the directories displayed
1108in the list or change to another directory.
1109\end{classdesc}
1110
Fred Drakec66ff202001-11-16 01:05:27 +00001111% Python Demo of:
1112% \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001113
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001114\begin{classdesc}{DirTree}{}
1115The \ulink{DirTree}
Fred Drakec66ff202001-11-16 01:05:27 +00001116{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm}
1117widget displays a tree view of a directory, its previous directories
1118and its sub-directories. The user can choose one of the directories
1119displayed in the list or change to another directory.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001120\end{classdesc}
1121
Fred Drakec66ff202001-11-16 01:05:27 +00001122% Python Demo of:
1123% \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001124
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001125\begin{classdesc}{DirSelectDialog}{}
1126The \ulink{DirSelectDialog}
Fred Drakec66ff202001-11-16 01:05:27 +00001127{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm}
1128widget presents the directories in the file system in a dialog
1129window. The user can use this dialog window to navigate through the
1130file system to select the desired directory.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001131\end{classdesc}
1132
Fred Drakec66ff202001-11-16 01:05:27 +00001133% Python Demo of:
1134% \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001135
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001136\begin{classdesc}{DirSelectBox}{}
1137The \class{DirSelectBox} is similar
1138to the standard Motif(TM) directory-selection box. It is generally used for
1139the user to choose a directory. DirSelectBox stores the directories mostly
1140recently selected into a ComboBox widget so that they can be quickly
1141selected again.
1142\end{classdesc}
1143
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001144\begin{classdesc}{ExFileSelectBox}{}
1145The \ulink{ExFileSelectBox}
Fred Drakec66ff202001-11-16 01:05:27 +00001146{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm}
1147widget is usually embedded in a tixExFileSelectDialog widget. It
1148provides an convenient method for the user to select files. The style
1149of the \class{ExFileSelectBox} widget is very similar to the standard
1150file dialog on MS Windows 3.1.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001151\end{classdesc}
1152
Fred Drakec66ff202001-11-16 01:05:27 +00001153% Python Demo of:
1154%\ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001155
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001156\begin{classdesc}{FileSelectBox}{}
1157The \ulink{FileSelectBox}
Fred Drakec66ff202001-11-16 01:05:27 +00001158{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm}
1159is similar to the standard Motif(TM) file-selection box. It is
1160generally used for the user to choose a file. FileSelectBox stores the
1161files mostly recently selected into a \class{ComboBox} widget so that
1162they can be quickly selected again.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001163\end{classdesc}
1164
Fred Drakec66ff202001-11-16 01:05:27 +00001165% Python Demo of:
1166% \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001167
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001168\begin{classdesc}{FileEntry}{}
1169The \ulink{FileEntry}
Fred Drakec66ff202001-11-16 01:05:27 +00001170{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm}
1171widget can be used to input a filename. The user can type in the
1172filename manually. Alternatively, the user can press the button widget
1173that sits next to the entry, which will bring up a file selection
1174dialog.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001175\end{classdesc}
1176
Fred Drakec66ff202001-11-16 01:05:27 +00001177% Python Demo of:
1178% \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001179
1180
1181\subsubsection{Hierachical ListBox}
1182
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001183\begin{classdesc}{HList}{}
1184The \ulink{HList}
Fred Drakec66ff202001-11-16 01:05:27 +00001185{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm}
1186widget can be used to display any data that have a hierarchical
1187structure, for example, file system directory trees. The list entries
1188are indented and connected by branch lines according to their places
1189in the hierachy.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001190\end{classdesc}
1191
Fred Drakec66ff202001-11-16 01:05:27 +00001192% Python Demo of:
1193% \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001194
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001195\begin{classdesc}{CheckList}{}
1196The \ulink{CheckList}
Fred Drakec66ff202001-11-16 01:05:27 +00001197{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm}
1198widget displays a list of items to be selected by the user. CheckList
1199acts similarly to the Tk checkbutton or radiobutton widgets, except it
1200is capable of handling many more items than checkbuttons or
1201radiobuttons.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001202\end{classdesc}
1203
Fred Drakec66ff202001-11-16 01:05:27 +00001204% Python Demo of:
1205% \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
1206% Python Demo of:
1207% \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
1208% Python Demo of:
1209% \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001210
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001211\begin{classdesc}{Tree}{}
1212The \ulink{Tree}
Fred Drakec66ff202001-11-16 01:05:27 +00001213{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm}
1214widget can be used to display hierachical data in a tree form. The
1215user can adjust the view of the tree by opening or closing parts of
1216the tree.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001217\end{classdesc}
1218
Fred Drakec66ff202001-11-16 01:05:27 +00001219% Python Demo of:
1220% \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001221
Fred Drakec66ff202001-11-16 01:05:27 +00001222% Python Demo of:
1223% \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001224
1225
1226\subsubsection{Tabular ListBox}
1227
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001228\begin{classdesc}{TList}{}
1229The \ulink{TList}
Fred Drakec66ff202001-11-16 01:05:27 +00001230{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm}
1231widget can be used to display data in a tabular format. The list
1232entries of a \class{TList} widget are similar to the entries in the Tk
1233listbox widget. The main differences are (1) the \class{TList} widget
1234can display the list entries in a two dimensional format and (2) you
1235can use graphical images as well as multiple colors and fonts for the
1236list entries.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001237\end{classdesc}
1238
Fred Drakec66ff202001-11-16 01:05:27 +00001239% Python Demo of:
1240% \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
1241% Python Demo of:
1242% \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001243
1244% Grid has yet to be added to Python
1245% \subsubsection{Grid Widget}
Fred Drakec66ff202001-11-16 01:05:27 +00001246% Python Demo of:
1247% \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
1248% Python Demo of:
1249% \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
1250% Python Demo of:
1251% \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001252
1253
1254\subsubsection{Manager Widgets}
1255
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001256\begin{classdesc}{PanedWindow}{}
1257The \ulink{PanedWindow}
Fred Drakec66ff202001-11-16 01:05:27 +00001258{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm}
1259widget allows the user to interactively manipulate the sizes of
1260several panes. The panes can be arranged either vertically or
1261horizontally. The user changes the sizes of the panes by dragging the
1262resize handle between two panes.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001263\end{classdesc}
1264
Fred Drakec66ff202001-11-16 01:05:27 +00001265% Python Demo of:
1266% \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001267
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001268\begin{classdesc}{ListNoteBook}{}
1269The \ulink{ListNoteBook}
Fred Drakec66ff202001-11-16 01:05:27 +00001270{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm}
1271widget is very similar to the \class{TixNoteBook} widget: it can be
1272used to display many windows in a limited space using a notebook
1273metaphor. The notebook is divided into a stack of pages (windows). At
1274one time only one of these pages can be shown. The user can navigate
1275through these pages by choosing the name of the desired page in the
1276\member{hlist} subwidget.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001277\end{classdesc}
1278
Fred Drakec66ff202001-11-16 01:05:27 +00001279% Python Demo of:
1280% \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001281
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001282\begin{classdesc}{NoteBook}{}
1283The \ulink{NoteBook}
Fred Drakec66ff202001-11-16 01:05:27 +00001284{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm}
1285widget can be used to display many windows in a limited space using a
1286notebook metaphor. The notebook is divided into a stack of pages. At
1287one time only one of these pages can be shown. The user can navigate
1288through these pages by choosing the visual ``tabs'' at the top of the
1289NoteBook widget.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001290\end{classdesc}
1291
Fred Drakec66ff202001-11-16 01:05:27 +00001292% Python Demo of:
1293% \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001294
1295
1296% \subsubsection{Scrolled Widgets}
Fred Drakec66ff202001-11-16 01:05:27 +00001297% Python Demo of:
1298% \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
1299% Python Demo of:
1300% \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
1301% Python Demo of:
1302% \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
1303% Python Demo of:
1304% \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001305
1306
1307\subsubsection{Image Types}
1308
1309The \refmodule{Tix} module adds:
1310\begin{itemize}
1311\item
1312\ulink{pixmap}
Fred Drake666ca802001-11-16 06:02:55 +00001313{http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm}
1314capabilities to all \refmodule{Tix} and \refmodule{Tkinter} widgets to
1315create color images from XPM files.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001316
1317% Python Demo of: \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
1318
1319% Python Demo of: \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
1320
1321\item
1322\ulink{Compound}
Fred Drake666ca802001-11-16 06:02:55 +00001323{http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.html}
1324image types can be used to create images that consists of multiple
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001325horizontal lines; each line is composed of a series of items (texts,
1326bitmaps, images or spaces) arranged from left to right. For example, a
1327compound image can be used to display a bitmap and a text string
1328simutaneously in a Tk \class{Button} widget.
1329
Fred Drake666ca802001-11-16 06:02:55 +00001330% Python Demo of:
1331% \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001332
Fred Drake666ca802001-11-16 06:02:55 +00001333% Python Demo of:
1334% \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001335
Fred Drake666ca802001-11-16 06:02:55 +00001336% Python Demo of:
1337% \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001338
Fred Drake666ca802001-11-16 06:02:55 +00001339% Python Demo of:
1340% \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001341\end{itemize}
1342
1343
1344\subsubsection{Miscellaneous Widgets}
1345
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001346\begin{classdesc}{InputOnly}{}
1347The \ulink{InputOnly}
Fred Drake666ca802001-11-16 06:02:55 +00001348{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm}
1349widgets are to accept inputs from the user, which can be done with the
1350\code{bind} command (\UNIX{} only).
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001351\end{classdesc}
1352
1353\subsubsection{Form Geometry Manager}
1354
1355In addition, \refmodule{Tix} augments \refmodule{Tkinter} by providing:
Fred Drake666ca802001-11-16 06:02:55 +00001356
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001357\begin{classdesc}{Form}{}
1358The \ulink{Form}
Fred Drake666ca802001-11-16 06:02:55 +00001359{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm}
1360geometry manager based on attachment rules for all Tk widgets.
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001361\end{classdesc}
1362
1363
1364%begin{latexonly}
1365%\subsection{Tix Class Structure}
1366%
1367%\begin{figure}[hbtp]
1368%\centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}}
1369%\vspace{.5cm}
1370%\caption{The Class Hierarchy of Tix Widgets}
1371%\end{figure}
1372%end{latexonly}
1373
Fred Drake44b6f842001-11-29 21:09:08 +00001374\subsection{Tix Commands}
1375
1376\begin{classdesc}{tixCommand}{}
1377The \ulink{tix commands}
1378{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm}
1379provide access to miscellaneous elements of \refmodule{Tix}'s internal
1380state and the \refmodule{Tix} application context. Most of the information
1381manipulated by these methods pertains to the application as a whole,
1382or to a screen or display, rather than to a particular window.
1383
1384To view the current settings, the common usage is:
1385\begin{verbatim}
1386import Tix
1387root = Tix.Tk()
1388print root.tix_configure()
1389\end{verbatim}
1390\end{classdesc}
1391
1392\begin{methoddesc}{tix_configure}{\optional{cnf,} **kw}
1393Query or modify the configuration options of the Tix application
1394context. If no option is specified, returns a dictionary all of the
1395available options. If option is specified with no value, then the
1396method returns a list describing the one named option (this list will
1397be identical to the corresponding sublist of the value returned if no
1398option is specified). If one or more option-value pairs are
1399specified, then the method modifies the given option(s) to have the
1400given value(s); in this case the method returns an empty string.
1401Option may be any of the configuration options.
1402\end{methoddesc}
1403
1404\begin{methoddesc}{tix_cget}{option}
1405Returns the current value of the configuration option given by
1406\var{option}. Option may be any of the configuration options.
1407\end{methoddesc}
1408
1409\begin{methoddesc}{tix_getbitmap}{name}
1410Locates a bitmap file of the name \code{name.xpm} or \code{name} in
1411one of the bitmap directories (see the \method{tix_addbitmapdir()}
1412method). By using \method{tix_getbitmap()}, you can avoid hard
1413coding the pathnames of the bitmap files in your application. When
1414successful, it returns the complete pathname of the bitmap file,
1415prefixed with the character \samp{@}. The returned value can be used to
1416configure the \code{bitmap} option of the Tk and Tix widgets.
1417\end{methoddesc}
1418
1419\begin{methoddesc}{tix_addbitmapdir}{directory}
1420Tix maintains a list of directories under which the
1421\method{tix_getimage()} and \method{tix_getbitmap()} methods will
1422search for image files. The standard bitmap directory is
1423\file{\$TIX_LIBRARY/bitmaps}. The \method{tix_addbitmapdir()} method
1424adds \var{directory} into this list. By using this method, the image
1425files of an applications can also be located using the
1426\method{tix_getimage()} or \method{tix_getbitmap()} method.
1427\end{methoddesc}
1428
1429\begin{methoddesc}{tix_filedialog}{\optional{dlgclass}}
1430Returns the file selection dialog that may be shared among different
1431calls from this application. This method will create a file selection
1432dialog widget when it is called the first time. This dialog will be
1433returned by all subsequent calls to \method{tix_filedialog()}. An
1434optional dlgclass parameter can be passed as a string to specified
1435what type of file selection dialog widget is desired. Possible
1436options are \code{tix}, \code{FileSelectDialog} or
1437\code{tixExFileSelectDialog}.
1438\end{methoddesc}
1439
1440
1441\begin{methoddesc}{tix_getimage}{self, name}
1442Locates an image file of the name \file{name.xpm}, \file{name.xbm} or
1443\file{name.ppm} in one of the bitmap directories (see the
1444\method{tix_addbitmapdir()} method above). If more than one file with
1445the same name (but different extensions) exist, then the image type is
1446chosen according to the depth of the X display: xbm images are chosen
1447on monochrome displays and color images are chosen on color
1448displays. By using \method{tix_getimage()}, you can avoid hard coding
1449the pathnames of the image files in your application. When successful,
1450this method returns the name of the newly created image, which can be
1451used to configure the \code{image} option of the Tk and Tix widgets.
1452\end{methoddesc}
1453
1454\begin{methoddesc}{tix_option_get}{name}
1455Gets the options manitained by the Tix scheme mechanism.
1456\end{methoddesc}
1457
1458\begin{methoddesc}{tix_resetoptions}{newScheme, newFontSet\optional{,
1459 newScmPrio}}
1460Resets the scheme and fontset of the Tix application to
1461\var{newScheme} and \var{newFontSet}, respectively. This affects only
1462those widgets created after this call. Therefore, it is best to call
1463the resetoptions method before the creation of any widgets in a Tix
1464application.
1465
1466The optional parameter \var{newScmPrio} can be given to reset the
1467priority level of the Tk options set by the Tix schemes.
1468
1469Because of the way Tk handles the X option database, after Tix has
1470been has imported and inited, it is not possible to reset the color
1471schemes and font sets using the \method{tix_config()} method.
1472Instead, the \method{tix_resetoptions()} method must be used.
1473\end{methoddesc}
1474
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001475
Fred Drake1a763862001-12-03 21:18:30 +00001476
1477\section{\module{ScrolledText} ---
1478 Scrolled Text Widget}
1479
1480\declaremodule{standard}{ScrolledText}
1481 \platform{Tk}
1482\modulesynopsis{Text widget with a vertical scroll bar.}
1483\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
1484
1485The \module{ScrolledText} module provides a class of the same name
1486which implements a basic text widget which has a vertical scroll bar
1487configured to do the ``right thing.'' Using the \class{ScrolledText}
1488class is a lot easier than setting up a text widget and scroll bar
1489directly. The constructor is the same as that of the
1490\class{Tkinter.Text} class.
1491
1492The text widget and scrollbar are packed together in a \class{Frame},
1493and the methods of the \class{Pack} geometry manager are acquired from
1494the \class{Frame} object. This allows the \class{ScrolledText} widget
1495to be used directly to achieve most normal geometry management
1496behavior.
1497
1498Should more specific control be necessary, the following attributes
1499are available:
1500
1501\begin{memberdesc}[ScrolledText]{frame}
1502 The frame which surrounds the text and scroll bar widgets.
1503\end{memberdesc}
1504
1505\begin{memberdesc}[ScrolledText]{vbar}
1506 The scroll bar widget.
1507\end{memberdesc}
1508
1509
Fred Drakec66ff202001-11-16 01:05:27 +00001510\input{libturtle}
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001511
1512
1513\section{Idle \label{idle}}
1514
1515%\declaremodule{standard}{idle}
1516%\modulesynopsis{A Python Integrated Developement Environment}
1517\moduleauthor{Guido van Rossum}{guido@Python.org}
1518
1519Idle is the Python IDE built with the \refmodule{Tkinter} GUI toolkit.
1520\index{Idle}
1521\index{Python Editor}
1522\index{Integrated Developement Environment}
1523
1524
1525IDLE has the following features:
1526
1527\begin{itemize}
1528\item coded in 100\% pure Python, using the \refmodule{Tkinter} GUI toolkit
1529
1530\item cross-platform: works on Windows and \UNIX{} (on Mac OS, there are
1531currently problems with Tcl/Tk)
1532
1533\item multi-window text editor with multiple undo, Python colorizing
1534and many other features, e.g. smart indent and call tips
1535
1536\item Python shell window (a.k.a. interactive interpreter)
1537
1538\item debugger (not complete, but you can set breakpoints, view and step)
1539\end{itemize}
1540
1541
1542\subsection{Menus}
1543
1544\subsubsection{File menu}
1545
1546\begin{description}
1547\item[New window] create a new editing window
1548\item[Open...] open an existing file
1549\item[Open module...] open an existing module (searches sys.path)
1550\item[Class browser] show classes and methods in current file
1551\item[Path browser] show sys.path directories, modules, classes and methods
1552\end{description}
1553\index{Class browser}
1554\index{Path browser}
1555
1556\begin{description}
1557\item[Save] save current window to the associated file (unsaved
1558windows have a * before and after the window title)
1559
1560\item[Save As...] save current window to new file, which becomes
1561the associated file
1562\item[Save Copy As...] save current window to different file
1563without changing the associated file
1564\end{description}
1565
1566\begin{description}
1567\item[Close] close current window (asks to save if unsaved)
1568\item[Exit] close all windows and quit IDLE (asks to save if unsaved)
1569\end{description}
1570
1571
1572\subsubsection{Edit menu}
1573
1574\begin{description}
1575\item[Undo] Undo last change to current window (max 1000 changes)
1576\item[Redo] Redo last undone change to current window
1577\end{description}
1578
1579\begin{description}
1580\item[Cut] Copy selection into system-wide clipboard; then delete selection
1581\item[Copy] Copy selection into system-wide clipboard
1582\item[Paste] Insert system-wide clipboard into window
1583\item[Select All] Select the entire contents of the edit buffer
1584\end{description}
1585
1586\begin{description}
1587\item[Find...] Open a search dialog box with many options
1588\item[Find again] Repeat last search
1589\item[Find selection] Search for the string in the selection
1590\item[Find in Files...] Open a search dialog box for searching files
1591\item[Replace...] Open a search-and-replace dialog box
1592\item[Go to line] Ask for a line number and show that line
1593\end{description}
1594
1595\begin{description}
1596\item[Indent region] Shift selected lines right 4 spaces
1597\item[Dedent region] Shift selected lines left 4 spaces
1598\item[Comment out region] Insert \#\# in front of selected lines
1599\item[Uncomment region] Remove leading \# or \#\# from selected lines
1600\item[Tabify region] Turns \emph{leading} stretches of spaces into tabs
1601\item[Untabify region] Turn \emph{all} tabs into the right number of spaces
1602\item[Expand word] Expand the word you have typed to match another
1603 word in the same buffer; repeat to get a different expansion
1604\item[Format Paragraph] Reformat the current blank-line-separated paragraph
1605\end{description}
1606
1607\begin{description}
1608\item[Import module] Import or reload the current module
1609\item[Run script] Execute the current file in the __main__ namespace
1610\end{description}
1611
1612\index{Import module}
1613\index{Run script}
1614
1615
1616\subsubsection{Windows menu}
1617
1618\begin{description}
1619\item[Zoom Height] toggles the window between normal size (24x80)
1620 and maximum height.
1621\end{description}
1622
1623The rest of this menu lists the names of all open windows; select one
1624to bring it to the foreground (deiconifying it if necessary).
1625
1626
1627\subsubsection{Debug menu (in the Python Shell window only)}
1628
1629\begin{description}
1630\item[Go to file/line] look around the insert point for a filename
1631 and linenumber, open the file, and show the line.
1632\item[Open stack viewer] show the stack traceback of the last exception
1633\item[Debugger toggle] Run commands in the shell under the debugger
1634\item[JIT Stack viewer toggle] Open stack viewer on traceback
1635\end{description}
1636
1637\index{stack viewer}
1638\index{debugger}
1639
1640
1641\subsection{Basic editing and navigation}
1642
1643\begin{itemize}
1644\item \kbd{Backspace} deletes to the left; \kbd{Del} deletes to the right
1645\item Arrow keys and \kbd{Page Up}/\kbd{Page Down} to move around
1646\item \kbd{Home}/\kbd{End} go to begin/end of line
1647\item \kbd{C-Home}/\kbd{C-End} go to begin/end of file
1648\item Some \program{Emacs} bindings may also work, including \kbd{C-B},
1649 \kbd{C-P}, \kbd{C-A}, \kbd{C-E}, \kbd{C-D}, \kbd{C-L}
1650\end{itemize}
1651
1652
1653\subsubsection{Automatic indentation}
1654
1655After a block-opening statement, the next line is indented by 4 spaces
1656(in the Python Shell window by one tab). After certain keywords
1657(break, return etc.) the next line is dedented. In leading
1658indentation, \kbd{Backspace} deletes up to 4 spaces if they are there.
1659\kbd{Tab} inserts 1-4 spaces (in the Python Shell window one tab).
1660See also the indent/dedent region commands in the edit menu.
1661
1662
1663\subsubsection{Python Shell window}
1664
1665\begin{itemize}
1666\item \kbd{C-C} interrupts executing command
1667\item \kbd{C-D} sends end-of-file; closes window if typed at
1668a \samp{>>>~} prompt
1669\end{itemize}
1670
1671\begin{itemize}
Fred Drake666ca802001-11-16 06:02:55 +00001672\item \kbd{Alt-p} retrieves previous command matching what you have typed
1673\item \kbd{Alt-n} retrieves next
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001674\item \kbd{Return} while on any previous command retrieves that command
Fred Drake666ca802001-11-16 06:02:55 +00001675\item \kbd{Alt-/} (Expand word) is also useful here
Fred Drake7cf4e5b2001-11-15 17:22:04 +00001676\end{itemize}
1677
1678\index{indentation}
1679
1680
1681\subsection{Syntax colors}
1682
1683The coloring is applied in a background ``thread,'' so you may
1684occasionally see uncolorized text. To change the color
1685scheme, edit the \code{[Colors]} section in \file{config.txt}.
1686
1687\begin{description}
1688\item[Python syntax colors:]
1689
1690\begin{description}
1691\item[Keywords] orange
1692\item[Strings ] green
1693\item[Comments] red
1694\item[Definitions] blue
1695\end{description}
1696
1697\item[Shell colors:]
1698\begin{description}
1699\item[Console output] brown
1700\item[stdout] blue
1701\item[stderr] dark green
1702\item[stdin] black
1703\end{description}
1704\end{description}
1705
1706
1707\subsubsection{Command line usage}
1708
1709\begin{verbatim}
1710idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
1711
1712-c command run this command
1713-d enable debugger
1714-e edit mode; arguments are files to be edited
1715-s run $IDLESTARTUP or $PYTHONSTARTUP first
1716-t title set title of shell window
1717\end{verbatim}
1718
1719If there are arguments:
1720
1721\begin{enumerate}
1722\item If \programopt{-e} is used, arguments are files opened for
1723 editing and \code{sys.argv} reflects the arguments passed to
1724 IDLE itself.
1725
1726\item Otherwise, if \programopt{-c} is used, all arguments are
1727 placed in \code{sys.argv[1:...]}, with \code{sys.argv[0]} set
1728 to \code{'-c'}.
1729
1730\item Otherwise, if neither \programopt{-e} nor \programopt{-c} is
1731 used, the first argument is a script which is executed with
1732 the remaining arguments in \code{sys.argv[1:...]} and
1733 \code{sys.argv[0]} set to the script name. If the script name
1734 is '-', no script is executed but an interactive Python
1735 session is started; the arguments are still available in
1736 \code{sys.argv}.
1737\end{enumerate}
Fred Drakec66ff202001-11-16 01:05:27 +00001738
1739
1740\section{Other Graphical User Interface Packages
1741 \label{other-gui-packages}}
1742
1743
1744There are an number of extension widget sets to \refmodule{Tkinter}.
1745
Fred Drake10cd3152001-11-30 18:17:24 +00001746\begin{seealso*}
Fred Drakec66ff202001-11-16 01:05:27 +00001747\seetitle[http://pmw.sourceforge.net/]{Python megawidgets}{is a
1748toolkit for building high-level compound widgets in Python using the
1749\refmodule{Tkinter} module. It consists of a set of base classes and
1750a library of flexible and extensible megawidgets built on this
1751foundation. These megawidgets include notebooks, comboboxes, selection
1752widgets, paned widgets, scrolled widgets, dialog windows, etc. Also,
1753with the Pmw.Blt interface to BLT, the busy, graph, stripchart, tabset
1754and vector commands are be available.
1755
1756The initial ideas for Pmw were taken from the Tk \code{itcl}
1757extensions \code{[incr Tk]} by Michael McLennan and \code{[incr
1758Widgets]} by Mark Ulferts. Several of the megawidgets are direct
1759translations from the itcl to Python. It offers most of the range of
1760widgets that \code{[incr Widgets]} does, and is almost as complete as
1761Tix, lacking however Tix's fast \class{HList} widget for drawing trees.
1762}
1763\seetitle[http://tkinter.effbot.org]{Tkinter3000}{
1764is a Widget Construction Kit that allows you to write new Tkinter
1765widgets in Python using Mixins. It is built on top of Tkinter,
1766and does not offer the extended range of widgets that \refmodule{Tix} does,
1767but does allow a form of building mega-widgets. The project is
1768still in the early stages.
1769}
Fred Drake10cd3152001-11-30 18:17:24 +00001770\end{seealso*}
Fred Drakec66ff202001-11-16 01:05:27 +00001771
1772
Fred Drake666ca802001-11-16 06:02:55 +00001773Tk is not the only GUI for Python, but is however the
Fred Drakec66ff202001-11-16 01:05:27 +00001774most commonly used one.
1775
Fred Drake10cd3152001-11-30 18:17:24 +00001776\begin{seealso*}
Fred Drakec66ff202001-11-16 01:05:27 +00001777\seetitle[http://www.wxwindows.org]{wxWindows}{
1778is a GUI toolkit that combines the most attractive attributes of Qt,
1779Tk, Motif, and GTK+ in one powerful and efficient package. It is
Fred Drakec37b65e2001-11-28 07:26:15 +00001780implemented in \Cpp. wxWindows supports two flavors of \UNIX{}
Fred Drakec66ff202001-11-16 01:05:27 +00001781implementation: GTK+ and Motif, and under Windows, it has a standard
1782Microsoft Foundation Classes (MFC) appearance, because it uses Win32
1783widgets. There is a Python class wrapper, independent of Tkinter.
1784
1785wxWindows is much richer in widgets than \refmodule{Tkinter}, with its
1786help system, sophisticated HTML and image viewers, and other
1787specialized widgets, extensive documentation, and printing capabilities.
1788}
1789\seetitle[http://www.thekompany.com]{PyKDE}{
1790PyKDE is a SIP wrapped interface to the Qt toolkit.
1791The Qt \Cpp{} toolkit lies at the heart of the KDE desktop, and the
1792Qt toolkit allows very tight integration with KDE, and also Windows
1793portability. SIP is a tool for generating bindings for \Cpp{} libraries
1794as Python classes, and is specifically designed for Python.
1795}
1796\seetitle[http://fxpy.sourceforge.net/]{FXPy}{
1797is a Python extension module which provides an interface to the
1798\citetitle[http://www.cfdrc.com/FOX/fox.html]{FOX} GUI.
1799FOX is a \Cpp{} based Toolkit for developing Graphical User Interfaces
1800easily and effectively. It offers a wide, and growing, collection of
1801Controls, and provides state of the art facilities such as drag and
1802drop, selection, as well as OpenGL widgets for 3D graphical
1803manipulation. FOX also implements icons, images, and user-convenience
1804features such as status line help, and tooltips.
1805
1806Even though FOX offers a large collection of controls already, FOX
1807leverages \Cpp{} to allow programmers to easily build additional Controls
1808and GUI elements, simply by taking existing controls, and creating a
1809derived class which simply adds or redefines the desired behavior.
1810}
1811\seetitle[http://www.daa.com.au/\~james/pygtk/]{PyGTK}{
1812is a set of bindings for the \ulink{GTK}{http://www.gtk.org/} widget set.
1813It provides an object oriented interface that is slightly higher
1814level than the C one. It automatically does all the type casting and
1815reference counting that you would have to do normally with the C
1816API. There are also \ulink{bindings}{http://www.daa.com.au/\~james/gnome/}
1817to \ulink{GNOME}{http://www.gnome.org}, and a
1818\ulink{tutorial}
1819{http://laguna.fmedic.unam.mx/\~daniel/pygtutorial/pygtutorial/index.html}
1820is available.
1821}
Fred Drake10cd3152001-11-30 18:17:24 +00001822\end{seealso*}
Fred Drakec66ff202001-11-16 01:05:27 +00001823
1824% XXX Reference URLs that compare the different UI packages