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

Public Member Functions
virtual	~Configurable ()
	virtual destructor More...

	Configurable (const Configurable &other)
	Copy constructor. More...

Configurable &	operator= (const Configurable &other)
	Assignment operator. More...

void	setConfigurableID (const std::string &ID)
	sets the ID of this configurable More...

const std::string &	getConfigurableID () const
	returns the configurables static ID More...

bool	isOrderedFlagSet () const
	returns whether the ordered flag is set More...

void	deactivateProperty (const std::string &pattern)
	adds an additional deativation pattern More...

void	deleteDeactivationPattern (const std::string &pattern)
	removed a formerly added deactivation pattern More...

std::vector< std::string >	getPropertyListWithoutDeactivated () const
	this returns a filtered list of properties (using all filters added by deactivateProperty) More...

virtual void	adaptProperty (const std::string &name, const std::string &newType, const std::string &newInfo, const std::string &newToolTip)
	this function can be used to adapt a specific property afterwards More...

void	registerCallback (const Callback &cb)
	add a callback for changed properties More...

void	removedCallback (const Callback &cb)
	removes a callback that was registered before More...

void	syncChangesTo (Configurable *others, int num=1)
	this can be used to let this instance also apply property changes to others More...

virtual void	setPropertyValue (const std::string &propertyName, const Any &value)
	sets a property value More...

virtual std::vector< std::string >	getPropertyList () const
	returns a list of All properties, that can be set using setProperty More...

virtual bool	supportsProperty (const std::string &propertyName) const
	base implementation for property check (seaches in the property list) More...

virtual void	saveProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC) const
	writes all available properties into a file More...

virtual void	loadProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC)
	reads a camera config file from disc More...

virtual std::string	getPropertyType (const std::string &propertyName) const
	get type of property More...

virtual std::string	getPropertyInfo (const std::string &propertyName) const
	get information of a properties valid values More...

virtual Any	getPropertyValue (const std::string &propertyName) const
	returns the current value of a property or a parameter More...

virtual std::string	getPropertyToolTip (const std::string &propertyName) const
	returns the tooltip description for a given property More...

virtual int	getPropertyVolatileness (const std::string &propertyName) const
	Returns whether this property may be changed internally. More...

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

static Configurable *	get (const std::string &id)
	returns configurable by given ID More...

static void	register_configurable_type (const std::string &classname, Function< Configurable * > creator)
	registers a configurable type More...

static std::vector< std::string >	get_registered_configurables ()
	returns a list of all registered configurable classnames More...

static Configurable *	create_configurable (const std::string &classname)
	creates a configurable by given name More...

Static Public Attributes
static const std::vector< std::string >	EMPTY_VEC
	used as shortcut – just an empty vector of std::strings More...

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())
	This can be used by derived classes to store supported properties in the internal list. More...

void	addChildConfigurable (Configurable *configurable, const std::string &childPrefix="")
	This adds another configurable as child. More...

void	removeChildConfigurable (Configurable *configurable)
	removes the given child configurable More...

Property &	prop (const std::string &propertyName)
	this CAN be used e.g. to store a property value in internal property-list More...

const Property &	prop (const std::string &propertyName) const
	this CAN be used e.g. to store a property value in internal property-list More...

	Configurable (const std::string &ID="", bool ordered=true)
	create this configurable with given ID More...

void	call_callbacks (const std::string &propertyName, const Configurable *caller) const
	calls all registered callbacks More...

Protected Attributes
std::vector< Callback >	callbacks
	internally managed list of callbacks More...

Private Types
typedef std::map< std::string, Property >	PropertyMap
	by default internally use property list More...

Private Attributes
PropertyMap	m_properties
	list of all properties More...

bool	m_isOrdered
	whether to use property ordering More...

std::map< int, std::string >	m_ordering
	ordering of the properties More...

std::map< const Configurable *, std::string >	m_childConfigurables
	internal list of child configurables More...

Configurable *	m_elderConfigurable
	internal pointer to elder configurable More...

std::string	m_ID
	internal ID, that is used to provide global access to all instantiated configurables at runtime by given ID; More...

std::vector< std::string >	m_deactivated
	list of patterns for deactiavted properties More...

UncopiedInstance< Mutex >	m_mutex
	locks all accesses to property values More...

Static Private Attributes
static std::map< std::string, Configurable * >	m_instances
	static list of all instantiated Configurables More...

Friends
class	ConfigurableProxy

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 (Image Convolution)

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

◆ Callback

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

Function type for changed properties.

◆ PropertyMap

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

private

by default internally use property list

Constructor & Destructor Documentation

◆ Configurable() [1/2]

icl::utils::Configurable::Configurable	(	const std::string &	ID = `""`,
		bool	ordered = `true`
	)

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

◆ ~Configurable()

virtual icl::utils::Configurable::~Configurable ( )

inlinevirtual

virtual destructor

◆ Configurable() [2/2]

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

Copy constructor.

the configurable ID is not copied. Use setConfigurableID afterwards

Member Function Documentation

◆ adaptProperty()

virtual void icl::utils::Configurable::adaptProperty	(	const std::string &	name,
		const std::string &	newType,
		const std::string &	newInfo,
		const std::string &	newToolTip
	)

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

◆ addChildConfigurable()

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

◆ addProperty()

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()`
	)

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.

◆ call_callbacks()

void icl::utils::Configurable::call_callbacks	(	const std::string &	propertyName,
		const Configurable *	caller
	)		const

protected

calls all registered callbacks

Parameters

propertyName	the name of the property to check
caller	the instance calling the function

◆ create_configurable()

static Configurable* icl::utils::Configurable::create_configurable ( const std::string & classname )

static

creates a configurable by given name

See also: Configurable Registration

◆ create_default_ID()

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

◆ deactivateProperty()

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

◆ deleteDeactivationPattern()

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.

◆ get()

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

◆ get_registered_configurables()

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

static

returns a list of all registered configurable classnames

See also: Configurable Registration

◆ getConfigurableID()

const std::string& icl::utils::Configurable::getConfigurableID ( ) const

inline

returns the configurables static ID

◆ getPropertyInfo()

virtual std::string icl::utils::Configurable::getPropertyInfo ( const std::string & propertyName ) const

inlinevirtual

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.

◆ getPropertyList()

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.

◆ getPropertyListWithoutDeactivated()

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

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

◆ getPropertyToolTip()

virtual std::string icl::utils::Configurable::getPropertyToolTip ( const std::string & propertyName ) const

inlinevirtual

returns the tooltip description for a given property

Reimplemented in icl::cv::CornerDetectorCSS.

◆ getPropertyType()

virtual std::string icl::utils::Configurable::getPropertyType ( const std::string & propertyName ) const

inlinevirtual

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.

◆ getPropertyValue()

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.

◆ getPropertyVolatileness()

virtual int icl::utils::Configurable::getPropertyVolatileness ( const std::string & propertyName ) const

inlinevirtual

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.

◆ isOrderedFlagSet()

bool icl::utils::Configurable::isOrderedFlagSet ( ) const

inline

returns whether the ordered flag is set

◆ loadProperties()

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

◆ operator=()

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

Assignment operator.

the configurable ID is not copied. Use setConfigurableID afterwards

◆ prop() [1/2]

Property& icl::utils::Configurable::prop ( const std::string & propertyName )

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

◆ prop() [2/2]

const Property& icl::utils::Configurable::prop ( const std::string & propertyName ) const

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

◆ register_configurable_type()

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

static

registers a configurable type

See also: Configurable Registration

◆ registerCallback()

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

inline

add a callback for changed properties

◆ removeChildConfigurable()

void icl::utils::Configurable::removeChildConfigurable ( Configurable * configurable )

protected

removes the given child configurable

◆ removedCallback()

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

removes a callback that was registered before

◆ saveProperties()

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

◆ setConfigurableID()

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

sets the ID of this configurable

The ID is used for accessing the configurable globally

◆ setPropertyValue()

virtual void icl::utils::Configurable::setPropertyValue	(	const std::string &	propertyName,
		const Any &	value
	)

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::filter::UnaryOp, and icl::cv::CornerDetectorCSS.

◆ supportsProperty()

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.

◆ syncChangesTo()

void icl::utils::Configurable::syncChangesTo	(	Configurable *	others,
		int	num = `1`
	)

this can be used to let this instance also apply property changes to others

Please take care to not create cyclic dependency graphs

Friends And Related Function Documentation

◆ ConfigurableProxy

friend class ConfigurableProxy

friend

Member Data Documentation

◆ callbacks

std::vector<Callback> icl::utils::Configurable::callbacks

protected

internally managed list of callbacks

◆ EMPTY_VEC

const std::vector<std::string> icl::utils::Configurable::EMPTY_VEC

static

used as shortcut – just an empty vector of std::strings

◆ m_childConfigurables

std::map<const Configurable*, std::string> icl::utils::Configurable::m_childConfigurables

private

internal list of child configurables

◆ m_deactivated

std::vector<std::string> icl::utils::Configurable::m_deactivated

private

list of patterns for deactiavted properties

◆ m_elderConfigurable

Configurable* icl::utils::Configurable::m_elderConfigurable

private

internal pointer to elder configurable

◆ m_ID

std::string icl::utils::Configurable::m_ID

private

internal ID, that is used to provide global access to all instantiated configurables at runtime by given ID;

◆ m_instances

std::map<std::string,Configurable*> icl::utils::Configurable::m_instances

staticprivate

static list of all instantiated Configurables

◆ m_isOrdered

bool icl::utils::Configurable::m_isOrdered

private

whether to use property ordering

◆ m_mutex

UncopiedInstance<Mutex> icl::utils::Configurable::m_mutex

mutableprivate

locks all accesses to property values

adding and adapting properties is not thread safe!

◆ m_ordering

std::map<int,std::string> icl::utils::Configurable::m_ordering

private

ordering of the properties

◆ m_properties

PropertyMap icl::utils::Configurable::m_properties

private

list of all properties

The documentation for this class was generated from the following file:

/Users/alneuman/vm/icl/ICLUtils/src/ICLUtils/Configurable.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Types

Private Attributes

Static Private Attributes

Friends

Detailed Description

Implementing the Configurable Interface

Child Configurables

Configurable Registration

Example (Image Convolution)

Member Typedef Documentation

◆ Callback

◆ PropertyMap

Constructor & Destructor Documentation

◆ Configurable() [1/2]

◆ ~Configurable()

◆ Configurable() [2/2]

Member Function Documentation

◆ adaptProperty()

◆ addChildConfigurable()

◆ addProperty()

◆ call_callbacks()

◆ create_configurable()

◆ create_default_ID()

◆ deactivateProperty()

◆ deleteDeactivationPattern()

◆ get()

◆ get_registered_configurables()

◆ getConfigurableID()

◆ getPropertyInfo()

◆ getPropertyList()

◆ getPropertyListWithoutDeactivated()

◆ getPropertyToolTip()

◆ getPropertyType()

◆ getPropertyValue()

◆ getPropertyVolatileness()

◆ isOrderedFlagSet()

◆ loadProperties()

◆ operator=()

◆ prop() [1/2]

◆ prop() [2/2]

◆ register_configurable_type()

◆ registerCallback()

◆ removeChildConfigurable()

◆ removedCallback()

◆ saveProperties()

◆ setConfigurableID()

◆ setPropertyValue()

◆ supportsProperty()

◆ syncChangesTo()

Friends And Related Function Documentation

◆ ConfigurableProxy

Member Data Documentation

◆ callbacks

◆ EMPTY_VEC

◆ m_childConfigurables

◆ m_deactivated

◆ m_elderConfigurable

◆ m_ID

◆ m_instances

◆ m_isOrdered

◆ m_mutex

◆ m_ordering

◆ m_properties