Interface for classes that can be configured from configuration-files and GUI-Components. More...

#include <Configurable.h>

Inheritance diagram for icl::utils::Configurable:

Classes
struct	Property
	Represents a single property. More...
Public Types
typedef Function< void, const Property & >	Callback
	Function type for changed properties.
Public Member Functions
	~Configurable ()
	virtual destructor
	Configurable (const Configurable &other)
	Copy constructor.
Configurable &	operator= (const Configurable &other)
	Assignment operator.
void	setConfigurableID (const std::string &ID) throw (ICLException)
	sets the ID of this configurable
const std::string &	getConfigurableID () const
	returns the configurables static ID
void	deactivateProperty (const std::string &pattern)
	adds an additional deativation pattern
void	deleteDeactivationPattern (const std::string &pattern)
	removed a formerly added deactivation pattern
std::vector< std::string >	getPropertyListWithoutDeactivated () const
	this returns a filtered list of properties (using all filters added by deactivateProperty)
virtual void	adaptProperty (const std::string &name, const std::string &newType, const std::string &newInfo, const std::string &newToolTip) throw (ICLException)
	this function can be used to adapt a specific property afterwards
void	registerCallback (const Callback &cb)
	add a callback for changed properties
void	removedCallback (const Callback &cb)
	removes a callback that was registered before
void	syncChangesTo (Configurable *others, int num=1)
	this can be used to let this instance also apply property changes to others
virtual void	setPropertyValue (const std::string &propertyName, const Any &value) throw (ICLException)
	sets a property value
virtual std::vector< std::string >	getPropertyList () const
	returns a list of All properties, that can be set using setProperty
virtual bool	supportsProperty (const std::string &propertyName) const
	base implementation for property check (seaches in the property list)
virtual void	saveProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC) const
	writes all available properties into a file
virtual void	loadProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC)
	reads a camera config file from disc
virtual std::string	getPropertyType (const std::string &propertyName) const
	get type of property
virtual std::string	getPropertyInfo (const std::string &propertyName) const
	get information of a properties valid values
virtual Any	getPropertyValue (const std::string &propertyName) const
	returns the current value of a property or a parameter
virtual std::string	getPropertyToolTip (const std::string &propertyName) const
	returns the tooltip description for a given property
virtual int	getPropertyVolatileness (const std::string &propertyName) const
	Returns whether this property may be changed internally.
Static Public Member Functions
static std::string	create_default_ID (const std::string &prefix)
	this function can be used in subclasses to create a default ID
static Configurable *	get (const std::string &id)
	returns configurable by given ID
static void	register_configurable_type (const std::string &classname, Function< Configurable * > creator) throw (ICLException)
	registers a configurable type
static std::vector< std::string >	get_registered_configurables ()
	returns a list of all registered configurable classnames
static Configurable *	create_configurable (const std::string &classname) throw (ICLException)
	creates a configurable by given name
Static Public Attributes
static const std::vector < std::string >	EMPTY_VEC
	used as shortcut -- just an empty vector of std::strings
Protected Member Functions
void	addProperty (const std::string &name, const std::string &type, const std::string &info, const Any &value=Any(), const int volatileness=0, const std::string &tooltip=std::string()) throw (ICLException)
	This can be used by derived classes to store supported properties in the internal list.
void	addChildConfigurable (Configurable *configurable, const std::string &childPrefix="")
	This adds another configurable as child.
Property &	prop (const std::string &propertyName) throw (ICLException)
	this CAN be used e.g. to store a property value in internal property-list
const Property &	prop (const std::string &propertyName) const throw (ICLException)
	this CAN be used e.g. to store a property value in internal property-list
	Configurable (const std::string &ID="") throw (ICLException)
	create this configurable with given ID
void	call_callbacks (const std::string &propertyName) const
	calls all registered callbacks
Protected Attributes
std::vector< Callback >	callbacks
	internally managed list of callbacks
Private Types
typedef std::map< std::string, Property >	PropertyMap
	by default internally use property list
Private Attributes
PropertyMap	m_properties
	list of all properties
std::vector< Configurable * >	m_childConfigurables
	internal list of child configurables
Configurable *	m_elderConfigurable
	internal pointer to elder configurable
std::string	m_ID
	internal ID, that is used to provide global access to all instantiated configurables at runtime by given ID;
std::vector< std::string >	m_deactivated
	list of patterns for deactiavted properties
UncopiedInstance< Mutex >	m_mutex
	locks all accesses to property values
Static Private Attributes
static std::map< std::string, Configurable * >	m_instances
	static list of all instantiated Configurables

Detailed Description

Interface for classes that can be configured from configuration-files and GUI-Components.

The Configurable-interface can be used to define a classes parameters/properties that shall be changed at runtime. The Configurable-subclasses can define properties that can be accessed by string identifiers. Each property has a type, a type-dependend description of possible values, a current value and a so called volatileness. Please see class interface and it's function descriptions for more details. A list of supported property types is provided in the documentation of the method icl::Configurable::getPropertyType

Implementing the Configurable Interface

It is strongly recommended to use the Configurable's property storage mechanism to manage a classes properties. Special behaviour to the adaption of certain properties can easily be added by registering a callback to an own member function. Alternatively, all Configurable's virtual methods can be reimplemented to obtain special behaviour. In this case the programmer himself can provide storage for the classes properties, but this is -- as said above -- not recommended due to the complex interface.

Child Configurables

Configurables can not only have a list of properties that can be got and set, but also a list of chlidren. All child-properties will also become properties of it's parent. However, the first section prefix (which is used for the property-tab's label) can be adapted. Note that this behaviour must be preserved if the virtual functions setPropertyValue and getPropertyValue are reimplemented. Usually, you can simply call Configurable::[set/get]PropertyValue(...) at the end of you versions of these methods.

Configurable Registration

Configurable class should be registered statically using one of the two registration macros REGISTER_CONFIGURABLE or REGISTER_CONFIGURABLE_DEFAULT. This is strongly recommended since the class interface of a configurable class does not give information about the properties that are provided by a specific Configurable class. Instead, all classes, that implement the Configurable interface, can be registered statically, which allows for runtime exploration of possible Configurable classes and their supported properties.

The example application icl-configurable-info can be used to explore allowed properties.

In order to make the static registration process as easy as possible, special macros are provided. Example:

        namespace icl{
          // MyConfigurable.h
          struct MyConfigurable{
             MyConfigurable();
             void foo(){}
             ...
          };
        }
  
        // MyConfigurable.cpp
        namespace icl{
          MyConfigurable::MyConfigurable(){
            addProperty(....);
          }
          void MyConfigurable::foo() {...}
        
          // registration at the end of the .cpp file 
          // within the icl-namespace
          REGISTER_CONFIGURABLE_DEFAULT(MyConfigurable);
        }

If no default constructor is available, the macro REGISTER_CONFIGURABLE can be used. Here, you can also specify how an instance of that class is created. Example:

        namespace icl{
          // MyComplexConfigurable.h
          struct MyComplexConfigurable{
             // no default constructor
             MyComplexConfigurable(int i, float j);
             void foo(){}
             ...
          };
        }
  
        // MyComplexConfigurable.cpp
        namespace icl{
          MyComplexConfigurable::MyComplexConfigurable(int i, float j){
            addProperty(....);
          }
          void MyComplexConfigurable::foo() {...}
        
          // provide default arguments here
          REGISTER_CONFIGURABLE(MyComplexConfigurable, return new MyComplexConfigurable(1,4.5));
        }

For classes with pure-virtual methods, it is recommended to provide a dummy non-virtual extension of that class whose name is extended by a _VIRTUAL postfix. In this case, listing the Configurable classnames shows explicitly, that a class is a virtual interface. Example:

        namespace icl{
          // MyVirtualConfigurable.h
          struct MyVirtualConfigurable{
             MyVirtualConfigurable();
             // pure virtual method
             virtual void foo(int bar) = 0;
             ...
          };
        }
  
        // MyVirtualConfigurable.cpp
        namespace icl{
          MyVirtualConfigurable::MyVirtualConfigurable(){
            addProperty(....);
          }
          
          struct MyVirtualConfigurable_VIRTUAL : public MyVirtualConfigurable{
            virtual void foo(int){}
          };
  
          // register the dummy implementation
          REGISTER_CONFIGURABLE_DEFAULT(MyVirtualConfigurable_VIRTUAL);
        }

Example

There are several examples available in the ICL-source try. Use the ICL-tool icl-configurable-info -list to obtain a list of all Configurable implementations and their supported properties.

Member Typedef Documentation

typedef Function<void,const Property&> icl::utils::Configurable::Callback

Function type for changed properties.

typedef std::map<std::string,Property> icl::utils::Configurable::PropertyMap [private]

by default internally use property list

Constructor & Destructor Documentation

icl::utils::Configurable::Configurable ( const std::string & ID = "" ) throw (ICLException) [protected]

create this configurable with given ID

all instantiated configurables are globally accessible by static getter functions If given ID is "", then this configurable is not added to the static list. Configurables can later be put into the static list by using setConfigurableID

icl::utils::Configurable::~Configurable ( ) [inline]

virtual destructor

icl::utils::Configurable::Configurable ( const Configurable & other )

Copy constructor.

the configurable ID is not copied. Use setConfigurableID afterwards

Member Function Documentation

virtual void icl::utils::Configurable::adaptProperty	(	const std::string &	name,
		const std::string &	newType,
		const std::string &	newInfo,
		const std::string &	newToolTip
	)		throw (ICLException) `[virtual]`

this function can be used to adapt a specific property afterwards

Please note: The newly given type and info value must of cause be compatible with the current property type. The type of a property cannot be changed. Please note also, that this Function also needs to be reimplemented if getPropertyInfo or getPropertyType was reimplemented. A range property can e.g. be adapted to a menu property, which then again restricts possible values. You can also set a properties type from range:spinbox to range:slider

void icl::utils::Configurable::addChildConfigurable	(	Configurable *	configurable,
		const std::string &	childPrefix = `""`
	)		`[protected]`

This adds another configurable as child.

Child configurables can be added with a given prefix. If this prefix is not "", the childs properties will get an own tab in the configurables GUI. Note: if the prefix is not "", it should end with a '.' character. If not, an additional '.' is added automatically in order to move all properties into a dedicated tab

void icl::utils::Configurable::addProperty	(	const std::string &	name,
		const std::string &	type,
		const std::string &	info,
		const Any &	value = `Any()`,
		const int	volatileness = `0`,
		const std::string &	tooltip = `std::string()`
	)		throw (ICLException) `[protected]`

This can be used by derived classes to store supported properties in the internal list.

Throws an exception if the property name is already defined. Note: properties names can structured using '.'-delimiters. e.g. properties like general.threshold,general.mean,filer.mask-size. This is then later translated into a structured configuratable GUI.

void icl::utils::Configurable::call_callbacks ( const std::string & propertyName ) const [protected]

calls all registered callbacks

static Configurable* icl::utils::Configurable::create_configurable ( const std::string & classname ) throw (ICLException) [static]

creates a configurable by given name

See also:: Configurable Registration

static std::string icl::utils::Configurable::create_default_ID ( const std::string & prefix ) [static]

this function can be used in subclasses to create a default ID

The ID will be the first not used prefixNUMBER where number is an integer value 0,1,...

void icl::utils::Configurable::deactivateProperty ( const std::string & pattern )

adds an additional deativation pattern

By this means, extended or also accumulating Configurable-instances can hide some of their inherited/accumulated properties. E.g. special ICLFilter::UnaryOp instances can hide the UnaryOp-properties 'Clip To ROI' and 'Check Only' if it is not appropriate to adapt these. The given pattern can be an abitrary regular expression which compared icl::match(const std::string&, const std::string&,int); E.g. to deactivate all UnaryOp-properties, you can add the filter reg-ex '^UnaryOp' more precisesly, you could also add the filter-reg-ex '^UnaryOp\..*' which ensures that a '.' and some other characters follow the 'UnaryOp' string. Commonly the '^Foo' can be used to remove all properties with given prefix 'Foo'.

void icl::utils::Configurable::deleteDeactivationPattern ( const std::string & pattern )

removed a formerly added deactivation pattern

Please note, that usually this should not be used because there is most probably a reason why a property was deactivated before.

static Configurable* icl::utils::Configurable::get ( const std::string & id ) [static]

returns configurable by given ID

returns instantiated Configurable by given ID or NULL, if the ID was not found

static std::vector<std::string> icl::utils::Configurable::get_registered_configurables ( ) [static]

returns a list of all registered configurable classnames

See also:: Configurable Registration

const std::string& icl::utils::Configurable::getConfigurableID ( ) const [inline]

returns the configurables static ID

virtual std::string icl::utils::Configurable::getPropertyInfo ( const std::string & propertyName ) const [inline, virtual]

get information of a properties valid values

This is the second function of the minimal configuration interface: If received a specific property type with getType(), it's possible to get the corresponding range, value-list or menu with this funcitons. The Syntax of the returned strings are:

"[A,B]:C" for a range with min=A, max=B and stepping = C or [A,B] with no stepping
"[A,B]" for float- and int-properties with min=A and max=B
",A,B,C,..." for a value-list and A,B,C are ascii doubles (real commas can be escaped using \)
",A,B,C,..." for a menu and A,B,C are strings (real commas can be escaped using \)
nothing for "info"- and "color"-typed properties
MAX_LENGTH for string typed properties
flag-properties always have the possible values "on|1|true" or "off|0|false" Note: The received string can be translated into C++ data with some static utility function in this Grabber class.

Reimplemented in icl::cv::CornerDetectorCSS.

virtual std::vector<std::string> icl::utils::Configurable::getPropertyList ( ) const [virtual]

returns a list of All properties, that can be set using setProperty

This function should usually not be used. Instead, you should call getPropertyListWithoutDeactivated

Returns:: list of supported property names

Reimplemented in icl::cv::CornerDetectorCSS.

std::vector<std::string> icl::utils::Configurable::getPropertyListWithoutDeactivated ( ) const

this returns a filtered list of properties (using all filters added by deactivateProperty)

virtual std::string icl::utils::Configurable::getPropertyToolTip ( const std::string & propertyName ) const [inline, virtual]

returns the tooltip description for a given property

Reimplemented in icl::cv::CornerDetectorCSS.

virtual std::string icl::utils::Configurable::getPropertyType ( const std::string & propertyName ) const [inline, virtual]

get type of property

This is a new minimal configuration interface: When implementing generic video device configuration utilities, the programmer needs information about the properties received by getPropertyList(). With the getType(const string&) function, you can explore all possible params and properties, and receive a type string which defines of which type the given property was:
(for detailed description of the types, see also the get Info function) Types are:

"range" this is the same as "range:slider" (see below)
"range:slider" the property is a double value in a given range
"range:spinbox" the property is an int-value in given range with stepping 1
"value-list" the property is a double value in a list of possible values
"menu" the property is a string value in a list of possible values
"flag" the property is a boolean flag that can be set to "on" and "off"
"command" property param has no additional parameters (this feature is
"float" the property value can be any valid float value within a given range
"int" the property value can be any valid int value within a given range
"string" the property is a string value with a given maximum length
"color" the property has RGBA values in range 0-255 used e.g. for triggered abilities of grabbing devices, like "save user settings" for the PWCGrabber
"info" the property is an unchangable internal value (it cannot be set actively)
... (propably some other types are defined later on)

Reimplemented in icl::cv::CornerDetectorCSS.

virtual Any icl::utils::Configurable::getPropertyValue ( const std::string & propertyName ) const [virtual]

returns the current value of a property or a parameter

If the property is actually owned by a child-configurable, the function forwards to that configurable

Reimplemented in icl::cv::CornerDetectorCSS.

virtual int icl::utils::Configurable::getPropertyVolatileness ( const std::string & propertyName ) const [inline, virtual]

Returns whether this property may be changed internally.

For example a video grabber's current stream position. This can be changed from outside, but it is changed when the stream is played. The isVolatile function should return a msec-value that describes how often the corresponding feature might be updated internally or just 0, if the corresponding feature is not volatile at all. The default implementation of isVolatile returns 0 for all features. So if there is no such feature in your grabber, this function must not be adapted at all. "info"-typed Properties might be volatile as well

Reimplemented in icl::cv::CornerDetectorCSS.

virtual void icl::utils::Configurable::loadProperties	(	const std::string &	filename,
		const std::vector< std::string > &	propertiesToSkip = `EMPTY_VEC`
	)		`[virtual]`

reads a camera config file from disc

@ see saveProperties

Configurable& icl::utils::Configurable::operator= ( const Configurable & other )

Assignment operator.

the configurable ID is not copied. Use setConfigurableID afterwards

Property& icl::utils::Configurable::prop ( const std::string & propertyName ) throw (ICLException) [protected]

this CAN be used e.g. to store a property value in internal property-list

Throws an exception if the given propertyName is not supported

const Property& icl::utils::Configurable::prop ( const std::string & propertyName ) const throw (ICLException) [protected]

this CAN be used e.g. to store a property value in internal property-list

Throws an exception if the given propertyName is not supported

static void icl::utils::Configurable::register_configurable_type	(	const std::string &	classname,
		Function< Configurable * >	creator
	)		throw (ICLException) `[static]`

registers a configurable type

See also:: Configurable Registration

void icl::utils::Configurable::registerCallback ( const Callback & cb ) [inline]

add a callback for changed properties

void icl::utils::Configurable::removedCallback ( const Callback & cb )

removes a callback that was registered before

virtual void icl::utils::Configurable::saveProperties	(	const std::string &	filename,
		const std::vector< std::string > &	propertiesToSkip = `EMPTY_VEC`
	)		const `[virtual]`

writes all available properties into a file

Parameters:

filename	destination xml-filename
propertiesToSkip	some common grabber parameters e.g. trigger-settings cause problems when they are read from configuration files, hence these parameters are skipped at default

void icl::utils::Configurable::setConfigurableID ( const std::string & ID ) throw (ICLException)

sets the ID of this configurable

The ID is used for accessing the configurable globally

virtual void icl::utils::Configurable::setPropertyValue	(	const std::string &	propertyName,
		const Any &	value
	)		throw (ICLException) `[virtual]`

sets a property value

If this method is specialized in subclasses, the parent method shold be called at the end in order to call all registered callbacks. If the property is actually owned by a child-configurable, the function forwards to that configurable

Reimplemented in icl::cv::CornerDetectorCSS, and icl::filter::UnaryOp.

virtual bool icl::utils::Configurable::supportsProperty ( const std::string & propertyName ) const [virtual]

base implementation for property check (seaches in the property list)

This function may be reimplemented in an optimized way in particular subclasses.