fsleyes_props.bindable

This module adds functionality to the HasProperties class to allow properties from different instances to be bound to each other. This module also contains the core event loop notification logic that forms the foundation of the fsleyes_props library.

The logic defined in this module is separated purely to keep the properties and properties_value module file sizes down.

The following functions are defined in this module and are used by the the HasProperties class.

bindProps	Binds the properties specified by propName and otherPropName such that changes to one are applied to the other.
unbindProps	Unbinds two properties previously bound via a call to bindProps().
isBound	Returns True if the specified property is bound to the other HasProperties instance, False otherwise.

These functions use the following functions, which work directly with PropertyValue instances, and are available for advanced usage:

bindPropVals	Binds two PropertyValue instances together such that when the value of one changes, the other is changed.
propValsAreBound	Returns True if the given PropertyValue instances are bound to each other, False otherwise.

PropertyValue instances use the following methods for synchronisation of attribute and values, notification of their listeners, and access to other PropertyValue instances to which they are bound:

syncAndNotify	Synchronises the value contained in all bound PropertyValue instances with the value contained in this instance, and notifies all registered listeners of the value change.
syncAndNotifyAtts	This method is called by the PropertyValue.notifyAttributeListeners() method.
buildBPVList	Recursively builds a list of all PVs that are bound to this one, either directly or indirectly.

Example usage

>>> import fsleyes_props as props

>>> class MyObj(props.HasProperties):
        myint  = props.Int()
        myreal = props.Real()

>>> myobj1 = MyObj()
>>> myobj2 = MyObj()

# Set some initial values
>>> myobj1.myint  = 1
>>> myobj1.myreal = 0.1
>>> myobj2.myint  = 2
>>> myobj2.myreal = 0.12

# Bind myobj1.myint and myobj2.myint.
# The instance on which bindProps is
# called will inherit the value of the
# other instance
>>> myobj2.bindProps('myint', myobj1)

>>> print myobj2
MyObj
   myint = 1
  myreal = 0.2

# Changing a bound property value on either
# instance will result in the value being
# propagated to the other instance.
>>> myobj2.myint = 8
>>> print myobj1
MyObj
   myint = 8
  myreal = 0.1

Details

When a HasProperties property value is changed, the associated PropertyValue instance does two things:

1. Casts and validates the new value and updates its stored value.

2. Calls the syncAndNotify() function.

The syncAndNotify function then does the following:

3. Updates the value on all bound PropertyValue instances.

4. Notifies all listeners, registered on the source PV instance, of the value change.

5. Notifies all listeners, registered on the bound PV instances, of the value change.

An important point to note regarding step 2 above is that all PV instances which are bound, either directly or indirectly, to the source PV instance, will be updated. In other words, there are no restrictions on the ways in which PropertyValue instances may be bound. A tree, chain, or even a network of PV instances can be bound together - the above process will still work.

class fsleyes_props.bindable.Bidict

Bases: object

A bare-bones bi-directional dictionary, used for binding PropertyValueList instances - see the _bindListProps() and _syncPropValLists() functions.

get(key, default=None)

fsleyes_props.bindable.bindProps(self, propName, other, otherPropName=None, bindval=True, bindatt=True, unbind=False)

Binds the properties specified by propName and otherPropName such that changes to one are applied to the other.

The binding direction is from other to self, i.e. in the first instance, the value of self.propName will be set to that of other.propName.

If the properties are List properties, the _bindListProps() function is called. Otherwise the _bindProps() function is called.

Parameters:

• propName (str) – The name of a property on this HasProperties instance.

• other – Another HasProperties instance.

• otherPropName – The name of a property on other to bind to. If None it is assumed that there is a property on other called propName.

• bindval – If True (the default), property values are bound. This parameter is ignored for list properties.

• bindatt – If True (the default), property attributes are bound. For List properties, this parameter applies to the list values, not to the list itself.

• unbind – If True, the properties are unbound. See the unbindProps() method.

fsleyes_props.bindable.unbindProps(self, propName, other, otherPropName=None, bindval=True, bindatt=True)

Unbinds two properties previously bound via a call to bindProps().

fsleyes_props.bindable.isBound(self, propName, other, otherPropName=None)

Returns True if the specified property is bound to the other HasProperties instance, False otherwise.

fsleyes_props.bindable.syncAndNotifyAtts(self, name, value)

This method is called by the PropertyValue.notifyAttributeListeners() method.

It ensures that the attributes of any bound PropertyValue instances are synchronised, and then notifies all attribute listeners.

fsleyes_props.bindable.syncAndNotify(self)

Synchronises the value contained in all bound PropertyValue instances with the value contained in this instance, and notifies all registered listeners of the value change. This method is called by the PropertyValue.propNotify() method.

fsleyes_props.bindable.propValsAreBound(pv1, pv2)

Returns True if the given PropertyValue instances are bound to each other, False otherwise.

fsleyes_props.bindable.bindPropVals(myPropVal, otherPropVal, bindval=True, bindatt=True, unbind=False)

Binds two PropertyValue instances together such that when the value of one changes, the other is changed. Note that the values are not immediately synchronised - they will become synchronised on the next change to either PropertyValue.

See bindProps() for details on the parameters.

fsleyes_props.bindable.buildBPVList(self, key, node=None, bpvSet=None)

Recursively builds a list of all PVs that are bound to this one, either directly or indirectly.

For each PV, we also store a reference to the ‘parent’ PV, i.e. the PV to which it is directly bound, as the direct bindings are needed to synchronise list PVs.

Returns two lists - the first containing bound PVs, and the second containing the parent for each bound PV.

Parameters:

• self – The root PV.

• key – A string, either boundPropVals or boundAttPropVals.

• node – The current PV to begin this step of the recursive search from (do not pass in on the non-recursive call).

• bpvSet – A set used to prevent cycles in the depth-first search (do not pass in on the non-recursive call).