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