This is just a summarizing readme providing the most vital information. The official documentation can be found at https://cppproperties.insane.engineer.

Introduction

This is a C++20 library providing a property system to client classes.

Features

The library is built with the following aspects in mind:

• Modern C++
• Easy to use
• Providing "raw access" to the properties just as if they were regular class members.
• Easy registration of custom property types.
• Easy integration of optional (de)serialization (XML & JSON already optionally built-in).
• Observer interface for property change notifications.
• Support for linked properties (properties in a base class not implementing this library).
• GUI generator (Qt widgets)

Notes

A couple of things to be aware of when using this library:

• Requires a C++20 capable compiler
• Properties are stored on the heap
• The memory layout of struct { MAKE_PROPERTY(a, int) }; is not the same as struct { int a; };
• Property change notification observer callbacks are invoked by which ever thread modified the property value.

License

This library is MIT licensed.

• If JSON (de)serialization is enabled, nlohmann::json is used for JSON serialization. The json library itself is MIT licensed.
• If XML (de)serialization is enabled, tinyxml2 is used for XML serialization. The tinyxml2 library itself is zlib licensed.

Support types

Any type can be registered as a property type using the REGISTER_PROPERTY macro. For convenience, a set of built-in types are already registered:

• bool
• int
• float
• double
• std::basic_string<T> (eg. std::string, std::wstring, ...)
• std::filesystem::path

If the cmake option CPPPROPERTIES_ENABLE_BOOST is set to ON, the following types are also built-in:

• boost:uuids::uuid

If the cmake option CPPPROPERTIES_ENABLE_QT is set to ON, the following types are also built-in:

• QString
• QPoint

Examples

Start by reading the Usage section below. More examples can be found in the examples directory.

Usage

Basic usage only requires inheriting from tct::properties::properties and adding properties using MAKE_PROPERTY():

structshape :
tct::properties::properties
{
MAKE_PROPERTY(x, float);
MAKE_PROPERTY(y, float);
};

The defined properties may now be used as if they were just class members of type float:

intmain(void)
{
shape s;
s.x = 24.48f;
s.y = -13.29f;
// Print them 
std::cout << "s.x = " << s.x << std::endl;
std::cout << "s.y = " << s.y << std::endl;
}

Custom types

Custom types may be used after registering them with REGISTER_PROPERTY():

/** * Define a custom type 'color'.*/structcolor
{
std::string name;
uint8_t r, g, b;
[[nodiscard]] std::string to_string() const
{
// ...return { };
}
voidfrom_string(const std::string& str)
{ // ...
}
};
/** * Register the property*/REGISTER_PROPERTY(
color,
[this](){ return data.to_string(); },
[this](const std::string& str){ this->data.from_string(str); }
)
/** * Client class using properties.*/structshape :
tct::properties::properties
{
MAKE_PROPERTY(x, float);
MAKE_PROPERTY(y, float);
MAKE_PROPERTY(stroke_color color);
MAKE_PROPERTY(fill_color color);
};

Notifications

Properties allow registering observers to notify them upon changes of the property value.

structshape :
tct::properties::properties
{
MAKE_PROPERTY(x, float);
MAKE_PROPERTY(y, float);
shape()
{
x.register_observer([](){ std::cout << "x property changed!\n"; });
y.register_observer([](){ std::cout << "y property changed!\n"; });
}
};
intmain()
{
shape s;
s.x = 42; // Prints "x property changed!";
s.y = 73; // Prints "y property changed!";return0;
}

Serialization

The library comes with built-in support for (de)serialization. Classes can be easily (de)serialization to/from XML:

structshape :
tct::properties::properties
{
MAKE_PROPERTY(x, float);
MAKE_PROPERTY(y, float);
}intmain(void)
{
// Create a shape
shape s;
s.x = 13;
s.y = 37;
// Serialize to std::string using XML format const std::string& xml_string = s.to_xml();
std::cout << xml_string << std::endl;
// Serialize to XML file
s.to_xml_file("/path/to/shape.xml");
// Deserialize from std::string
shape s2;
s2.from_xml(xml_string);
// Deserialize from XML file
shape s3;
s3.from_xml_file("/path/to/shape.xml");
return0;
}

Linked properties

One is likely to encounter a scenario where a client class derived inherits from tct::properties::properties but also from another, existing base class base. In this case serializing an instance of derived will only contain the properties created with MAKE_PROPERTY. However, one might like (or need) to also include members of the base class although these members are not registered as properties in the base class.

An example:

structbase
{
int x;
int y;
};
structderived :
public base,
public tct::properties::properties
{
MAKE_PROPERTY(name, std::string);
};

Serializing instances of type derived will contain the name properties but not other vital information such as X & Y coordinates which are public members of base. In this cae, LINK_PROPERTY() may be used to include them in (de)serialization too:

structbase :
{
int x;
int y;
};
structderived :
public base,
public tct::properties::properties
{
MAKE_PROPERTY(name, std::string);
LINK_PROPERTY(x, &x);
LINK_PROPERTY(y, &y);
};

Linked functions (getter/setter)

This is similar to Linked properties but instead of directly accessing a base class member we use the corresponding getter & setters. This way, members from a base class only accessible via getters & setters can be included in (de)serialization.

An example:

structbase
{
public:voidset_x(constint x) { m_x = x; }
[[nodiscard]]intx() const { return m_x; }
private:int m_x = 0;
};
structderived :
base,
tct::properties::properties
{
derived()
{
LINK_PROPERTY_FUNCTIONS(x, int, base::set_x, base::x)
}
};

Qt Widgets

If CPPPROPERTIES_ENABLE_QT_WIDGETS is set to ON, Qt based widgets can be generated automatically for a property or a property group:

#include<iostream>
#include<QApplication>
#include<QWidget>
#include"cppproperties/properties.hpp"
#include"cppproperties/qt_widgets/factory.hpp"structshape :
tct::properties::properties
{
MAKE_PROPERTY(enabled, bool);
MAKE_PROPERTY(x, int);
MAKE_PROPERTY(y, int);
shape()
{
enabled.register_observer([](){ std::cout << "enabled changed!\n"; });
x.register_observer([](){ std::cout << "x changed!\n"; });
y.register_observer([](){ std::cout << "x changed!\n"; });
}
};
structcircle :
shape
{
MAKE_PROPERTY(radius, int);
circle()
{
radius.register_observer([](){ std::cout << "radius channged!\n"; });
}
};
intmain(int argc, char* argv[])
{
QApplication a(argc, argv);
circle s;
// Set some property values
s.x = 24;
s.y = 48;
s.radius = 14;
// Create widgetauto w = tct::properties::qt_widgets::factory::build_form(s);
if (w)
w->show();
return a.exec();
}

Testing

This library provides a doctest based test suite under /test. The corresponding cmake target is tests.