blob: 7bf39b3109cca4813d0e5b0217f4cdd1affad3c8 [file] [log] [blame]
Guilherme Polo5f238482009-01-28 14:41:10 +00001:mod:`tkinter.ttk` --- Tk themed widgets
2========================================
3
4.. module:: tkinter.ttk
5 :synopsis: Tk themed widget set
6.. sectionauthor:: Guilherme Polo <ggpolo@gmail.com>
7
8
9.. index:: single: ttk
10
11The :mod:`tkinter.ttk` module provides access to the Tk themed widget set,
Raymond Hettinger238018c2009-04-08 08:23:44 +000012introduced in Tk 8.5. If Python has not been compiled against Tk 8.5, this
13module can still be accessed if *Tile* has been installed. The former
14method using Tk 8.5 provides additional benefits including anti-aliased font
15rendering under X11 and window transparency (requiring a composition
16window manager on X11).
Guilherme Polo5f238482009-01-28 14:41:10 +000017
Raymond Hettinger238018c2009-04-08 08:23:44 +000018The basic idea for :mod:`tkinter.ttk` is to separate, to the extent possible,
Guilherme Polo5f238482009-01-28 14:41:10 +000019the code implementing a widget's behavior from the code implementing its
20appearance.
21
22
23.. seealso::
24
25 `Tk Widget Styling Support <http://www.tcl.tk/cgi-bin/tct/tip/48>`_
Raymond Hettinger238018c2009-04-08 08:23:44 +000026 A document introducing theming support for Tk
Guilherme Polo5f238482009-01-28 14:41:10 +000027
28
29Using Ttk
30---------
31
Raymond Hettinger238018c2009-04-08 08:23:44 +000032To start using Ttk, import its module::
Guilherme Polo5f238482009-01-28 14:41:10 +000033
34 from tkinter import ttk
35
Raymond Hettinger238018c2009-04-08 08:23:44 +000036To override the basic Tk widgets, the import should follow the Tk import::
Guilherme Polo5f238482009-01-28 14:41:10 +000037
38 from tkinter import *
39 from tkinter.ttk import *
40
Raymond Hettinger238018c2009-04-08 08:23:44 +000041That code causes several :mod:`tkinter.ttk` widgets (:class:`Button`,
Guilherme Polo5f238482009-01-28 14:41:10 +000042:class:`Checkbutton`, :class:`Entry`, :class:`Frame`, :class:`Label`,
43:class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`,
Raymond Hettinger238018c2009-04-08 08:23:44 +000044:class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`) to
45automatically replace the Tk widgets.
Guilherme Polo5f238482009-01-28 14:41:10 +000046
Raymond Hettinger238018c2009-04-08 08:23:44 +000047This has the direct benefit of using the new widgets which gives a better
48look and feel across platforms; however, the replacement widgets are not
49completely compatible. The main difference is that widget options such as
50"fg", "bg" and others related to widget styling are no
51longer present in Ttk widgets. Instead, use the :class:`ttk.Style` class
52for improved styling effects.
53
Guilherme Polo5f238482009-01-28 14:41:10 +000054
55.. seealso::
56
Raymond Hettinger238018c2009-04-08 08:23:44 +000057 `Converting existing applications to use Tile widgets <http://tktable.sourceforge.net/tile/doc/converting.txt>`_
58 A monograph (using Tcl terminology) about differences typically
59 encountered when moving applications to use the new widgets.
Guilherme Polo5f238482009-01-28 14:41:10 +000060
61
62Ttk Widgets
63-----------
64
Raymond Hettinger238018c2009-04-08 08:23:44 +000065Ttk comes with 17 widgets, eleven of which already existed in tkinter:
Guilherme Polo5f238482009-01-28 14:41:10 +000066:class:`Button`, :class:`Checkbutton`, :class:`Entry`, :class:`Frame`,
67:class:`Label`, :class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`,
Raymond Hettinger238018c2009-04-08 08:23:44 +000068:class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`. The other six are
Guilherme Polo5f238482009-01-28 14:41:10 +000069new: :class:`Combobox`, :class:`Notebook`, :class:`Progressbar`,
70:class:`Separator`, :class:`Sizegrip` and :class:`Treeview`. And all them are
71subclasses of :class:`Widget`.
72
Raymond Hettinger238018c2009-04-08 08:23:44 +000073Using the Ttk widgets gives the application an improved look and feel.
74As discussed above, there are differences in how the styling is coded.
Guilherme Polo5f238482009-01-28 14:41:10 +000075
76Tk code::
77
78 l1 = tkinter.Label(text="Test", fg="black", bg="white")
79 l2 = tkinter.Label(text="Test", fg="black", bg="white")
80
81
82Ttk code::
83
84 style = ttk.Style()
85 style.configure("BW.TLabel", foreground="black", background="white")
86
87 l1 = ttk.Label(text="Test", style="BW.TLabel")
88 l2 = ttk.Label(text="Test", style="BW.TLabel")
89
Raymond Hettinger238018c2009-04-08 08:23:44 +000090For more information about TtkStyling_, see the :class:`Style` class
Guilherme Polo5f238482009-01-28 14:41:10 +000091documentation.
92
93Widget
94------
95
96:class:`ttk.Widget` defines standard options and methods supported by Tk
97themed widgets and is not supposed to be directly instantiated.
98
99
100Standard Options
101^^^^^^^^^^^^^^^^
102
103All the :mod:`ttk` Widgets accepts the following options:
104
105 +-----------+--------------------------------------------------------------+
106 | Option | Description |
107 +===========+==============================================================+
108 | class | Specifies the window class. The class is used when querying |
109 | | the option database for the window's other options, to |
110 | | determine the default bindtags for the window, and to select |
111 | | the widget's default layout and style. This is a read-only |
112 | | which may only be specified when the window is created |
113 +-----------+--------------------------------------------------------------+
114 | cursor | Specifies the mouse cursor to be used for the widget. If set |
115 | | to the empty string (the default), the cursor is inherited |
116 | | for the parent widget. |
117 +-----------+--------------------------------------------------------------+
118 | takefocus | Determines whether the window accepts the focus during |
Ezio Melotti1a263ad2010-03-14 09:51:37 +0000119 | | keyboard traversal. 0, 1 or an empty string is returned. |
120 | | If 0 is returned, it means that the window should be skipped |
121 | | entirely during keyboard traversal. If 1, it means that the |
122 | | window should receive the input focus as long as it is |
123 | | viewable. And an empty string means that the traversal |
124 | | scripts make the decision about whether or not to focus |
125 | | on the window. |
Guilherme Polo5f238482009-01-28 14:41:10 +0000126 +-----------+--------------------------------------------------------------+
127 | style | May be used to specify a custom widget style. |
128 +-----------+--------------------------------------------------------------+
129
130
131Scrollable Widget Options
132^^^^^^^^^^^^^^^^^^^^^^^^^
133
134The following options are supported by widgets that are controlled by a
135scrollbar.
136
137 +----------------+---------------------------------------------------------+
138 | option | description |
139 +================+=========================================================+
Georg Brandlae2dbe22009-03-13 19:04:40 +0000140 | xscrollcommand | Used to communicate with horizontal scrollbars. |
Guilherme Polo5f238482009-01-28 14:41:10 +0000141 | | |
142 | | When the view in the widget's window change, the widget |
143 | | will generate a Tcl command based on the scrollcommand. |
144 | | |
145 | | Usually this option consists of the method |
146 | | :meth:`Scrollbar.set` of some scrollbar. This will cause|
147 | | the scrollbar to be updated whenever the view in the |
148 | | window changes. |
149 +----------------+---------------------------------------------------------+
Georg Brandlae2dbe22009-03-13 19:04:40 +0000150 | yscrollcommand | Used to communicate with vertical scrollbars. |
Guilherme Polo5f238482009-01-28 14:41:10 +0000151 | | For some more information, see above. |
152 +----------------+---------------------------------------------------------+
153
154
155Label Options
156^^^^^^^^^^^^^
157
158The following options are supported by labels, buttons and other button-like
159widgets.
160
Georg Brandl2c860042009-06-16 19:24:38 +0000161.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
162..
163
Guilherme Polo5f238482009-01-28 14:41:10 +0000164 +--------------+-----------------------------------------------------------+
165 | option | description |
166 +==============+===========================================================+
167 | text | Specifies a text string to be displayed inside the widget.|
168 +--------------+-----------------------------------------------------------+
169 | textvariable | Specifies a name whose value will be used in place of the |
170 | | text option resource. |
171 +--------------+-----------------------------------------------------------+
172 | underline | If set, specifies the index (0-based) of a character to |
173 | | underline in the text string. The underline character is |
174 | | used for mnemonic activation. |
175 +--------------+-----------------------------------------------------------+
176 | image | Specifies an image to display. This is a list of 1 or more|
177 | | elements. The first element is the default image name. The|
178 | | rest of the list if a sequence of statespec/value pairs as|
179 | | defined by :meth:`Style.map`, specifying different images |
180 | | to use when the widget is in a particular state or a |
181 | | combination of states. All images in the list should have |
182 | | the same size. |
183 +--------------+-----------------------------------------------------------+
184 | compound | Specifies how to display the image relative to the text, |
185 | | in the case both text and images options are present. |
186 | | Valid values are: |
187 | | |
188 | | * text: display text only |
189 | | * image: display image only |
190 | | * top, bottom, left, right: display image above, below, |
191 | | left of, or right of the text, respectively. |
192 | | * none: the default. display the image if present, |
193 | | otherwise the text. |
194 +--------------+-----------------------------------------------------------+
195 | width | If greater than zero, specifies how much space, in |
196 | | character widths, to allocate for the text label, if less |
197 | | than zero, specifies a minimum width. If zero or |
198 | | unspecified, the natural width of the text label is used. |
199 +--------------+-----------------------------------------------------------+
200
201
202Compatibility Options
203^^^^^^^^^^^^^^^^^^^^^
204
205 +--------+----------------------------------------------------------------+
206 | option | description |
207 +========+================================================================+
208 | state | May be set to "normal" or "disabled" to control the "disabled" |
209 | | state bit. This is a write-only option: setting it changes the |
210 | | widget state, but the :meth:`Widget.state` method does not |
211 | | affect this option. |
212 +--------+----------------------------------------------------------------+
213
214Widget States
215^^^^^^^^^^^^^
216
217The widget state is a bitmap of independent state flags.
218
219 +------------+-------------------------------------------------------------+
220 | flag | description |
221 +============+=============================================================+
222 | active | The mouse cursor is over the widget and pressing a mouse |
223 | | button will cause some action to occur |
224 +------------+-------------------------------------------------------------+
225 | disabled | Widget is disabled under program control |
226 +------------+-------------------------------------------------------------+
227 | focus | Widget has keyboard focus |
228 +------------+-------------------------------------------------------------+
229 | pressed | Widget is being pressed |
230 +------------+-------------------------------------------------------------+
231 | selected | "On", "true", or "current" for things like Checkbuttons and |
232 | | radiobuttons |
233 +------------+-------------------------------------------------------------+
234 | background | Windows and Mac have a notion of an "active" or foreground |
235 | | window. The *background* state is set for widgets in a |
236 | | background window, and cleared for those in the foreground |
237 | | window |
238 +------------+-------------------------------------------------------------+
239 | readonly | Widget should not allow user modification |
240 +------------+-------------------------------------------------------------+
241 | alternate | A widget-specific alternate display format |
242 +------------+-------------------------------------------------------------+
243 | invalid | The widget's value is invalid |
244 +------------+-------------------------------------------------------------+
245
246A state specification is a sequence of state names, optionally prefixed with
247an exclamation point indicating that the bit is off.
248
249
250ttk.Widget
251^^^^^^^^^^
252
Benjamin Petersond23f8222009-04-05 19:13:16 +0000253Besides the methods described below, the :class:`ttk.Widget` supports the
Guilherme Polo5f238482009-01-28 14:41:10 +0000254methods :meth:`tkinter.Widget.cget` and :meth:`tkinter.Widget.configure`.
255
256.. class:: Widget
257
258 .. method:: identify(x, y)
259
260 Returns the name of the element at position *x* *y*, or the empty string
261 if the point does not lie within any element.
262
263 *x* and *y* are pixel coordinates relative to the widget.
264
265
Georg Brandl7f01a132009-09-16 15:58:14 +0000266 .. method:: instate(statespec, callback=None, *args, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +0000267
268 Test the widget's state. If a callback is not specified, returns True
269 if the widget state matches *statespec* and False otherwise. If callback
270 is specified then it is called with args if widget state matches
271 *statespec*.
272
273
Georg Brandl7f01a132009-09-16 15:58:14 +0000274 .. method:: state(statespec=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000275
276 Modify or inquire widget state. If *statespec* is specified, sets the
277 widget state according to it and return a new *statespec* indicating
278 which flags were changed. If *statespec* is not specified, returns
279 the currently-enabled state flags.
280
281 *statespec* will usually be a list or a tuple.
282
283
284Combobox
285--------
286
287The :class:`ttk.Combobox` widget combines a text field with a pop-down list of
288values. This widget is a subclass of :class:`Entry`.
289
290Besides the methods inherited from :class:`Widget`: :meth:`Widget.cget`,
291:meth:`Widget.configure`, :meth:`Widget.identify`, :meth:`Widget.instate`
292and :meth:`Widget.state`, and the following inherited from :class:`Entry`:
293:meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`,
294:meth:`Entry.index`, :meth:`Entry.inset`, :meth:`Entry.selection`,
295:meth:`Entry.xview`, it has some other methods, described at
296:class:`ttk.Combobox`.
297
298
299Options
300^^^^^^^
301
302This widget accepts the following specific options:
303
304 +-----------------+--------------------------------------------------------+
305 | option | description |
306 +=================+========================================================+
307 | exportselection | Boolean value. If set, the widget selection is linked |
308 | | to the Window Manager selection (which can be returned |
309 | | by invoking Misc.selection_get, for example). |
310 +-----------------+--------------------------------------------------------+
311 | justify | Specifies how the text is aligned within the widget. |
312 | | One of "left", "center", or "right". |
313 +-----------------+--------------------------------------------------------+
314 | height | Specifies the height of the pop-down listbox, in rows. |
315 +-----------------+--------------------------------------------------------+
316 | postcommand | A script (possibly registered with Misc.register) that |
317 | | is called immediately before displaying the values. It |
318 | | may specify which values to display. |
319 +-----------------+--------------------------------------------------------+
320 | state | One of "normal", "readonly", or "disabled". In the |
321 | | "readonly" state, the value may not be edited directly,|
322 | | and the user can only selection of the values from the |
323 | | dropdown list. In the "normal" state, the text field is|
324 | | directly editable. In the "disabled" state, no |
325 | | interaction is possible. |
326 +-----------------+--------------------------------------------------------+
327 | textvariable | Specifies a name whose value is linked to the widget |
328 | | value. Whenever the value associated with that name |
329 | | changes, the widget value is updated, and vice versa. |
330 | | See :class:`tkinter.StringVar`. |
331 +-----------------+--------------------------------------------------------+
332 | values | Specifies the list of values to display in the |
333 | | drop-down listbox. |
334 +-----------------+--------------------------------------------------------+
335 | width | Specifies an integer value indicating the desired width|
336 | | of the entry window, in average-size characters of the |
337 | | widget's font. |
338 +-----------------+--------------------------------------------------------+
339
340
341Virtual events
342^^^^^^^^^^^^^^
343
344The combobox widgets generates a **<<ComboboxSelected>>** virtual event
345when the user selects an element from the list of values.
346
347
348ttk.Combobox
349^^^^^^^^^^^^
350
351.. class:: Combobox
352
Georg Brandl7f01a132009-09-16 15:58:14 +0000353 .. method:: current(newindex=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000354
355 If *newindex* is specified, sets the combobox value to the element
356 position *newindex*. Otherwise, returns the index of the current value or
357 -1 if the current value is not in the values list.
358
359
360 .. method:: get()
361
362 Returns the current value of the combobox.
363
364
365 .. method:: set(value)
366
367 Sets the value of the combobox to *value*.
368
369
370Notebook
371--------
372
373Ttk Notebook widget manages a collection of windows and displays a single
374one at a time. Each child window is associated with a tab, which the user
375may select to change the currently-displayed window.
376
377
378Options
379^^^^^^^
380
381This widget accepts the following specific options:
382
383 +---------+----------------------------------------------------------------+
384 | option | description |
385 +=========+================================================================+
386 | height | If present and greater than zero, specifies the desired height |
387 | | of the pane area (not including internal padding or tabs). |
388 | | Otherwise, the maximum height of all panes is used. |
389 +---------+----------------------------------------------------------------+
390 | padding | Specifies the amount of extra space to add around the outside |
391 | | of the notebook. The padding is a list up to four length |
392 | | specifications left top right bottom. If fewer than four |
393 | | elements are specified, bottom defaults to top, right defaults |
394 | | to left, and top defaults to left. |
395 +---------+----------------------------------------------------------------+
396 | width | If present and greater than zero, specified the desired width |
397 | | of the pane area (not including internal padding). Otherwise, |
398 | | the maximum width of all panes is used. |
399 +---------+----------------------------------------------------------------+
400
401
402Tab Options
403^^^^^^^^^^^
404
405There are also specific options for tabs:
406
407 +-----------+--------------------------------------------------------------+
408 | option | description |
409 +===========+==============================================================+
410 | state | Either "normal", "disabled" or "hidden". If "disabled", then |
411 | | the tab is not selectable. If "hidden", then the tab is not |
412 | | shown. |
413 +-----------+--------------------------------------------------------------+
414 | sticky | Specifies how the child window is positioned within the pane |
415 | | area. Value is a string containing zero or more of the |
416 | | characters "n", "s", "e" or "w". Each letter refers to a |
417 | | side (north, south, east or west) that the child window will |
418 | | stick to, as per the :meth:`grid` geometry manager. |
419 +-----------+--------------------------------------------------------------+
420 | padding | Specifies the amount of extra space to add between the |
421 | | notebook and this pane. Syntax is the same as for the option |
422 | | padding used by this widget. |
423 +-----------+--------------------------------------------------------------+
424 | text | Specifies a text to be displayed in the tab. |
425 +-----------+--------------------------------------------------------------+
426 | image | Specifies an image to display in the tab. See the option |
427 | | image described in :class:`Widget`. |
428 +-----------+--------------------------------------------------------------+
429 | compound | Specifies how to display the image relative to the text, in |
430 | | the case both options text and image are present. See |
431 | | `Label Options`_ for legal values. |
432 +-----------+--------------------------------------------------------------+
433 | underline | Specifies the index (0-based) of a character to underline in |
434 | | the text string. The underlined character is used for |
435 | | mnemonic activation if :meth:`Notebook.enable_traversal` is |
436 | | called. |
437 +-----------+--------------------------------------------------------------+
438
439
440Tab Identifiers
441^^^^^^^^^^^^^^^
442
443The tab_id present in several methods of :class:`ttk.Notebook` may take any
444of the following forms:
445
446* An integer between zero and the number of tabs
447* The name of a child window
448* A positional specification of the form "@x,y", which identifies the tab
449* The literal string "current", which identifies the currently-selected tab
450* The literal string "end", which returns the number of tabs (only valid for
451 :meth:`Notebook.index`)
452
453
454Virtual Events
455^^^^^^^^^^^^^^
456
457This widget generates a **<<NotebookTabChanged>>** virtual event after a new
458tab is selected.
459
460
461ttk.Notebook
462^^^^^^^^^^^^
463
464.. class:: Notebook
465
466 .. method:: add(child, **kw)
467
468 Adds a new tab to the notebook.
469
470 If window is currently managed by the notebook but hidden, it is
471 restored to its previous position.
472
473 See `Tab Options`_ for the list of available options.
474
475
476 .. method:: forget(tab_id)
477
478 Removes the tab specified by *tab_id*, unmaps and unmanages the
479 associated window.
480
481
482 .. method:: hide(tab_id)
483
484 Hides the tab specified by *tab_id*.
485
486 The tab will not be displayed, but the associated window remains
487 managed by the notebook and its configuration remembered. Hidden tabs
Benjamin Petersond23f8222009-04-05 19:13:16 +0000488 may be restored with the :meth:`add` command.
Guilherme Polo5f238482009-01-28 14:41:10 +0000489
490
491 .. method:: identify(x, y)
492
493 Returns the name of the tab element at position *x*, *y*, or the empty
494 string if none.
495
496
497 .. method:: index(tab_id)
498
499 Returns the numeric index of the tab specified by *tab_id*, or the total
500 number of tabs if *tab_id* is the string "end".
501
502
503 .. method:: insert(pos, child, **kw)
504
505 Inserts a pane at the specified position.
506
Benjamin Petersond23f8222009-04-05 19:13:16 +0000507 *pos* is either the string "end", an integer index, or the name of a
Guilherme Polo5f238482009-01-28 14:41:10 +0000508 managed child. If *child* is already managed by the notebook, moves it to
509 the specified position.
510
511 See `Tab Options`_ for the list of available options.
512
513
Georg Brandl7f01a132009-09-16 15:58:14 +0000514 .. method:: select(tab_id=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000515
516 Selects the specified *tab_id*.
517
518 The associated child window will be displayed, and the
519 previously-selected window (if different) is unmapped. If *tab_id* is
520 omitted, returns the widget name of the currently selected pane.
521
522
Georg Brandl7f01a132009-09-16 15:58:14 +0000523 .. method:: tab(tab_id, option=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +0000524
525 Query or modify the options of the specific *tab_id*.
526
Benjamin Petersond23f8222009-04-05 19:13:16 +0000527 If *kw* is not given, returns a dictionary of the tab option values. If
Guilherme Polo5f238482009-01-28 14:41:10 +0000528 *option* is specified, returns the value of that *option*. Otherwise,
529 sets the options to the corresponding values.
530
531
532 .. method:: tabs()
533
534 Returns a list of windows managed by the notebook.
535
536
537 .. method:: enable_traversal()
538
539 Enable keyboard traversal for a toplevel window containing this notebook.
540
541 This will extend the bindings for the toplevel window containing the
542 notebook as follows:
543
Benjamin Petersond23f8222009-04-05 19:13:16 +0000544 * Control-Tab: selects the tab following the currently selected one.
545 * Shift-Control-Tab: selects the tab preceding the currently selected one.
Guilherme Polo5f238482009-01-28 14:41:10 +0000546 * Alt-K: where K is the mnemonic (underlined) character of any tab, will
547 select that tab.
548
549 Multiple notebooks in a single toplevel may be enabled for traversal,
550 including nested notebooks. However, notebook traversal only works
Benjamin Petersond23f8222009-04-05 19:13:16 +0000551 properly if all panes have the notebook they are in as master.
Guilherme Polo5f238482009-01-28 14:41:10 +0000552
553
554Progressbar
555-----------
556
557The :class:`ttk.Progressbar` widget shows the status of a long-running
Raymond Hettinger238018c2009-04-08 08:23:44 +0000558operation. It can operate in two modes: 1) the determinate mode which shows the
559amount completed relative to the total amount of work to be done and 2) the
560indeterminate mode which provides an animated display to let the user know that
561work is progressing.
Guilherme Polo5f238482009-01-28 14:41:10 +0000562
563
564Options
565^^^^^^^
566
567This widget accepts the following specific options:
568
569 +----------+---------------------------------------------------------------+
570 | option | description |
571 +==========+===============================================================+
572 | orient | One of "horizontal" or "vertical". Specifies the orientation |
573 | | of the progress bar. |
574 +----------+---------------------------------------------------------------+
575 | length | Specifies the length of the long axis of the progress bar |
576 | | (width if horizontal, height if vertical). |
577 +----------+---------------------------------------------------------------+
578 | mode | One of "determinate" or "indeterminate". |
579 +----------+---------------------------------------------------------------+
580 | maximum | A number specifying the maximum value. Defaults to 100. |
581 +----------+---------------------------------------------------------------+
582 | value | The current value of the progress bar. In "determinate" mode, |
583 | | this represents the amount of work completed. In |
Benjamin Petersond23f8222009-04-05 19:13:16 +0000584 | | "indeterminate" mode, it is interpreted as modulo *maximum*; |
Guilherme Polo5f238482009-01-28 14:41:10 +0000585 | | that is, the progress bar completes one "cycle" when its value|
Benjamin Petersond23f8222009-04-05 19:13:16 +0000586 | | increases by *maximum*. |
Guilherme Polo5f238482009-01-28 14:41:10 +0000587 +----------+---------------------------------------------------------------+
588 | variable | A name which is linked to the option value. If specified, the |
Benjamin Petersond23f8222009-04-05 19:13:16 +0000589 | | value of the progress bar is automatically set to the value of|
Guilherme Polo5f238482009-01-28 14:41:10 +0000590 | | this name whenever the latter is modified. |
591 +----------+---------------------------------------------------------------+
592 | phase | Read-only option. The widget periodically increments the value|
593 | | of this option whenever its value is greater than 0 and, in |
594 | | determinate mode, less than maximum. This option may be used |
595 | | by the current theme to provide additional animation effects. |
596 +----------+---------------------------------------------------------------+
597
598
599ttk.Progressbar
600^^^^^^^^^^^^^^^
601
602.. class:: Progressbar
603
Georg Brandl7f01a132009-09-16 15:58:14 +0000604 .. method:: start(interval=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000605
Benjamin Petersond23f8222009-04-05 19:13:16 +0000606 Begin autoincrement mode: schedules a recurring timer event that calls
Guilherme Polo5f238482009-01-28 14:41:10 +0000607 :meth:`Progressbar.step` every *interval* milliseconds. If omitted,
608 *interval* defaults to 50 milliseconds.
609
610
Georg Brandl7f01a132009-09-16 15:58:14 +0000611 .. method:: step(amount=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000612
Benjamin Petersond23f8222009-04-05 19:13:16 +0000613 Increments the progress bar's value by *amount*.
Guilherme Polo5f238482009-01-28 14:41:10 +0000614
615 *amount* defaults to 1.0 if omitted.
616
617
618 .. method:: stop()
619
620 Stop autoincrement mode: cancels any recurring timer event initiated by
Benjamin Petersond23f8222009-04-05 19:13:16 +0000621 :meth:`Progressbar.start` for this progress bar.
Guilherme Polo5f238482009-01-28 14:41:10 +0000622
623
624Separator
625---------
626
627The :class:`ttk.Separator` widget displays a horizontal or vertical separator
628bar.
629
Benjamin Petersond23f8222009-04-05 19:13:16 +0000630It has no other methods besides the ones inherited from :class:`ttk.Widget`.
Guilherme Polo5f238482009-01-28 14:41:10 +0000631
632
633Options
634^^^^^^^
635
636This widget accepts the following specific option:
637
638 +--------+----------------------------------------------------------------+
639 | option | description |
640 +========+================================================================+
641 | orient | One of "horizontal" or "vertical". Specifies the orientation of|
642 | | the separator. |
643 +--------+----------------------------------------------------------------+
644
645
646Sizegrip
647--------
648
Benjamin Petersond23f8222009-04-05 19:13:16 +0000649The :class:`ttk.Sizegrip` widget (also known as a grow box) allows the user to
Guilherme Polo5f238482009-01-28 14:41:10 +0000650resize the containing toplevel window by pressing and dragging the grip.
651
Benjamin Petersond23f8222009-04-05 19:13:16 +0000652This widget has neither specific options nor specific methods, besides the
Guilherme Polo5f238482009-01-28 14:41:10 +0000653ones inherited from :class:`ttk.Widget`.
654
655
656Platform-specific notes
657^^^^^^^^^^^^^^^^^^^^^^^
658
Benjamin Petersond23f8222009-04-05 19:13:16 +0000659* On MacOS X, toplevel windows automatically include a built-in size grip
660 by default. Adding a :class:`Sizegrip` is harmless, since the built-in
Guilherme Polo5f238482009-01-28 14:41:10 +0000661 grip will just mask the widget.
662
663
664Bugs
665^^^^
666
667* If the containing toplevel's position was specified relative to the right
Benjamin Petersond23f8222009-04-05 19:13:16 +0000668 or bottom of the screen (e.g. ....), the :class:`Sizegrip` widget will
669 not resize the window.
Guilherme Polo5f238482009-01-28 14:41:10 +0000670* This widget supports only "southeast" resizing.
671
672
673Treeview
674--------
675
676The :class:`ttk.Treeview` widget displays a hierarchical collection of items.
677Each item has a textual label, an optional image, and an optional list of data
678values. The data values are displayed in successive columns after the tree
679label.
680
681The order in which data values are displayed may be controlled by setting
Benjamin Petersond23f8222009-04-05 19:13:16 +0000682the widget option ``displaycolumns``. The tree widget can also display column
Guilherme Polo5f238482009-01-28 14:41:10 +0000683headings. Columns may be accessed by number or symbolic names listed in the
684widget option columns. See `Column Identifiers`_.
685
686Each item is identified by an unique name. The widget will generate item IDs
687if they are not supplied by the caller. There is a distinguished root item,
Benjamin Petersond23f8222009-04-05 19:13:16 +0000688named ``{}``. The root item itself is not displayed; its children appear at the
Guilherme Polo5f238482009-01-28 14:41:10 +0000689top level of the hierarchy.
690
Benjamin Petersond23f8222009-04-05 19:13:16 +0000691Each item also has a list of tags, which can be used to associate event bindings
Guilherme Polo5f238482009-01-28 14:41:10 +0000692with individual items and control the appearance of the item.
693
694The Treeview widget supports horizontal and vertical scrolling, according to
695the options described in `Scrollable Widget Options`_ and the methods
696:meth:`Treeview.xview` and :meth:`Treeview.yview`.
697
698
699Options
700^^^^^^^
701
Benjamin Petersond23f8222009-04-05 19:13:16 +0000702This widget accepts the following specific options:
Guilherme Polo5f238482009-01-28 14:41:10 +0000703
Georg Brandl2c860042009-06-16 19:24:38 +0000704.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
705..
706
Guilherme Polo5f238482009-01-28 14:41:10 +0000707 +----------------+--------------------------------------------------------+
708 | option | description |
709 +================+========================================================+
710 | columns | A list of column identifiers, specifying the number of |
711 | | columns and their names. |
712 +----------------+--------------------------------------------------------+
713 | displaycolumns | A list of column identifiers (either symbolic or |
714 | | integer indices) specifying which data columns are |
715 | | displayed and the order in which they appear, or the |
716 | | string "#all". |
717 +----------------+--------------------------------------------------------+
718 | height | Specifies the number of rows which should be visible. |
719 | | Note: the requested width is determined from the sum |
720 | | of the column widths. |
721 +----------------+--------------------------------------------------------+
722 | padding | Specifies the internal padding for the widget. The |
723 | | padding is a list of up to four length specifications. |
724 +----------------+--------------------------------------------------------+
725 | selectmode | Controls how the built-in class bindings manage the |
726 | | selection. One of "extended", "browse" or "none". |
727 | | If set to "extended" (the default), multiple items may |
728 | | be selected. If "browse", only a single item will be |
729 | | selected at a time. If "none", the selection will not |
730 | | be changed. |
731 | | |
732 | | Note that the application code and tag bindings can set|
Benjamin Petersond23f8222009-04-05 19:13:16 +0000733 | | the selection however they wish, regardless of the |
734 | | value of this option. |
Guilherme Polo5f238482009-01-28 14:41:10 +0000735 +----------------+--------------------------------------------------------+
736 | show | A list containing zero or more of the following values,|
737 | | specifying which elements of the tree to display. |
738 | | |
739 | | * tree: display tree labels in column #0. |
740 | | * headings: display the heading row. |
741 | | |
742 | | The default is "tree headings", i.e., show all |
743 | | elements. |
744 | | |
Benjamin Petersond23f8222009-04-05 19:13:16 +0000745 | | **Note**: Column #0 always refers to the tree column, |
Guilherme Polo5f238482009-01-28 14:41:10 +0000746 | | even if show="tree" is not specified. |
747 +----------------+--------------------------------------------------------+
748
749
750Item Options
751^^^^^^^^^^^^
752
753The following item options may be specified for items in the insert and item
754widget commands.
755
756 +--------+---------------------------------------------------------------+
757 | option | description |
758 +========+===============================================================+
759 | text | The textual label to display for the item. |
760 +--------+---------------------------------------------------------------+
761 | image | A Tk Image, displayed to the left of the label. |
762 +--------+---------------------------------------------------------------+
763 | values | The list of values associated with the item. |
764 | | |
765 | | Each item should have the same number of values as the widget |
766 | | option columns. If there are fewer values than columns, the |
767 | | remaining values are assumed empty. If there are more values |
768 | | than columns, the extra values are ignored. |
769 +--------+---------------------------------------------------------------+
770 | open | True/False value indicating whether the item's children should|
771 | | be displayed or hidden. |
772 +--------+---------------------------------------------------------------+
773 | tags | A list of tags associated with this item. |
774 +--------+---------------------------------------------------------------+
775
776
777Tag Options
778^^^^^^^^^^^
779
780The following options may be specified on tags:
781
782 +------------+-----------------------------------------------------------+
783 | option | description |
784 +============+===========================================================+
785 | foreground | Specifies the text foreground color. |
786 +------------+-----------------------------------------------------------+
787 | background | Specifies the cell or item background color. |
788 +------------+-----------------------------------------------------------+
789 | font | Specifies the font to use when drawing text. |
790 +------------+-----------------------------------------------------------+
791 | image | Specifies the item image, in case the item's image option |
792 | | is empty. |
793 +------------+-----------------------------------------------------------+
794
795
796Column Identifiers
797^^^^^^^^^^^^^^^^^^
798
799Column identifiers take any of the following forms:
800
801* A symbolic name from the list of columns option.
802* An integer n, specifying the nth data column.
803* A string of the form #n, where n is an integer, specifying the nth display
804 column.
805
806Notes:
807
808* Item's option values may be displayed in a different order than the order
809 in which they are stored.
810* Column #0 always refers to the tree column, even if show="tree" is not
811 specified.
812
813A data column number is an index into an item's option values list; a display
814column number is the column number in the tree where the values are displayed.
815Tree labels are displayed in column #0. If option displaycolumns is not set,
816then data column n is displayed in column #n+1. Again, **column #0 always
817refers to the tree column**.
818
819
820Virtual Events
821^^^^^^^^^^^^^^
822
823The Treeview widget generates the following virtual events.
824
825 +--------------------+--------------------------------------------------+
826 | event | description |
827 +====================+==================================================+
828 | <<TreeviewSelect>> | Generated whenever the selection changes. |
829 +--------------------+--------------------------------------------------+
830 | <<TreeviewOpen>> | Generated just before settings the focus item to |
831 | | open=True. |
832 +--------------------+--------------------------------------------------+
833 | <<TreeviewClose>> | Generated just after setting the focus item to |
834 | | open=False. |
835 +--------------------+--------------------------------------------------+
836
837The :meth:`Treeview.focus` and :meth:`Treeview.selection` methods can be used
838to determine the affected item or items.
839
840
841ttk.Treeview
842^^^^^^^^^^^^
843
844.. class:: Treeview
845
Georg Brandl7f01a132009-09-16 15:58:14 +0000846 .. method:: bbox(item, column=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000847
848 Returns the bounding box (relative to the treeview widget's window) of
849 the specified *item* in the form (x, y, width, height).
850
851 If *column* is specified, returns the bounding box of that cell. If the
852 *item* is not visible (i.e., if it is a descendant of a closed item or is
853 scrolled offscreen), returns an empty string.
854
855
Georg Brandl7f01a132009-09-16 15:58:14 +0000856 .. method:: get_children(item=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000857
858 Returns the list of children belonging to *item*.
859
860 If *item* is not specified, returns root children.
861
862
863 .. method:: set_children(item, *newchildren)
864
Benjamin Petersond23f8222009-04-05 19:13:16 +0000865 Replaces *item*'s child with *newchildren*.
Guilherme Polo5f238482009-01-28 14:41:10 +0000866
Benjamin Petersond23f8222009-04-05 19:13:16 +0000867 Children present in *item* that are not present in *newchildren* are
868 detached from the tree. No items in *newchildren* may be an ancestor of
869 *item*. Note that not specifying *newchildren* results in detaching
Guilherme Polo5f238482009-01-28 14:41:10 +0000870 *item*'s children.
871
872
Georg Brandl7f01a132009-09-16 15:58:14 +0000873 .. method:: column(column, option=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +0000874
875 Query or modify the options for the specified *column*.
876
877 If *kw* is not given, returns a dict of the column option values. If
878 *option* is specified then the value for that *option* is returned.
879 Otherwise, sets the options to the corresponding values.
880
881 The valid options/values are:
882
883 * id
Benjamin Petersond23f8222009-04-05 19:13:16 +0000884 Returns the column name. This is a read-only option.
Guilherme Polo5f238482009-01-28 14:41:10 +0000885 * anchor: One of the standard Tk anchor values.
886 Specifies how the text in this column should be aligned with respect
887 to the cell.
888 * minwidth: width
889 The minimum width of the column in pixels. The treeview widget will
Benjamin Petersond23f8222009-04-05 19:13:16 +0000890 not make the column any smaller than specified by this option when
Guilherme Polo5f238482009-01-28 14:41:10 +0000891 the widget is resized or the user drags a column.
892 * stretch: True/False
Benjamin Petersond23f8222009-04-05 19:13:16 +0000893 Specifies whether the column's width should be adjusted when
Guilherme Polo5f238482009-01-28 14:41:10 +0000894 the widget is resized.
895 * width: width
896 The width of the column in pixels.
897
898 To configure the tree column, call this with column = "#0"
899
900 .. method:: delete(*items)
901
902 Delete all specified *items* and all their descendants.
903
904 The root item may not be deleted.
905
906
907 .. method:: detach(*items)
908
909 Unlinks all of the specified *items* from the tree.
910
911 The items and all of their descendants are still present, and may be
912 reinserted at another point in the tree, but will not be displayed.
913
914 The root item may not be detached.
915
916
917 .. method:: exists(item)
918
Benjamin Petersond23f8222009-04-05 19:13:16 +0000919 Returns True if the specified *item* is present in the tree.
Guilherme Polo5f238482009-01-28 14:41:10 +0000920
921
Georg Brandl7f01a132009-09-16 15:58:14 +0000922 .. method:: focus(item=None)
Guilherme Polo5f238482009-01-28 14:41:10 +0000923
924 If *item* is specified, sets the focus item to *item*. Otherwise, returns
925 the current focus item, or '' if there is none.
926
927
Georg Brandl7f01a132009-09-16 15:58:14 +0000928 .. method:: heading(column, option=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +0000929
930 Query or modify the heading options for the specified *column*.
931
932 If *kw* is not given, returns a dict of the heading option values. If
933 *option* is specified then the value for that *option* is returned.
934 Otherwise, sets the options to the corresponding values.
935
936 The valid options/values are:
937
938 * text: text
939 The text to display in the column heading.
940 * image: imageName
941 Specifies an image to display to the right of the column heading.
942 * anchor: anchor
943 Specifies how the heading text should be aligned. One of the standard
944 Tk anchor values.
945 * command: callback
946 A callback to be invoked when the heading label is pressed.
947
Benjamin Petersond23f8222009-04-05 19:13:16 +0000948 To configure the tree column heading, call this with column = "#0".
Guilherme Polo5f238482009-01-28 14:41:10 +0000949
950
951 .. method:: identify(component, x, y)
952
953 Returns a description of the specified *component* under the point given
954 by *x* and *y*, or the empty string if no such *component* is present at
955 that position.
956
957
958 .. method:: identify_row(y)
959
960 Returns the item ID of the item at position *y*.
961
962
963 .. method:: identify_column(x)
964
965 Returns the data column identifier of the cell at position *x*.
966
967 The tree column has ID #0.
968
969
970 .. method:: identify_region(x, y)
971
972 Returns one of:
973
974 +-----------+--------------------------------------+
975 | region | meaning |
976 +===========+======================================+
977 | heading | Tree heading area. |
978 +-----------+--------------------------------------+
979 | separator | Space between two columns headings. |
980 +-----------+--------------------------------------+
981 | tree | The tree area. |
982 +-----------+--------------------------------------+
983 | cell | A data cell. |
984 +-----------+--------------------------------------+
985
986 Availability: Tk 8.6.
987
988
989 .. method:: identify_element(x, y)
990
Benjamin Petersond23f8222009-04-05 19:13:16 +0000991 Returns the element at position *x*, *y*.
Guilherme Polo5f238482009-01-28 14:41:10 +0000992
993 Availability: Tk 8.6.
994
995
996 .. method:: index(item)
997
998 Returns the integer index of *item* within its parent's list of children.
999
1000
Georg Brandl7f01a132009-09-16 15:58:14 +00001001 .. method:: insert(parent, index, iid=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +00001002
Benjamin Petersond23f8222009-04-05 19:13:16 +00001003 Creates a new item and returns the item identifier of the newly created
Guilherme Polo5f238482009-01-28 14:41:10 +00001004 item.
1005
1006 *parent* is the item ID of the parent item, or the empty string to create
1007 a new top-level item. *index* is an integer, or the value "end",
1008 specifying where in the list of parent's children to insert the new item.
1009 If *index* is less than or equal to zero, the new node is inserted at
Benjamin Petersond23f8222009-04-05 19:13:16 +00001010 the beginning; if *index* is greater than or equal to the current number
Guilherme Polo5f238482009-01-28 14:41:10 +00001011 of children, it is inserted at the end. If *iid* is specified, it is used
Benjamin Petersond23f8222009-04-05 19:13:16 +00001012 as the item identifier; *iid* must not already exist in the tree.
Guilherme Polo5f238482009-01-28 14:41:10 +00001013 Otherwise, a new unique identifier is generated.
1014
1015 See `Item Options`_ for the list of available points.
1016
1017
Georg Brandl7f01a132009-09-16 15:58:14 +00001018 .. method:: item(item, option=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +00001019
1020 Query or modify the options for the specified *item*.
1021
1022 If no options are given, a dict with options/values for the item is
1023 returned.
1024 If *option* is specified then the value for that option is returned.
1025 Otherwise, sets the options to the corresponding values as given by *kw*.
1026
1027
1028 .. method:: move(item, parent, index)
1029
1030 Moves *item* to position *index* in *parent*'s list of children.
1031
Benjamin Petersond23f8222009-04-05 19:13:16 +00001032 It is illegal to move an item under one of its descendants. If *index* is
1033 less than or equal to zero, *item* is moved to the beginning; if greater
1034 than or equal to the number of children, it is moved to the end. If *item*
Guilherme Polo5f238482009-01-28 14:41:10 +00001035 was detached it is reattached.
1036
1037
1038 .. method:: next(item)
1039
1040 Returns the identifier of *item*'s next sibling, or '' if *item* is the
1041 last child of its parent.
1042
1043
1044 .. method:: parent(item)
1045
1046 Returns the ID of the parent of *item*, or '' if *item* is at the top
1047 level of the hierarchy.
1048
1049
1050 .. method:: prev(item)
1051
1052 Returns the identifier of *item*'s previous sibling, or '' if *item* is
1053 the first child of its parent.
1054
1055
1056 .. method:: reattach(item, parent, index)
1057
1058 An alias for :meth:`Treeview.move`.
1059
1060
1061 .. method:: see(item)
1062
1063 Ensure that *item* is visible.
1064
1065 Sets all of *item*'s ancestors open option to True, and scrolls the
1066 widget if necessary so that *item* is within the visible portion of
1067 the tree.
1068
1069
Georg Brandl7f01a132009-09-16 15:58:14 +00001070 .. method:: selection(selop=None, items=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001071
1072 If *selop* is not specified, returns selected items. Otherwise, it will
1073 act according to the following selection methods.
1074
1075
1076 .. method:: selection_set(items)
1077
1078 *items* becomes the new selection.
1079
1080
1081 .. method:: selection_add(items)
1082
1083 Add *items* to the selection.
1084
1085
1086 .. method:: selection_remove(items)
1087
1088 Remove *items* from the selection.
1089
1090
1091 .. method:: selection_toggle(items)
1092
1093 Toggle the selection state of each item in *items*.
1094
1095
Georg Brandl7f01a132009-09-16 15:58:14 +00001096 .. method:: set(item, column=None, value=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001097
1098 With one argument, returns a dictionary of column/value pairs for the
1099 specified *item*. With two arguments, returns the current value of the
1100 specified *column*. With three arguments, sets the value of given
1101 *column* in given *item* to the specified *value*.
1102
1103
Georg Brandl7f01a132009-09-16 15:58:14 +00001104 .. method:: tag_bind(tagname, sequence=None, callback=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001105
1106 Bind a callback for the given event *sequence* to the tag *tagname*.
Benjamin Petersond23f8222009-04-05 19:13:16 +00001107 When an event is delivered to an item, the callbacks for each of the
Guilherme Polo5f238482009-01-28 14:41:10 +00001108 item's tags option are called.
1109
1110
Georg Brandl7f01a132009-09-16 15:58:14 +00001111 .. method:: tag_configure(tagname, option=None, **kw)
Guilherme Polo5f238482009-01-28 14:41:10 +00001112
1113 Query or modify the options for the specified *tagname*.
1114
1115 If *kw* is not given, returns a dict of the option settings for
1116 *tagname*. If *option* is specified, returns the value for that *option*
1117 for the specified *tagname*. Otherwise, sets the options to the
1118 corresponding values for the given *tagname*.
1119
1120
Georg Brandl7f01a132009-09-16 15:58:14 +00001121 .. method:: tag_has(tagname, item=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001122
1123 If *item* is specified, returns 1 or 0 depending on whether the specified
1124 *item* has the given *tagname*. Otherwise, returns a list of all items
Benjamin Petersond23f8222009-04-05 19:13:16 +00001125 that have the specified tag.
Guilherme Polo5f238482009-01-28 14:41:10 +00001126
1127 Availability: Tk 8.6
1128
1129
1130 .. method:: xview(*args)
1131
1132 Query or modify horizontal position of the treeview.
1133
1134
1135 .. method:: yview(*args)
1136
1137 Query or modify vertical position of the treeview.
1138
1139
1140.. _TtkStyling:
1141
1142Ttk Styling
1143-----------
1144
1145Each widget in :mod:`ttk` is assigned a style, which specifies the set of
1146elements making up the widget and how they are arranged, along with dynamic
1147and default settings for element options. By default the style name is the
1148same as the widget's class name, but it may be overriden by the widget's style
1149option. If you don't know the class name of a widget, use the method
1150:meth:`Misc.winfo_class` (somewidget.winfo_class()).
1151
1152.. seealso::
1153
1154 `Tcl'2004 conference presentation <http://tktable.sourceforge.net/tile/tile-tcl2004.pdf>`_
1155 This document explains how the theme engine works
1156
1157
1158.. class:: Style
1159
1160 This class is used to manipulate the style database.
1161
1162
1163 .. method:: configure(style, query_opt=None, **kw)
1164
Benjamin Petersond23f8222009-04-05 19:13:16 +00001165 Query or set the default value of the specified option(s) in *style*.
Guilherme Polo5f238482009-01-28 14:41:10 +00001166
1167 Each key in *kw* is an option and each value is a string identifying
1168 the value for that option.
1169
1170 For example, to change every default button to be a flat button with
Raymond Hettinger238018c2009-04-08 08:23:44 +00001171 some padding and a different background color::
Guilherme Polo5f238482009-01-28 14:41:10 +00001172
1173 from tkinter import ttk
1174 import tkinter
1175
1176 root = tkinter.Tk()
1177
1178 ttk.Style().configure("TButton", padding=6, relief="flat",
1179 background="#ccc")
1180
1181 btn = ttk.Button(text="Sample")
1182 btn.pack()
1183
1184 root.mainloop()
1185
1186
1187 .. method:: map(style, query_opt=None, **kw)
1188
1189 Query or sets dynamic values of the specified option(s) in *style*.
1190
Benjamin Petersond23f8222009-04-05 19:13:16 +00001191 Each key in *kw* is an option and each value should be a list or a
1192 tuple (usually) containing statespecs grouped in tuples, lists, or
Raymond Hettinger238018c2009-04-08 08:23:44 +00001193 some other preference. A statespec is a compound of one
Benjamin Petersond23f8222009-04-05 19:13:16 +00001194 or more states and then a value.
Guilherme Polo5f238482009-01-28 14:41:10 +00001195
1196 An example may make it more understandable::
1197
1198 import tkinter
1199 from tkinter import ttk
1200
1201 root = tkinter.Tk()
1202
1203 style = ttk.Style()
1204 style.map("C.TButton",
1205 foreground=[('pressed', 'red'), ('active', 'blue')],
1206 background=[('pressed', '!disabled', 'black'), ('active', 'white')]
1207 )
1208
1209 colored_btn = ttk.Button(text="Test", style="C.TButton").pack()
1210
1211 root.mainloop()
1212
1213
Benjamin Petersond23f8222009-04-05 19:13:16 +00001214 Note that the order of the (states, value) sequences for an option does
Raymond Hettinger238018c2009-04-08 08:23:44 +00001215 matter, if the order is changed to ``[('active', 'blue'), ('pressed',
1216 'red')]`` in the foreground option, for example, the result would be a
1217 blue foreground when the widget were in active or pressed states.
Guilherme Polo5f238482009-01-28 14:41:10 +00001218
1219
Georg Brandl7f01a132009-09-16 15:58:14 +00001220 .. method:: lookup(style, option, state=None, default=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001221
1222 Returns the value specified for *option* in *style*.
1223
1224 If *state* is specified, it is expected to be a sequence of one or more
1225 states. If the *default* argument is set, it is used as a fallback value
1226 in case no specification for option is found.
1227
Raymond Hettinger238018c2009-04-08 08:23:44 +00001228 To check what font a Button uses by default::
Guilherme Polo5f238482009-01-28 14:41:10 +00001229
1230 from tkinter import ttk
1231
Ezio Melotti985e24d2009-09-13 07:54:02 +00001232 print(ttk.Style().lookup("TButton", "font"))
Guilherme Polo5f238482009-01-28 14:41:10 +00001233
1234
Georg Brandl7f01a132009-09-16 15:58:14 +00001235 .. method:: layout(style, layoutspec=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001236
1237 Define the widget layout for given *style*. If *layoutspec* is omitted,
1238 return the layout specification for given style.
1239
Benjamin Petersond23f8222009-04-05 19:13:16 +00001240 *layoutspec*, if specified, is expected to be a list or some other
1241 sequence type (excluding strings), where each item should be a tuple and
Guilherme Polo5f238482009-01-28 14:41:10 +00001242 the first item is the layout name and the second item should have the
1243 format described described in `Layouts`_.
1244
Benjamin Petersond23f8222009-04-05 19:13:16 +00001245 To understand the format, see the following example (it is not
1246 intended to do anything useful)::
Guilherme Polo5f238482009-01-28 14:41:10 +00001247
1248 from tkinter import ttk
1249 import tkinter
1250
1251 root = tkinter.Tk()
1252
1253 style = ttk.Style()
1254 style.layout("TMenubutton", [
1255 ("Menubutton.background", None),
1256 ("Menubutton.button", {"children":
1257 [("Menubutton.focus", {"children":
1258 [("Menubutton.padding", {"children":
1259 [("Menubutton.label", {"side": "left", "expand": 1})]
1260 })]
1261 })]
1262 }),
1263 ])
1264
1265 mbtn = ttk.Menubutton(text='Text')
1266 mbtn.pack()
1267 root.mainloop()
1268
1269
1270 .. method:: element_create(elementname, etype, *args, **kw)
1271
Benjamin Petersond23f8222009-04-05 19:13:16 +00001272 Create a new element in the current theme, of the given *etype* which is
Guilherme Polo5f238482009-01-28 14:41:10 +00001273 expected to be either "image", "from" or "vsapi". The latter is only
1274 available in Tk 8.6a for Windows XP and Vista and is not described here.
1275
1276 If "image" is used, *args* should contain the default image name followed
Benjamin Petersond23f8222009-04-05 19:13:16 +00001277 by statespec/value pairs (this is the imagespec), and *kw* may have the
Guilherme Polo5f238482009-01-28 14:41:10 +00001278 following options:
1279
1280 * border=padding
1281 padding is a list of up to four integers, specifying the left, top,
1282 right, and bottom borders, respectively.
1283
1284 * height=height
1285 Specifies a minimum height for the element. If less than zero, the
1286 base image's height is used as a default.
1287
1288 * padding=padding
1289 Specifies the element's interior padding. Defaults to border's value
1290 if not specified.
1291
1292 * sticky=spec
1293 Specifies how the image is placed within the final parcel. spec
1294 contains zero or more characters “n”, “s”, “w”, or “e”.
1295
1296 * width=width
1297 Specifies a minimum width for the element. If less than zero, the
1298 base image's width is used as a default.
1299
Benjamin Petersond23f8222009-04-05 19:13:16 +00001300 If "from" is used as the value of *etype*,
1301 :meth:`element_create` will clone an existing
1302 element. *args* is expected to contain a themename, from which
Guilherme Polo5f238482009-01-28 14:41:10 +00001303 the element will be cloned, and optionally an element to clone from.
1304 If this element to clone from is not specified, an empty element will
Benjamin Petersond23f8222009-04-05 19:13:16 +00001305 be used. *kw* is discarded.
Guilherme Polo5f238482009-01-28 14:41:10 +00001306
1307
1308 .. method:: element_names()
1309
1310 Returns the list of elements defined in the current theme.
1311
1312
1313 .. method:: element_options(elementname)
1314
1315 Returns the list of *elementname*'s options.
1316
1317
Georg Brandl7f01a132009-09-16 15:58:14 +00001318 .. method:: theme_create(themename, parent=None, settings=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001319
1320 Create a new theme.
1321
1322 It is an error if *themename* already exists. If *parent* is specified,
1323 the new theme will inherit styles, elements and layouts from the parent
1324 theme. If *settings* are present they are expected to have the same
1325 syntax used for :meth:`theme_settings`.
1326
1327
1328 .. method:: theme_settings(themename, settings)
1329
1330 Temporarily sets the current theme to *themename*, apply specified
1331 *settings* and then restore the previous theme.
1332
1333 Each key in *settings* is a style and each value may contain the keys
1334 'configure', 'map', 'layout' and 'element create' and they are expected
1335 to have the same format as specified by the methods
1336 :meth:`Style.configure`, :meth:`Style.map`, :meth:`Style.layout` and
1337 :meth:`Style.element_create` respectively.
1338
Benjamin Petersond23f8222009-04-05 19:13:16 +00001339 As an example, let's change the Combobox for the default theme a bit::
Guilherme Polo5f238482009-01-28 14:41:10 +00001340
1341 from tkinter import ttk
1342 import tkinter
1343
1344 root = tkinter.Tk()
1345
1346 style = ttk.Style()
1347 style.theme_settings("default", {
1348 "TCombobox": {
1349 "configure": {"padding": 5},
1350 "map": {
1351 "background": [("active", "green2"),
1352 ("!disabled", "green4")],
1353 "fieldbackground": [("!disabled", "green3")],
1354 "foreground": [("focus", "OliveDrab1"),
1355 ("!disabled", "OliveDrab2")]
1356 }
1357 }
1358 })
1359
1360 combo = ttk.Combobox().pack()
1361
1362 root.mainloop()
1363
1364
1365 .. method:: theme_names()
1366
1367 Returns a list of all known themes.
1368
1369
Georg Brandl7f01a132009-09-16 15:58:14 +00001370 .. method:: theme_use(themename=None)
Guilherme Polo5f238482009-01-28 14:41:10 +00001371
Benjamin Petersond23f8222009-04-05 19:13:16 +00001372 If *themename* is not given, returns the theme in use. Otherwise, sets
Guilherme Polo5f238482009-01-28 14:41:10 +00001373 the current theme to *themename*, refreshes all widgets and emits a
1374 <<ThemeChanged>> event.
1375
1376
1377Layouts
1378^^^^^^^
1379
Benjamin Petersond23f8222009-04-05 19:13:16 +00001380A layout can be just None, if it takes no options, or a dict of
1381options specifying how to arrange the element. The layout mechanism
1382uses a simplified version of the pack geometry manager: given an
1383initial cavity, each element is allocated a parcel. Valid
1384options/values are:
Guilherme Polo5f238482009-01-28 14:41:10 +00001385
1386 * side: whichside
Benjamin Petersond23f8222009-04-05 19:13:16 +00001387 Specifies which side of the cavity to place the element; one of
Guilherme Polo5f238482009-01-28 14:41:10 +00001388 top, right, bottom or left. If omitted, the element occupies the
1389 entire cavity.
1390
1391 * sticky: nswe
1392 Specifies where the element is placed inside its allocated parcel.
1393
1394 * unit: 0 or 1
1395 If set to 1, causes the element and all of its descendants to be treated as
1396 a single element for the purposes of :meth:`Widget.identify` et al. It's
1397 used for things like scrollbar thumbs with grips.
1398
1399 * children: [sublayout... ]
1400 Specifies a list of elements to place inside the element. Each
1401 element is a tuple (or other sequence type) where the first item is
1402 the layout name, and the other is a `Layout`_.
1403
1404.. _Layout: `Layouts`_