Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 1 | :mod:`tkinter` --- Python interface to Tcl/Tk |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2 | ============================================= |
| 3 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 4 | .. module:: tkinter |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | :synopsis: Interface to Tcl/Tk for graphical user interfaces |
| 6 | .. moduleauthor:: Guido van Rossum <guido@Python.org> |
| 7 | |
| 8 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 9 | The :mod:`tkinter` package ("Tk interface") is the standard Python interface to |
| 10 | the Tk GUI toolkit. Both Tk and :mod:`tkinter` are available on most Unix |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 11 | platforms, as well as on Windows systems. (Tk itself is not part of Python; it |
| 12 | is maintained at ActiveState.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | .. seealso:: |
| 15 | |
| 16 | `Python Tkinter Resources <http://www.python.org/topics/tkinter/>`_ |
| 17 | The Python Tkinter Topic Guide provides a great deal of information on using Tk |
| 18 | from Python and links to other sources of information on Tk. |
| 19 | |
| 20 | `An Introduction to Tkinter <http://www.pythonware.com/library/an-introduction-to-tkinter.htm>`_ |
| 21 | Fredrik Lundh's on-line reference material. |
| 22 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 23 | `Tkinter reference: a GUI for Python <http://infohost.nmt.edu/tcc/help/pubs/lang.html>`_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | On-line reference material. |
| 25 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | `Python and Tkinter Programming <http://www.amazon.com/exec/obidos/ASIN/1884777813>`_ |
| 27 | The book by John Grayson (ISBN 1-884777-81-3). |
| 28 | |
| 29 | |
| 30 | Tkinter Modules |
| 31 | --------------- |
| 32 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 33 | Most of the time, :mod:`tkinter` is all you really need, but a number of |
| 34 | additional modules are available as well. The Tk interface is located in a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | binary module named :mod:`_tkinter`. This module contains the low-level |
| 36 | interface to Tk, and should never be used directly by application programmers. |
| 37 | It is usually a shared library (or DLL), but might in some cases be statically |
| 38 | linked with the Python interpreter. |
| 39 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 40 | In addition to the Tk interface module, :mod:`tkinter` includes a number of |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 41 | Python modules, :mod:`tkinter.constants` being one of the most important. |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 42 | Importing :mod:`tkinter` will automatically import :mod:`tkinter.constants`, |
| 43 | so, usually, to use Tkinter all you need is a simple import statement:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 45 | import tkinter |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
| 47 | Or, more often:: |
| 48 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 49 | from tkinter import * |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
| 51 | |
| 52 | .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1) |
| 53 | |
| 54 | The :class:`Tk` class is instantiated without arguments. This creates a toplevel |
| 55 | widget of Tk which usually is the main window of an application. Each instance |
| 56 | has its own associated Tcl interpreter. |
| 57 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 58 | .. FIXME: The following keyword arguments are currently recognized: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) |
| 62 | |
| 63 | The :func:`Tcl` function is a factory function which creates an object much like |
| 64 | that created by the :class:`Tk` class, except that it does not initialize the Tk |
| 65 | subsystem. This is most often useful when driving the Tcl interpreter in an |
| 66 | environment where one doesn't want to create extraneous toplevel windows, or |
| 67 | where one cannot (such as Unix/Linux systems without an X server). An object |
| 68 | created by the :func:`Tcl` object can have a Toplevel window created (and the Tk |
| 69 | subsystem initialized) by calling its :meth:`loadtk` method. |
| 70 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | Other modules that provide Tk support include: |
| 73 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 74 | :mod:`tkinter.scrolledtext` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | Text widget with a vertical scroll bar built in. |
| 76 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 77 | :mod:`tkinter.colorchooser` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | Dialog to let the user choose a color. |
| 79 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 80 | :mod:`tkinter.commondialog` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | Base class for the dialogs defined in the other modules listed here. |
| 82 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 83 | :mod:`tkinter.filedialog` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | Common dialogs to allow the user to specify a file to open or save. |
| 85 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 86 | :mod:`tkinter.font` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | Utilities to help work with fonts. |
| 88 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 89 | :mod:`tkinter.messagebox` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | Access to standard Tk dialog boxes. |
| 91 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 92 | :mod:`tkinter.simpledialog` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | Basic dialogs and convenience functions. |
| 94 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 95 | :mod:`tkinter.dnd` |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 96 | Drag-and-drop support for :mod:`tkinter`. This is experimental and should |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 97 | become deprecated when it is replaced with the Tk DND. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
Georg Brandl | 23d11d3 | 2008-09-21 07:50:52 +0000 | [diff] [blame] | 99 | :mod:`turtle` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | Turtle graphics in a Tk window. |
| 101 | |
| 102 | |
| 103 | Tkinter Life Preserver |
| 104 | ---------------------- |
| 105 | |
| 106 | .. sectionauthor:: Matt Conway |
| 107 | |
| 108 | |
| 109 | This section is not designed to be an exhaustive tutorial on either Tk or |
| 110 | Tkinter. Rather, it is intended as a stop gap, providing some introductory |
| 111 | orientation on the system. |
| 112 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | Credits: |
| 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | * Tk was written by John Ousterhout while at Berkeley. |
| 116 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 117 | * Tkinter was written by Steen Lumholt and Guido van Rossum. |
| 118 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | * This Life Preserver was written by Matt Conway at the University of Virginia. |
| 120 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 121 | * The HTML rendering, and some liberal editing, was produced from a FrameMaker |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | version by Ken Manheimer. |
| 123 | |
| 124 | * Fredrik Lundh elaborated and revised the class interface descriptions, to get |
| 125 | them current with Tk 4.2. |
| 126 | |
| 127 | * Mike Clarkson converted the documentation to LaTeX, and compiled the User |
| 128 | Interface chapter of the reference manual. |
| 129 | |
| 130 | |
| 131 | How To Use This Section |
| 132 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 133 | |
| 134 | This section is designed in two parts: the first half (roughly) covers |
| 135 | background material, while the second half can be taken to the keyboard as a |
| 136 | handy reference. |
| 137 | |
| 138 | When trying to answer questions of the form "how do I do blah", it is often best |
| 139 | to find out how to do"blah" in straight Tk, and then convert this back into the |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 140 | corresponding :mod:`tkinter` call. Python programmers can often guess at the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | correct Python command by looking at the Tk documentation. This means that in |
| 142 | order to use Tkinter, you will have to know a little bit about Tk. This document |
| 143 | can't fulfill that role, so the best we can do is point you to the best |
| 144 | documentation that exists. Here are some hints: |
| 145 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 146 | * The authors strongly suggest getting a copy of the Tk man pages. |
| 147 | Specifically, the man pages in the ``manN`` directory are most useful. |
| 148 | The ``man3`` man pages describe the C interface to the Tk library and thus |
| 149 | are not especially helpful for script writers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | * Addison-Wesley publishes a book called Tcl and the Tk Toolkit by John |
| 152 | Ousterhout (ISBN 0-201-63337-X) which is a good introduction to Tcl and Tk for |
| 153 | the novice. The book is not exhaustive, and for many details it defers to the |
| 154 | man pages. |
| 155 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 156 | * :file:`tkinter/__init__.py` is a last resort for most, but can be a good |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 157 | place to go when nothing else makes sense. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
| 159 | |
| 160 | .. seealso:: |
| 161 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 162 | `Tcl/Tk 8.6 man pages <http://www.tcl.tk/man/tcl8.6/>`_ |
| 163 | The Tcl/Tk manual on www.tcl.tk. |
| 164 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 165 | `ActiveState Tcl Home Page <http://tcl.activestate.com/>`_ |
| 166 | The Tk/Tcl development is largely taking place at ActiveState. |
| 167 | |
| 168 | `Tcl and the Tk Toolkit <http://www.amazon.com/exec/obidos/ASIN/020163337X>`_ |
| 169 | The book by John Ousterhout, the inventor of Tcl . |
| 170 | |
| 171 | `Practical Programming in Tcl and Tk <http://www.amazon.com/exec/obidos/ASIN/0130220280>`_ |
| 172 | Brent Welch's encyclopedic book. |
| 173 | |
| 174 | |
| 175 | A Simple Hello World Program |
| 176 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 177 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | :: |
| 179 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 180 | from tkinter import * |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 181 | |
| 182 | class Application(Frame): |
| 183 | def say_hi(self): |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 184 | print("hi there, everyone!") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 185 | |
| 186 | def createWidgets(self): |
| 187 | self.QUIT = Button(self) |
| 188 | self.QUIT["text"] = "QUIT" |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 189 | self.QUIT["fg"] = "red" |
| 190 | self.QUIT["command"] = self.quit |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
| 192 | self.QUIT.pack({"side": "left"}) |
| 193 | |
| 194 | self.hi_there = Button(self) |
| 195 | self.hi_there["text"] = "Hello", |
| 196 | self.hi_there["command"] = self.say_hi |
| 197 | |
| 198 | self.hi_there.pack({"side": "left"}) |
| 199 | |
| 200 | def __init__(self, master=None): |
| 201 | Frame.__init__(self, master) |
| 202 | self.pack() |
| 203 | self.createWidgets() |
| 204 | |
| 205 | root = Tk() |
| 206 | app = Application(master=root) |
| 207 | app.mainloop() |
| 208 | root.destroy() |
| 209 | |
| 210 | |
| 211 | A (Very) Quick Look at Tcl/Tk |
| 212 | ----------------------------- |
| 213 | |
| 214 | The class hierarchy looks complicated, but in actual practice, application |
| 215 | programmers almost always refer to the classes at the very bottom of the |
| 216 | hierarchy. |
| 217 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | Notes: |
| 219 | |
| 220 | * These classes are provided for the purposes of organizing certain functions |
| 221 | under one namespace. They aren't meant to be instantiated independently. |
| 222 | |
| 223 | * The :class:`Tk` class is meant to be instantiated only once in an application. |
| 224 | Application programmers need not instantiate one explicitly, the system creates |
| 225 | one whenever any of the other classes are instantiated. |
| 226 | |
| 227 | * The :class:`Widget` class is not meant to be instantiated, it is meant only |
| 228 | for subclassing to make "real" widgets (in C++, this is called an 'abstract |
| 229 | class'). |
| 230 | |
| 231 | To make use of this reference material, there will be times when you will need |
| 232 | to know how to read short passages of Tk and how to identify the various parts |
| 233 | of a Tk command. (See section :ref:`tkinter-basic-mapping` for the |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 234 | :mod:`tkinter` equivalents of what's below.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | |
| 236 | Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are just lists |
| 237 | of tokens separated by spaces. A Tk widget is just its *class*, the *options* |
| 238 | that help configure it, and the *actions* that make it do useful things. |
| 239 | |
| 240 | To make a widget in Tk, the command is always of the form:: |
| 241 | |
| 242 | classCommand newPathname options |
| 243 | |
| 244 | *classCommand* |
| 245 | denotes which kind of widget to make (a button, a label, a menu...) |
| 246 | |
| 247 | *newPathname* |
| 248 | is the new name for this widget. All names in Tk must be unique. To help |
| 249 | enforce this, widgets in Tk are named with *pathnames*, just like files in a |
| 250 | file system. The top level widget, the *root*, is called ``.`` (period) and |
| 251 | children are delimited by more periods. For example, |
| 252 | ``.myApp.controlPanel.okButton`` might be the name of a widget. |
| 253 | |
| 254 | *options* |
| 255 | configure the widget's appearance and in some cases, its behavior. The options |
| 256 | come in the form of a list of flags and values. Flags are preceded by a '-', |
| 257 | like Unix shell command flags, and values are put in quotes if they are more |
| 258 | than one word. |
| 259 | |
| 260 | For example:: |
| 261 | |
| 262 | button .fred -fg red -text "hi there" |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 263 | ^ ^ \______________________/ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | | | | |
| 265 | class new options |
| 266 | command widget (-opt val -opt val ...) |
| 267 | |
| 268 | Once created, the pathname to the widget becomes a new command. This new |
| 269 | *widget command* is the programmer's handle for getting the new widget to |
| 270 | perform some *action*. In C, you'd express this as someAction(fred, |
| 271 | someOptions), in C++, you would express this as fred.someAction(someOptions), |
| 272 | and in Tk, you say:: |
| 273 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 274 | .fred someAction someOptions |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | |
| 276 | Note that the object name, ``.fred``, starts with a dot. |
| 277 | |
| 278 | As you'd expect, the legal values for *someAction* will depend on the widget's |
| 279 | class: ``.fred disable`` works if fred is a button (fred gets greyed out), but |
| 280 | does not work if fred is a label (disabling of labels is not supported in Tk). |
| 281 | |
| 282 | The legal values of *someOptions* is action dependent. Some actions, like |
| 283 | ``disable``, require no arguments, others, like a text-entry box's ``delete`` |
| 284 | command, would need arguments to specify what range of text to delete. |
| 285 | |
| 286 | |
| 287 | .. _tkinter-basic-mapping: |
| 288 | |
| 289 | Mapping Basic Tk into Tkinter |
| 290 | ----------------------------- |
| 291 | |
| 292 | Class commands in Tk correspond to class constructors in Tkinter. :: |
| 293 | |
| 294 | button .fred =====> fred = Button() |
| 295 | |
| 296 | The master of an object is implicit in the new name given to it at creation |
| 297 | time. In Tkinter, masters are specified explicitly. :: |
| 298 | |
| 299 | button .panel.fred =====> fred = Button(panel) |
| 300 | |
| 301 | The configuration options in Tk are given in lists of hyphened tags followed by |
| 302 | values. In Tkinter, options are specified as keyword-arguments in the instance |
| 303 | constructor, and keyword-args for configure calls or as instance indices, in |
| 304 | dictionary style, for established instances. See section |
| 305 | :ref:`tkinter-setting-options` on setting options. :: |
| 306 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 307 | button .fred -fg red =====> fred = Button(panel, fg="red") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | .fred configure -fg red =====> fred["fg"] = red |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 309 | OR ==> fred.config(fg="red") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 310 | |
| 311 | In Tk, to perform an action on a widget, use the widget name as a command, and |
| 312 | follow it with an action name, possibly with arguments (options). In Tkinter, |
| 313 | you call methods on the class instance to invoke actions on the widget. The |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 314 | actions (methods) that a given widget can perform are listed in |
| 315 | :file:`tkinter/__init__.py`. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | |
| 317 | .fred invoke =====> fred.invoke() |
| 318 | |
| 319 | To give a widget to the packer (geometry manager), you call pack with optional |
| 320 | arguments. In Tkinter, the Pack class holds all this functionality, and the |
| 321 | various forms of the pack command are implemented as methods. All widgets in |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 322 | :mod:`tkinter` are subclassed from the Packer, and so inherit all the packing |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 323 | methods. See the :mod:`tkinter.tix` module documentation for additional |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 324 | information on the Form geometry manager. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 326 | pack .fred -side left =====> fred.pack(side="left") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
| 328 | |
| 329 | How Tk and Tkinter are Related |
| 330 | ------------------------------ |
| 331 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | From the top down: |
| 333 | |
| 334 | Your App Here (Python) |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 335 | A Python application makes a :mod:`tkinter` call. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 336 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 337 | tkinter (Python Package) |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 338 | This call (say, for example, creating a button widget), is implemented in |
| 339 | the :mod:`tkinter` package, which is written in Python. This Python |
| 340 | function will parse the commands and the arguments and convert them into a |
| 341 | form that makes them look as if they had come from a Tk script instead of |
| 342 | a Python script. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 344 | _tkinter (C) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | These commands and their arguments will be passed to a C function in the |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 346 | :mod:`_tkinter` - note the underscore - extension module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | |
| 348 | Tk Widgets (C and Tcl) |
| 349 | This C function is able to make calls into other C modules, including the C |
| 350 | functions that make up the Tk library. Tk is implemented in C and some Tcl. |
| 351 | The Tcl part of the Tk widgets is used to bind certain default behaviors to |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 352 | widgets, and is executed once at the point where the Python :mod:`tkinter` |
| 353 | package is imported. (The user never sees this stage). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | |
| 355 | Tk (C) |
| 356 | The Tk part of the Tk Widgets implement the final mapping to ... |
| 357 | |
| 358 | Xlib (C) |
| 359 | the Xlib library to draw graphics on the screen. |
| 360 | |
| 361 | |
| 362 | Handy Reference |
| 363 | --------------- |
| 364 | |
| 365 | |
| 366 | .. _tkinter-setting-options: |
| 367 | |
| 368 | Setting Options |
| 369 | ^^^^^^^^^^^^^^^ |
| 370 | |
| 371 | Options control things like the color and border width of a widget. Options can |
| 372 | be set in three ways: |
| 373 | |
| 374 | At object creation time, using keyword arguments |
| 375 | :: |
| 376 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 377 | fred = Button(self, fg="red", bg="blue") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 378 | |
| 379 | After object creation, treating the option name like a dictionary index |
| 380 | :: |
| 381 | |
| 382 | fred["fg"] = "red" |
| 383 | fred["bg"] = "blue" |
| 384 | |
| 385 | Use the config() method to update multiple attrs subsequent to object creation |
| 386 | :: |
| 387 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 388 | fred.config(fg="red", bg="blue") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 389 | |
| 390 | For a complete explanation of a given option and its behavior, see the Tk man |
| 391 | pages for the widget in question. |
| 392 | |
| 393 | Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC OPTIONS" |
| 394 | for each widget. The former is a list of options that are common to many |
| 395 | widgets, the latter are the options that are idiosyncratic to that particular |
| 396 | widget. The Standard Options are documented on the :manpage:`options(3)` man |
| 397 | page. |
| 398 | |
| 399 | No distinction between standard and widget-specific options is made in this |
| 400 | document. Some options don't apply to some kinds of widgets. Whether a given |
| 401 | widget responds to a particular option depends on the class of the widget; |
| 402 | buttons have a ``command`` option, labels do not. |
| 403 | |
| 404 | The options supported by a given widget are listed in that widget's man page, or |
| 405 | can be queried at runtime by calling the :meth:`config` method without |
| 406 | arguments, or by calling the :meth:`keys` method on that widget. The return |
| 407 | value of these calls is a dictionary whose key is the name of the option as a |
| 408 | string (for example, ``'relief'``) and whose values are 5-tuples. |
| 409 | |
| 410 | Some options, like ``bg`` are synonyms for common options with long names |
| 411 | (``bg`` is shorthand for "background"). Passing the ``config()`` method the name |
| 412 | of a shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple passed |
| 413 | back will contain the name of the synonym and the "real" option (such as |
| 414 | ``('bg', 'background')``). |
| 415 | |
| 416 | +-------+---------------------------------+--------------+ |
| 417 | | Index | Meaning | Example | |
| 418 | +=======+=================================+==============+ |
| 419 | | 0 | option name | ``'relief'`` | |
| 420 | +-------+---------------------------------+--------------+ |
| 421 | | 1 | option name for database lookup | ``'relief'`` | |
| 422 | +-------+---------------------------------+--------------+ |
| 423 | | 2 | option class for database | ``'Relief'`` | |
| 424 | | | lookup | | |
| 425 | +-------+---------------------------------+--------------+ |
| 426 | | 3 | default value | ``'raised'`` | |
| 427 | +-------+---------------------------------+--------------+ |
| 428 | | 4 | current value | ``'groove'`` | |
| 429 | +-------+---------------------------------+--------------+ |
| 430 | |
| 431 | Example:: |
| 432 | |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 433 | >>> print(fred.config()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 434 | {'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')} |
| 435 | |
| 436 | Of course, the dictionary printed will include all the options available and |
| 437 | their values. This is meant only as an example. |
| 438 | |
| 439 | |
| 440 | The Packer |
| 441 | ^^^^^^^^^^ |
| 442 | |
| 443 | .. index:: single: packing (widgets) |
| 444 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 445 | The packer is one of Tk's geometry-management mechanisms. Geometry managers |
| 446 | are used to specify the relative positioning of the positioning of widgets |
| 447 | within their container - their mutual *master*. In contrast to the more |
| 448 | cumbersome *placer* (which is used less commonly, and we do not cover here), the |
| 449 | packer takes qualitative relationship specification - *above*, *to the left of*, |
| 450 | *filling*, etc - and works everything out to determine the exact placement |
| 451 | coordinates for you. |
| 452 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 453 | The size of any *master* widget is determined by the size of the "slave widgets" |
| 454 | inside. The packer is used to control where slave widgets appear inside the |
| 455 | master into which they are packed. You can pack widgets into frames, and frames |
| 456 | into other frames, in order to achieve the kind of layout you desire. |
| 457 | Additionally, the arrangement is dynamically adjusted to accommodate incremental |
| 458 | changes to the configuration, once it is packed. |
| 459 | |
| 460 | Note that widgets do not appear until they have had their geometry specified |
| 461 | with a geometry manager. It's a common early mistake to leave out the geometry |
| 462 | specification, and then be surprised when the widget is created but nothing |
| 463 | appears. A widget will appear only after it has had, for example, the packer's |
| 464 | :meth:`pack` method applied to it. |
| 465 | |
| 466 | The pack() method can be called with keyword-option/value pairs that control |
| 467 | where the widget is to appear within its container, and how it is to behave when |
| 468 | the main application window is resized. Here are some examples:: |
| 469 | |
| 470 | fred.pack() # defaults to side = "top" |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 471 | fred.pack(side="left") |
| 472 | fred.pack(expand=1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 473 | |
| 474 | |
| 475 | Packer Options |
| 476 | ^^^^^^^^^^^^^^ |
| 477 | |
| 478 | For more extensive information on the packer and the options that it can take, |
| 479 | see the man pages and page 183 of John Ousterhout's book. |
| 480 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 481 | anchor |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 482 | Anchor type. Denotes where the packer is to place each slave in its parcel. |
| 483 | |
| 484 | expand |
| 485 | Boolean, ``0`` or ``1``. |
| 486 | |
| 487 | fill |
| 488 | Legal values: ``'x'``, ``'y'``, ``'both'``, ``'none'``. |
| 489 | |
| 490 | ipadx and ipady |
| 491 | A distance - designating internal padding on each side of the slave widget. |
| 492 | |
| 493 | padx and pady |
| 494 | A distance - designating external padding on each side of the slave widget. |
| 495 | |
| 496 | side |
| 497 | Legal values are: ``'left'``, ``'right'``, ``'top'``, ``'bottom'``. |
| 498 | |
| 499 | |
| 500 | Coupling Widget Variables |
| 501 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 502 | |
| 503 | The current-value setting of some widgets (like text entry widgets) can be |
| 504 | connected directly to application variables by using special options. These |
| 505 | options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and |
| 506 | ``value``. This connection works both ways: if the variable changes for any |
| 507 | reason, the widget it's connected to will be updated to reflect the new value. |
| 508 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 509 | Unfortunately, in the current implementation of :mod:`tkinter` it is not |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 510 | possible to hand over an arbitrary Python variable to a widget through a |
| 511 | ``variable`` or ``textvariable`` option. The only kinds of variables for which |
| 512 | this works are variables that are subclassed from a class called Variable, |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 513 | defined in :mod:`tkinter`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 514 | |
| 515 | There are many useful subclasses of Variable already defined: |
| 516 | :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and |
| 517 | :class:`BooleanVar`. To read the current value of such a variable, call the |
Georg Brandl | c5605df | 2009-08-13 08:26:44 +0000 | [diff] [blame] | 518 | :meth:`get` method on it, and to change its value you call the :meth:`!set` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 519 | method. If you follow this protocol, the widget will always track the value of |
| 520 | the variable, with no further intervention on your part. |
| 521 | |
| 522 | For example:: |
| 523 | |
| 524 | class App(Frame): |
| 525 | def __init__(self, master=None): |
| 526 | Frame.__init__(self, master) |
| 527 | self.pack() |
| 528 | |
| 529 | self.entrythingy = Entry() |
| 530 | self.entrythingy.pack() |
| 531 | |
| 532 | # here is the application variable |
| 533 | self.contents = StringVar() |
| 534 | # set it to some value |
| 535 | self.contents.set("this is a variable") |
| 536 | # tell the entry widget to watch this variable |
| 537 | self.entrythingy["textvariable"] = self.contents |
| 538 | |
| 539 | # and here we get a callback when the user hits return. |
| 540 | # we will have the program print out the value of the |
| 541 | # application variable when the user hits return |
| 542 | self.entrythingy.bind('<Key-Return>', |
| 543 | self.print_contents) |
| 544 | |
| 545 | def print_contents(self, event): |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 546 | print("hi. contents of entry is now ---->", |
| 547 | self.contents.get()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 548 | |
| 549 | |
| 550 | The Window Manager |
| 551 | ^^^^^^^^^^^^^^^^^^ |
| 552 | |
| 553 | .. index:: single: window manager (widgets) |
| 554 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 555 | In Tk, there is a utility command, ``wm``, for interacting with the window |
| 556 | manager. Options to the ``wm`` command allow you to control things like titles, |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 557 | placement, icon bitmaps, and the like. In :mod:`tkinter`, these commands have |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 558 | been implemented as methods on the :class:`Wm` class. Toplevel widgets are |
| 559 | subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods |
| 560 | directly. |
| 561 | |
| 562 | To get at the toplevel window that contains a given widget, you can often just |
| 563 | refer to the widget's master. Of course if the widget has been packed inside of |
| 564 | a frame, the master won't represent a toplevel window. To get at the toplevel |
| 565 | window that contains an arbitrary widget, you can call the :meth:`_root` method. |
| 566 | This method begins with an underscore to denote the fact that this function is |
| 567 | part of the implementation, and not an interface to Tk functionality. |
| 568 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 569 | Here are some examples of typical usage:: |
| 570 | |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 571 | from tkinter import * |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 572 | class App(Frame): |
| 573 | def __init__(self, master=None): |
| 574 | Frame.__init__(self, master) |
| 575 | self.pack() |
| 576 | |
| 577 | |
| 578 | # create the application |
| 579 | myapp = App() |
| 580 | |
| 581 | # |
| 582 | # here are method calls to the window manager class |
| 583 | # |
| 584 | myapp.master.title("My Do-Nothing Application") |
| 585 | myapp.master.maxsize(1000, 400) |
| 586 | |
| 587 | # start the program |
| 588 | myapp.mainloop() |
| 589 | |
| 590 | |
| 591 | Tk Option Data Types |
| 592 | ^^^^^^^^^^^^^^^^^^^^ |
| 593 | |
| 594 | .. index:: single: Tk Option Data Types |
| 595 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 596 | anchor |
| 597 | Legal values are points of the compass: ``"n"``, ``"ne"``, ``"e"``, ``"se"``, |
| 598 | ``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``. |
| 599 | |
| 600 | bitmap |
| 601 | There are eight built-in, named bitmaps: ``'error'``, ``'gray25'``, |
| 602 | ``'gray50'``, ``'hourglass'``, ``'info'``, ``'questhead'``, ``'question'``, |
| 603 | ``'warning'``. To specify an X bitmap filename, give the full path to the file, |
| 604 | preceded with an ``@``, as in ``"@/usr/contrib/bitmap/gumby.bit"``. |
| 605 | |
| 606 | boolean |
| 607 | You can pass integers 0 or 1 or the strings ``"yes"`` or ``"no"`` . |
| 608 | |
| 609 | callback |
| 610 | This is any Python function that takes no arguments. For example:: |
| 611 | |
| 612 | def print_it(): |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 613 | print("hi there") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 614 | fred["command"] = print_it |
| 615 | |
| 616 | color |
| 617 | Colors can be given as the names of X colors in the rgb.txt file, or as strings |
| 618 | representing RGB values in 4 bit: ``"#RGB"``, 8 bit: ``"#RRGGBB"``, 12 bit" |
| 619 | ``"#RRRGGGBBB"``, or 16 bit ``"#RRRRGGGGBBBB"`` ranges, where R,G,B here |
| 620 | represent any legal hex digit. See page 160 of Ousterhout's book for details. |
| 621 | |
| 622 | cursor |
| 623 | The standard X cursor names from :file:`cursorfont.h` can be used, without the |
| 624 | ``XC_`` prefix. For example to get a hand cursor (:const:`XC_hand2`), use the |
| 625 | string ``"hand2"``. You can also specify a bitmap and mask file of your own. |
| 626 | See page 179 of Ousterhout's book. |
| 627 | |
| 628 | distance |
| 629 | Screen distances can be specified in either pixels or absolute distances. |
| 630 | Pixels are given as numbers and absolute distances as strings, with the trailing |
| 631 | character denoting units: ``c`` for centimetres, ``i`` for inches, ``m`` for |
| 632 | millimetres, ``p`` for printer's points. For example, 3.5 inches is expressed |
| 633 | as ``"3.5i"``. |
| 634 | |
| 635 | font |
| 636 | Tk uses a list font name format, such as ``{courier 10 bold}``. Font sizes with |
| 637 | positive numbers are measured in points; sizes with negative numbers are |
| 638 | measured in pixels. |
| 639 | |
| 640 | geometry |
| 641 | This is a string of the form ``widthxheight``, where width and height are |
| 642 | measured in pixels for most widgets (in characters for widgets displaying text). |
| 643 | For example: ``fred["geometry"] = "200x100"``. |
| 644 | |
| 645 | justify |
| 646 | Legal values are the strings: ``"left"``, ``"center"``, ``"right"``, and |
| 647 | ``"fill"``. |
| 648 | |
| 649 | region |
| 650 | This is a string with four space-delimited elements, each of which is a legal |
| 651 | distance (see above). For example: ``"2 3 4 5"`` and ``"3i 2i 4.5i 2i"`` and |
| 652 | ``"3c 2c 4c 10.43c"`` are all legal regions. |
| 653 | |
| 654 | relief |
| 655 | Determines what the border style of a widget will be. Legal values are: |
| 656 | ``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, and ``"ridge"``. |
| 657 | |
| 658 | scrollcommand |
Georg Brandl | c5605df | 2009-08-13 08:26:44 +0000 | [diff] [blame] | 659 | This is almost always the :meth:`!set` method of some scrollbar widget, but can |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 660 | be any widget method that takes a single argument. Refer to the file |
| 661 | :file:`Demo/tkinter/matt/canvas-with-scrollbars.py` in the Python source |
| 662 | distribution for an example. |
| 663 | |
| 664 | wrap: |
| 665 | Must be one of: ``"none"``, ``"char"``, or ``"word"``. |
| 666 | |
| 667 | |
| 668 | Bindings and Events |
| 669 | ^^^^^^^^^^^^^^^^^^^ |
| 670 | |
| 671 | .. index:: |
| 672 | single: bind (widgets) |
| 673 | single: events (widgets) |
| 674 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 675 | The bind method from the widget command allows you to watch for certain events |
| 676 | and to have a callback function trigger when that event type occurs. The form |
| 677 | of the bind method is:: |
| 678 | |
| 679 | def bind(self, sequence, func, add=''): |
| 680 | |
| 681 | where: |
| 682 | |
| 683 | sequence |
| 684 | is a string that denotes the target kind of event. (See the bind man page and |
| 685 | page 201 of John Ousterhout's book for details). |
| 686 | |
| 687 | func |
| 688 | is a Python function, taking one argument, to be invoked when the event occurs. |
| 689 | An Event instance will be passed as the argument. (Functions deployed this way |
| 690 | are commonly known as *callbacks*.) |
| 691 | |
| 692 | add |
| 693 | is optional, either ``''`` or ``'+'``. Passing an empty string denotes that |
| 694 | this binding is to replace any other bindings that this event is associated |
| 695 | with. Passing a ``'+'`` means that this function is to be added to the list |
| 696 | of functions bound to this event type. |
| 697 | |
| 698 | For example:: |
| 699 | |
| 700 | def turnRed(self, event): |
| 701 | event.widget["activeforeground"] = "red" |
| 702 | |
| 703 | self.button.bind("<Enter>", self.turnRed) |
| 704 | |
| 705 | Notice how the widget field of the event is being accessed in the |
| 706 | :meth:`turnRed` callback. This field contains the widget that caught the X |
| 707 | event. The following table lists the other event fields you can access, and how |
| 708 | they are denoted in Tk, which can be useful when referring to the Tk man pages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 709 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 710 | +----+---------------------+----+---------------------+ |
| 711 | | Tk | Tkinter Event Field | Tk | Tkinter Event Field | |
| 712 | +====+=====================+====+=====================+ |
| 713 | | %f | focus | %A | char | |
| 714 | +----+---------------------+----+---------------------+ |
| 715 | | %h | height | %E | send_event | |
| 716 | +----+---------------------+----+---------------------+ |
| 717 | | %k | keycode | %K | keysym | |
| 718 | +----+---------------------+----+---------------------+ |
| 719 | | %s | state | %N | keysym_num | |
| 720 | +----+---------------------+----+---------------------+ |
| 721 | | %t | time | %T | type | |
| 722 | +----+---------------------+----+---------------------+ |
| 723 | | %w | width | %W | widget | |
| 724 | +----+---------------------+----+---------------------+ |
| 725 | | %x | x | %X | x_root | |
| 726 | +----+---------------------+----+---------------------+ |
| 727 | | %y | y | %Y | y_root | |
| 728 | +----+---------------------+----+---------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 729 | |
| 730 | |
| 731 | The index Parameter |
| 732 | ^^^^^^^^^^^^^^^^^^^ |
| 733 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 734 | A number of widgets require "index" parameters to be passed. These are used to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 735 | point at a specific place in a Text widget, or to particular characters in an |
| 736 | Entry widget, or to particular menu items in a Menu widget. |
| 737 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 738 | Entry widget indexes (index, view index, etc.) |
| 739 | Entry widgets have options that refer to character positions in the text being |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 740 | displayed. You can use these :mod:`tkinter` functions to access these special |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 741 | points in text widgets: |
| 742 | |
| 743 | AtEnd() |
| 744 | refers to the last position in the text |
| 745 | |
| 746 | AtInsert() |
| 747 | refers to the point where the text cursor is |
| 748 | |
| 749 | AtSelFirst() |
| 750 | indicates the beginning point of the selected text |
| 751 | |
| 752 | AtSelLast() |
| 753 | denotes the last point of the selected text and finally |
| 754 | |
| 755 | At(x[, y]) |
| 756 | refers to the character at pixel location *x*, *y* (with *y* not used in the |
| 757 | case of a text entry widget, which contains a single line of text). |
| 758 | |
| 759 | Text widget indexes |
| 760 | The index notation for Text widgets is very rich and is best described in the Tk |
| 761 | man pages. |
| 762 | |
| 763 | Menu indexes (menu.invoke(), menu.entryconfig(), etc.) |
| 764 | Some options and methods for menus manipulate specific menu entries. Anytime a |
| 765 | menu index is needed for an option or a parameter, you may pass in: |
| 766 | |
| 767 | * an integer which refers to the numeric position of the entry in the widget, |
| 768 | counted from the top, starting with 0; |
| 769 | |
Ezio Melotti | 8209fcc | 2010-03-14 09:53:34 +0000 | [diff] [blame] | 770 | * the string ``"active"``, which refers to the menu position that is currently |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 771 | under the cursor; |
| 772 | |
| 773 | * the string ``"last"`` which refers to the last menu item; |
| 774 | |
| 775 | * An integer preceded by ``@``, as in ``@6``, where the integer is interpreted |
| 776 | as a y pixel coordinate in the menu's coordinate system; |
| 777 | |
| 778 | * the string ``"none"``, which indicates no menu entry at all, most often used |
| 779 | with menu.activate() to deactivate all entries, and finally, |
| 780 | |
| 781 | * a text string that is pattern matched against the label of the menu entry, as |
| 782 | scanned from the top of the menu to the bottom. Note that this index type is |
| 783 | considered after all the others, which means that matches for menu items |
| 784 | labelled ``last``, ``active``, or ``none`` may be interpreted as the above |
| 785 | literals, instead. |
| 786 | |
| 787 | |
| 788 | Images |
| 789 | ^^^^^^ |
| 790 | |
| 791 | Bitmap/Pixelmap images can be created through the subclasses of |
Georg Brandl | ac6060c | 2008-05-17 18:44:45 +0000 | [diff] [blame] | 792 | :class:`tkinter.Image`: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 793 | |
| 794 | * :class:`BitmapImage` can be used for X11 bitmap data. |
| 795 | |
| 796 | * :class:`PhotoImage` can be used for GIF and PPM/PGM color bitmaps. |
| 797 | |
| 798 | Either type of image is created through either the ``file`` or the ``data`` |
| 799 | option (other options are available as well). |
| 800 | |
| 801 | The image object can then be used wherever an ``image`` option is supported by |
| 802 | some widget (e.g. labels, buttons, menus). In these cases, Tk will not keep a |
| 803 | reference to the image. When the last Python reference to the image object is |
| 804 | deleted, the image data is deleted as well, and Tk will display an empty box |
| 805 | wherever the image was used. |
| 806 | |