Base 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 val)
	Sets the value of the control-parameter specified by key to val. More...

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_val, bool local=False)
	Returns the value of the control-parameter specified by key , or the default value def_val if an entry does not exist. More...

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 of the `ControlParameterContainer` instance cntnr. More...

None	copyParameters (ControlParameterContainer cntnr)
	Replaces the current control-parameter entries 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 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 ()
	Returns a list containing the keys of the current control-parameter entries. More...

list	getParameterValues ()
	Returns a list containing the values of the current control-parameter entries. More...

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)
	Returns the value of the control-parameter specified by key. More...

None	__setitem__ (LookupKey key, Any val)
	Sets the value of the control-parameter specified by key to val. More...

bool	__delitem__ (LookupKey key)
	Removes the entry for the control-parameter specified by key. More...

bool	__contains__ (LookupKey key)
	Tells whether or not a value has been assigned to the control-parameter specified by key. More...

int	__len__ ()
	Returns the number of container entries. More...

Properties
	objectID = property(getObjectID)

	parent = property(getParent, setParent)

	parameterKeys = property(getParameterKeys)

	parameterValues = property(getParameterValues)

	parameters = property(getParameters)

	numParameters = property(getNumParameters)

Detailed Description

Base 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.

Control-parameters are stored in an associative map as Base.LookupKey / Base.Any pairs. The current number of entries can be queried with the method getNumParameters().

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() method is provided which expects 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 does not exist.

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 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:

registerParameterChangedCallback()
registers callback target functions that get invoked when the value of a control-parameter has changed
registerParameterRemovedCallback()
registers callback target functions that get invoked when a control-parameter entry has been removed
and registerParentChangedCallback()
is used to register callback target functions that get invoked when the parent container has been changed or was detached

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	val
	)

Sets the value of the control-parameter specified by key to val.

If val is None, and a control-parameter entry for key exists, the entry gets erased (equivalent to removeParameter() with key as argument). Otherwise the control-parameter is assigned the specified value and any callback functions registered by registerParameterChangedCallback() will be invoked with key and val 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

key	The key of the control-parameter value to assign or remove.
val	The value of the control-parameter.

◆ 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

key	The 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 result 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 instance is returned if _throw is False, and a Base.ItemNotFound exception will be thrown if _throw is True.

Parameters

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.

Returns: The stored control-parameter value or an empty Base.Any instance.

Exceptions

Base.ItemNotFound if 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_val,
		bool	local = `False`
	)

Returns the value of the control-parameter specified by key , or the default value def_val if an entry does not exist.

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, a parent container has been set and the argument local is False, the call is forwarded to the parent (which may also forward the request). Otherwise the default value specified by def_val is returned.

Parameters

key	The key of the control-parameter for which to return the stored (or specified default) value.
def_val	The default value that shall be returned if an entry for the specified 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.

Returns: The stored control-parameter value or the default specified by def_val.

◆ 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

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.

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 of the ControlParameterContainer instance cntnr.

Any control-parameters which have no corresponding entry 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

cntnr The ControlParameterContainer instance providing the control-parameter entries to add.

◆ copyParameters()

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

Replaces the current control-parameter entries 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

cntnr The ControlParameterContainer instance providing the control-parameter entries to copy.

◆ 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

func	A Base.VoidLookupKeyFunctor instance 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

id	The 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

func	A Base.VoidLookupKeyFunctor instance 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

id	The 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

func	A Base.VoidFunctor instance 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

id	The identifier of the callback to unregister.

◆ getParent()

ControlParameterContainer CDPL.Base.ControlParameterContainer.getParent ( )

Returns the parent control-parameter container.

Returns: 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 None). Callbacks of any direct and indirect children also get invoked.

Parameters

cntnr The parent control-parameter container or None. If the reference equals None, the currently set parent container (if any) gets detached.

◆ getParameterKeys()

list CDPL.Base.ControlParameterContainer.getParameterKeys ( )

Returns a list containing the keys of the current control-parameter entries.

Returns: A list containing the requested control-parameter keys.

◆ getParameterValues()

list CDPL.Base.ControlParameterContainer.getParameterValues ( )

Returns a list containing the values of the current control-parameter entries.

Returns: A list containing the requested control-parameter values.

◆ 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 )

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. Otherwise a Base.ItemNotFound exception will be thrown.

Parameters

key	The key of the control-parameter value to return.

Returns: The stored control-parameter value.

Exceptions

Base.ItemNotFound if an entry for the requested control-parameter value does not exist.

◆ setitem()

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

Sets the value of the control-parameter specified by key to val.

If val is of type Base.Any and empty, i.e. the method Base.Any.isEmpty() returns True, and a control-parameter entry for key exists, the entry gets erased (equivalent to removeParameter() with key as argument). Otherwise the control-parameter is assigned the specified value and any callback functions registered by registerParameterChangedCallback() will be invoked with key and val 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

key	The key of the control-parameter value to assign or remove.
val	The value of the control-parameter.

◆ delitem()

bool CDPL.Base.ControlParameterContainer.__delitem__ ( 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

key	The key of the control-parameter entry to remove.

Returns: True if an entry for key could be found and was removed, and False otherwise.

◆ contains()

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

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

Parameters

key	The key of the control-parameter.

Returns: True if an entry for the specified control-parameter could be found, and False otherwise.

◆ len()

int CDPL.Base.ControlParameterContainer.__len__ ( )

Returns the number of container entries.

Returns: The number of container entries.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ setParameter()

◆ removeParameter()

◆ getParameter()

◆ getParameterOrDefault()

◆ isParameterSet()

◆ clearParameters()

◆ addParameters()

◆ copyParameters()

◆ getNumParameters()

◆ registerParameterChangedCallback()

◆ unregisterParameterChangedCallback()

◆ registerParameterRemovedCallback()

◆ unregisterParameterRemovedCallback()

◆ registerParentChangedCallback()

◆ unregisterParentChangedCallback()

◆ getParent()

◆ setParent()

◆ getParameterKeys()

◆ getParameterValues()

◆ getParameters()

◆ getObjectID()

◆ __getitem__()

◆ __setitem__()

◆ __delitem__()

◆ __contains__()

◆ __len__()

◆ getitem()

◆ setitem()

◆ delitem()

◆ contains()

◆ len()