 |
Chemical Data Processing Library Python API - Version 1.2.0
|
|
Chemical Data Processing Library Python API - Version 1.2.0
|
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) | |
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.
| key | |
| value |
| 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.
| key | The key of the control-parameter entry to remove. |
True if an entry for key could be found and was removed, and False otherwise. | 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.
| key | The 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. |
| local | Specifies whether or not the request shall be forwarded to the parent container if a local entry for the control-parameter does not exist. |
| Base.ItemNotFound | if an entry for the requested control-parameter value does not exist and _throw is True. |
| Any CDPL.Base.ControlParameterContainer.getParameterOrDefault | ( | LookupKey | key, |
| Any | def_value, | ||
| bool | local = False |
||
| ) |
| key | |
| def_value | |
| local |
| 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.
| key | The key of the control-parameter. |
| local | Specifies whether or not the query shall be forwarded to the parent container if a local entry for the control-parameter does not exist. |
True if an entry for the specified control-parameter could be found, and False otherwise. | 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.
| 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.
| cntnr | The ControlParameterContainer instance containing the control-parameter value entries to add. |
| 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.
| cntnr | The ControlParameterContainer instance containing the control-parameter value entries to add. |
| int CDPL.Base.ControlParameterContainer.getNumParameters | ( | ) |
Returns the number of container entries.
| int CDPL.Base.ControlParameterContainer.registerParameterChangedCallback | ( | VoidLookupKeyAnyFunctor | func | ) |
Registers a callback target function that gets invoked when the value of a control-parameter has changed.
| func | A ControlParameterContainer.ParameterChangedCallbackFunction object wrapping the target function. |
| 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.
| id | The identifier of the callback to unregister. |
| int CDPL.Base.ControlParameterContainer.registerParameterRemovedCallback | ( | VoidLookupKeyFunctor | func | ) |
Registers a callback target function that gets invoked when a control-parameter entry has been removed.
| func | A ControlParameterContainer.ParameterRemovedCallbackFunction object wrapping the target function. |
| 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.
| id | The identifier of the callback to unregister. |
| 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.
| func | A ControlParameterContainer.ParentChangedCallbackFunction object wrapping the target function. |
| 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.
| id | The identifier of the callback to unregister. |
| ControlParameterContainer CDPL.Base.ControlParameterContainer.getParent | ( | ) |
Returns a reference to the parent control-parameter container.
| 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.
| cntnr | A reference to the parent control-parameter container or None. If the reference is None, the currently set parent container (if any) gets detached. |
| list CDPL.Base.ControlParameterContainer.getParameterKeys | ( | ) |
| list CDPL.Base.ControlParameterContainer.getParameterValues | ( | ) |
| list CDPL.Base.ControlParameterContainer.getParameters | ( | ) |
Returns a reference to itself.
| 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().
| key | |
| value |
| bool CDPL.Base.ControlParameterContainer.__delitem__ | ( | LookupKey | self | ) |
| arg1 |
| bool CDPL.Base.ControlParameterContainer.__contains__ | ( | LookupKey | self, |
| bool | key | ||
| ) |
Returns the result of the membership test operation self in arg1.
| self | The value to test for membership. |
| int CDPL.Base.ControlParameterContainer.__len__ | ( | ) |
1.9.1