7
Beginning in Traits 3.0, TraitsUI supports using *themes* to customize the
8
appearance of user interfaces, by applying graphical elements extracted from
9
simple images. For example, Figure 8 shows an unthemed Traits user interface.
11
.. figure:: images/unthemed_ui.jpg
12
:alt: Dialog box with standard widgets
14
Figure 8: Unthemed Traits user interface
16
Figure 9 shows the same user interface with a theme applied to it.
18
.. figure:: images/themed_ui1.jpg
19
:alt: Dialog box with blue labels and an orange-outlined heading
21
Figure 9: Themed Traits user interface
23
Figure 10 shows the same user interface with a different theme applied.
25
.. figure:: images/themed_ui2.jpg
26
:alt: Dialog box with tan background and raised widgets and labels
28
Figure 10: Theme Traits user interface with alternate theme
33
All of the data used by TraitsUI for themes is in the form of simple images, a
34
few examples of which are shown in Figure 11:
36
.. image:: images/theme_image1.gif
37
:alt: Gray square with rounded, gray, shaded border
39
.. image:: images/theme_image2.gif
40
:alt: Yellow square with sharp-cornered, orange, raised border
42
.. figure:: images/theme_image3.gif
43
:alt: Green square, raised, with no border
45
Figure 11: Theme images
47
Any type of JPEG or Portable Network Graphics (PNG) file is supported. In
48
particular, PNG files with alpha information allow smooth compositing of
49
multiple theme images. The first image in Figure 11 is an example of a PNG
50
file containing alpha information. That is, the interior of the rectangle is not
51
gray, but transparent, with a thin alpha gradient shadow around its edges.
53
Themeable TraitsUI Elements
54
----------------------------
56
Theme information can be applied to the following classes of TraitsUI objects:
62
All of these classes have **item_theme** and **label_theme** attributes, which
63
specify the themes for an editor and its label, respectively; the Group class
64
also has a **group_theme** attribute, which specifies the theme for the group
65
itself. These attributes are defined to be Theme traits, which accept values
66
which are either PyFace ImageResource objects, or strings that specify an image
67
file to use. In the case of string values, no path information need be included.
68
The path to the image file is assumed to be the images subdirectory or
69
:file:`images.zip` file located in the same directory as the source file
70
containing the string. [13]_ However, if the string begins with an '@'
71
(at-sign), the string is assumed to be a reference to an image in the default
72
image library provided with PyFace. [14]_
74
The **item_theme** and **label_theme** attributes are transferred via
75
containment. That is, if an Item object has an **item_theme** defined, that
76
value is used for the Item object's editor. If **item_theme** is not defined on
77
the Item object, the **item_theme** value from the containing Group is used, and
78
so on up to the **item_theme** value on containing View, if necessary.
79
Therefore, it is possible to set the item and label themes for a whole user
80
interface at the view level.
82
The **group_theme** attribute value is not transferred through containment, but
83
nested groups automatically visually inherit the theme of the containing group.
84
You can, of course, explicitly specify theme information at each level of a
85
nested group hierarchy.
90
To add themes to a Traits user interface, you add the theme-related attributes
91
to the View, Group, and Item definitions. Example 10 shows the code for the
92
unthemed user interface shown in Figure 8.
94
.. _example-10-traits-ui-without-themes:
96
.. rubric:: Example 10: TraitsUI without themes
103
# unthemed.py -- Example of a TraitsUI without themes
104
from traits.api import HasTraits, Str, Range, Float, Enum
105
from traitsui.api import View, Group, Item, Label
106
class Test ( HasTraits ):
109
age = Range( 1, 100 )
111
gender = Enum( 'Male', 'Female' )
115
Label( 'An Unthemed Label' ),
121
title = 'Unthemed TraitsUI',
124
Test().configure_traits()
126
Example 11 shows the code for the user interface shown in Figure 9, which is
127
essentially the same as in Example 10, but with theme data added.
129
.. _example-11-traits-ui-with-themese:
131
.. rubric:: Example 11: TraitsUI with themes
135
# themed.py -- Example of a TraitsUI with themes
136
from traits.api import HasTraits, Str, Range, Float, Enum
137
from traitsui.api import View, Group, Item, Label
138
from traitsui.wx.themed_text_editor import \
141
class Test ( HasTraits ):
144
age = Range( 1, 100 )
146
gender = Enum( 'Male', 'Female' )
151
Label( 'A Themed Label', '@GF6' ),
154
Item( 'weight', editor=ThemedTextEditor()),
162
title = 'Themed TraitsUI',
165
Test().configure_traits()
167
This example uses the following theme-related items:
169
- The **group_theme**, **item_theme**, and **label_theme** attributes are
170
explicitly specified (lines 24 to 26).
171
- The Label constructor (line 17)takes an optional second argument (in this
172
case '@GF6'), which specifies the **item_theme** information for the Label
173
object. (Label is a subclass of Item.)
174
- The item for weight (line 20) uses a ThemedTextEditor factory; this isn't
175
strictly necessary, but illustrates the use of a themed editor factory. For
176
more information on themed editor factories, refer to
177
:ref:`extra-trait-editor-factories`, and to the *Traits API Reference*.
178
- The example contains an extra Group level (line 16), and shows the results of
179
two nested **group_theme** values ('@G' and '@GD0'). The outermost
180
**group_theme** value ('@G') specifies the gray background, while the
181
innermost **group_theme** value ('@GD0') specifies the light gray rectangle
182
drawn over it. This combination demonstrates the automatic compositing of
183
themes, since the rounded rectangle is transparent except where the light
185
- The theme data strings use the '@' prefix to reference images from the
186
default image library.
188
.. rubric:: Footnotes
190
.. [13] This is very similar to the way that PyFace ImageResource objects work
191
when no search path is specified.
193
.. [14] PyFace is provided by the pyface package in the Traits GUI
194
project (not to be confused with the TraitsUI package, traitsui,
195
the subject of this document.)
added
removed
docs/source/traitsui_user_manual/themes.rst
