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