#include <ImFusion/Core/Properties.h>

Storage container for serialization of arbitrary types, internally backed by strings. More...

Detailed Description

Storage container for serialization of arbitrary types, internally backed by strings.

Properties storage is hierarchical in the sense that a Properties instance can have any number of nested subproperties. Parameters of subproperties can be set and retrieved by a path, for example param("Views/window", val) will retrieve the value for window in the subproperties Views. The same works with setParam(), which will always create all subproperties on the way. The path separator is always /, which must not be used in the naming of parameters or subproperties.

The following types are supported for parameter serialization:

most fundamental types except void and long double
std::string and const char*
Filesystem::Path and Filesystem::Url
Most Eigen typedefs in Mat.h (vecX, vecXf, vecXi, matX, matXf in sizes 2-6)
std::vector containers of the previous types
std::optional containers of the previous types (including std::vector)
std::set and std::unordered_set of fundamental types and string types

If you want to store a custom type in Properties make it implement the Configurable interface, implement the pair of configure()/configuration() functions and then serialize the type into a subproperty.

Note: Since parameter serialization is implemented through explicit template specialization on the library side, using an unsupported type will yield a linker error instead of a compiler error.

See also: Object Serialization, Configurable

Examples: DicomExtensionExample.cpp, DicomExtensionExample3.cpp, ExampleAlgorithm.cpp, ExampleAlgorithm.h, Serialization.cpp, SqrtAlgorithm.cpp, and SqrtAlgorithm.h.

Public Types
enum class	Comparison { ValuesOnly = 0 , Order = 1 << 0 , Defaults = 1 << 1 , Types = 1 << 2 , Attributes = 1 << 3 , SubProperties = 1 << 4 , All = 0xFF }
	Bitflag enumeration to define which aspects to consider during comparison of two Properties objects. More...

enum class	CopyOptions { Default = 0 , ReplaceSubProperties = 1 << 0 , KeepType = 1 << 1 , KeepAttributes = 1 << 2 , ExistingParamsOnly = 1 << 3 }
	Bitflag enumeration to configure behavior of copyFrom(). More...

using	ParamType = PropertiesDetail::ParamType

using	Attribute = PropertiesDetail::Attribute

using	Param = PropertiesDetail::Param

using	StringAccepter = PropertiesDetail::StringAccepter

Public Member Functions
	Properties (const std::string &name)
	Instantiates a new empty Properties instance.

	Properties (std::initializer_list< std::pair< std::string, StringAccepter > > list)
	Convenience constructor enabling you to set parameters directly using an initializer list.

	Properties (const Properties &p)

	Properties (Properties &&rhs) noexcept

Properties &	operator= (const Properties &rhs)

Properties &	operator= (Properties &&rhs) noexcept

const std::string &	name () const
	Return the name of the property.

void	setName (const std::string &name)
	Set the name of the property.

bool	contains (const std::string &name) const
	Return whether the param with the given name is part of the properties or not.

bool	isEmpty () const
	Return true if there are neither parameters nor sub-properties.

void	clearParamsOnly ()
	Clear all parameters.

void	clear ()
	Clear all parameters and sub properties.

void	removeParam (const std::string &name)
	Remove a single parameter.

void	removeDefault (const std::string &name)
	Remove the default for a single parameter.

void	removeDefaultParams ()
	Remove all parameters which current value is their default value.

void	renameParam (const std::string &oldName, const std::string &newName)
	Rename a parameter.

void	setToDefaultParams ()
	Set all parameters that have a default value to the default value.

Setting parameters
template<class T, PROHIBIT_ENUM(T)>
void	setParam (const std::string &name, const T &value, const T &defaultValue)
	Set a parameter with arbitrary type and a default value.

template<class T, REQUIRE_ENUM(T)>
void	setParam (const std::string &name, const T &value, const T &defaultValue)
	Set a parameter with arbitrary enum type and a default value. Internally uses int.

template<class T, PROHIBIT_ENUM(T)>
void	setParam (const std::string &name, const T &value)
	Set a parameter with arbitrary type without default value.

template<class T, REQUIRE_ENUM(T)>
void	setParam (const std::string &name, const T &value)
	Set a parameter with arbitrary enum type and a default value. Internally uses int.

void	setParam (const std::string &name, const char value, const char defaultValue)
	Set a parameter as C string with default value.

void	setParam (const std::string &name, const std::string &value, const char *defaultValue)
	Set a parameter only the defaultValue given as C string.

void	setParam (const std::string &name, const char *value)
	Set a parameter as C string.

void	setParam (const std::string &name, const std::string &value, const std::optional< std::string > &defaultValue, ParamType type)
	Set a parameter as string, specifying the type, passing std::nullopt as defaultValue resets the default.

template<class ForwardIterator>
void	setParamRange (const std::string &name, ForwardIterator first, ForwardIterator last)
	Set a parameter to a sequence of elements.

Querying parameters
template<class T, PROHIBIT_ENUM(T)>
bool	param (const std::string &name, T &value) const
	Return the value of a parameter of arbitrary types.

template<class T, REQUIRE_ENUM(T)>
bool	param (const std::string &name, T &value) const
	Return the value of a parameter, enum version. internally uses int for representing enums.

template<class T>
std::optional< T >	param (const std::string &name) const
	Return the value of a parameter of arbitrary types.

template<class ForwardIterator>
bool	paramRange (const std::string &name, ForwardIterator first, ForwardIterator last) const
	Return sequence of values from a parameter into an iterator.

const std::map< std::string, Param > &	paramMap () const
	Return the map with name-value pairs for all parameters.

const std::vector< std::string > &	params () const
	Return all parameters in the order as they were inserted.

std::vector< std::string >	paramsRecursive () const
	Recursively return all parameter names and those of the sub-properties.

Configure global and per-parameter attributes, used for instance by default-generated GUI
ParamType	paramType (const std::string &name) const
	Return the type of a parameter.

void	setParamType (const std::string &name, ParamType type)
	Overrides the ParamType set by setParam.

void	setAttributes (const std::vector< Attribute > &attributes)
	Set global attributes for this Properties instance.

const std::vector< Attribute > &	attributes () const
	Return the list of global attributes assigned to this Properties.

std::optional< std::string >	attribute (const std::string &key) const
	Return the value of a global attribute if it exists.

bool	setParamAttributes (const std::string &name, const std::vector< Attribute > &attributes)
	Set special attributes to a single parameter.

bool	setParamAttributes (const std::string &name, const std::string &attributes)
	Set special attributes to a single parameter.

std::vector< Attribute >	paramAttributes (const std::string &name) const
	Returns a list of attributes for the parameters type.

std::optional< std::string >	paramAttribute (const std::string &name, const std::string &key) const
	Return the value of a parameter attribute if it exists.

void	setParamSchema (const std::string &name, ParamType type, const std::vector< Attribute > &attributes, const std::optional< std::string > &defaultValue)
	Convenience function to set parameter type, attributes, and default value at once.

Dealing with sub-properties
Properties *	addSubProperties (const std::string &name)
	Add sub-properties with specified name and return the created instance.

void	addSubProperties (std::unique_ptr< Properties > p)
	Add the provided properties instance.

void	insertSubProperties (std::unique_ptr< Properties > p, int location)
	Insert the provided properties instance at a given location.

const Properties *	subProperties (const std::string &name) const
	Return (first) sub-properties instance with the specified name.

Properties *	subProperties (const std::string &name, bool createIfDoesntExist=false)
	Return (first) sub-properties instance with the specified name and optionally creates one if it doesn't exist.

PropertyList	subPropertiesAll (const std::string &name) const
	Return all properties instances with the given name in the correct order.

PropertyList	subProperties () const
	Return a list of all sub-properties.

const std::map< std::string, PropertyList > &	propertyMap () const
	Return the map with for all sub-properties group by their name.

void	deleteSubProperty (Properties *p)
	Delete a sub property.

bool	removeSubProperties (const std::string &name)
	Remove (all) sub-properties with the specified name.

bool	removeEmptySubProperties ()
	Recursively removes all empty sub properties.

Utility functions
int	fillPlaceHolders (const std::map< std::string, std::string > &placeholders)
	Replace all occurrences of placeholders of the form `%(key)`.

std::vector< std::string >	getPlaceHolders () const
	Return list of all placeholders of the form `%(key)` in the properties values that have not been replaced yet.

void	iterate (std::function< void(const Properties *properties, const std::string &pathAndName)> visitorFunction) const
	Performs a recursive breadth-first iteration over this instance and all of its sub properties.

void	iterate (std::function< void(Properties *properties, const std::string &pathAndName)> visitorFunction)

bool	compareWith (const Properties &other, Flags< Comparison > compareFlags=Comparison::All) const
	Compares the other Properties instance with this one.

void	copyFrom (const Properties &src, Flags< CopyOptions > copyOptions=CopyOptions::Default, std::function< bool(const std::string &name, const Param &value)> predicate=nullptr)
	Copy properties from another instance You can optionally pass a predicate function, which gets evaluated for every parameter and every sub property.

void	sortParams (const std::function< bool(const std::string &, const std::string &)> &lessThan=std::less< std::string >())
	Sort parameters by name, default is lexicographical.

static bool	compare (const std::optional< Properties > &lhs, const std::optional< Properties > &rhs, Flags< Comparison > compareFlags) noexcept
	Convenience function to compare std::optional<Properties> instances.

Member Enumeration Documentation

◆ Comparison

enum class Comparison

strong

Bitflag enumeration to define which aspects to consider during comparison of two Properties objects.

Enumerator
ValuesOnly	Compare only the param values (will always be compared)
Order	Compare the order of the parameters.
Defaults	Compare the optional default values of the parameters.
Types	Compare the parameter types.
Attributes	Compare the optional parameter attributes.
SubProperties	Recursively compare sub properties.
All	Compare all aspects of the Properties object.

◆ CopyOptions

enum class CopyOptions

strong

Bitflag enumeration to configure behavior of copyFrom().

Enumerator
Default	Overwrite existing parameters but not existing subproperties.
ReplaceSubProperties	Overwrite existing subproperties instead of adding new ones.
KeepType	Keep the original ParamType when overwriting existing parameters.
KeepAttributes	Keep the original attributes when overwriting existing parameters.
ExistingParamsOnly	Only copy parameters that exist in the target. Implies ReplaceSubProperties.

Constructor & Destructor Documentation

◆ Properties()

Properties ( std::initializer_list< std::pair< std::string, StringAccepter > > list )

Convenience constructor enabling you to set parameters directly using an initializer list.

Properties p{{"name", "Frank"},
             {"age", 42},
             {"isResident", true}};

Member Function Documentation

◆ setParam() [1/2]

template<class T, typename std::enable_if_t< std::is_enum_v< T > > *>

void setParam	(	const std::string &	name,
		const T &	value,
		const T &	defaultValue )

Set a parameter with arbitrary type and a default value.

Also works with Eigen types, standard vectors, and vectors of Eigen types.

Examples: ExampleAlgorithm.cpp, Serialization.cpp, and SqrtAlgorithm.cpp.

◆ setParam() [2/2]

template<class T, typename std::enable_if_t< std::is_enum_v< T > > *>

void setParam	(	const std::string &	name,
		const T &	value )

Set a parameter with arbitrary type without default value.

Also works with Eigen types, standard vectors, and vectors of Eigen types.

◆ param() [1/2]

template<class T, typename std::enable_if_t< std::is_enum_v< T > > *>

bool param	(	const std::string &	name,
		T &	value ) const

Return the value of a parameter of arbitrary types.

Also works with Eigen types, standard vectors, vectors of Eigen types, and standard (unordered) sets (of basic types only). Returns true on success, and false on failure (e.g. param not present or not of compatible type).

Examples: ExampleAlgorithm.cpp, Serialization.cpp, and SqrtAlgorithm.cpp.

◆ param() [2/2]

template<class T>

std::optional< T > param ( const std::string & name ) const

Return the value of a parameter of arbitrary types.

Also works with Eigen types, standard vectors, vectors of Eigen types, and standard (unordered) sets (of basic types only). Returns std::nullopt on failure (e.g. param not present or not of compatible type).

◆ paramMap()

const std::map< std::string, Param > & paramMap ( ) const

inline

Return the map with name-value pairs for all parameters.

This offers fast lookup for string value compared to the param() method. Be aware that the order in the map is alphabetically which is not necessarily the actual order of parameters!

◆ paramsRecursive()

std::vector< std::string > paramsRecursive ( ) const

Recursively return all parameter names and those of the sub-properties.

The parameter names of the sub-properties are prefix with the name of the sub-property, e.g. sub/par.

◆ setAttributes()

void setAttributes ( const std::vector< Attribute > & attributes )

Set global attributes for this Properties instance.

Currently supported attributes are:

label (string): Text to use for the label instead of the name when displaying this property as sub property.
collapsible (bool): Flag whether to show this sub property in a collapsible group box.
hidden (bool): If set the PropertiesWidget will not show controls for this sub property.
tight (bool): If set, the PropertiesWidget will not show left/right margins for this sub property.

◆ setParamAttributes() [1/2]

bool setParamAttributes	(	const std::string &	name,
		const std::vector< Attribute > &	attributes )

Set special attributes to a single parameter.

The attributes are specified in the form: <attribute>: <value>, <attribute>: <value>. Whitespace in between the elements (e.g. around the :) is automatically trimmed. Attributes must not contain whitespace. The value can be either a number or a string. Strings must be quoted with single quotes (') and are allowed to contain ,.

The supported attributes depend on the type of the parameter. Currently supported attributes are:

General:
- label (string): text to use for the label when displaying this property in a default PropertiesWidget.
- useroption ('r', 'w', or 'rw'): if this is set for a parameter of an IoAlgorithm, the parameter will be displayed in the global settings dialog.
- read-only (bool): if set, the user cannot change the value
- tooltip (string): tooltip that describes the parameter
- hidden (bool): if set, the PropertiesWidget will not show a control for this parameter
Double, Integer:
- min (double or int): minimum allowed value
- max (double or int): maximum allowed value
- step (double or int): step by which the value is increased
- prefix (string): prefix displayed before the value (e.g. a unit)
- suffix (string): suffix displayed after the value (e.g. a unit)
- withSlider (bool): add a slider in the user interface
Double:
- decimals (int): number of decimals displayed. Setting this might alter min/max value (see https://doc.qt.io/qt-5/qdoublespinbox.html#decimals-prop)
Enum, EnumString:
- values (comma separated string, with or without whitespace around comma): String representation of enumerators.
- keys (comma separated string, with or without whitespace around comma): Integer values assigned to enumerators. If not specified, integer values 0,1,2,3,... are assumed.
Path:
- type: specifies the dialog type and must be one of: OpenDirectory, OpenFile or SaveFile. The default is OpenFile.
- caption: sets the title of the dialog (the default is a generic caption depending on the type)
- filter: string of wildcard patterns to filter available files, separated by ;;, e.g.: Text files (*.txt);;XML files (*.xml) (see also QFileDialog)
- dontUseNativeDialog: when set to true use the Qt dialog instead of the native dialog. The default is false.
String:
- textBox (bool): if set, uses a text box instead of a line edit, making it more user-friendly for long or multi-line text. The default is false.
Color:
- type: specifies the dialog type and must be one of: normal, reduced, in-place.

Note: Setting attributes will not change the value or restrict future values of the parameter in any way, e.g. setting a max value for an integer does not automatically clamp values assigned by setParam. Attributes are pure informational and can be used by other object to actually enforce these restrictions (e.g. PropertiesWidget).

// a double value that is restricted between -1 and 1, and increases in steps of 0.1
p.setParamAttributes("someDouble", "min: -1.0, max: 1.0, step: 0.1");
 
// an enum value that can have three values\n
p.setParamAttributes("someEnum", "values: 'value1, value2, value3'");

Returns true if the given string could be parsed or false otherwise.

See also: String::join, PropertiesWidget

◆ setParamAttributes() [2/2]

bool setParamAttributes	(	const std::string &	name,
		const std::string &	attributes )

Set special attributes to a single parameter.

The attributes are specified in the form: <attribute>: <value>, <attribute>: <value>. Whitespace in between the elements (e.g. around the :) is automatically trimmed. Attributes must not contain whitespace. The value can be either a number or a string. Strings must be quoted with single quotes (') and are allowed to contain ,.

The supported attributes depend on the type of the parameter. Currently supported attributes are:

General:
- label (string): text to use for the label when displaying this property in a default PropertiesWidget.
- useroption ('r', 'w', or 'rw'): if this is set for a parameter of an IoAlgorithm, the parameter will be displayed in the global settings dialog.
- read-only (bool): if set, the user cannot change the value
- tooltip (string): tooltip that describes the parameter
- hidden (bool): if set, the PropertiesWidget will not show a control for this parameter
Double, Integer:
- min (double or int): minimum allowed value
- max (double or int): maximum allowed value
- step (double or int): step by which the value is increased
- prefix (string): prefix displayed before the value (e.g. a unit)
- suffix (string): suffix displayed after the value (e.g. a unit)
- withSlider (bool): add a slider in the user interface
Double:
- decimals (int): number of decimals displayed. Setting this might alter min/max value (see https://doc.qt.io/qt-5/qdoublespinbox.html#decimals-prop)
Enum, EnumString:
- values (comma separated string, with or without whitespace around comma): String representation of enumerators.
- keys (comma separated string, with or without whitespace around comma): Integer values assigned to enumerators. If not specified, integer values 0,1,2,3,... are assumed.
Path:
- type: specifies the dialog type and must be one of: OpenDirectory, OpenFile or SaveFile. The default is OpenFile.
- caption: sets the title of the dialog (the default is a generic caption depending on the type)
- filter: string of wildcard patterns to filter available files, separated by ;;, e.g.: Text files (*.txt);;XML files (*.xml) (see also QFileDialog)
- dontUseNativeDialog: when set to true use the Qt dialog instead of the native dialog. The default is false.
String:
- textBox (bool): if set, uses a text box instead of a line edit, making it more user-friendly for long or multi-line text. The default is false.
Color:
- type: specifies the dialog type and must be one of: normal, reduced, in-place.

Note: Setting attributes will not change the value or restrict future values of the parameter in any way, e.g. setting a max value for an integer does not automatically clamp values assigned by setParam. Attributes are pure informational and can be used by other object to actually enforce these restrictions (e.g. PropertiesWidget).

// a double value that is restricted between -1 and 1, and increases in steps of 0.1
p.setParamAttributes("someDouble", "min: -1.0, max: 1.0, step: 0.1");
 
// an enum value that can have three values\n
p.setParamAttributes("someEnum", "values: 'value1, value2, value3'");

Returns true if the given string could be parsed or false otherwise.

See also: String::join, PropertiesWidget

◆ setParamSchema()

void setParamSchema	(	const std::string &	name,
		ParamType	type,
		const std::vector< Attribute > &	attributes,
		const std::optional< std::string > &	defaultValue )

Convenience function to set parameter type, attributes, and default value at once.

This function will not change the param value. Will create the param with empty value if it does not yet exist.

◆ addSubProperties()

Properties * addSubProperties ( const std::string & name )

Add sub-properties with specified name and return the created instance.

If the name is a path, all intermediate sub-properties will be created as well but only the last one is returned. E.g. foo/bar/test would create 3 sub-properties and return a pointer to test.

Examples: Serialization.cpp.

◆ subProperties() [1/2]

const Properties * subProperties ( const std::string & name ) const

Return (first) sub-properties instance with the specified name.

name can also be a path of sub-properties in which case always the first sub-properties on each level is used.

Examples: Serialization.cpp.

◆ subProperties() [2/2]

Properties * subProperties	(	const std::string &	name,
		bool	createIfDoesntExist = false )

Return (first) sub-properties instance with the specified name and optionally creates one if it doesn't exist.

If the name is a path of sub-properties all missing intermediate sub-properties will be created as well.

◆ propertyMap()

const std::map< std::string, PropertyList > & propertyMap ( ) const

inline

Return the map with for all sub-properties group by their name.

Be aware that the order in the map is alphabetically which is not necessarily the actual order of the sub-properties!

◆ removeSubProperties()

bool removeSubProperties ( const std::string & name )

Remove (all) sub-properties with the specified name.

name can also be a path of sub-properties.

Returns: true if any sub-properties were removed

◆ removeEmptySubProperties()

bool removeEmptySubProperties ( )

Recursively removes all empty sub properties.

Returns: true if this Property is empty afterwards.

◆ fillPlaceHolders()

int fillPlaceHolders ( const std::map< std::string, std::string > & placeholders )

Replace all occurrences of placeholders of the form %(key).

The method returns the number of replaced items.

Parameters

placeholders Map of placeholder keys (as returned by getPlaceHolders(), i.e. including parenthesis) and their replacements

◆ iterate()

void iterate ( std::function< void(const Properties *properties, const std::string &pathAndName)> visitorFunction ) const

Performs a recursive breadth-first iteration over this instance and all of its sub properties.

The visitorFunction is called for this and each of the sub properties and receives a pointer to the instance and the absolute path (e.g. SubPropName/SubSubPropName/) to it as arguments.

◆ compareWith()

bool compareWith	(	const Properties &	other,
		Flags< Comparison >	compareFlags = Comparison::All ) const

Compares the other Properties instance with this one.

Only those parts are compared that are listed in compareFlags, which can be useful if defaults/attributes are not configured in one of them.

◆ compare()

static bool compare	(	const std::optional< Properties > &	lhs,
		const std::optional< Properties > &	rhs,
		Flags< Comparison >	compareFlags )

staticnoexcept

Convenience function to compare std::optional<Properties> instances.

Only those parts are compared that are listed in compareFlags, which can be useful if defaults/attributes are not configured in one of them. Returns false if any or both optionals are empty

◆ copyFrom()

void copyFrom	(	const Properties &	src,
		Flags< CopyOptions >	copyOptions = CopyOptions::Default,
		std::function< bool(const std::string &name, const Param &value)>	predicate = nullptr )

Copy properties from another instance You can optionally pass a predicate function, which gets evaluated for every parameter and every sub property.

Only those parts of src are copied for which predicate yields true. The predicate function gets the parameter/sub property name as well as its Param record as arguments.

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

ImFusion/Core/Properties.h

Detailed Description

Public Types

Public Member Functions

Setting parameters

Querying parameters

Configure global and per-parameter attributes, used for instance by default-generated GUI

Dealing with sub-properties

Utility functions

Member Enumeration Documentation

◆ Comparison

◆ CopyOptions

Constructor & Destructor Documentation

◆ Properties()

Member Function Documentation

◆ setParam() [1/2]

◆ setParam() [2/2]

◆ param() [1/2]

◆ param() [2/2]

◆ paramMap()

◆ paramsRecursive()

◆ setAttributes()

◆ setParamAttributes() [1/2]

◆ setParamAttributes() [2/2]

◆ setParamSchema()

◆ addSubProperties()

◆ subProperties() [1/2]

◆ subProperties() [2/2]

◆ propertyMap()

◆ removeSubProperties()

◆ removeEmptySubProperties()

◆ fillPlaceHolders()

◆ iterate()

◆ compareWith()

◆ compare()

◆ copyFrom()