1
# Copyright (c) 2007, Enthought, Inc.
5
The example demonstrates how to create a 'settable cached' property. The example
6
itself is nonsensical, and is provided mainly to show how to set up such a
7
property, and how it differs from a standard 'cached' property.
9
A normal 'cached' property does not have a 'setter' method, meaning that the
10
property is read-only. It usually represents a value which depends upon the
11
state of other traits for its value. The cached property provides both a
12
mechanism for remembering (i.e. caching) the current value of the property as
13
well as a means of automatically detecting when the value of the property
14
changes (which causes the cache to be flushed), and notifying any associated
15
trait listeners that the value of the property has changed.
17
Normally there is no 'setter' for such a property because the value is derived
18
from the value of other traits.
20
However, it is possible to define a 'settable cached' property which in addition
21
to the capabilities of a normal 'cached' property, also allows the property's
22
value to be explicitly set.
24
To accomplish this, simply set the 'settable' argument to the
25
'property_depends_on' decorator to True (see the '_get_c' method in the
26
example code). When set this way, an appropriate 'setter' method is
27
automatically generated for the associated property.
29
This allows code to set the value of the property directly if desired, subject
30
to any constraints specified in the property declaration. For example, in the
31
example, the 'c' trait is a 'settable cached' property whose value must be an
32
integer. Attempting to set a non-integer value of the property will raise an
33
exception, just like any other trait would.
35
If any of the traits which the property depends upon change value, the current
36
value of the property will be flushed from the cache and a change notification
37
for the property will be generated. Any code that then attempts to read the
38
value of the property will result in the cache being reloaded with the new value
39
returned by the property's 'getter' method.
41
In the example, trait 'c' is a 'settable cached' property which returns the
42
product of 'a' times 'b', and trait 'd' is a normal 'cached' property that
43
returns double the value of 'c'.
45
To see the effect of these traits in action, try moving the 'a' and 'b' sliders
46
and watching the 'c' and 'd' traits update. This demonstrates how 'c' and 'd'
47
are properties that depend upon the values of other traits.
49
Now try changing the value of the 'c' trait by moving the slider or typing a
50
new value into the text entry field. You will see that the 'd' trait updates
51
as well, illustrating that the 'c' trait can be set directly, as well as
52
indirectly by changes to 'a' and 'b'.
54
Also, try typing non-numeric values into the 'c' field and you will see that
55
any values set are being type checked as well (i.e. they must be integer
58
Now try typing a value into the 'd' trait and you will see that an error
59
results (indicated by the text entry field turning red), because this is a
60
normal 'cached' trait that has no 'setter' method defined.
63
#-- Imports --------------------------------------------------------------------
66
import HasTraits, Int, Range, Property, property_depends_on
69
import View, Item, RangeEditor
71
#-- Demo Class -----------------------------------------------------------------
73
class SettableCachedProperty ( HasTraits ):
85
editor = RangeEditor( low = 1, high = 100, mode = 'slider' ) ),
89
editor = RangeEditor( low = 1, high = 400, mode = 'slider' ) ),
94
@property_depends_on( 'a,b', settable = True )
96
return (self.a * self.b)
98
@property_depends_on( 'c' )
100
return (self.c + self.c)
102
#-- Run the demo ---------------------------------------------------------------
105
demo = SettableCachedProperty()
107
# Run the demo (if invoked from the command line):
108
if __name__ == '__main__':
109
demo.configure_traits()
added
removed
examples/demo/Advanced/Settable_cached_property.py
