5.2.2
Mapped Traits
If the Trait() function is called with parameters that
include one or more dictionaries, then the resulting trait is called a mapped trait. In practice, this means that the
resulting object actually contains two attributes:
·
An attribute whose value is a key in the dictionary used to
define the trait.
·
An attribute containing its corresponding value (i.e., the mapped
or shadow value). The name of the shadow
attribute is simply the base attribute name with an underscore appended.
Mapped traits can be used to allow a variety of
user-friendly input values to be mapped to a set of internal, program-friendly
values.
The following examples illustrates mapped traits that map
color names to tuples representing red, green, blue, and transparency values:
# mapped.py --- Example of a mapped trait
from
enthought.traits.api import HasTraits, Trait
standard_color
= Trait ('black',
{'black': (0.0, 0.0, 0.0, 1.0),
'blue': (0.0, 0.0, 1.0, 1.0),
'cyan': (0.0, 1.0, 1.0, 1.0),
'green': (0.0, 1.0, 0.0, 1.0),
'magenta': (1.0, 0.0, 1.0, 1.0),
'orange': (0.8, 0.196, 0.196, 1.0),
'purple': (0.69, 0.0, 1.0, 1.0),
'red': (1.0, 0.0, 0.0, 1.0),
'violet': (0.31, 0.184, 0.31, 1.0),
'yellow': (1.0, 1.0, 0.0, 1.0),
'white': (1.0, 1.0, 1.0, 1.0),
'transparent': (1.0, 1.0, 1.0, 0.0) } )
red_color =
Trait ('red', standard_color)
class
GraphicShape (HasTraits):
line_color = standard_color
fill_color = red_color
The GraphicShape class has two attributes: line_color and fill_color.
These attributes are defined in terms of the standard_color
trait, which uses a dictionary. The standard_color
trait is a mapped trait, which means that each GraphicShape instance has two
shadow attributes: line_color_ and fill_color_. Any time a new value is assigned to either
line_color or fill_color,
the corresponding shadow attribute is updated with the value in the dictionary
corresponding to the value assigned. For example:
>>>
import mapped
>>>
my_shape1 = mapped.GraphicShape()
>>>
print my_shape1.line_color, my_shape1.fill_color
black red
>>>
print my_shape1.line_color_, my_shape1.fill_color_
(0.0, 0.0,
0.0, 1.0) (1.0, 0.0, 0.0, 1.0)
>>>
my_shape2 = mapped.GraphicShape()
>>>
my_shape2.line_color = 'blue'
>>>
my_shape2.fill_color = 'green'
>>>
print my_shape2.line_color, my_shape2.fill_color
blue green
>>>
print my_shape2.line_color_, my_shape2.fill_color_
(0.0, 0.0,
1.0, 1.0) (0.0, 1.0, 0.0, 1.0)
This example shows how a mapped trait can be used to
create a user-friendly attribute (such as line_color)
and a corresponding program-friendly shadow attribute (such as line_color_). The shadow attribute is
program-friendly because it is usually in a form that can be directly used by
program logic.
There are a few other points to keep in mind when creating
a mapped trait:
·
If not all values passed to the Trait() function are
dictionaries, the non-dictionary values are copied directly to the shadow
attribute (i.e., the mapping used is the identity mapping).
·
Assigning directly to a shadow attribute (the attribute with the
trailing underscore in the name) is not allowed, and raises a TraitError.
The concept of a mapped trait extends beyond traits
defined via a dictionary. Any trait that has a shadow value is a mapped trait.
For example, for the Expression trait, the assigned value must be a valid
Python expression, and the shadow value is the compiled form of the expression.
|