enthought / traitsui
1
#  Copyright (c) 2008-19, Enthought, Inc.
2
#  All rights reserved.
3
#
4
#  This software is provided without warranty under the terms of the BSD
5
#  license included in LICENSE.txt and may be redistributed only
6
#  under the conditions described in the aforementioned license.  The license
7
#  is also available online at http://www.enthought.com/licenses/BSD.txt
8
#
9
#  Thanks for using Enthought open source!
10
#
11
#  Author: David C. Morrill
12
#  Date:   08/18/2008
13

14 4
"""
15
Defines some helper classes and traits used to define 'bindable' editor
16
values.  These classes and associated traits are designed to simplify
17
writing editors by allowing the editor factory to specify a context value
18
instance for attributes and have the value on the editor be synchronized
19
with the corresponsing value rom the context.
20

21
The factory should look something like this::
22

23
    class MyEditorFactory(EditorFactory):
24

25
        #: The minimum value.
26
        minimum = CVInt
27

28
        #: The suffix for the data.
29
        suffix = CVType(Str)
30

31
The editor class needs to have traits which correspond to the context value
32
traits, and should be able to react to changes to them::
33

34
    class MyEditor(Editor):
35

36
        #: The minimum value.
37
        minimum = Int()
38

39
        #: The suffix for the data.
40
        suffix = Str()
41

42
This can then be used in views, with values either as constants or as
43
instances of :class:`ContextValue` (abbreviated as ``CV``)::
44

45
    class MyObject(HasTraits):
46

47
        #: An important value.
48
        my_value = Str()
49

50
        #: The minimum value.
51
        my_minimum = Int(10)
52

53
        traits_view = View(
54
            Item(
55
                'my_value',
56
                editor=MyEditorFactory(
57
                    minimum=CV('my_minimum'),
58
                    suffix='...',
59
                ),
60
            )
61
        )
62
"""
63

64

65 4
from traits.api import HasStrictTraits, Instance, Str, Int, Float, Either
66

67

68 4
class ContextValue(HasStrictTraits):
69
    """ Defines the name of a context value that can be bound to an editor
70

71
    Resolution of the name follows the same rules as for context values in
72
    Item objects: if there is no dot in it then it is treated as an
73
    attribute of the 'object' context value, other wise the first part
74
    specifies the object in the context and the rest are dotted attribute
75
    look-ups.
76
    """
77

78
    #: The extended trait name of the value that can be bound to the editor
79
    #: (e.g. 'selection' or 'handler.selection'):
80 4
    name = Str()
81

82
    # ------------------------------------------------------------------------
83
    # object Interface
84
    # ------------------------------------------------------------------------
85

86 4
    def __init__(self, name):
87 4
        super(ContextValue, self).__init__(name=name)
88

89

90
#: Define a shorthand name for a ContextValue:
91 4
CV = ContextValue
92

93

94
# Trait definitions useful in defining bindable editor traits ---------------
95

96

97 4
def CVType(type, **metadata):
98
    """ Factory that creates a union of a trait type and a ContextValue trait.
99

100
    This also sets up one-way synchronization to the editor if no
101
    other synchronization is specified.
102

103
    Parameters
104
    ----------
105
    type : trait type
106
        The trait type that is expected for constant values.
107
    **metadata
108
        Additional metadata for the trait.
109

110
    Returns
111
    -------
112
    cv_type_trait : trait
113
        A trait which can either hold a constant of the specified
114
        type or an instance of the ContextValue class.
115
    """
116 4
    metadata.setdefault("sync_value", "to")
117 4
    return Either(type, InstanceOfContextValue, **metadata)
118

119

120
#: Shorthand for an Instance of ContextValue trait.
121 4
InstanceOfContextValue = Instance(ContextValue, allow_none=False)
122

123
#: Int or Context value trait
124 4
CVInt = CVType(Int)
125

126
#: Float or Context value trait
127 4
CVFloat = CVType(Float)
128

129
#: Str or Context value trait
130 4
CVStr = CVType(Str)

Read our documentation on viewing source code .

Loading