High-level declarative configuration facade. More...

#include <phosphor-config/include/PhosphorConfig/Store.h>

Inheritance diagram for PhosphorConfig::Store:

Signals
void	changed (const QString &group, const QString &key)
	Emitted after any successful `write()` or `reset()` operation.

Public Member Functions
	Store (IBackend backend, Schema schema, QObject parent=nullptr)
	Construct a store that borrows `backend` and applies `schema`.

	~Store () override

template<typename T >
T	read (const QString &group, const QString &key) const
	Read a declared key.

QVariant	readVariant (const QString &group, const QString &key) const
	Read as `QVariant`.

void	write (const QString &group, const QString &key, const QVariant &value)
	Write a value.

void	reset (const QString &group, const QString &key)
	Reset one key to its schema default.

void	resetGroup (const QString &group)
	Reset every key declared in `group`. Undeclared extras are left alone.

void	resetAll ()
	Reset every declared key in every declared group. Extras are untouched.

QJsonObject	exportToJson () const
	Produce a JSON snapshot of every declared key's current value.

bool	importFromJson (const QJsonObject &snapshot)
	Overwrite declared keys from `snapshot`.

bool	sync ()
	Flush the underlying backend.

IBackend *	backend () const
	Direct access for callers that still need the backend (e.g.

const Schema &	schema () const
	The schema the store was constructed with.

template<>
PHOSPHORCONFIG_EXPORT QString	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT int	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT bool	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT double	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT QColor	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT QVariantMap	read (const QString &, const QString &) const

template<>
PHOSPHORCONFIG_EXPORT QVariantList	read (const QString &, const QString &) const

Detailed Description

High-level declarative configuration facade.

Wraps an IBackend with a Schema so consumers get:

Automatic default fallback on reads (from the schema, no re-declared defaults at call sites)
reset() / resetGroup() / resetAll() operations, no hand-written switch statements
exportToJson() / importFromJson() for backup, dotfile sync, and settings-panel "export"
Automatic schema-version stamping and migration-runner execution on construction
A uniform changed() signal that consumers can wire directly to UI updates

Schema schema;
schema.version = 1;
schema.groups["Window"] = {
    {QStringLiteral("Width"),  600,       QMetaType::Int},
    {QStringLiteral("Height"), 400,       QMetaType::Int},
    {QStringLiteral("Title"),  QStringLiteral("Hello")},
};
 
auto store = std::make_unique<Store>(std::move(backend), schema);
int w = store->read<int>("Window", "Width"); // returns 600 if unset
store->write("Window", "Width", 800);
store->reset("Window", "Width"); // back to 600

Constructor & Destructor Documentation

◆ Store()

PhosphorConfig::Store::Store	(	IBackend *	backend,
		Schema	schema,
		QObject *	parent = `nullptr`
	)

Construct a store that borrows backend and applies schema.

The backend must outlive the store — typically owned by the caller via std::unique_ptr in a containing class. On entry the schema's migration chain runs against the backend's in-memory state; after migration the version key is stamped (JsonBackend only).

◆ ~Store()

PhosphorConfig::Store::~Store ( )

override

Member Function Documentation

◆ backend()

IBackend * PhosphorConfig::Store::backend ( ) const

Direct access for callers that still need the backend (e.g.

to read an undeclared key or to call groupList()).

◆ changed

void PhosphorConfig::Store::changed	(	const QString &	group,
		const QString &	key
	)

signal

Emitted after any successful write() or reset() operation.

Connect to refresh dependent UI.

◆ exportToJson()

QJsonObject PhosphorConfig::Store::exportToJson ( ) const

Produce a JSON snapshot of every declared key's current value.

Useful for "export settings" UIs and dotfile sync. Keys absent from the backing store are emitted with their schema default.

◆ importFromJson()

bool PhosphorConfig::Store::importFromJson ( const QJsonObject & snapshot )

Overwrite declared keys from snapshot.

Unknown groups/keys in snapshot are ignored (silently — no adaptive migration). Use MigrationRunner first if snapshot came from an older schema.

Keys declared in the schema but ABSENT from snapshot are also skipped — importFromJson is strictly additive / overwriting, never subtractive. For a full "restore defaults from snapshot" workflow, call resetAll() before importFromJson so absent keys land at their schema defaults.

Returns: true on a successful import; false when the snapshot is rejected (version mismatch, malformed version key). On a false return no keys are written. Callers should propagate the result so settings-panel UIs can distinguish "import succeeded" from "import refused" instead of relying on log scraping.

◆ read() [1/8]

template<>

PHOSPHORCONFIG_EXPORT QString PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [2/8]

template<>

PHOSPHORCONFIG_EXPORT int PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [3/8]

template<>

PHOSPHORCONFIG_EXPORT bool PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [4/8]

template<>

PHOSPHORCONFIG_EXPORT double PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [5/8]

template<>

PHOSPHORCONFIG_EXPORT QColor PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [6/8]

template<>

PHOSPHORCONFIG_EXPORT QVariantMap PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [7/8]

template<>

PHOSPHORCONFIG_EXPORT QVariantList PhosphorConfig::Store::read	(	const QString &	,
		const QString &
	)		const

◆ read() [8/8]

template<typename T >

T PhosphorConfig::Store::read	(	const QString &	group,
		const QString &	key
	)		const

inline

Read a declared key.

If the key is ABSENT, returns the schema default.
If the key is PRESENT but unparseable as T:
- For scalar types (QString, int, bool, double, QColor) returns the schema default.
- For QVariantMap and QVariantList, returns an EMPTY collection (not the schema default). This intentional asymmetry lets the Settings layer distinguish "user has never written this blob" (returns the schema default — populated value) from "blob is corrupt" (returns empty — caller substitutes library/project defaults instead of stamping the schema default back over corrupt user data).
Undeclared keys always return QVariant() — effectively T{}.

The primary template is intentionally a static_assert trap: Store::read<T> is only fully specialized for the types listed below, and instantiating it with anything else should fail at compile time with a clear message rather than at link time with an opaque "undefined reference" error.

◆ readVariant()

QVariant PhosphorConfig::Store::readVariant	(	const QString &	group,
		const QString &	key
	)		const

Read as QVariant.

Uses QString coercion on the wire and reconstructs the type via QMetaType when possible. Undeclared keys return QVariant().

◆ reset()

void PhosphorConfig::Store::reset	(	const QString &	group,
		const QString &	key
	)

Reset one key to its schema default.

No-op when the key is undeclared.

Only emits changed when the key was actually present in the backing store — a reset on a never-written key is a no-op that skips the changed() emission, since the read path already returned the schema default and no observer would see a change. Callers relying on reset() to force a QML rebinding on a pristine key should re-read via read and emit their own signal instead.

◆ resetAll()

void PhosphorConfig::Store::resetAll ( )

Reset every declared key in every declared group. Extras are untouched.

◆ resetGroup()

void PhosphorConfig::Store::resetGroup ( const QString & group )

Reset every key declared in group. Undeclared extras are left alone.

◆ schema()

const Schema & PhosphorConfig::Store::schema ( ) const

The schema the store was constructed with.

◆ sync()

bool PhosphorConfig::Store::sync ( )

Flush the underlying backend.

Returns the backend's sync() result — true on success (or nothing to flush), false on an I/O error.

◆ write()

void PhosphorConfig::Store::write	(	const QString &	group,
		const QString &	key,
		const QVariant &	value
	)

Write a value.

If the schema declares an expectedType for this key and value has a different typeId, a warning is logged but the write proceeds (Qt will coerce on read back). Emits changed.

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

phosphor-config/include/PhosphorConfig/Store.h

Phosphor Qt6 / Wayland library suite for window-management tools

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Store()

◆ ~Store()

Member Function Documentation

◆ backend()

◆ changed

◆ exportToJson()

◆ importFromJson()

◆ read() [1/8]

◆ read() [2/8]

◆ read() [3/8]

◆ read() [4/8]

◆ read() [5/8]

◆ read() [6/8]

◆ read() [7/8]

◆ read() [8/8]

◆ readVariant()

◆ reset()

◆ resetAll()

◆ resetGroup()

◆ schema()

◆ sync()

◆ write()