Skip to content

ConfigStore

#include <mrx/core/config/ConfigStore.hpp>
class mrx::core::ConfigStore

Provides thread-safe read/write access to a single INI-format QSettings file.

Every public method acquires an internal QMutex before touching the file, so a single ConfigStore instance may be shared across threads. Backend instances are created locally inside each call, so there is no long-lived handle to worry about.

Methods that operate on a specific key return false (or a safe default) when the underlying file path is absent, unreadable, or otherwise inaccessible, rather than emitting errors.

ReturnNameDescription
ConfigStore explicitConstructs a ConfigStore bound to the given INI file.
QStringfilePath constReturns the file path this store was constructed with.
QVariantreadValue constReads a single value from the store.
boolwriteValueWrites a single value to the store and flushes immediately.
boolcontains constChecks whether a key exists in the store.
boolremoveValueRemoves a single key from the store and flushes immediately.
boolmoveValueMoves a value from one key (and optionally group) to another.
QStringListkeysInGroup constLists keys stored under a given group.
boolsyncFlushes any unsynced in-memory changes to disk.
Statusstatus constReturns the current status of the underlying file.
boolbackup constCreates a backup copy of the settings file.
boolreadBool constReads a boolean value, falling back to defaultValue when absent or inaccessible.
doublereadDouble constReads a double value, falling back to defaultValue when absent or inaccessible.
intreadInt constReads an integer value, falling back to defaultValue when absent or inaccessible.
QStringreadString constReads a string value, falling back to defaultValue when absent or inaccessible.
boolwriteBoolWrites a boolean value and flushes immediately.
boolwriteDoubleWrites a double value and flushes immediately.
boolwriteIntWrites an integer value and flushes immediately.
boolwriteStringWrites a string value and flushes immediately.

explicit
explicit ConfigStore(const QString& filePath = QString())

Constructs a ConfigStore bound to the given INI file.

The file is not opened at construction time; it is opened lazily on first access.

NameTypeDescription
filePathconst QString&Absolute path to the INI file. When empty (the default), the store is unbound and every accessor returns its default or false.

const
QString filePath() const

Returns the file path this store was constructed with.


const
QVariant readValue(const QString& key, const QVariant& defaultValue = QVariant(), const QString& group = "") const

Reads a single value from the store.

The stored value, or defaultValue when the key is missing or unreadable.

This method is read-only and never modifies the file.

NameTypeDescription
keyconst QString&The key to look up.
defaultValueconst QVariant&Value returned when key is absent or the file is inaccessible.
groupconst QString&Optional INI group prefix (e.g. "Network"). Empty for the root group.

bool writeValue(const QString& key, const QVariant& value, const QString& group = "")

Writes a single value to the store and flushes immediately.

true when the write and subsequent sync succeeded; false when the key is empty, the file is inaccessible, or the sync failed.

NameTypeDescription
keyconst QString&The key to write. Must be non-empty.
valueconst QVariant&The value to store.
groupconst QString&Optional INI group prefix. Empty for the root group.

const
bool contains(const QString& key, const QString& group = "") const

Checks whether a key exists in the store.

true when the key is present and the file is accessible.

NameTypeDescription
keyconst QString&The key to look up.
groupconst QString&Optional INI group prefix. Empty for the root group.

bool removeValue(const QString& key, const QString& group = "")

Removes a single key from the store and flushes immediately.

true when the removal and subsequent sync succeeded; false when the key is empty, the file is inaccessible, or the sync failed.

NameTypeDescription
keyconst QString&The key to remove. Must be non-empty.
groupconst QString&Optional INI group prefix. Empty for the root group.

bool moveValue(const QString& oldKey, const QString& oldGroup, const QString& newKey, const QString& newGroup = "")

Moves a value from one key (and optionally group) to another.

true always, except when the file is inaccessible or either key is empty.

This method is intentionally non-destructive:

  • If oldKey does not exist, the call succeeds as a no-op.
  • If newKey already exists at the destination, the existing value is preserved and the source is not moved.

These semantics make repeated migrations safe when newer configuration versions may already contain the destination key.

NameTypeDescription
oldKeyconst QString&Source key. Must be non-empty.
oldGroupconst QString&Source group prefix. Empty for the root group.
newKeyconst QString&Destination key. Must be non-empty.
newGroupconst QString&Destination group prefix (defaults to the root group).

const
QStringList keysInGroup(const QString& group) const

Lists keys stored under a given group.

A list of keys (without the group prefix) under group, or an empty list when the file is inaccessible.

NameTypeDescription
groupconst QString&Group prefix to filter by. Empty returns all keys in the file.

bool sync()

Flushes any unsynced in-memory changes to disk.

true when the sync succeeded; false when the file is inaccessible.


const
Status status() const

Returns the current status of the underlying file.

One of:

  • NoError when the file is accessible and valid.
  • AccessError when the file path is empty, nonexistent, or not readable/writable.
  • FormatError when the file exists but contains malformed INI content.

Internally this syncs first so the status reflects the latest on-disk state.


const
bool backup(QString* backupPath = nullptr) const

Creates a backup copy of the settings file.

true when the backup was created; false when the source file does not exist or is inaccessible.

Any pre-existing “.bak file is replaced. Backups are explicit and must succeed before callers mutate a settings file.

NameTypeDescription
backupPathQString*Optional output parameter set to the absolute path of the backup file ("<filePath>.bak") on success.

const
bool readBool(const QString& key, bool defaultValue, const QString& group = "") const

Reads a boolean value, falling back to defaultValue when absent or inaccessible.

The stored value converted via QVariant::toBool().

NameTypeDescription
keyconst QString&The key to look up.
defaultValueboolValue returned when the key is missing or unreadable.
groupconst QString&Optional INI group prefix.

const
double readDouble(const QString& key, double defaultValue, const QString& group = "") const

Reads a double value, falling back to defaultValue when absent or inaccessible.

The stored value converted via QVariant::toDouble().

NameTypeDescription
keyconst QString&The key to look up.
defaultValuedoubleValue returned when the key is missing or unreadable.
groupconst QString&Optional INI group prefix.

const
int readInt(const QString& key, int defaultValue, const QString& group = "") const

Reads an integer value, falling back to defaultValue when absent or inaccessible.

The stored value converted via QVariant::toInt().

NameTypeDescription
keyconst QString&The key to look up.
defaultValueintValue returned when the key is missing or unreadable.
groupconst QString&Optional INI group prefix.

const
QString readString(const QString& key, const QString& defaultValue, const QString& group = "") const

Reads a string value, falling back to defaultValue when absent or inaccessible.

The stored value converted via QVariant::toString().

NameTypeDescription
keyconst QString&The key to look up.
defaultValueconst QString&Value returned when the key is missing or unreadable.
groupconst QString&Optional INI group prefix.

bool writeBool(const QString& key, bool value, const QString& group = "")

Writes a boolean value and flushes immediately.

true when the write and sync succeeded; false otherwise.

NameTypeDescription
keyconst QString&The key to write. Must be non-empty.
valueboolThe boolean value to store.
groupconst QString&Optional INI group prefix.

bool writeDouble(const QString& key, double value, const QString& group = "")

Writes a double value and flushes immediately.

true when the write and sync succeeded; false otherwise.

NameTypeDescription
keyconst QString&The key to write. Must be non-empty.
valuedoubleThe double value to store.
groupconst QString&Optional INI group prefix.

bool writeInt(const QString& key, int value, const QString& group = "")

Writes an integer value and flushes immediately.

true when the write and sync succeeded; false otherwise.

NameTypeDescription
keyconst QString&The key to write. Must be non-empty.
valueintThe integer value to store.
groupconst QString&Optional INI group prefix.

bool writeString(const QString& key, const QString& value, const QString& group = "")

Writes a string value and flushes immediately.

true when the write and sync succeeded; false otherwise.

NameTypeDescription
keyconst QString&The key to write. Must be non-empty.
valueconst QString&The string value to store.
groupconst QString&Optional INI group prefix.
NameDescription
StatusDescribes the current state of the underlying settings file.

enum Status

Describes the current state of the underlying settings file.

Values mirror QSettings::Status so callers can inspect them without depending on Qt directly in client code.

ValueDescription
NoErrorNo error detected during the last operation.
AccessErrorThe file does not exist, is not readable, or its path is invalid.
FormatErrorThe file exists but could not be parsed as valid INI content.