Debian Codegraph @

Doc/library/tkinter.ttk.rst

raw
1 :mod:`!tkinter.ttk` --- Tk themed widgets
2 =========================================
3
4 .. module:: tkinter.ttk
5 :synopsis: Tk themed widget set
6
7 .. sectionauthor:: Guilherme Polo <[email protected]>
8
9 **Source code:** :source:`Lib/tkinter/ttk.py`
10
11 .. index:: single: ttk
12
13 --------------
14
15 The :mod:`!tkinter.ttk` module provides access to the Tk themed widget set,
16 introduced in Tk 8.5.
17 Its widgets adapt their appearance to the platform's native theme,
18 giving an application a better and more consistent look and feel
19 than the classic :mod:`tkinter` widgets, whose appearance is fixed.
20
21 The basic idea for :mod:`tkinter.ttk` is to separate, to the extent possible,
22 the code implementing a widget's behavior from the code implementing its
23 appearance.
24
25 Ttk widgets are used just like the classic :mod:`tkinter` widgets
26 and share the same machinery:
27 the widget hierarchy, the geometry managers, variable coupling and event binding.
28 Those foundational concepts are covered in the :mod:`tkinter` documentation
29 and are not repeated here.
30
31 .. versionadded:: 3.1
32
33
34 .. seealso::
35
36 `Tk Widget Styling Support (TIP #48) <https://tip.tcl-lang.org/48.html>`_
37 The Tcl Improvement Proposal that introduced the themed widget styling engine.
38
39
40 Using Ttk
41 ---------
42
43 To start using Ttk, import its module::
44
45 from tkinter import ttk
46
47 To override the basic Tk widgets, the import should follow the Tk import::
48
49 from tkinter import *
50 from tkinter.ttk import *
51
52 That code causes several :mod:`tkinter.ttk` widgets (:class:`Button`,
53 :class:`Checkbutton`, :class:`Entry`, :class:`Frame`, :class:`Label`,
54 :class:`LabelFrame`, :class:`Menubutton`, :class:`OptionMenu`,
55 :class:`PanedWindow`, :class:`Radiobutton`, :class:`Scale`,
56 :class:`Scrollbar` and :class:`Spinbox`) to
57 automatically replace the Tk widgets.
58
59 .. note::
60
61 Overriding the classic widgets with ``from tkinter.ttk import *``
62 is convenient for adapting existing code,
63 but new code is usually clearer if it imports the module
64 as ``from tkinter import ttk`` and refers to the themed widgets explicitly,
65 such as ``ttk.Button``.
66
67 This has the direct benefit of using the new widgets which gives a better look
68 and feel across platforms; however, the replacement widgets are not completely
69 compatible.
70 The main difference is that widget options such as ``fg``, ``bg`` and others
71 related to widget styling are no longer present in Ttk widgets.
72 Instead, use the :class:`ttk.Style <Style>` class for improved styling effects.
73
74
75 Ttk widgets
76 -----------
77
78 Ttk comes with 18 widgets, twelve of which already existed in tkinter:
79 :class:`Button`, :class:`Checkbutton`, :class:`Entry`, :class:`Frame`,
80 :class:`Label`, :class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`,
81 :class:`Radiobutton`, :class:`Scale`, :class:`Scrollbar`, and :class:`Spinbox`.
82 The other six are new: :class:`Combobox`, :class:`Notebook`,
83 :class:`Progressbar`, :class:`Separator`, :class:`Sizegrip` and
84 :class:`Treeview`. All of them are subclasses of :class:`Widget`.
85
86 Using the Ttk widgets gives the application an improved look and feel.
87 As discussed above, there are differences in how the styling is coded.
88
89 Tk code::
90
91 l1 = tkinter.Label(text="Test", fg="black", bg="white")
92 l2 = tkinter.Label(text="Test", fg="black", bg="white")
93
94
95 Ttk code::
96
97 style = ttk.Style()
98 style.configure("BW.TLabel", foreground="black", background="white")
99
100 l1 = ttk.Label(text="Test", style="BW.TLabel")
101 l2 = ttk.Label(text="Test", style="BW.TLabel")
102
103 For more information about TtkStyling_, see the :class:`Style` class
104 documentation.
105
106 Widget
107 ------
108
109 :class:`ttk.Widget <Widget>` defines standard options and methods supported by
110 Tk themed widgets and is not supposed to be directly instantiated.
111
112
113 Standard options
114 ^^^^^^^^^^^^^^^^
115
116 All the :mod:`!ttk` Widgets accept the following options:
117
118 .. tabularcolumns:: |l|L|
119
120 +-----------+--------------------------------------------------------------+
121 | Option | Description |
122 +===========+==============================================================+
123 | class | Specifies the window class. The class is used when querying |
124 | | the option database for the window's other options, to |
125 | | determine the default bindtags for the window, and to select |
126 | | the widget's default layout and style. This option is |
127 | | read-only, and may only be specified when the window is |
128 | | created. |
129 +-----------+--------------------------------------------------------------+
130 | cursor | Specifies the mouse cursor to be used for the widget. See |
131 | | the *cursor* option type under :ref:`Tk-option-data-types`. |
132 | | If set to the empty string (the default), the cursor is |
133 | | inherited from the parent widget. |
134 +-----------+--------------------------------------------------------------+
135 | takefocus | Determines whether the window accepts the focus during |
136 | | keyboard traversal. 0, 1 or an empty string is returned. |
137 | | If 0 is returned, it means that the window should be skipped |
138 | | entirely during keyboard traversal. If 1, it means that the |
139 | | window should receive the input focus as long as it is |
140 | | viewable. And an empty string means that the traversal |
141 | | scripts make the decision about whether or not to focus |
142 | | on the window. |
143 +-----------+--------------------------------------------------------------+
144 | style | May be used to specify a custom widget style. |
145 +-----------+--------------------------------------------------------------+
146
147
148 Scrollable widget options
149 ^^^^^^^^^^^^^^^^^^^^^^^^^
150
151 The following options are supported by widgets that are controlled by a
152 scrollbar.
153
154 .. tabularcolumns:: |l|L|
155
156 +----------------+---------------------------------------------------------+
157 | Option | Description |
158 +================+=========================================================+
159 | xscrollcommand | Used to communicate with horizontal scrollbars. |
160 | | |
161 | | When the view in the widget's window changes, the widget|
162 | | calls the *xscrollcommand* callback. |
163 | | |
164 | | Usually this option consists of the method |
165 | | :meth:`Scrollbar.set <tkinter.Scrollbar.set>` of some |
166 | | scrollbar. This will cause the scrollbar to be updated |
167 | | whenever the view in the window changes. |
168 +----------------+---------------------------------------------------------+
169 | yscrollcommand | Used to communicate with vertical scrollbars. |
170 | | For some more information, see above. |
171 +----------------+---------------------------------------------------------+
172
173
174 Label options
175 ^^^^^^^^^^^^^
176
177 The following options are supported by labels, buttons and other button-like
178 widgets.
179
180 .. tabularcolumns:: |l|p{0.7\linewidth}|
181
182 +--------------+-----------------------------------------------------------+
183 | Option | Description |
184 +==============+===========================================================+
185 | text | Specifies a text string to be displayed inside the widget.|
186 +--------------+-----------------------------------------------------------+
187 | textvariable | Specifies a name whose value will be used in place of the |
188 | | text option resource. |
189 +--------------+-----------------------------------------------------------+
190 | underline | If set, specifies the index (0-based) of a character to |
191 | | underline in the text string. The underline character is |
192 | | used for mnemonic activation. |
193 +--------------+-----------------------------------------------------------+
194 | image | Specifies an image to display. This is a list of 1 or more|
195 | | elements. The first element is the default image name. The|
196 | | rest of the list if a sequence of statespec/value pairs as|
197 | | defined by :meth:`Style.map`, specifying different images |
198 | | to use when the widget is in a particular state or a |
199 | | combination of states. All images in the list should have |
200 | | the same size. |
201 +--------------+-----------------------------------------------------------+
202 | compound | Specifies how to display the image relative to the text, |
203 | | in the case both text and images options are present. |
204 | | Valid values are: |
205 | | |
206 | | * text: display text only |
207 | | * image: display image only |
208 | | * top, bottom, left, right: display image above, below, |
209 | | left of, or right of the text, respectively. |
210 | | * none: the default. display the image if present, |
211 | | otherwise the text. |
212 +--------------+-----------------------------------------------------------+
213 | width | If greater than zero, specifies how much space, in |
214 | | character widths, to allocate for the text label, if less |
215 | | than zero, specifies a minimum width. If zero or |
216 | | unspecified, the natural width of the text label is used. |
217 +--------------+-----------------------------------------------------------+
218
219
220 Compatibility options
221 ^^^^^^^^^^^^^^^^^^^^^
222
223 .. tabularcolumns:: |l|L|
224
225 +--------+----------------------------------------------------------------+
226 | Option | Description |
227 +========+================================================================+
228 | state | May be set to "normal" or "disabled" to control the "disabled" |
229 | | state bit. This is a write-only option: setting it changes the |
230 | | widget state, but the :meth:`Widget.state` method does not |
231 | | affect this option. |
232 +--------+----------------------------------------------------------------+
233
234 Widget states
235 ^^^^^^^^^^^^^
236
237 The widget state is a bitmap of independent state flags.
238
239 .. tabularcolumns:: |l|L|
240
241 +------------+-------------------------------------------------------------+
242 | Flag | Description |
243 +============+=============================================================+
244 | active | The mouse cursor is over the widget and pressing a mouse |
245 | | button will cause some action to occur |
246 +------------+-------------------------------------------------------------+
247 | disabled | Widget is disabled under program control |
248 +------------+-------------------------------------------------------------+
249 | focus | Widget has keyboard focus |
250 +------------+-------------------------------------------------------------+
251 | pressed | Widget is being pressed |
252 +------------+-------------------------------------------------------------+
253 | selected | "On", "true", or "current" for things like Checkbuttons and |
254 | | radiobuttons |
255 +------------+-------------------------------------------------------------+
256 | background | Windows and Mac have a notion of an "active" or foreground |
257 | | window. The *background* state is set for widgets in a |
258 | | background window, and cleared for those in the foreground |
259 | | window |
260 +------------+-------------------------------------------------------------+
261 | readonly | Widget should not allow user modification |
262 +------------+-------------------------------------------------------------+
263 | alternate | A widget-specific alternate display format |
264 +------------+-------------------------------------------------------------+
265 | invalid | The widget's value is invalid |
266 +------------+-------------------------------------------------------------+
267
268 A state specification is a sequence of state names, optionally prefixed with
269 an exclamation point indicating that the bit is off.
270
271
272 ttk.Widget
273 ^^^^^^^^^^
274
275 Besides the methods described below, the :class:`ttk.Widget <Widget>` supports
276 the methods :meth:`tkinter.Widget.cget <tkinter.Misc.cget>` and
277 :meth:`tkinter.Widget.configure <tkinter.Misc.configure>`.
278
279 .. class:: Widget
280
281 .. method:: identify(x, y)
282
283 Returns the name of the element at position *x* *y*, or the empty string
284 if the point does not lie within any element.
285
286 *x* and *y* are pixel coordinates relative to the widget.
287
288
289 .. method:: instate(statespec, callback=None, *args, **kw)
290
291 Test the widget's state. If a callback is not specified, returns ``True``
292 if the widget state matches *statespec* and ``False`` otherwise. If callback
293 is specified then it is called with args if widget state matches
294 *statespec*.
295
296
297 .. method:: state(statespec=None)
298
299 Modify or inquire widget state. If *statespec* is specified, sets the
300 widget state according to it and return a new *statespec* indicating
301 which flags were changed. If *statespec* is not specified, returns
302 the currently enabled state flags.
303
304 Not to be confused with :meth:`Wm.state <tkinter.Wm.state>`.
305
306 *statespec* will usually be a list or a tuple.
307
308
309 Combobox
310 --------
311
312 The :class:`ttk.Combobox <Combobox>` widget combines a text field with a
313 pop-down list of values.
314 This widget is a subclass of :class:`Entry`.
315
316 Besides the methods inherited from :class:`Widget`: :meth:`~tkinter.Misc.cget`,
317 :meth:`~tkinter.Misc.configure`, :meth:`~Widget.identify`,
318 :meth:`~Widget.instate` and :meth:`~Widget.state`, and the following inherited
319 from :class:`Entry`: :meth:`~Entry.bbox`, :meth:`~tkinter.Entry.delete`,
320 :meth:`~tkinter.Entry.icursor`, :meth:`~tkinter.Entry.index`,
321 :meth:`~tkinter.Entry.insert`,
322 :meth:`selection* <tkinter.Entry.selection_adjust>`,
323 :meth:`xview* <tkinter.XView.xview>`, it has some other methods, described at
324 :class:`ttk.Combobox <Combobox>`.
325
326
327 Options
328 ^^^^^^^
329
330 This widget accepts the following specific options:
331
332 .. tabularcolumns:: |l|L|
333
334 +-----------------+--------------------------------------------------------+
335 | Option | Description |
336 +=================+========================================================+
337 | exportselection | Boolean value. If set, the widget selection is linked |
338 | | to the X selection (which can be returned |
339 | | by invoking Misc.selection_get, for example). |
340 +-----------------+--------------------------------------------------------+
341 | justify | Specifies how the text is aligned within the widget. |
342 | | One of "left", "center", or "right". |
343 +-----------------+--------------------------------------------------------+
344 | height | Specifies the height of the pop-down listbox, in rows. |
345 +-----------------+--------------------------------------------------------+
346 | postcommand | A script (possibly registered with Misc.register) that |
347 | | is called immediately before displaying the values. It |
348 | | may specify which values to display. |
349 +-----------------+--------------------------------------------------------+
350 | state | One of "normal", "readonly", or "disabled". In the |
351 | | "readonly" state, the value may not be edited directly,|
352 | | and the user can only select one of the values from the|
353 | | dropdown list. In the "normal" state, the text field is|
354 | | directly editable. In the "disabled" state, no |
355 | | interaction is possible. |
356 +-----------------+--------------------------------------------------------+
357 | textvariable | Specifies a name whose value is linked to the widget |
358 | | value. Whenever the value associated with that name |
359 | | changes, the widget value is updated, and vice versa. |
360 | | See :class:`tkinter.StringVar`. |
361 +-----------------+--------------------------------------------------------+
362 | values | Specifies the list of values to display in the |
363 | | drop-down listbox. |
364 +-----------------+--------------------------------------------------------+
365 | width | Specifies an integer value indicating the desired width|
366 | | of the entry window, in average-size characters of the |
367 | | widget's font. |
368 +-----------------+--------------------------------------------------------+
369
370 .. note::
371
372 Tk 9.1 added the *locale* option, which selects the locale used to determine
373 word and character boundaries within the text (``"C"`` by default).
374
375
376 Virtual events
377 ^^^^^^^^^^^^^^
378
379 The combobox widgets generates a **<<ComboboxSelected>>** virtual event
380 when the user selects an element from the list of values.
381
382
383 ttk.Combobox
384 ^^^^^^^^^^^^
385
386 .. class:: Combobox
387
388 .. method:: current(newindex=None)
389
390 If *newindex* is specified, sets the combobox value to the element
391 position *newindex*. Otherwise, returns the index of the current value or
392 -1 if the current value is not in the values list.
393
394
395 .. method:: get()
396
397 Returns the current value of the combobox.
398
399
400 .. method:: set(value)
401
402 Sets the value of the combobox to *value*.
403
404
405 Spinbox
406 -------
407
408 The :class:`ttk.Spinbox <Spinbox>` widget is a :class:`ttk.Entry <Entry>`
409 enhanced with increment and decrement arrows.
410 It can be used for numbers or lists of string values.
411 This widget is a subclass of :class:`Entry`.
412 Besides the methods inherited from :class:`Widget`: :meth:`~tkinter.Misc.cget`,
413 :meth:`~tkinter.Misc.configure`, :meth:`~Widget.identify`,
414 :meth:`~Widget.instate` and :meth:`~Widget.state`, and the following inherited
415 from :class:`Entry`: :meth:`~Entry.bbox`, :meth:`~tkinter.Entry.delete`,
416 :meth:`~tkinter.Entry.icursor`, :meth:`~tkinter.Entry.index`,
417 :meth:`~tkinter.Entry.insert`, :meth:`xview* <tkinter.XView.xview>`, it has
418 some other methods, described at :class:`ttk.Spinbox <Spinbox>`.
419
420 Options
421 ^^^^^^^
422
423 This widget accepts the following specific options:
424
425 .. tabularcolumns:: |l|L|
426
427 +----------------------+------------------------------------------------------+
428 | Option | Description |
429 +======================+======================================================+
430 | from | Float value. If set, this is the minimum value to |
431 | | which the decrement button will decrement. Must be |
432 | | spelled as ``from_`` when used as an argument, since |
433 | | ``from`` is a Python keyword. |
434 +----------------------+------------------------------------------------------+
435 | to | Float value. If set, this is the maximum value to |
436 | | which the increment button will increment. |
437 +----------------------+------------------------------------------------------+
438 | increment | Float value. Specifies the amount which the |
439 | | increment/decrement buttons change the |
440 | | value. Defaults to 1.0. |
441 +----------------------+------------------------------------------------------+
442 | values | Sequence of string or float values. If specified, |
443 | | the increment/decrement buttons will cycle through |
444 | | the items in this sequence rather than incrementing |
445 | | or decrementing numbers. |
446 | | |
447 +----------------------+------------------------------------------------------+
448 | wrap | Boolean value. If ``True``, increment and decrement |
449 | | buttons will cycle from the ``to`` value to the |
450 | | ``from`` value or the ``from`` value to the ``to`` |
451 | | value, respectively. |
452 +----------------------+------------------------------------------------------+
453 | format | String value. This specifies the format of numbers |
454 | | set by the increment/decrement buttons. It must be |
455 | | in the form "%W.Pf", where W is the padded width of |
456 | | the value, P is the precision, and '%' and 'f' are |
457 | | literal. |
458 +----------------------+------------------------------------------------------+
459 | command | Python callable. Will be called with no arguments |
460 | | whenever either of the increment or decrement buttons|
461 | | are pressed. |
462 | | |
463 +----------------------+------------------------------------------------------+
464
465
466 Virtual events
467 ^^^^^^^^^^^^^^
468
469 The spinbox widget generates an **<<Increment>>** virtual event when the
470 user presses <Up>, and a **<<Decrement>>** virtual event when the user
471 presses <Down>.
472
473 ttk.Spinbox
474 ^^^^^^^^^^^^
475
476 .. class:: Spinbox
477
478 With a non-integer increment, see :ref:`numeric values and the locale
479 <tkinter-numeric-locale>`.
480
481 .. versionadded:: 3.8
482
483 .. method:: get()
484
485 Returns the current value of the spinbox.
486
487
488 .. method:: set(value)
489
490 Sets the value of the spinbox to *value*.
491
492
493
494 Notebook
495 --------
496
497 Ttk Notebook widget manages a collection of windows and displays a single
498 one at a time. Each child window is associated with a tab, which the user
499 may select to change the currently displayed window.
500
501
502 Options
503 ^^^^^^^
504
505 This widget accepts the following specific options:
506
507 .. tabularcolumns:: |l|L|
508
509 +---------+----------------------------------------------------------------+
510 | Option | Description |
511 +=========+================================================================+
512 | height | If present and greater than zero, specifies the desired height |
513 | | of the pane area (not including internal padding or tabs). |
514 | | Otherwise, the maximum height of all panes is used. |
515 +---------+----------------------------------------------------------------+
516 | padding | Specifies the amount of extra space to add around the outside |
517 | | of the notebook. The padding is a list up to four length |
518 | | specifications left top right bottom. If fewer than four |
519 | | elements are specified, bottom defaults to top, right defaults |
520 | | to left, and top defaults to left. |
521 +---------+----------------------------------------------------------------+
522 | width | If present and greater than zero, specified the desired width |
523 | | of the pane area (not including internal padding). Otherwise, |
524 | | the maximum width of all panes is used. |
525 +---------+----------------------------------------------------------------+
526
527
528 Tab options
529 ^^^^^^^^^^^
530
531 There are also specific options for tabs:
532
533 .. tabularcolumns:: |l|L|
534
535 +-----------+--------------------------------------------------------------+
536 | Option | Description |
537 +===========+==============================================================+
538 | state | Either "normal", "disabled" or "hidden". If "disabled", then |
539 | | the tab is not selectable. If "hidden", then the tab is not |
540 | | shown. |
541 +-----------+--------------------------------------------------------------+
542 | sticky | Specifies how the child window is positioned within the pane |
543 | | area. Value is a string containing zero or more of the |
544 | | characters "n", "s", "e" or "w". Each letter refers to a |
545 | | side (north, south, east or west) that the child window will |
546 | | stick to, as per the :meth:`grid <tkinter.Grid.grid>` |
547 | | geometry manager. |
548 +-----------+--------------------------------------------------------------+
549 | padding | Specifies the amount of extra space to add between the |
550 | | notebook and this pane. Syntax is the same as for the option |
551 | | padding used by this widget. |
552 +-----------+--------------------------------------------------------------+
553 | text | Specifies a text to be displayed in the tab. |
554 +-----------+--------------------------------------------------------------+
555 | image | Specifies an image to display in the tab. See the option |
556 | | image described in :class:`Widget`. |
557 +-----------+--------------------------------------------------------------+
558 | compound | Specifies how to display the image relative to the text, in |
559 | | the case both options text and image are present. See |
560 | | `Label Options`_ for legal values. |
561 +-----------+--------------------------------------------------------------+
562 | underline | Specifies the index (0-based) of a character to underline in |
563 | | the text string. The underlined character is used for |
564 | | mnemonic activation if :meth:`Notebook.enable_traversal` is |
565 | | called. |
566 +-----------+--------------------------------------------------------------+
567
568
569 Tab identifiers
570 ^^^^^^^^^^^^^^^
571
572 The tab_id present in several methods of :class:`ttk.Notebook <Notebook>` may
573 take any of the following forms:
574
575 * An integer between zero and the number of tabs
576 * The name of a child window
577 * A positional specification of the form "@x,y", which identifies the tab
578 * The literal string "current", which identifies the currently selected tab
579 * The literal string "end", which returns the number of tabs (only valid for
580 :meth:`Notebook.index`)
581
582
583 Virtual events
584 ^^^^^^^^^^^^^^
585
586 This widget generates a **<<NotebookTabChanged>>** virtual event after a new
587 tab is selected.
588
589
590 ttk.Notebook
591 ^^^^^^^^^^^^
592
593 .. class:: Notebook
594
595 .. method:: add(child, **kw)
596
597 Adds a new tab to the notebook.
598
599 If window is currently managed by the notebook but hidden, it is
600 restored to its previous position.
601
602 See `Tab Options`_ for the list of available options.
603
604
605 .. method:: forget(tab_id)
606
607 Removes the tab specified by *tab_id*, unmaps and unmanages the
608 associated window.
609
610 This shadows the inherited geometry-manager :meth:`!forget`;
611 use :meth:`~tkinter.Pack.pack_forget`, :meth:`~tkinter.Grid.grid_forget`
612 or :meth:`~tkinter.Place.place_forget` to remove the widget itself from
613 its manager.
614
615
616 .. method:: hide(tab_id)
617
618 Hides the tab specified by *tab_id*.
619
620 The tab will not be displayed, but the associated window remains
621 managed by the notebook and its configuration remembered. Hidden tabs
622 may be restored with the :meth:`add` command.
623
624
625 .. method:: identify(x, y)
626
627 Returns the name of the tab element at position *x*, *y*, or the empty
628 string if none.
629
630
631 .. method:: index(tab_id)
632
633 Returns the numeric index of the tab specified by *tab_id*, or the total
634 number of tabs if *tab_id* is the string "end".
635
636
637 .. method:: insert(pos, child, **kw)
638
639 Inserts a pane at the specified position.
640
641 *pos* is either the string "end", an integer index, or the name of a
642 managed child. If *child* is already managed by the notebook, moves it to
643 the specified position.
644
645 See `Tab Options`_ for the list of available options.
646
647
648 .. method:: select(tab_id=None)
649
650 Selects the specified *tab_id*.
651
652 The associated child window will be displayed, and the
653 previously selected window (if different) is unmapped. If *tab_id* is
654 omitted, returns the widget name of the currently selected pane.
655
656
657 .. method:: tab(tab_id, option=None, **kw)
658
659 Query or modify the options of the specific *tab_id*.
660
661 If *kw* is not given, returns a dictionary of the tab option values. If
662 *option* is specified, returns the value of that *option*. Otherwise,
663 sets the options to the corresponding values.
664
665
666 .. method:: tabs()
667
668 Returns a tuple of windows managed by the notebook.
669
670
671 .. method:: enable_traversal()
672
673 Enable keyboard traversal for a toplevel window containing this notebook.
674
675 This will extend the bindings for the toplevel window containing the
676 notebook as follows:
677
678 * :kbd:`Control-Tab`: selects the tab following the currently selected one.
679 * :kbd:`Shift-Control-Tab`: selects the tab preceding the currently selected one.
680 * :kbd:`Alt-K`: where *K* is the mnemonic (underlined) character of any tab, will
681 select that tab.
682
683 Multiple notebooks in a single toplevel may be enabled for traversal,
684 including nested notebooks.
685 However, notebook traversal only works properly if all panes are direct
686 children of the notebook.
687
688
689 Progressbar
690 -----------
691
692 The :class:`ttk.Progressbar <Progressbar>` widget shows the status of a
693 long-running operation.
694 It can operate in two modes: 1) the determinate mode which shows the amount
695 completed relative to the total amount of work to be done and 2) the
696 indeterminate mode which provides an animated display to let the user know that
697 work is progressing.
698
699
700 Options
701 ^^^^^^^
702
703 This widget accepts the following specific options:
704
705 .. tabularcolumns:: |l|L|
706
707 +----------+---------------------------------------------------------------+
708 | Option | Description |
709 +==========+===============================================================+
710 | orient | One of "horizontal" or "vertical". Specifies the orientation |
711 | | of the progress bar. |
712 +----------+---------------------------------------------------------------+
713 | length | Specifies the length of the long axis of the progress bar |
714 | | (width if horizontal, height if vertical). |
715 +----------+---------------------------------------------------------------+
716 | mode | One of "determinate" or "indeterminate". |
717 +----------+---------------------------------------------------------------+
718 | maximum | A number specifying the maximum value. Defaults to 100. |
719 +----------+---------------------------------------------------------------+
720 | value | The current value of the progress bar. In "determinate" mode, |
721 | | this represents the amount of work completed. In |
722 | | "indeterminate" mode, it is interpreted as modulo *maximum*; |
723 | | that is, the progress bar completes one "cycle" when its value|
724 | | increases by *maximum*. |
725 +----------+---------------------------------------------------------------+
726 | variable | A name which is linked to the option value. If specified, the |
727 | | value of the progress bar is automatically set to the value of|
728 | | this name whenever the latter is modified. |
729 +----------+---------------------------------------------------------------+
730 | phase | Read-only option. The widget periodically increments the value|
731 | | of this option whenever its value is greater than 0 and, in |
732 | | determinate mode, less than maximum. This option may be used |
733 | | by the current theme to provide additional animation effects. |
734 +----------+---------------------------------------------------------------+
735
736
737 ttk.Progressbar
738 ^^^^^^^^^^^^^^^
739
740 .. class:: Progressbar
741
742 .. method:: start(interval=None)
743
744 Begin autoincrement mode: schedules a recurring timer event that calls
745 :meth:`Progressbar.step` every *interval* milliseconds. If omitted,
746 *interval* defaults to 50 milliseconds.
747
748
749 .. method:: step(amount=None)
750
751 Increments the progress bar's value by *amount*.
752
753 *amount* defaults to 1.0 if omitted.
754
755
756 .. method:: stop()
757
758 Stop autoincrement mode: cancels any recurring timer event initiated by
759 :meth:`Progressbar.start` for this progress bar.
760
761
762 Separator
763 ---------
764
765 The :class:`ttk.Separator <Separator>` widget displays a horizontal or vertical
766 separator bar.
767
768 It has no other methods besides the ones inherited from
769 :class:`ttk.Widget <Widget>`.
770
771
772 Options
773 ^^^^^^^
774
775 This widget accepts the following specific option:
776
777 .. tabularcolumns:: |l|L|
778
779 +--------+----------------------------------------------------------------+
780 | Option | Description |
781 +========+================================================================+
782 | orient | One of "horizontal" or "vertical". Specifies the orientation of|
783 | | the separator. |
784 +--------+----------------------------------------------------------------+
785
786
787 Sizegrip
788 --------
789
790 The :class:`ttk.Sizegrip <Sizegrip>` widget (also known as a grow box) allows
791 the user to resize the containing toplevel window by pressing and dragging the
792 grip.
793
794 This widget has neither specific options nor specific methods, besides the
795 ones inherited from :class:`ttk.Widget <Widget>`.
796
797
798 Platform-specific notes
799 ^^^^^^^^^^^^^^^^^^^^^^^
800
801 * On macOS, toplevel windows automatically include a built-in size grip
802 by default. Adding a :class:`Sizegrip` is harmless, since the built-in
803 grip will just mask the widget.
804
805
806 Bugs
807 ^^^^
808
809 * If the containing toplevel's position was specified relative to the right
810 or bottom of the screen (for example, ....), the :class:`Sizegrip` widget
811 will not resize the window.
812 * This widget supports only "southeast" resizing.
813
814
815 Treeview
816 --------
817
818 The :class:`ttk.Treeview <Treeview>` widget displays a hierarchical collection
819 of items.
820 Each item has a textual label, an optional image, and an optional list of data
821 values.
822 The data values are displayed in successive columns after the tree label.
823
824 The order in which data values are displayed may be controlled by setting
825 the widget option ``displaycolumns``. The tree widget can also display column
826 headings. Columns may be accessed by number or symbolic names listed in the
827 widget option columns. See `Column Identifiers`_.
828
829 Each item is identified by a unique name. The widget will generate item IDs
830 if they are not supplied by the caller. There is a distinguished root item,
831 named ``{}``. The root item itself is not displayed; its children appear at the
832 top level of the hierarchy.
833
834 Each item also has a list of tags, which can be used to associate event bindings
835 with individual items and control the appearance of the item.
836
837 The Treeview widget supports horizontal and vertical scrolling, according to
838 the options described in `Scrollable Widget Options`_ and the methods
839 :meth:`Treeview.xview` and :meth:`Treeview.yview`.
840
841
842 Options
843 ^^^^^^^
844
845 This widget accepts the following specific options:
846
847 .. tabularcolumns:: |l|p{0.7\linewidth}|
848
849 +----------------+--------------------------------------------------------+
850 | Option | Description |
851 +================+========================================================+
852 | columns | A list of column identifiers, specifying the number of |
853 | | columns and their names. |
854 +----------------+--------------------------------------------------------+
855 | displaycolumns | A list of column identifiers (either symbolic or |
856 | | integer indices) specifying which data columns are |
857 | | displayed and the order in which they appear, or the |
858 | | string "#all". |
859 +----------------+--------------------------------------------------------+
860 | height | Specifies the number of rows which should be visible. |
861 | | Note: the requested width is determined from the sum |
862 | | of the column widths. |
863 +----------------+--------------------------------------------------------+
864 | padding | Specifies the internal padding for the widget. The |
865 | | padding is a list of up to four length specifications. |
866 +----------------+--------------------------------------------------------+
867 | selectmode | Controls how the built-in class bindings manage the |
868 | | selection. One of "extended", "browse" or "none". |
869 | | If set to "extended" (the default), multiple items may |
870 | | be selected. If "browse", only a single item will be |
871 | | selected at a time. If "none", the selection will not |
872 | | be changed. |
873 | | |
874 | | Note that the application code and tag bindings can set|
875 | | the selection however they wish, regardless of the |
876 | | value of this option. |
877 +----------------+--------------------------------------------------------+
878 | show | A list containing zero or more of the following values,|
879 | | specifying which elements of the tree to display. |
880 | | |
881 | | * tree: display tree labels in column #0. |
882 | | * headings: display the heading row. |
883 | | |
884 | | The default is "tree headings", that is, show all |
885 | | elements. |
886 | | |
887 | | **Note**: Column #0 always refers to the tree column, |
888 | | even if show="tree" is not specified. |
889 +----------------+--------------------------------------------------------+
890
891 .. note::
892
893 Tk 9.0 added several :class:`Treeview` features.
894 The *selectmode* option gained the values ``"single"`` and ``"multiple"``;
895 the new widget options *selecttype* (``"item"`` or ``"cell"`` selection),
896 *striped* (zebra-striped rows), and *titlecolumns* / *titleitems* (columns
897 or rows frozen against scrolling) were introduced; the column *separator*
898 option was added; and items gained a *hidden* option.
899 Tk 9.1 added the *rowheight* and *headingheight* options.
900
901
902 Item options
903 ^^^^^^^^^^^^
904
905 The following item options may be specified for items in the insert and item
906 widget commands.
907
908 .. tabularcolumns:: |l|L|
909
910 +--------+---------------------------------------------------------------+
911 | Option | Description |
912 +========+===============================================================+
913 | text | The textual label to display for the item. |
914 +--------+---------------------------------------------------------------+
915 | image | A Tk Image, displayed to the left of the label. |
916 +--------+---------------------------------------------------------------+
917 | values | The list of values associated with the item. |
918 | | |
919 | | Each item should have the same number of values as the widget |
920 | | option columns. If there are fewer values than columns, the |
921 | | remaining values are assumed empty. If there are more values |
922 | | than columns, the extra values are ignored. |
923 +--------+---------------------------------------------------------------+
924 | open | ``True``/``False`` value indicating whether the item's |
925 | | children should be displayed or hidden. |
926 +--------+---------------------------------------------------------------+
927 | tags | A list of tags associated with this item. |
928 +--------+---------------------------------------------------------------+
929
930
931 Tag options
932 ^^^^^^^^^^^
933
934 The following options may be specified on tags:
935
936 .. tabularcolumns:: |l|L|
937
938 +------------+-----------------------------------------------------------+
939 | Option | Description |
940 +============+===========================================================+
941 | foreground | Specifies the text foreground color. |
942 +------------+-----------------------------------------------------------+
943 | background | Specifies the cell or item background color. |
944 +------------+-----------------------------------------------------------+
945 | font | Specifies the font to use when drawing text. |
946 +------------+-----------------------------------------------------------+
947 | image | Specifies the item image, in case the item's image option |
948 | | is empty. |
949 +------------+-----------------------------------------------------------+
950
951
952 Column identifiers
953 ^^^^^^^^^^^^^^^^^^
954
955 Column identifiers take any of the following forms:
956
957 * A symbolic name from the list of columns option.
958 * An integer n, specifying the nth data column.
959 * A string of the form #n, where n is an integer, specifying the nth display
960 column.
961
962 Notes:
963
964 * Item's option values may be displayed in a different order than the order
965 in which they are stored.
966 * Column #0 always refers to the tree column, even if show="tree" is not
967 specified.
968
969 A data column number is an index into an item's option values list; a display
970 column number is the column number in the tree where the values are displayed.
971 Tree labels are displayed in column #0. If option displaycolumns is not set,
972 then data column n is displayed in column #n+1. Again, **column #0 always
973 refers to the tree column**.
974
975
976 Virtual events
977 ^^^^^^^^^^^^^^
978
979 The Treeview widget generates the following virtual events.
980
981 .. tabularcolumns:: |l|L|
982
983 +--------------------+--------------------------------------------------+
984 | Event | Description |
985 +====================+==================================================+
986 | <<TreeviewSelect>> | Generated whenever the selection changes. |
987 +--------------------+--------------------------------------------------+
988 | <<TreeviewOpen>> | Generated just before settings the focus item to |
989 | | open=True. |
990 +--------------------+--------------------------------------------------+
991 | <<TreeviewClose>> | Generated just after setting the focus item to |
992 | | open=False. |
993 +--------------------+--------------------------------------------------+
994
995 The :meth:`Treeview.focus` and :meth:`Treeview.selection` methods can be used
996 to determine the affected item or items.
997
998
999 ttk.Treeview
1000 ^^^^^^^^^^^^
1001
1002 .. class:: Treeview
1003
1004 .. method:: bbox(item, column=None)
1005
1006 Returns the bounding box (relative to the treeview widget's window) of
1007 the specified *item* in the form (x, y, width, height).
1008
1009 If *column* is specified, returns the bounding box of that cell. If the
1010 *item* is not visible (that is, if it is a descendant of a closed item
1011 or is scrolled offscreen), returns an empty string.
1012
1013 This shadows the inherited :meth:`!Misc.bbox`;
1014 use :meth:`~tkinter.Misc.grid_bbox` for the grid bounding box.
1015
1016
1017 .. method:: get_children(item=None)
1018
1019 Returns a tuple of children belonging to *item*.
1020
1021 If *item* is not specified, returns root children.
1022
1023
1024 .. method:: set_children(item, *newchildren)
1025
1026 Replaces *item*'s children with *newchildren*.
1027
1028 Children present in *item* that are not present in *newchildren* are
1029 detached from the tree. No items in *newchildren* may be an ancestor of
1030 *item*. Note that not specifying *newchildren* results in detaching
1031 *item*'s children.
1032
1033
1034 .. method:: column(column, option=None, **kw)
1035
1036 Query or modify the options for the specified *column*.
1037
1038 If *kw* is not given, returns a dict of the column option values. If
1039 *option* is specified then the value for that *option* is returned.
1040 Otherwise, sets the options to the corresponding values.
1041
1042 The valid options/values are:
1043
1044 *id*
1045 Returns the column name. This is a read-only option.
1046 *anchor*: One of the standard Tk anchor values.
1047 Specifies how the text in this column should be aligned with respect
1048 to the cell.
1049 *minwidth*: width
1050 The minimum width of the column in pixels. The treeview widget will
1051 not make the column any smaller than specified by this option when
1052 the widget is resized or the user drags a column.
1053 *separator*: ``True``/``False``
1054 Specifies whether a column separator should be drawn to the right of
1055 the column.
1056 *stretch*: ``True``/``False``
1057 Specifies whether the column's width should be adjusted when
1058 the widget is resized.
1059 *width*: width
1060 The width of the column in pixels.
1061
1062 To configure the tree column, call this with column = "#0"
1063
1064 .. method:: delete(*items)
1065
1066 Delete all specified *items* and all their descendants.
1067
1068 The root item may not be deleted.
1069
1070
1071 .. method:: detach(*items)
1072
1073 Unlinks all of the specified *items* from the tree.
1074
1075 The items and all of their descendants are still present, and may be
1076 reinserted at another point in the tree, but will not be displayed.
1077
1078 The root item may not be detached.
1079
1080
1081 .. method:: exists(item)
1082
1083 Returns ``True`` if the specified *item* is present in the tree,
1084 ``False`` otherwise.
1085
1086
1087 .. method:: focus(item=None)
1088
1089 If *item* is specified, sets the focus item to *item*. Otherwise, returns
1090 the current focus item, or '' if there is none.
1091
1092 This shadows the inherited :meth:`!Misc.focus`;
1093 use :meth:`~tkinter.Misc.focus_set` to focus the widget itself.
1094
1095
1096 .. method:: heading(column, option=None, **kw)
1097
1098 Query or modify the heading options for the specified *column*.
1099
1100 If *kw* is not given, returns a dict of the heading option values. If
1101 *option* is specified then the value for that *option* is returned.
1102 Otherwise, sets the options to the corresponding values.
1103
1104 The valid options/values are:
1105
1106 *text*: text
1107 The text to display in the column heading.
1108 *image*: imageName
1109 Specifies an image to display to the right of the column heading.
1110 *anchor*: anchor
1111 Specifies how the heading text should be aligned. One of the standard
1112 Tk anchor values.
1113 *command*: callback
1114 A callback to be invoked when the heading label is pressed.
1115
1116 To configure the tree column heading, call this with column = "#0".
1117
1118
1119 .. method:: identify(component, x, y)
1120
1121 Returns a description of the specified *component* under the point given
1122 by *x* and *y*, or the empty string if no such *component* is present at
1123 that position.
1124
1125
1126 .. method:: identify_row(y)
1127
1128 Returns the item ID of the item at position *y*.
1129
1130
1131 .. method:: identify_column(x)
1132
1133 Returns the display column identifier of the cell at position *x*.
1134
1135 The tree column has ID #0.
1136
1137
1138 .. method:: identify_region(x, y)
1139
1140 Returns one of:
1141
1142 +-----------+--------------------------------------+
1143 | region | meaning |
1144 +===========+======================================+
1145 | heading | Tree heading area. |
1146 +-----------+--------------------------------------+
1147 | separator | Space between two columns headings. |
1148 +-----------+--------------------------------------+
1149 | tree | The tree area. |
1150 +-----------+--------------------------------------+
1151 | cell | A data cell. |
1152 +-----------+--------------------------------------+
1153
1154 Availability: Tk 8.6.
1155
1156
1157 .. method:: identify_element(x, y)
1158
1159 Returns the element at position *x*, *y*.
1160
1161 Availability: Tk 8.6.
1162
1163
1164 .. method:: index(item)
1165
1166 Returns the integer index of *item* within its parent's list of children.
1167
1168
1169 .. method:: insert(parent, index, iid=None, **kw)
1170
1171 Creates a new item and returns the item identifier of the newly created
1172 item.
1173
1174 *parent* is the item ID of the parent item, or the empty string to create
1175 a new top-level item. *index* is an integer, or the value "end",
1176 specifying where in the list of parent's children to insert the new item.
1177 If *index* is less than or equal to zero, the new node is inserted at
1178 the beginning; if *index* is greater than or equal to the current number
1179 of children, it is inserted at the end. If *iid* is specified, it is used
1180 as the item identifier; *iid* must not already exist in the tree.
1181 Otherwise, a new unique identifier is generated.
1182
1183 See `Item Options`_ for the list of available options.
1184
1185
1186 .. method:: item(item, option=None, **kw)
1187
1188 Query or modify the options for the specified *item*.
1189
1190 If no options are given, a dict with options/values for the item is
1191 returned.
1192 If *option* is specified then the value for that option is returned.
1193 Otherwise, sets the options to the corresponding values as given by *kw*.
1194
1195
1196 .. method:: reattach(item, parent, index)
1197 :no-typesetting:
1198
1199 .. method:: move(item, parent, index)
1200
1201 Moves *item* to position *index* in *parent*'s list of children.
1202
1203 It is illegal to move an item under one of its descendants. If *index* is
1204 less than or equal to zero, *item* is moved to the beginning; if greater
1205 than or equal to the number of children, it is moved to the end. If *item*
1206 was detached it is reattached.
1207
1208 :meth:`reattach` is an alias of :meth:`!move`.
1209
1210
1211 .. method:: next(item)
1212
1213 Returns the identifier of *item*'s next sibling, or '' if *item* is the
1214 last child of its parent.
1215
1216
1217 .. method:: parent(item)
1218
1219 Returns the ID of the parent of *item*, or '' if *item* is at the top
1220 level of the hierarchy.
1221
1222
1223 .. method:: prev(item)
1224
1225 Returns the identifier of *item*'s previous sibling, or '' if *item* is
1226 the first child of its parent.
1227
1228
1229 .. method:: see(item)
1230
1231 Ensure that *item* is visible.
1232
1233 Sets all of *item*'s ancestors open option to ``True``, and scrolls the
1234 widget if necessary so that *item* is within the visible portion of
1235 the tree.
1236
1237
1238 .. method:: selection()
1239
1240 Returns a tuple of selected items.
1241
1242 .. versionchanged:: 3.8
1243 ``selection()`` no longer takes arguments. For changing the selection
1244 state use the following selection methods.
1245
1246
1247 .. method:: selection_set(*items)
1248
1249 *items* becomes the new selection.
1250
1251 .. versionchanged:: 3.6
1252 *items* can be passed as separate arguments, not just as a single tuple.
1253
1254
1255 .. method:: selection_add(*items)
1256
1257 Add *items* to the selection.
1258
1259 .. versionchanged:: 3.6
1260 *items* can be passed as separate arguments, not just as a single tuple.
1261
1262
1263 .. method:: selection_remove(*items)
1264
1265 Remove *items* from the selection.
1266
1267 .. versionchanged:: 3.6
1268 *items* can be passed as separate arguments, not just as a single tuple.
1269
1270
1271 .. method:: selection_toggle(*items)
1272
1273 Toggle the selection state of each item in *items*.
1274
1275 .. versionchanged:: 3.6
1276 *items* can be passed as separate arguments, not just as a single tuple.
1277
1278
1279 .. method:: set(item, column=None, value=None)
1280
1281 With one argument, returns a dictionary of column/value pairs for the
1282 specified *item*. With two arguments, returns the current value of the
1283 specified *column*. With three arguments, sets the value of given
1284 *column* in given *item* to the specified *value*.
1285
1286
1287 .. method:: tag_bind(tagname, sequence=None, callback=None)
1288
1289 Bind a callback for the given event *sequence* to the tag *tagname*.
1290 When an event is delivered to an item, the callbacks for each of the
1291 item's tags option are called.
1292
1293
1294 .. method:: tag_configure(tagname, option=None, **kw)
1295
1296 Query or modify the options for the specified *tagname*.
1297
1298 If *kw* is not given, returns a dict of the option settings for
1299 *tagname*. If *option* is specified, returns the value for that *option*
1300 for the specified *tagname*. Otherwise, sets the options to the
1301 corresponding values for the given *tagname*.
1302
1303
1304 .. method:: tag_has(tagname, item=None)
1305
1306 If *item* is specified, returns ``True`` if the specified *item* has the
1307 given *tagname* and ``False`` otherwise.
1308 Otherwise, returns a tuple of all items that have the specified tag.
1309
1310 Availability: Tk 8.6
1311
1312
1313 .. method:: xview(*args)
1314
1315 Query or modify horizontal position of the treeview.
1316
1317
1318 .. method:: yview(*args)
1319
1320 Query or modify vertical position of the treeview.
1321
1322
1323 .. _TtkStyling:
1324
1325 Ttk styling
1326 -----------
1327
1328 Each widget in :mod:`!ttk` is assigned a style, which specifies the set of
1329 elements making up the widget and how they are arranged, along with dynamic and
1330 default settings for element options.
1331 By default the style name is the same as the widget's class name, but it may be
1332 overridden by the widget's style option.
1333 If you don't know the class name of a widget, use the method
1334 :meth:`Misc.winfo_class <tkinter.Misc.winfo_class>` (somewidget.winfo_class()).
1335
1336 .. seealso::
1337
1338 `Introduction to the Tk theme engine <https://www.tcl-lang.org/man/tcl9.0/TkCmd/ttk_intro.html>`_
1339 The ``ttk::intro`` man page explains how the theme engine works.
1340
1341 `The Tile Widget Set <https://tktable.sourceforge.net/tile/tile-tcl2004.pdf>`_
1342 Joe English's 2004 paper introducing the theme engine
1343 (then the separate *Tile* extension),
1344 with diagrams of how elements and layouts make up a widget's appearance.
1345
1346
1347 .. class:: Style
1348
1349 This class is used to manipulate the style database.
1350
1351
1352 .. method:: configure(style, query_opt=None, **kw)
1353
1354 Query or set the default value of the specified option(s) in *style*.
1355
1356 Each key in *kw* is an option and each value is a string identifying
1357 the value for that option.
1358
1359 For example, to change every default button to be a flat button with
1360 some padding and a different background color::
1361
1362 from tkinter import ttk
1363 import tkinter
1364
1365 root = tkinter.Tk()
1366
1367 ttk.Style().configure("TButton", padding=6, relief="flat",
1368 background="#ccc")
1369
1370 btn = ttk.Button(text="Sample")
1371 btn.pack()
1372
1373 root.mainloop()
1374
1375
1376 .. method:: map(style, query_opt=None, **kw)
1377
1378 Query or sets dynamic values of the specified option(s) in *style*.
1379
1380 Each key in *kw* is an option and each value should be a list or a
1381 tuple (usually) containing statespecs grouped in tuples, lists, or
1382 some other preference. A statespec is a compound of one
1383 or more states and then a value.
1384
1385 An example may make it more understandable::
1386
1387 import tkinter
1388 from tkinter import ttk
1389
1390 root = tkinter.Tk()
1391
1392 style = ttk.Style()
1393 style.map("C.TButton",
1394 foreground=[('pressed', 'red'), ('active', 'blue')],
1395 background=[('pressed', '!disabled', 'black'), ('active', 'white')]
1396 )
1397
1398 colored_btn = ttk.Button(text="Test", style="C.TButton").pack()
1399
1400 root.mainloop()
1401
1402
1403 Note that the order of the (states, value) sequences for an option does
1404 matter, if the order is changed to ``[('active', 'blue'), ('pressed',
1405 'red')]`` in the foreground option, for example, the result would be a
1406 blue foreground when the widget were in active or pressed states.
1407
1408 When called to query the map (without specifying values to set), it
1409 returns a dictionary mapping each option to its list of statespecs.
1410
1411 .. versionchanged:: 3.10
1412 The value returned when querying the map was corrected.
1413
1414
1415 .. method:: lookup(style, option, state=None, default=None)
1416
1417 Returns the value specified for *option* in *style*.
1418
1419 If *state* is specified, it is expected to be a sequence of one or more
1420 states. If the *default* argument is set, it is used as a fallback value
1421 in case no specification for option is found.
1422
1423 To check what font a Button uses by default::
1424
1425 from tkinter import ttk
1426
1427 print(ttk.Style().lookup("TButton", "font"))
1428
1429
1430 .. method:: layout(style, layoutspec=None)
1431
1432 Define the widget layout for given *style*. If *layoutspec* is omitted,
1433 return the layout specification for given style.
1434
1435 *layoutspec*, if specified, is expected to be a list or some other
1436 sequence type (excluding strings), where each item should be a tuple and
1437 the first item is the layout name and the second item should have the
1438 format described in `Layouts`_.
1439
1440 To understand the format, see the following example (it is not
1441 intended to do anything useful)::
1442
1443 from tkinter import ttk
1444 import tkinter
1445
1446 root = tkinter.Tk()
1447
1448 style = ttk.Style()
1449 style.layout("TMenubutton", [
1450 ("Menubutton.background", None),
1451 ("Menubutton.button", {"children":
1452 [("Menubutton.focus", {"children":
1453 [("Menubutton.padding", {"children":
1454 [("Menubutton.label", {"side": "left", "expand": 1})]
1455 })]
1456 })]
1457 }),
1458 ])
1459
1460 mbtn = ttk.Menubutton(text='Text')
1461 mbtn.pack()
1462 root.mainloop()
1463
1464
1465 .. method:: element_create(elementname, etype, *args, **kw)
1466
1467 Create a new element in the current theme, of the given *etype* which is
1468 expected to be either "image", "from" or "vsapi".
1469 The latter is only available in Tk 8.6 on Windows.
1470
1471 If "image" is used, *args* should contain the default image name followed
1472 by statespec/value pairs (this is the imagespec), and *kw* may have the
1473 following options:
1474
1475 border=padding
1476 padding is a list of up to four integers, specifying the left, top,
1477 right, and bottom borders, respectively.
1478
1479 height=height
1480 Specifies a minimum height for the element. If less than zero, the
1481 base image's height is used as a default.
1482
1483 padding=padding
1484 Specifies the element's interior padding. Defaults to border's value
1485 if not specified.
1486
1487 sticky=spec
1488 Specifies how the image is placed within the final parcel. spec
1489 contains zero or more characters "n", "s", "w", or "e".
1490
1491 width=width
1492 Specifies a minimum width for the element. If less than zero, the
1493 base image's width is used as a default.
1494
1495 Example::
1496
1497 img1 = tkinter.PhotoImage(master=root, file='button.png')
1498 img1 = tkinter.PhotoImage(master=root, file='button-pressed.png')
1499 img1 = tkinter.PhotoImage(master=root, file='button-active.png')
1500 style = ttk.Style(root)
1501 style.element_create('Button.button', 'image',
1502 img1, ('pressed', img2), ('active', img3),
1503 border=(2, 4), sticky='we')
1504
1505 If "from" is used as the value of *etype*,
1506 :meth:`element_create` will clone an existing
1507 element. *args* is expected to contain a themename, from which
1508 the element will be cloned, and optionally an element to clone from.
1509 If this element to clone from is not specified, an empty element will
1510 be used. *kw* is discarded.
1511
1512 Example::
1513
1514 style = ttk.Style(root)
1515 style.element_create('plain.background', 'from', 'default')
1516
1517 If "vsapi" is used as the value of *etype*, :meth:`element_create`
1518 will create a new element in the current theme whose visual appearance
1519 is drawn using the Microsoft Visual Styles API which is responsible
1520 for the themed styles on Windows XP and Vista.
1521 *args* is expected to contain the Visual Styles class and part as
1522 given in the Microsoft documentation followed by an optional sequence
1523 of tuples of ttk states and the corresponding Visual Styles API state
1524 value.
1525 *kw* may have the following options:
1526
1527 padding=padding
1528 Specify the element's interior padding.
1529 *padding* is a list of up to four integers specifying the left,
1530 top, right and bottom padding quantities respectively.
1531 If fewer than four elements are specified, bottom defaults to top,
1532 right defaults to left, and top defaults to left.
1533 In other words, a list of three numbers specify the left, vertical,
1534 and right padding; a list of two numbers specify the horizontal
1535 and the vertical padding; a single number specifies the same
1536 padding all the way around the widget.
1537 This option may not be mixed with any other options.
1538
1539 margins=padding
1540 Specifies the elements exterior padding.
1541 *padding* is a list of up to four integers specifying the left, top,
1542 right and bottom padding quantities respectively.
1543 This option may not be mixed with any other options.
1544
1545 width=width
1546 Specifies the width for the element.
1547 If this option is set then the Visual Styles API will not be queried
1548 for the recommended size or the part.
1549 If this option is set then *height* should also be set.
1550 The *width* and *height* options cannot be mixed with the *padding*
1551 or *margins* options.
1552
1553 height=height
1554 Specifies the height of the element.
1555 See the comments for *width*.
1556
1557 Example::
1558
1559 style = ttk.Style(root)
1560 style.element_create('pin', 'vsapi', 'EXPLORERBAR', 3, [
1561 ('pressed', '!selected', 3),
1562 ('active', '!selected', 2),
1563 ('pressed', 'selected', 6),
1564 ('active', 'selected', 5),
1565 ('selected', 4),
1566 ('', 1)])
1567 style.layout('Explorer.Pin',
1568 [('Explorer.Pin.pin', {'sticky': 'news'})])
1569 pin = ttk.Checkbutton(style='Explorer.Pin')
1570 pin.pack(expand=True, fill='both')
1571
1572 .. versionchanged:: 3.13
1573 Added support of the "vsapi" element factory.
1574
1575 .. method:: element_names()
1576
1577 Returns a tuple of elements defined in the current theme.
1578
1579
1580 .. method:: element_options(elementname)
1581
1582 Returns a tuple of *elementname*'s options.
1583
1584
1585 .. method:: theme_create(themename, parent=None, settings=None)
1586
1587 Create a new theme.
1588
1589 It is an error if *themename* already exists. If *parent* is specified,
1590 the new theme will inherit styles, elements and layouts from the parent
1591 theme. If *settings* are present they are expected to have the same
1592 syntax used for :meth:`theme_settings`.
1593
1594
1595 .. method:: theme_settings(themename, settings)
1596
1597 Temporarily sets the current theme to *themename*, apply specified
1598 *settings* and then restore the previous theme.
1599
1600 Each key in *settings* is a style and each value may contain the keys
1601 'configure', 'map', 'layout' and 'element create' and they are expected
1602 to have the same format as specified by the methods
1603 :meth:`Style.configure`, :meth:`Style.map`, :meth:`Style.layout` and
1604 :meth:`Style.element_create` respectively.
1605
1606 As an example, let's change the Combobox for the default theme a bit::
1607
1608 from tkinter import ttk
1609 import tkinter
1610
1611 root = tkinter.Tk()
1612
1613 style = ttk.Style()
1614 style.theme_settings("default", {
1615 "TCombobox": {
1616 "configure": {"padding": 5},
1617 "map": {
1618 "background": [("active", "green2"),
1619 ("!disabled", "green4")],
1620 "fieldbackground": [("!disabled", "green3")],
1621 "foreground": [("focus", "OliveDrab1"),
1622 ("!disabled", "OliveDrab2")]
1623 }
1624 }
1625 })
1626
1627 combo = ttk.Combobox().pack()
1628
1629 root.mainloop()
1630
1631
1632 .. method:: theme_names()
1633
1634 Returns a tuple of all known themes.
1635
1636
1637 .. method:: theme_use(themename=None)
1638
1639 If *themename* is not given, returns the theme in use. Otherwise, sets
1640 the current theme to *themename*, refreshes all widgets and emits a
1641 <<ThemeChanged>> event.
1642
1643
1644 Layouts
1645 ^^^^^^^
1646
1647 A layout can be just ``None``, if it takes no options, or a dict of
1648 options specifying how to arrange the element. The layout mechanism
1649 uses a simplified version of the pack geometry manager: given an
1650 initial cavity, each element is allocated a parcel.
1651
1652 The valid options/values are:
1653
1654 *side*: whichside
1655 Specifies which side of the cavity to place the element; one of
1656 top, right, bottom or left. If omitted, the element occupies the
1657 entire cavity.
1658
1659 *sticky*: nswe
1660 Specifies where the element is placed inside its allocated parcel.
1661
1662 *unit*: 0 or 1
1663 If set to 1, causes the element and all of its descendants to be treated as
1664 a single element for the purposes of :meth:`Widget.identify` et al. It's
1665 used for things like scrollbar thumbs with grips.
1666
1667 *children*: [sublayout... ]
1668 Specifies a list of elements to place inside the element. Each
1669 element is a tuple (or other sequence type) where the first item is
1670 the layout name, and the other is a `Layout`_.
1671
1672 .. _Layout: `Layouts`_
1673
1674
1675 Additional widgets
1676 ------------------
1677
1678 The following themed widgets complete the :mod:`tkinter.ttk` widget set.
1679 Each is the themed counterpart of the like-named classic :mod:`tkinter` widget
1680 and inherits the common methods of :class:`Widget`.
1681
1682 .. class:: Button(master=None, **kw)
1683
1684 Ttk :class:`Button` widget, displays a textual label and/or image, and
1685 evaluates a command when pressed.
1686 It is the themed counterpart of :class:`tkinter.Button` and inherits the
1687 common widget methods from :class:`Widget`.
1688
1689 .. method:: invoke()
1690
1691 Invoke the command associated with the button and return its result.
1692
1693
1694 .. class:: Checkbutton(master=None, **kw)
1695
1696 Ttk :class:`Checkbutton` widget, used to control a boolean variable that is
1697 toggled on and off.
1698 It is the themed counterpart of :class:`tkinter.Checkbutton` and inherits
1699 the common widget methods from :class:`Widget`.
1700
1701 .. method:: invoke()
1702
1703 Toggle the button between its selected and deselected states, invoke the
1704 command associated with the button, and return its result.
1705
1706
1707 .. class:: Entry(master=None, widget=None, **kw)
1708
1709 Ttk :class:`Entry` widget, displays a one-line text string and allows the
1710 user to edit it.
1711 It is the themed counterpart of :class:`tkinter.Entry` and inherits the
1712 common widget methods from :class:`Widget` as well as the editing methods
1713 from :class:`tkinter.Entry`.
1714
1715 .. method:: bbox(index)
1716
1717 Return a tuple ``(x, y, width, height)`` giving the bounding box of the
1718 character at the given *index*.
1719
1720 This shadows the inherited :meth:`!Misc.bbox`;
1721 use :meth:`~tkinter.Misc.grid_bbox` for the grid bounding box.
1722
1723 .. method:: identify(x, y)
1724
1725 Return the name of the element under the point given by *x* and *y*, or
1726 the empty string if no element is present at that location.
1727
1728 .. method:: validate()
1729
1730 Force validation of the entry and return ``True`` if validation
1731 succeeded, and ``False`` otherwise.
1732
1733
1734 .. class:: Frame(master=None, **kw)
1735
1736 Ttk :class:`Frame` widget, a container used to group and lay out other
1737 widgets.
1738 It is the themed counterpart of :class:`tkinter.Frame` and inherits the
1739 common widget methods from :class:`Widget`.
1740
1741
1742 .. class:: Label(master=None, **kw)
1743
1744 Ttk :class:`Label` widget, displays a textual label and/or image.
1745 It is the themed counterpart of :class:`tkinter.Label` and inherits the
1746 common widget methods from :class:`Widget`.
1747
1748
1749 .. class:: Labelframe(master=None, **kw)
1750
1751 Ttk :class:`Labelframe` widget, a container that draws a border and a title
1752 label around its contents.
1753 It is the themed counterpart of :class:`tkinter.LabelFrame` and inherits the
1754 common widget methods from :class:`Widget`.
1755
1756
1757 .. class:: Menubutton(master=None, **kw)
1758
1759 Ttk :class:`Menubutton` widget, displays a textual label and/or image, and
1760 pops up a menu when pressed.
1761 It is the themed counterpart of :class:`tkinter.Menubutton` and inherits the
1762 common widget methods from :class:`Widget`.
1763
1764
1765 .. class:: OptionMenu(master, variable, default=None, *values, **kwargs)
1766
1767 Ttk :class:`OptionMenu` widget, a :class:`Menubutton` that pops up a menu of
1768 mutually exclusive choices.
1769 *variable* is the variable that tracks the currently selected value,
1770 *default* is the value to set initially, and *values* are the entries to
1771 display in the menu.
1772 A *command* keyword argument may be given to specify a callable that is
1773 invoked with the selected value whenever the selection changes; the *style*
1774 keyword argument sets the style used by the underlying menubutton; and the
1775 *direction* keyword argument sets where the menu is posted relative to the
1776 menubutton (one of ``'above'``, ``'below'`` (the default), ``'left'``,
1777 ``'right'`` or ``'flush'``).
1778
1779 .. method:: set_menu(default=None, *values)
1780
1781 Replace the entries of the menu with *values*.
1782 If *default* is given, also set it as the current value of the
1783 *variable*.
1784
1785 .. method:: destroy()
1786
1787 Destroy this widget and its associated menu.
1788
1789
1790
1791 .. class:: Panedwindow(master=None, **kw)
1792
1793 Ttk :class:`Panedwindow` widget, displays a number of subwindows stacked
1794 either vertically or horizontally.
1795 The user may adjust the relative sizes of the subwindows by dragging the
1796 sash between panes.
1797 It is the themed counterpart of :class:`tkinter.PanedWindow` and inherits
1798 the common widget methods from :class:`Widget`, as well as the :meth:`!add`
1799 and :meth:`!panes` methods from :class:`tkinter.PanedWindow`.
1800
1801 .. method:: insert(pos, child, **kw)
1802
1803 Insert a pane containing *child* at the position *pos*.
1804 *pos* is either the string ``'end'``, an integer index, or the name of a
1805 managed subwindow.
1806 If *child* is already managed by the paned window, move it to the
1807 specified position.
1808 Any keyword arguments set pane options.
1809
1810 .. method:: forget(child)
1811
1812 Remove *child*, which may be either an integer index or the name of a
1813 managed subwindow, from the panes.
1814
1815 This shadows the inherited geometry-manager :meth:`!forget`;
1816 use :meth:`~tkinter.Pack.pack_forget`, :meth:`~tkinter.Grid.grid_forget`
1817 or :meth:`~tkinter.Place.place_forget` to remove the widget itself from
1818 its manager.
1819
1820 .. method:: pane(pane, option=None, **kw)
1821
1822 Query or modify the options of the specified *pane*, where *pane* is
1823 either an integer index or the name of a managed subwindow.
1824 If no arguments are given, return a dictionary of the pane option values.
1825 If *option* is specified, return the value of that option.
1826 Otherwise, set the options given as keyword arguments to their
1827 corresponding values.
1828
1829 .. method:: sashpos(index, newpos=None)
1830
1831 If *newpos* is specified, set the position of sash number *index* and
1832 return its new position.
1833 This may adjust the positions of adjacent sashes to ensure that positions
1834 are monotonically increasing; positions are also constrained to be
1835 between 0 and the total size of the widget.
1836 If *newpos* is omitted, return the current position of the sash.
1837
1838
1839 .. class:: Radiobutton(master=None, **kw)
1840
1841 Ttk :class:`Radiobutton` widget, used as part of a group to control a single
1842 shared variable by selecting one of several mutually exclusive values.
1843 It is the themed counterpart of :class:`tkinter.Radiobutton` and inherits
1844 the common widget methods from :class:`Widget`.
1845
1846 .. method:: invoke()
1847
1848 Set the option variable to the button's value, select the button, invoke
1849 the command associated with the button, and return its result.
1850
1851
1852 .. class:: Scale(master=None, **kw)
1853
1854 Ttk :class:`Scale` widget, displays a slider that lets the user select a
1855 numeric value from a range by moving the slider along a trough.
1856 It is the themed counterpart of :class:`tkinter.Scale` and inherits the
1857 common widget methods from :class:`Widget`.
1858
1859 .. method:: configure(cnf=None, **kw)
1860
1861 Modify or query the widget options, like
1862 :meth:`Widget.configure <tkinter.Misc.configure>`.
1863 In addition, this method clips the ``from`` and ``to`` values so that the
1864 current value stays within the range defined by them.
1865
1866 .. versionchanged:: 3.9
1867 Now returns the configuration value, like
1868 :meth:`Widget.configure <tkinter.Misc.configure>`.
1869
1870
1871 .. method:: get(x=None, y=None)
1872
1873 Return the current value of the scale.
1874 If *x* and *y* are given, return the value corresponding to the pixel
1875 coordinate *x*, *y* instead.
1876
1877
1878 .. class:: Scrollbar(master=None, **kw)
1879
1880 Ttk :class:`Scrollbar` widget, controls the viewport of an associated
1881 scrollable widget such as a :class:`Treeview`, :class:`Entry` or
1882 :class:`tkinter.Text`.
1883 It is the themed counterpart of :class:`tkinter.Scrollbar` and inherits the
1884 common widget methods from :class:`Widget`, as well as the :meth:`!set` and
1885 :meth:`!get` methods from :class:`tkinter.Scrollbar`.
1886
1887
1888 .. class:: Separator(master=None, **kw)
1889
1890 Ttk :class:`Separator` widget, displays a horizontal or vertical separator
1891 line.
1892 It has no direct counterpart in :mod:`tkinter` and inherits the common
1893 widget methods from :class:`Widget`.
1894
1895
1896 .. class:: Sizegrip(master=None, **kw)
1897
1898 Ttk :class:`Sizegrip` widget, displays a grip that allows the user to resize
1899 the containing toplevel window by pressing and dragging the grip, typically
1900 placed in the bottom-right corner.
1901 It has no direct counterpart in :mod:`tkinter` and inherits the common
1902 widget methods from :class:`Widget`.
1903
1904
1905 .. class:: LabeledScale(master=None, variable=None, from_=0, to=10, **kw)
1906
1907 A :class:`Frame` containing a :class:`Scale` and a :class:`Label` that shows
1908 the scale's current value.
1909 *variable* is the :class:`~tkinter.IntVar` tracked by the scale (one is
1910 created if it is not given), and *from_* and *to* define the range of the
1911 scale.
1912
1913 .. method:: destroy()
1914
1915 Destroy this widget and remove the trace callback registered on the
1916 associated variable.
1917
1918
1919 .. class:: LabelFrame(master=None, **kw)
1920
1921 Alias of :class:`Labelframe`, kept for naming compatibility with
1922 :class:`tkinter.LabelFrame`.
1923
1924
1925 .. class:: PanedWindow(master=None, **kw)
1926
1927 Alias of :class:`Panedwindow`, kept for naming compatibility with
1928 :class:`tkinter.PanedWindow`.