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""" 15Defines some helper classes and traits used to define 'bindable' editor 16values. These classes and associated traits are designed to simplify 17writing editors by allowing the editor factory to specify a context value 18instance for attributes and have the value on the editor be synchronized 19with the corresponsing value rom the context. 20 21The 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 31The editor class needs to have traits which correspond to the context value 32traits, 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 42This can then be used in views, with values either as constants or as 43instances 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 65from traits.api import HasStrictTraits, Instance, Str, Int, Float, Either 66 67 68class 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 name = Str() 81 82 # ------------------------------------------------------------------------ 83 # object Interface 84 # ------------------------------------------------------------------------ 85 86 def __init__(self, name): 87 super(ContextValue, self).__init__(name=name) 88 89 90#: Define a shorthand name for a ContextValue: 91CV = ContextValue 92 93 94# Trait definitions useful in defining bindable editor traits --------------- 95 96 97def 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 metadata.setdefault("sync_value", "to") 117 return Either(type, InstanceOfContextValue, **metadata) 118 119 120#: Shorthand for an Instance of ContextValue trait. 121InstanceOfContextValue = Instance(ContextValue, allow_none=False) 122 123#: Int or Context value trait 124CVInt = CVType(Int) 125 126#: Float or Context value trait 127CVFloat = CVType(Float) 128 129#: Str or Context value trait 130CVStr = CVType(Str) 131