Chemical Data Processing Library Python API - Version 1.1.1
Public Member Functions | Properties | List of all members
CDPL.Base.ControlParameterContainer Class Reference

A class providing methods for the storage and lookup of control-parameter values. More...

+ Inheritance diagram for CDPL.Base.ControlParameterContainer:

Public Member Functions

None __init__ ()
 Constructs an empty ControlParameterContainer instance.
 
None setParameter (LookupKey key, Any value)
 
bool removeParameter (LookupKey key)
 Removes the entry for the control-parameter specified by key. More...
 
Any getParameter (LookupKey key, bool throw_=False, bool local=False)
 Returns the value of the control-parameter specified by key. More...
 
Any getParameterOrDefault (LookupKey key, Any def_value, bool local=False)
 
bool isParameterSet (LookupKey key, bool local=False)
 Tells whether or not a value has been assigned to the control-parameter specified by key. More...
 
None clearParameters ()
 Erases all container entries. More...
 
None addParameters (ControlParameterContainer cntnr)
 Adds the control-parameter value entries in the ControlParameterContainer instance cntnr. More...
 
None copyParameters (ControlParameterContainer cntnr)
 Replaces the current set of properties by a copy of the entries in cntnr. More...
 
int getNumParameters ()
 Returns the number of container entries. More...
 
int registerParameterChangedCallback (VoidLookupKeyAnyFunctor func)
 Registers a callback target function that gets invoked when the value of a control-parameter has changed. More...
 
None unregisterParameterChangedCallback (int id)
 Unregisters the callback specified by id. More...
 
int registerParameterRemovedCallback (VoidLookupKeyFunctor func)
 Registers a callback target function that gets invoked when a control-parameter entry has been removed. More...
 
None unregisterParameterRemovedCallback (int id)
 Unregisters the callback specified by id. More...
 
int registerParentChangedCallback (VoidFunctor func)
 Registers a callback target function that gets invoked when the parent container has been changed or was detached. More...
 
None unregisterParentChangedCallback (int id)
 Unregisters the callback specified by id. More...
 
ControlParameterContainer getParent ()
 Returns a reference to the parent control-parameter container. More...
 
None setParent (ControlParameterContainer cntnr)
 Sets or removes the parent control-parameter container used to resolve requests for missing entries. More...
 
list getParameterKeys ()
 
list getParameterValues ()
 
list getParameters ()
 Returns a reference to itself. More...
 
int getObjectID ()
 Returns the numeric identifier (ID) of the wrapped C++ class instance. More...
 
Any __getitem__ (LookupKey key)
 
None __setitem__ (LookupKey key, Any value)
 
bool __delitem__ (LookupKey self)
 
bool __contains__ (LookupKey self, bool key)
 Returns the result of the membership test operation self in arg1. More...
 
int __len__ ()
 

Properties

 objectID = property(getObjectID)
 
 parent = property(getParent, setParent)
 
 parameterKeys = property(getParameterKeys)
 
 parameterValues = property(getParameterValues)
 
 parameters = property(getParameters)
 
 numParameters = property(getNumParameters)
 

Detailed Description

A class providing methods for the storage and lookup of control-parameter values.

The purpose of ControlParameterContainer is to provide a common facility for the storage and lookup of dynamic parameter values to subclasses which can be used to control their runtime-behaviour.

For the explicit assignment of control-parameter values the method setParameter() is provided which expects the key of the control-parameter as its first and the value to assign as the second argument. The availability of a value for a particular control-parameter can be tested by the method isParameterSet(). For the retrieval of control-parameter values the getParameter() family of overloaded methods is provided which expect the key of the control-parameter as an argument. The method getParameterOrDefault() additionally allows to specify a default value that gets returned if an entry for the requested control-parameter value does not exist. ControlParameterContainer guarantees that the complexity of these operations is never worse than logarithmic.

Control-parameter values are stored in an associative map as Base.LookupKey / Base.Any pairs of type ControlParameterContainer.ParameterEntry. The current number of entries can be queried with the method getNumParameters(). Iterators pointing to the beginning and end of the container are obtained via the methods getEntriesBegin() and getEntriesEnd(), respectively.

ControlParameterContainer allows for an arrangement of instances in a tree-like hierarchy where each non-root instance has exactly one parent and zero or more children. In such hierarchies, a child container forwards requests for control-parameter values to their parents if they do not contain a local entry for a given control-parameter. The parent container is set and detached by the method setParent(). A ControlParameterContainer instance automatically keeps track of any links from and to other instances in the hierarchy and detaches any parent or child containers on object destruction.

For the notification of client code about any changes that affect control-parameter values, the ControlParameterContainer interface provides three methods for the registration of callback functions:

Each of these methods returns a numeric identifier for the registered callback function. For callback unregistration purposes the methods unregisterParameterChangedCallback(), unregisterParameterRemovedCallback() and unregisterParentChangedCallback() are provided. These methods require the previously obtained numeric identifier of the callback to be passed as an argument.

Member Function Documentation

◆ setParameter()

None CDPL.Base.ControlParameterContainer.setParameter ( LookupKey  key,
Any  value 
)
Parameters
key
value

◆ removeParameter()

bool CDPL.Base.ControlParameterContainer.removeParameter ( LookupKey  key)

Removes the entry for the control-parameter specified by key.

If an entry for the control-parameter specified by key exists, the entry is removed and any callback functions registered by registerParameterRemovedCallback() will be invoked with key provided as an argument. Callbacks of affected direct and indirect children which do not have an entry for the specified control-parameter also get invoked.

Parameters
keyThe key of the control-parameter entry to remove.
Returns
True if an entry for key could be found and was removed, and False otherwise.

◆ getParameter()

Any CDPL.Base.ControlParameterContainer.getParameter ( LookupKey  key,
bool   throw_ = False,
bool   local = False 
)

Returns the value of the control-parameter specified by key.

If the container contains an entry for the specified control-parameter, the stored value will be returned. If an entry for the control-parameter does not exist, the results depends on the arguments throw_ and local:

If a parent container has been set and the argument local is False, the request is forwarded to the parent (which may also forward the request). Otherwise an empty Base.Any object is returned if _throw is False, and a Base.ItemNotFound exception will be thrown if _throw is True.

Parameters
keyThe key of the control-parameter value to return.
throw_Specifies whether or not to throw a Base.ItemNotFound exception if an entry for the control-parameter does not exist.
localSpecifies whether or not the request shall be forwarded to the parent container if a local entry for the control-parameter does not exist.
Returns
The stored control-parameter value or an empty Base.Any object.
Exceptions
Base.ItemNotFoundif an entry for the requested control-parameter value does not exist and _throw is True.

◆ getParameterOrDefault()

Any CDPL.Base.ControlParameterContainer.getParameterOrDefault ( LookupKey  key,
Any  def_value,
bool   local = False 
)
Parameters
key
def_value
local
Returns

◆ isParameterSet()

bool CDPL.Base.ControlParameterContainer.isParameterSet ( LookupKey  key,
bool   local = False 
)

Tells whether or not a value has been assigned to the control-parameter specified by key.

If the container does not contain an entry for the specified control-parameter, a parent container has been set and the argument local is False, the call is forwarded to the parent (which may also forward the call). Otherwise the result of the local search is returned.

Parameters
keyThe key of the control-parameter.
localSpecifies whether or not the query shall be forwarded to the parent container if a local entry for the control-parameter does not exist.
Returns
True if an entry for the specified control-parameter could be found, and False otherwise.

◆ clearParameters()

None CDPL.Base.ControlParameterContainer.clearParameters ( )

Erases all container entries.

For each container entry, any callback functions registered by registerParameterRemovedCallback() will be invoked with the key of the removed control-parameter entry as an argument. Callbacks of affected direct and indirect children which do not have an entry for the erased control-parameter also get invoked.

◆ addParameters()

None CDPL.Base.ControlParameterContainer.addParameters ( ControlParameterContainer  cntnr)

Adds the control-parameter value entries in the ControlParameterContainer instance cntnr.

Any control-parameter values which have no corresponding assigned value in cntnr are left unchanged. Otherwise the value of the local control-parameter gets overwritten by the value stored in cntnr and any callback functions registered by registerParameterChangedCallback() will be invoked with key and value provided as arguments. Callbacks of affected direct and indirect children which do not have an entry for the specified control-parameter also get invoked.

Parameters
cntnrThe ControlParameterContainer instance containing the control-parameter value entries to add.

◆ copyParameters()

None CDPL.Base.ControlParameterContainer.copyParameters ( ControlParameterContainer  cntnr)

Replaces the current set of properties by a copy of the entries in cntnr.

The assignment is equivalent to first erasing all entries by calling clearParameters() and then calling setParameter() for each key/value entry in cntnr.

Parameters
cntnrThe ControlParameterContainer instance containing the control-parameter value entries to add.

◆ getNumParameters()

int CDPL.Base.ControlParameterContainer.getNumParameters ( )

Returns the number of container entries.

Returns
The number of container entries.

◆ registerParameterChangedCallback()

int CDPL.Base.ControlParameterContainer.registerParameterChangedCallback ( VoidLookupKeyAnyFunctor  func)

Registers a callback target function that gets invoked when the value of a control-parameter has changed.

Parameters
funcA ControlParameterContainer.ParameterChangedCallbackFunction object wrapping the target function.
Returns
An identifier for the registered callback.

◆ unregisterParameterChangedCallback()

None CDPL.Base.ControlParameterContainer.unregisterParameterChangedCallback ( int  id)

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters
idThe identifier of the callback to unregister.

◆ registerParameterRemovedCallback()

int CDPL.Base.ControlParameterContainer.registerParameterRemovedCallback ( VoidLookupKeyFunctor  func)

Registers a callback target function that gets invoked when a control-parameter entry has been removed.

Parameters
funcA ControlParameterContainer.ParameterRemovedCallbackFunction object wrapping the target function.
Returns
An identifier for the registered callback.

◆ unregisterParameterRemovedCallback()

None CDPL.Base.ControlParameterContainer.unregisterParameterRemovedCallback ( int  id)

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters
idThe identifier of the callback to unregister.

◆ registerParentChangedCallback()

int CDPL.Base.ControlParameterContainer.registerParentChangedCallback ( VoidFunctor  func)

Registers a callback target function that gets invoked when the parent container has been changed or was detached.

Parameters
funcA ControlParameterContainer.ParentChangedCallbackFunction object wrapping the target function.
Returns
An identifier for the registered callback.

◆ unregisterParentChangedCallback()

None CDPL.Base.ControlParameterContainer.unregisterParentChangedCallback ( int  id)

Unregisters the callback specified by id.

If a registered callback with the identifier id does not exist, the method has no effect.

Parameters
idThe identifier of the callback to unregister.

◆ getParent()

ControlParameterContainer CDPL.Base.ControlParameterContainer.getParent ( )

Returns a reference to the parent control-parameter container.

Returns
A reference to the parent control-parameter container, or None if no parent container has been set.
See also
setParent()

◆ setParent()

None CDPL.Base.ControlParameterContainer.setParent ( ControlParameterContainer  cntnr)

Sets or removes the parent control-parameter container used to resolve requests for missing entries.

A control-parameter container that has been set as a parent gets used whenever a request for a control-parameter value cannot be satisfied locally by the container itself. That is, if a key/value entry for a given control-parameter does not exist, the request is simply forwarded to the parent container (which may also forward the request).

Any callback functions registered by registerParentChangedCallback() will be invoked after the new parent container has been set (or the old container was detached by providing a None reference). Callbacks of any direct and indirect children also get invoked.

Parameters
cntnrA reference to the parent control-parameter container or None. If the reference is None, the currently set parent container (if any) gets detached.

◆ getParameterKeys()

list CDPL.Base.ControlParameterContainer.getParameterKeys ( )
Returns

◆ getParameterValues()

list CDPL.Base.ControlParameterContainer.getParameterValues ( )
Returns

◆ getParameters()

list CDPL.Base.ControlParameterContainer.getParameters ( )

Returns a reference to itself.

Returns
self

◆ getObjectID()

int CDPL.Base.ControlParameterContainer.getObjectID ( )

Returns the numeric identifier (ID) of the wrapped C++ class instance.

Different Python ControlParameterContainer instances may reference the same underlying C++ class instance. The commonly used Python expression a is not b thus cannot tell reliably whether the two ControlParameterContainer instances a and b reference different C++ objects. The numeric identifier returned by this method allows to correctly implement such an identity test via the simple expression a.getObjectID() != b.getObjectID().

Returns
The numeric ID of the internally referenced C++ class instance.

◆ __getitem__()

Any CDPL.Base.ControlParameterContainer.__getitem__ ( LookupKey  key)
Parameters
key
Returns

◆ __setitem__()

None CDPL.Base.ControlParameterContainer.__setitem__ ( LookupKey  key,
Any  value 
)
Parameters
key
value

◆ __delitem__()

bool CDPL.Base.ControlParameterContainer.__delitem__ ( LookupKey  self)
Parameters
arg1
Returns

◆ __contains__()

bool CDPL.Base.ControlParameterContainer.__contains__ ( LookupKey  self,
bool  key 
)

Returns the result of the membership test operation self in arg1.

Parameters
selfThe value to test for membership.
Returns
The result of the membership test operation.

◆ __len__()

int CDPL.Base.ControlParameterContainer.__len__ ( )
Returns