| 1 |
:mod:`!tkinter` --- Python interface to Tcl/Tk |
| 2 |
============================================== |
| 3 |
|
| 4 |
.. module:: tkinter |
| 5 |
:synopsis: Interface to Tcl/Tk for graphical user interfaces |
| 6 |
|
| 7 |
.. moduleauthor:: Guido van Rossum <[email protected]> |
| 8 |
|
| 9 |
**Source code:** :source:`Lib/tkinter/__init__.py` |
| 10 |
|
| 11 |
-------------- |
| 12 |
|
| 13 |
The :mod:`tkinter` package ("Tk interface") is the standard Python interface to |
| 14 |
the Tcl/Tk GUI toolkit. Both Tk and :mod:`tkinter` are available on most Unix |
| 15 |
platforms, including macOS, as well as on Windows systems. |
| 16 |
|
| 17 |
Running ``python -m tkinter`` from the command line should open a window |
| 18 |
demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is |
| 19 |
properly installed on your system, and also showing what version of Tcl/Tk is |
| 20 |
installed, so you can read the Tcl/Tk documentation specific to that version. |
| 21 |
|
| 22 |
Tkinter supports a range of Tcl/Tk versions, built either with or without |
| 23 |
thread support. |
| 24 |
Tcl/Tk 8.5.12 is the minimum supported version; the official Python binary |
| 25 |
release bundles Tcl/Tk 8.6. |
| 26 |
See the source code for the :mod:`_tkinter` module for more information about |
| 27 |
supported versions. |
| 28 |
|
| 29 |
.. versionchanged:: 3.11 |
| 30 |
Support for Tcl/Tk versions older than 8.5.12 was removed. |
| 31 |
|
| 32 |
Tkinter is not a thin wrapper, but adds a fair amount of its own logic to |
| 33 |
make the experience more pythonic. This documentation will concentrate on these |
| 34 |
additions and changes, and refer to the official Tcl/Tk documentation for |
| 35 |
details that are unchanged. |
| 36 |
|
| 37 |
.. note:: |
| 38 |
|
| 39 |
Tcl/Tk 8.5 (2007) introduced a modern set of themed user interface components |
| 40 |
along with a new API to use them (see :mod:`tkinter.ttk`). |
| 41 |
Both old and new APIs are still available. |
| 42 |
Most documentation you will find online still uses the old API and |
| 43 |
can be woefully outdated. |
| 44 |
|
| 45 |
.. seealso:: |
| 46 |
|
| 47 |
* `TkDocs <https://tkdocs.com/>`_ |
| 48 |
Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, |
| 49 |
and illustrates recommended approaches using the modern API. |
| 50 |
|
| 51 |
* `Tkinter 8.5 reference: a GUI for Python <https://www.tkdocs.com/shipman/>`_ |
| 52 |
Reference documentation for Tkinter 8.5 detailing available classes, methods, and options. |
| 53 |
|
| 54 |
Tcl/Tk Resources: |
| 55 |
|
| 56 |
* `Tk commands <https://www.tcl-lang.org/man/tcl9.0/TkCmd/index.html>`_ |
| 57 |
Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter. |
| 58 |
|
| 59 |
* `Tcl/Tk Home Page <https://www.tcl.tk>`_ |
| 60 |
Additional documentation, and links to Tcl/Tk core development. |
| 61 |
|
| 62 |
Books: |
| 63 |
|
| 64 |
* `Modern Tkinter for Busy Python Developers <https://tkdocs.com/book.html>`_ |
| 65 |
By Mark Roseman. (ISBN 978-1999149567) |
| 66 |
|
| 67 |
* `Python GUI programming with Tkinter <https://www.packtpub.com/en-us/product/python-gui-programming-with-tkinter-9781788835886>`_ |
| 68 |
By Alan D. Moore. (ISBN 978-1788835886) |
| 69 |
|
| 70 |
* `Programming Python <https://learning-python.com/about-pp4e.html>`_ |
| 71 |
By Mark Lutz; has excellent coverage of Tkinter. (ISBN 978-0596158101) |
| 72 |
|
| 73 |
* `Tcl and the Tk Toolkit (2nd edition) <https://www.amazon.com/exec/obidos/ASIN/032133633X>`_ |
| 74 |
By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not cover Tkinter. (ISBN 978-0321336330) |
| 75 |
|
| 76 |
|
| 77 |
Architecture |
| 78 |
------------ |
| 79 |
|
| 80 |
Tcl/Tk is not a single library but rather consists of a few distinct |
| 81 |
modules, each with separate functionality and its own official |
| 82 |
documentation. Python's binary releases also ship an add-on module |
| 83 |
together with it. |
| 84 |
|
| 85 |
Tcl |
| 86 |
Tcl is a dynamic interpreted programming language, just like Python. Though |
| 87 |
it can be used on its own as a general-purpose programming language, it is |
| 88 |
most commonly embedded into C applications as a scripting engine or an |
| 89 |
interface to the Tk toolkit. The Tcl library has a C interface to |
| 90 |
create and manage one or more instances of a Tcl interpreter, run Tcl |
| 91 |
commands and scripts in those instances, and add custom commands |
| 92 |
implemented in either Tcl or C. Each interpreter has an event queue, |
| 93 |
and there are facilities to send events to it and process them. |
| 94 |
Unlike Python, Tcl's execution model is designed around cooperative |
| 95 |
multitasking, and Tkinter bridges this difference |
| 96 |
(see `Threading model`_ for details). |
| 97 |
|
| 98 |
Tk |
| 99 |
Tk is a `Tcl package <https://wiki.tcl-lang.org/37432>`_ implemented in C |
| 100 |
that adds custom commands to create and manipulate GUI widgets. Each |
| 101 |
:class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into |
| 102 |
it. Tk's widgets are very customizable, though at the cost of a dated appearance. |
| 103 |
Tk uses Tcl's event queue to generate and process GUI events. |
| 104 |
|
| 105 |
Ttk |
| 106 |
Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better |
| 107 |
appearance on different platforms than many of the classic Tk widgets. |
| 108 |
Ttk is distributed as part of Tk, starting with Tk version 8.5. Python |
| 109 |
bindings are provided in a separate module, :mod:`tkinter.ttk`. |
| 110 |
|
| 111 |
Internally, Tk and Ttk use facilities of the underlying operating system, |
| 112 |
that is, Xlib on Unix/X11, Cocoa on macOS, GDI on Windows. |
| 113 |
|
| 114 |
When your Python application uses a class in Tkinter, for example, to create a widget, |
| 115 |
the :mod:`!tkinter` module first assembles a Tcl/Tk command string. It passes that |
| 116 |
Tcl command string to an internal :mod:`_tkinter` binary module, which then |
| 117 |
calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the |
| 118 |
Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI. |
| 119 |
|
| 120 |
|
| 121 |
Tkinter modules |
| 122 |
--------------- |
| 123 |
|
| 124 |
Support for Tkinter is spread across several modules. Most applications will need the |
| 125 |
main :mod:`tkinter` module, as well as the :mod:`tkinter.ttk` module, which provides |
| 126 |
the modern themed widget set and API:: |
| 127 |
|
| 128 |
|
| 129 |
from tkinter import * |
| 130 |
from tkinter import ttk |
| 131 |
|
| 132 |
|
| 133 |
The modules that provide Tk support include: |
| 134 |
|
| 135 |
:mod:`tkinter` |
| 136 |
Main Tkinter module. |
| 137 |
|
| 138 |
:mod:`tkinter.colorchooser` |
| 139 |
Dialog to let the user choose a color. |
| 140 |
|
| 141 |
:mod:`tkinter.commondialog` |
| 142 |
Base class for the dialogs defined in the other modules listed here. |
| 143 |
|
| 144 |
:mod:`tkinter.filedialog` |
| 145 |
Common dialogs to allow the user to specify a file to open or save. |
| 146 |
|
| 147 |
:mod:`tkinter.font` |
| 148 |
Utilities to help work with fonts. |
| 149 |
|
| 150 |
:mod:`tkinter.messagebox` |
| 151 |
Access to standard Tk dialog boxes. |
| 152 |
|
| 153 |
:mod:`tkinter.scrolledtext` |
| 154 |
Text widget with a vertical scroll bar built in. |
| 155 |
|
| 156 |
:mod:`tkinter.simpledialog` |
| 157 |
Basic dialogs and convenience functions. |
| 158 |
|
| 159 |
:mod:`tkinter.ttk` |
| 160 |
Themed widget set introduced in Tk 8.5, providing modern alternatives |
| 161 |
for many of the classic widgets in the main :mod:`tkinter` module. |
| 162 |
|
| 163 |
Additional modules: |
| 164 |
|
| 165 |
.. module:: _tkinter |
| 166 |
:synopsis: A binary module that contains the low-level interface to Tcl/Tk. |
| 167 |
|
| 168 |
:mod:`_tkinter` |
| 169 |
A binary module that contains the low-level interface to Tcl/Tk. |
| 170 |
It is automatically imported by the main :mod:`tkinter` module, |
| 171 |
and should never be used directly by application programmers. |
| 172 |
It is usually a shared library (or DLL), but might in some cases be |
| 173 |
statically linked with the Python interpreter. |
| 174 |
|
| 175 |
:mod:`idlelib` |
| 176 |
Python's Integrated Development and Learning Environment (IDLE). Based |
| 177 |
on :mod:`tkinter`. |
| 178 |
|
| 179 |
:mod:`!tkinter.constants` |
| 180 |
Symbolic constants that can be used in place of strings when passing |
| 181 |
various parameters to Tkinter calls. Automatically imported by the |
| 182 |
main :mod:`tkinter` module. |
| 183 |
|
| 184 |
:mod:`tkinter.dnd` |
| 185 |
(experimental) Drag-and-drop support for :mod:`tkinter`. This will |
| 186 |
become deprecated when it is replaced with the Tk DND. |
| 187 |
|
| 188 |
:mod:`turtle` |
| 189 |
Turtle graphics in a Tk window. |
| 190 |
|
| 191 |
.. currentmodule:: tkinter |
| 192 |
|
| 193 |
|
| 194 |
Tkinter life preserver |
| 195 |
---------------------- |
| 196 |
|
| 197 |
This section is not designed to be an exhaustive tutorial on either Tk or |
| 198 |
Tkinter. For that, refer to one of the external resources noted earlier. |
| 199 |
Instead, this section provides a very quick orientation to what a Tkinter |
| 200 |
application looks like, identifies foundational Tk concepts, and |
| 201 |
explains how the Tkinter wrapper is structured. |
| 202 |
|
| 203 |
The remainder of this section will help you to identify the classes, |
| 204 |
methods, and options you'll need in your Tkinter application, and where to |
| 205 |
find more detailed documentation on them, including in the official Tcl/Tk |
| 206 |
reference manual. |
| 207 |
|
| 208 |
|
| 209 |
A Hello World program |
| 210 |
^^^^^^^^^^^^^^^^^^^^^ |
| 211 |
|
| 212 |
We'll start by walking through a "Hello World" application in Tkinter. This |
| 213 |
isn't the smallest one we could write, but has enough to illustrate some |
| 214 |
key concepts you'll need to know. |
| 215 |
|
| 216 |
:: |
| 217 |
|
| 218 |
from tkinter import * |
| 219 |
from tkinter import ttk |
| 220 |
root = Tk() |
| 221 |
frm = ttk.Frame(root, padding=10) |
| 222 |
frm.grid() |
| 223 |
ttk.Label(frm, text="Hello World!").grid(column=0, row=0) |
| 224 |
ttk.Button(frm, text="Quit", command=root.destroy).grid(column=1, row=0) |
| 225 |
root.mainloop() |
| 226 |
|
| 227 |
|
| 228 |
After the imports, the next line creates an instance of the :class:`Tk` class, |
| 229 |
which initializes Tk and creates its associated Tcl interpreter. It also |
| 230 |
creates a toplevel window, known as the root window, which serves as the main |
| 231 |
window of the application. |
| 232 |
|
| 233 |
The following line creates a frame widget, which in this case will contain |
| 234 |
a label and a button we'll create next. The frame is fit inside the root |
| 235 |
window. |
| 236 |
|
| 237 |
The next line creates a label widget holding a static text string. |
| 238 |
The :meth:`~Grid.grid` method is used to specify the relative layout (position) |
| 239 |
of the label within its containing frame widget, similar to how tables in HTML |
| 240 |
work. |
| 241 |
|
| 242 |
A button widget is then created, and placed to the right of the label. |
| 243 |
When pressed, it will call the :meth:`~Misc.destroy` method of the root window. |
| 244 |
|
| 245 |
Finally, the :meth:`mainloop` method puts everything on the display, and |
| 246 |
responds to user input until the program terminates. |
| 247 |
|
| 248 |
|
| 249 |
|
| 250 |
Important Tk concepts |
| 251 |
^^^^^^^^^^^^^^^^^^^^^ |
| 252 |
|
| 253 |
Even this simple program illustrates the following key Tk concepts: |
| 254 |
|
| 255 |
widgets |
| 256 |
A Tkinter user interface is made up of individual *widgets*. Each widget is |
| 257 |
represented as a Python object, instantiated from classes like |
| 258 |
:class:`ttk.Frame`, :class:`ttk.Label`, and :class:`ttk.Button`. |
| 259 |
|
| 260 |
widget hierarchy |
| 261 |
Widgets are arranged in a *hierarchy*. The label and button were contained |
| 262 |
within a frame, which in turn was contained within the root window. When |
| 263 |
creating each *child* widget, its *parent* widget is passed as the first |
| 264 |
argument to the widget constructor. |
| 265 |
|
| 266 |
configuration options |
| 267 |
Widgets have *configuration options*, which modify their appearance and |
| 268 |
behavior, such as the text to display in a label or button. Different |
| 269 |
classes of widgets will have different sets of options. |
| 270 |
|
| 271 |
geometry management |
| 272 |
Widgets aren't automatically added to the user interface when they are |
| 273 |
created. A *geometry manager* like ``grid`` controls where in the |
| 274 |
user interface they are placed. |
| 275 |
|
| 276 |
event loop |
| 277 |
Tkinter reacts to user input, changes from your program, and even refreshes |
| 278 |
the display only when actively running an *event loop*. If your program |
| 279 |
isn't running the event loop, your user interface won't update. |
| 280 |
|
| 281 |
|
| 282 |
Understanding how Tkinter wraps Tcl/Tk |
| 283 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 284 |
|
| 285 |
When your application uses Tkinter's classes and methods, internally Tkinter |
| 286 |
is assembling strings representing Tcl/Tk commands, and executing those |
| 287 |
commands in the Tcl interpreter attached to your application's :class:`Tk` |
| 288 |
instance. |
| 289 |
|
| 290 |
Whether it's trying to navigate reference documentation, trying to find |
| 291 |
the right method or option, adapting some existing code, or debugging your |
| 292 |
Tkinter application, there are times that it will be useful to understand |
| 293 |
what those underlying Tcl/Tk commands look like. |
| 294 |
|
| 295 |
To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinter |
| 296 |
script above. |
| 297 |
|
| 298 |
:: |
| 299 |
|
| 300 |
ttk::frame .frm -padding 10 |
| 301 |
grid .frm |
| 302 |
grid [ttk::label .frm.lbl -text "Hello World!"] -column 0 -row 0 |
| 303 |
grid [ttk::button .frm.btn -text "Quit" -command "destroy ."] -column 1 -row 0 |
| 304 |
|
| 305 |
|
| 306 |
Tcl's syntax is similar to many shell languages, where the first word is the |
| 307 |
command to be executed, with arguments to that command following it, separated |
| 308 |
by spaces. Without getting into too many details, notice the following: |
| 309 |
|
| 310 |
* The commands used to create widgets (like ``ttk::frame``) correspond to |
| 311 |
widget classes in Tkinter. |
| 312 |
|
| 313 |
* Tcl widget options (like ``-text``) correspond to keyword arguments in |
| 314 |
Tkinter. |
| 315 |
|
| 316 |
* Widgets are referred to by a *pathname* in Tcl (like ``.frm.btn``), |
| 317 |
whereas Tkinter doesn't use names but object references. |
| 318 |
|
| 319 |
* A widget's place in the widget hierarchy is encoded in its (hierarchical) |
| 320 |
pathname, which uses a ``.`` (dot) as a path separator. The pathname for |
| 321 |
the root window is just ``.`` (dot). In Tkinter, the hierarchy is defined |
| 322 |
not by pathname but by specifying the parent widget when creating each |
| 323 |
child widget. |
| 324 |
|
| 325 |
* Operations which are implemented as separate *commands* in Tcl (like |
| 326 |
``grid`` or ``destroy``) are represented as *methods* on Tkinter widget |
| 327 |
objects. As you'll see shortly, at other times Tcl uses what appear to be |
| 328 |
method calls on widget objects, which more closely mirror what is |
| 329 |
used in Tkinter. |
| 330 |
|
| 331 |
|
| 332 |
How do I...? What option does...? |
| 333 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 334 |
|
| 335 |
If you're not sure how to do something in Tkinter, and you can't immediately |
| 336 |
find it in the tutorial or reference documentation you're using, there are a |
| 337 |
few strategies that can be helpful. |
| 338 |
|
| 339 |
First, remember that the details of how individual widgets work may vary |
| 340 |
across different versions of both Tkinter and Tcl/Tk. If you're searching |
| 341 |
documentation, make sure it corresponds to the Python and Tcl/Tk versions |
| 342 |
installed on your system. |
| 343 |
|
| 344 |
When searching for how to use an API, it helps to know the exact name of the |
| 345 |
class, option, or method that you're using. Introspection, either in an |
| 346 |
interactive Python shell or with :func:`print`, can help you identify what |
| 347 |
you need. |
| 348 |
|
| 349 |
To find out what configuration options are available on any widget, call its |
| 350 |
:meth:`~Misc.configure` method, which returns a dictionary containing a variety |
| 351 |
of information about each object, including its default and current values. |
| 352 |
Use :meth:`~Misc.keys` to get just the names of each option. |
| 353 |
|
| 354 |
:: |
| 355 |
|
| 356 |
btn = ttk.Button(frm, ...) |
| 357 |
print(btn.configure().keys()) |
| 358 |
|
| 359 |
As most widgets have many configuration options in common, it can be useful |
| 360 |
to find out which are specific to a particular widget class. Comparing the |
| 361 |
list of options to that of a simpler widget, like a frame, is one way to |
| 362 |
do that. |
| 363 |
|
| 364 |
:: |
| 365 |
|
| 366 |
print(set(btn.configure().keys()) - set(frm.configure().keys())) |
| 367 |
|
| 368 |
Similarly, you can find the available methods for a widget object using the |
| 369 |
standard :func:`dir` function. If you try it, you'll see there are over 200 |
| 370 |
common widget methods, so again identifying those specific to a widget class |
| 371 |
is helpful. |
| 372 |
|
| 373 |
:: |
| 374 |
|
| 375 |
print(dir(btn)) |
| 376 |
print(set(dir(btn)) - set(dir(frm))) |
| 377 |
|
| 378 |
|
| 379 |
Navigating the Tcl/Tk reference manual |
| 380 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 381 |
|
| 382 |
As noted, the official |
| 383 |
`Tk commands <https://www.tcl-lang.org/man/tcl9.0/TkCmd/index.html>`_ reference |
| 384 |
manual (man pages) is often the most accurate description of what specific |
| 385 |
operations on widgets do. |
| 386 |
Even when you know the name of the option or method that you need, you may |
| 387 |
still have a few places to look. |
| 388 |
|
| 389 |
While all operations in Tkinter are implemented as method calls on widget |
| 390 |
objects, you've seen that many Tcl/Tk operations appear as commands that |
| 391 |
take a widget pathname as its first parameter, followed by optional |
| 392 |
parameters, for example |
| 393 |
|
| 394 |
:: |
| 395 |
|
| 396 |
destroy . |
| 397 |
grid .frm.btn -column 0 -row 0 |
| 398 |
|
| 399 |
Others, however, look more like methods called on a widget object (in fact, |
| 400 |
when you create a widget in Tcl/Tk, it creates a Tcl command with the name |
| 401 |
of the widget pathname, with the first parameter to that command being the |
| 402 |
name of a method to call). |
| 403 |
|
| 404 |
:: |
| 405 |
|
| 406 |
.frm.btn invoke |
| 407 |
.frm.lbl configure -text "Goodbye" |
| 408 |
|
| 409 |
|
| 410 |
In the official Tcl/Tk reference documentation, you'll find most operations |
| 411 |
that look like method calls on the man page for a specific widget (for example, |
| 412 |
you'll find the :meth:`~tkinter.ttk.Button.invoke` method on the |
| 413 |
`ttk::button <https://www.tcl-lang.org/man/tcl9.0/TkCmd/ttk_button.html>`_ |
| 414 |
man page), while functions that take a widget as a parameter often have |
| 415 |
their own man page (for example, |
| 416 |
`grid <https://www.tcl-lang.org/man/tcl9.0/TkCmd/grid.html>`_). |
| 417 |
|
| 418 |
You'll find many common options and methods in the |
| 419 |
`options <https://www.tcl-lang.org/man/tcl9.0/TkCmd/options.html>`_ or |
| 420 |
`ttk::widget <https://www.tcl-lang.org/man/tcl9.0/TkCmd/ttk_widget.html>`_ man |
| 421 |
pages, while others are found in the man page for a specific widget class. |
| 422 |
|
| 423 |
You'll also find that many Tkinter methods have compound names, for example, |
| 424 |
:meth:`~Misc.winfo_x`, :meth:`~Misc.winfo_height`, |
| 425 |
:meth:`~Misc.winfo_viewable`. |
| 426 |
You'd find documentation for all of these in the |
| 427 |
`winfo <https://www.tcl-lang.org/man/tcl9.0/TkCmd/winfo.html>`_ man page. |
| 428 |
|
| 429 |
.. note:: |
| 430 |
Somewhat confusingly, there are also methods on all Tkinter widgets |
| 431 |
that don't actually operate on the widget, but operate at a global |
| 432 |
scope, independent of any widget. Examples are methods for accessing |
| 433 |
the clipboard or the system bell. (They happen to be implemented as |
| 434 |
methods in the base :class:`Widget` class that all Tkinter widgets |
| 435 |
inherit from). |
| 436 |
|
| 437 |
|
| 438 |
Threading model |
| 439 |
--------------- |
| 440 |
|
| 441 |
Python and Tcl/Tk have very different threading models, which :mod:`tkinter` |
| 442 |
tries to bridge. If you use threads, you may need to be aware of this. |
| 443 |
|
| 444 |
A Python interpreter may have many threads associated with it. In Tcl, multiple |
| 445 |
threads can be created, but each thread has a separate Tcl interpreter instance |
| 446 |
associated with it. Threads can also create more than one interpreter instance, |
| 447 |
though each interpreter instance can be used only by the one thread that created it. |
| 448 |
|
| 449 |
Each :class:`Tk` object created by :mod:`tkinter` contains a Tcl interpreter. |
| 450 |
It also keeps track of which thread created that interpreter. Calls to |
| 451 |
:mod:`tkinter` can be made from any Python thread. Internally, if a call comes |
| 452 |
from a thread other than the one that created the :class:`Tk` object, an event |
| 453 |
is posted to the interpreter's event queue, and when executed, the result is |
| 454 |
returned to the calling Python thread. |
| 455 |
|
| 456 |
Tcl/Tk applications are normally event-driven, meaning that after |
| 457 |
initialization, the interpreter runs an event loop (that is, |
| 458 |
:meth:`Tk.mainloop <Misc.mainloop>`) and responds to events. |
| 459 |
Because it is single-threaded, event handlers must respond quickly, otherwise |
| 460 |
they will block other events from being processed. |
| 461 |
To avoid this, any long-running computations should not run in an event |
| 462 |
handler, but are either broken into smaller pieces using timers, or run in |
| 463 |
another thread. |
| 464 |
This is different from many GUI toolkits where the GUI runs in a completely |
| 465 |
separate thread from all application code including event handlers. |
| 466 |
|
| 467 |
If the Tcl interpreter is not running the event loop and processing events, any |
| 468 |
:mod:`tkinter` calls made from threads other than the one running the Tcl |
| 469 |
interpreter will fail. |
| 470 |
|
| 471 |
A number of special cases exist: |
| 472 |
|
| 473 |
* Tcl/Tk libraries built without thread support are now rare: the bundled |
| 474 |
Tcl/Tk 8.6 is built with thread support, so this case only arises with some |
| 475 |
older non-threaded builds. When the library is not thread-aware, |
| 476 |
:mod:`!tkinter` calls the library from the originating Python thread, even |
| 477 |
if this is different than the thread that created the Tcl interpreter. A global |
| 478 |
lock ensures only one call occurs at a time. |
| 479 |
|
| 480 |
* While :mod:`tkinter` allows you to create more than one instance of a :class:`Tk` |
| 481 |
object (with its own interpreter), all interpreters that are part of the same |
| 482 |
thread share a common event queue, which gets ugly fast. In practice, don't create |
| 483 |
more than one instance of :class:`Tk` at a time. Otherwise, it's best to create |
| 484 |
them in separate threads and ensure you're running a thread-aware Tcl/Tk build. |
| 485 |
|
| 486 |
* Blocking event handlers are not the only way to prevent the Tcl interpreter from |
| 487 |
reentering the event loop. It is even possible to run multiple nested event loops |
| 488 |
or abandon the event loop entirely. If you're doing anything tricky when it comes |
| 489 |
to events or threads, be aware of these possibilities. |
| 490 |
|
| 491 |
* There are a few select :mod:`tkinter` functions that presently work only when |
| 492 |
called from the thread that created the Tcl interpreter. |
| 493 |
|
| 494 |
|
| 495 |
Handy reference |
| 496 |
--------------- |
| 497 |
|
| 498 |
|
| 499 |
.. _tkinter-setting-options: |
| 500 |
|
| 501 |
Setting options |
| 502 |
^^^^^^^^^^^^^^^ |
| 503 |
|
| 504 |
Options control things like the color and border width of a widget. Options can |
| 505 |
be set in three ways: |
| 506 |
|
| 507 |
At object creation time, using keyword arguments |
| 508 |
:: |
| 509 |
|
| 510 |
fred = Button(self, fg="red", bg="blue") |
| 511 |
|
| 512 |
After object creation, treating the option name like a dictionary index |
| 513 |
:: |
| 514 |
|
| 515 |
fred["fg"] = "red" |
| 516 |
fred["bg"] = "blue" |
| 517 |
|
| 518 |
Use the config() method to update multiple attrs subsequent to object creation |
| 519 |
:: |
| 520 |
|
| 521 |
fred.config(fg="red", bg="blue") |
| 522 |
|
| 523 |
.. note:: |
| 524 |
|
| 525 |
The ``fg`` and ``bg`` options used here, |
| 526 |
and other options that control a widget's appearance, |
| 527 |
belong to the classic :mod:`!tkinter` widgets. |
| 528 |
The themed :mod:`tkinter.ttk` widgets recommended in the introduction |
| 529 |
do not accept them; |
| 530 |
style a themed widget through the :class:`ttk.Style <tkinter.ttk.Style>` |
| 531 |
class instead. |
| 532 |
The three ways of setting an option shown above apply to both widget sets. |
| 533 |
|
| 534 |
For a complete explanation of a given option and its behavior, see the Tk man |
| 535 |
pages for the widget in question. |
| 536 |
|
| 537 |
Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC OPTIONS" |
| 538 |
for each widget. The former is a list of options that are common to many |
| 539 |
widgets, the latter are the options that are idiosyncratic to that particular |
| 540 |
widget. The Standard Options are documented on the :manpage:`options(3)` man |
| 541 |
page. |
| 542 |
|
| 543 |
No distinction between standard and widget-specific options is made in this |
| 544 |
document. Some options don't apply to some kinds of widgets. Whether a given |
| 545 |
widget responds to a particular option depends on the class of the widget; |
| 546 |
buttons have a ``command`` option, labels do not. |
| 547 |
|
| 548 |
The options supported by a given widget are listed in that widget's man page, |
| 549 |
or can be queried at runtime by calling the :meth:`~Misc.config` method without |
| 550 |
arguments, or by calling the :meth:`~Misc.keys` method on that widget. |
| 551 |
The return value of these calls is a dictionary whose key is the name of the |
| 552 |
option as a string (for example, ``'relief'``) and whose values are 5-tuples. |
| 553 |
|
| 554 |
Some options, like ``bg``, are synonyms for common options with long names |
| 555 |
(``bg`` is shorthand for "background"). |
| 556 |
|
| 557 |
+-------+---------------------------------+--------------+ |
| 558 |
| Index | Meaning | Example | |
| 559 |
+=======+=================================+==============+ |
| 560 |
| 0 | option name | ``'relief'`` | |
| 561 |
+-------+---------------------------------+--------------+ |
| 562 |
| 1 | option name for database lookup | ``'relief'`` | |
| 563 |
+-------+---------------------------------+--------------+ |
| 564 |
| 2 | option class for database | ``'Relief'`` | |
| 565 |
| | lookup | | |
| 566 |
+-------+---------------------------------+--------------+ |
| 567 |
| 3 | default value | ``'raised'`` | |
| 568 |
+-------+---------------------------------+--------------+ |
| 569 |
| 4 | current value | ``'groove'`` | |
| 570 |
+-------+---------------------------------+--------------+ |
| 571 |
|
| 572 |
Example:: |
| 573 |
|
| 574 |
>>> print(fred.config()) |
| 575 |
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')} |
| 576 |
|
| 577 |
Of course, the dictionary printed will include all the options available and |
| 578 |
their values. This is meant only as an example. |
| 579 |
|
| 580 |
|
| 581 |
.. _pack-the-packer: |
| 582 |
.. _tkinter-geometry-management: |
| 583 |
.. _the-packer: |
| 584 |
.. _packer-options: |
| 585 |
|
| 586 |
Geometry management |
| 587 |
^^^^^^^^^^^^^^^^^^^ |
| 588 |
|
| 589 |
.. index:: |
| 590 |
single: geometry management (widgets) |
| 591 |
single: packing (widgets) |
| 592 |
|
| 593 |
Creating a widget does not display it. |
| 594 |
A widget appears only after it has been handed to a *geometry manager*, |
| 595 |
which works out its size and position inside its container |
| 596 |
and keeps the layout up to date as the container is resized or its content changes. |
| 597 |
Forgetting to call a geometry manager is a common early mistake: |
| 598 |
the widget is created, but nothing shows up. |
| 599 |
|
| 600 |
Tk provides three geometry managers. |
| 601 |
Each is inherited by every widget, so any widget can be managed by any of them |
| 602 |
(but see the warning below about the incompatibility of grid and pack). |
| 603 |
The choice depends on the kind of layout you want. |
| 604 |
|
| 605 |
:meth:`grid <Grid.grid_configure>` |
| 606 |
Arranges widgets in a two-dimensional table of rows and columns. |
| 607 |
It is the most flexible manager and the one to reach for by default: |
| 608 |
layouts that would otherwise need several nested frames can often be |
| 609 |
expressed as a single grid, |
| 610 |
and rows and columns can be told how to absorb extra space. |
| 611 |
|
| 612 |
:: |
| 613 |
|
| 614 |
ttk.Label(frm, text="Name:").grid(column=0, row=0, sticky="w") |
| 615 |
ttk.Entry(frm).grid(column=1, row=0) |
| 616 |
ttk.Button(frm, text="OK").grid(column=1, row=1, sticky="e") |
| 617 |
|
| 618 |
:meth:`pack <Pack.pack_configure>` |
| 619 |
Stacks widgets against one side of their container |
| 620 |
-- ``"top"`` (the default), ``"bottom"``, ``"left"`` or ``"right"`` -- |
| 621 |
and can make them fill or expand into the space that is left. |
| 622 |
It is convenient for simple arrangements, |
| 623 |
such as a single row or column of widgets |
| 624 |
or a content area framed by a toolbar and a status bar. |
| 625 |
|
| 626 |
:: |
| 627 |
|
| 628 |
toolbar.pack(side="top", fill="x") |
| 629 |
status.pack(side="bottom", fill="x") |
| 630 |
body.pack(side="left", expand=True, fill="both") |
| 631 |
|
| 632 |
:meth:`place <Place.place_configure>` |
| 633 |
Positions each widget at an explicit spot, |
| 634 |
given either as absolute screen distances or as a fraction of the container's size. |
| 635 |
It offers the most control but the least automatic behavior, and is used the least; |
| 636 |
it suits special cases such as overlapping widgets or precise custom layouts. |
| 637 |
|
| 638 |
:: |
| 639 |
|
| 640 |
background.place(x=0, y=0, relwidth=1.0, relheight=1.0) |
| 641 |
badge.place(relx=1.0, rely=0.0, anchor="ne") |
| 642 |
|
| 643 |
Layouts are built up by nesting: |
| 644 |
grid or pack widgets, including frames, inside a frame or toplevel. |
| 645 |
Toplevels are managed by the OS window manager. |
| 646 |
Classic and themed :mod:`tkinter.ttk` widgets can be managed interchangeably. |
| 647 |
|
| 648 |
.. warning:: |
| 649 |
|
| 650 |
Do not apply :meth:`!pack` and :meth:`!grid` to two widgets that share the same container. |
| 651 |
The two managers negotiate sizes in incompatible ways, |
| 652 |
and the application can hang as they repeatedly resize the container against each other. |
| 653 |
To combine them, keep each manager's widgets in a separate frame. |
| 654 |
|
| 655 |
The full set of options accepted by each manager, with their values and defaults, |
| 656 |
is documented under :meth:`Grid.grid_configure`, :meth:`Pack.pack_configure` |
| 657 |
and :meth:`Place.place_configure`; |
| 658 |
see also the :manpage:`grid(3tk)`, :manpage:`pack(3tk)` and :manpage:`place(3tk)` |
| 659 |
man pages. |
| 660 |
|
| 661 |
|
| 662 |
.. _coupling-widget-variables: |
| 663 |
|
| 664 |
Coupling widget variables |
| 665 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 666 |
|
| 667 |
Some widgets can tie their current value directly to a program variable, |
| 668 |
so that the two stay in sync. |
| 669 |
Options such as ``variable``, ``textvariable``, ``value``, ``onvalue`` and |
| 670 |
``offvalue`` set up this connection: |
| 671 |
when the user changes the widget the variable is updated, |
| 672 |
and when the variable is set the widget redraws to match. |
| 673 |
|
| 674 |
A widget can be linked only to a :class:`Variable` object, |
| 675 |
not to an ordinary Python variable. |
| 676 |
This is not a limitation of :mod:`!tkinter` |
| 677 |
but a consequence of how the two languages differ: |
| 678 |
the link relies on Tcl being notified every time the value changes, |
| 679 |
and Python offers no way to react when a plain variable is reassigned. |
| 680 |
A :class:`Variable` sidesteps this by keeping its value inside the Tcl interpreter |
| 681 |
and exposing it through explicit :meth:`~Variable.get` and :meth:`~Variable.set` methods. |
| 682 |
|
| 683 |
Ready-made subclasses cover the common types: |
| 684 |
:class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` and :class:`BooleanVar`. |
| 685 |
Pass one as a widget's ``textvariable`` (or ``variable``) option, |
| 686 |
then read and update it with :meth:`~Variable.get` and :meth:`~Variable.set`; |
| 687 |
the widget tracks it with no further work on your part. |
| 688 |
|
| 689 |
Keep a reference to the variable for as long as the widget uses it |
| 690 |
-- for example by storing it as an attribute. |
| 691 |
A :class:`Variable` that is garbage collected removes its underlying Tcl variable, |
| 692 |
breaking the connection to the widget (see :class:`Variable`). |
| 693 |
|
| 694 |
For example:: |
| 695 |
|
| 696 |
import tkinter as tk |
| 697 |
from tkinter import ttk |
| 698 |
|
| 699 |
root = tk.Tk() |
| 700 |
|
| 701 |
# Create the application variable and give it an initial value. |
| 702 |
contents = tk.StringVar(value="this is a variable") |
| 703 |
|
| 704 |
# Tell the entry widget to track the variable. |
| 705 |
entry = ttk.Entry(root, textvariable=contents) |
| 706 |
entry.pack() |
| 707 |
|
| 708 |
# Print the current value whenever the user presses Return. |
| 709 |
def print_contents(event): |
| 710 |
print("The current entry content is:", contents.get()) |
| 711 |
|
| 712 |
entry.bind("<Return>", print_contents) |
| 713 |
|
| 714 |
# Setting the variable from the program updates the entry through the |
| 715 |
# same link. |
| 716 |
def clear(): |
| 717 |
contents.set("") |
| 718 |
|
| 719 |
ttk.Button(root, text="Clear", command=clear).pack() |
| 720 |
|
| 721 |
root.mainloop() |
| 722 |
|
| 723 |
.. _tkinter-window-manager: |
| 724 |
|
| 725 |
The window manager |
| 726 |
^^^^^^^^^^^^^^^^^^ |
| 727 |
|
| 728 |
.. index:: single: window manager (widgets) |
| 729 |
|
| 730 |
The *window manager* is the part of the desktop responsible for the title bar, |
| 731 |
border and controls drawn around each top-level window, |
| 732 |
and for such things as its title, position, size and icon. |
| 733 |
Tk gives access to these through the :class:`Wm` mixin, |
| 734 |
which is inherited by the :class:`Tk` root window and by every :class:`Toplevel`. |
| 735 |
You therefore call the window-manager methods directly on a top-level window. |
| 736 |
Each has a short name and an equivalent ``wm_``-prefixed name, |
| 737 |
for example :meth:`~Wm.title` and :meth:`~Wm.wm_title`. |
| 738 |
|
| 739 |
These methods act on the top-level window |
| 740 |
whether its content is built from the classic widgets or the themed :mod:`tkinter.ttk` widgets. |
| 741 |
To reach the top-level window containing an arbitrary widget, |
| 742 |
call its :meth:`~Misc.winfo_toplevel` method. |
| 743 |
|
| 744 |
For example:: |
| 745 |
|
| 746 |
import tkinter as tk |
| 747 |
from tkinter import ttk |
| 748 |
|
| 749 |
root = tk.Tk() |
| 750 |
root.title("My Application") |
| 751 |
root.geometry("640x480") |
| 752 |
root.minsize(320, 240) |
| 753 |
|
| 754 |
ttk.Label(root, text="Hello").pack(padx=20, pady=20) |
| 755 |
|
| 756 |
root.mainloop() |
| 757 |
|
| 758 |
See :class:`Wm` for the full set of window-manager methods. |
| 759 |
|
| 760 |
|
| 761 |
.. _Tk-option-data-types: |
| 762 |
|
| 763 |
Tk option data types |
| 764 |
^^^^^^^^^^^^^^^^^^^^ |
| 765 |
|
| 766 |
.. index:: single: Tk Option Data Types |
| 767 |
|
| 768 |
Many widget options documented in the reference |
| 769 |
accept values of a small number of common types, described here. |
| 770 |
|
| 771 |
anchor |
| 772 |
Legal values are points of the compass: ``"n"``, ``"ne"``, ``"e"``, ``"se"``, |
| 773 |
``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``. |
| 774 |
|
| 775 |
bitmap |
| 776 |
There are ten built-in, named bitmaps: ``'error'``, ``'gray12'``, |
| 777 |
``'gray25'``, ``'gray50'``, ``'gray75'``, ``'hourglass'``, ``'info'``, |
| 778 |
``'questhead'``, ``'question'``, ``'warning'``. To specify an X bitmap |
| 779 |
filename, give the full path to the file, preceded with an ``@``, as in |
| 780 |
``"@/usr/contrib/bitmap/gumby.bit"``. |
| 781 |
|
| 782 |
boolean |
| 783 |
You can pass integers 0 or 1 or the strings ``"yes"`` or ``"no"``. |
| 784 |
|
| 785 |
callback |
| 786 |
This is any Python function that takes no arguments. For example:: |
| 787 |
|
| 788 |
def print_it(): |
| 789 |
print("hi there") |
| 790 |
fred["command"] = print_it |
| 791 |
|
| 792 |
color |
| 793 |
Colors can be given as the names of X colors in the rgb.txt file, or as strings |
| 794 |
representing RGB values in 4 bit: ``"#RGB"``, 8 bit: ``"#RRGGBB"``, 12 bit: |
| 795 |
``"#RRRGGGBBB"``, or 16 bit: ``"#RRRRGGGGBBBB"`` ranges, where R,G,B here |
| 796 |
represent any legal hex digit. See the :manpage:`colors(3tk)` man page for |
| 797 |
the list of named colors. |
| 798 |
|
| 799 |
cursor |
| 800 |
The name of the mouse cursor to display while the pointer is over the widget. |
| 801 |
Tk provides a portable set of cursor names available on all platforms |
| 802 |
(for example ``"arrow"``, ``"watch"``, ``"cross"``, or ``"hand2"``); |
| 803 |
the standard X cursor names from :file:`cursorfont.h` may also be used, |
| 804 |
without the ``XC_`` prefix (so ``XC_hand2`` becomes ``"hand2"``). |
| 805 |
The full list of names, including the platform-specific ones, |
| 806 |
is given in the :manpage:`cursors(3tk)` manual page. |
| 807 |
You can also specify a bitmap and mask file of your own. |
| 808 |
On Windows a cursor file (:file:`.cur` or :file:`.ani`) may be used directly, |
| 809 |
giving its path preceded with an ``@``, as in ``"@C:/cursors/bart.ani"``. |
| 810 |
|
| 811 |
distance |
| 812 |
Screen distances can be specified in either pixels or absolute distances. |
| 813 |
Pixels are given as numbers and absolute distances as strings, with the trailing |
| 814 |
character denoting units: ``c`` for centimetres, ``i`` for inches, ``m`` for |
| 815 |
millimetres, ``p`` for printer's points. For example, 3.5 inches is expressed |
| 816 |
as ``"3.5i"``. |
| 817 |
|
| 818 |
font |
| 819 |
Tk uses a font description such as ``{courier 10 bold}``; in |
| 820 |
:mod:`!tkinter` this is most naturally passed as a tuple of |
| 821 |
``(family, size, *styles)`` (or as the equivalent string |
| 822 |
``"Courier 10 bold"``). Font sizes with positive numbers are measured in |
| 823 |
points; sizes with negative numbers are measured in pixels. |
| 824 |
|
| 825 |
geometry |
| 826 |
This is a string of the form ``widthxheight``, where width and height are |
| 827 |
measured in pixels for most widgets (in characters for widgets displaying text). |
| 828 |
For example: ``fred["geometry"] = "200x100"``. |
| 829 |
|
| 830 |
justify |
| 831 |
Legal values are the strings: ``"left"``, ``"center"``, and ``"right"``. |
| 832 |
|
| 833 |
region |
| 834 |
This is a string with four space-delimited elements, each of which is a legal |
| 835 |
distance (see above). For example: ``"2 3 4 5"`` and ``"3i 2i 4.5i 2i"`` and |
| 836 |
``"3c 2c 4c 10.43c"`` are all legal regions. |
| 837 |
|
| 838 |
relief |
| 839 |
Determines what the border style of a widget will be. Legal values are: |
| 840 |
``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, ``"ridge"``, and |
| 841 |
``"solid"``. |
| 842 |
|
| 843 |
scrollcommand |
| 844 |
This is almost always the :meth:`!set` method of some scrollbar widget, but can |
| 845 |
be any widget method that takes a single argument. |
| 846 |
|
| 847 |
wrap |
| 848 |
Must be one of: ``"none"``, ``"char"``, or ``"word"``. |
| 849 |
|
| 850 |
.. _Bindings-and-Events: |
| 851 |
|
| 852 |
Bindings and events |
| 853 |
^^^^^^^^^^^^^^^^^^^ |
| 854 |
|
| 855 |
.. index:: |
| 856 |
single: bind (widgets) |
| 857 |
single: events (widgets) |
| 858 |
|
| 859 |
The bind method from the widget command allows you to watch for certain events |
| 860 |
and to have a callback function trigger when that event type occurs. The form |
| 861 |
of the bind method is:: |
| 862 |
|
| 863 |
def bind(self, sequence, func, add=''): |
| 864 |
|
| 865 |
where: |
| 866 |
|
| 867 |
sequence |
| 868 |
is a string that denotes the target kind of event. Physical events use the |
| 869 |
``<modifier-modifier-type-detail>`` form (for example ``"<Enter>"`` or |
| 870 |
``"<Control-Button-1>"``); application-defined virtual events use double angle |
| 871 |
brackets, as in ``"<<Paste>>"``. (See the |
| 872 |
:manpage:`bind(3tk)` man page for details.) |
| 873 |
|
| 874 |
func |
| 875 |
is a Python function, taking one argument, to be invoked when the event occurs. |
| 876 |
An Event instance will be passed as the argument. (Functions deployed this way |
| 877 |
are commonly known as *callbacks*.) |
| 878 |
|
| 879 |
add |
| 880 |
is optional, either ``''`` or ``'+'``. Passing an empty string denotes that |
| 881 |
this binding is to replace any other bindings that this event is associated |
| 882 |
with. Passing a ``'+'`` means that this function is to be added to the list |
| 883 |
of functions bound to this event type. |
| 884 |
|
| 885 |
For example:: |
| 886 |
|
| 887 |
def turn_red(self, event): |
| 888 |
event.widget["activeforeground"] = "red" |
| 889 |
|
| 890 |
self.button.bind("<Enter>", self.turn_red) |
| 891 |
|
| 892 |
Notice how the widget field of the event is being accessed in the |
| 893 |
``turn_red()`` callback. This field contains the widget that caught the X |
| 894 |
event. The following table lists the other event fields you can access, and how |
| 895 |
they are denoted in Tk, which can be useful when referring to the Tk man pages. |
| 896 |
|
| 897 |
+----+---------------------+----+---------------------+ |
| 898 |
| Tk | Tkinter Event Field | Tk | Tkinter Event Field | |
| 899 |
+====+=====================+====+=====================+ |
| 900 |
| %f | focus | %A | char | |
| 901 |
+----+---------------------+----+---------------------+ |
| 902 |
| %h | height | %E | send_event | |
| 903 |
+----+---------------------+----+---------------------+ |
| 904 |
| %k | keycode | %K | keysym | |
| 905 |
+----+---------------------+----+---------------------+ |
| 906 |
| %s | state | %N | keysym_num | |
| 907 |
+----+---------------------+----+---------------------+ |
| 908 |
| %t | time | %T | type | |
| 909 |
+----+---------------------+----+---------------------+ |
| 910 |
| %w | width | %W | widget | |
| 911 |
+----+---------------------+----+---------------------+ |
| 912 |
| %x | x | %X | x_root | |
| 913 |
+----+---------------------+----+---------------------+ |
| 914 |
| %y | y | %Y | y_root | |
| 915 |
+----+---------------------+----+---------------------+ |
| 916 |
| %# | serial | %b | num | |
| 917 |
+----+---------------------+----+---------------------+ |
| 918 |
| %d | detail | %D | delta | |
| 919 |
+----+---------------------+----+---------------------+ |
| 920 |
|
| 921 |
The ``add`` parameter above only affects the bindings you make yourself. |
| 922 |
Every widget also inherits *class bindings* |
| 923 |
that implement its standard behavior -- |
| 924 |
for example a :class:`Text` widget binds :kbd:`Control-t` |
| 925 |
to transpose two characters. |
| 926 |
These are described in the bindings section of the widget's Tk man page |
| 927 |
(such as :manpage:`text(3tk)` or :manpage:`entry(3tk)`). |
| 928 |
|
| 929 |
Class bindings are processed separately from your own, |
| 930 |
so binding an event yourself does not replace the default; both run. |
| 931 |
To suppress an unwanted default binding, |
| 932 |
bind the event on the widget |
| 933 |
and return the string ``"break"`` from your callback. |
| 934 |
|
| 935 |
|
| 936 |
The index parameter |
| 937 |
^^^^^^^^^^^^^^^^^^^ |
| 938 |
|
| 939 |
A number of widgets require "index" parameters to be passed. These are used to |
| 940 |
point at a specific place in a Text widget, or to particular characters in an |
| 941 |
Entry widget, or to particular menu items in a Menu widget. |
| 942 |
|
| 943 |
Entry widget indexes (index, view index, etc.) |
| 944 |
Entry widgets have methods and options that refer to character positions |
| 945 |
in the text being displayed. |
| 946 |
Anytime an index is needed, you may pass in: |
| 947 |
|
| 948 |
* an integer which refers to the numeric position of a character, |
| 949 |
counted from the beginning of the text, starting with 0; |
| 950 |
|
| 951 |
* the string ``"anchor"``, |
| 952 |
which refers to the anchor point of the selection, |
| 953 |
set with the widget's selection methods; |
| 954 |
|
| 955 |
* the string ``"end"``, |
| 956 |
which refers to the position just after the last character; |
| 957 |
|
| 958 |
* the string ``"insert"``, |
| 959 |
which refers to the character just after the insertion cursor; |
| 960 |
|
| 961 |
* the strings ``"sel.first"`` and ``"sel.last"``, |
| 962 |
which refer to the first character in the selection |
| 963 |
and the position just after the last |
| 964 |
(it is an error to use these if there is no selection); |
| 965 |
|
| 966 |
* a string consisting of ``@`` followed by an integer, as in ``"@6"``, |
| 967 |
where the integer is interpreted as an x pixel coordinate |
| 968 |
in the entry's coordinate system, |
| 969 |
selecting the character spanning that point. |
| 970 |
|
| 971 |
Text widget indexes |
| 972 |
The index notation for Text widgets is very rich and is best described in the Tk |
| 973 |
man pages. |
| 974 |
|
| 975 |
Menu indexes (menu.invoke(), menu.entryconfig(), etc.) |
| 976 |
Some options and methods for menus manipulate specific menu entries. Anytime a |
| 977 |
menu index is needed for an option or a parameter, you may pass in: |
| 978 |
|
| 979 |
* an integer which refers to the numeric position of the entry in the widget, |
| 980 |
counted from the top, starting with 0; |
| 981 |
|
| 982 |
* the string ``"active"``, which refers to the menu position that is currently |
| 983 |
under the cursor; |
| 984 |
|
| 985 |
* the string ``"last"`` which refers to the last menu item; |
| 986 |
|
| 987 |
* a string consisting of ``@`` followed by an integer, as in ``"@6"``, where |
| 988 |
the integer is interpreted as a y pixel coordinate in the menu's coordinate |
| 989 |
system; |
| 990 |
|
| 991 |
* the string ``"none"``, which indicates no menu entry at all, most often used |
| 992 |
with menu.activate() to deactivate all entries, and finally, |
| 993 |
|
| 994 |
* a text string that is pattern matched against the label of the menu entry, as |
| 995 |
scanned from the top of the menu to the bottom. Note that this index type is |
| 996 |
considered after all the others, which means that matches for menu items |
| 997 |
labelled ``last``, ``active``, or ``none`` may be interpreted as the above |
| 998 |
literals, instead. |
| 999 |
|
| 1000 |
|
| 1001 |
Images |
| 1002 |
^^^^^^ |
| 1003 |
|
| 1004 |
Images of different formats can be created through the corresponding subclass |
| 1005 |
of :class:`tkinter.Image`: |
| 1006 |
|
| 1007 |
* :class:`BitmapImage` for images in XBM format. |
| 1008 |
|
| 1009 |
* :class:`PhotoImage` for images in PGM, PPM, GIF and PNG formats. The latter |
| 1010 |
is supported starting with Tk 8.6. |
| 1011 |
|
| 1012 |
Either type of image is created through either the ``file`` or the ``data`` |
| 1013 |
option (other options are available as well). |
| 1014 |
|
| 1015 |
.. versionchanged:: 3.13 |
| 1016 |
Added the :class:`!PhotoImage` method :meth:`!copy_replace` to copy a region |
| 1017 |
from one image to other image, possibly with pixel zooming and/or |
| 1018 |
subsampling. |
| 1019 |
Add *from_coords* parameter to :class:`!PhotoImage` methods :meth:`!copy`, |
| 1020 |
:meth:`!zoom` and :meth:`!subsample`. |
| 1021 |
Add *zoom* and *subsample* parameters to :class:`!PhotoImage` method |
| 1022 |
:meth:`!copy`. |
| 1023 |
|
| 1024 |
The image object can then be used wherever an ``image`` option is supported by |
| 1025 |
some widget (for example, labels, buttons, menus). In these cases, Tk will not keep a |
| 1026 |
reference to the image. When the last Python reference to the image object is |
| 1027 |
deleted, the image data is deleted as well, and Tk will display an empty box |
| 1028 |
wherever the image was used. |
| 1029 |
|
| 1030 |
.. seealso:: |
| 1031 |
|
| 1032 |
The `Pillow <https://python-pillow.org/>`_ package adds support for |
| 1033 |
formats such as BMP, JPEG, TIFF, and WebP, among others. |
| 1034 |
|
| 1035 |
|
| 1036 |
Reference |
| 1037 |
--------- |
| 1038 |
|
| 1039 |
.. currentmodule:: tkinter |
| 1040 |
|
| 1041 |
This section documents the classes, methods, functions and constants of the |
| 1042 |
:mod:`!tkinter` module. |
| 1043 |
Most of them wrap Tcl/Tk commands; consult the official Tcl/Tk manual pages for |
| 1044 |
the full list of widget options and further details. |
| 1045 |
|
| 1046 |
.. exception:: TclError |
| 1047 |
|
| 1048 |
The exception raised when a call into the Tcl interpreter fails, for example |
| 1049 |
when a widget is given an unknown option or an invalid value. |
| 1050 |
|
| 1051 |
Base and mixin classes |
| 1052 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 1053 |
|
| 1054 |
.. class:: Misc() |
| 1055 |
|
| 1056 |
The :class:`!Misc` class is a mix-in inherited by :class:`Tk` and, through |
| 1057 |
:class:`BaseWidget`, by every widget. |
| 1058 |
It provides the large set of methods common to all Tk objects: querying |
| 1059 |
window information, managing event bindings and the event loop, controlling |
| 1060 |
the keyboard focus and pointer grabs, accessing the selection, clipboard and |
| 1061 |
option database, and assorted utility and introspection services. |
| 1062 |
Because they are inherited, these methods are available on every widget and |
| 1063 |
on the :class:`Tk` application object, and are documented here once rather |
| 1064 |
than repeated for each widget. |
| 1065 |
|
| 1066 |
.. method:: cget(key) |
| 1067 |
|
| 1068 |
Return the current value of the configuration option named *key* for this |
| 1069 |
widget, as a string. |
| 1070 |
The expression ``widget[key]`` is equivalent and may be used instead. |
| 1071 |
|
| 1072 |
.. method:: config(cnf=None, **kw) |
| 1073 |
:no-typesetting: |
| 1074 |
|
| 1075 |
.. method:: configure(cnf=None, **kw) |
| 1076 |
|
| 1077 |
Query or modify the configuration options of the widget. |
| 1078 |
With no arguments, return a dictionary mapping every available option |
| 1079 |
name to a tuple describing it (its name, X resource name, X resource |
| 1080 |
class, default value and current value). |
| 1081 |
If a single option name is given as a string, return the tuple for just |
| 1082 |
that option. |
| 1083 |
If one or more keyword arguments are given, or a dictionary is passed as |
| 1084 |
*cnf*, set each named option to the corresponding value; the expression |
| 1085 |
``widget[key] = value`` sets a single option in the same way. |
| 1086 |
|
| 1087 |
:meth:`config` is an alias of :meth:`!configure`. |
| 1088 |
|
| 1089 |
.. method:: keys() |
| 1090 |
|
| 1091 |
Return a list of the names of all configuration options of this widget. |
| 1092 |
|
| 1093 |
.. method:: getboolean(s) |
| 1094 |
|
| 1095 |
Interpret the string *s* as a Tcl boolean and return the corresponding |
| 1096 |
:class:`bool`. |
| 1097 |
Tcl accepts values such as ``'1'``, ``'0'``, ``'yes'``, ``'no'``, |
| 1098 |
``'true'`` and ``'false'``. |
| 1099 |
Raise :exc:`ValueError` if *s* is not a valid boolean. |
| 1100 |
|
| 1101 |
.. method:: getdouble(s) |
| 1102 |
|
| 1103 |
Interpret the string *s* as a Tcl floating-point number and return it as |
| 1104 |
a :class:`float`. |
| 1105 |
Raise :exc:`ValueError` if *s* is not a valid number. |
| 1106 |
|
| 1107 |
.. versionadded:: 3.5 |
| 1108 |
|
| 1109 |
|
| 1110 |
.. method:: getint(s) |
| 1111 |
|
| 1112 |
Interpret the string *s* as a Tcl integer and return it as an |
| 1113 |
:class:`int`. |
| 1114 |
Raise :exc:`ValueError` if *s* is not a valid integer. |
| 1115 |
|
| 1116 |
.. method:: getvar(name) |
| 1117 |
|
| 1118 |
Return the value of the Tcl global variable named *name*. |
| 1119 |
|
| 1120 |
.. method:: setvar(name, value) |
| 1121 |
|
| 1122 |
Set the Tcl global variable named *name* to *value*. |
| 1123 |
|
| 1124 |
The :meth:`!getvar` and :meth:`!setvar` methods give direct access to Tcl |
| 1125 |
variables. |
| 1126 |
In most code you will instead use a :class:`Variable` subclass such as |
| 1127 |
:class:`StringVar` or :class:`IntVar`, which wraps a Tcl variable and |
| 1128 |
converts its value to and from a Python type. |
| 1129 |
|
| 1130 |
.. method:: register(func, subst=None, needcleanup=1) |
| 1131 |
|
| 1132 |
Register the Python callable *func* as a Tcl command and return the name |
| 1133 |
of the new command as a string. |
| 1134 |
Whenever Tcl invokes that command, *func* is called; if *subst* is given, |
| 1135 |
it is applied to the command's arguments first. |
| 1136 |
This is the mechanism used internally to turn Python callbacks into the |
| 1137 |
command names passed to Tk options such as *command*. |
| 1138 |
Unless *needcleanup* is false, the command is deleted automatically when |
| 1139 |
the widget is destroyed. |
| 1140 |
|
| 1141 |
.. versionchanged:: 3.13 |
| 1142 |
The arguments passed to *func* are no longer converted to strings. |
| 1143 |
|
| 1144 |
.. method:: deletecommand(name) |
| 1145 |
|
| 1146 |
Delete the Tcl command named *name*, such as one previously returned by |
| 1147 |
:meth:`register`. |
| 1148 |
|
| 1149 |
.. method:: nametowidget(name) |
| 1150 |
|
| 1151 |
Return the widget instance corresponding to the Tk pathname *name*. |
| 1152 |
|
| 1153 |
.. method:: send(interp, cmd, *args) |
| 1154 |
|
| 1155 |
Send the Tcl command *cmd*, with the given *args*, to the Tcl interpreter |
| 1156 |
registered under the name *interp*, and return its result. |
| 1157 |
This is not available on all platforms. |
| 1158 |
|
| 1159 |
.. method:: destroy() |
| 1160 |
|
| 1161 |
Destroy this widget and all of its descendant widgets, and delete the Tcl |
| 1162 |
commands associated with them. |
| 1163 |
|
| 1164 |
.. method:: lift(aboveThis=None) |
| 1165 |
:no-typesetting: |
| 1166 |
|
| 1167 |
.. method:: tkraise(aboveThis=None) |
| 1168 |
|
| 1169 |
Raise this widget in the stacking order so that it is drawn on top of its |
| 1170 |
siblings. |
| 1171 |
If *aboveThis* is given, the widget is moved to be just above it in the |
| 1172 |
stacking order instead. |
| 1173 |
|
| 1174 |
:meth:`lift` is an alias of :meth:`!tkraise`. |
| 1175 |
|
| 1176 |
.. method:: lower(belowThis=None) |
| 1177 |
|
| 1178 |
Lower this widget in the stacking order so that it is drawn beneath its |
| 1179 |
siblings. |
| 1180 |
If *belowThis* is given, the widget is moved to be just below it in the |
| 1181 |
stacking order instead. |
| 1182 |
|
| 1183 |
:meth:`tkraise`/:meth:`lift` and :meth:`lower` are overridden by the |
| 1184 |
:class:`Canvas` widget, |
| 1185 |
where they restack canvas items instead. |
| 1186 |
|
| 1187 |
.. method:: image_names() |
| 1188 |
|
| 1189 |
Return the names of all images that currently exist in the Tcl |
| 1190 |
interpreter. |
| 1191 |
|
| 1192 |
This is overridden by the :class:`Text` widget, |
| 1193 |
where :meth:`!image_names` returns the names of its embedded images |
| 1194 |
instead. |
| 1195 |
|
| 1196 |
.. method:: image_types() |
| 1197 |
|
| 1198 |
Return the available image types, such as ``'photo'`` and ``'bitmap'``. |
| 1199 |
|
| 1200 |
.. method:: anchor(anchor=None) |
| 1201 |
:no-typesetting: |
| 1202 |
|
| 1203 |
.. method:: grid_anchor(anchor=None) |
| 1204 |
|
| 1205 |
Set the anchor that controls where the grid is placed inside this |
| 1206 |
container when the container is larger than the grid and no row or column |
| 1207 |
has a non-zero weight. |
| 1208 |
*anchor* is one of the usual anchor strings, such as ``'nw'`` (the |
| 1209 |
default) or ``'center'``. |
| 1210 |
Called with no argument, this method has no effect. |
| 1211 |
|
| 1212 |
:meth:`anchor` is an alias of :meth:`!grid_anchor`. |
| 1213 |
|
| 1214 |
.. versionadded:: 3.3 |
| 1215 |
|
| 1216 |
.. method:: bbox(column=None, row=None, col2=None, row2=None) |
| 1217 |
:no-typesetting: |
| 1218 |
|
| 1219 |
.. method:: grid_bbox(column=None, row=None, col2=None, row2=None) |
| 1220 |
|
| 1221 |
Return the bounding box, in pixels, of a region of the grid laid out in |
| 1222 |
this container, as a 4-tuple ``(xoffset, yoffset, width, height)``. |
| 1223 |
With no arguments the bounding box of the whole grid is returned. |
| 1224 |
If *column* and *row* are given, the box spans from the cell at row and |
| 1225 |
column 0 to that cell; if *col2* and *row2* are also given, it spans from |
| 1226 |
the cell (*column*, *row*) to the cell (*col2*, *row2*). |
| 1227 |
|
| 1228 |
:meth:`bbox` is an alias of :meth:`!grid_bbox`, |
| 1229 |
except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`, |
| 1230 |
:class:`Text`, :class:`ttk.Entry <tkinter.ttk.Entry>` and |
| 1231 |
:class:`ttk.Treeview <tkinter.ttk.Treeview>`, |
| 1232 |
which provide their own :meth:`!bbox` method. |
| 1233 |
|
| 1234 |
.. method:: columnconfigure(index, cnf={}, **kw) |
| 1235 |
:no-typesetting: |
| 1236 |
|
| 1237 |
.. method:: grid_columnconfigure(index, cnf={}, **kw) |
| 1238 |
|
| 1239 |
Query or set the properties of the column (or columns) *index* of the |
| 1240 |
grid managed by this container. |
| 1241 |
*index* may be a column number; when setting options it may also be a |
| 1242 |
list of column numbers, the string ``'all'`` to affect every column, or |
| 1243 |
a child widget whose occupied columns are affected. |
| 1244 |
The supported options are: |
| 1245 |
|
| 1246 |
*minsize* |
| 1247 |
The column's minimum size, in pixels. |
| 1248 |
|
| 1249 |
*weight* |
| 1250 |
An integer setting how much of any extra space is apportioned to the |
| 1251 |
column. |
| 1252 |
A weight of ``0`` keeps the column at its requested size, and a column |
| 1253 |
of weight two grows twice as fast as a column of weight one. |
| 1254 |
|
| 1255 |
*uniform* |
| 1256 |
The name of a uniform group. |
| 1257 |
Columns sharing a non-empty group name are kept in sizes that are |
| 1258 |
strictly proportional to their weights. |
| 1259 |
|
| 1260 |
*pad* |
| 1261 |
Extra space, in pixels, added to the largest widget in the column when |
| 1262 |
computing the column's size. |
| 1263 |
|
| 1264 |
With a single option name, return that option's value; with no options, |
| 1265 |
return a dictionary of all of them. |
| 1266 |
|
| 1267 |
:meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. |
| 1268 |
|
| 1269 |
.. method:: rowconfigure(index, cnf={}, **kw) |
| 1270 |
:no-typesetting: |
| 1271 |
|
| 1272 |
.. method:: grid_rowconfigure(index, cnf={}, **kw) |
| 1273 |
|
| 1274 |
Query or set the properties of the row (or rows) *index* of the grid |
| 1275 |
managed by this container. |
| 1276 |
*index* is interpreted as for :meth:`grid_columnconfigure`, and the |
| 1277 |
supported options (*minsize*, *weight*, *uniform* and *pad*) are the |
| 1278 |
same, applied to a row instead of a column. |
| 1279 |
|
| 1280 |
:meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. |
| 1281 |
|
| 1282 |
.. method:: grid_location(x, y) |
| 1283 |
|
| 1284 |
Return the ``(column, row)`` of the grid cell that contains the pixel at |
| 1285 |
position (*x*, *y*), given in pixels relative to this container. |
| 1286 |
For locations above or to the left of the grid, ``-1`` is returned for |
| 1287 |
the corresponding coordinate. |
| 1288 |
|
| 1289 |
.. method:: grid_propagate() |
| 1290 |
grid_propagate(flag) |
| 1291 |
|
| 1292 |
Enable or disable geometry propagation for this container when it manages |
| 1293 |
its children with the grid geometry manager. |
| 1294 |
When *flag* is true, the container resizes itself to fit the requested |
| 1295 |
sizes of its children; when it is false, its size is left under your |
| 1296 |
control. |
| 1297 |
Called with no argument, return the current setting as a boolean. |
| 1298 |
|
| 1299 |
.. method:: size() |
| 1300 |
:no-typesetting: |
| 1301 |
|
| 1302 |
.. method:: grid_size() |
| 1303 |
|
| 1304 |
Return the size of the grid managed by this container as a |
| 1305 |
``(columns, rows)`` tuple. |
| 1306 |
|
| 1307 |
:meth:`size` is an alias of :meth:`!grid_size`, |
| 1308 |
except on the :class:`Listbox` widget, |
| 1309 |
which provides its own :meth:`!size` method. |
| 1310 |
|
| 1311 |
.. method:: grid_slaves(row=None, column=None) |
| 1312 |
|
| 1313 |
Return a list of the child widgets managed in this container's grid, most |
| 1314 |
recently managed first. |
| 1315 |
If *row* or *column* is given, only the children in that row or column |
| 1316 |
are returned. |
| 1317 |
|
| 1318 |
.. method:: propagate() |
| 1319 |
propagate(flag) |
| 1320 |
:no-typesetting: |
| 1321 |
|
| 1322 |
.. method:: pack_propagate() |
| 1323 |
pack_propagate(flag) |
| 1324 |
|
| 1325 |
Enable or disable geometry propagation for this container when it manages |
| 1326 |
its children with the pack geometry manager. |
| 1327 |
When *flag* is true, the container resizes itself to fit the requested |
| 1328 |
sizes of its children; when it is false, its size is left under your |
| 1329 |
control. |
| 1330 |
Called with no argument, return the current setting as a boolean. |
| 1331 |
|
| 1332 |
:meth:`propagate` is an alias of :meth:`!pack_propagate`. |
| 1333 |
|
| 1334 |
.. method:: slaves() |
| 1335 |
:no-typesetting: |
| 1336 |
|
| 1337 |
.. method:: pack_slaves() |
| 1338 |
|
| 1339 |
Return a list of the child widgets managed by this container with the |
| 1340 |
pack geometry manager, in packing order. |
| 1341 |
|
| 1342 |
:meth:`slaves` is an alias of :meth:`!pack_slaves`. |
| 1343 |
|
| 1344 |
.. method:: place_slaves() |
| 1345 |
|
| 1346 |
Return a list of the child widgets managed by this container with the |
| 1347 |
place geometry manager. |
| 1348 |
|
| 1349 |
The methods with the ``bind`` and ``unbind`` prefixes associate event |
| 1350 |
patterns with callbacks and remove those associations. |
| 1351 |
|
| 1352 |
.. method:: bind(sequence=None, func=None, add=None) |
| 1353 |
|
| 1354 |
Bind the event pattern *sequence* on this widget to the callable *func*. |
| 1355 |
|
| 1356 |
*sequence* is an event pattern, such as ``'<Button-1>'`` (a mouse click) |
| 1357 |
or ``'<KeyPress-a>'``, optionally a concatenation of several such |
| 1358 |
patterns that must occur shortly after one another. |
| 1359 |
When the event occurs, *func* is called with an :class:`Event` instance |
| 1360 |
describing it as its only argument; if *func* returns the string |
| 1361 |
``'break'``, no further bindings for the event are invoked. |
| 1362 |
|
| 1363 |
If *add* is true, *func* is added to any functions already bound to |
| 1364 |
*sequence*; otherwise it replaces them. |
| 1365 |
The binding applies only to this widget. |
| 1366 |
|
| 1367 |
:meth:`!bind` returns a string identifier (a *funcid*) that can later be |
| 1368 |
passed to :meth:`unbind` to remove the binding without leaking the |
| 1369 |
associated Tcl command. |
| 1370 |
|
| 1371 |
If *func* is omitted, return the binding currently associated with |
| 1372 |
*sequence*; if *sequence* is also omitted, return a list of all the |
| 1373 |
sequences for which bindings exist on this widget. |
| 1374 |
|
| 1375 |
.. method:: bind_class(className, sequence=None, func=None, add=None) |
| 1376 |
|
| 1377 |
Like :meth:`bind`, but bind *func* to the binding tag *className* rather |
| 1378 |
than to a single widget, so that the binding applies to every widget |
| 1379 |
having that tag. |
| 1380 |
*className* is usually the name of a widget class, such as ``'Button'``, |
| 1381 |
in which case the binding affects all widgets of that class. |
| 1382 |
The set of binding tags for a widget can be inspected and changed with |
| 1383 |
:meth:`bindtags`. |
| 1384 |
|
| 1385 |
The remaining arguments and the return value are as for :meth:`bind`. |
| 1386 |
|
| 1387 |
.. method:: bind_all(sequence=None, func=None, add=None) |
| 1388 |
|
| 1389 |
Like :meth:`bind`, but bind *func* to the special binding tag ``'all'``, |
| 1390 |
so that the binding applies to every widget in the application. |
| 1391 |
|
| 1392 |
The remaining arguments and the return value are as for :meth:`bind`. |
| 1393 |
|
| 1394 |
.. method:: unbind(sequence, funcid=None) |
| 1395 |
|
| 1396 |
Remove bindings for the event pattern *sequence* on this widget. |
| 1397 |
|
| 1398 |
If *funcid* is given, only the function identified by it (a value |
| 1399 |
returned from a previous call to :meth:`bind`) is removed, and its |
| 1400 |
associated Tcl command is deleted. |
| 1401 |
Otherwise all bindings for *sequence* are destroyed, leaving it unbound. |
| 1402 |
|
| 1403 |
.. versionchanged:: 3.13 |
| 1404 |
If *funcid* is given, only that callback is unbound; other callbacks |
| 1405 |
bound to *sequence* are kept. |
| 1406 |
|
| 1407 |
|
| 1408 |
.. method:: unbind_class(className, sequence) |
| 1409 |
|
| 1410 |
Remove all bindings for the event pattern *sequence* from the binding tag |
| 1411 |
*className*. |
| 1412 |
See :meth:`bind_class`. |
| 1413 |
|
| 1414 |
.. method:: unbind_all(sequence) |
| 1415 |
|
| 1416 |
Remove all bindings for the event pattern *sequence* from the special |
| 1417 |
binding tag ``'all'``. |
| 1418 |
See :meth:`bind_all`. |
| 1419 |
|
| 1420 |
.. method:: bindtags(tagList=None) |
| 1421 |
|
| 1422 |
If *tagList* is omitted, return a tuple of the binding tags associated |
| 1423 |
with this widget. |
| 1424 |
When an event occurs in a widget, it is applied to each of the widget's |
| 1425 |
binding tags in order, and for each tag the most specific matching |
| 1426 |
binding is executed. |
| 1427 |
By default a widget has four binding tags: its own pathname, its widget |
| 1428 |
class, the pathname of its nearest toplevel ancestor, and ``'all'``, in |
| 1429 |
that order. |
| 1430 |
|
| 1431 |
If *tagList* is given, it must be a sequence of strings; the widget's |
| 1432 |
binding tags are set to its elements, which determines the order in which |
| 1433 |
bindings are evaluated. |
| 1434 |
|
| 1435 |
The methods with the ``event_`` prefix define virtual events and generate |
| 1436 |
events programmatically. |
| 1437 |
|
| 1438 |
.. method:: event_add(virtual, *sequences) |
| 1439 |
|
| 1440 |
Associate the virtual event *virtual*, whose name has the form |
| 1441 |
``'<<Paste>>'``, with each of the physical event patterns given by |
| 1442 |
*sequences*, so that the virtual event triggers whenever any of them |
| 1443 |
occurs. |
| 1444 |
If *virtual* is already defined, the new sequences are added to its |
| 1445 |
existing ones. |
| 1446 |
|
| 1447 |
.. method:: event_delete(virtual, *sequences) |
| 1448 |
|
| 1449 |
Remove each of *sequences* from those associated with the virtual event |
| 1450 |
*virtual*. |
| 1451 |
Sequences that are not currently associated with *virtual* are ignored. |
| 1452 |
If no *sequences* are given, all physical event sequences are removed, so |
| 1453 |
that *virtual* no longer triggers. |
| 1454 |
|
| 1455 |
.. method:: event_generate(sequence, **kw) |
| 1456 |
|
| 1457 |
Generate the event *sequence* on this widget and arrange for it to be |
| 1458 |
processed just as if it had come from the window system. |
| 1459 |
*sequence* must be a single event pattern, such as ``'<Button-1>'`` or |
| 1460 |
``'<<Paste>>'``, not a concatenation of several. |
| 1461 |
Keyword arguments specify additional fields of the event, for example *x* |
| 1462 |
and *y* for the pointer position, or *when* to control when the event is |
| 1463 |
processed; refer to the Tk ``event`` manual page for the full list. |
| 1464 |
|
| 1465 |
.. method:: event_info(virtual=None) |
| 1466 |
|
| 1467 |
If *virtual* is omitted, return a tuple of all the virtual events that |
| 1468 |
are currently defined. |
| 1469 |
If *virtual* is given, return a tuple of the physical event sequences |
| 1470 |
currently associated with it, or an empty tuple if it is not defined. |
| 1471 |
|
| 1472 |
The methods with the ``after`` prefix schedule callbacks to run after a |
| 1473 |
delay or when the application is idle. |
| 1474 |
|
| 1475 |
.. method:: after(ms, func=None, *args) |
| 1476 |
|
| 1477 |
Schedule the callable *func* to be called after *ms* milliseconds, with |
| 1478 |
*args* passed to it as positional arguments. |
| 1479 |
Return an identifier that can be passed to :meth:`after_cancel` to cancel |
| 1480 |
the call. |
| 1481 |
|
| 1482 |
If *func* is omitted, sleep for *ms* milliseconds instead, processing no |
| 1483 |
events during that time, and return ``None``. |
| 1484 |
|
| 1485 |
.. versionchanged:: 3.10 |
| 1486 |
*func* can now be any callable object, not only a function. |
| 1487 |
|
| 1488 |
|
| 1489 |
.. method:: after_cancel(id) |
| 1490 |
|
| 1491 |
Cancel a callback previously scheduled with :meth:`after` or |
| 1492 |
:meth:`after_idle`. |
| 1493 |
*id* must be an identifier returned by one of those methods; passing a |
| 1494 |
value that is not such an identifier raises :exc:`ValueError`. |
| 1495 |
If the callback has already run or been cancelled, this has no effect. |
| 1496 |
|
| 1497 |
.. versionchanged:: 3.7 |
| 1498 |
Passing ``None`` (or any false value) as *id* now raises |
| 1499 |
:exc:`ValueError`. |
| 1500 |
|
| 1501 |
|
| 1502 |
.. method:: after_idle(func, *args) |
| 1503 |
|
| 1504 |
Schedule the callable *func* to be called, with *args* passed to |
| 1505 |
it, when the Tk main loop next becomes idle, that is, when it has no |
| 1506 |
other events to process. |
| 1507 |
Return an identifier that can be passed to :meth:`after_cancel` to cancel |
| 1508 |
the call. |
| 1509 |
|
| 1510 |
|
| 1511 |
.. method:: after_info(id=None) |
| 1512 |
|
| 1513 |
If *id* is omitted, return a tuple of the identifiers of all callbacks |
| 1514 |
currently scheduled with :meth:`after` and :meth:`after_idle` for this |
| 1515 |
interpreter. |
| 1516 |
|
| 1517 |
If *id* is given, it must identify a callback that has not yet run or |
| 1518 |
been cancelled, and the return value is a tuple ``(script, type)``, where |
| 1519 |
*script* refers to the function to be called and *type* is either |
| 1520 |
``'idle'`` or ``'timer'``. |
| 1521 |
A :exc:`TclError` is raised if *id* does not exist. |
| 1522 |
|
| 1523 |
.. versionadded:: 3.13 |
| 1524 |
|
| 1525 |
|
| 1526 |
.. method:: mainloop(n=0) |
| 1527 |
|
| 1528 |
Enter the Tk event loop, which processes events until all windows are |
| 1529 |
destroyed. |
| 1530 |
This is normally called once, on the root window, to run the application. |
| 1531 |
|
| 1532 |
.. method:: quit() |
| 1533 |
|
| 1534 |
Quit the Tcl interpreter, causing :meth:`mainloop` to return. |
| 1535 |
|
| 1536 |
.. method:: update() |
| 1537 |
|
| 1538 |
Enter the event loop until all pending events, including idle callbacks, |
| 1539 |
have been processed. |
| 1540 |
This brings the display up to date and handles any events that are |
| 1541 |
already queued, then returns. |
| 1542 |
|
| 1543 |
.. method:: update_idletasks() |
| 1544 |
|
| 1545 |
Enter the event loop until all pending idle callbacks have been called. |
| 1546 |
This updates the display of windows, for example after geometry changes, |
| 1547 |
but does not process events caused by the user. |
| 1548 |
|
| 1549 |
.. method:: waitvar(name) |
| 1550 |
:no-typesetting: |
| 1551 |
|
| 1552 |
.. method:: wait_variable(name) |
| 1553 |
|
| 1554 |
Wait until the Tcl variable *name* is modified, continuing to process |
| 1555 |
events in the meantime so that the application stays responsive. |
| 1556 |
*name* is usually a :class:`Variable` instance, such as an |
| 1557 |
:class:`IntVar` or :class:`StringVar`. |
| 1558 |
|
| 1559 |
:meth:`waitvar` is an alias of :meth:`!wait_variable`. |
| 1560 |
|
| 1561 |
.. method:: wait_window(window=None) |
| 1562 |
|
| 1563 |
Wait until *window* is destroyed, continuing to process events in the |
| 1564 |
meantime. |
| 1565 |
If *window* is omitted, this widget is used. |
| 1566 |
This is typically used to wait for the user to finish interacting with a |
| 1567 |
dialog box. |
| 1568 |
|
| 1569 |
.. method:: wait_visibility(window=None) |
| 1570 |
|
| 1571 |
Wait until the visibility state of *window* changes, for example when it |
| 1572 |
first appears on the screen, continuing to process events in the |
| 1573 |
meantime. |
| 1574 |
If *window* is omitted, this widget is used. |
| 1575 |
This is typically used to wait for a newly created window to become |
| 1576 |
visible before acting on it. |
| 1577 |
|
| 1578 |
The methods with the ``focus_`` prefix manage the keyboard focus. |
| 1579 |
|
| 1580 |
.. method:: focus_set() |
| 1581 |
:no-typesetting: |
| 1582 |
|
| 1583 |
.. method:: focus() |
| 1584 |
|
| 1585 |
Direct the keyboard input focus for this widget's display to this widget. |
| 1586 |
If the application does not currently have the input focus on this |
| 1587 |
widget's display, the widget is remembered as the focus window for its |
| 1588 |
top level, and the focus will be redirected to it the next time the |
| 1589 |
window manager gives the focus to the top level. |
| 1590 |
:meth:`focus` is an alias of :meth:`!focus_set`, |
| 1591 |
except on the :class:`Canvas` and |
| 1592 |
:class:`ttk.Treeview <tkinter.ttk.Treeview>` widgets, |
| 1593 |
which provide their own :meth:`!focus` method. |
| 1594 |
|
| 1595 |
.. method:: focus_force() |
| 1596 |
|
| 1597 |
Direct the keyboard input focus to this widget even if the application |
| 1598 |
does not currently have the input focus for the widget's display. |
| 1599 |
This method should be used sparingly, if at all; normally an application |
| 1600 |
should wait for the window manager to give it the focus rather than |
| 1601 |
claiming it. |
| 1602 |
|
| 1603 |
.. method:: focus_get() |
| 1604 |
|
| 1605 |
Return the widget that currently has the keyboard focus in the |
| 1606 |
application, or ``None`` if no widget in the application has the focus. |
| 1607 |
Use :meth:`focus_displayof` to work correctly with several displays. |
| 1608 |
|
| 1609 |
.. method:: focus_displayof() |
| 1610 |
|
| 1611 |
Return the widget that currently has the keyboard focus on the display |
| 1612 |
where this widget is located, or ``None`` if no widget in the application |
| 1613 |
has the focus on that display. |
| 1614 |
|
| 1615 |
.. method:: focus_lastfor() |
| 1616 |
|
| 1617 |
Return the most recent widget to have had the keyboard focus among all |
| 1618 |
the widgets in the same top level as this widget; this is the widget that |
| 1619 |
will receive the focus the next time the window manager gives the focus |
| 1620 |
to the top level. |
| 1621 |
If no widget in that top level has ever had the focus, or if the most |
| 1622 |
recent focus widget has been deleted, the top level itself is returned. |
| 1623 |
|
| 1624 |
.. method:: tk_focusFollowsMouse() |
| 1625 |
|
| 1626 |
Reconfigure Tk to use an implicit focus model in which the focus is set |
| 1627 |
to a widget whenever the mouse pointer enters it. |
| 1628 |
This cannot easily be disabled once enabled. |
| 1629 |
|
| 1630 |
.. method:: tk_focusNext() |
| 1631 |
|
| 1632 |
Return the next widget after this one in the keyboard traversal order, or |
| 1633 |
``None`` if there is none. |
| 1634 |
The traversal order goes first to the next child, then recursively to the |
| 1635 |
children of that child, and then to the next sibling higher in the |
| 1636 |
stacking order. |
| 1637 |
A widget is skipped if its ``takefocus`` option is set to ``0``. |
| 1638 |
This method is used in the default bindings for the :kbd:`Tab` key. |
| 1639 |
|
| 1640 |
.. method:: tk_focusPrev() |
| 1641 |
|
| 1642 |
Return the previous widget before this one in the keyboard traversal |
| 1643 |
order, or ``None`` if there is none. |
| 1644 |
See :meth:`tk_focusNext` for how the order is defined. |
| 1645 |
This method is used in the default bindings for the :kbd:`Shift-Tab` key. |
| 1646 |
|
| 1647 |
The methods with the ``grab_`` prefix set and query the input grab, which |
| 1648 |
directs all input events to a single widget. |
| 1649 |
|
| 1650 |
.. method:: grab_set() |
| 1651 |
|
| 1652 |
Set a local grab on this widget. |
| 1653 |
A grab confines pointer events to this widget and its descendants: while |
| 1654 |
the pointer is outside the widget's subtree, button presses and releases |
| 1655 |
and pointer motion are reported to the grab widget, and windows outside |
| 1656 |
the subtree become insensitive until the grab is released. |
| 1657 |
A local grab affects only the grabbing application. |
| 1658 |
Any grab previously set by this application on the widget's display is |
| 1659 |
automatically released. |
| 1660 |
Setting a grab is the usual way to make a dialog modal: while the grab is |
| 1661 |
in effect the user cannot interact with the other windows of the |
| 1662 |
application. |
| 1663 |
|
| 1664 |
.. method:: grab_set_global() |
| 1665 |
|
| 1666 |
Set a global grab on this widget. |
| 1667 |
A global grab is like the local grab set by :meth:`grab_set`, but it |
| 1668 |
locks out all other applications on the screen, so that only this |
| 1669 |
widget's subtree is sensitive to pointer events, and it also grabs the |
| 1670 |
keyboard. |
| 1671 |
Use with caution: it is easy to render a display unusable with a global |
| 1672 |
grab, since other applications stop receiving events until it is |
| 1673 |
released. |
| 1674 |
|
| 1675 |
.. method:: grab_release() |
| 1676 |
|
| 1677 |
Release the grab on this widget if there is one; otherwise do nothing. |
| 1678 |
|
| 1679 |
.. method:: grab_current() |
| 1680 |
|
| 1681 |
Return the widget that currently holds the grab in this application for |
| 1682 |
this widget's display, or ``None`` if there is no such widget. |
| 1683 |
|
| 1684 |
.. method:: grab_status() |
| 1685 |
|
| 1686 |
Return ``None`` if no grab is currently set on this widget, ``"local"`` |
| 1687 |
if a local grab is set, or ``"global"`` if a global grab is set. |
| 1688 |
|
| 1689 |
The methods with the ``selection_`` prefix retrieve and manage the X |
| 1690 |
selection. |
| 1691 |
|
| 1692 |
.. method:: selection_clear(**kw) |
| 1693 |
|
| 1694 |
Clear the X selection, so that no window owns it anymore. |
| 1695 |
The selection to clear is given by the keyword argument *selection*, an |
| 1696 |
atom name such as ``'PRIMARY'`` or ``'CLIPBOARD'``; it defaults to |
| 1697 |
``PRIMARY``. |
| 1698 |
The *displayof* keyword argument names a widget that determines the |
| 1699 |
display on which to operate, and defaults to this widget. |
| 1700 |
|
| 1701 |
This is overridden by the :class:`Entry`, :class:`Listbox` and |
| 1702 |
:class:`Spinbox` widgets, |
| 1703 |
where :meth:`!selection_clear` clears the widget's own selection instead. |
| 1704 |
|
| 1705 |
.. method:: selection_get(**kw) |
| 1706 |
|
| 1707 |
Return the contents of the current X selection. |
| 1708 |
The keyword argument *selection* names the selection and defaults to |
| 1709 |
``PRIMARY``. |
| 1710 |
The keyword argument *type* specifies the form in which the data is to be |
| 1711 |
returned (the desired conversion target), an atom name such as |
| 1712 |
``'STRING'`` or ``'FILE_NAME'``; it defaults to ``STRING``, except on |
| 1713 |
X11, where ``UTF8_STRING`` is tried first and ``STRING`` is used as a |
| 1714 |
fallback. |
| 1715 |
The *displayof* keyword argument names a widget that determines the |
| 1716 |
display from which to retrieve the selection, and defaults to this |
| 1717 |
widget. |
| 1718 |
|
| 1719 |
.. method:: selection_handle(command, **kw) |
| 1720 |
|
| 1721 |
Register *command* as a handler to supply the X selection owned by this |
| 1722 |
widget when another application requests it. |
| 1723 |
When the selection is retrieved, *command* is called with two arguments, |
| 1724 |
the starting character offset and the maximum number of characters to |
| 1725 |
return, and must return at most that many characters of the selection |
| 1726 |
starting at that offset; for very long selections it is called repeatedly |
| 1727 |
with increasing offsets. |
| 1728 |
The keyword argument *selection* names the selection (default |
| 1729 |
``PRIMARY``) and the keyword argument *type* gives the form of the |
| 1730 |
selection that the handler supplies (such as ``'STRING'`` or |
| 1731 |
``'FILE_NAME'``, default ``STRING``). |
| 1732 |
|
| 1733 |
.. method:: selection_own(**kw) |
| 1734 |
|
| 1735 |
Make this widget the owner of the X selection on its display. |
| 1736 |
The previous owner, if any, is notified that it has lost the selection. |
| 1737 |
The keyword argument *selection* names the selection and defaults to |
| 1738 |
``PRIMARY``. |
| 1739 |
|
| 1740 |
.. method:: selection_own_get(**kw) |
| 1741 |
|
| 1742 |
Return the widget in this application that owns the X selection on the |
| 1743 |
display containing this widget, or ``None`` if no widget in this |
| 1744 |
application owns the selection. |
| 1745 |
The keyword argument *selection* names the selection and defaults to |
| 1746 |
``PRIMARY``. |
| 1747 |
The *displayof* keyword argument names a widget that determines the |
| 1748 |
display to query, and defaults to this widget. |
| 1749 |
|
| 1750 |
The methods with the ``clipboard_`` prefix manage the clipboard. |
| 1751 |
|
| 1752 |
.. method:: clipboard_append(string, **kw) |
| 1753 |
|
| 1754 |
Append *string* to the Tk clipboard and claim ownership of the clipboard |
| 1755 |
on this widget's display. |
| 1756 |
Before appending, the clipboard should be emptied with |
| 1757 |
:meth:`clipboard_clear`; all appends should be completed before returning |
| 1758 |
to the event loop so that the clipboard is updated atomically. |
| 1759 |
The keyword argument *type* specifies the form of the data, an atom name |
| 1760 |
such as ``'STRING'`` or ``'FILE_NAME'`` (default ``STRING``), and the |
| 1761 |
keyword argument *format* specifies the representation used to transmit |
| 1762 |
it (default ``STRING``). |
| 1763 |
The *displayof* keyword argument names a widget that determines the |
| 1764 |
target display, and defaults to this widget. |
| 1765 |
The contents can be retrieved with :meth:`clipboard_get` or |
| 1766 |
:meth:`selection_get`. |
| 1767 |
|
| 1768 |
.. method:: clipboard_clear(**kw) |
| 1769 |
|
| 1770 |
Claim ownership of the clipboard on this widget's display and remove any |
| 1771 |
previous contents. |
| 1772 |
The *displayof* keyword argument names a widget that determines the |
| 1773 |
target display, and defaults to this widget. |
| 1774 |
|
| 1775 |
.. method:: clipboard_get(**kw) |
| 1776 |
|
| 1777 |
Retrieve data from the clipboard on this widget's display. |
| 1778 |
The keyword argument *type* specifies the form in which the data is to be |
| 1779 |
returned, an atom name such as ``'STRING'`` or ``'FILE_NAME'``; it |
| 1780 |
defaults to ``STRING``, except on X11, where ``UTF8_STRING`` is tried |
| 1781 |
first and ``STRING`` is used as a fallback. |
| 1782 |
The *displayof* keyword argument names a widget that determines the |
| 1783 |
display, and defaults to the root window of the application. |
| 1784 |
This is equivalent to ``selection_get(selection='CLIPBOARD')``. |
| 1785 |
|
| 1786 |
The methods with the ``option_`` prefix query and modify the Tk option |
| 1787 |
database. |
| 1788 |
|
| 1789 |
.. method:: option_add(pattern, value, priority=None) |
| 1790 |
|
| 1791 |
Add an option to the Tk option database that associates *value* with |
| 1792 |
*pattern*. |
| 1793 |
*pattern* consists of names and/or classes separated by asterisks or |
| 1794 |
dots, in the usual X format. |
| 1795 |
*priority* is an integer between 0 and 100, or one of the symbolic names |
| 1796 |
``'widgetDefault'`` (20), ``'startupFile'`` (40), ``'userDefault'`` (60), |
| 1797 |
or ``'interactive'`` (80); it defaults to ``interactive``. |
| 1798 |
|
| 1799 |
.. method:: option_clear() |
| 1800 |
|
| 1801 |
Clear the Tk option database. |
| 1802 |
Default options from the :envvar:`!RESOURCE_MANAGER` property or the |
| 1803 |
:file:`.Xdefaults` file are reloaded automatically the next time an |
| 1804 |
option is added to or removed from the database. |
| 1805 |
|
| 1806 |
.. method:: option_get(name, className) |
| 1807 |
|
| 1808 |
Return the value of the option matching this widget under *name* and |
| 1809 |
*className* from the Tk option database, or an empty string if there is |
| 1810 |
no matching entry. |
| 1811 |
When several entries match, the one with the highest priority is |
| 1812 |
returned, and among entries of equal priority the most recently added |
| 1813 |
one. |
| 1814 |
|
| 1815 |
.. method:: option_readfile(fileName, priority=None) |
| 1816 |
|
| 1817 |
Read the file named *fileName*, which should have the standard format for |
| 1818 |
an X resource database such as :file:`.Xdefaults`, and add all the |
| 1819 |
options it specifies to the Tk option database. |
| 1820 |
*priority* is interpreted as for :meth:`option_add` and defaults to |
| 1821 |
``interactive``. |
| 1822 |
|
| 1823 |
.. method:: bell(displayof=0) |
| 1824 |
|
| 1825 |
Ring the bell on the display for this widget, using the display's current |
| 1826 |
bell-related settings, and reset the screen saver for the screen. |
| 1827 |
If *displayof* is given as a widget, the bell is rung on that widget's |
| 1828 |
display instead. |
| 1829 |
|
| 1830 |
.. method:: tk_setPalette(background, /) |
| 1831 |
tk_setPalette(*args, **kw) |
| 1832 |
|
| 1833 |
Set a new color scheme for all Tk widget elements. |
| 1834 |
Existing widgets are updated and the option database is changed so that |
| 1835 |
future widgets use the new colors. |
| 1836 |
A single color argument is taken as the normal background color, from |
| 1837 |
which a complete palette is computed. |
| 1838 |
Alternatively, the arguments may be given as keyword *name*/*value* pairs |
| 1839 |
naming individual options in the option database. |
| 1840 |
The recognized option names are ``activeBackground``, |
| 1841 |
``activeForeground``, ``background``, ``disabledForeground``, |
| 1842 |
``foreground``, ``highlightBackground``, ``highlightColor``, |
| 1843 |
``insertBackground``, ``selectColor``, ``selectBackground``, |
| 1844 |
``selectForeground``, and ``troughColor``; reasonable defaults are |
| 1845 |
computed for any that are not specified. |
| 1846 |
|
| 1847 |
.. method:: tk_bisque() |
| 1848 |
|
| 1849 |
Restore the application's colors to the light brown (bisque) color scheme |
| 1850 |
used in Tk 3.6 and earlier versions. |
| 1851 |
Provided for backward compatibility. |
| 1852 |
|
| 1853 |
.. method:: tk_strictMotif(boolean=None) |
| 1854 |
|
| 1855 |
Query or set whether Tk's look and feel should strictly adhere to Motif. |
| 1856 |
A true *boolean* value enables strict Motif compliance (for example, no |
| 1857 |
color change when the mouse passes over a slider). |
| 1858 |
Return the resulting setting. |
| 1859 |
|
| 1860 |
The methods with the ``busy_`` prefix manage the busy state of a window, |
| 1861 |
which shows a busy cursor and ignores user input. |
| 1862 |
|
| 1863 |
.. method:: busy(**kw) |
| 1864 |
:no-typesetting: |
| 1865 |
|
| 1866 |
.. method:: busy_hold(**kw) |
| 1867 |
:no-typesetting: |
| 1868 |
|
| 1869 |
.. method:: tk_busy(**kw) |
| 1870 |
:no-typesetting: |
| 1871 |
|
| 1872 |
.. method:: tk_busy_hold(**kw) |
| 1873 |
|
| 1874 |
Make this widget appear busy. |
| 1875 |
A transparent window is placed in front of the widget, so that it and all |
| 1876 |
of its descendants in the widget hierarchy are blocked from pointer |
| 1877 |
events and display a busy cursor. |
| 1878 |
Normally :meth:`update` should be called immediately afterwards to ensure |
| 1879 |
that the hold operation is in effect before the application starts its |
| 1880 |
processing. |
| 1881 |
|
| 1882 |
The only supported configuration option is *cursor*, the cursor to be |
| 1883 |
displayed while the widget is busy; it may have any of the values |
| 1884 |
accepted by :meth:`!configure`. |
| 1885 |
|
| 1886 |
:meth:`busy_hold`, :meth:`busy` and :meth:`tk_busy` are aliases of |
| 1887 |
:meth:`!tk_busy_hold`. |
| 1888 |
|
| 1889 |
.. versionadded:: 3.13 |
| 1890 |
|
| 1891 |
|
| 1892 |
.. method:: busy_configure(cnf=None, **kw) |
| 1893 |
:no-typesetting: |
| 1894 |
|
| 1895 |
.. method:: busy_config(cnf=None, **kw) |
| 1896 |
:no-typesetting: |
| 1897 |
|
| 1898 |
.. method:: tk_busy_config(cnf=None, **kw) |
| 1899 |
:no-typesetting: |
| 1900 |
|
| 1901 |
.. method:: tk_busy_configure(cnf=None, **kw) |
| 1902 |
|
| 1903 |
Query or modify the configuration options of the busy window. |
| 1904 |
The widget must have been previously made busy by :meth:`tk_busy_hold`. |
| 1905 |
With no arguments, return a dictionary describing all of the available |
| 1906 |
options; if *cnf* is the name of an option, return a tuple describing |
| 1907 |
that one option. |
| 1908 |
Otherwise set the given options to the given values. |
| 1909 |
Options may have any of the values accepted by :meth:`tk_busy_hold`. |
| 1910 |
|
| 1911 |
The option database is referenced through the widget name or class. |
| 1912 |
For example, if a :class:`Frame` widget named ``frame`` is to be made |
| 1913 |
busy, the busy cursor can be specified for it by either of the calls:: |
| 1914 |
|
| 1915 |
w.option_add('*frame.busyCursor', 'gumby') |
| 1916 |
w.option_add('*Frame.BusyCursor', 'gumby') |
| 1917 |
|
| 1918 |
:meth:`busy_configure`, :meth:`busy_config` and :meth:`tk_busy_config` |
| 1919 |
are aliases of :meth:`!tk_busy_configure`. |
| 1920 |
|
| 1921 |
.. versionadded:: 3.13 |
| 1922 |
|
| 1923 |
|
| 1924 |
.. method:: busy_cget(option) |
| 1925 |
:no-typesetting: |
| 1926 |
|
| 1927 |
.. method:: tk_busy_cget(option) |
| 1928 |
|
| 1929 |
Return the current value of the busy configuration *option*. |
| 1930 |
The widget must have been previously made busy by :meth:`tk_busy_hold`, |
| 1931 |
and *option* may have any of the values accepted by that method. |
| 1932 |
|
| 1933 |
:meth:`busy_cget` is an alias of :meth:`!tk_busy_cget`. |
| 1934 |
|
| 1935 |
.. versionadded:: 3.13 |
| 1936 |
|
| 1937 |
|
| 1938 |
.. method:: busy_forget() |
| 1939 |
:no-typesetting: |
| 1940 |
|
| 1941 |
.. method:: tk_busy_forget() |
| 1942 |
|
| 1943 |
Make this widget no longer busy, releasing the resources (including the |
| 1944 |
transparent window) allocated when it was made busy. |
| 1945 |
User events will again be received by the widget. |
| 1946 |
These resources are also released when the widget is destroyed. |
| 1947 |
|
| 1948 |
:meth:`busy_forget` is an alias of :meth:`!tk_busy_forget`. |
| 1949 |
|
| 1950 |
.. versionadded:: 3.13 |
| 1951 |
|
| 1952 |
|
| 1953 |
.. method:: busy_status() |
| 1954 |
:no-typesetting: |
| 1955 |
|
| 1956 |
.. method:: tk_busy_status() |
| 1957 |
|
| 1958 |
Return ``True`` if the widget is currently busy, ``False`` otherwise. |
| 1959 |
|
| 1960 |
:meth:`busy_status` is an alias of :meth:`!tk_busy_status`. |
| 1961 |
|
| 1962 |
.. versionadded:: 3.13 |
| 1963 |
|
| 1964 |
|
| 1965 |
.. method:: busy_current(pattern=None) |
| 1966 |
:no-typesetting: |
| 1967 |
|
| 1968 |
.. method:: tk_busy_current(pattern=None) |
| 1969 |
|
| 1970 |
Return a list of widgets that are currently busy. |
| 1971 |
If *pattern* is given, only busy widgets whose path names match the |
| 1972 |
pattern are returned. |
| 1973 |
|
| 1974 |
:meth:`busy_current` is an alias of :meth:`!tk_busy_current`. |
| 1975 |
|
| 1976 |
.. versionadded:: 3.13 |
| 1977 |
|
| 1978 |
The methods with the ``winfo_`` prefix retrieve information about windows |
| 1979 |
managed by Tk. |
| 1980 |
|
| 1981 |
.. method:: winfo_atom(name, displayof=0) |
| 1982 |
|
| 1983 |
Return the integer identifier for the atom whose name is *name*, creating |
| 1984 |
a new atom if none exists. |
| 1985 |
If *displayof* is given, the atom is looked up on the display of that |
| 1986 |
window; otherwise it is looked up on the display of the application's |
| 1987 |
main window. |
| 1988 |
|
| 1989 |
.. method:: winfo_atomname(id, displayof=0) |
| 1990 |
|
| 1991 |
Return the textual name for the atom whose integer identifier is *id*. |
| 1992 |
This is the inverse of :meth:`winfo_atom`. |
| 1993 |
If *displayof* is given, the identifier is looked up on the display of |
| 1994 |
that window; otherwise it is looked up on the display of the |
| 1995 |
application's main window. |
| 1996 |
|
| 1997 |
.. method:: winfo_cells() |
| 1998 |
|
| 1999 |
Return the number of cells in the colormap for the widget. |
| 2000 |
|
| 2001 |
.. method:: winfo_children() |
| 2002 |
|
| 2003 |
Return a list containing the widgets that are children of the widget, in |
| 2004 |
stacking order from lowest to highest. |
| 2005 |
Toplevel windows are returned as children of their logical parents. |
| 2006 |
|
| 2007 |
.. method:: winfo_class() |
| 2008 |
|
| 2009 |
Return the class name of the widget. |
| 2010 |
|
| 2011 |
.. method:: winfo_colormapfull() |
| 2012 |
|
| 2013 |
Return ``True`` if the colormap for the widget is known to be full, |
| 2014 |
``False`` otherwise. |
| 2015 |
|
| 2016 |
.. method:: winfo_containing(rootX, rootY, displayof=0) |
| 2017 |
|
| 2018 |
Return the widget containing the point given by *rootX* and *rootY*, or |
| 2019 |
``None`` if no window in this application contains the point. |
| 2020 |
The coordinates are in screen units in the coordinate system of the root |
| 2021 |
window. |
| 2022 |
If *displayof* is given, the coordinates refer to the screen containing |
| 2023 |
that window; otherwise they refer to the screen of the application's main |
| 2024 |
window. |
| 2025 |
|
| 2026 |
.. method:: winfo_depth() |
| 2027 |
|
| 2028 |
Return the depth of the widget, that is, the number of bits per pixel. |
| 2029 |
|
| 2030 |
.. method:: winfo_exists() |
| 2031 |
|
| 2032 |
Return true if the widget exists, false otherwise. |
| 2033 |
|
| 2034 |
.. method:: winfo_fpixels(number) |
| 2035 |
|
| 2036 |
Return a floating-point value giving the number of pixels in the widget |
| 2037 |
corresponding to the screen distance *number* (for example, |
| 2038 |
``"2.0c"`` or ``"1i"``). |
| 2039 |
The result may be fractional; for a rounded integer value use |
| 2040 |
:meth:`winfo_pixels`. |
| 2041 |
|
| 2042 |
.. method:: winfo_geometry() |
| 2043 |
|
| 2044 |
Return the geometry of the widget, in the form ``widthxheight+x+y``. |
| 2045 |
All dimensions are in pixels. |
| 2046 |
An offset can be negative; see :meth:`~Wm.geometry`. |
| 2047 |
|
| 2048 |
.. method:: winfo_height() |
| 2049 |
|
| 2050 |
Return the height of the widget in pixels. |
| 2051 |
When a window is first created its height is 1 pixel; it is eventually |
| 2052 |
changed by a geometry manager. |
| 2053 |
See also :meth:`winfo_reqheight`. |
| 2054 |
|
| 2055 |
.. method:: winfo_id() |
| 2056 |
|
| 2057 |
Return a low-level platform-specific identifier for the widget. |
| 2058 |
On Unix this is the X window identifier, and on Windows it is the window |
| 2059 |
handle. |
| 2060 |
|
| 2061 |
.. method:: winfo_interps(displayof=0) |
| 2062 |
|
| 2063 |
Return a tuple of the names of all Tcl interpreters currently registered |
| 2064 |
for a particular display. |
| 2065 |
If *displayof* is given, the return value refers to the display of that |
| 2066 |
window; otherwise it refers to the display of the application's main |
| 2067 |
window. |
| 2068 |
|
| 2069 |
.. method:: winfo_ismapped() |
| 2070 |
|
| 2071 |
Return true if the widget is currently mapped, false otherwise. |
| 2072 |
|
| 2073 |
.. method:: winfo_manager() |
| 2074 |
|
| 2075 |
Return the name of the geometry manager currently responsible for the |
| 2076 |
widget, or an empty string if it is not managed by any geometry manager. |
| 2077 |
|
| 2078 |
.. method:: winfo_name() |
| 2079 |
|
| 2080 |
Return the widget's name within its parent, as opposed to its full path |
| 2081 |
name. |
| 2082 |
|
| 2083 |
.. method:: winfo_parent() |
| 2084 |
|
| 2085 |
Return the path name of the widget's parent, or an empty string if the |
| 2086 |
widget is the main window of the application. |
| 2087 |
|
| 2088 |
.. method:: winfo_pathname(id, displayof=0) |
| 2089 |
|
| 2090 |
Return the path name of the window whose identifier is *id*. |
| 2091 |
If *displayof* is given, the identifier is looked up on the display of |
| 2092 |
that window; otherwise it is looked up on the display of the |
| 2093 |
application's main window. |
| 2094 |
|
| 2095 |
.. method:: winfo_pixels(number) |
| 2096 |
|
| 2097 |
Return the number of pixels in the widget corresponding to the screen |
| 2098 |
distance *number* (for example, ``"2.0c"`` or ``"1i"``). |
| 2099 |
The result is rounded to the nearest integer; for a fractional result use |
| 2100 |
:meth:`winfo_fpixels`. |
| 2101 |
|
| 2102 |
.. method:: winfo_pointerx() |
| 2103 |
|
| 2104 |
Return the pointer's *x* coordinate, in pixels, relative to the screen's |
| 2105 |
root window (or virtual root, if one is in use). |
| 2106 |
Return ``-1`` if the pointer is not on the same screen as the widget. |
| 2107 |
|
| 2108 |
.. method:: winfo_pointerxy() |
| 2109 |
|
| 2110 |
Return the pointer's coordinates as an ``(x, y)`` tuple, in pixels, |
| 2111 |
relative to the screen's root window (or virtual root, if one is in use). |
| 2112 |
Both coordinates are ``-1`` if the pointer is not on the same screen as |
| 2113 |
the widget. |
| 2114 |
|
| 2115 |
.. method:: winfo_pointery() |
| 2116 |
|
| 2117 |
Return the pointer's *y* coordinate, in pixels, relative to the screen's |
| 2118 |
root window (or virtual root, if one is in use). |
| 2119 |
Return ``-1`` if the pointer is not on the same screen as the widget. |
| 2120 |
|
| 2121 |
.. method:: winfo_reqheight() |
| 2122 |
|
| 2123 |
Return the widget's requested height in pixels. |
| 2124 |
This is the value used by the widget's geometry manager to compute its |
| 2125 |
geometry. |
| 2126 |
|
| 2127 |
.. method:: winfo_reqwidth() |
| 2128 |
|
| 2129 |
Return the widget's requested width in pixels. |
| 2130 |
This is the value used by the widget's geometry manager to compute its |
| 2131 |
geometry. |
| 2132 |
|
| 2133 |
.. method:: winfo_rgb(color) |
| 2134 |
|
| 2135 |
Return an ``(r, g, b)`` tuple of the red, green, and blue intensities, in |
| 2136 |
the range 0 to 65535, that correspond to *color* in the widget. |
| 2137 |
*color* may be specified in any of the forms acceptable for a color |
| 2138 |
option. |
| 2139 |
|
| 2140 |
.. method:: winfo_rootx() |
| 2141 |
|
| 2142 |
Return the *x* coordinate, in the root window of the screen, of the |
| 2143 |
upper-left corner of the widget's border (or of the widget itself if it |
| 2144 |
has no border). |
| 2145 |
|
| 2146 |
.. method:: winfo_rooty() |
| 2147 |
|
| 2148 |
Return the *y* coordinate, in the root window of the screen, of the |
| 2149 |
upper-left corner of the widget's border (or of the widget itself if it |
| 2150 |
has no border). |
| 2151 |
|
| 2152 |
.. method:: winfo_screen() |
| 2153 |
|
| 2154 |
Return the name of the screen associated with the widget, in the form |
| 2155 |
``displayName.screenIndex``. |
| 2156 |
|
| 2157 |
.. method:: winfo_screencells() |
| 2158 |
|
| 2159 |
Return the number of cells in the default colormap for the widget's |
| 2160 |
screen. |
| 2161 |
|
| 2162 |
.. method:: winfo_screendepth() |
| 2163 |
|
| 2164 |
Return the depth of the root window of the widget's screen, that is, the |
| 2165 |
number of bits per pixel. |
| 2166 |
|
| 2167 |
.. method:: winfo_screenheight() |
| 2168 |
|
| 2169 |
Return the height of the widget's screen in pixels. |
| 2170 |
|
| 2171 |
.. method:: winfo_screenmmheight() |
| 2172 |
|
| 2173 |
Return the height of the widget's screen in millimeters. |
| 2174 |
|
| 2175 |
.. method:: winfo_screenmmwidth() |
| 2176 |
|
| 2177 |
Return the width of the widget's screen in millimeters. |
| 2178 |
|
| 2179 |
.. method:: winfo_screenvisual() |
| 2180 |
|
| 2181 |
Return the default visual class for the widget's screen, one of |
| 2182 |
``"directcolor"``, ``"grayscale"``, ``"pseudocolor"``, ``"staticcolor"``, |
| 2183 |
``"staticgray"``, or ``"truecolor"``. |
| 2184 |
|
| 2185 |
.. method:: winfo_screenwidth() |
| 2186 |
|
| 2187 |
Return the width of the widget's screen in pixels. |
| 2188 |
|
| 2189 |
.. method:: winfo_server() |
| 2190 |
|
| 2191 |
Return a string containing information about the server for the widget's |
| 2192 |
display. |
| 2193 |
The exact format of this string may vary from platform to platform. |
| 2194 |
|
| 2195 |
.. method:: winfo_toplevel() |
| 2196 |
|
| 2197 |
Return the top-of-hierarchy window containing the widget. |
| 2198 |
In standard Tk this is always a :class:`Toplevel` widget. |
| 2199 |
|
| 2200 |
.. method:: winfo_viewable() |
| 2201 |
|
| 2202 |
Return true if the widget and all of its ancestors up through the |
| 2203 |
nearest toplevel window are mapped, false otherwise. |
| 2204 |
|
| 2205 |
.. method:: winfo_visual() |
| 2206 |
|
| 2207 |
Return the visual class for the widget, one of ``"directcolor"``, |
| 2208 |
``"grayscale"``, ``"pseudocolor"``, ``"staticcolor"``, ``"staticgray"``, |
| 2209 |
or ``"truecolor"``. |
| 2210 |
|
| 2211 |
.. method:: winfo_visualid() |
| 2212 |
|
| 2213 |
Return the X identifier for the visual for the widget. |
| 2214 |
|
| 2215 |
.. method:: winfo_visualsavailable(includeids=False) |
| 2216 |
|
| 2217 |
Return a list describing the visuals available for the widget's screen. |
| 2218 |
Each item consists of a visual class (see :meth:`winfo_visual`) followed |
| 2219 |
by an integer depth. |
| 2220 |
If *includeids* is true, the X identifier for the visual is also |
| 2221 |
included. |
| 2222 |
|
| 2223 |
.. method:: winfo_vrootheight() |
| 2224 |
|
| 2225 |
Return the height of the virtual root window associated with the widget |
| 2226 |
if there is one; otherwise return the height of the widget's screen. |
| 2227 |
|
| 2228 |
.. method:: winfo_vrootwidth() |
| 2229 |
|
| 2230 |
Return the width of the virtual root window associated with the widget if |
| 2231 |
there is one; otherwise return the width of the widget's screen. |
| 2232 |
|
| 2233 |
.. method:: winfo_vrootx() |
| 2234 |
|
| 2235 |
Return the *x* offset of the virtual root window associated with the |
| 2236 |
widget, relative to the root window of its screen. |
| 2237 |
This is normally zero or negative, and is ``0`` if there is no virtual |
| 2238 |
root window. |
| 2239 |
|
| 2240 |
.. method:: winfo_vrooty() |
| 2241 |
|
| 2242 |
Return the *y* offset of the virtual root window associated with the |
| 2243 |
widget, relative to the root window of its screen. |
| 2244 |
This is normally zero or negative, and is ``0`` if there is no virtual |
| 2245 |
root window. |
| 2246 |
|
| 2247 |
.. method:: winfo_width() |
| 2248 |
|
| 2249 |
Return the width of the widget in pixels. |
| 2250 |
When a window is first created its width is 1 pixel; it is eventually |
| 2251 |
changed by a geometry manager. |
| 2252 |
See also :meth:`winfo_reqwidth`. |
| 2253 |
|
| 2254 |
.. method:: winfo_x() |
| 2255 |
|
| 2256 |
Return the *x* coordinate, in the widget's parent, of the upper-left |
| 2257 |
corner of the widget's border (or of the widget itself if it has no |
| 2258 |
border). |
| 2259 |
|
| 2260 |
.. method:: winfo_y() |
| 2261 |
|
| 2262 |
Return the *y* coordinate, in the widget's parent, of the upper-left |
| 2263 |
corner of the widget's border (or of the widget itself if it has no |
| 2264 |
border). |
| 2265 |
|
| 2266 |
.. method:: info_patchlevel() |
| 2267 |
|
| 2268 |
Return the Tcl/Tk patch level as a named tuple with the same five fields |
| 2269 |
as :data:`sys.version_info`: *major*, *minor*, *micro*, *releaselevel* |
| 2270 |
and *serial*. |
| 2271 |
*releaselevel* is ``'alpha'``, ``'beta'`` or ``'final'``. |
| 2272 |
Converting it to a string gives the version in the usual Tcl/Tk notation, |
| 2273 |
for example ``'9.0.3'`` for a final release or ``'9.1b2'`` for a |
| 2274 |
pre-release. |
| 2275 |
|
| 2276 |
.. versionadded:: 3.11 |
| 2277 |
|
| 2278 |
|
| 2279 |
|
| 2280 |
.. class:: Wm() |
| 2281 |
|
| 2282 |
The :class:`!Wm` mixin provides access to the window manager, allowing an |
| 2283 |
application to control such things as the title, geometry and icon of a |
| 2284 |
top-level window, the way it is resized, and how it responds to window |
| 2285 |
manager protocols. |
| 2286 |
It is mixed into :class:`Tk` and :class:`Toplevel`, so its methods are |
| 2287 |
available on every top-level window. |
| 2288 |
Each method has two equivalent spellings: a short name and a |
| 2289 |
``wm_``-prefixed name (for example, :meth:`title` and :meth:`wm_title`). |
| 2290 |
See also :ref:`tkinter-window-manager`. |
| 2291 |
|
| 2292 |
.. method:: wm_aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) |
| 2293 |
:no-typesetting: |
| 2294 |
|
| 2295 |
.. method:: aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None) |
| 2296 |
|
| 2297 |
Constrain the aspect ratio (the ratio of width to height) of the window. |
| 2298 |
If all four arguments are given, the window manager keeps the ratio |
| 2299 |
between ``minNumer/minDenom`` and ``maxNumer/maxDenom``; passing empty |
| 2300 |
strings removes any existing restriction. |
| 2301 |
With no arguments, return a tuple of the four current values, or ``None`` |
| 2302 |
if no aspect restriction is in effect. |
| 2303 |
:meth:`wm_aspect` is an alias of :meth:`!aspect`. |
| 2304 |
|
| 2305 |
.. method:: wm_attributes(*args, return_python_dict=False, **kwargs) |
| 2306 |
:no-typesetting: |
| 2307 |
|
| 2308 |
.. method:: attributes(*args, return_python_dict=False, **kwargs) |
| 2309 |
|
| 2310 |
Query or set platform-specific attributes of the window. |
| 2311 |
With no arguments, return the platform-specific flags and their values; |
| 2312 |
pass *return_python_dict* as true to get them as a dictionary. |
| 2313 |
A single option name such as ``'alpha'`` returns the value of that |
| 2314 |
option, and options are set using keyword arguments (``alpha=0.5``). |
| 2315 |
|
| 2316 |
The available attributes differ by platform. |
| 2317 |
All platforms support: |
| 2318 |
|
| 2319 |
*alpha* |
| 2320 |
The window's opacity, from ``0.0`` (fully transparent) to ``1.0`` |
| 2321 |
(opaque). |
| 2322 |
Where transparency is unsupported the value stays at ``1.0``. |
| 2323 |
|
| 2324 |
*appearance* |
| 2325 |
Whether the window is rendered in dark mode on Windows and macOS: |
| 2326 |
``'auto'``, ``'light'`` or ``'dark'`` (this has no effect on X11). |
| 2327 |
|
| 2328 |
*fullscreen* |
| 2329 |
Whether the window takes up the entire screen and has no borders. |
| 2330 |
|
| 2331 |
*topmost* |
| 2332 |
Whether the window is displayed above all other windows. |
| 2333 |
|
| 2334 |
Windows additionally supports: |
| 2335 |
|
| 2336 |
*disabled* |
| 2337 |
Whether the window is in a disabled state. |
| 2338 |
|
| 2339 |
*toolwindow* |
| 2340 |
Whether the window uses the tool window style. |
| 2341 |
|
| 2342 |
*transparentcolor* |
| 2343 |
The color that is made fully transparent, or an empty string for none. |
| 2344 |
|
| 2345 |
macOS additionally supports: |
| 2346 |
|
| 2347 |
*class* |
| 2348 |
Whether the underlying Aqua window is an ``nswindow`` or an |
| 2349 |
``nspanel``; this can only be set before the window is created. |
| 2350 |
|
| 2351 |
*modified* |
| 2352 |
The modification state shown by the window's close button and proxy |
| 2353 |
icon. |
| 2354 |
|
| 2355 |
*notify* |
| 2356 |
Whether the application's dock icon bounces to request attention. |
| 2357 |
|
| 2358 |
*stylemask* |
| 2359 |
The style mask of the underlying Aqua window, given as a list of bit |
| 2360 |
names such as ``titled`` or ``resizable``. |
| 2361 |
|
| 2362 |
*tabbingid* |
| 2363 |
The identifier of the tab group that the window belongs to. |
| 2364 |
|
| 2365 |
*tabbingmode* |
| 2366 |
Whether the window may be opened as a tab: ``'auto'``, ``'preferred'`` |
| 2367 |
or ``'disallowed'``. |
| 2368 |
|
| 2369 |
*titlepath* |
| 2370 |
The path of the file represented by the window's proxy icon. |
| 2371 |
|
| 2372 |
*transparent* |
| 2373 |
Whether the content area is transparent and the window shadow is |
| 2374 |
turned off. |
| 2375 |
|
| 2376 |
X11 additionally supports: |
| 2377 |
|
| 2378 |
*type* |
| 2379 |
The window type, or a list of types in order of preference, that the |
| 2380 |
window manager should use to interpret the window, such as |
| 2381 |
``'dialog'`` or ``'splash'``. |
| 2382 |
|
| 2383 |
*zoomed* |
| 2384 |
Whether the window is maximized. |
| 2385 |
|
| 2386 |
.. note:: |
| 2387 |
|
| 2388 |
Tk 8.6 added the *type* attribute, and Tk 9.0 added the *appearance*, |
| 2389 |
*class*, *stylemask*, *tabbingid* and *tabbingmode* attributes. |
| 2390 |
|
| 2391 |
On X11 changes are applied asynchronously, so a queried value may not yet |
| 2392 |
reflect the most recent request. |
| 2393 |
:meth:`wm_attributes` is an alias of :meth:`!attributes`. |
| 2394 |
|
| 2395 |
.. versionchanged:: 3.13 |
| 2396 |
A single attribute may now be queried by name without the leading |
| 2397 |
``-``, and attributes may be set using keyword arguments. |
| 2398 |
The *return_python_dict* parameter was added. |
| 2399 |
|
| 2400 |
.. deprecated:: 3.13 |
| 2401 |
Setting an attribute by passing the option name (with a leading |
| 2402 |
``-``) and its value as two positional arguments, as in |
| 2403 |
``w.attributes('-alpha', 0.5)``, is deprecated; use keyword arguments |
| 2404 |
instead. |
| 2405 |
|
| 2406 |
|
| 2407 |
.. method:: wm_client(name=None) |
| 2408 |
:no-typesetting: |
| 2409 |
|
| 2410 |
.. method:: client(name=None) |
| 2411 |
|
| 2412 |
Store *name*, which should be the name of the host on which the |
| 2413 |
application is running, in the window's ``WM_CLIENT_MACHINE`` property |
| 2414 |
for use by the window or session manager. |
| 2415 |
An empty string deletes the property. |
| 2416 |
With no argument, return the last name set, or an empty string. |
| 2417 |
:meth:`wm_client` is an alias of :meth:`!client`. |
| 2418 |
|
| 2419 |
.. method:: wm_colormapwindows(*wlist) |
| 2420 |
:no-typesetting: |
| 2421 |
|
| 2422 |
.. method:: colormapwindows(*wlist) |
| 2423 |
|
| 2424 |
Manipulate the ``WM_COLORMAP_WINDOWS`` property, which tells the window |
| 2425 |
manager about windows that have private colormaps. |
| 2426 |
If *wlist* is given, overwrite the property with those windows (their |
| 2427 |
order is a priority order for installing colormaps). |
| 2428 |
With no arguments, return the list of windows currently named in the |
| 2429 |
property. |
| 2430 |
:meth:`wm_colormapwindows` is an alias of :meth:`!colormapwindows`. |
| 2431 |
|
| 2432 |
.. method:: wm_command(value=None) |
| 2433 |
:no-typesetting: |
| 2434 |
|
| 2435 |
.. method:: command(value=None) |
| 2436 |
|
| 2437 |
Store *value* in the window's ``WM_COMMAND`` property for use by the |
| 2438 |
window or session manager; it should be a list giving the words of the |
| 2439 |
command used to invoke the application. |
| 2440 |
An empty string deletes the property. |
| 2441 |
With no argument, return the last value set, or an empty string. |
| 2442 |
:meth:`wm_command` is an alias of :meth:`!command`. |
| 2443 |
|
| 2444 |
.. method:: wm_deiconify() |
| 2445 |
:no-typesetting: |
| 2446 |
|
| 2447 |
.. method:: deiconify() |
| 2448 |
|
| 2449 |
Display the window in normal (non-iconified) form by mapping it. |
| 2450 |
If the window has never been mapped, this ensures it appears de-iconified |
| 2451 |
when it is first mapped. |
| 2452 |
On Windows the window is also raised and given the focus. |
| 2453 |
:meth:`wm_deiconify` is an alias of :meth:`!deiconify`. |
| 2454 |
|
| 2455 |
.. method:: wm_focusmodel(model=None) |
| 2456 |
:no-typesetting: |
| 2457 |
|
| 2458 |
.. method:: focusmodel(model=None) |
| 2459 |
|
| 2460 |
Set or query the focus model for the window. |
| 2461 |
*model* is either ``'active'`` (the window claims the input focus for |
| 2462 |
itself or its descendants, even when the focus is in another application) |
| 2463 |
or ``'passive'`` (the window relies on the window manager to give it the |
| 2464 |
focus). |
| 2465 |
With no argument, return the current model. |
| 2466 |
The default is ``'passive'``, which is what the :meth:`!focus` command |
| 2467 |
assumes. |
| 2468 |
:meth:`wm_focusmodel` is an alias of :meth:`!focusmodel`. |
| 2469 |
|
| 2470 |
.. method:: wm_forget(window) |
| 2471 |
:no-typesetting: |
| 2472 |
|
| 2473 |
.. method:: forget(window) |
| 2474 |
|
| 2475 |
Unmap *window* from the screen so that it is no longer managed by the |
| 2476 |
window manager. |
| 2477 |
A :class:`Toplevel` is then treated like a :class:`Frame`, although its |
| 2478 |
``-menu`` configuration is remembered and the menu reappears if the |
| 2479 |
widget is managed again. |
| 2480 |
:meth:`wm_forget` is an alias of :meth:`!forget`. |
| 2481 |
|
| 2482 |
Not to be confused with :meth:`Pack.forget`. |
| 2483 |
|
| 2484 |
.. versionadded:: 3.3 |
| 2485 |
|
| 2486 |
.. method:: wm_frame() |
| 2487 |
:no-typesetting: |
| 2488 |
|
| 2489 |
.. method:: frame() |
| 2490 |
|
| 2491 |
Return the platform-specific window identifier for the outermost |
| 2492 |
decorative frame containing the window, if the window manager has |
| 2493 |
reparented it into such a frame; otherwise return the identifier of the |
| 2494 |
window itself. |
| 2495 |
:meth:`wm_frame` is an alias of :meth:`!frame`. |
| 2496 |
|
| 2497 |
.. method:: wm_geometry(newGeometry=None) |
| 2498 |
:no-typesetting: |
| 2499 |
|
| 2500 |
.. method:: geometry(newGeometry=None) |
| 2501 |
|
| 2502 |
Set or query the geometry of the window. |
| 2503 |
*newGeometry* has the form ``=widthxheight+x+y``, where any of ``=``, |
| 2504 |
``widthxheight`` and the ``+x+y`` position may be omitted. |
| 2505 |
*width* and *height* are in pixels (or grid units for a gridded window); |
| 2506 |
a position preceded by ``+`` is measured from the left or top edge of the |
| 2507 |
screen and one preceded by ``-`` from the right or bottom edge. |
| 2508 |
An offset can be negative, as in ``'200x100+-9+-8'``, when the window |
| 2509 |
edge is positioned beyond the corresponding screen edge. |
| 2510 |
An empty string cancels any user-specified geometry, letting the window |
| 2511 |
revert to its natural size. |
| 2512 |
With no argument, return the current geometry as a string of the form |
| 2513 |
``'200x200+10+10'``. |
| 2514 |
:meth:`wm_geometry` is an alias of :meth:`!geometry`. |
| 2515 |
|
| 2516 |
.. method:: wm_grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) |
| 2517 |
:no-typesetting: |
| 2518 |
|
| 2519 |
.. method:: grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None) |
| 2520 |
|
| 2521 |
Manage the window as a gridded window and define the relationship between |
| 2522 |
grid units and pixels. |
| 2523 |
*baseWidth* and *baseHeight* are the numbers of grid units for the |
| 2524 |
window's internally requested size, and *widthInc* and *heightInc* are |
| 2525 |
the pixel sizes of a horizontal and vertical grid unit. |
| 2526 |
Empty strings turn off gridded management. |
| 2527 |
With no arguments, return a tuple of the four current values, or ``None`` |
| 2528 |
if the window is not gridded. |
| 2529 |
:meth:`wm_grid` is an alias of :meth:`!grid`. |
| 2530 |
|
| 2531 |
Not to be confused with the grid geometry manager :meth:`Grid.grid`. |
| 2532 |
|
| 2533 |
.. method:: wm_group(pathName=None) |
| 2534 |
:no-typesetting: |
| 2535 |
|
| 2536 |
.. method:: group(pathName=None) |
| 2537 |
|
| 2538 |
Set or query the leader of a group of related windows. |
| 2539 |
*pathName* gives the path name of the group leader; the window manager |
| 2540 |
may, for example, unmap all windows in the group when the leader is |
| 2541 |
iconified. |
| 2542 |
An empty string removes the window from any group. |
| 2543 |
With no argument, return the path name of the current group leader, or an |
| 2544 |
empty string. |
| 2545 |
:meth:`wm_group` is an alias of :meth:`!group`. |
| 2546 |
|
| 2547 |
.. method:: wm_iconbitmap(bitmap=None, default=None) |
| 2548 |
:no-typesetting: |
| 2549 |
|
| 2550 |
.. method:: iconbitmap(bitmap=None, default=None) |
| 2551 |
|
| 2552 |
Set or query the bitmap used by the window manager for the window's icon. |
| 2553 |
*bitmap* names a bitmap in one of the standard forms accepted by Tk; an |
| 2554 |
empty string cancels the current icon bitmap. |
| 2555 |
With no argument, return the name of the current icon bitmap, or an empty |
| 2556 |
string. |
| 2557 |
On Windows the *default* argument names an icon (for example an ``.ico`` |
| 2558 |
file) applied to all top-level windows that have no icon of their own. |
| 2559 |
:meth:`wm_iconbitmap` is an alias of :meth:`!iconbitmap`. |
| 2560 |
|
| 2561 |
.. method:: wm_iconify() |
| 2562 |
:no-typesetting: |
| 2563 |
|
| 2564 |
.. method:: iconify() |
| 2565 |
|
| 2566 |
Iconify the window. |
| 2567 |
If the window has not yet been mapped for the first time, arrange for it |
| 2568 |
to appear in the iconified state when it is eventually mapped. |
| 2569 |
:meth:`wm_iconify` is an alias of :meth:`!iconify`. |
| 2570 |
|
| 2571 |
.. method:: wm_iconmask(bitmap=None) |
| 2572 |
:no-typesetting: |
| 2573 |
|
| 2574 |
.. method:: iconmask(bitmap=None) |
| 2575 |
|
| 2576 |
Set or query the bitmap used as a mask for the icon (see |
| 2577 |
:meth:`iconbitmap`). |
| 2578 |
Where the mask is zero no icon is displayed; where it is one, the |
| 2579 |
corresponding bits of the icon bitmap are shown. |
| 2580 |
An empty string cancels the current mask. |
| 2581 |
With no argument, return the name of the current icon mask, or an empty |
| 2582 |
string. |
| 2583 |
:meth:`wm_iconmask` is an alias of :meth:`!iconmask`. |
| 2584 |
|
| 2585 |
.. method:: wm_iconname(newName=None) |
| 2586 |
:no-typesetting: |
| 2587 |
|
| 2588 |
.. method:: iconname(newName=None) |
| 2589 |
|
| 2590 |
Set or query the name displayed by the window manager inside the window's |
| 2591 |
icon. |
| 2592 |
With no argument, return the current icon name, or an empty string if |
| 2593 |
none has been set (in which case the window manager normally displays the |
| 2594 |
window's title). |
| 2595 |
:meth:`wm_iconname` is an alias of :meth:`!iconname`. |
| 2596 |
|
| 2597 |
.. method:: wm_iconphoto(default=False, *images) |
| 2598 |
:no-typesetting: |
| 2599 |
|
| 2600 |
.. method:: iconphoto(default=False, *images) |
| 2601 |
|
| 2602 |
Set the titlebar icon for the window from one or more :class:`PhotoImage` |
| 2603 |
objects given in *images*. |
| 2604 |
Several images of different sizes (for example 16x16 and 32x32) may be |
| 2605 |
supplied so that the window manager can choose an appropriate one. |
| 2606 |
The image data is taken as a snapshot at the time of the call; later |
| 2607 |
changes to the images are not reflected. |
| 2608 |
If *default* is true, the icon is also applied to all top-level windows |
| 2609 |
created in the future. |
| 2610 |
On macOS only the first image is used. |
| 2611 |
:meth:`wm_iconphoto` is an alias of :meth:`!iconphoto`. |
| 2612 |
|
| 2613 |
.. versionadded:: 3.3 |
| 2614 |
|
| 2615 |
.. method:: wm_iconposition(x=None, y=None) |
| 2616 |
:no-typesetting: |
| 2617 |
|
| 2618 |
.. method:: iconposition(x=None, y=None) |
| 2619 |
|
| 2620 |
Set or query a hint to the window manager about where the window's icon |
| 2621 |
should be positioned. |
| 2622 |
Empty strings cancel an existing hint. |
| 2623 |
With no arguments, return a tuple of the two current values, or ``None`` |
| 2624 |
if no hint is in effect. |
| 2625 |
:meth:`wm_iconposition` is an alias of :meth:`!iconposition`. |
| 2626 |
|
| 2627 |
.. method:: wm_iconwindow(pathName=None) |
| 2628 |
:no-typesetting: |
| 2629 |
|
| 2630 |
.. method:: iconwindow(pathName=None) |
| 2631 |
|
| 2632 |
Set or query the window used as the icon for the window. |
| 2633 |
When the window is iconified, *pathName* is mapped to serve as its icon |
| 2634 |
and unmapped again when it is de-iconified. |
| 2635 |
An empty string cancels the association. |
| 2636 |
With no argument, return the path name of the current icon window, or an |
| 2637 |
empty string. |
| 2638 |
Not all window managers support icon windows, and the concept is |
| 2639 |
meaningless on non-X11 platforms. |
| 2640 |
:meth:`wm_iconwindow` is an alias of :meth:`!iconwindow`. |
| 2641 |
|
| 2642 |
.. method:: wm_manage(widget) |
| 2643 |
:no-typesetting: |
| 2644 |
|
| 2645 |
.. method:: manage(widget) |
| 2646 |
|
| 2647 |
Make *widget* a stand-alone top-level window, decorated by the window |
| 2648 |
manager with a title bar and so on. |
| 2649 |
Only :class:`Frame`, :class:`LabelFrame` and :class:`Toplevel` widgets |
| 2650 |
may be used (the :mod:`tkinter.ttk` versions are **not** accepted); |
| 2651 |
passing any other widget type raises an error. |
| 2652 |
:meth:`wm_manage` is an alias of :meth:`!manage`. |
| 2653 |
|
| 2654 |
.. versionadded:: 3.3 |
| 2655 |
|
| 2656 |
.. method:: wm_maxsize(width=None, height=None) |
| 2657 |
:no-typesetting: |
| 2658 |
|
| 2659 |
.. method:: maxsize(width=None, height=None) |
| 2660 |
|
| 2661 |
Set or query the maximum permissible dimensions of the window, in pixels |
| 2662 |
(or grid units for a gridded window). |
| 2663 |
The window manager restricts the window to be no larger than *width* and |
| 2664 |
*height*. |
| 2665 |
With no arguments, return a tuple of the current maximum width and |
| 2666 |
height. |
| 2667 |
The maximum size defaults to the size of the screen. |
| 2668 |
:meth:`wm_maxsize` is an alias of :meth:`!maxsize`. |
| 2669 |
|
| 2670 |
.. method:: wm_minsize(width=None, height=None) |
| 2671 |
:no-typesetting: |
| 2672 |
|
| 2673 |
.. method:: minsize(width=None, height=None) |
| 2674 |
|
| 2675 |
Set or query the minimum permissible dimensions of the window, in pixels |
| 2676 |
(or grid units for a gridded window). |
| 2677 |
The window manager restricts the window to be no smaller than *width* and |
| 2678 |
*height*. |
| 2679 |
With no arguments, return a tuple of the current minimum width and |
| 2680 |
height. |
| 2681 |
The minimum size defaults to one pixel in each dimension. |
| 2682 |
:meth:`wm_minsize` is an alias of :meth:`!minsize`. |
| 2683 |
|
| 2684 |
.. method:: wm_overrideredirect(boolean=None) |
| 2685 |
:no-typesetting: |
| 2686 |
|
| 2687 |
.. method:: overrideredirect(boolean=None) |
| 2688 |
|
| 2689 |
Set or query the override-redirect flag for the window. |
| 2690 |
When this flag is set, the window is ignored by the window manager: it is |
| 2691 |
not reparented into a decorative frame and the user cannot manipulate it |
| 2692 |
through the usual window manager controls. |
| 2693 |
With no argument, return a boolean indicating whether the flag is set, |
| 2694 |
or ``None`` if it has not been set. |
| 2695 |
The flag is reliably honored only when the window is first mapped or |
| 2696 |
remapped from the withdrawn state. |
| 2697 |
:meth:`wm_overrideredirect` is an alias of :meth:`!overrideredirect`. |
| 2698 |
|
| 2699 |
.. method:: wm_positionfrom(who=None) |
| 2700 |
:no-typesetting: |
| 2701 |
|
| 2702 |
.. method:: positionfrom(who=None) |
| 2703 |
|
| 2704 |
Set or query the source of the window's current position. |
| 2705 |
*who* is either ``'program'`` or ``'user'`` and indicates whether the |
| 2706 |
position was requested by the program or by the user; an empty string |
| 2707 |
cancels the current source. |
| 2708 |
With no argument, return the current source, or an empty string if none |
| 2709 |
has been set. |
| 2710 |
Tk automatically sets the source to ``'user'`` when :meth:`geometry` is |
| 2711 |
called, unless it has been set explicitly to ``'program'``. |
| 2712 |
:meth:`wm_positionfrom` is an alias of :meth:`!positionfrom`. |
| 2713 |
|
| 2714 |
.. method:: wm_protocol(name=None, func=None) |
| 2715 |
:no-typesetting: |
| 2716 |
|
| 2717 |
.. method:: protocol(name=None, func=None) |
| 2718 |
|
| 2719 |
Register *func* as the handler for the window manager protocol *name*, an |
| 2720 |
atom such as ``'WM_DELETE_WINDOW'``, ``'WM_SAVE_YOURSELF'`` or |
| 2721 |
``'WM_TAKE_FOCUS'``; *func* is then called whenever the window manager |
| 2722 |
sends a message of that protocol. |
| 2723 |
Tk installs a default ``WM_DELETE_WINDOW`` handler that destroys the |
| 2724 |
window, which this method can replace. |
| 2725 |
If *func* is an empty string, the handler is removed. |
| 2726 |
With only *name*, return the name of its registered handler command, or |
| 2727 |
an empty string if none is set (the default ``WM_DELETE_WINDOW`` handler |
| 2728 |
is not reported); with no arguments, return a tuple of the protocols that |
| 2729 |
currently have handlers. |
| 2730 |
:meth:`wm_protocol` is an alias of :meth:`!protocol`. |
| 2731 |
|
| 2732 |
.. method:: wm_resizable(width=None, height=None) |
| 2733 |
:no-typesetting: |
| 2734 |
|
| 2735 |
.. method:: resizable(width=None, height=None) |
| 2736 |
|
| 2737 |
Control whether the user may interactively resize the window. |
| 2738 |
*width* and *height* are boolean values that determine whether the |
| 2739 |
window's width and height may be changed. |
| 2740 |
With no arguments, return a tuple of two ``0``/``1`` values indicating |
| 2741 |
whether each dimension is currently resizable. |
| 2742 |
By default a window is resizable in both dimensions. |
| 2743 |
:meth:`wm_resizable` is an alias of :meth:`!resizable`. |
| 2744 |
|
| 2745 |
.. method:: wm_sizefrom(who=None) |
| 2746 |
:no-typesetting: |
| 2747 |
|
| 2748 |
.. method:: sizefrom(who=None) |
| 2749 |
|
| 2750 |
Set or query the source of the window's current size. |
| 2751 |
*who* is either ``'program'`` or ``'user'`` and indicates whether the |
| 2752 |
size was requested by the program or by the user; an empty string cancels |
| 2753 |
the current source. |
| 2754 |
With no argument, return the current source, or an empty string if none |
| 2755 |
has been set. |
| 2756 |
:meth:`wm_sizefrom` is an alias of :meth:`!sizefrom`. |
| 2757 |
|
| 2758 |
.. method:: wm_state(newstate=None) |
| 2759 |
:no-typesetting: |
| 2760 |
|
| 2761 |
.. method:: state(newstate=None) |
| 2762 |
|
| 2763 |
Set or query the state of the window. |
| 2764 |
With no argument, return the current state: one of ``'normal'``, |
| 2765 |
``'iconic'``, ``'withdrawn'``, ``'icon'`` or, on Windows and macOS only, |
| 2766 |
``'zoomed'``. |
| 2767 |
``'iconic'`` refers to a window that has been iconified, while ``'icon'`` |
| 2768 |
refers to a window serving as the icon for another window (see |
| 2769 |
:meth:`iconwindow`); the ``'icon'`` state cannot be set. |
| 2770 |
:meth:`wm_state` is an alias of :meth:`!state`. |
| 2771 |
|
| 2772 |
Not to be confused with :meth:`ttk.Widget.state |
| 2773 |
<tkinter.ttk.Widget.state>`. |
| 2774 |
|
| 2775 |
.. method:: wm_title(string=None) |
| 2776 |
:no-typesetting: |
| 2777 |
|
| 2778 |
.. method:: title(string=None) |
| 2779 |
|
| 2780 |
Set or query the title for the window, which the window manager should |
| 2781 |
display in the window's title bar. |
| 2782 |
With no argument, return the current title. |
| 2783 |
The title defaults to the window's name. |
| 2784 |
:meth:`wm_title` is an alias of :meth:`!title`. |
| 2785 |
|
| 2786 |
.. method:: wm_transient(master=None) |
| 2787 |
:no-typesetting: |
| 2788 |
|
| 2789 |
.. method:: transient(master=None) |
| 2790 |
|
| 2791 |
Mark the window as a transient window (such as a pull-down menu or |
| 2792 |
dialog) working on behalf of *master*, the path name of another top-level |
| 2793 |
window. |
| 2794 |
An empty string clears the transient status. |
| 2795 |
With no argument, return the path name of the current master, or an empty |
| 2796 |
string. |
| 2797 |
A transient window mirrors state changes in its master and may be |
| 2798 |
decorated differently by the window manager; it is an error to make a |
| 2799 |
window a transient of itself. |
| 2800 |
:meth:`wm_transient` is an alias of :meth:`!transient`. |
| 2801 |
|
| 2802 |
.. method:: wm_withdraw() |
| 2803 |
:no-typesetting: |
| 2804 |
|
| 2805 |
.. method:: withdraw() |
| 2806 |
|
| 2807 |
Withdraw the window from the screen, unmapping it and causing the window |
| 2808 |
manager to forget about it. |
| 2809 |
If the window has never been mapped, it is instead mapped in the |
| 2810 |
withdrawn state. |
| 2811 |
It is sometimes necessary to withdraw a window and then re-map it (for |
| 2812 |
example with :meth:`deiconify`) to make some window managers notice |
| 2813 |
changes to window attributes. |
| 2814 |
:meth:`wm_withdraw` is an alias of :meth:`!withdraw`. |
| 2815 |
|
| 2816 |
|
| 2817 |
.. class:: Pack() |
| 2818 |
|
| 2819 |
Geometry manager that arranges widgets by packing them against the sides of |
| 2820 |
their container. |
| 2821 |
The :class:`!Pack` mix-in is inherited by all widgets (through |
| 2822 |
:class:`Widget`) and provides the methods for managing a widget with the |
| 2823 |
*pack* geometry manager. |
| 2824 |
See also :ref:`tkinter-geometry-management`. |
| 2825 |
|
| 2826 |
.. note:: |
| 2827 |
|
| 2828 |
:class:`Pack`, :class:`Place` and :class:`Grid` all define the short |
| 2829 |
method names :meth:`!forget`, :meth:`!info`, :meth:`!slaves`, |
| 2830 |
:meth:`!content` and :meth:`!propagate`. |
| 2831 |
On a widget the bare names resolve to the *pack* manager's versions, |
| 2832 |
since :class:`Pack` and :class:`Misc` precede :class:`Place` and |
| 2833 |
:class:`Grid` in the method resolution order, |
| 2834 |
whatever manager actually manages the widget; |
| 2835 |
and :meth:`!configure`/:meth:`!config` configure the widget's options, |
| 2836 |
not its geometry. |
| 2837 |
Use the explicit ``pack_*``, ``grid_*`` and ``place_*`` methods |
| 2838 |
(and ``pack``, ``grid``, ``place`` for geometry configuration) |
| 2839 |
to act on a specific geometry manager. |
| 2840 |
|
| 2841 |
.. method:: configure(cnf={}, **kw) |
| 2842 |
:no-typesetting: |
| 2843 |
|
| 2844 |
.. method:: config(cnf={}, **kw) |
| 2845 |
:no-typesetting: |
| 2846 |
|
| 2847 |
.. method:: pack_configure(cnf={}, **kw) |
| 2848 |
pack(cnf={}, **kw) |
| 2849 |
|
| 2850 |
Pack the widget inside its container, positioning it relative to the |
| 2851 |
siblings already packed there. |
| 2852 |
The supported options are: |
| 2853 |
|
| 2854 |
*side* |
| 2855 |
Which side of the container to pack the widget against: ``'top'`` (the |
| 2856 |
default), ``'bottom'``, ``'left'`` or ``'right'``. |
| 2857 |
|
| 2858 |
*fill* |
| 2859 |
Whether to stretch the widget to fill its parcel: ``'none'`` (the |
| 2860 |
default), ``'x'``, ``'y'`` or ``'both'``. |
| 2861 |
|
| 2862 |
*expand* |
| 2863 |
Whether the widget should expand to consume any extra space in its |
| 2864 |
container (a boolean, default false). |
| 2865 |
|
| 2866 |
*anchor* |
| 2867 |
Where to position the widget in its parcel when the parcel is larger |
| 2868 |
than the widget: an anchor such as ``'n'`` or ``'sw'`` (default |
| 2869 |
``'center'``). |
| 2870 |
|
| 2871 |
*ipadx*, *ipady* |
| 2872 |
Internal padding added on the left and right (*ipadx*) or top and |
| 2873 |
bottom (*ipady*) of the widget, as a screen distance (default ``0``). |
| 2874 |
|
| 2875 |
*padx*, *pady* |
| 2876 |
External padding left on the left and right (*padx*) or top and bottom |
| 2877 |
(*pady*) of the widget, as a screen distance or a pair of two |
| 2878 |
distances for the two sides (default ``0``). |
| 2879 |
|
| 2880 |
*after* |
| 2881 |
Pack the widget after the given widget in the packing order, using the |
| 2882 |
same container. |
| 2883 |
|
| 2884 |
*before* |
| 2885 |
Pack the widget before the given widget in the packing order, using |
| 2886 |
the same container. |
| 2887 |
|
| 2888 |
*in_* |
| 2889 |
The container in which to pack the widget; it defaults to the parent |
| 2890 |
widget. |
| 2891 |
|
| 2892 |
:meth:`pack`, :meth:`configure` and :meth:`config` are aliases of |
| 2893 |
:meth:`!pack_configure`. |
| 2894 |
|
| 2895 |
.. method:: forget() |
| 2896 |
:no-typesetting: |
| 2897 |
|
| 2898 |
.. method:: pack_forget() |
| 2899 |
|
| 2900 |
Unmap the widget and remove it from the packing order, forgetting its |
| 2901 |
packing options. |
| 2902 |
It can be packed again later with :meth:`pack_configure`. |
| 2903 |
:meth:`forget` is an alias of :meth:`!pack_forget`, |
| 2904 |
except on :class:`PanedWindow`, |
| 2905 |
:class:`ttk.Notebook <tkinter.ttk.Notebook>` and |
| 2906 |
:class:`ttk.PanedWindow <tkinter.ttk.PanedWindow>`, |
| 2907 |
which provide their own :meth:`!forget` method. |
| 2908 |
|
| 2909 |
Not to be confused with :meth:`Wm.forget`. |
| 2910 |
|
| 2911 |
.. method:: info() |
| 2912 |
:no-typesetting: |
| 2913 |
|
| 2914 |
.. method:: pack_info() |
| 2915 |
|
| 2916 |
Return a dictionary of the widget's current packing options. |
| 2917 |
:meth:`info` is an alias of :meth:`!pack_info`. |
| 2918 |
|
| 2919 |
.. method:: propagate() |
| 2920 |
propagate(flag) |
| 2921 |
:no-typesetting: |
| 2922 |
|
| 2923 |
.. method:: pack_propagate() |
| 2924 |
pack_propagate(flag) |
| 2925 |
|
| 2926 |
Same as :meth:`Misc.pack_propagate`, treating this widget as a container: |
| 2927 |
enable or disable geometry propagation. |
| 2928 |
:meth:`propagate` is an alias of :meth:`!pack_propagate`. |
| 2929 |
|
| 2930 |
.. method:: slaves() |
| 2931 |
:no-typesetting: |
| 2932 |
|
| 2933 |
.. method:: pack_slaves() |
| 2934 |
|
| 2935 |
Same as :meth:`Misc.pack_slaves`: return the list of widgets packed in |
| 2936 |
this widget. |
| 2937 |
:meth:`slaves` is an alias of :meth:`!pack_slaves`. |
| 2938 |
|
| 2939 |
|
| 2940 |
.. class:: Place() |
| 2941 |
|
| 2942 |
Geometry manager that places widgets at explicit positions and sizes within |
| 2943 |
their container. |
| 2944 |
The :class:`!Place` mix-in is inherited by all widgets (through |
| 2945 |
:class:`Widget`). |
| 2946 |
See also :ref:`tkinter-geometry-management`. |
| 2947 |
|
| 2948 |
.. method:: configure(cnf={}, **kw) |
| 2949 |
:no-typesetting: |
| 2950 |
|
| 2951 |
.. method:: config(cnf={}, **kw) |
| 2952 |
:no-typesetting: |
| 2953 |
|
| 2954 |
.. method:: place_configure(cnf={}, **kw) |
| 2955 |
place(cnf={}, **kw) |
| 2956 |
|
| 2957 |
Place the widget inside its container at an absolute or relative |
| 2958 |
position. |
| 2959 |
The supported options are: |
| 2960 |
|
| 2961 |
*x*, *y* |
| 2962 |
The absolute horizontal and vertical position of the widget's anchor |
| 2963 |
point, as a screen distance (default ``0``). |
| 2964 |
|
| 2965 |
*relx*, *rely* |
| 2966 |
The horizontal and vertical position of the widget's anchor point as a |
| 2967 |
fraction of the container's width and height, where ``0.0`` is the |
| 2968 |
left or top edge and ``1.0`` is the right or bottom edge. |
| 2969 |
If both the absolute and the relative option are given, their values |
| 2970 |
are summed. |
| 2971 |
|
| 2972 |
*anchor* |
| 2973 |
Which point of the widget is placed at the given position: an anchor |
| 2974 |
such as ``'n'`` or ``'se'`` (default ``'nw'``). |
| 2975 |
|
| 2976 |
*width*, *height* |
| 2977 |
The absolute width and height of the widget, as a screen distance. |
| 2978 |
By default the widget's requested size is used. |
| 2979 |
|
| 2980 |
*relwidth*, *relheight* |
| 2981 |
The width and height of the widget as a fraction of the container's |
| 2982 |
width and height. |
| 2983 |
If both the absolute and the relative option are given, their values |
| 2984 |
are summed. |
| 2985 |
|
| 2986 |
*bordermode* |
| 2987 |
How the container's border affects placement: ``'inside'`` (the |
| 2988 |
default) measures the area inside the border, ``'outside'`` measures |
| 2989 |
the area including the border, and ``'ignore'`` uses the official X |
| 2990 |
area. |
| 2991 |
|
| 2992 |
*in_* |
| 2993 |
The container relative to which the widget is placed; it must be the |
| 2994 |
widget's parent or a descendant of the parent, and defaults to the |
| 2995 |
parent. |
| 2996 |
|
| 2997 |
:meth:`place`, :meth:`configure` and :meth:`config` are aliases of |
| 2998 |
:meth:`!place_configure`. |
| 2999 |
|
| 3000 |
.. method:: forget() |
| 3001 |
:no-typesetting: |
| 3002 |
|
| 3003 |
.. method:: place_forget() |
| 3004 |
|
| 3005 |
Unmap the widget and remove it from the placement, forgetting its place |
| 3006 |
options. |
| 3007 |
|
| 3008 |
.. method:: info() |
| 3009 |
:no-typesetting: |
| 3010 |
|
| 3011 |
.. method:: place_info() |
| 3012 |
|
| 3013 |
Return a dictionary of the widget's current place options. |
| 3014 |
|
| 3015 |
.. method:: slaves() |
| 3016 |
:no-typesetting: |
| 3017 |
|
| 3018 |
.. method:: place_slaves() |
| 3019 |
|
| 3020 |
Same as :meth:`Misc.place_slaves`: return the list of widgets placed in |
| 3021 |
this widget. |
| 3022 |
|
| 3023 |
|
| 3024 |
.. class:: Grid() |
| 3025 |
|
| 3026 |
Geometry manager that arranges widgets in a two-dimensional grid of rows and |
| 3027 |
columns within their container. |
| 3028 |
The :class:`!Grid` mix-in is inherited by all widgets (through |
| 3029 |
:class:`Widget`). |
| 3030 |
See also :ref:`tkinter-geometry-management`. |
| 3031 |
|
| 3032 |
.. method:: configure(cnf={}, **kw) |
| 3033 |
:no-typesetting: |
| 3034 |
|
| 3035 |
.. method:: config(cnf={}, **kw) |
| 3036 |
:no-typesetting: |
| 3037 |
|
| 3038 |
.. method:: grid_configure(cnf={}, **kw) |
| 3039 |
grid(cnf={}, **kw) |
| 3040 |
|
| 3041 |
Position the widget in a cell of its container's grid. |
| 3042 |
|
| 3043 |
Not to be confused with :meth:`Wm.grid`. |
| 3044 |
|
| 3045 |
The supported options are: |
| 3046 |
|
| 3047 |
*row*, *column* |
| 3048 |
The row and column of the cell to place the widget in, counting from |
| 3049 |
``0``. |
| 3050 |
*column* defaults to the column after the previous widget placed in |
| 3051 |
the same :meth:`!grid_configure` call (or ``0``), and *row* defaults |
| 3052 |
to the next empty row. |
| 3053 |
|
| 3054 |
*rowspan*, *columnspan* |
| 3055 |
The number of rows and columns the widget should span (default ``1``). |
| 3056 |
|
| 3057 |
*sticky* |
| 3058 |
How to position or stretch the widget when its cell is larger than the |
| 3059 |
widget: a string containing zero or more of the characters ``'n'``, |
| 3060 |
``'s'``, ``'e'`` and ``'w'``, naming the cell sides the widget sticks |
| 3061 |
to. |
| 3062 |
Specifying both ``'n'`` and ``'s'`` (or ``'e'`` and ``'w'``) stretches |
| 3063 |
the widget to fill the height (or width) of the cell. |
| 3064 |
The default is ``''``, which centers the widget at its requested size. |
| 3065 |
|
| 3066 |
*ipadx*, *ipady* |
| 3067 |
Internal padding added on the left and right (*ipadx*) or top and |
| 3068 |
bottom (*ipady*) of the widget, as a screen distance (default ``0``). |
| 3069 |
|
| 3070 |
*padx*, *pady* |
| 3071 |
External padding left on the left and right (*padx*) or top and bottom |
| 3072 |
(*pady*) of the widget, as a screen distance or a pair of two |
| 3073 |
distances for the two sides (default ``0``). |
| 3074 |
|
| 3075 |
*in_* |
| 3076 |
The container in whose grid to place the widget; it defaults to the |
| 3077 |
parent widget. |
| 3078 |
|
| 3079 |
:meth:`grid`, :meth:`configure` and :meth:`config` are aliases of |
| 3080 |
:meth:`!grid_configure`. |
| 3081 |
|
| 3082 |
.. method:: forget() |
| 3083 |
:no-typesetting: |
| 3084 |
|
| 3085 |
.. method:: grid_forget() |
| 3086 |
|
| 3087 |
Unmap the widget and remove it from the grid, forgetting its grid |
| 3088 |
options. |
| 3089 |
|
| 3090 |
.. method:: grid_remove() |
| 3091 |
|
| 3092 |
Unmap the widget and remove it from the grid, but remember its grid |
| 3093 |
options so that it is restored to the same cell if it is gridded again. |
| 3094 |
|
| 3095 |
.. method:: info() |
| 3096 |
:no-typesetting: |
| 3097 |
|
| 3098 |
.. method:: grid_info() |
| 3099 |
|
| 3100 |
Return a dictionary of the widget's current grid options. |
| 3101 |
|
| 3102 |
.. method:: bbox(column=None, row=None, col2=None, row2=None) |
| 3103 |
:no-typesetting: |
| 3104 |
|
| 3105 |
.. method:: grid_bbox(column=None, row=None, col2=None, row2=None) |
| 3106 |
|
| 3107 |
Same as :meth:`Misc.grid_bbox`. |
| 3108 |
:meth:`bbox` is an alias of :meth:`!grid_bbox`, |
| 3109 |
except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`, |
| 3110 |
:class:`Text`, :class:`ttk.Entry <tkinter.ttk.Entry>` and |
| 3111 |
:class:`ttk.Treeview <tkinter.ttk.Treeview>`, |
| 3112 |
which provide their own :meth:`!bbox` method. |
| 3113 |
|
| 3114 |
.. method:: columnconfigure(index, cnf={}, **kw) |
| 3115 |
:no-typesetting: |
| 3116 |
|
| 3117 |
.. method:: grid_columnconfigure(index, cnf={}, **kw) |
| 3118 |
|
| 3119 |
Same as :meth:`Misc.grid_columnconfigure`: query or set the options (such |
| 3120 |
as *weight*, *minsize*, *pad* and *uniform*) of a grid column. |
| 3121 |
:meth:`columnconfigure` is an alias of :meth:`!grid_columnconfigure`. |
| 3122 |
|
| 3123 |
.. method:: rowconfigure(index, cnf={}, **kw) |
| 3124 |
:no-typesetting: |
| 3125 |
|
| 3126 |
.. method:: grid_rowconfigure(index, cnf={}, **kw) |
| 3127 |
|
| 3128 |
Same as :meth:`Misc.grid_rowconfigure`: query or set the options of a |
| 3129 |
grid row. |
| 3130 |
:meth:`rowconfigure` is an alias of :meth:`!grid_rowconfigure`. |
| 3131 |
|
| 3132 |
.. method:: location(x, y) |
| 3133 |
:no-typesetting: |
| 3134 |
|
| 3135 |
.. method:: grid_location(x, y) |
| 3136 |
|
| 3137 |
Same as :meth:`Misc.grid_location`: return the ``(column, row)`` of the |
| 3138 |
cell that covers the pixel at *x*, *y*. |
| 3139 |
:meth:`location` is an alias of :meth:`!grid_location`. |
| 3140 |
|
| 3141 |
.. method:: size() |
| 3142 |
:no-typesetting: |
| 3143 |
|
| 3144 |
.. method:: grid_size() |
| 3145 |
|
| 3146 |
Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving |
| 3147 |
the size of the grid. |
| 3148 |
:meth:`size` is an alias of :meth:`!grid_size`, |
| 3149 |
except on the :class:`Listbox` widget, |
| 3150 |
which provides its own :meth:`!size` method. |
| 3151 |
|
| 3152 |
.. method:: propagate() |
| 3153 |
propagate(flag) |
| 3154 |
:no-typesetting: |
| 3155 |
|
| 3156 |
.. method:: grid_propagate() |
| 3157 |
grid_propagate(flag) |
| 3158 |
|
| 3159 |
Same as :meth:`Misc.grid_propagate`. |
| 3160 |
|
| 3161 |
.. method:: slaves(row=None, column=None) |
| 3162 |
:no-typesetting: |
| 3163 |
|
| 3164 |
.. method:: grid_slaves(row=None, column=None) |
| 3165 |
|
| 3166 |
Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid, |
| 3167 |
optionally restricted to a *row* and/or *column*. |
| 3168 |
|
| 3169 |
|
| 3170 |
.. class:: XView() |
| 3171 |
|
| 3172 |
Mix-in providing the horizontal-scrolling interface shared by widgets such |
| 3173 |
as :class:`Entry`, :class:`Canvas`, :class:`Listbox`, :class:`Text` and |
| 3174 |
:class:`Spinbox`. |
| 3175 |
A widget's :meth:`xview` method is registered as the *command* of a |
| 3176 |
horizontal :class:`Scrollbar`. |
| 3177 |
|
| 3178 |
.. method:: xview(*args) |
| 3179 |
|
| 3180 |
Query or change the horizontal position of the view. |
| 3181 |
With no arguments, return a tuple ``(first, last)`` of two fractions |
| 3182 |
between 0 and 1 giving the portion of the document that is currently |
| 3183 |
visible. |
| 3184 |
Otherwise the arguments are passed to the Tk ``xview`` widget command and |
| 3185 |
are usually generated by a scrollbar; :meth:`xview_moveto` and |
| 3186 |
:meth:`xview_scroll` provide a more convenient interface. |
| 3187 |
|
| 3188 |
.. method:: xview_moveto(fraction) |
| 3189 |
|
| 3190 |
Adjust the view so that *fraction* of the total width of the document is |
| 3191 |
off-screen to the left. |
| 3192 |
*fraction* is a number between 0 and 1. |
| 3193 |
|
| 3194 |
.. method:: xview_scroll(number, what) |
| 3195 |
|
| 3196 |
Shift the view left or right by *number* units. |
| 3197 |
*what* is either ``'units'`` or ``'pages'``; a negative *number* scrolls |
| 3198 |
left and a positive one scrolls right. |
| 3199 |
|
| 3200 |
|
| 3201 |
.. class:: YView() |
| 3202 |
|
| 3203 |
Mix-in providing the vertical-scrolling interface shared by widgets such as |
| 3204 |
:class:`Canvas`, :class:`Listbox` and :class:`Text`. |
| 3205 |
A widget's :meth:`yview` method is registered as the *command* of a vertical |
| 3206 |
:class:`Scrollbar`. |
| 3207 |
|
| 3208 |
.. method:: yview(*args) |
| 3209 |
|
| 3210 |
Query or change the vertical position of the view. |
| 3211 |
With no arguments, return a tuple ``(first, last)`` of two fractions |
| 3212 |
between 0 and 1 giving the portion of the document that is currently |
| 3213 |
visible. |
| 3214 |
Otherwise the arguments are passed to the Tk ``yview`` widget command, |
| 3215 |
usually generated by a scrollbar; :meth:`yview_moveto` and |
| 3216 |
:meth:`yview_scroll` provide a more convenient interface. |
| 3217 |
|
| 3218 |
.. method:: yview_moveto(fraction) |
| 3219 |
|
| 3220 |
Adjust the view so that *fraction* of the total height of the document is |
| 3221 |
off-screen above the top. |
| 3222 |
*fraction* is a number between 0 and 1. |
| 3223 |
|
| 3224 |
.. method:: yview_scroll(number, what) |
| 3225 |
|
| 3226 |
Shift the view up or down by *number* units. |
| 3227 |
*what* is either ``'units'`` or ``'pages'``; a negative *number* scrolls |
| 3228 |
up and a positive one scrolls down. |
| 3229 |
|
| 3230 |
|
| 3231 |
.. class:: BaseWidget(master, widgetName, cnf={}, kw={}, extra=()) |
| 3232 |
|
| 3233 |
Internal base class for all widgets. |
| 3234 |
It inherits from :class:`Misc` and adds the machinery that creates the |
| 3235 |
underlying Tk widget; application code normally uses :class:`Widget` or a |
| 3236 |
concrete widget class rather than instantiating :class:`!BaseWidget` |
| 3237 |
directly. |
| 3238 |
|
| 3239 |
.. method:: destroy() |
| 3240 |
|
| 3241 |
Destroy this widget and all of its children, removing the corresponding |
| 3242 |
Tk widgets and deleting the associated Tcl commands. |
| 3243 |
|
| 3244 |
|
| 3245 |
.. class:: Widget(master, widgetName, cnf={}, kw={}, extra=()) |
| 3246 |
|
| 3247 |
Internal base class for the standard widgets. |
| 3248 |
It combines :class:`BaseWidget` with the geometry-manager mix-ins |
| 3249 |
:class:`Pack`, :class:`Place` and :class:`Grid`, so that every widget can be |
| 3250 |
managed by any of the three geometry managers. |
| 3251 |
The concrete widget classes (:class:`Button`, :class:`Label`, and so on) |
| 3252 |
derive from :class:`!Widget`. |
| 3253 |
|
| 3254 |
|
| 3255 |
Toplevel widgets |
| 3256 |
^^^^^^^^^^^^^^^^ |
| 3257 |
|
| 3258 |
.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None) |
| 3259 |
|
| 3260 |
Construct a toplevel Tk widget, which is usually the main window of an |
| 3261 |
application, and initialize a Tcl interpreter for this widget. Each |
| 3262 |
instance has its own associated Tcl interpreter. |
| 3263 |
Inherits from :class:`Misc` and :class:`Wm`. |
| 3264 |
|
| 3265 |
To create a Tcl interpreter without initializing the Tk subsystem, use the |
| 3266 |
:func:`Tcl` factory function instead. |
| 3267 |
|
| 3268 |
The :class:`Tk` class is typically instantiated using all default values. |
| 3269 |
However, the following keyword arguments are currently recognized: |
| 3270 |
|
| 3271 |
*screenName* |
| 3272 |
When given (as a string), sets the :envvar:`DISPLAY` environment |
| 3273 |
variable. (X11 only) |
| 3274 |
*baseName* |
| 3275 |
Name of the profile file. By default, *baseName* is derived from the |
| 3276 |
program name (``sys.argv[0]``). |
| 3277 |
*className* |
| 3278 |
Name of the widget class. Used as a profile file and also as the name |
| 3279 |
with which Tcl is invoked (*argv0* in *interp*). |
| 3280 |
*useTk* |
| 3281 |
If ``True``, initialize the Tk subsystem. The :func:`tkinter.Tcl() <Tcl>` |
| 3282 |
function sets this to ``False``. |
| 3283 |
*sync* |
| 3284 |
If ``True``, execute all X server commands synchronously, so that errors |
| 3285 |
are reported immediately. Can be used for debugging. (X11 only) |
| 3286 |
*use* |
| 3287 |
Specifies the *id* of the window in which to embed the application, |
| 3288 |
instead of it being created as an independent toplevel window. *id* must |
| 3289 |
be specified in the same way as the value for the -use option for |
| 3290 |
toplevel widgets (that is, it has a form like that returned by |
| 3291 |
:meth:`~Misc.winfo_id`). |
| 3292 |
|
| 3293 |
Note that on some platforms this will only work correctly if *id* refers |
| 3294 |
to a Tk frame or toplevel that has its -container option enabled. |
| 3295 |
|
| 3296 |
:class:`Tk` reads and interprets profile files, named |
| 3297 |
:file:`.{className}.tcl` and :file:`.{baseName}.tcl`, into the Tcl |
| 3298 |
interpreter and calls :func:`exec` on the contents of |
| 3299 |
:file:`.{className}.py` and :file:`.{baseName}.py`. The path for the |
| 3300 |
profile files is the :envvar:`HOME` environment variable or, if that |
| 3301 |
isn't defined, then :data:`os.curdir`. |
| 3302 |
|
| 3303 |
.. note:: |
| 3304 |
|
| 3305 |
On Windows, creating a Tcl interpreter (by instantiating :class:`Tk` or |
| 3306 |
calling :func:`Tcl`) sets the :envvar:`HOME` environment variable for |
| 3307 |
the process, if it is not already set, to ``%HOMEDRIVE%%HOMEPATH%`` (or |
| 3308 |
:envvar:`USERPROFILE`, or ``c:\``). This is done by Tcl and can affect |
| 3309 |
other code that reads :envvar:`HOME`. |
| 3310 |
|
| 3311 |
.. attribute:: tk |
| 3312 |
|
| 3313 |
The Tk application object created by instantiating :class:`Tk`. This |
| 3314 |
provides access to the Tcl interpreter. Each widget that is attached |
| 3315 |
the same instance of :class:`Tk` has the same value for its :attr:`tk` |
| 3316 |
attribute. |
| 3317 |
|
| 3318 |
.. attribute:: master |
| 3319 |
|
| 3320 |
The widget object that contains this widget. |
| 3321 |
For :class:`Tk`, the :attr:`!master` is :const:`None` because it is the |
| 3322 |
main window. |
| 3323 |
The terms *master* and *parent* are similar and sometimes used |
| 3324 |
interchangeably as argument names; however, calling |
| 3325 |
:meth:`~Misc.winfo_parent` returns a string of the widget name whereas |
| 3326 |
:attr:`!master` returns the object. |
| 3327 |
*parent*/*child* reflects the tree-like relationship while *master* (or |
| 3328 |
*container*)/*content* reflects the container structure. |
| 3329 |
|
| 3330 |
.. attribute:: children |
| 3331 |
|
| 3332 |
The immediate descendants of this widget as a :class:`dict` with the |
| 3333 |
child widget names as the keys and the child instance objects as the |
| 3334 |
values. |
| 3335 |
|
| 3336 |
.. method:: destroy() |
| 3337 |
|
| 3338 |
Destroy this and all descendant widgets and, for the main window, end the |
| 3339 |
connection to the underlying Tcl interpreter. |
| 3340 |
|
| 3341 |
.. method:: loadtk() |
| 3342 |
|
| 3343 |
Finish loading and initializing the Tk subsystem. |
| 3344 |
This is needed only when the interpreter was created without Tk (for |
| 3345 |
example through :func:`Tcl`); it is called automatically when *useTk* is |
| 3346 |
true. |
| 3347 |
|
| 3348 |
.. method:: readprofile(baseName, className) |
| 3349 |
|
| 3350 |
Read and source the user's profile files :file:`.{className}.tcl` and |
| 3351 |
:file:`.{baseName}.tcl` into the Tcl interpreter, and execute the |
| 3352 |
corresponding :file:`.{className}.py` and :file:`.{baseName}.py` files. |
| 3353 |
This is called during initialization; see the description of the |
| 3354 |
constructor above. |
| 3355 |
|
| 3356 |
.. method:: report_callback_exception(exc, val, tb) |
| 3357 |
|
| 3358 |
Report a callback exception. |
| 3359 |
This is called when an exception propagates out of a Tkinter callback; |
| 3360 |
*exc*, *val* and *tb* are the exception type, value and traceback as |
| 3361 |
returned by :func:`sys.exc_info`. |
| 3362 |
The default implementation prints a traceback to :data:`sys.stderr`. |
| 3363 |
It can be overridden to customize error handling, for example to display |
| 3364 |
the traceback in a dialog. |
| 3365 |
|
| 3366 |
|
| 3367 |
.. class:: Toplevel(master=None, cnf={}, **kw) |
| 3368 |
|
| 3369 |
A :class:`!Toplevel` widget is a top-level window, similar to a |
| 3370 |
:class:`Frame` except that its X parent is the root window of a screen |
| 3371 |
rather than its logical parent. |
| 3372 |
Its primary purpose is to serve as a container for dialog boxes and other |
| 3373 |
collections of widgets; its only visible features are its background and an |
| 3374 |
optional 3-D border. |
| 3375 |
Notable options include *menu*, which installs a :class:`Menu` as the |
| 3376 |
window's menubar. |
| 3377 |
Inherits from :class:`BaseWidget` and :class:`Wm`, so a toplevel is managed |
| 3378 |
by the window manager. |
| 3379 |
Refer to the Tk ``toplevel`` manual page for the full list of options. |
| 3380 |
|
| 3381 |
|
| 3382 |
Widget classes |
| 3383 |
^^^^^^^^^^^^^^ |
| 3384 |
|
| 3385 |
.. class:: Button(master=None, cnf={}, **kw) |
| 3386 |
|
| 3387 |
A :class:`!Button` widget displays a textual string, bitmap or image and |
| 3388 |
invokes a command when the user presses it (by clicking mouse button 1 over |
| 3389 |
the button or, when the button has focus, by pressing the space key). |
| 3390 |
Inherits from :class:`Widget`. |
| 3391 |
In addition to the standard widget options, a button accepts the options |
| 3392 |
documented in the Tk ``button`` manual page, such as *command* (the callback |
| 3393 |
invoked when the button is pressed), *textvariable*, *state* and *default*. |
| 3394 |
|
| 3395 |
.. method:: invoke() |
| 3396 |
|
| 3397 |
Invoke the command associated with the button, if there is one, and |
| 3398 |
return its result, or an empty string if no command is associated with |
| 3399 |
the button. |
| 3400 |
This is ignored if the button's state is ``disabled``. |
| 3401 |
|
| 3402 |
.. method:: flash() |
| 3403 |
|
| 3404 |
Flash the button by redisplaying it several times, alternating between |
| 3405 |
the active and normal colors. |
| 3406 |
At the end of the flash the button is left in the same normal or active |
| 3407 |
state as when the method was called. |
| 3408 |
This is ignored if the button's state is ``disabled``. |
| 3409 |
|
| 3410 |
|
| 3411 |
.. class:: Canvas(master=None, cnf={}, **kw) |
| 3412 |
|
| 3413 |
A :class:`!Canvas` widget implements structured graphics. |
| 3414 |
It displays any number of *items*, such as arcs, lines, ovals, polygons, |
| 3415 |
rectangles, text, bitmaps, images and embedded windows, which may be drawn, |
| 3416 |
moved, re-colored and bound to events. |
| 3417 |
Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the |
| 3418 |
view can be scrolled horizontally and vertically with :meth:`~XView.xview` |
| 3419 |
and :meth:`~YView.yview`. |
| 3420 |
Refer to the Tk ``canvas`` manual page for the full list of widget and item |
| 3421 |
options. |
| 3422 |
|
| 3423 |
Each item has a unique integer *id*, assigned when it is created, and zero |
| 3424 |
or more string *tags*. |
| 3425 |
A tag is an arbitrary string that does not have the form of an integer; the |
| 3426 |
same tag may be shared by many items, which makes tags convenient for |
| 3427 |
grouping items. |
| 3428 |
The special tag ``'all'`` matches every item in the canvas, and |
| 3429 |
``'current'`` matches the topmost item under the mouse pointer. |
| 3430 |
Most methods take a *tagOrId* argument that may be an integer id naming a |
| 3431 |
single item, or a tag naming zero or more items; as described in the Tk |
| 3432 |
``canvas`` manual page, a tag may also be a logical expression of tags |
| 3433 |
combined with the operators ``&&``, ``||``, ``^``, ``!`` and parentheses. |
| 3434 |
When a method that operates on a single item is given a *tagOrId* matching |
| 3435 |
several items, it normally uses the lowest matching item in the display |
| 3436 |
list. |
| 3437 |
|
| 3438 |
The items are kept in a *display list* that determines drawing order: items |
| 3439 |
later in the list are drawn on top of earlier ones. |
| 3440 |
A newly created item is placed at the top of the list; the order can be |
| 3441 |
changed with :meth:`tag_raise` and :meth:`tag_lower`. |
| 3442 |
|
| 3443 |
.. method:: create_arc(*args, **kw) |
| 3444 |
create_bitmap(*args, **kw) |
| 3445 |
create_image(*args, **kw) |
| 3446 |
create_line(*args, **kw) |
| 3447 |
create_oval(*args, **kw) |
| 3448 |
create_polygon(*args, **kw) |
| 3449 |
create_rectangle(*args, **kw) |
| 3450 |
create_text(*args, **kw) |
| 3451 |
create_window(*args, **kw) |
| 3452 |
|
| 3453 |
Create a new item of the corresponding type and return its integer id. |
| 3454 |
Each method is called as ``create_TYPE(coord..., **options)``: the |
| 3455 |
leading positional arguments give the coordinates that define the item |
| 3456 |
(as separate numbers, as a single sequence of numbers, or as coordinate |
| 3457 |
pairs), and the keyword arguments set item-specific options. |
| 3458 |
Coordinates and screen distances may be given as numbers (interpreted as |
| 3459 |
pixels) or as strings with a unit suffix (``'m'``, ``'c'``, ``'i'`` or |
| 3460 |
``'p'`` for millimetres, centimetres, inches or printer's points), but |
| 3461 |
are always stored and returned in pixels. |
| 3462 |
|
| 3463 |
The item types are: ``arc`` (an arc-shaped region that is a section of an |
| 3464 |
oval, defined by two diagonally opposite corners ``x1, y1, x2, y2`` of |
| 3465 |
the enclosing rectangle); ``bitmap`` (a two-color bitmap positioned at a |
| 3466 |
point ``x, y``); ``image`` (a Tk image positioned at a point ``x, y``); |
| 3467 |
``line`` (a line or curve through the points ``x1, y1, ..., xn, yn``); |
| 3468 |
``oval`` (a circle or ellipse inscribed in the rectangle |
| 3469 |
``x1, y1, x2, y2``); ``polygon`` (a closed polygon through the points |
| 3470 |
``x1, y1, ..., xn, yn``); ``rectangle`` (a rectangle with corners |
| 3471 |
``x1, y1, x2, y2``); ``text`` (a string of text positioned at a point |
| 3472 |
``x, y``); and ``window`` (a child widget embedded in the canvas at a |
| 3473 |
point ``x, y``, specified with the *window* option). |
| 3474 |
|
| 3475 |
Most item types accept a common set of *standard item options*, plus a |
| 3476 |
few options specific to each type. |
| 3477 |
Option names are passed as keyword arguments, without the leading |
| 3478 |
hyphen. |
| 3479 |
|
| 3480 |
The standard item options are: |
| 3481 |
|
| 3482 |
*fill* |
| 3483 |
The color used to fill the item's interior, or to draw a *line* |
| 3484 |
item or the characters of a *text* item. |
| 3485 |
An empty string (the default for all types except *line* and *text*) |
| 3486 |
leaves the item unfilled. |
| 3487 |
|
| 3488 |
*outline* |
| 3489 |
The color used to draw the item's outline. |
| 3490 |
An empty string draws no outline. |
| 3491 |
|
| 3492 |
*width* |
| 3493 |
The width of the outline, defaulting to ``1.0``. |
| 3494 |
Has no effect if *outline* is empty. |
| 3495 |
|
| 3496 |
*dash* |
| 3497 |
A dash pattern for the outline, given either as a sequence of |
| 3498 |
segment lengths in pixels or as a string of the characters |
| 3499 |
``'.'``, ``','``, ``'-'``, ``'_'`` and space. |
| 3500 |
An empty pattern (the default) draws a solid outline. |
| 3501 |
|
| 3502 |
*dashoffset* |
| 3503 |
The starting offset in pixels into the *dash* pattern. |
| 3504 |
Ignored if there is no *dash* pattern. |
| 3505 |
|
| 3506 |
*stipple* |
| 3507 |
A bitmap used as a stipple pattern when filling the item. |
| 3508 |
Only well supported on X11. |
| 3509 |
|
| 3510 |
*outlinestipple* |
| 3511 |
A bitmap used as a stipple pattern when drawing the outline. |
| 3512 |
Has no effect if *outline* is empty. |
| 3513 |
|
| 3514 |
*offset*, *outlineoffset* |
| 3515 |
The offset of the fill and outline stipple patterns, given as |
| 3516 |
``'x,y'`` or as a side such as ``'n'``, ``'se'`` or ``'center'``. |
| 3517 |
Stipple offsets are only supported on X11. |
| 3518 |
|
| 3519 |
*state* |
| 3520 |
Overrides the canvas state for this item; one of ``'normal'``, |
| 3521 |
``'disabled'`` or ``'hidden'``. |
| 3522 |
|
| 3523 |
*tags* |
| 3524 |
A single tag or a sequence of tags to associate with the item, |
| 3525 |
replacing any existing tags. |
| 3526 |
|
| 3527 |
Many of these options have *active...* and *disabled...* variants |
| 3528 |
(such as *activefill*, *disabledfill*, *activewidth*, *disableddash*, |
| 3529 |
*activeoutline*, *disabledstipple*) that override the base option when |
| 3530 |
the item is the active item (under the mouse pointer) or is in the |
| 3531 |
disabled state. |
| 3532 |
|
| 3533 |
The following item types support additional options. |
| 3534 |
|
| 3535 |
For ``arc`` items: |
| 3536 |
|
| 3537 |
*start* |
| 3538 |
The start of the arc's angular range, in degrees measured |
| 3539 |
counter-clockwise from the 3-o'clock position. |
| 3540 |
|
| 3541 |
*extent* |
| 3542 |
The size of the angular range, in degrees counter-clockwise from |
| 3543 |
*start*. |
| 3544 |
|
| 3545 |
*style* |
| 3546 |
How the arc is drawn: ``'pieslice'`` (the default), ``'chord'`` or |
| 3547 |
``'arc'``. |
| 3548 |
|
| 3549 |
For ``line`` items: |
| 3550 |
|
| 3551 |
*arrow* |
| 3552 |
Where to draw arrowheads: ``'none'`` (the default), ``'first'``, |
| 3553 |
``'last'`` or ``'both'``. |
| 3554 |
|
| 3555 |
*arrowshape* |
| 3556 |
A sequence of three distances describing the shape of the |
| 3557 |
arrowheads. |
| 3558 |
|
| 3559 |
*capstyle* |
| 3560 |
How line ends are drawn: ``'butt'`` (the default), ``'projecting'`` |
| 3561 |
or ``'round'``. |
| 3562 |
|
| 3563 |
*joinstyle* |
| 3564 |
How line vertices are drawn: ``'round'`` (the default), ``'bevel'`` |
| 3565 |
or ``'miter'``. |
| 3566 |
|
| 3567 |
*smooth* |
| 3568 |
The smoothing method: a false value (the default) for no smoothing, |
| 3569 |
or ``'true'``/``'bezier'`` or ``'raw'`` to draw the line as a curve. |
| 3570 |
|
| 3571 |
*splinesteps* |
| 3572 |
The number of line segments approximating each spline when |
| 3573 |
*smooth* is enabled. |
| 3574 |
|
| 3575 |
For ``polygon`` items: |
| 3576 |
|
| 3577 |
*joinstyle*, *smooth*, *splinesteps* |
| 3578 |
As for ``line`` items, applied to the polygon's outline. |
| 3579 |
|
| 3580 |
For ``text`` items: |
| 3581 |
|
| 3582 |
*text* |
| 3583 |
The string to display; newline characters start new lines. |
| 3584 |
|
| 3585 |
*font* |
| 3586 |
The font used for the text. |
| 3587 |
|
| 3588 |
*justify* |
| 3589 |
How lines are justified: ``'left'`` (the default), ``'right'`` or |
| 3590 |
``'center'``. |
| 3591 |
|
| 3592 |
*anchor* |
| 3593 |
How the text is positioned relative to its point, defaulting to |
| 3594 |
``'center'``. |
| 3595 |
|
| 3596 |
*width* |
| 3597 |
The maximum line length; if non-zero, lines are wrapped at spaces. |
| 3598 |
|
| 3599 |
*angle* |
| 3600 |
How many degrees to rotate the text counter-clockwise about its |
| 3601 |
positioning point, from ``0.0`` to ``360.0`` (default ``0.0``). |
| 3602 |
|
| 3603 |
*underline* |
| 3604 |
The index of a character to underline, or ``-1`` for none. |
| 3605 |
|
| 3606 |
For ``bitmap`` items: |
| 3607 |
|
| 3608 |
*bitmap* |
| 3609 |
The bitmap to display. |
| 3610 |
|
| 3611 |
*anchor* |
| 3612 |
How the bitmap is positioned relative to its point. |
| 3613 |
|
| 3614 |
*background*, *foreground* |
| 3615 |
The colors used for the bitmap's ``0`` and ``1`` pixels; an empty |
| 3616 |
*background* makes the ``0`` pixels transparent. |
| 3617 |
Both have *active...* and *disabled...* variants, and *bitmap* has |
| 3618 |
*activebitmap* and *disabledbitmap* variants. |
| 3619 |
|
| 3620 |
For ``image`` items: |
| 3621 |
|
| 3622 |
*image* |
| 3623 |
The Tk image to display, previously created with the image |
| 3624 |
protocols. |
| 3625 |
|
| 3626 |
*anchor* |
| 3627 |
How the image is positioned relative to its point. |
| 3628 |
|
| 3629 |
Both options have *active...* and *disabled...* variants |
| 3630 |
(*activeimage*, *disabledimage*) used in the active and disabled |
| 3631 |
states. |
| 3632 |
|
| 3633 |
For ``window`` items: |
| 3634 |
|
| 3635 |
*window* |
| 3636 |
The widget to embed; it must be a child of the canvas or of one of |
| 3637 |
its ancestors, and may not be a top-level window. |
| 3638 |
|
| 3639 |
*anchor* |
| 3640 |
How the window is positioned relative to its point. |
| 3641 |
|
| 3642 |
*width*, *height* |
| 3643 |
The size to assign to the window; if zero (the default), the window |
| 3644 |
is given its requested size. |
| 3645 |
|
| 3646 |
``oval`` and ``rectangle`` items have no type-specific options; they |
| 3647 |
use only the standard item options. |
| 3648 |
|
| 3649 |
.. note:: |
| 3650 |
|
| 3651 |
Tk 8.6 added the *angle* option and Tk 9.0 added the *underline* |
| 3652 |
option for ``text`` items. |
| 3653 |
|
| 3654 |
.. method:: coords(tagOrId) |
| 3655 |
coords(tagOrId, coordList, /) |
| 3656 |
coords(tagOrId, /, *coordList) |
| 3657 |
|
| 3658 |
Query or modify the coordinates of an item. |
| 3659 |
With only *tagOrId*, return a list of the floating-point coordinates of |
| 3660 |
the item given by *tagOrId* (the first matching item if it matches |
| 3661 |
several). |
| 3662 |
Given new coordinates, replace the coordinates of that item with them; |
| 3663 |
like the ``create_*`` methods, the coordinates may be given as separate |
| 3664 |
numbers, as a single sequence, or as coordinate pairs. |
| 3665 |
The returned coordinates are always in pixels, regardless of the units |
| 3666 |
used to specify them; for rectangles, ovals and arcs they are ordered |
| 3667 |
left, top, right, bottom. |
| 3668 |
|
| 3669 |
.. versionchanged:: 3.12 |
| 3670 |
The arguments are now flattened: the coordinates may be given as |
| 3671 |
separate arguments, as a single sequence, or grouped in pairs, like |
| 3672 |
the ``create_*`` methods. |
| 3673 |
|
| 3674 |
|
| 3675 |
.. method:: move(tagOrId, xAmount, yAmount, /) |
| 3676 |
|
| 3677 |
Move each of the items given by *tagOrId* in the canvas coordinate space |
| 3678 |
by adding *xAmount* to every x-coordinate and *yAmount* to every |
| 3679 |
y-coordinate of the item. |
| 3680 |
|
| 3681 |
.. method:: moveto(tagOrId, x='', y='') |
| 3682 |
|
| 3683 |
Move the items given by *tagOrId* so that the first coordinate pair (the |
| 3684 |
upper-left corner of the bounding box) of the lowest matching item is at |
| 3685 |
position (*x*, *y*). |
| 3686 |
*x* or *y* may be an empty string, in which case the corresponding |
| 3687 |
coordinate is unchanged. |
| 3688 |
All matching items keep their positions relative to each other. |
| 3689 |
|
| 3690 |
.. versionadded:: 3.8 |
| 3691 |
|
| 3692 |
|
| 3693 |
.. method:: scale(tagOrId, xOrigin, yOrigin, xScale, yScale, /) |
| 3694 |
|
| 3695 |
Rescale the coordinates of all items given by *tagOrId* in canvas |
| 3696 |
coordinate space. |
| 3697 |
Each x-coordinate is adjusted so that its distance from *xOrigin* changes |
| 3698 |
by a factor of *xScale*, and each y-coordinate so that its distance from |
| 3699 |
*yOrigin* changes by a factor of *yScale* (a factor of ``1.0`` leaves the |
| 3700 |
coordinate unchanged). |
| 3701 |
|
| 3702 |
.. method:: delete(*tagOrIds) |
| 3703 |
|
| 3704 |
Delete each of the items given by the *tagOrIds* arguments. |
| 3705 |
|
| 3706 |
.. method:: dchars(tagOrId, first, /) |
| 3707 |
dchars(tagOrId, first, last, /) |
| 3708 |
|
| 3709 |
Delete from each of the items given by *tagOrId* the characters (for text |
| 3710 |
items) or coordinates (for line and polygon items) in the range from |
| 3711 |
*first* to *last* inclusive; *last* defaults to *first*. |
| 3712 |
Items that do not support indexing ignore this operation. |
| 3713 |
|
| 3714 |
.. method:: insert(tagOrId, beforeThis, string, /) |
| 3715 |
|
| 3716 |
Insert *string* into each of the items given by *tagOrId* just before the |
| 3717 |
character or coordinate whose index is *beforeThis*. |
| 3718 |
For line and polygon items *string* must be a valid sequence of |
| 3719 |
coordinates. |
| 3720 |
|
| 3721 |
.. method:: itemcget(tagOrId, option) |
| 3722 |
|
| 3723 |
Return the current value of the configuration option *option* for the |
| 3724 |
item given by *tagOrId* (the lowest matching item if it matches several). |
| 3725 |
This is like :meth:`~Misc.cget` but applies to an individual item. |
| 3726 |
|
| 3727 |
.. method:: itemconfig(tagOrId, cnf=None, **kw) |
| 3728 |
:no-typesetting: |
| 3729 |
|
| 3730 |
.. method:: itemconfigure(tagOrId, cnf=None, **kw) |
| 3731 |
|
| 3732 |
Query or modify the configuration options of the items given by |
| 3733 |
*tagOrId*. |
| 3734 |
This mirrors :meth:`~Misc.configure`, except that it applies to |
| 3735 |
individual items rather than to the canvas as a whole. |
| 3736 |
With no options, it returns a dictionary describing the current options |
| 3737 |
of the first matching item; otherwise it sets the given options on every |
| 3738 |
matching item. |
| 3739 |
The legal options are those accepted by the corresponding ``create_*`` |
| 3740 |
method. |
| 3741 |
:meth:`itemconfig` is an alias of :meth:`!itemconfigure`. |
| 3742 |
|
| 3743 |
.. method:: type(tagOrId) |
| 3744 |
|
| 3745 |
Return the type of the item given by *tagOrId* (the first matching item |
| 3746 |
if it matches several), such as ``'rectangle'`` or ``'text'``, or |
| 3747 |
``None`` if *tagOrId* does not match any item. |
| 3748 |
|
| 3749 |
.. method:: gettags(tagOrId, /) |
| 3750 |
|
| 3751 |
Return a tuple of the tags associated with the item given by *tagOrId* |
| 3752 |
(the first matching item in display-list order if it matches several). |
| 3753 |
Return an empty tuple if no item matches or the item has no tags. |
| 3754 |
|
| 3755 |
.. method:: dtag(tagOrId, /) |
| 3756 |
dtag(tagOrId, tagToDelete, /) |
| 3757 |
|
| 3758 |
Remove the tag *tagToDelete* (which defaults to *tagOrId*) from each of |
| 3759 |
the items given by *tagOrId*. |
| 3760 |
Items that do not have that tag are unaffected. |
| 3761 |
|
| 3762 |
.. method:: addtag(newtag, searchSpec, /, *args) |
| 3763 |
|
| 3764 |
Add the tag *newtag* to each item selected by the search specification |
| 3765 |
*searchSpec* (and any further *args*). |
| 3766 |
*searchSpec* is one of ``'above'``, ``'all'``, ``'below'``, |
| 3767 |
``'closest'``, ``'enclosed'``, ``'overlapping'`` or ``'withtag'``; the |
| 3768 |
``addtag_*`` methods below are convenient wrappers that supply each of |
| 3769 |
these forms. |
| 3770 |
|
| 3771 |
.. method:: addtag_above(newtag, tagOrId) |
| 3772 |
|
| 3773 |
Add the tag *newtag* to the item just above (after) *tagOrId* in the |
| 3774 |
display list. |
| 3775 |
|
| 3776 |
.. method:: addtag_all(newtag) |
| 3777 |
|
| 3778 |
Add the tag *newtag* to all items in the canvas. |
| 3779 |
|
| 3780 |
.. method:: addtag_below(newtag, tagOrId) |
| 3781 |
|
| 3782 |
Add the tag *newtag* to the item just below (before) *tagOrId* in the |
| 3783 |
display list. |
| 3784 |
|
| 3785 |
.. method:: addtag_closest(newtag, x, y, halo=None, start=None) |
| 3786 |
|
| 3787 |
Add the tag *newtag* to the item closest to the point (*x*, *y*). |
| 3788 |
If *halo* is given, any item within that distance of the point is treated |
| 3789 |
as overlapping it. |
| 3790 |
If *start* is given (a tag or id), select the topmost closest item that |
| 3791 |
lies below *start* in the display list, which can be used to step through |
| 3792 |
all the closest items. |
| 3793 |
|
| 3794 |
.. method:: addtag_enclosed(newtag, x1, y1, x2, y2) |
| 3795 |
|
| 3796 |
Add the tag *newtag* to every item completely enclosed within the |
| 3797 |
rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= *y2*. |
| 3798 |
|
| 3799 |
.. method:: addtag_overlapping(newtag, x1, y1, x2, y2) |
| 3800 |
|
| 3801 |
Add the tag *newtag* to every item that overlaps or is enclosed within |
| 3802 |
the rectangle (*x1*, *y1*, *x2*, *y2*), where *x1* <= *x2* and *y1* <= |
| 3803 |
*y2*. |
| 3804 |
|
| 3805 |
.. method:: addtag_withtag(newtag, tagOrId) |
| 3806 |
|
| 3807 |
Add the tag *newtag* to every item given by *tagOrId*. |
| 3808 |
|
| 3809 |
.. method:: find(searchSpec, /, *args) |
| 3810 |
|
| 3811 |
Return a tuple of the ids of all items selected by the search |
| 3812 |
specification *searchSpec* (and any further *args*), in stacking order |
| 3813 |
with the lowest item first. |
| 3814 |
The search specification has any of the forms accepted by :meth:`addtag`. |
| 3815 |
The ``find_*`` methods below are more convenient wrappers around it. |
| 3816 |
|
| 3817 |
.. method:: find_above(tagOrId) |
| 3818 |
|
| 3819 |
Return a tuple containing the id of the item just above *tagOrId* in the |
| 3820 |
display list. |
| 3821 |
|
| 3822 |
.. method:: find_all() |
| 3823 |
|
| 3824 |
Return a tuple of the ids of all items in the canvas, in stacking order. |
| 3825 |
|
| 3826 |
.. method:: find_below(tagOrId) |
| 3827 |
|
| 3828 |
Return a tuple containing the id of the item just below *tagOrId* in the |
| 3829 |
display list. |
| 3830 |
|
| 3831 |
.. method:: find_closest(x, y, halo=None, start=None) |
| 3832 |
|
| 3833 |
Return a tuple containing the id of the item closest to the point (*x*, |
| 3834 |
*y*). |
| 3835 |
*halo* and *start* are interpreted as for :meth:`addtag_closest`. |
| 3836 |
|
| 3837 |
.. method:: find_enclosed(x1, y1, x2, y2) |
| 3838 |
|
| 3839 |
Return a tuple of the ids of all items completely enclosed within the |
| 3840 |
rectangle (*x1*, *y1*, *x2*, *y2*). |
| 3841 |
|
| 3842 |
.. method:: find_overlapping(x1, y1, x2, y2) |
| 3843 |
|
| 3844 |
Return a tuple of the ids of all items that overlap or are enclosed |
| 3845 |
within the rectangle (*x1*, *y1*, *x2*, *y2*). |
| 3846 |
|
| 3847 |
.. method:: find_withtag(tagOrId) |
| 3848 |
|
| 3849 |
Return a tuple of the ids of all items given by *tagOrId*. |
| 3850 |
|
| 3851 |
.. method:: lift(tagOrId, aboveThis=None, /) |
| 3852 |
:no-typesetting: |
| 3853 |
|
| 3854 |
.. method:: tkraise(tagOrId, aboveThis=None, /) |
| 3855 |
:no-typesetting: |
| 3856 |
|
| 3857 |
.. method:: tag_raise(tagOrId, aboveThis=None, /) |
| 3858 |
|
| 3859 |
Move all items given by *tagOrId* to a new position in the display list |
| 3860 |
just above the item given by *aboveThis*, or to the top of the display |
| 3861 |
list if *aboveThis* is omitted. |
| 3862 |
When several items are moved their relative order is preserved. |
| 3863 |
This has no effect on embedded window items, whose stacking order is |
| 3864 |
controlled by :meth:`Misc.tkraise` and :meth:`Misc.lower` instead. |
| 3865 |
:meth:`lift` and :meth:`tkraise` are aliases of :meth:`!tag_raise`. |
| 3866 |
|
| 3867 |
.. method:: lower(tagOrId, belowThis=None, /) |
| 3868 |
:no-typesetting: |
| 3869 |
|
| 3870 |
.. method:: tag_lower(tagOrId, belowThis=None, /) |
| 3871 |
|
| 3872 |
Move all items given by *tagOrId* to a new position in the display list |
| 3873 |
just below the item given by *belowThis*, or to the bottom of the display |
| 3874 |
list if *belowThis* is omitted. |
| 3875 |
When several items are moved their relative order is preserved. |
| 3876 |
This has no effect on embedded window items. |
| 3877 |
:meth:`lower` is an alias of :meth:`!tag_lower`. |
| 3878 |
|
| 3879 |
.. note:: |
| 3880 |
|
| 3881 |
On a :class:`Canvas`, :meth:`tkraise`/:meth:`lift` and :meth:`lower` |
| 3882 |
restack canvas items, |
| 3883 |
shadowing the inherited :meth:`Misc.tkraise`/:meth:`Misc.lift` and |
| 3884 |
:meth:`Misc.lower` methods that restack the widget itself, |
| 3885 |
which are therefore not available. |
| 3886 |
|
| 3887 |
.. method:: tag_bind(tagOrId, sequence=None, func=None, add=None) |
| 3888 |
|
| 3889 |
Bind the callback *func* to the event *sequence* for all items given by |
| 3890 |
*tagOrId*, so that *func* is invoked whenever that event occurs for one |
| 3891 |
of the items. |
| 3892 |
This is like :meth:`Widget.bind <Misc.bind>` but operates on canvas items |
| 3893 |
rather than on whole widgets; only mouse, keyboard and virtual events may |
| 3894 |
be bound. |
| 3895 |
Mouse events are directed to the current item and keyboard events to the |
| 3896 |
focus item (see :meth:`focus`). |
| 3897 |
If *add* is true the new binding is added to any existing bindings for |
| 3898 |
the same sequence, rather than replacing them. |
| 3899 |
Return the identifier of the bound function, which can be passed to |
| 3900 |
:meth:`tag_unbind`. |
| 3901 |
|
| 3902 |
.. method:: tag_unbind(tagOrId, sequence, funcid=None) |
| 3903 |
|
| 3904 |
Remove for all items given by *tagOrId* the binding for the event |
| 3905 |
*sequence*. |
| 3906 |
If *funcid* is given, only that callback (as returned by |
| 3907 |
:meth:`tag_bind`) is unbound and deregistered. |
| 3908 |
|
| 3909 |
.. versionchanged:: 3.13 |
| 3910 |
If *funcid* is given, only that callback is unbound. |
| 3911 |
|
| 3912 |
|
| 3913 |
.. method:: bbox(tagOrId, /, *tagOrIds) |
| 3914 |
|
| 3915 |
Return a 4-tuple ``(x1, y1, x2, y2)`` giving an approximate bounding box, |
| 3916 |
in pixels, that encloses all the items given by *tagOrId* and any further |
| 3917 |
*tagOrIds*. |
| 3918 |
The result may overestimate the true bounding box by a few pixels. |
| 3919 |
Return ``None`` if no item matches or the matching items have nothing to |
| 3920 |
display. |
| 3921 |
|
| 3922 |
This shadows the inherited :meth:`!Misc.bbox`; |
| 3923 |
use :meth:`~Misc.grid_bbox` for the grid bounding box. |
| 3924 |
|
| 3925 |
.. method:: canvasx(screenx, gridspacing=None) |
| 3926 |
|
| 3927 |
Given a window x-coordinate *screenx*, return the canvas x-coordinate |
| 3928 |
displayed at that location. |
| 3929 |
If *gridspacing* is given, the result is rounded to the nearest multiple |
| 3930 |
of *gridspacing* units. |
| 3931 |
|
| 3932 |
.. method:: canvasy(screeny, gridspacing=None) |
| 3933 |
|
| 3934 |
Given a window y-coordinate *screeny*, return the canvas y-coordinate |
| 3935 |
displayed at that location. |
| 3936 |
If *gridspacing* is given, the result is rounded to the nearest multiple |
| 3937 |
of *gridspacing* units. |
| 3938 |
|
| 3939 |
.. method:: focus() |
| 3940 |
focus(tagOrId, /) |
| 3941 |
|
| 3942 |
With *tagOrId*, set the keyboard focus for the canvas to the first item |
| 3943 |
given by *tagOrId* that supports the insertion cursor; the focus is left |
| 3944 |
unchanged if no such item exists. |
| 3945 |
If *tagOrId* is an empty string, reset the focus so that no item has it. |
| 3946 |
With no argument, return the id of the item that currently has the focus, |
| 3947 |
or an empty string if none does. |
| 3948 |
An item only displays the insertion cursor when both it is the focus item |
| 3949 |
and its canvas has the input focus. |
| 3950 |
|
| 3951 |
This shadows the inherited :meth:`!Misc.focus`; |
| 3952 |
use :meth:`~Misc.focus_set` to focus the widget itself. |
| 3953 |
|
| 3954 |
.. method:: icursor(tagOrId, index, /) |
| 3955 |
|
| 3956 |
Set the insertion cursor of the items given by *tagOrId* to just before |
| 3957 |
the character given by *index*. |
| 3958 |
Items that do not support an insertion cursor are unaffected. |
| 3959 |
The cursor is only displayed when the item has the focus, but its |
| 3960 |
position may be set at any time. |
| 3961 |
|
| 3962 |
.. method:: index(tagOrId, index, /) |
| 3963 |
|
| 3964 |
Return as an integer the numerical index within *tagOrId* corresponding |
| 3965 |
to *index*, which is a textual description of a position (for text items |
| 3966 |
an index into the characters, for line and polygon items an index into |
| 3967 |
the coordinates). |
| 3968 |
If *tagOrId* matches several items, the first one that supports indexing |
| 3969 |
is used. |
| 3970 |
|
| 3971 |
.. method:: select_adjust(tagOrId, index) |
| 3972 |
|
| 3973 |
Adjust the end of the selection in *tagOrId* nearest to *index* so that |
| 3974 |
it is at *index*, and make the other end the anchor point for future |
| 3975 |
:meth:`select_to` calls. |
| 3976 |
If the selection is not currently in *tagOrId*, this behaves like |
| 3977 |
:meth:`select_to`. |
| 3978 |
|
| 3979 |
.. method:: select_clear() |
| 3980 |
|
| 3981 |
Clear the selection if it is in this canvas; otherwise do nothing. |
| 3982 |
|
| 3983 |
.. method:: select_from(tagOrId, index) |
| 3984 |
|
| 3985 |
Set the selection anchor point to just before the character given by |
| 3986 |
*index* in the item given by *tagOrId*. |
| 3987 |
This does not change the selection itself; it sets the fixed end for |
| 3988 |
future :meth:`select_to` calls. |
| 3989 |
|
| 3990 |
.. method:: select_item() |
| 3991 |
|
| 3992 |
Return the id of the item that holds the selection, or ``None`` if the |
| 3993 |
selection is not in this canvas. |
| 3994 |
Unlike :meth:`find` and the ``find_*`` methods, this returns the id as a |
| 3995 |
string rather than an integer. |
| 3996 |
|
| 3997 |
.. method:: select_to(tagOrId, index) |
| 3998 |
|
| 3999 |
Set the selection to the characters of *tagOrId* between the selection |
| 4000 |
anchor point and *index*, inclusive of *index*. |
| 4001 |
The anchor point is the one set by the most recent :meth:`select_adjust` |
| 4002 |
or :meth:`select_from` call. |
| 4003 |
|
| 4004 |
.. method:: scan_mark(x, y) |
| 4005 |
|
| 4006 |
Record *x*, *y* and the current view, for use with later |
| 4007 |
:meth:`scan_dragto` calls. |
| 4008 |
This is typically bound to a mouse button press in the widget. |
| 4009 |
|
| 4010 |
.. method:: scan_dragto(x, y, gain=10) |
| 4011 |
|
| 4012 |
Scroll the canvas by *gain* times the difference between *x*, *y* and the |
| 4013 |
coordinates passed to the last :meth:`scan_mark` call. |
| 4014 |
This is typically bound to mouse motion events in the widget, producing |
| 4015 |
the effect of dragging the canvas at high speed through its window. |
| 4016 |
|
| 4017 |
.. method:: postscript(cnf={}, **kw) |
| 4018 |
|
| 4019 |
Generate a PostScript (Encapsulated PostScript, version 3.0) |
| 4020 |
representation of part or all of the canvas. |
| 4021 |
If the *file* or *channel* option is given, the PostScript is written |
| 4022 |
there and an empty string is returned; otherwise it is returned as a |
| 4023 |
string. |
| 4024 |
By default only the area currently visible in the window is generated, so |
| 4025 |
it is usually necessary either to call :meth:`~Misc.update` first or to |
| 4026 |
use the *width* and *height* options. |
| 4027 |
Supported options include *colormap*, *colormode*, *file*, *fontmap*, |
| 4028 |
*height*, *pageanchor*, *pageheight*, *pagewidth*, *pagex*, *pagey*, |
| 4029 |
*rotate*, *width*, *x* and *y*. |
| 4030 |
|
| 4031 |
|
| 4032 |
.. class:: Checkbutton(master=None, cnf={}, **kw) |
| 4033 |
|
| 4034 |
A :class:`!Checkbutton` widget displays a textual string, bitmap or image |
| 4035 |
together with a square indicator, and toggles a boolean selection when |
| 4036 |
pressed. |
| 4037 |
It has all the behavior of a simple button and, in addition, can be |
| 4038 |
selected: when selected the indicator is drawn with a check mark and the |
| 4039 |
associated variable is set to the ``onvalue``, and when deselected the |
| 4040 |
indicator is drawn empty and the variable is set to the ``offvalue``. |
| 4041 |
Inherits from :class:`Widget`. |
| 4042 |
In addition to the standard widget options, a checkbutton accepts the |
| 4043 |
options documented in the Tk ``checkbutton`` manual page, such as |
| 4044 |
*variable*, *onvalue*, *offvalue* and *command*. |
| 4045 |
|
| 4046 |
.. method:: invoke() |
| 4047 |
|
| 4048 |
Do just what would happen if the user pressed the checkbutton with the |
| 4049 |
mouse: toggle the selection state of the button and invoke the associated |
| 4050 |
command, if there is one. |
| 4051 |
Return the result of the command, or an empty string if no command is |
| 4052 |
associated with the checkbutton. |
| 4053 |
This is ignored if the checkbutton's state is ``disabled``. |
| 4054 |
|
| 4055 |
.. method:: select() |
| 4056 |
|
| 4057 |
Select the checkbutton and set the associated variable to its |
| 4058 |
``onvalue``. |
| 4059 |
|
| 4060 |
.. method:: deselect() |
| 4061 |
|
| 4062 |
Deselect the checkbutton and set the associated variable to its |
| 4063 |
``offvalue``. |
| 4064 |
|
| 4065 |
.. method:: toggle() |
| 4066 |
|
| 4067 |
Toggle the selection state of the button, redisplaying it and modifying |
| 4068 |
its associated variable to reflect the new state. |
| 4069 |
|
| 4070 |
.. method:: flash() |
| 4071 |
|
| 4072 |
Flash the checkbutton by redisplaying it several times, alternating |
| 4073 |
between the active and normal colors. |
| 4074 |
At the end of the flash the checkbutton is left in the same normal or |
| 4075 |
active state as when the method was called. |
| 4076 |
This is ignored if the checkbutton's state is ``disabled``. |
| 4077 |
|
| 4078 |
|
| 4079 |
.. class:: Entry(master=None, cnf={}, **kw) |
| 4080 |
|
| 4081 |
An :class:`!Entry` widget displays a single line of text and lets the user |
| 4082 |
edit it. |
| 4083 |
Inherits from :class:`Widget` and :class:`XView`; since entries can hold |
| 4084 |
strings too long to fit in the window, they support horizontal scrolling |
| 4085 |
through :meth:`~XView.xview`. |
| 4086 |
|
| 4087 |
In addition to the standard widget options, an entry accepts the options |
| 4088 |
documented in the Tk ``entry`` manual page. |
| 4089 |
Notable ones are *textvariable* (the name of a variable kept in sync with |
| 4090 |
the entry's contents), *show* (if set, each character is displayed as the |
| 4091 |
given character rather than its true value, useful for password entry), |
| 4092 |
*validate* and *validatecommand* (which together let a callback accept or |
| 4093 |
reject edits), and *state* (one of ``'normal'``, ``'disabled'`` or |
| 4094 |
``'readonly'``). |
| 4095 |
|
| 4096 |
Many of the methods below take an *index* argument that selects a character |
| 4097 |
in the entry's string. |
| 4098 |
As described in the Tk ``entry`` manual page, *index* may be a number |
| 4099 |
(counting from 0), ``'insert'`` (the character just after the insertion |
| 4100 |
cursor), ``'end'`` (just after the last character), ``'anchor'`` (the |
| 4101 |
selection anchor point), ``'sel.first'`` and ``'sel.last'`` (the ends of the |
| 4102 |
selection), or ``@x`` (the character covering pixel x-coordinate *x* in the |
| 4103 |
window). |
| 4104 |
Out-of-range indices are rounded to the nearest legal value. |
| 4105 |
|
| 4106 |
.. method:: delete(first, last=None) |
| 4107 |
|
| 4108 |
Delete the characters from index *first* up to but not including index |
| 4109 |
*last*. |
| 4110 |
If *last* is omitted, only the single character at *first* is deleted. |
| 4111 |
|
| 4112 |
.. method:: get() |
| 4113 |
|
| 4114 |
Return the entry's current string. |
| 4115 |
|
| 4116 |
.. method:: insert(index, string) |
| 4117 |
|
| 4118 |
Insert *string* just before the character given by *index*. |
| 4119 |
|
| 4120 |
.. method:: icursor(index) |
| 4121 |
|
| 4122 |
Arrange for the insertion cursor to be displayed just before the |
| 4123 |
character given by *index*. |
| 4124 |
|
| 4125 |
.. method:: index(index) |
| 4126 |
|
| 4127 |
Return the numerical index corresponding to *index*. |
| 4128 |
|
| 4129 |
.. method:: select_adjust(index) |
| 4130 |
:no-typesetting: |
| 4131 |
|
| 4132 |
.. method:: selection_adjust(index) |
| 4133 |
|
| 4134 |
Locate the end of the selection nearest to the character given by |
| 4135 |
*index*, and adjust that end to be at *index* (including but not going |
| 4136 |
beyond it); the other end becomes the anchor point for future |
| 4137 |
:meth:`selection_to` calls. |
| 4138 |
If there is no selection in the entry, a new one is created between |
| 4139 |
*index* and the most recent anchor point, inclusive. |
| 4140 |
:meth:`select_adjust` is an alias of :meth:`!selection_adjust`. |
| 4141 |
|
| 4142 |
.. method:: select_clear() |
| 4143 |
:no-typesetting: |
| 4144 |
|
| 4145 |
.. method:: selection_clear() |
| 4146 |
|
| 4147 |
Clear the selection if it is currently in this widget. |
| 4148 |
If the selection is not in this widget the method has no effect. |
| 4149 |
:meth:`select_clear` is an alias of :meth:`!selection_clear`. |
| 4150 |
|
| 4151 |
.. note:: |
| 4152 |
|
| 4153 |
This shadows the inherited :meth:`Misc.selection_clear`, |
| 4154 |
which clears the X selection; |
| 4155 |
that method is not available on an :class:`Entry`. |
| 4156 |
|
| 4157 |
.. method:: select_from(index) |
| 4158 |
:no-typesetting: |
| 4159 |
|
| 4160 |
.. method:: selection_from(index) |
| 4161 |
|
| 4162 |
Set the selection anchor point to just before the character given by |
| 4163 |
*index*, without changing the selection. |
| 4164 |
:meth:`select_from` is an alias of :meth:`!selection_from`. |
| 4165 |
|
| 4166 |
.. method:: select_present() |
| 4167 |
:no-typesetting: |
| 4168 |
|
| 4169 |
.. method:: selection_present() |
| 4170 |
|
| 4171 |
Return ``True`` if there are characters selected in the entry, ``False`` |
| 4172 |
otherwise. |
| 4173 |
:meth:`select_present` is an alias of :meth:`!selection_present`. |
| 4174 |
|
| 4175 |
.. method:: select_range(start, end) |
| 4176 |
:no-typesetting: |
| 4177 |
|
| 4178 |
.. method:: selection_range(start, end) |
| 4179 |
|
| 4180 |
Set the selection to include the characters starting with the one indexed |
| 4181 |
by *start* and ending with the one just before *end*. |
| 4182 |
If *end* refers to the same character as *start* or an earlier one, the |
| 4183 |
selection is cleared. |
| 4184 |
:meth:`select_range` is an alias of :meth:`!selection_range`. |
| 4185 |
|
| 4186 |
.. method:: select_to(index) |
| 4187 |
:no-typesetting: |
| 4188 |
|
| 4189 |
.. method:: selection_to(index) |
| 4190 |
|
| 4191 |
Set the selection between the anchor point and *index*: if *index* is |
| 4192 |
before the anchor point, the selection runs from *index* up to but not |
| 4193 |
including the anchor; if *index* is after it, from the anchor up to but |
| 4194 |
not including *index*; if they coincide, nothing happens. |
| 4195 |
The anchor point is the one set by the most recent :meth:`selection_from` |
| 4196 |
or :meth:`selection_adjust` call. |
| 4197 |
If there is no selection in the entry, a new one is created using the |
| 4198 |
most recent anchor point. |
| 4199 |
:meth:`select_to` is an alias of :meth:`!selection_to`. |
| 4200 |
|
| 4201 |
.. method:: scan_mark(x) |
| 4202 |
|
| 4203 |
Record *x* and the current view in the entry window, for use with later |
| 4204 |
:meth:`scan_dragto` calls. |
| 4205 |
Typically associated with a mouse button press in the widget. |
| 4206 |
|
| 4207 |
.. method:: scan_dragto(x) |
| 4208 |
|
| 4209 |
Compute the difference between *x* and the *x* given to the last |
| 4210 |
:meth:`scan_mark` call, and adjust the view left or right by 10 times |
| 4211 |
that difference. |
| 4212 |
Typically associated with mouse motion events, to produce the effect of |
| 4213 |
dragging the entry at high speed through the window. |
| 4214 |
|
| 4215 |
|
| 4216 |
.. class:: Frame(master=None, cnf={}, **kw) |
| 4217 |
|
| 4218 |
A :class:`!Frame` widget is a simple container. |
| 4219 |
Its primary purpose is to act as a spacer or container for complex window |
| 4220 |
layouts; its only features are its background and an optional 3-D border to |
| 4221 |
make the frame appear raised or sunken. |
| 4222 |
Inherits from :class:`Widget`. |
| 4223 |
Refer to the Tk ``frame`` manual page for the full list of options. |
| 4224 |
|
| 4225 |
|
| 4226 |
.. class:: Label(master=None, cnf={}, **kw) |
| 4227 |
|
| 4228 |
A :class:`!Label` widget displays a non-interactive textual string, bitmap |
| 4229 |
or image. |
| 4230 |
The displayed text is set with the *text* option or linked to a variable |
| 4231 |
through *textvariable*, and an image can be shown using the *image* option. |
| 4232 |
Text must all be in a single font but may occupy multiple lines, and one |
| 4233 |
character may be underlined with the *underline* option. |
| 4234 |
Inherits from :class:`Widget`. |
| 4235 |
Refer to the Tk ``label`` manual page for the full list of options. |
| 4236 |
|
| 4237 |
|
| 4238 |
.. class:: LabelFrame(master=None, cnf={}, **kw) |
| 4239 |
|
| 4240 |
A :class:`!LabelFrame` widget is a container that has the features of a |
| 4241 |
:class:`Frame` plus the ability to display a label. |
| 4242 |
The label text is set with the *text* option and positioned with |
| 4243 |
*labelanchor*, or an arbitrary widget may be used as the label by giving it |
| 4244 |
as the *labelwidget* option. |
| 4245 |
Inherits from :class:`Widget`. |
| 4246 |
Refer to the Tk ``labelframe`` manual page for the full list of options. |
| 4247 |
|
| 4248 |
|
| 4249 |
.. class:: Listbox(master=None, cnf={}, **kw) |
| 4250 |
|
| 4251 |
A :class:`!Listbox` widget displays a list of single-line text items, one |
| 4252 |
per line, of which the user can select one or more. |
| 4253 |
The way the selection behaves is governed by the *selectmode* option, which |
| 4254 |
is one of ``browse`` (the default; at most one item, which may be dragged |
| 4255 |
with the mouse), ``single`` (at most one item), ``multiple`` (any number of |
| 4256 |
items, toggled individually), or ``extended`` (any number of items, |
| 4257 |
including discontiguous ranges, selected by clicking and dragging). |
| 4258 |
Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the |
| 4259 |
view can be scrolled horizontally and vertically with :meth:`~XView.xview` |
| 4260 |
and :meth:`~YView.yview`. |
| 4261 |
Refer to the Tk ``listbox`` manual page for the full list of options. |
| 4262 |
|
| 4263 |
Many of the methods take an *index* argument identifying a particular item. |
| 4264 |
As described in the Tk ``listbox`` manual page, *index* may be a numeric |
| 4265 |
index (counting from 0 at the top), ``'active'`` (the item with the location |
| 4266 |
cursor, set with :meth:`activate`), ``'anchor'`` (the selection anchor, set |
| 4267 |
with :meth:`selection_anchor`), ``'end'`` (the last item, or for |
| 4268 |
:meth:`index` and :meth:`insert` the position just after it), or ``@x,y`` |
| 4269 |
(the item covering pixel coordinates *x*, *y* in the listbox window). |
| 4270 |
Arguments named *first* and *last* are indices of the same forms. |
| 4271 |
|
| 4272 |
.. method:: insert(index, *elements) |
| 4273 |
|
| 4274 |
Insert the given *elements* as new items just before the item given by |
| 4275 |
*index*. |
| 4276 |
If *index* is ``'end'``, the new items are appended to the end of the |
| 4277 |
list. |
| 4278 |
|
| 4279 |
.. method:: delete(first, last=None) |
| 4280 |
|
| 4281 |
Delete the items in the range from *first* to *last* inclusive. |
| 4282 |
If *last* is omitted, it defaults to *first*, so that a single item is |
| 4283 |
deleted. |
| 4284 |
|
| 4285 |
.. method:: get(first, last=None) |
| 4286 |
|
| 4287 |
If *last* is omitted, return the contents of the item given by *first*, |
| 4288 |
or an empty string if *first* refers to a non-existent item. |
| 4289 |
If *last* is given, return a tuple of all the items in the range from |
| 4290 |
*first* to *last* inclusive. |
| 4291 |
|
| 4292 |
.. method:: size() |
| 4293 |
|
| 4294 |
Return the total number of items in the listbox. |
| 4295 |
|
| 4296 |
This shadows the inherited :meth:`!Misc.size`; |
| 4297 |
use :meth:`~Misc.grid_size` for the grid size. |
| 4298 |
|
| 4299 |
.. method:: index(index) |
| 4300 |
|
| 4301 |
Return the integer index value corresponding to *index*, or ``None`` if |
| 4302 |
*index* is out of range. |
| 4303 |
If *index* is ``'end'``, the result is a count of the number of items in |
| 4304 |
the listbox (not the index of the last item). |
| 4305 |
|
| 4306 |
.. method:: bbox(index) |
| 4307 |
|
| 4308 |
Return a tuple ``(x, y, width, height)`` describing the bounding box, in |
| 4309 |
pixels relative to the widget, of the text of the item given by *index*. |
| 4310 |
Return ``None`` if no part of that item is visible on the screen, or if |
| 4311 |
*index* refers to a non-existent item; if the item is only partly |
| 4312 |
visible, the result still gives the full area of the item, including the |
| 4313 |
parts that are not visible. |
| 4314 |
|
| 4315 |
This shadows the inherited :meth:`!Misc.bbox`; |
| 4316 |
use :meth:`~Misc.grid_bbox` for the grid bounding box. |
| 4317 |
|
| 4318 |
.. method:: nearest(y) |
| 4319 |
|
| 4320 |
Given a y-coordinate within the listbox window, return the index of the |
| 4321 |
visible item nearest to that y-coordinate. |
| 4322 |
|
| 4323 |
.. method:: see(index) |
| 4324 |
|
| 4325 |
Adjust the view so that the item given by *index* is visible. |
| 4326 |
If the item is already visible the method has no effect; if it is near an |
| 4327 |
edge of the window the listbox scrolls just enough to bring it into view |
| 4328 |
at that edge, otherwise the listbox scrolls to center the item. |
| 4329 |
|
| 4330 |
.. method:: activate(index) |
| 4331 |
|
| 4332 |
Set the active item to the one given by *index*. |
| 4333 |
If *index* is outside the range of items, the closest item is activated |
| 4334 |
instead. |
| 4335 |
The active item is drawn as specified by the *activestyle* option when |
| 4336 |
the widget has the input focus, and its index may be retrieved with the |
| 4337 |
``'active'`` index. |
| 4338 |
|
| 4339 |
.. method:: curselection() |
| 4340 |
|
| 4341 |
Return a tuple containing the numerical indices of all of the items that |
| 4342 |
are currently selected, or an empty tuple if no items are selected. |
| 4343 |
|
| 4344 |
.. method:: select_anchor(index) |
| 4345 |
:no-typesetting: |
| 4346 |
|
| 4347 |
.. method:: selection_anchor(index) |
| 4348 |
|
| 4349 |
Set the selection anchor to the item given by *index*. |
| 4350 |
If *index* refers to a non-existent item, the closest item is used. |
| 4351 |
The selection anchor is the end of the selection that is fixed while |
| 4352 |
dragging out a selection with the mouse, and may afterwards be referred |
| 4353 |
to with the ``'anchor'`` index. |
| 4354 |
:meth:`select_anchor` is an alias of :meth:`!selection_anchor`. |
| 4355 |
|
| 4356 |
.. method:: select_clear(first, last=None) |
| 4357 |
:no-typesetting: |
| 4358 |
|
| 4359 |
.. method:: selection_clear(first, last=None) |
| 4360 |
|
| 4361 |
Deselect any of the items in the range from *first* to *last* inclusive |
| 4362 |
that are selected. |
| 4363 |
The selection state of items outside this range is not changed. |
| 4364 |
:meth:`select_clear` is an alias of :meth:`!selection_clear`. |
| 4365 |
|
| 4366 |
.. note:: |
| 4367 |
|
| 4368 |
This shadows the inherited :meth:`Misc.selection_clear`, |
| 4369 |
which clears the X selection; |
| 4370 |
that method is not available on a :class:`Listbox`. |
| 4371 |
|
| 4372 |
.. method:: select_includes(index) |
| 4373 |
:no-typesetting: |
| 4374 |
|
| 4375 |
.. method:: selection_includes(index) |
| 4376 |
|
| 4377 |
Return ``True`` if the item given by *index* is currently selected, |
| 4378 |
``False`` otherwise. |
| 4379 |
:meth:`select_includes` is an alias of :meth:`!selection_includes`. |
| 4380 |
|
| 4381 |
.. method:: select_set(first, last=None) |
| 4382 |
:no-typesetting: |
| 4383 |
|
| 4384 |
.. method:: selection_set(first, last=None) |
| 4385 |
|
| 4386 |
Select all of the items in the range from *first* to *last* inclusive, |
| 4387 |
without affecting the selection state of items outside that range. |
| 4388 |
:meth:`select_set` is an alias of :meth:`!selection_set`. |
| 4389 |
|
| 4390 |
.. method:: itemcget(index, option) |
| 4391 |
|
| 4392 |
Return the current value of the configuration option *option* for the |
| 4393 |
item given by *index*. |
| 4394 |
|
| 4395 |
.. method:: itemconfig(index, cnf=None, **kw) |
| 4396 |
:no-typesetting: |
| 4397 |
|
| 4398 |
.. method:: itemconfigure(index, cnf=None, **kw) |
| 4399 |
|
| 4400 |
Query or modify the configuration options of the item given by *index*. |
| 4401 |
This mirrors :meth:`~Misc.configure`, except that it applies to an |
| 4402 |
individual item rather than to the listbox as a whole. |
| 4403 |
With no options, it returns a dictionary describing the current options |
| 4404 |
of the item; otherwise it sets the given options. |
| 4405 |
The supported item options are *background*, *foreground*, |
| 4406 |
*selectbackground* and *selectforeground*. |
| 4407 |
:meth:`itemconfig` is an alias of :meth:`!itemconfigure`. |
| 4408 |
|
| 4409 |
.. method:: scan_mark(x, y) |
| 4410 |
|
| 4411 |
Record *x*, *y* and the current view, for use with later |
| 4412 |
:meth:`scan_dragto` calls. |
| 4413 |
This is typically bound to a mouse button press in the widget. |
| 4414 |
|
| 4415 |
.. method:: scan_dragto(x, y) |
| 4416 |
|
| 4417 |
Scroll the listbox by 10 times the difference between *x*, *y* and the |
| 4418 |
coordinates passed to the last :meth:`scan_mark` call. |
| 4419 |
This is typically bound to mouse motion events in the widget, producing |
| 4420 |
the effect of dragging the list at high speed through the window. |
| 4421 |
|
| 4422 |
|
| 4423 |
.. class:: Menu(master=None, cnf={}, **kw) |
| 4424 |
|
| 4425 |
A :class:`!Menu` widget displays a column of entries, each of which may be a |
| 4426 |
command, a checkbutton, a radiobutton, a cascade (which posts an associated |
| 4427 |
submenu) or a separator. |
| 4428 |
Menus are used as the menubar of a toplevel window, as pulldown menus posted |
| 4429 |
from a cascade entry or menubutton, and as popup menus. |
| 4430 |
Inherits from :class:`Widget`. |
| 4431 |
|
| 4432 |
Many of the entry methods take an *index* argument that selects which entry |
| 4433 |
to operate on. |
| 4434 |
As described in the Tk ``menu`` manual page, *index* may be a numeric index |
| 4435 |
(counting from 0 at the top), ``'active'`` (the currently active entry), |
| 4436 |
``'end'`` or ``'last'`` (the bottommost entry), ``'none'`` (no entry at all, |
| 4437 |
written ``{}`` in Tcl), ``@y`` (the entry covering pixel y-coordinate *y* in |
| 4438 |
the menu window), or a pattern matched against the labels of the entries |
| 4439 |
from the top down. |
| 4440 |
|
| 4441 |
.. method:: add(itemType, cnf={}, **kw) |
| 4442 |
|
| 4443 |
Add a new entry to the bottom of the menu. |
| 4444 |
*itemType* is one of ``'command'``, ``'cascade'``, ``'checkbutton'``, |
| 4445 |
``'radiobutton'`` or ``'separator'`` and determines the type of the new |
| 4446 |
entry; the remaining options configure it. |
| 4447 |
The :meth:`!add_command`, :meth:`!add_cascade`, :meth:`!add_checkbutton`, |
| 4448 |
:meth:`!add_radiobutton` and :meth:`!add_separator` convenience methods |
| 4449 |
call this method with the corresponding *itemType*. |
| 4450 |
|
| 4451 |
The entry is configured by the following options, although not every |
| 4452 |
option applies to every entry type (a separator accepts none of them): |
| 4453 |
|
| 4454 |
*label* |
| 4455 |
The text to display in the entry. |
| 4456 |
|
| 4457 |
*command* |
| 4458 |
The function to call when the entry is invoked (command, checkbutton |
| 4459 |
and radiobutton entries). |
| 4460 |
|
| 4461 |
*accelerator* |
| 4462 |
A string displayed at the right of the entry to advertise an |
| 4463 |
accelerator keystroke; it does not itself create the binding. |
| 4464 |
|
| 4465 |
*underline* |
| 4466 |
The index of a character in the label to underline for keyboard |
| 4467 |
traversal. |
| 4468 |
|
| 4469 |
*state* |
| 4470 |
One of ``'normal'``, ``'active'`` or ``'disabled'``. |
| 4471 |
|
| 4472 |
*image* |
| 4473 |
An image to display instead of, or together with, the text label. |
| 4474 |
|
| 4475 |
*compound* |
| 4476 |
Where to show the image relative to the text: ``'none'`` (the |
| 4477 |
default), ``'text'``, ``'image'``, ``'top'``, ``'bottom'``, ``'left'`` |
| 4478 |
or ``'right'``. |
| 4479 |
|
| 4480 |
*bitmap* |
| 4481 |
A bitmap to display instead of the text label. |
| 4482 |
|
| 4483 |
*font* |
| 4484 |
The font to use for the text. |
| 4485 |
|
| 4486 |
*background*, *foreground* |
| 4487 |
The entry's background and foreground colors in its normal state |
| 4488 |
(ignored on macOS). |
| 4489 |
|
| 4490 |
*activebackground*, *activeforeground* |
| 4491 |
The background and foreground colors used when the entry is active |
| 4492 |
(ignored on macOS). |
| 4493 |
|
| 4494 |
*columnbreak* |
| 4495 |
If true, the entry starts a new column instead of being placed below |
| 4496 |
the previous entry. |
| 4497 |
|
| 4498 |
*hidemargin* |
| 4499 |
If true, the standard margin around the entry is omitted, which is |
| 4500 |
useful when a menu is used as a palette. |
| 4501 |
|
| 4502 |
*menu* |
| 4503 |
The submenu posted by a cascade entry; it must be a child of this |
| 4504 |
menu. |
| 4505 |
|
| 4506 |
*variable* |
| 4507 |
The variable associated with a checkbutton or radiobutton entry. |
| 4508 |
|
| 4509 |
*onvalue*, *offvalue* |
| 4510 |
The values stored in *variable* when a checkbutton entry is selected |
| 4511 |
or cleared. |
| 4512 |
|
| 4513 |
*value* |
| 4514 |
The value stored in *variable* when a radiobutton entry is selected. |
| 4515 |
|
| 4516 |
*indicatoron* |
| 4517 |
Whether to display the indicator of a checkbutton or radiobutton |
| 4518 |
entry. |
| 4519 |
|
| 4520 |
*selectcolor* |
| 4521 |
The color of the indicator of a checkbutton or radiobutton entry when |
| 4522 |
it is selected. |
| 4523 |
|
| 4524 |
*selectimage* |
| 4525 |
The image displayed when a checkbutton or radiobutton entry is |
| 4526 |
selected and *image* is also given. |
| 4527 |
|
| 4528 |
.. method:: add_cascade(cnf={}, **kw) |
| 4529 |
|
| 4530 |
Add a new cascade entry to the bottom of the menu. |
| 4531 |
A cascade entry has an associated submenu, given by its *menu* option, |
| 4532 |
which must be a child of this menu; posting the entry posts the submenu |
| 4533 |
next to it. |
| 4534 |
|
| 4535 |
.. method:: add_checkbutton(cnf={}, **kw) |
| 4536 |
|
| 4537 |
Add a new checkbutton entry to the bottom of the menu. |
| 4538 |
When invoked, a checkbutton entry toggles between its *onvalue* and |
| 4539 |
*offvalue*, storing the result in its associated *variable*, and displays |
| 4540 |
an indicator showing whether it is selected. |
| 4541 |
|
| 4542 |
.. method:: add_command(cnf={}, **kw) |
| 4543 |
|
| 4544 |
Add a new command entry to the bottom of the menu. |
| 4545 |
A command entry behaves much like a button: when it is invoked, the |
| 4546 |
callback given by its *command* option is called. |
| 4547 |
|
| 4548 |
.. method:: add_radiobutton(cnf={}, **kw) |
| 4549 |
|
| 4550 |
Add a new radiobutton entry to the bottom of the menu. |
| 4551 |
Radiobutton entries sharing the same *variable* form a group of which |
| 4552 |
only one may be selected at a time; selecting an entry stores its *value* |
| 4553 |
in the variable. |
| 4554 |
|
| 4555 |
.. method:: add_separator(cnf={}, **kw) |
| 4556 |
|
| 4557 |
Add a separator to the bottom of the menu. |
| 4558 |
A separator is displayed as a horizontal dividing line and cannot be |
| 4559 |
activated or invoked. |
| 4560 |
|
| 4561 |
.. method:: insert(index, itemType, cnf={}, **kw) |
| 4562 |
|
| 4563 |
Same as :meth:`add`, except that the new entry is inserted just before |
| 4564 |
the entry given by *index* instead of being appended to the end of the |
| 4565 |
menu. |
| 4566 |
*itemType* is one of ``'command'``, ``'cascade'``, ``'checkbutton'``, |
| 4567 |
``'radiobutton'`` or ``'separator'``. |
| 4568 |
The :meth:`!insert_command`, :meth:`!insert_cascade`, |
| 4569 |
:meth:`!insert_checkbutton`, :meth:`!insert_radiobutton` and |
| 4570 |
:meth:`!insert_separator` convenience methods call this method with the |
| 4571 |
corresponding *itemType*. |
| 4572 |
|
| 4573 |
.. method:: insert_cascade(index, cnf={}, **kw) |
| 4574 |
|
| 4575 |
Insert a new cascade entry before the entry given by *index* (see |
| 4576 |
:meth:`add_cascade`). |
| 4577 |
|
| 4578 |
.. method:: insert_checkbutton(index, cnf={}, **kw) |
| 4579 |
|
| 4580 |
Insert a new checkbutton entry before the entry given by *index* (see |
| 4581 |
:meth:`add_checkbutton`). |
| 4582 |
|
| 4583 |
.. method:: insert_command(index, cnf={}, **kw) |
| 4584 |
|
| 4585 |
Insert a new command entry before the entry given by *index* (see |
| 4586 |
:meth:`add_command`). |
| 4587 |
|
| 4588 |
.. method:: insert_radiobutton(index, cnf={}, **kw) |
| 4589 |
|
| 4590 |
Insert a new radiobutton entry before the entry given by *index* (see |
| 4591 |
:meth:`add_radiobutton`). |
| 4592 |
|
| 4593 |
.. method:: insert_separator(index, cnf={}, **kw) |
| 4594 |
|
| 4595 |
Insert a separator before the entry given by *index* (see |
| 4596 |
:meth:`add_separator`). |
| 4597 |
|
| 4598 |
.. method:: delete(index1, index2=None) |
| 4599 |
|
| 4600 |
Delete all of the menu entries between *index1* and *index2* inclusive. |
| 4601 |
If *index2* is omitted, it defaults to *index1*, so that a single entry |
| 4602 |
is deleted. |
| 4603 |
Attempts to delete a tear-off entry are ignored; remove it by changing |
| 4604 |
the *tearoff* option instead. |
| 4605 |
|
| 4606 |
.. method:: entrycget(index, option) |
| 4607 |
|
| 4608 |
Return the current value of the configuration option *option* for the |
| 4609 |
entry given by *index*. |
| 4610 |
|
| 4611 |
.. method:: entryconfig(index, cnf=None, **kw) |
| 4612 |
:no-typesetting: |
| 4613 |
|
| 4614 |
.. method:: entryconfigure(index, cnf=None, **kw) |
| 4615 |
|
| 4616 |
Query or modify the configuration options of the entry given by *index*. |
| 4617 |
This mirrors :meth:`~Misc.configure`, except that it applies to an |
| 4618 |
individual entry rather than to the menu as a whole. |
| 4619 |
With no options, it returns a dictionary describing the current options |
| 4620 |
of the entry; otherwise it sets the given options. |
| 4621 |
The supported options are those accepted by :meth:`add` for the entry's |
| 4622 |
type. |
| 4623 |
:meth:`entryconfig` is an alias of :meth:`!entryconfigure`. |
| 4624 |
|
| 4625 |
.. method:: index(index) |
| 4626 |
|
| 4627 |
Return the numerical index corresponding to *index*, or ``None`` if |
| 4628 |
*index* selects no entry. |
| 4629 |
|
| 4630 |
.. method:: type(index) |
| 4631 |
|
| 4632 |
Return the type of the entry given by *index*: one of ``'command'``, |
| 4633 |
``'cascade'``, ``'checkbutton'``, ``'radiobutton'``, ``'separator'`` or |
| 4634 |
``'tearoff'`` (for the tear-off entry). |
| 4635 |
|
| 4636 |
.. method:: activate(index) |
| 4637 |
|
| 4638 |
Make the entry given by *index* the active entry, redisplaying it with |
| 4639 |
its active colors, and deactivate any previously active entry. |
| 4640 |
If *index* selects no entry, or the selected entry is disabled, the menu |
| 4641 |
ends up with no active entry. |
| 4642 |
|
| 4643 |
.. method:: invoke(index) |
| 4644 |
|
| 4645 |
Invoke the action of the entry given by *index*, as if it had been |
| 4646 |
clicked. |
| 4647 |
Nothing happens if the entry is disabled. |
| 4648 |
If the entry has a *command* associated with it, the result of that |
| 4649 |
command is returned; otherwise the result is an empty string. |
| 4650 |
|
| 4651 |
.. method:: post(x, y) |
| 4652 |
|
| 4653 |
Display the menu on the screen at the root-window coordinates *x* and |
| 4654 |
*y*, adjusting them if necessary so that the whole menu is visible. |
| 4655 |
If the *postcommand* option has been specified, it is evaluated before |
| 4656 |
the menu is posted. |
| 4657 |
|
| 4658 |
.. method:: tk_popup(x, y, entry='') |
| 4659 |
|
| 4660 |
Post the menu as a popup at the root-window coordinates *x* and *y*. |
| 4661 |
If *entry* is given, the menu is positioned so that this entry is |
| 4662 |
displayed under the pointer. |
| 4663 |
|
| 4664 |
.. method:: unpost() |
| 4665 |
|
| 4666 |
Unmap the menu so that it is no longer displayed, also unposting any |
| 4667 |
posted lower-level cascaded submenu. |
| 4668 |
This has no effect on Windows and macOS, which manage the unposting of |
| 4669 |
menus themselves. |
| 4670 |
|
| 4671 |
.. method:: xposition(index) |
| 4672 |
|
| 4673 |
Return the x-coordinate, within the menu window, of the leftmost pixel of |
| 4674 |
the entry given by *index*. |
| 4675 |
|
| 4676 |
.. versionadded:: 3.3 |
| 4677 |
|
| 4678 |
.. method:: yposition(index) |
| 4679 |
|
| 4680 |
Return the y-coordinate, within the menu window, of the topmost pixel of |
| 4681 |
the entry given by *index*. |
| 4682 |
|
| 4683 |
|
| 4684 |
.. class:: Menubutton(master=None, cnf={}, **kw) |
| 4685 |
|
| 4686 |
A :class:`!Menubutton` widget displays a textual string, bitmap or image and |
| 4687 |
posts an associated :class:`Menu`, given by its *menu* option, when the user |
| 4688 |
presses it. |
| 4689 |
Like a :class:`Label` it can show *text*, a *textvariable*, or an *image*, |
| 4690 |
and the *direction* option controls where the menu appears relative to the |
| 4691 |
button. |
| 4692 |
Inherits from :class:`Widget`. |
| 4693 |
Refer to the Tk ``menubutton`` manual page for the full list of options. |
| 4694 |
|
| 4695 |
|
| 4696 |
.. class:: Message(master=None, cnf={}, **kw) |
| 4697 |
|
| 4698 |
A :class:`!Message` widget displays a non-interactive textual string, given |
| 4699 |
by the *text* option or linked to a variable through *textvariable*. |
| 4700 |
Unlike a :class:`Label`, it breaks the string into multiple lines in order |
| 4701 |
to produce a given aspect ratio, choosing line breaks at word boundaries, |
| 4702 |
and it can justify the text left, centered or right. |
| 4703 |
Inherits from :class:`Widget`. |
| 4704 |
Refer to the Tk ``message`` manual page for the full list of options. |
| 4705 |
|
| 4706 |
|
| 4707 |
.. class:: OptionMenu(master, variable, value, *values, **kwargs) |
| 4708 |
|
| 4709 |
A helper subclass of :class:`Menubutton` that displays a pop-up menu of |
| 4710 |
mutually exclusive choices. |
| 4711 |
*variable* is a :class:`Variable` kept in sync with the selection, *value* |
| 4712 |
is the initial choice, and *values* are the remaining menu entries. |
| 4713 |
The keyword argument *command* may be given a callback that is invoked with |
| 4714 |
the selected value. |
| 4715 |
|
| 4716 |
.. method:: destroy() |
| 4717 |
|
| 4718 |
Destroy the widget, also cleaning up the associated pop-up menu. |
| 4719 |
|
| 4720 |
|
| 4721 |
|
| 4722 |
.. class:: PanedWindow(master=None, cnf={}, **kw) |
| 4723 |
|
| 4724 |
A :class:`!PanedWindow` is a geometry-manager widget that arranges any |
| 4725 |
number of child *panes* in a row (when *orient* is ``'horizontal'``) or a |
| 4726 |
column (when *orient* is ``'vertical'``). |
| 4727 |
Each pane holds one widget, and each pair of adjacent panes is separated by |
| 4728 |
a movable *sash* that the user can drag with the mouse to resize the widgets |
| 4729 |
on either side of it. |
| 4730 |
Inherits from :class:`Widget`. |
| 4731 |
|
| 4732 |
The *orient* option selects the layout direction, *sashwidth* sets the width |
| 4733 |
of each sash and *sashrelief* its relief. |
| 4734 |
When *showhandle* is true a small handle is drawn on each sash that the user |
| 4735 |
can grab to drag it. |
| 4736 |
Refer to the Tk ``panedwindow`` manual page for the full list of options. |
| 4737 |
|
| 4738 |
.. method:: add(child, **kw) |
| 4739 |
|
| 4740 |
Add *child* to the panedwindow as a new pane, placed after any existing |
| 4741 |
panes. |
| 4742 |
The keyword arguments specify per-pane management options for *child*; |
| 4743 |
they may be any of the options accepted by :meth:`paneconfigure`. |
| 4744 |
|
| 4745 |
.. method:: forget(child) |
| 4746 |
:no-typesetting: |
| 4747 |
|
| 4748 |
.. method:: remove(child) |
| 4749 |
|
| 4750 |
Remove the pane containing *child* from the panedwindow. |
| 4751 |
All geometry management options for *child* are forgotten. |
| 4752 |
:meth:`forget` is an alias of :meth:`!remove`. |
| 4753 |
This shadows the inherited geometry-manager :meth:`!forget`; |
| 4754 |
use :meth:`~Pack.pack_forget`, :meth:`~Grid.grid_forget` or |
| 4755 |
:meth:`~Place.place_forget` to remove the widget itself from its manager. |
| 4756 |
|
| 4757 |
.. method:: panes() |
| 4758 |
|
| 4759 |
Return a tuple of the widgets managed by the panedwindow, one per pane, |
| 4760 |
in order. |
| 4761 |
|
| 4762 |
.. method:: panecget(child, option) |
| 4763 |
|
| 4764 |
Return the current value of the management option *option* for the pane |
| 4765 |
containing *child*. |
| 4766 |
*option* may be any value allowed by :meth:`paneconfigure`. |
| 4767 |
|
| 4768 |
.. method:: paneconfig(tagOrId, cnf=None, **kw) |
| 4769 |
:no-typesetting: |
| 4770 |
|
| 4771 |
.. method:: paneconfigure(tagOrId, cnf=None, **kw) |
| 4772 |
|
| 4773 |
Query or modify the management options of the pane containing the widget |
| 4774 |
*tagOrId*. |
| 4775 |
With no options, it returns a dictionary describing all of the available |
| 4776 |
options for the pane; given a single option name as a string, it returns |
| 4777 |
a description of that one option; otherwise it sets the given options. |
| 4778 |
The supported options include *after* and *before* (insert the pane after |
| 4779 |
or before another managed window), *height* and *width* (the outer |
| 4780 |
dimensions of the window, including any border), *minsize* (the minimum |
| 4781 |
size in the paned dimension), *padx* and *pady* (extra space to leave on |
| 4782 |
each side of the window), *sticky* (position or stretch the window within |
| 4783 |
an oversized pane, using a string of the characters ``n``, ``s``, ``e`` |
| 4784 |
and ``w``), *hide* (hide the pane while keeping it in the list of panes) |
| 4785 |
and *stretch* (how extra space is allocated to the pane: one of |
| 4786 |
``'always'``, ``'first'``, ``'last'``, ``'middle'`` or ``'never'``). |
| 4787 |
:meth:`paneconfig` is an alias of :meth:`!paneconfigure`. |
| 4788 |
|
| 4789 |
.. method:: identify(x, y) |
| 4790 |
|
| 4791 |
Identify the panedwindow component underneath the point given by *x* and |
| 4792 |
*y*, in window coordinates. |
| 4793 |
If the point is over a sash or a sash handle, the result is a two-element |
| 4794 |
tuple containing the index of the sash or handle and a word indicating |
| 4795 |
whether it is over a sash or a handle, such as ``(0, 'sash')`` or |
| 4796 |
``(2, 'handle')``. |
| 4797 |
If the point is over any other part of the panedwindow, the result is an |
| 4798 |
empty string. |
| 4799 |
|
| 4800 |
.. method:: sash(*args) |
| 4801 |
|
| 4802 |
Query or change the position of the sashes in the panedwindow. |
| 4803 |
This is a thin wrapper around the Tk ``sash`` subcommand; the convenience |
| 4804 |
methods :meth:`sash_coord`, :meth:`sash_mark` and :meth:`sash_place` |
| 4805 |
should normally be used instead. |
| 4806 |
|
| 4807 |
.. method:: sash_coord(index) |
| 4808 |
|
| 4809 |
Return the current x and y coordinate pair for the sash given by *index*, |
| 4810 |
which must be an integer between 0 and one less than the number of panes |
| 4811 |
in the panedwindow. |
| 4812 |
The coordinates returned are those of the top left corner of the region |
| 4813 |
containing the sash. |
| 4814 |
|
| 4815 |
.. method:: sash_mark(index) |
| 4816 |
|
| 4817 |
Record the current mouse position for the sash given by *index*, for use |
| 4818 |
together with later sash-drag operations to move the sash. |
| 4819 |
|
| 4820 |
.. method:: sash_place(index, x, y) |
| 4821 |
|
| 4822 |
Place the sash given by *index* at the coordinates *x* and *y*. |
| 4823 |
|
| 4824 |
.. method:: proxy(*args) |
| 4825 |
|
| 4826 |
Query or change the position of the sash proxy, the "ghost" sash shown |
| 4827 |
while a sash is being dragged with non-opaque resizing. |
| 4828 |
This is a thin wrapper around the Tk ``proxy`` subcommand; the |
| 4829 |
convenience methods :meth:`proxy_coord`, :meth:`proxy_forget` and |
| 4830 |
:meth:`proxy_place` should normally be used instead. |
| 4831 |
|
| 4832 |
.. method:: proxy_coord() |
| 4833 |
|
| 4834 |
Return a tuple containing the x and y coordinates of the most recent |
| 4835 |
proxy location. |
| 4836 |
|
| 4837 |
.. method:: proxy_forget() |
| 4838 |
|
| 4839 |
Remove the proxy from the display. |
| 4840 |
|
| 4841 |
.. method:: proxy_place(x, y) |
| 4842 |
|
| 4843 |
Place the proxy at the coordinates *x* and *y*. |
| 4844 |
|
| 4845 |
|
| 4846 |
.. class:: Radiobutton(master=None, cnf={}, **kw) |
| 4847 |
|
| 4848 |
A :class:`!Radiobutton` widget displays a textual string, bitmap or image |
| 4849 |
together with a diamond or circular indicator, and selects one choice out of |
| 4850 |
several. |
| 4851 |
It has all the behavior of a simple button and, in addition, can be |
| 4852 |
selected: typically several radiobuttons share a single *variable*, and |
| 4853 |
selecting one sets that variable to the radiobutton's *value*; each |
| 4854 |
radiobutton also monitors the variable and automatically selects or |
| 4855 |
deselects itself when the variable changes. |
| 4856 |
Inherits from :class:`Widget`. |
| 4857 |
In addition to the standard widget options, a radiobutton accepts the |
| 4858 |
options documented in the Tk ``radiobutton`` manual page, such as |
| 4859 |
*variable*, *value* and *command*. |
| 4860 |
|
| 4861 |
.. method:: invoke() |
| 4862 |
|
| 4863 |
Do just what would happen if the user pressed the radiobutton with the |
| 4864 |
mouse: select the button and invoke the associated command, if there is |
| 4865 |
one. |
| 4866 |
Return the result of the command, or an empty string if no command is |
| 4867 |
associated with the radiobutton. |
| 4868 |
This is ignored if the radiobutton's state is ``disabled``. |
| 4869 |
|
| 4870 |
.. method:: select() |
| 4871 |
|
| 4872 |
Select the radiobutton and set the associated variable to the value |
| 4873 |
corresponding to this widget. |
| 4874 |
|
| 4875 |
.. method:: deselect() |
| 4876 |
|
| 4877 |
Deselect the radiobutton and set the associated variable to an empty |
| 4878 |
string. |
| 4879 |
If this radiobutton was not currently selected, this has no effect. |
| 4880 |
|
| 4881 |
.. method:: flash() |
| 4882 |
|
| 4883 |
Flash the radiobutton by redisplaying it several times, alternating |
| 4884 |
between the active and normal colors. |
| 4885 |
At the end of the flash the radiobutton is left in the same normal or |
| 4886 |
active state as when the method was called. |
| 4887 |
This is ignored if the radiobutton's state is ``disabled``. |
| 4888 |
|
| 4889 |
|
| 4890 |
.. class:: Scale(master=None, cnf={}, **kw) |
| 4891 |
|
| 4892 |
A :class:`!Scale` widget lets the user select a numerical value by moving a |
| 4893 |
slider along a trough. |
| 4894 |
It can be oriented vertically or horizontally and can optionally display a |
| 4895 |
label and the current value. |
| 4896 |
Inherits from :class:`Widget`. |
| 4897 |
|
| 4898 |
In addition to the standard widget options, a scale accepts the options |
| 4899 |
documented in the Tk ``scale`` manual page, such as *from_*, *to*, |
| 4900 |
*resolution*, *orient*, *tickinterval*, *variable* and *command*. |
| 4901 |
As elsewhere in :mod:`!tkinter`, the leading ``-`` of the Tk option name is |
| 4902 |
dropped; *from* is spelled ``from_`` because :keyword:`from` is a Python |
| 4903 |
keyword. |
| 4904 |
|
| 4905 |
With a non-integer *resolution*, see :ref:`numeric values and the locale |
| 4906 |
<tkinter-numeric-locale>`. |
| 4907 |
|
| 4908 |
.. method:: get() |
| 4909 |
|
| 4910 |
Return the current value of the scale. |
| 4911 |
The result is an integer if the scale's *resolution* yields whole |
| 4912 |
numbers, and a float otherwise. |
| 4913 |
|
| 4914 |
.. method:: set(value) |
| 4915 |
|
| 4916 |
Set the scale to *value*, moving the slider accordingly. |
| 4917 |
This has no effect if the scale is disabled. |
| 4918 |
|
| 4919 |
.. method:: coords(value=None) |
| 4920 |
|
| 4921 |
Return a tuple ``(x, y)`` giving the pixel coordinates, relative to the |
| 4922 |
widget, of the point on the centerline of the trough that corresponds to |
| 4923 |
*value*. |
| 4924 |
If *value* is omitted, the scale's current value is used. |
| 4925 |
|
| 4926 |
.. method:: identify(x, y) |
| 4927 |
|
| 4928 |
Return a string describing the part of the scale at the pixel coordinates |
| 4929 |
*x*, *y*: ``'slider'``, ``'trough1'`` (the part of the trough above or to |
| 4930 |
the left of the slider), ``'trough2'`` (below or to the right of the |
| 4931 |
slider), or an empty string if the point is not over any of these |
| 4932 |
elements. |
| 4933 |
|
| 4934 |
|
| 4935 |
.. class:: Scrollbar(master=None, cnf={}, **kw) |
| 4936 |
|
| 4937 |
A :class:`!Scrollbar` widget displays a slider and two arrows that let the |
| 4938 |
user scroll an associated widget, such as a :class:`Listbox`, :class:`Text`, |
| 4939 |
:class:`Canvas` or :class:`Entry`. |
| 4940 |
It is connected to the scrolled widget by setting that widget's |
| 4941 |
*xscrollcommand* or *yscrollcommand* option to the scrollbar's :meth:`set` |
| 4942 |
method, and the scrollbar's *command* option to the scrolled widget's |
| 4943 |
:meth:`~XView.xview` or :meth:`~YView.yview` method. |
| 4944 |
Inherits from :class:`Widget`. |
| 4945 |
|
| 4946 |
.. method:: get() |
| 4947 |
|
| 4948 |
Return the current scrollbar settings as a tuple ``(first, last)`` of two |
| 4949 |
fractions between 0 and 1, describing the portion of the document that is |
| 4950 |
currently visible, as last passed to :meth:`set`. |
| 4951 |
|
| 4952 |
.. method:: set(first, last) |
| 4953 |
|
| 4954 |
Set the scrollbar. |
| 4955 |
*first* and *last* are fractions between 0 and 1 giving the positions of |
| 4956 |
the start and end of the visible portion of the associated document. |
| 4957 |
This method is normally registered as the scrolled widget's |
| 4958 |
*xscrollcommand* or *yscrollcommand* and called by that widget. |
| 4959 |
|
| 4960 |
.. method:: activate(index=None) |
| 4961 |
|
| 4962 |
Mark the element *index* (one of ``'arrow1'``, ``'slider'`` or |
| 4963 |
``'arrow2'``) as active, displaying it according to the |
| 4964 |
*activebackground* and *activerelief* options. |
| 4965 |
If *index* is omitted, return the name of the currently active element, |
| 4966 |
or ``None`` if no element is active. |
| 4967 |
|
| 4968 |
.. versionchanged:: 3.5 |
| 4969 |
The *index* argument is now optional. |
| 4970 |
|
| 4971 |
.. method:: delta(deltax, deltay) |
| 4972 |
|
| 4973 |
Return a float indicating the fractional change in the scrollbar setting |
| 4974 |
that corresponds to moving the slider by *deltax* pixels horizontally |
| 4975 |
(for horizontal scrollbars) or *deltay* pixels vertically (for vertical |
| 4976 |
scrollbars). |
| 4977 |
|
| 4978 |
.. method:: fraction(x, y) |
| 4979 |
|
| 4980 |
Return a float between 0 and 1 indicating where the point at pixel |
| 4981 |
coordinates *x*, *y* lies in the trough: 0 corresponds to the top or left |
| 4982 |
of the trough and 1 to the bottom or right. |
| 4983 |
|
| 4984 |
.. method:: identify(x, y) |
| 4985 |
|
| 4986 |
Return the name of the element under the pixel coordinates *x*, *y* (such |
| 4987 |
as ``'arrow1'``), or an empty string if the point does not lie in any |
| 4988 |
element of the scrollbar. |
| 4989 |
|
| 4990 |
|
| 4991 |
.. class:: Spinbox(master=None, cnf={}, **kw) |
| 4992 |
|
| 4993 |
A :class:`!Spinbox` widget is an :class:`Entry`-like widget with a pair of |
| 4994 |
up/down arrow buttons that let the user step through a range of values in |
| 4995 |
addition to editing the value directly. |
| 4996 |
The set of values may be a numeric range given by the *from_*, *to* and |
| 4997 |
*increment* options, or an explicit list of strings given by the *values* |
| 4998 |
option (which takes precedence over the range). |
| 4999 |
Each time an arrow is invoked the *command* callback, if any, is called; the |
| 5000 |
*wrap* option controls whether stepping past either end of the range wraps |
| 5001 |
around to the other end; the *format* option specifies how numeric values |
| 5002 |
are formatted; and the *validate* option enables validation of the entered |
| 5003 |
text. |
| 5004 |
Inherits from :class:`Widget` and :class:`XView`. |
| 5005 |
|
| 5006 |
With a non-integer *increment*, see :ref:`numeric values and the locale |
| 5007 |
<tkinter-numeric-locale>`. |
| 5008 |
|
| 5009 |
Many of the methods take an *index* argument identifying a character in the |
| 5010 |
spinbox's string. |
| 5011 |
As described in the Tk ``spinbox`` manual page, *index* may be a numeric |
| 5012 |
index (counting from 0), ``'anchor'`` (the selection anchor point), |
| 5013 |
``'end'`` (just after the last character), ``'insert'`` (the character just |
| 5014 |
after the insertion cursor), ``'sel.first'`` or ``'sel.last'`` (the ends of |
| 5015 |
the selection), or ``@x`` (the character covering pixel x-coordinate *x* in |
| 5016 |
the window). |
| 5017 |
|
| 5018 |
.. method:: get() |
| 5019 |
|
| 5020 |
Return the spinbox's string. |
| 5021 |
|
| 5022 |
.. method:: insert(index, s) |
| 5023 |
|
| 5024 |
Insert the characters of the string *s* just before the character given |
| 5025 |
by *index*. |
| 5026 |
|
| 5027 |
.. method:: delete(first, last=None) |
| 5028 |
|
| 5029 |
Delete one or more characters of the spinbox. |
| 5030 |
*first* is the index of the first character to delete, and *last* is the |
| 5031 |
index of the character just after the last one to delete. |
| 5032 |
If *last* is omitted, a single character at *first* is deleted. |
| 5033 |
|
| 5034 |
.. method:: icursor(index) |
| 5035 |
|
| 5036 |
Arrange for the insertion cursor to be displayed just before the |
| 5037 |
character given by *index*. |
| 5038 |
|
| 5039 |
.. method:: index(index) |
| 5040 |
|
| 5041 |
Return the numerical index corresponding to *index*, as a string. |
| 5042 |
|
| 5043 |
.. method:: bbox(index) |
| 5044 |
|
| 5045 |
Return a tuple of four integers ``(x, y, width, height)`` describing the |
| 5046 |
bounding box of the character given by *index*. |
| 5047 |
*x* and *y* are the pixel coordinates of the upper-left corner of the |
| 5048 |
character relative to the widget, and *width* and *height* are its size |
| 5049 |
in pixels. |
| 5050 |
The bounding box may refer to a region outside the visible area of the |
| 5051 |
window. |
| 5052 |
|
| 5053 |
This shadows the inherited :meth:`!Misc.bbox`; |
| 5054 |
use :meth:`~Misc.grid_bbox` for the grid bounding box. |
| 5055 |
|
| 5056 |
.. method:: identify(x, y) |
| 5057 |
|
| 5058 |
Return the name of the window element at the pixel coordinates *x*, *y*: |
| 5059 |
one of ``'buttondown'``, ``'buttonup'``, ``'entry'`` or ``'none'``. |
| 5060 |
|
| 5061 |
.. method:: invoke(element) |
| 5062 |
|
| 5063 |
Invoke the spin button given by *element*, either ``'buttonup'`` or |
| 5064 |
``'buttondown'``, triggering the action associated with it. |
| 5065 |
|
| 5066 |
.. method:: scan(*args) |
| 5067 |
|
| 5068 |
A thin wrapper around the Tk ``scan`` widget subcommand, used to |
| 5069 |
implement fast dragging of the view: ``scan('mark', x)`` records *x* and |
| 5070 |
the current view, and ``scan('dragto', x)`` adjusts the view relative to |
| 5071 |
that mark. |
| 5072 |
The :meth:`scan_mark` and :meth:`scan_dragto` methods wrap the two forms. |
| 5073 |
|
| 5074 |
.. method:: scan_mark(x) |
| 5075 |
|
| 5076 |
Record *x* and the current view in the spinbox window, for use with a |
| 5077 |
later :meth:`scan_dragto` call. |
| 5078 |
This is typically associated with a mouse button press in the widget. |
| 5079 |
|
| 5080 |
.. method:: scan_dragto(x) |
| 5081 |
|
| 5082 |
Adjust the view by 10 times the difference between *x* and the *x* passed |
| 5083 |
to the last :meth:`scan_mark` call. |
| 5084 |
This is typically associated with mouse motion events, producing the |
| 5085 |
effect of dragging the spinbox at high speed through the window. |
| 5086 |
|
| 5087 |
.. method:: selection(*args) |
| 5088 |
|
| 5089 |
A thin wrapper around the Tk ``selection`` widget subcommand, used to |
| 5090 |
adjust the selection within the spinbox. |
| 5091 |
It has several forms depending on the first argument, such as |
| 5092 |
``selection('adjust', index)``, ``selection('clear')``, |
| 5093 |
``selection('element', ?elem?)``, ``selection('from', index)``, |
| 5094 |
``selection('present')``, ``selection('range', start, end)`` and |
| 5095 |
``selection('to', index)``. |
| 5096 |
The :meth:`selection_adjust`, :meth:`selection_clear`, |
| 5097 |
:meth:`selection_element`, :meth:`selection_from`, |
| 5098 |
:meth:`selection_present`, :meth:`selection_range` and |
| 5099 |
:meth:`selection_to` methods wrap these forms. |
| 5100 |
|
| 5101 |
.. method:: selection_adjust(index) |
| 5102 |
|
| 5103 |
Locate the end of the selection nearest to the character given by *index* |
| 5104 |
and adjust that end of the selection to be at *index* (including but not |
| 5105 |
going beyond *index*). |
| 5106 |
The other end becomes the anchor point for future :meth:`selection_to` |
| 5107 |
calls. |
| 5108 |
If the selection is not currently in the spinbox, a new selection is |
| 5109 |
created to include the characters between *index* and the most recent |
| 5110 |
anchor point, inclusive. |
| 5111 |
|
| 5112 |
.. method:: selection_clear() |
| 5113 |
|
| 5114 |
Clear the selection if it is currently in this widget. |
| 5115 |
If the selection is not in this widget, the method has no effect. |
| 5116 |
|
| 5117 |
.. note:: |
| 5118 |
|
| 5119 |
This shadows the inherited :meth:`Misc.selection_clear`, |
| 5120 |
which clears the X selection; |
| 5121 |
that method is not available on a :class:`Spinbox`. |
| 5122 |
|
| 5123 |
.. method:: selection_element(element=None) |
| 5124 |
|
| 5125 |
Set or get the currently selected element. |
| 5126 |
If *element* (one of ``'buttonup'``, ``'buttondown'`` or ``'none'``) is |
| 5127 |
given, that spin button is selected and displayed depressed; otherwise |
| 5128 |
the name of the currently selected element is returned. |
| 5129 |
|
| 5130 |
.. method:: selection_from(index) |
| 5131 |
|
| 5132 |
Set the selection anchor point to just before the character given by |
| 5133 |
*index*, without changing the selection itself. |
| 5134 |
|
| 5135 |
.. versionadded:: 3.8 |
| 5136 |
|
| 5137 |
|
| 5138 |
.. method:: selection_present() |
| 5139 |
|
| 5140 |
Return ``True`` if there are characters selected in the spinbox, |
| 5141 |
``False`` otherwise. |
| 5142 |
|
| 5143 |
.. versionadded:: 3.8 |
| 5144 |
|
| 5145 |
|
| 5146 |
.. method:: selection_range(start, end) |
| 5147 |
|
| 5148 |
Set the selection to include the characters starting with the one indexed |
| 5149 |
by *start* and ending with the one just before *end*. |
| 5150 |
If *end* refers to the same character as *start* or an earlier one, the |
| 5151 |
selection is cleared. |
| 5152 |
|
| 5153 |
.. versionadded:: 3.8 |
| 5154 |
|
| 5155 |
|
| 5156 |
.. method:: selection_to(index) |
| 5157 |
|
| 5158 |
Set the selection between *index* and the anchor point. |
| 5159 |
If *index* is before the anchor point, the selection runs from *index* up |
| 5160 |
to but not including the anchor point; if it is after, the selection runs |
| 5161 |
from the anchor point up to but not including *index*; if it is the same, |
| 5162 |
nothing happens. |
| 5163 |
The anchor point is the one set by the most recent :meth:`selection_from` |
| 5164 |
or :meth:`selection_adjust` call. |
| 5165 |
If the selection is not in this widget, a new selection is created using |
| 5166 |
the most recent anchor point. |
| 5167 |
|
| 5168 |
.. versionadded:: 3.8 |
| 5169 |
|
| 5170 |
|
| 5171 |
|
| 5172 |
.. class:: Text(master=None, cnf={}, **kw) |
| 5173 |
|
| 5174 |
A :class:`!Text` widget displays and edits multi-line text. |
| 5175 |
Portions of the text may be styled with **tags**, particular positions may |
| 5176 |
be annotated with floating **marks**, and arbitrary images and other widgets |
| 5177 |
may be embedded in the text. |
| 5178 |
The widget also provides an unlimited undo/redo mechanism and supports peer |
| 5179 |
widgets that share the same underlying data. |
| 5180 |
Inherits from :class:`Widget`, :class:`XView` and :class:`YView`, so the |
| 5181 |
view can be scrolled horizontally and vertically with :meth:`~XView.xview` |
| 5182 |
and :meth:`~YView.yview`. |
| 5183 |
Refer to the Tk ``text`` manual page for the full list of options. |
| 5184 |
|
| 5185 |
Most of the methods take one or more *index* arguments that identify a |
| 5186 |
position within the text. |
| 5187 |
As described in the Tk ``text`` manual page, an index is a string consisting |
| 5188 |
of a base, optionally followed by one or more modifiers. |
| 5189 |
The base may be ``'line.char'`` (line *line*, character *char*, where lines |
| 5190 |
are counted from 1 and characters within a line from 0; ``'line.end'`` |
| 5191 |
refers to the newline ending the line), ``'end'`` (the position just after |
| 5192 |
the last newline), the name of a mark, ``'tag.first'`` or ``'tag.last'`` |
| 5193 |
(the first character tagged with *tag*, or the position just after the last |
| 5194 |
such character), the name of an embedded image or window, or ``@x,y`` (the |
| 5195 |
character covering pixel coordinates *x*, *y* in the widget). |
| 5196 |
A modifier such as ``'+5 chars'``, ``'-3 lines'``, ``'linestart'``, |
| 5197 |
``'lineend'``, ``'wordstart'`` or ``'wordend'`` adjusts the index relative |
| 5198 |
to its base; several modifiers may be combined and are applied from left to |
| 5199 |
right, for example ``'insert wordstart - 1 c'``. |
| 5200 |
|
| 5201 |
.. method:: insert(index, chars, *args) |
| 5202 |
|
| 5203 |
Insert the string *chars* just before the character at *index* (if |
| 5204 |
*index* is ``'end'``, just before the final newline). |
| 5205 |
By default the new text inherits any tags present on both sides of the |
| 5206 |
insertion point. |
| 5207 |
If *args* is given, it consists of alternating *tagList*, *chars* values: |
| 5208 |
the preceding *chars* receives exactly the tags listed (a tag list may be |
| 5209 |
a single tag name or a sequence of names), overriding the surrounding |
| 5210 |
tags. |
| 5211 |
|
| 5212 |
.. method:: delete(index1, index2=None) |
| 5213 |
|
| 5214 |
Delete the range of characters from *index1* up to but not including |
| 5215 |
*index2*. |
| 5216 |
If *index2* is omitted, the single character at *index1* is deleted. |
| 5217 |
The widget always keeps a newline as its last character, so a deletion |
| 5218 |
that would remove it is adjusted accordingly. |
| 5219 |
|
| 5220 |
.. method:: replace(index1, index2, chars, *args) |
| 5221 |
|
| 5222 |
Replace the range of characters from *index1* up to but not including |
| 5223 |
*index2* with *chars*. |
| 5224 |
This is equivalent to a :meth:`delete` followed by an :meth:`insert` at |
| 5225 |
*index1*; *args* is interpreted as for :meth:`insert`. |
| 5226 |
|
| 5227 |
.. versionadded:: 3.3 |
| 5228 |
|
| 5229 |
.. method:: get(index1, index2=None) |
| 5230 |
|
| 5231 |
Return the text from *index1* up to but not including *index2* as a |
| 5232 |
string. |
| 5233 |
If *index2* is omitted, return the single character at *index1*. |
| 5234 |
Embedded images and windows are omitted from the result. |
| 5235 |
|
| 5236 |
.. method:: index(index) |
| 5237 |
|
| 5238 |
Return the position corresponding to *index* in the canonical |
| 5239 |
``'line.char'`` form. |
| 5240 |
|
| 5241 |
.. method:: compare(index1, op, index2) |
| 5242 |
|
| 5243 |
Compare the positions of *index1* and *index2* using the relational |
| 5244 |
operator *op*, which must be one of ``'<'``, ``'<='``, ``'=='``, |
| 5245 |
``'>='``, ``'>'`` or ``'!='``, and return the boolean result. |
| 5246 |
|
| 5247 |
.. method:: count(index1, index2, *options, return_ints=False) |
| 5248 |
|
| 5249 |
Count the number of items of the requested kinds between *index1* and |
| 5250 |
*index2*; the count is negative if *index1* is after *index2*. |
| 5251 |
Each of *options* names a kind of item to count: ``'chars'``, |
| 5252 |
``'displaychars'``, ``'displayindices'``, ``'displaylines'``, |
| 5253 |
``'indices'``, ``'lines'``, ``'xpixels'`` or ``'ypixels'`` (the default, |
| 5254 |
used when no option is given, is ``'indices'``). |
| 5255 |
The pseudo-option ``'update'`` forces any out-of-date layout information |
| 5256 |
to be recalculated before the following options are evaluated. |
| 5257 |
When *return_ints* is true and a single counting option is given, return |
| 5258 |
a plain integer; otherwise return a tuple with one integer per counting |
| 5259 |
option (or ``None`` if the result is empty). |
| 5260 |
|
| 5261 |
.. versionadded:: 3.3 |
| 5262 |
|
| 5263 |
.. versionchanged:: 3.13 |
| 5264 |
Added the *return_ints* parameter. |
| 5265 |
|
| 5266 |
|
| 5267 |
.. method:: see(index) |
| 5268 |
|
| 5269 |
Adjust the view so that the character given by *index* is visible. |
| 5270 |
If it is already visible the method has no effect; if it is a short |
| 5271 |
distance out of view the widget scrolls just enough to bring it to the |
| 5272 |
nearest edge, otherwise it scrolls to center *index* in the window. |
| 5273 |
|
| 5274 |
.. method:: bbox(index) |
| 5275 |
|
| 5276 |
Return a tuple ``(x, y, width, height)`` giving the bounding box, in |
| 5277 |
pixels, of the visible part of the character at *index*, or ``None`` if |
| 5278 |
that character is not visible on the screen. |
| 5279 |
|
| 5280 |
This shadows the inherited :meth:`!Misc.bbox`; |
| 5281 |
use :meth:`~Misc.grid_bbox` for the grid bounding box. |
| 5282 |
|
| 5283 |
.. method:: dlineinfo(index) |
| 5284 |
|
| 5285 |
Return a tuple ``(x, y, width, height, baseline)`` describing the display |
| 5286 |
line that contains *index*: the first four values give the bounding box |
| 5287 |
of the line in pixels and *baseline* gives the offset of the baseline |
| 5288 |
measured down from the top of the area. |
| 5289 |
Return ``None`` if that display line is not visible on the screen. |
| 5290 |
|
| 5291 |
.. method:: mark_set(markName, index) |
| 5292 |
|
| 5293 |
Set the mark named *markName* to the position just before the character |
| 5294 |
at *index*, creating the mark if it does not already exist. |
| 5295 |
A mark created this way has right gravity by default. |
| 5296 |
|
| 5297 |
.. method:: mark_unset(*markNames) |
| 5298 |
|
| 5299 |
Remove each of the marks named in *markNames*. |
| 5300 |
The special ``insert`` and ``current`` marks may not be removed. |
| 5301 |
|
| 5302 |
.. method:: mark_names() |
| 5303 |
|
| 5304 |
Return a tuple of the names of all marks currently set in the widget. |
| 5305 |
|
| 5306 |
.. method:: mark_gravity(markName, direction=None) |
| 5307 |
|
| 5308 |
If *direction* is omitted, return the gravity of mark *markName*, either |
| 5309 |
``'left'`` or ``'right'``. |
| 5310 |
Otherwise set its gravity to *direction*. |
| 5311 |
The gravity determines on which side of the mark text inserted at the |
| 5312 |
mark's position appears: a mark with right gravity (the default) stays to |
| 5313 |
the right of such text. |
| 5314 |
|
| 5315 |
.. method:: mark_next(index) |
| 5316 |
|
| 5317 |
Return the name of the first mark at or after *index*, or ``None`` if |
| 5318 |
there is none. |
| 5319 |
When *index* is the name of a mark, the search starts just after that |
| 5320 |
mark. |
| 5321 |
|
| 5322 |
.. method:: mark_previous(index) |
| 5323 |
|
| 5324 |
Return the name of the last mark at or before *index*, or ``None`` if |
| 5325 |
there is none. |
| 5326 |
When *index* is the name of a mark, the search starts just before that |
| 5327 |
mark. |
| 5328 |
|
| 5329 |
.. method:: tag_add(tagName, index1, *args) |
| 5330 |
|
| 5331 |
Add the tag *tagName* to the range of characters from *index1* up to but |
| 5332 |
not including the next index in *args*. |
| 5333 |
Further pairs of indices may follow in *args* to tag additional ranges; a |
| 5334 |
trailing single index tags just the character at that index. |
| 5335 |
|
| 5336 |
.. method:: tag_remove(tagName, index1, index2=None) |
| 5337 |
|
| 5338 |
Remove the tag *tagName* from the characters from *index1* up to but not |
| 5339 |
including *index2* (or from the single character at *index1* if *index2* |
| 5340 |
is omitted). |
| 5341 |
The tag itself continues to exist even if no characters carry it. |
| 5342 |
|
| 5343 |
.. method:: tag_delete(*tagNames) |
| 5344 |
|
| 5345 |
Delete each of the tags named in *tagNames*, removing them from all |
| 5346 |
characters and discarding their options and bindings. |
| 5347 |
|
| 5348 |
.. method:: tag_config(tagName, cnf=None, **kw) |
| 5349 |
:no-typesetting: |
| 5350 |
|
| 5351 |
.. method:: tag_configure(tagName, cnf=None, **kw) |
| 5352 |
|
| 5353 |
Query or modify the configuration options of the tag *tagName*. |
| 5354 |
This mirrors :meth:`~Misc.configure`, except that it applies to a tag |
| 5355 |
rather than to the widget as a whole: with no options it returns a |
| 5356 |
dictionary describing the current options, otherwise it sets the given |
| 5357 |
options. |
| 5358 |
Defining a tag this way also gives it a priority higher than any existing |
| 5359 |
tag. |
| 5360 |
|
| 5361 |
The supported tag options, all controlling the appearance of the tagged |
| 5362 |
text, are: |
| 5363 |
|
| 5364 |
*font* |
| 5365 |
The font to use for the text. |
| 5366 |
|
| 5367 |
*foreground* |
| 5368 |
The color to use for the text. |
| 5369 |
|
| 5370 |
*background* |
| 5371 |
The color to use for the area behind the text. |
| 5372 |
|
| 5373 |
*fgstipple*, *bgstipple* |
| 5374 |
Bitmaps used to stipple the foreground (text) and the background; |
| 5375 |
only well supported on X11. |
| 5376 |
|
| 5377 |
*borderwidth* |
| 5378 |
The width of the border drawn around the text according to *relief* |
| 5379 |
(default ``0``). |
| 5380 |
|
| 5381 |
*relief* |
| 5382 |
The 3-D appearance of the text's border: ``'flat'`` (the default), |
| 5383 |
``'raised'``, ``'sunken'``, ``'ridge'``, ``'groove'`` or ``'solid'``. |
| 5384 |
|
| 5385 |
*offset* |
| 5386 |
How far the text is raised above (or, if negative, lowered below) the |
| 5387 |
baseline, for superscripts and subscripts. |
| 5388 |
|
| 5389 |
*underline* |
| 5390 |
Whether to underline the text. |
| 5391 |
|
| 5392 |
*underlinefg* |
| 5393 |
The color of the underline; it defaults to the text color. |
| 5394 |
|
| 5395 |
*overstrike* |
| 5396 |
Whether to draw a line through the middle of the text. |
| 5397 |
|
| 5398 |
*overstrikefg* |
| 5399 |
The color of the overstrike line; it defaults to the text color. |
| 5400 |
|
| 5401 |
*elide* |
| 5402 |
Whether the text is elided (hidden). |
| 5403 |
|
| 5404 |
*justify* |
| 5405 |
How to justify the first character of a display line: ``'left'`` (the |
| 5406 |
default), ``'right'`` or ``'center'``. |
| 5407 |
|
| 5408 |
*wrap* |
| 5409 |
How to wrap lines that are too long: ``'char'``, ``'word'`` or |
| 5410 |
``'none'``. |
| 5411 |
|
| 5412 |
*lmargin1*, *lmargin2* |
| 5413 |
The indentation, in pixels, of the first display line of a logical |
| 5414 |
line and of the remaining display lines. |
| 5415 |
|
| 5416 |
*lmargincolor* |
| 5417 |
The color of the left margin area. |
| 5418 |
|
| 5419 |
*rmargin* |
| 5420 |
The right-hand margin, in pixels. |
| 5421 |
|
| 5422 |
*rmargincolor* |
| 5423 |
The color of the right margin area. |
| 5424 |
|
| 5425 |
*spacing1*, *spacing2*, *spacing3* |
| 5426 |
Extra space, in pixels, above the first display line of a logical |
| 5427 |
line, between its display lines, and below its last display line. |
| 5428 |
|
| 5429 |
*tabs* |
| 5430 |
The set of tab stops, in the same form as the widget's *tabs* option. |
| 5431 |
|
| 5432 |
*tabstyle* |
| 5433 |
How tab stops are interpreted: ``'tabular'`` or ``'wordprocessor'``. |
| 5434 |
|
| 5435 |
*selectbackground*, *selectforeground* |
| 5436 |
The background and foreground colors used for the text while it is |
| 5437 |
selected. |
| 5438 |
|
| 5439 |
.. note:: |
| 5440 |
|
| 5441 |
Tk 8.6 added the *lmargincolor*, *overstrikefg*, *rmargincolor*, |
| 5442 |
*selectbackground*, *selectforeground* and *underlinefg* options. |
| 5443 |
|
| 5444 |
:meth:`tag_config` is an alias of :meth:`!tag_configure`. |
| 5445 |
|
| 5446 |
.. method:: tag_cget(tagName, option) |
| 5447 |
|
| 5448 |
Return the current value of the configuration option *option* for the tag |
| 5449 |
*tagName*. |
| 5450 |
|
| 5451 |
.. method:: tag_names(index=None) |
| 5452 |
|
| 5453 |
If *index* is omitted, return a tuple of the names of all tags defined in |
| 5454 |
the widget; otherwise return only the names of the tags applied to the |
| 5455 |
character at *index*. |
| 5456 |
The names are ordered from lowest to highest priority. |
| 5457 |
|
| 5458 |
.. method:: tag_ranges(tagName) |
| 5459 |
|
| 5460 |
Return a tuple of indices describing all ranges of text tagged with |
| 5461 |
*tagName*. |
| 5462 |
The result alternates start and end indices, so that elements ``2*i`` and |
| 5463 |
``2*i+1`` bound the *i*-th range. |
| 5464 |
|
| 5465 |
.. method:: tag_nextrange(tagName, index1, index2=None) |
| 5466 |
|
| 5467 |
Search forward from *index1* (up to *index2* if given) for the first |
| 5468 |
range of characters tagged with *tagName*, and return a two-element tuple |
| 5469 |
of its start and end indices, or an empty tuple if there is no such |
| 5470 |
range. |
| 5471 |
|
| 5472 |
.. method:: tag_prevrange(tagName, index1, index2=None) |
| 5473 |
|
| 5474 |
Search backward from *index1* (down to *index2* if given) for the nearest |
| 5475 |
preceding range of characters tagged with *tagName*, and return a |
| 5476 |
two-element tuple of its start and end indices, or an empty tuple if |
| 5477 |
there is no such range. |
| 5478 |
|
| 5479 |
.. method:: tag_raise(tagName, aboveThis=None) |
| 5480 |
|
| 5481 |
Raise the priority of tag *tagName* so that it is just above the priority |
| 5482 |
of *aboveThis*, or to the highest priority of all tags if *aboveThis* is |
| 5483 |
omitted. |
| 5484 |
When the display options of overlapping tags conflict, the |
| 5485 |
higher-priority tag wins. |
| 5486 |
|
| 5487 |
.. method:: tag_lower(tagName, belowThis=None) |
| 5488 |
|
| 5489 |
Lower the priority of tag *tagName* so that it is just below the priority |
| 5490 |
of *belowThis*, or to the lowest priority of all tags if *belowThis* is |
| 5491 |
omitted. |
| 5492 |
|
| 5493 |
.. method:: tag_bind(tagName, sequence, func, add=None) |
| 5494 |
|
| 5495 |
Bind the event *sequence* on characters tagged with *tagName* to the |
| 5496 |
callback *func*, so that *func* is invoked when that event occurs over |
| 5497 |
such a character. |
| 5498 |
If *add* is true the binding is added alongside any existing bindings for |
| 5499 |
*sequence*, otherwise it replaces them. |
| 5500 |
Works like :meth:`~Misc.bind` and returns the identifier of the new |
| 5501 |
binding. |
| 5502 |
|
| 5503 |
.. method:: tag_unbind(tagName, sequence, funcid=None) |
| 5504 |
|
| 5505 |
Remove the bindings of the event *sequence* on characters tagged with |
| 5506 |
*tagName*. |
| 5507 |
If *funcid* is given, only that binding (as returned by :meth:`tag_bind`) |
| 5508 |
is removed and its callback is unregistered. |
| 5509 |
|
| 5510 |
.. versionchanged:: 3.13 |
| 5511 |
If *funcid* is given, only that callback is unbound. |
| 5512 |
|
| 5513 |
|
| 5514 |
.. method:: image_create(index, cnf={}, **kw) |
| 5515 |
|
| 5516 |
Embed an image at *index* and return the name assigned to this image |
| 5517 |
instance, which may then be used as an index or passed to the other |
| 5518 |
``image_*`` methods. |
| 5519 |
The options, given in *cnf* and *kw*, include *image* (the Tk image to |
| 5520 |
display), *name* (a base name for the instance), *align*, *padx* and |
| 5521 |
*pady*. |
| 5522 |
|
| 5523 |
.. method:: image_cget(index, option) |
| 5524 |
|
| 5525 |
Return the current value of the configuration option *option* for the |
| 5526 |
embedded image at *index*. |
| 5527 |
|
| 5528 |
.. method:: image_configure(index, cnf=None, **kw) |
| 5529 |
|
| 5530 |
Query or modify the configuration options of the embedded image at |
| 5531 |
*index*, like :meth:`~Misc.configure` but applied to that image. |
| 5532 |
|
| 5533 |
.. method:: image_names() |
| 5534 |
|
| 5535 |
Return a tuple of the names of all images embedded in the widget. |
| 5536 |
|
| 5537 |
.. note:: |
| 5538 |
|
| 5539 |
This shadows the inherited :meth:`Misc.image_names`, |
| 5540 |
which returns the names of all images in the Tcl interpreter; |
| 5541 |
that method is not available on a :class:`Text`. |
| 5542 |
|
| 5543 |
.. method:: window_create(index, cnf={}, **kw) |
| 5544 |
|
| 5545 |
Embed a window (any widget) at *index*. |
| 5546 |
The options, given in *cnf* and *kw*, include *window* (the widget to |
| 5547 |
embed), *create* (a callback that creates the widget on demand), *align*, |
| 5548 |
*stretch*, *padx* and *pady*. |
| 5549 |
The embedded widget must be a descendant of the text widget's parent. |
| 5550 |
|
| 5551 |
.. method:: window_cget(index, option) |
| 5552 |
|
| 5553 |
Return the current value of the configuration option *option* for the |
| 5554 |
embedded window at *index*. |
| 5555 |
|
| 5556 |
.. method:: window_config(index, cnf=None, **kw) |
| 5557 |
:no-typesetting: |
| 5558 |
|
| 5559 |
.. method:: window_configure(index, cnf=None, **kw) |
| 5560 |
|
| 5561 |
Query or modify the configuration options of the embedded window at |
| 5562 |
*index*, like :meth:`~Misc.configure` but applied to that window. |
| 5563 |
|
| 5564 |
:meth:`window_config` is an alias of :meth:`!window_configure`. |
| 5565 |
|
| 5566 |
.. method:: window_names() |
| 5567 |
|
| 5568 |
Return a tuple of the names of all windows embedded in the widget. |
| 5569 |
|
| 5570 |
.. method:: edit(*args) |
| 5571 |
|
| 5572 |
Low-level wrapper around the Tk ``edit`` widget command that controls the |
| 5573 |
undo/redo mechanism and the modified flag; *args* is the ``edit`` |
| 5574 |
subcommand and its arguments. |
| 5575 |
The :meth:`!edit_\*` methods below are thin wrappers around it and are |
| 5576 |
usually more convenient. |
| 5577 |
|
| 5578 |
.. method:: edit_modified(arg=None) |
| 5579 |
|
| 5580 |
If *arg* is omitted, return the current state of the modified flag as |
| 5581 |
true or false; the flag is set automatically whenever the text is |
| 5582 |
inserted or deleted. |
| 5583 |
Otherwise set the flag to the boolean *arg*. |
| 5584 |
|
| 5585 |
.. method:: edit_undo() |
| 5586 |
|
| 5587 |
Undo the most recent edit action, that is, all the inserts and deletes |
| 5588 |
recorded on the undo stack since the previous separator, and move it to |
| 5589 |
the redo stack. |
| 5590 |
Raises :exc:`TclError` if the undo stack is empty. |
| 5591 |
Has no effect unless the *undo* option is true. |
| 5592 |
Since Tk 9.0, returns a tuple of indices delimiting the ranges of text |
| 5593 |
that were changed. |
| 5594 |
|
| 5595 |
.. method:: edit_redo() |
| 5596 |
|
| 5597 |
Reapply the most recently undone edit action, provided no further edits |
| 5598 |
have been made since, and move it back to the undo stack. |
| 5599 |
Raises :exc:`TclError` if the redo stack is empty. |
| 5600 |
Has no effect unless the *undo* option is true. |
| 5601 |
Since Tk 9.0, returns a tuple of indices delimiting the ranges of text |
| 5602 |
that were changed. |
| 5603 |
|
| 5604 |
.. method:: edit_reset() |
| 5605 |
|
| 5606 |
Clear the undo and redo stacks. |
| 5607 |
|
| 5608 |
.. method:: edit_separator() |
| 5609 |
|
| 5610 |
Push a separator onto the undo stack, marking a boundary between edit |
| 5611 |
actions for undo and redo. |
| 5612 |
Has no effect unless the *undo* option is true. |
| 5613 |
Separators are inserted automatically when the *autoseparators* option is |
| 5614 |
true. |
| 5615 |
|
| 5616 |
.. method:: search(pattern, index, stopindex=None, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None) |
| 5617 |
|
| 5618 |
Search for *pattern* starting at *index* and return the index of the |
| 5619 |
first character of the first match, or an empty string if there is no |
| 5620 |
match. |
| 5621 |
Searching stops at *stopindex* if given; otherwise it wraps around the |
| 5622 |
ends of the text until the starting position is reached again. |
| 5623 |
The following boolean keyword flags control the search: *forwards* or |
| 5624 |
*backwards* select the direction (forward is the default); *exact* (the |
| 5625 |
default) or *regexp* select literal or regular-expression matching; |
| 5626 |
*nocase* makes the match case-insensitive; and *elide* causes hidden text |
| 5627 |
to be searched as well. |
| 5628 |
If *count* is a :class:`Variable`, the number of index positions in the |
| 5629 |
match is stored in it. |
| 5630 |
|
| 5631 |
|
| 5632 |
.. method:: scan_mark(x, y) |
| 5633 |
|
| 5634 |
Record *x*, *y* and the current view, for use with later |
| 5635 |
:meth:`scan_dragto` calls. |
| 5636 |
This is typically bound to a mouse button press in the widget. |
| 5637 |
|
| 5638 |
.. method:: scan_dragto(x, y) |
| 5639 |
|
| 5640 |
Scroll the widget by 10 times the difference between *x*, *y* and the |
| 5641 |
coordinates passed to the last :meth:`scan_mark` call. |
| 5642 |
This is typically bound to mouse motion events, producing the effect of |
| 5643 |
dragging the text at high speed through the window. |
| 5644 |
|
| 5645 |
.. method:: debug(boolean=None) |
| 5646 |
|
| 5647 |
If *boolean* is omitted, return whether internal consistency checks of |
| 5648 |
the B-tree data structure are enabled. |
| 5649 |
Otherwise enable or disable them. |
| 5650 |
The setting is shared by all text widgets and may noticeably slow down |
| 5651 |
widgets holding large amounts of text. |
| 5652 |
|
| 5653 |
.. method:: dump(index1, index2=None, command=None, **kw) |
| 5654 |
|
| 5655 |
Return the contents of the widget from *index1* up to but not including |
| 5656 |
*index2* (or just the segment at *index1* if *index2* is omitted), |
| 5657 |
including text and information about marks, tags, images and windows. |
| 5658 |
The result is a list of ``(key, value, index)`` triples, where *key* is |
| 5659 |
one of ``'text'``, ``'mark'``, ``'tagon'``, ``'tagoff'``, ``'image'`` or |
| 5660 |
``'window'``. |
| 5661 |
By default all kinds are reported; passing any of the keyword arguments |
| 5662 |
*all*, *text*, *mark*, *tag*, *image* or *window* as true restricts the |
| 5663 |
dump to the selected kinds. |
| 5664 |
If *command* is given, it is called once per triple with the three values |
| 5665 |
as arguments and nothing is returned. |
| 5666 |
|
| 5667 |
.. method:: peer_create(newPathName, cnf={}, **kw) |
| 5668 |
|
| 5669 |
Create a peer text widget with the path name *newPathName* that shares |
| 5670 |
this widget's underlying data (text, marks, tags, images and the undo |
| 5671 |
stack). |
| 5672 |
Changes made through any peer are reflected in all of them. |
| 5673 |
By default the peer covers the same lines as this widget; standard text |
| 5674 |
options, including *startline* and *endline*, may be given to override |
| 5675 |
this. |
| 5676 |
|
| 5677 |
.. versionadded:: 3.3 |
| 5678 |
|
| 5679 |
.. method:: peer_names() |
| 5680 |
|
| 5681 |
Return a tuple of the path names of this widget's peers, not including |
| 5682 |
the widget itself. |
| 5683 |
|
| 5684 |
.. versionadded:: 3.3 |
| 5685 |
|
| 5686 |
.. method:: yview_pickplace(*what) |
| 5687 |
|
| 5688 |
Adjust the view so that the location given by *what* is visible. |
| 5689 |
This is an obsolete equivalent of :meth:`see`, which should be used |
| 5690 |
instead. |
| 5691 |
|
| 5692 |
|
| 5693 |
Variable classes |
| 5694 |
^^^^^^^^^^^^^^^^ |
| 5695 |
|
| 5696 |
.. class:: Variable(master=None, value=None, name=None) |
| 5697 |
|
| 5698 |
The base class for the Tk variable wrappers. |
| 5699 |
A Tk variable is a value stored in the Tcl interpreter that can be linked to |
| 5700 |
widgets through their *variable* or *textvariable* options (see |
| 5701 |
:ref:`coupling-widget-variables`), so that changes propagate both ways: |
| 5702 |
updating the variable updates every widget bound to it, and a user editing |
| 5703 |
such a widget updates the variable. |
| 5704 |
|
| 5705 |
*master* is the widget whose Tcl interpreter owns the variable; if omitted, |
| 5706 |
the default root window is used. |
| 5707 |
*value* is the initial value; if omitted, a type-specific default is used. |
| 5708 |
*name* is the name of the variable in the Tcl interpreter; if omitted, a |
| 5709 |
unique name of the form ``'PY_VARnum'`` is generated. |
| 5710 |
If *name* matches an existing variable and *value* is omitted, the existing |
| 5711 |
value is retained. |
| 5712 |
|
| 5713 |
In most cases you should use one of the typed subclasses below -- |
| 5714 |
:class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` or |
| 5715 |
:class:`BooleanVar` -- rather than :class:`!Variable` directly. |
| 5716 |
|
| 5717 |
.. note:: |
| 5718 |
|
| 5719 |
When a :class:`!Variable` is garbage collected, its Tcl variable is unset. |
| 5720 |
Keep a reference to it for as long as a widget is linked to it, for example |
| 5721 |
by storing it as an attribute rather than in a local variable. |
| 5722 |
Otherwise Tk recreates the Tcl variable to keep the widget working, but it |
| 5723 |
is never unset again, leaking one Tcl variable per dropped wrapper. |
| 5724 |
|
| 5725 |
.. versionchanged:: 3.10 |
| 5726 |
Two variables now compare equal (``==``) only when they have the same |
| 5727 |
name, are of the same class, and belong to the same Tcl interpreter. |
| 5728 |
|
| 5729 |
.. method:: get() |
| 5730 |
|
| 5731 |
Return the current value of the variable. |
| 5732 |
For the base class the value is returned as a string; the typed |
| 5733 |
subclasses convert it to the appropriate Python type. |
| 5734 |
|
| 5735 |
.. method:: initialize(value) |
| 5736 |
:no-typesetting: |
| 5737 |
|
| 5738 |
.. method:: set(value) |
| 5739 |
|
| 5740 |
Set the variable to *value*. |
| 5741 |
:meth:`initialize` is an alias of :meth:`!set`. |
| 5742 |
|
| 5743 |
.. versionadded:: 3.3 |
| 5744 |
The *initialize* spelling. |
| 5745 |
|
| 5746 |
.. method:: trace_add(mode, callback) |
| 5747 |
|
| 5748 |
Register *callback* to be called when the variable is accessed according |
| 5749 |
to *mode*. |
| 5750 |
*mode* is one of the strings ``'array'``, ``'read'``, ``'write'`` or |
| 5751 |
``'unset'``, or a list or tuple of such strings. |
| 5752 |
|
| 5753 |
When triggered, *callback* is called with three arguments: the name of |
| 5754 |
the Tcl variable, an index (or an empty string if the variable is not an |
| 5755 |
element of an array), and the *mode* that triggered the call. |
| 5756 |
|
| 5757 |
Return the internal name of the registered callback, which can be passed |
| 5758 |
to :meth:`trace_remove`. |
| 5759 |
|
| 5760 |
.. versionadded:: 3.6 |
| 5761 |
|
| 5762 |
.. method:: trace_remove(mode, cbname) |
| 5763 |
|
| 5764 |
Remove a trace callback from the variable. |
| 5765 |
*mode* must match the *mode* that was passed to :meth:`trace_add`, and |
| 5766 |
*cbname* is the callback name returned by :meth:`trace_add`. |
| 5767 |
|
| 5768 |
.. versionadded:: 3.6 |
| 5769 |
|
| 5770 |
.. method:: trace_info() |
| 5771 |
|
| 5772 |
Return a list of ``(modes, cbname)`` pairs describing all traces |
| 5773 |
currently set on the variable, where *modes* is a tuple of mode strings |
| 5774 |
and *cbname* is the internal callback name. |
| 5775 |
|
| 5776 |
.. versionadded:: 3.6 |
| 5777 |
|
| 5778 |
.. method:: trace(mode, callback) |
| 5779 |
:no-typesetting: |
| 5780 |
|
| 5781 |
.. method:: trace_variable(mode, callback) |
| 5782 |
|
| 5783 |
Register *callback* to be called when the variable is accessed according |
| 5784 |
to *mode*. |
| 5785 |
*mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for read, write |
| 5786 |
or unset. |
| 5787 |
Return the internal name of the registered callback. |
| 5788 |
:meth:`trace` is an alias of :meth:`!trace_variable`. |
| 5789 |
|
| 5790 |
.. deprecated:: 3.6 |
| 5791 |
Use :meth:`trace_add` instead. This method wraps a Tcl feature that |
| 5792 |
was removed in Tcl 9.0. |
| 5793 |
|
| 5794 |
.. method:: trace_vdelete(mode, cbname) |
| 5795 |
|
| 5796 |
Remove the trace callback named *cbname* registered for *mode* with |
| 5797 |
:meth:`trace_variable`. |
| 5798 |
|
| 5799 |
.. deprecated:: 3.6 |
| 5800 |
Use :meth:`trace_remove` instead. This method wraps a Tcl feature |
| 5801 |
that was removed in Tcl 9.0. |
| 5802 |
|
| 5803 |
.. method:: trace_vinfo() |
| 5804 |
|
| 5805 |
Return a list of ``(mode, cbname)`` pairs for all traces set on the |
| 5806 |
variable with :meth:`trace_variable`. |
| 5807 |
|
| 5808 |
.. deprecated:: 3.6 |
| 5809 |
Use :meth:`trace_info` instead. This method wraps a Tcl feature that |
| 5810 |
was removed in Tcl 9.0. |
| 5811 |
|
| 5812 |
|
| 5813 |
.. class:: StringVar(master=None, value=None, name=None) |
| 5814 |
|
| 5815 |
A :class:`Variable` subclass that holds a string. |
| 5816 |
The default value is ``''``. |
| 5817 |
|
| 5818 |
.. method:: get() |
| 5819 |
|
| 5820 |
Return the value of the variable as a :class:`str`. |
| 5821 |
|
| 5822 |
|
| 5823 |
.. class:: IntVar(master=None, value=None, name=None) |
| 5824 |
|
| 5825 |
A :class:`Variable` subclass that holds an integer. |
| 5826 |
The default value is ``0``. |
| 5827 |
|
| 5828 |
.. method:: get() |
| 5829 |
|
| 5830 |
Return the value of the variable as an :class:`int`. |
| 5831 |
|
| 5832 |
|
| 5833 |
.. class:: DoubleVar(master=None, value=None, name=None) |
| 5834 |
|
| 5835 |
A :class:`Variable` subclass that holds a float. |
| 5836 |
The default value is ``0.0``. |
| 5837 |
|
| 5838 |
.. method:: get() |
| 5839 |
|
| 5840 |
Return the value of the variable as a :class:`float`. |
| 5841 |
|
| 5842 |
.. _tkinter-numeric-locale: |
| 5843 |
|
| 5844 |
.. note:: |
| 5845 |
|
| 5846 |
A floating-point value is always parsed with a period (``.``) as the |
| 5847 |
decimal separator, but :class:`Spinbox`, :class:`Scale` and |
| 5848 |
:class:`ttk.Spinbox <tkinter.ttk.Spinbox>` format it according to the |
| 5849 |
``LC_NUMERIC`` locale. Under a locale that uses a comma they produce a |
| 5850 |
value that :meth:`get` cannot read, raising :exc:`TclError`. Set |
| 5851 |
``LC_NUMERIC`` to a locale that uses a period (such as ``'C'``) to avoid |
| 5852 |
this. |
| 5853 |
|
| 5854 |
|
| 5855 |
.. class:: BooleanVar(master=None, value=None, name=None) |
| 5856 |
|
| 5857 |
A :class:`Variable` subclass that holds a boolean. |
| 5858 |
The default value is ``False``. |
| 5859 |
|
| 5860 |
.. method:: get() |
| 5861 |
|
| 5862 |
Return the value of the variable as a :class:`bool`. |
| 5863 |
Raise a :exc:`ValueError` if the value cannot be interpreted as a |
| 5864 |
boolean. |
| 5865 |
|
| 5866 |
.. method:: initialize(value) |
| 5867 |
:no-typesetting: |
| 5868 |
|
| 5869 |
.. method:: set(value) |
| 5870 |
|
| 5871 |
Set the variable to *value*, converting it to a boolean. |
| 5872 |
:meth:`initialize` is an alias of :meth:`!set`. |
| 5873 |
|
| 5874 |
.. versionadded:: 3.3 |
| 5875 |
The *initialize* spelling. |
| 5876 |
|
| 5877 |
|
| 5878 |
Image classes |
| 5879 |
^^^^^^^^^^^^^ |
| 5880 |
|
| 5881 |
.. class:: Image(imgtype, name=None, cnf={}, master=None, **kw) |
| 5882 |
|
| 5883 |
Base class for Tk images. |
| 5884 |
*imgtype* is the Tk image type, one of ``'photo'`` or ``'bitmap'``. |
| 5885 |
An image is a named object that can be displayed by widgets through their |
| 5886 |
*image* option; deleting all references to the :class:`!Image` object |
| 5887 |
deletes the underlying Tk image. |
| 5888 |
Usually you create a :class:`PhotoImage` or :class:`BitmapImage` rather than |
| 5889 |
an :class:`!Image` directly. |
| 5890 |
|
| 5891 |
The image's configuration options are given by *cnf* and *kw* and may be |
| 5892 |
queried and changed later with the mapping protocol (using ``image[key]``) |
| 5893 |
or with the :meth:`configure` method. |
| 5894 |
|
| 5895 |
.. method:: config(**kw) |
| 5896 |
:no-typesetting: |
| 5897 |
|
| 5898 |
.. method:: configure(**kw) |
| 5899 |
|
| 5900 |
Modify one or more configuration options of the image. |
| 5901 |
The valid options depend on the image type; see :class:`PhotoImage` and |
| 5902 |
:class:`BitmapImage`. |
| 5903 |
:meth:`config` is an alias of :meth:`!configure`. |
| 5904 |
|
| 5905 |
.. method:: height() |
| 5906 |
|
| 5907 |
Return the height of the image, in pixels. |
| 5908 |
|
| 5909 |
.. method:: width() |
| 5910 |
|
| 5911 |
Return the width of the image, in pixels. |
| 5912 |
|
| 5913 |
.. method:: type() |
| 5914 |
|
| 5915 |
Return the type of the image, that is the value of *imgtype* with which |
| 5916 |
it was created (for example ``'photo'`` or ``'bitmap'``). |
| 5917 |
|
| 5918 |
|
| 5919 |
.. class:: PhotoImage(name=None, cnf={}, master=None, **kw) |
| 5920 |
|
| 5921 |
A full-color image (the Tk ``photo`` image type), stored internally with a |
| 5922 |
varying degree of transparency per pixel. |
| 5923 |
It can read and write GIF, PPM/PGM and (in Tk 8.6 and later) PNG files, read |
| 5924 |
SVG files (in Tk 9.0 and later), and be drawn in widgets. |
| 5925 |
Inherits from :class:`Image`. |
| 5926 |
|
| 5927 |
The configuration options include *data* (the image contents as a string), |
| 5928 |
*file* (the name of a file to read the contents from), *format* (the name of |
| 5929 |
the file format handler), *width* and *height* (the size of the image, used |
| 5930 |
when building it up piece by piece), *gamma* and *palette*. |
| 5931 |
|
| 5932 |
.. method:: blank() |
| 5933 |
|
| 5934 |
Blank the image; that is, set the entire image to have no data, so that |
| 5935 |
it is displayed as transparent and the background of whatever window it |
| 5936 |
is displayed in shows through. |
| 5937 |
|
| 5938 |
.. method:: cget(option) |
| 5939 |
|
| 5940 |
Return the current value of the configuration option *option*. |
| 5941 |
|
| 5942 |
.. method:: copy(*, from_coords=None, zoom=None, subsample=None) |
| 5943 |
|
| 5944 |
Return a new :class:`PhotoImage` with a copy of this image. |
| 5945 |
|
| 5946 |
*from_coords* specifies a rectangular sub-region of the source image to |
| 5947 |
be copied. |
| 5948 |
It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. |
| 5949 |
``(x1, y1)`` and ``(x2, y2)`` specify diagonally opposite corners of the |
| 5950 |
rectangle. |
| 5951 |
If *x2* and *y2* are not specified, they default to the bottom-right |
| 5952 |
corner of the source image. |
| 5953 |
The pixels copied include the left and top edges of the rectangle but not |
| 5954 |
the bottom or right edges. |
| 5955 |
If *from_coords* is not given, the whole source image is copied. |
| 5956 |
|
| 5957 |
If *zoom* or *subsample* are specified, the image is transformed as in |
| 5958 |
the :meth:`zoom` or :meth:`subsample` methods. |
| 5959 |
The value must be a single integer or a pair of integers. |
| 5960 |
|
| 5961 |
.. versionchanged:: 3.13 |
| 5962 |
Added the *from_coords*, *zoom* and *subsample* parameters. |
| 5963 |
|
| 5964 |
|
| 5965 |
.. method:: copy_replace(sourceImage, *, from_coords=None, to=None, \ |
| 5966 |
shrink=False, zoom=None, subsample=None, \ |
| 5967 |
compositingrule=None) |
| 5968 |
|
| 5969 |
Copy a region from *sourceImage* (which must be a :class:`PhotoImage`) |
| 5970 |
into this image, possibly with pixel zooming and/or subsampling. |
| 5971 |
If no options are specified, the whole of *sourceImage* is copied into |
| 5972 |
this image, starting at coordinates ``(0, 0)``. |
| 5973 |
|
| 5974 |
*from_coords* specifies a rectangular sub-region of the source image to |
| 5975 |
be copied, as in the :meth:`copy` method. |
| 5976 |
|
| 5977 |
*to* specifies a rectangular sub-region of the destination image to be |
| 5978 |
affected. |
| 5979 |
It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. |
| 5980 |
If *x2* and *y2* are not specified, they default to ``(x1, y1)`` plus the |
| 5981 |
size of the source region (after subsampling and zooming, if specified). |
| 5982 |
If *x2* and *y2* are specified, the source region is replicated if |
| 5983 |
necessary to fill the destination region in a tiled fashion. |
| 5984 |
|
| 5985 |
If *shrink* is true, the size of the destination image is reduced, if |
| 5986 |
necessary, so that the region being copied into is at the bottom-right |
| 5987 |
corner of the image. |
| 5988 |
|
| 5989 |
If *zoom* or *subsample* are specified, the image is transformed as in |
| 5990 |
the :meth:`zoom` or :meth:`subsample` methods. |
| 5991 |
The value must be a single integer or a pair of integers. |
| 5992 |
|
| 5993 |
*compositingrule* specifies how transparent pixels in the source image |
| 5994 |
are combined with the destination image. |
| 5995 |
With ``'overlay'`` (the default), the old contents of the destination |
| 5996 |
image remain visible, as if the source image were printed on a piece of |
| 5997 |
transparent film and placed over the top of the destination. |
| 5998 |
With ``'set'``, the old contents of the destination image are discarded |
| 5999 |
and the source image is used as-is. |
| 6000 |
|
| 6001 |
.. versionadded:: 3.13 |
| 6002 |
|
| 6003 |
|
| 6004 |
.. method:: data(format=None, *, from_coords=None, background=None, \ |
| 6005 |
grayscale=False) |
| 6006 |
|
| 6007 |
Return the image data. |
| 6008 |
|
| 6009 |
*format* specifies the name of the image file format handler to use. |
| 6010 |
If it is not given, the data is returned as a tuple (one element per row) |
| 6011 |
of strings containing space-separated (one element per pixel/column) |
| 6012 |
colors in ``#RRGGBB`` format. |
| 6013 |
|
| 6014 |
*from_coords* specifies a rectangular region of the image to be returned. |
| 6015 |
It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. |
| 6016 |
If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` |
| 6017 |
to the bottom-right corner of the image. |
| 6018 |
If all four coordinates are given, they specify diagonally opposite |
| 6019 |
corners of the region, including ``(x1, y1)`` and excluding ``(x2, y2)``. |
| 6020 |
If *from_coords* is not given, the whole image is returned. |
| 6021 |
|
| 6022 |
If *background* is specified, the data does not contain any transparency |
| 6023 |
information; in all transparent pixels the color is replaced by the |
| 6024 |
specified color. |
| 6025 |
|
| 6026 |
If *grayscale* is true, the data does not contain color information; all |
| 6027 |
pixel data is transformed into grayscale. |
| 6028 |
|
| 6029 |
.. versionadded:: 3.13 |
| 6030 |
|
| 6031 |
|
| 6032 |
.. method:: get(x, y) |
| 6033 |
|
| 6034 |
Return the color of the pixel at coordinates (*x*, *y*) as an |
| 6035 |
``(r, g, b)`` tuple of three integers between 0 and 255, representing the |
| 6036 |
red, green and blue components respectively. |
| 6037 |
|
| 6038 |
.. method:: put(data, to=None) |
| 6039 |
|
| 6040 |
Set pixels of the image to the colors given in *data*, which must be a |
| 6041 |
string or a nested sequence of horizontal rows of pixel colors (for |
| 6042 |
example ``"{red green} {blue yellow}"``). |
| 6043 |
|
| 6044 |
*to* specifies the coordinates of the region of the image into which the |
| 6045 |
data are copied. |
| 6046 |
It must be a tuple or a list of 2 or 4 integers ``(x1, y1)`` or |
| 6047 |
``(x1, y1, x2, y2)`` giving the top-left corner, and optionally the |
| 6048 |
bottom-right corner, of the region. |
| 6049 |
The default position is ``(0, 0)``. |
| 6050 |
|
| 6051 |
.. method:: read(filename, format=None, *, from_coords=None, to=None, \ |
| 6052 |
shrink=False) |
| 6053 |
|
| 6054 |
Read image data from the file named *filename* into the image. |
| 6055 |
|
| 6056 |
*format* specifies the format of the image data in the file. |
| 6057 |
|
| 6058 |
*from_coords* specifies a rectangular sub-region of the image file data |
| 6059 |
to be copied to the destination image. |
| 6060 |
It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. |
| 6061 |
If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` |
| 6062 |
to the bottom-right corner of the image in the file. |
| 6063 |
If all four coordinates are given, they specify diagonally opposite |
| 6064 |
corners of the region. |
| 6065 |
If *from_coords* is not given, the whole of the image in the file is |
| 6066 |
read. |
| 6067 |
|
| 6068 |
*to* specifies the coordinates of the top-left corner of the region of |
| 6069 |
the image into which the data are read. |
| 6070 |
The default is ``(0, 0)``. |
| 6071 |
|
| 6072 |
If *shrink* is true, the size of the image is reduced, if necessary, so |
| 6073 |
that the region into which the file data are read is at the bottom-right |
| 6074 |
corner of the image. |
| 6075 |
|
| 6076 |
.. versionadded:: 3.13 |
| 6077 |
|
| 6078 |
|
| 6079 |
.. method:: subsample(x, y='', *, from_coords=None) |
| 6080 |
|
| 6081 |
Return a new :class:`PhotoImage` based on this image but using only every |
| 6082 |
*x*-th pixel in the X direction and every *y*-th pixel in the Y |
| 6083 |
direction. |
| 6084 |
If *y* is not given, it defaults to the same value as *x*. |
| 6085 |
|
| 6086 |
*from_coords* specifies a rectangular sub-region of the source image to |
| 6087 |
be copied, as in the :meth:`copy` method. |
| 6088 |
|
| 6089 |
.. versionchanged:: 3.13 |
| 6090 |
Added the *from_coords* parameter. |
| 6091 |
|
| 6092 |
|
| 6093 |
.. method:: transparency_get(x, y) |
| 6094 |
|
| 6095 |
Return ``True`` if the pixel at coordinates (*x*, *y*) is fully |
| 6096 |
transparent, ``False`` otherwise. |
| 6097 |
|
| 6098 |
.. versionadded:: 3.8 |
| 6099 |
|
| 6100 |
|
| 6101 |
.. method:: transparency_set(x, y, boolean) |
| 6102 |
|
| 6103 |
Make the pixel at coordinates (*x*, *y*) fully transparent if *boolean* |
| 6104 |
is true, fully opaque otherwise. |
| 6105 |
|
| 6106 |
.. versionadded:: 3.8 |
| 6107 |
|
| 6108 |
|
| 6109 |
.. method:: write(filename, format=None, from_coords=None, *, \ |
| 6110 |
background=None, grayscale=False) |
| 6111 |
|
| 6112 |
Write image data from the image to the file named *filename*. |
| 6113 |
|
| 6114 |
*format* specifies the name of the image file format handler to use. |
| 6115 |
If it is not given, the format is guessed from the file extension. |
| 6116 |
|
| 6117 |
*from_coords* specifies a rectangular region of the image to be written. |
| 6118 |
It must be a tuple or a list of 1 to 4 integers ``(x1, y1, x2, y2)``. |
| 6119 |
If only *x1* and *y1* are specified, the region extends from ``(x1, y1)`` |
| 6120 |
to the bottom-right corner of the image. |
| 6121 |
If all four coordinates are given, they specify diagonally opposite |
| 6122 |
corners of the region. |
| 6123 |
If *from_coords* is not given, the whole image is written. |
| 6124 |
|
| 6125 |
If *background* is specified, the data does not contain any transparency |
| 6126 |
information; in all transparent pixels the color is replaced by the |
| 6127 |
specified color. |
| 6128 |
|
| 6129 |
If *grayscale* is true, the data does not contain color information; all |
| 6130 |
pixel data is transformed into grayscale. |
| 6131 |
|
| 6132 |
.. versionchanged:: 3.13 |
| 6133 |
Added the *background* and *grayscale* parameters. |
| 6134 |
|
| 6135 |
|
| 6136 |
.. method:: zoom(x, y='', *, from_coords=None) |
| 6137 |
|
| 6138 |
Return a new :class:`PhotoImage` with this image magnified by a factor of |
| 6139 |
*x* in the X direction and *y* in the Y direction. |
| 6140 |
If *y* is not given, it defaults to the same value as *x*. |
| 6141 |
|
| 6142 |
*from_coords* specifies a rectangular sub-region of the source image to |
| 6143 |
be copied, as in the :meth:`copy` method. |
| 6144 |
|
| 6145 |
.. versionchanged:: 3.13 |
| 6146 |
Added the *from_coords* parameter. |
| 6147 |
|
| 6148 |
|
| 6149 |
|
| 6150 |
.. class:: BitmapImage(name=None, cnf={}, master=None, **kw) |
| 6151 |
|
| 6152 |
A two-color image (the Tk ``bitmap`` image type) created from an X11 bitmap. |
| 6153 |
Each pixel displays a foreground color, a background color, or nothing |
| 6154 |
(producing a transparent effect). |
| 6155 |
Inherits from :class:`Image`. |
| 6156 |
|
| 6157 |
The configuration options are *data* or *file* (the source bitmap, given as |
| 6158 |
a string in X11 bitmap format or as the name of a file in that format), |
| 6159 |
*maskdata* or *maskfile* (the mask bitmap, in the same forms), and |
| 6160 |
*foreground* and *background* (the two colors). |
| 6161 |
For pixels where the mask is zero the image displays nothing; for other |
| 6162 |
pixels it displays the foreground color where the source is one and the |
| 6163 |
background color where the source is zero. |
| 6164 |
If *background* is set to an empty string, the background pixels are |
| 6165 |
transparent. |
| 6166 |
|
| 6167 |
:class:`!BitmapImage` has no methods of its own beyond those inherited from |
| 6168 |
:class:`Image`. |
| 6169 |
|
| 6170 |
|
| 6171 |
Other classes |
| 6172 |
^^^^^^^^^^^^^ |
| 6173 |
|
| 6174 |
.. class:: Event() |
| 6175 |
|
| 6176 |
A container for the attributes of an event passed to a callback bound with |
| 6177 |
:meth:`Misc.bind`. |
| 6178 |
An :class:`!Event` instance has the following attributes, each corresponding |
| 6179 |
to a field of the underlying Tk event; depending on the event type, some |
| 6180 |
attributes may be set to the string ``'??'`` to indicate that they are not |
| 6181 |
meaningful. |
| 6182 |
See :ref:`bindings-and-events`. |
| 6183 |
|
| 6184 |
.. attribute:: serial |
| 6185 |
|
| 6186 |
The serial number of the event. |
| 6187 |
|
| 6188 |
.. attribute:: num |
| 6189 |
|
| 6190 |
The mouse button that was pressed or released (for button events). |
| 6191 |
|
| 6192 |
.. attribute:: focus |
| 6193 |
|
| 6194 |
Whether the window has the focus (for ``Enter`` and ``Leave`` events). |
| 6195 |
|
| 6196 |
.. attribute:: height |
| 6197 |
width |
| 6198 |
|
| 6199 |
The new height and width of the window (for ``Configure`` and ``Expose`` |
| 6200 |
events). |
| 6201 |
|
| 6202 |
.. attribute:: keycode |
| 6203 |
|
| 6204 |
The keycode of the key that was pressed or released. |
| 6205 |
|
| 6206 |
.. attribute:: state |
| 6207 |
|
| 6208 |
The state of the event, as a number (for most events) or a string (for |
| 6209 |
``Visibility`` events). |
| 6210 |
|
| 6211 |
.. attribute:: time |
| 6212 |
|
| 6213 |
The timestamp of the event, in milliseconds. |
| 6214 |
|
| 6215 |
.. attribute:: x |
| 6216 |
y |
| 6217 |
|
| 6218 |
The pointer position relative to the widget, in pixels. |
| 6219 |
|
| 6220 |
.. attribute:: x_root |
| 6221 |
y_root |
| 6222 |
|
| 6223 |
The pointer position relative to the top-left corner of the screen, in |
| 6224 |
pixels. |
| 6225 |
|
| 6226 |
.. attribute:: char |
| 6227 |
|
| 6228 |
The character typed, as a string (for key events). |
| 6229 |
|
| 6230 |
.. attribute:: send_event |
| 6231 |
|
| 6232 |
``True`` if the event was sent by another application. |
| 6233 |
|
| 6234 |
.. attribute:: keysym |
| 6235 |
|
| 6236 |
The symbolic name of the key that was pressed or released. |
| 6237 |
|
| 6238 |
.. attribute:: keysym_num |
| 6239 |
|
| 6240 |
The numeric value of :attr:`keysym`. |
| 6241 |
|
| 6242 |
.. attribute:: type |
| 6243 |
|
| 6244 |
The :class:`EventType` of the event. |
| 6245 |
|
| 6246 |
.. attribute:: widget |
| 6247 |
|
| 6248 |
The widget on which the event occurred. |
| 6249 |
|
| 6250 |
.. attribute:: delta |
| 6251 |
|
| 6252 |
The amount the mouse wheel was rotated (for ``MouseWheel`` events). |
| 6253 |
|
| 6254 |
|
| 6255 |
.. class:: EventType(*values) |
| 6256 |
|
| 6257 |
An :class:`enum.StrEnum` enumerating the Tk event types, used as the value |
| 6258 |
of :attr:`Event.type`. |
| 6259 |
Its members include, among others, ``KeyPress``, ``KeyRelease``, |
| 6260 |
``ButtonPress``, ``ButtonRelease``, ``Motion``, ``Enter``, ``Leave``, |
| 6261 |
``FocusIn``, ``FocusOut``, ``Configure``, ``Map``, ``Unmap``, ``Expose``, |
| 6262 |
``Destroy`` and ``MouseWheel``. |
| 6263 |
|
| 6264 |
.. versionadded:: 3.6 |
| 6265 |
|
| 6266 |
|
| 6267 |
|
| 6268 |
.. class:: CallWrapper(func, subst, widget) |
| 6269 |
|
| 6270 |
Internal helper that wraps a Python callback so that it can be invoked from |
| 6271 |
Tcl. |
| 6272 |
*func* is the Python function, *subst* is an optional function that |
| 6273 |
pre-processes the Tcl arguments, and *widget* is the widget used for error |
| 6274 |
reporting. |
| 6275 |
Instances are created automatically by :meth:`Misc.register`; this class is |
| 6276 |
not normally used directly. |
| 6277 |
|
| 6278 |
|
| 6279 |
Module-level functions |
| 6280 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 6281 |
|
| 6282 |
.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) |
| 6283 |
|
| 6284 |
The :func:`Tcl` function is a factory function which creates an object much |
| 6285 |
like that created by the :class:`Tk` class, except that it does not |
| 6286 |
initialize the Tk subsystem. |
| 6287 |
This is most often useful when driving the Tcl interpreter in an environment |
| 6288 |
where one doesn't want to create extraneous toplevel windows, or where one |
| 6289 |
cannot (such as Unix/Linux systems without an X server). |
| 6290 |
An object created by the :func:`Tcl` object can have a Toplevel window |
| 6291 |
created (and the Tk subsystem initialized) by calling its :meth:`~Tk.loadtk` |
| 6292 |
method. |
| 6293 |
|
| 6294 |
.. function:: NoDefaultRoot() |
| 6295 |
|
| 6296 |
Inhibit the creation of an implicit default root window. |
| 6297 |
Afterwards :mod:`!tkinter` no longer creates a shared default root |
| 6298 |
automatically, and operations that rely on one --- such as constructing a |
| 6299 |
widget without an explicit *master* --- raise a :exc:`RuntimeError`. |
| 6300 |
Call this early in larger applications to make the root window explicit. |
| 6301 |
|
| 6302 |
.. function:: mainloop(n=0) |
| 6303 |
|
| 6304 |
Run the Tk main event loop on the default root window until all windows are |
| 6305 |
destroyed. |
| 6306 |
Equivalent to calling :meth:`Misc.mainloop` on the default root. |
| 6307 |
|
| 6308 |
.. function:: getboolean(s) |
| 6309 |
|
| 6310 |
Convert the Tcl boolean string *s* (one of ``'1'``, ``'true'``, ``'yes'``, |
| 6311 |
``'on'`` and similar, or their false counterparts) to a Python |
| 6312 |
:class:`bool`. |
| 6313 |
Raise :exc:`TclError` for an invalid value. |
| 6314 |
|
| 6315 |
.. function:: getdouble(s) |
| 6316 |
|
| 6317 |
Convert *s* to a floating-point number. |
| 6318 |
This is the built-in :class:`float`. |
| 6319 |
|
| 6320 |
.. function:: getint(s) |
| 6321 |
|
| 6322 |
Convert *s* to an integer. |
| 6323 |
This is the built-in :class:`int`. |
| 6324 |
|
| 6325 |
.. function:: image_names() |
| 6326 |
|
| 6327 |
Return the names of all existing images in the default root's interpreter. |
| 6328 |
|
| 6329 |
.. function:: image_types() |
| 6330 |
|
| 6331 |
Return the available image types (such as ``'photo'`` and ``'bitmap'``) in |
| 6332 |
the default root's interpreter. |
| 6333 |
|
| 6334 |
|
| 6335 |
.. _tkinter-file-handlers: |
| 6336 |
|
| 6337 |
File handlers |
| 6338 |
^^^^^^^^^^^^^ |
| 6339 |
|
| 6340 |
Tk allows you to register and unregister a callback function which will be |
| 6341 |
called from the Tk mainloop when I/O is possible on a file descriptor. |
| 6342 |
Only one handler may be registered per file descriptor. Example code:: |
| 6343 |
|
| 6344 |
import tkinter |
| 6345 |
widget = tkinter.Tk() |
| 6346 |
mask = tkinter.READABLE | tkinter.WRITABLE |
| 6347 |
widget.tk.createfilehandler(file, mask, callback) |
| 6348 |
... |
| 6349 |
widget.tk.deletefilehandler(file) |
| 6350 |
|
| 6351 |
This feature is not available on Windows. |
| 6352 |
|
| 6353 |
Since you don't know how many bytes are available for reading, you may not |
| 6354 |
want to use the :class:`~io.BufferedIOBase` or :class:`~io.TextIOBase` |
| 6355 |
:meth:`~io.BufferedIOBase.read` or :meth:`~io.IOBase.readline` methods, |
| 6356 |
since these will insist on reading a predefined number of bytes. |
| 6357 |
For sockets, the :meth:`~socket.socket.recv` or |
| 6358 |
:meth:`~socket.socket.recvfrom` methods will work fine; for other files, |
| 6359 |
use raw reads or ``os.read(file.fileno(), maxbytecount)``. |
| 6360 |
|
| 6361 |
|
| 6362 |
.. method:: Widget.tk.createfilehandler(file, mask, func) |
| 6363 |
|
| 6364 |
Registers the file handler callback function *func*. The *file* argument |
| 6365 |
may either be an object with a :meth:`~io.IOBase.fileno` method (such as |
| 6366 |
a file or socket object), or an integer file descriptor. The *mask* |
| 6367 |
argument is an ORed combination of any of the three constants below. |
| 6368 |
The callback is called as follows:: |
| 6369 |
|
| 6370 |
callback(file, mask) |
| 6371 |
|
| 6372 |
|
| 6373 |
.. method:: Widget.tk.deletefilehandler(file) |
| 6374 |
|
| 6375 |
Unregisters a file handler. |
| 6376 |
|
| 6377 |
|
| 6378 |
.. data:: READABLE |
| 6379 |
WRITABLE |
| 6380 |
EXCEPTION |
| 6381 |
|
| 6382 |
Constants used in the *mask* arguments. |
| 6383 |
|
| 6384 |
|
| 6385 |
Constants |
| 6386 |
^^^^^^^^^ |
| 6387 |
|
| 6388 |
The following symbolic constants are available in both the :mod:`!tkinter` |
| 6389 |
and :mod:`!tkinter.constants` namespaces. |
| 6390 |
|
| 6391 |
.. data:: TRUE |
| 6392 |
YES |
| 6393 |
ON |
| 6394 |
|
| 6395 |
Truthy values, all equal to the integer ``1``. |
| 6396 |
|
| 6397 |
.. data:: FALSE |
| 6398 |
NO |
| 6399 |
OFF |
| 6400 |
|
| 6401 |
Falsy values, all equal to the integer ``0``. |
| 6402 |
|
| 6403 |
.. data:: N |
| 6404 |
S |
| 6405 |
E |
| 6406 |
W |
| 6407 |
NE |
| 6408 |
NW |
| 6409 |
SE |
| 6410 |
SW |
| 6411 |
NS |
| 6412 |
EW |
| 6413 |
NSEW |
| 6414 |
CENTER |
| 6415 |
|
| 6416 |
Compass directions (``'n'``, ``'s'``, ``'e'``, ``'w'`` and the diagonals and |
| 6417 |
edges) plus ``CENTER`` (``'center'``), used as values for the *anchor* and |
| 6418 |
*sticky* options and by methods such as :meth:`Misc.grid_anchor`. |
| 6419 |
|
| 6420 |
.. data:: LEFT |
| 6421 |
RIGHT |
| 6422 |
TOP |
| 6423 |
BOTTOM |
| 6424 |
|
| 6425 |
Sides for the *side* option of the packer (see :meth:`Pack.pack_configure`). |
| 6426 |
|
| 6427 |
.. data:: X |
| 6428 |
Y |
| 6429 |
BOTH |
| 6430 |
NONE |
| 6431 |
|
| 6432 |
Values for the *fill* option of the packer: ``'x'``, ``'y'``, ``'both'`` or |
| 6433 |
``'none'``. |
| 6434 |
|
| 6435 |
.. data:: RAISED |
| 6436 |
SUNKEN |
| 6437 |
FLAT |
| 6438 |
RIDGE |
| 6439 |
GROOVE |
| 6440 |
SOLID |
| 6441 |
|
| 6442 |
Values for the *relief* option, which controls a widget's 3-D border. |
| 6443 |
|
| 6444 |
.. data:: HORIZONTAL |
| 6445 |
VERTICAL |
| 6446 |
|
| 6447 |
Values for the *orient* option of widgets such as :class:`Scale`, |
| 6448 |
:class:`Scrollbar` and :class:`PanedWindow`. |
| 6449 |
|
| 6450 |
.. data:: CHAR |
| 6451 |
WORD |
| 6452 |
|
| 6453 |
Values for the *wrap* option of the :class:`Text` widget, selecting line |
| 6454 |
wrapping on character or word boundaries. |
| 6455 |
|
| 6456 |
.. data:: BASELINE |
| 6457 |
|
| 6458 |
The text-alignment value ``'baseline'``. |
| 6459 |
|
| 6460 |
.. data:: INSIDE |
| 6461 |
OUTSIDE |
| 6462 |
|
| 6463 |
Values for the *bordermode* option of the placer (see |
| 6464 |
:meth:`Place.place_configure`). |
| 6465 |
|
| 6466 |
.. data:: INSERT |
| 6467 |
CURRENT |
| 6468 |
END |
| 6469 |
ANCHOR |
| 6470 |
SEL |
| 6471 |
SEL_FIRST |
| 6472 |
SEL_LAST |
| 6473 |
|
| 6474 |
Symbolic indices used by the :class:`Text`, :class:`Entry`, :class:`Listbox` |
| 6475 |
and :class:`Canvas` widgets, such as ``'insert'`` (the insertion cursor), |
| 6476 |
``'current'``, ``'end'``, ``'anchor'`` and the bounds of the selection |
| 6477 |
(``'sel.first'`` and ``'sel.last'``). |
| 6478 |
|
| 6479 |
.. data:: ALL |
| 6480 |
|
| 6481 |
The special tag ``'all'``, which matches every item of a :class:`Canvas` or |
| 6482 |
every character of a :class:`Text` (for example ``canvas.delete(ALL)``). |
| 6483 |
|
| 6484 |
.. data:: NORMAL |
| 6485 |
DISABLED |
| 6486 |
ACTIVE |
| 6487 |
HIDDEN |
| 6488 |
|
| 6489 |
Values for the *state* option of various widgets and items. |
| 6490 |
|
| 6491 |
.. data:: CASCADE |
| 6492 |
CHECKBUTTON |
| 6493 |
COMMAND |
| 6494 |
RADIOBUTTON |
| 6495 |
SEPARATOR |
| 6496 |
|
| 6497 |
Menu entry types, used as the *itemType* argument of :meth:`Menu.add` and |
| 6498 |
:meth:`Menu.insert`. |
| 6499 |
|
| 6500 |
.. data:: SINGLE |
| 6501 |
BROWSE |
| 6502 |
MULTIPLE |
| 6503 |
EXTENDED |
| 6504 |
|
| 6505 |
Values for the *selectmode* option of the :class:`Listbox` widget. |
| 6506 |
|
| 6507 |
.. data:: PIESLICE |
| 6508 |
CHORD |
| 6509 |
ARC |
| 6510 |
|
| 6511 |
Values for the *style* option of :class:`Canvas` arc items. |
| 6512 |
|
| 6513 |
.. data:: BUTT |
| 6514 |
PROJECTING |
| 6515 |
ROUND |
| 6516 |
BEVEL |
| 6517 |
MITER |
| 6518 |
|
| 6519 |
Values for the *capstyle* (``'butt'``, ``'projecting'``, ``'round'``) and |
| 6520 |
*joinstyle* (``'round'``, ``'bevel'``, ``'miter'``) options of |
| 6521 |
:class:`Canvas` line items. |
| 6522 |
|
| 6523 |
.. data:: FIRST |
| 6524 |
LAST |
| 6525 |
|
| 6526 |
Values for the *arrow* option of :class:`Canvas` line items, indicating |
| 6527 |
which ends have arrowheads. |
| 6528 |
|
| 6529 |
.. data:: MOVETO |
| 6530 |
SCROLL |
| 6531 |
|
| 6532 |
The first argument passed by a :class:`Scrollbar` to the :meth:`XView.xview` |
| 6533 |
or :meth:`YView.yview` method of the scrolled widget. |
| 6534 |
|
| 6535 |
.. data:: UNITS |
| 6536 |
PAGES |
| 6537 |
|
| 6538 |
Values for the *what* argument of :meth:`XView.xview_scroll` and |
| 6539 |
:meth:`YView.yview_scroll`. |
| 6540 |
|
| 6541 |
.. data:: UNDERLINE |
| 6542 |
NUMERIC |
| 6543 |
DOTBOX |
| 6544 |
|
| 6545 |
Other option values: ``'underline'``, ``'numeric'`` and ``'dotbox'``. |