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