Detailed Description

Serialization of data structures to and from generic storage.

Serialization enables you to translate the state of data structures to a sequence of bytes that can be stored anywhere and reverse the process at later time to restore a new instance of the same data structure with the same content. In the ImFusion SDK we often refer to this concept as "configuration". It is implemented through two main classes: the Configurable interface used to make custom classes serializable and the Properties class serving as storage entity.

The Properties class (storage backend)

The Properties class serves as storage backend for serialized data. Internally it maintains a key-value map of strings so that entries can be stored and retrieved using unique identifiers. Furthermore, Properties exhibit a hierarchical structure where each Properties instance can hold an arbitrary number of subproperties. Subproperties are also identified using string as keys, which however do not need to be unique (in contrast to regular parameter identifiers).

The Configurable interface

The Configurable interface enables you to make custom data structures serializable to Properties objects. Therefore, you need to implement the pair of of configuration() (store) and configure() (retrieve) methods in a symmetric fashion.

// Inherit from Configurable to make your class serializable
class ExampleClass : public Configurable
{
public:
    // Serializes object state to the provided Properties instance
    void configuration(Properties* p) const override
    {
        if (!p)
            return;
        Configurable::configuration(p);
 
        // store a single primitive type with default value
        p->setParam("count", m_count, 42);
 
        // store a complex type in a nested subproperty
        m_nestedClass.configuration(p->addSubProperties("NestedClass"));
    }
 
    // Restores object state from the provided Properties instance
    void configure(const Properties* p) override
    {
        if (!p)
            return;
        Configurable::configure(p);
 
        // restore a single primitive type
        p->param("count", m_count);
 
        // restore a complex type from a nested property
        m_nestedClass.configure(p->subProperties("NestedClass"));
    }
 
private:
    int m_count = 42;
    SomeOtherConfigurableClass m_nestedClass;
};

The Parameter<T> and SubProperty<T> classes (syntactic sugar)

Since manual implementation of configure()/configuration() can be cumbersome and error-prone, you can make use of the Parameter and SubProperty interfaces. They are usually used as members of Configurable classes. Once registered the default implementation of Configurable::configuration()/configure() will automatically (de-)serialize the parameter values and subproperties into/from the Properties. You even should consider making the Parameter members public to avoid writing getters/setters for them. By convention, Parameter-members use the p_ prefix instead of the m_ prefix to make their semantics easier to identify in code.

// More terse implementation of the same logic as above
class ExampleClass : public Configurable
{
public:
    // Here we use a Parameter<T> instead of a naked T.
    // Initializing it in the header communicates its parameter key and the default value to the user.
    // Passing this to the constructor will register it with the Configurable interface.
    Parameter<int> p_count = {"count", 42, this};
 
    // You can nest multiple Configurable instances using the SubProperty<T> type
    SubProperty<SomeOtherConfigurableClass> p_nestedClass = {"NestedClass", SomeOtherConfigurableClass(), this};
}

Persistence

The Properties class serves as storage entity at runtime. Use the functions in the PropertiesIO namespace to write/read its contents to/from disk or a single std::string.

Automatic GUI Generation

You can use the PropertiesWidget class to automatically generate a Qt Widgets-based GUI from a populated Properties instance. Based on the Properties::ParamType "parameter type" and the Properties::setParamAttributes() "parameter attributes" it will create a suitable widget for each parameter and a nested PropertiesListWidget for each subproperty.

See also: Using Properties and Configuration

Namespaces
namespace	ImFusion::PropertiesIO
	Writing and reading Properties instances to/from structured file formats.

Classes
class	Configurable
	Base interface for classes that support object serialization from/to Properties objects. More...

class	Parameter< T >
	The Parameter class represents a single parameter of a Configurable entity. More...

class	ParameterBase
	Shared base interface of Parameter and SubProperty so that Configurable can maintain a collection of those. More...

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

struct	Attribute
	Attributes allow for attaching custom data to individual parameters or an entire Properties instance. More...

struct	Param
	Record of all properties that represent a single param inside a Properties instance. More...

struct	StringAccepter
	Helper class to enable the convenience Properties constructor taking an initializer list. More...

class	SubProperty< T >
	The SubProperty class represents a nested record of a Configurable entity. More...

class	SubPropertyList< T >
	The SubPropertyList class represents nested records of Configurable entities. More...

class	BinarySerializable
	Interface for class which can be serialized and deserialized. More...

class	PropertiesListWidget
	The PropertiesListWidget shows as sub-properties as a list. More...

class	PropertiesWidget
	The PropertiesWidget class provides a widget for Properties. More...

class	ParamControl
	Base class for parameter controls. More...

Enumerations
enum class	ParamType { Unknown = 0 , String , Bool , Integer , Double , Vector , Matrix , Color , Enum , EnumString , Path , List , Subproperty , ListFlag = 64 , OptionalFlag = 128 }
	Enumeration of available high-level parameter types, mainly used to automatically generate a suitable GUI. More...

Functions
std::optional< std::string >	saveToString (const Properties &properties, Format format, const std::string &commentString="")
	Serialize the given Properties instance to a string using the specified format.

bool	saveToXML (const Properties &properties, const Filesystem::Path &filename, Format format, const std::string &commentString="")
	Serialize the given Properties instance to an XML file on the local filesystem.

bool	saveToJSON (const Properties &properties, const Filesystem::Path &filename, Format format, const std::string &commentString="")
	Serialize the given Properties instance to a JSON file on the local filesystem.

std::unique_ptr< Properties >	loadFromString (const std::string &input, Format format)
	Deserialize the given input string to a new Properties instance using the specified format.

std::unique_ptr< Properties >	loadFromXML (const Filesystem::Path &filename)
	Deserialize the given XML file to a new Properties instance.

std::unique_ptr< Properties >	loadFromJSON (const Filesystem::Path &filename)
	Deserialize the given JSON file to a new Properties instance.

Enumeration Type Documentation

◆ ParamType

enum class ParamType

strong

#include <ImFusion/Core/PropertiesDetail.h>

Enumeration of available high-level parameter types, mainly used to automatically generate a suitable GUI.

Enumerator
Unknown	Unspecified.
String	Free text.
Bool	Boolean value.
Integer	Integer value.
Double	Floating-point value.
Vector	Eigen vector of any type.
Matrix	Eigen matrix of any type.
Color	Color representation of Vector with 4 entries ranging from 0 to 1.
Enum	Enumeration saved as an integer.
EnumString	Enumeration saved as a string.
Path	A file path.
List	A generic list of elements of unknown type, e.g. a std::vector<T> Deprecated Use ListFlag in combination with the element type instead
Subproperty	Not used for a single parameter, distinguishes parameters from sub-props in predicates/callbacks (e.g. copyFrom())
ListFlag	Additional bit used to denote a list<T> where T is indicated by the remaining bits.
OptionalFlag	Additional bit used to denote an Optional<T> where T is indicated by the remaining bits.