Traits UI Integration¶
Bound class is a Traits UI
Item that can be used to place a
widget into a Traits UI
View and bind it to traits on the model or
It comes with its own
Editor that knows how to set up the
Binder and use it
as the control for the
Bound constructor takes a
Binder instance and some bindings. Bindings
are either instances of
Binding subclasses or, more conveniently,
specially-formatted strings that will be parsed to
traits_view = View( Bound( HBoxLayout( Label(id='label'), LineEdit(id='edit', placeholderText=u'An integer'), ), Factory('edit.validator', QtGui.QIntValidator), 'label.text << handler.label', 'edit.text := object.text', 'spacing = 5', ), )
View succinctly demonstrates most of the Traits UI features. The
HBoxLayout is a
Binder that transparently wraps the
QHBoxLayout Qt layout
object. It is slightly customized with a constructor that lets you declare the
child widgets by passing
Binder objects. Thus you can build most typical
layouts using a hierarchy of layout and widget
constructors can take an
id keyword argument that sets a name for the
Binder that should be unique to the tree of
Binder objects it is in. This
name will be used to refer to that
Binder in the bindings that follow. Other
traits that proxy Qt properties can also be set in the
They will be assigned when the underlying
QObject is assigned to the
Following the root
Binder is a list of
Binding strings or objects. These
follow a pattern of
'binder_trait <operator> model_trait_or_expression'. On
the left of the operator is either the name of a trait on the root
spacing refers to the
HBoxLayout.spacing property) or a dotted
reference to a trait on a descendant
Binder that has provided an explicit
edit.text refers to the
On the right side of the operator is an expression evaluated in the Traits UI
context. For a
Binding that writes back to the model (
PushedTo), this is restricted to a simple extended trait reference; i.e.
object.foo.bar but not
object.foo.bar + 10. This context starts with the
Traits UI context (i.e. has
handler at a minimum) and is
extended with any
Binder in the tree with a non-empty
PulledFrom, the expression will be parsed for extended trait references
and the binding will be evaluated whenever it changes.
format(handler.template, object.child.value) will re-evaluate and
assign to the left-hand side whenever
Annoyingly, at the moment we cannot detect when such a dotted
reference has a non-terminal non-
HasTraits object. In the example above,
handler.template.format(object.child.value) would cause an error because
handler.template is a string, not a
HasTraits object to which
a listener can be attached.
There are four operators that can be used in the string representations of
SetOnceTo: Set a value once. This evaluates the right-hand side once when the binding is established. No notifications will be sent afterwards.
PulledFrom: Pull values from the model. This evaluates the right-hand side once when the binding is established and whenever any traits used in the expression fire a change notification.
PushedTo: Push values from the
Binderto the model. When the
Bindertrait on the left-hand side changes, this will assign the new value to the attribute referenced on the right-hand side. No value is assigned on initialization.
SyncedWith: A combination of
PushedToto synchronize a binder trait with a model trait. Because the right-hand side of
PushedTois restricted to plain attribute references, so is this. Like
PulledFrom, the right-hand side will be evaluated when the binding is established and assigned to the left-hand side to initialize it.
And the last
Binding cannot be put into string form:
Factory: Call the provided function once when the binding is established, and set the value. No notifications will be sent afterwards.
Bindings which initialize a value (i.e.
Factory) will be evaluated in the order in which they
are specified. This can be important for initializing some Qt objects. For
example, setting up validator properties before assigning the value.
Bound takes the following optional keyword arguments:
- label :
- Like the normal
labelargument, except that if one is not provided, then
show_label=False. Since the
Itemis not exclusively associated with any single trait like other Traits UI
Itemsare, the default Traits UI behavior of using the trait name as a label is not useful.
- extra_context :
- Any extra objects that should be added to the context used to evaluate the right-hand-side of bindings.
- configure : function with signature
- A function to call after the root
Binderhas been constructed and the bindings established but before display. It will be passed the root
Binderand the context dictionary. This can be used to do customizations using the raw Qt API that may not be achievable using bindings alone.
- stylesheet :
- A Qt stylesheet applied to the root control.
- button_groups :
- Collect buttons in the UI into named, bindable groups that will be added to the context.