SubProperty< T > Class Template Reference

#include <ImFusion/Core/SubProperty.h>

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

Inheritance diagram for SubProperty< T >:

Detailed Description

template<typename T>
class ImFusion::SubProperty< T >

The SubProperty class represents a nested record of a Configurable entity.

It is intended to be used as member of Configurable classes and enables you to reduce the amount of boilerplate code needed to implement the pair of configure()/configuration() functions for each nested class member that is supposed to be serialized. In order for this to work each SubProperty must be registered with the parent Configurable instance. This can be automatized by passing it as additional argument to the corresponding constructor overload. Registration is preserved across copies/moves/assignments, and removed on destruction.

SubProperties wrap a regular type T that must implement the Configurable interface or alternatively an std::optional or std::unique_ptr of it and make it serializable to/from the Properties interface. The nested object is stored as a subproperty inside the given Properties.

Depending on T the behavior of configure() is as follows:

• If T is a regular value type it will always configure the payload from the subproperty if present.
• If T is of type std::optional<S> configure will set the payload to the empty Optional if the subproperty is absent, and instantiate a default-constructed S if the subproperty is present. Therefore, S must be default-constructible.
• If T is of type std::unique_ptr<S> configure will not change the null-state of the payload: This means that if T is originally not null but the subproperty is absent the payload will remain unchanged. Also, if T is originally null but the subproperty is present the payload will remain nullptr. This is an active design decision to allow S to be a polymorphic and/or not default-constructible type.

The SubProperty class provides the arrow operator, so that you can easily access members of the nested elements:

struct InnerStruct : public Configurable {
    Parameter<int> p_count = {"count", 0, this};
}
struct OuterStruct : public Configurable {
    SubProperty<InnerStruct> p_innerStruct = {"InnerStruct", InnerStruct(), this};
}
 
OuterStruct o;
o.p_innerStruct->p_count = 42;

The signal signalValueChanged is only emitted whenever the nested object is changed using setValue(), configure(), or if its Configurable::signalParametersChanged was emitted.

By convention, public SubProperties members use the p_ prefix for the variable name (instead of the common m_ prefix) in order to make their semantics easier to identify in code.

Note

Due to the way deserialization is implemented, you can not have multiple SubProperty instances with the same name next to each other.

Template Parameters

T	Underlying type of the parameter, must be copyable and implement the Configurable interface. If T is nullable (pointer/optional) those requirements apply to its payload.

See also

Parameter, SubPropertyList

Public Member Functions
template<typename U>
	SubProperty (const std::string &name, U &&value)
	Creates a SubProperty that will be configured under the given name and with the given initial value.
template<typename U>
	SubProperty (const std::string &name, U &&value, Configurable *parent)
	Create a SubProperty that is directly registered to the parent Configurable instance.
template<typename U>
	SubProperty (const std::string &name, U &&value, Configurable &parent)
	SubProperty (const SubProperty< T > &other)
	SubProperty (SubProperty< T > &&other)
SubProperty< T > &	operator= (const SubProperty< T > &other)
	Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.
SubProperty< T > &	operator= (SubProperty< T > &other)
	Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.
SubProperty< T > &	operator= (SubProperty< T > &&other)
	Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.
template<typename U>
SubProperty< T > &	operator= (U &&value)
	Assign a new value to this SubProperty, emits signalValueChanged.
template<typename U>
void	setValue (U &&value)
	Assign a new value to this SubProperty, emits signalValueChanged.
const T &	value () const
	Access the underlying value.
T &	value ()
const T *	operator-> () const
	Access the underlying value.
T *	operator-> ()
void	configure (const Properties *p) override
	Configure this parameter/sub property by de-serializing the given Properties.
void	configuration (Properties *p) const override
	Serialize the current parameter/sub property state into the given Properties object.
Public Member Functions inherited from ParameterBase
	ParameterBase (const std::string &name)
const Configurable *	parent () const
	Return the parent Configurable instance that this parameter is registered with.
virtual const std::string &	name () const
	Returns parameter name, can only be set during construction.
void	setAttribute (const std::string &key, const std::string &value)
	Add the given attribute key-value pair to the set of parameter attributes.
void	removeAttribute (const std::string &key)
	Remove the attribute with the given key.
const std::map< std::string, std::string > &	attributes () const
	Get the attribute map.
void	setLabel (const std::string &label)
	Sets an optional label for the Parameter if displayed in the UI.
void	addDeprecatedName (const std::string &deprecatedName)
	Adds an optional alternative parameter name that should be used for param lookup for during configure() in case de-serialization from m_name was not successful.
const std::vector< std::string > &	deprecatedNames () const
	Returns the list of deprecated parameter names that should be used for param lookup (see addDeprecatedName()).
Public Member Functions inherited from SignalReceiver
	SignalReceiver ()=default
	Default constructor.
	SignalReceiver (const SignalReceiver &other)
	Copy constructor, does not copy any existing signal connections from other.
SignalReceiver &	operator= (SignalReceiver rhs)
	Assignment operator, disconnects all existing connections, does not copy any existing signal connections from rhs.
virtual	~SignalReceiver ()
	Virtual destructor disconnects from all connected signals.

Protected Attributes
T	m_value
Protected Attributes inherited from ParameterBase
Configurable *	m_parent = nullptr
const std::string	m_name
std::vector< std::string >	m_deprecatedNames
std::map< std::string, std::string >	m_attributes

Additional Inherited Members
Public Attributes inherited from ParameterBase
Signal	signalValueChanged
	Signal gets emitted when the underlying value of the Parameter/SubProperty has changed (either through setValue() or configure()).
Protected Member Functions inherited from ParameterBase
void	setParentFromCopy (const ParameterBase &other)
	Helper function to be called from a copy/move ctor in order to correctly set the parent relation ship to the new parent Configurable.
Protected Member Functions inherited from SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Constructor & Destructor Documentation

SubProperty()

template<typename T>

template<typename U>

SubProperty	(	const std::string &	name,
		U &&	value,
		Configurable *	parent )

Create a SubProperty that is directly registered to the parent Configurable instance.

The parent instance is stored and thus must have a lifetime longer than this object.

Member Function Documentation

operator=() [1/3]

template<typename T>

SubProperty< T > & operator=

(

const SubProperty< T > &

other

)

Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.

Expects name and deprecated names to be the same and will not change the parent relationship. Use *this = other.value() if you want to assign only the value from other

operator=() [2/3]

template<typename T>

SubProperty< T > & operator=

(

SubProperty< T > &

other

)

Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.

Expects name and deprecated names to be the same and will not change the parent relationship. Use *this = other.value() if you want to assign only the value from other

Note

This implementation is required as otherwise operator=(U&&) will be picked up as non-const assign operator.

operator=() [3/3]

template<typename T>

SubProperty< T > & operator=

(

SubProperty< T > &&

other

)

Assigns the value and attributes from another SubProperty instance of the same type and emits signalValueChanged.

Expects name and deprecated names to be the same and will not change the parent relationship. Use *this = other.value() if you want to assign only the value from other

configure()

template<typename T>

void configure ( const Properties * p )

overridevirtual

Configure this parameter/sub property by de-serializing the given Properties.

Depending on T the behavior of configure(const Properties* p) is as follows:

• If T is a regular value type it will always configure the payload from the subproperty if present in p.
• If T is of type std::optional<S> configure will set the payload to nullopt if the subproperty is absent in p, and instantiate a default-constructed S if the subproperty is present in p. Therefore, S must be default-constructible.
• If T is of type std::unique_ptr<S> configure will not change the null-state of the payload: This means that if T is originally not null but the subproperty is absent in p the payload will remain unchanged. Also, if T is originally null but the subproperty is present in p the payload will remain nullptr. This is an active design decision to allow S to be a polymorphic and/or not default-constructible type.

Implements ParameterBase.

configuration()

template<typename T>

void configuration ( Properties * p ) const

overridevirtual

Serialize the current parameter/sub property state into the given Properties object.

Implements ParameterBase.

---

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

• ImFusion/Core/SubProperty.h