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