fsleyes_props.syncable

This module provides the SyncableHasProperties class, an extension to the HasProperties class which allows a parent-child relationship to exist between instances. A one-to-many synchronisation relationship is possible between one parent, and many children. Property values are synchronised between a parent and its children, using the functionality provided by the bindable module.

All that is needed to make use of this functionality is to extend the SyncableHasProperties class instead of the HasProperties class:

>>> import fsleyes_props as props

>>> class MyObj(props.SyncableHasProperties):
        myint = props.Int()
        def __init__(self, parent=None):
            props.SyncableHasProperties.__init__(self, parent=parent)

Given a class definition such as the above, a parent-child relationship between two instances can be set up as follows:

>>> myParent = MyObj()
>>> myChild  = MyObj(myParent)

The myint properties of both instances are now bound to each other - when it changes in one instance, that change is propagated to the other instance:

>>> def parentPropChanged(*a):
        print('myParent.myint changed: {}'.format(myParent.myint))
>>>
>>> def childPropChanged(*a):
        print('myChild.myint changed: {}'.format(myChild.myint))

>>> myParent.addListener('myint', 'parentPropChanged', parentPropChanged)
>>> myChild.addListener( 'myint', 'childPropChanged',  childPropChanged)

>>> myParent.myint = 12345
myParent.myint changed: 12345
myChild.myint changed: 12345

>>> myChild.myint = 54321
myParent.myint changed: 54321
myChild.myint changed: 54321

This synchronisation can be toggled on the child instance, via the unsyncFromParent() and syncToParent() methods of the SyncableHasProperties class. Listeners to sync state changes may be registered on the child instance via the addSyncChangeListener() method (and de-registered via the removeSyncChangeListener() method).

exception fsleyes_props.syncable.SyncError

Bases: Exception

Exception type raised when an illegal attempt is made to synchronise or unsynchronise a property. See the nobind and nounbind parameters to SyncableHasProperties.__init__().

class fsleyes_props.syncable.SyncableHasProperties(*args, **kwargs)

Bases: HasProperties

An extension to the HasProperties class which supports parent-child relationships between instances.

Create a SyncableHasProperties instance.

If this SyncableHasProperties instance does not have a parent, there is no need to call this constructor explicitly. Otherwise, the parent must be an instance of the same class to which this instance’s properties should be bound.

Parameters:

• parent – Another SyncableHasProperties instance, which has the same type as this instance.

• nobind – A sequence of property names which should not be bound with the parent.

• nounbind – A sequence of property names which cannot be unbound from the parent.

• state – Initial synchronised state. Can be either True or False, in which case all properties will initially be either synced or unsynced. Or can be a dictionary of {propName : boolean} mappings, defining the sync state for each property.

• direction – Initial binding direction. Not applicable if this instance does not have a parent. If True, when a property is bound to the parent, this instance will inherit the parent’s value. Otherwise, when a property is bound, the parent will inherit this instance’s value.

• kwargs – All other arguments are passed to the HasProperties.__init__() method.

classmethod getSyncPropertyName(propName)

Returns the name of the boolean property which can be used to toggle binding of the given property to the parent property of this instance.

classmethod getSyncProperty(propName)

Returns the PropertyBase instance of the boolean property which can be used to toggle binding of the given property to the parent property of this instance.

getParent()

Returns the parent of this instance, or None if there is no parent.

On child SyncableHasProperties instances, this method must not be called before __init__() has been called. If this happens, an AttributeError will be raised.

getChildren()

Returns a list of all children that are synced to this parent instance, or None if this instance is not a parent.

getBindingDirection(propName)

Returns the current binding direction for the given property. See the setBindingDirection() method.

setBindingDirection(direction, propName=None)

Set the current binding direction for the named property. If the direction is True, when this property is bound, this instance will inherit the parent’s value. Otherwise, when this property is bound, the parent will inherit the value from this instance.

If a property is not specified, the binding direction of all properties will be changed.

syncToParent(propName)

Synchronise the given property with the parent instance.

If this SyncableHasProperties instance has no parent, a RuntimeError is raised. If the specified property is in the nobind list (see __init__()), a SyncError is raised.

..note:: The nobind check can be avoided by calling

bindable.bindProps() directly. But don’t do that.

unsyncFromParent(propName)

Unsynchronise the given property from the parent instance.

If this SyncableHasProperties instance has no parent, a RuntimeError is raised. If the specified property is in the nounbind list (see __init__()), a SyncError is raised.

..note:: The nounbind check can be avoided by calling

bindable.bindProps() directly. But don’t do that.

syncAllToParent()

Synchronises all properties to the parent instance.

Does not attempt to synchronise properties in the nobind list.

unsyncAllFromParent()

Unynchronises all properties from the parent instance.

Does not attempt to synchronise properties in the nounbind list.

detachFromParent(propName)

If this is a child SyncableHasProperties instance, it detaches the specified property from its parent. This is an irreversible operation.

detachAllFromParent()

If this is a child SyncableHasProperties instance, it detaches itself from its parent. This is an irreversible operation.

TODO: Add the ability to dynamically set/clear the parent

SHP instance.

isSyncedToParent(propName)

Returns True if the specified property is synced to the parent of this SyncableHasProperties instance, False otherwise.

anySyncedToParent()

Returns True if any properties are synced to the parent of this SyncableHasProperties instance, False otherwise.

allSyncedToParent()

Returns True if all properties are synced to the parent of this SyncableHasProperties instance, False otherwise.

canBeSyncedToParent(propName)

Returns True if the given property can be synced between this SyncableHasProperties instance and its parent (see the nobind parameter in __init__()).

canBeUnsyncedFromParent(propName)

Returns True if the given property can be unsynced between this SyncableHasProperties instance and its parent (see the nounbind parameter in __init__()).

addSyncChangeListener(propName, listenerName, callback, overwrite=False, weak=True)

Registers the given callback function to be called when the sync state of the specified property changes.

removeSyncChangeListener(propName, listenerName)

De-registers the given listener from receiving sync state changes.