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