Debian Codegraph @

Doc/library/tkinter.rst

raw
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'``.