An interface to provide a generic way to access settings of any origin. More...

#include <isettingsaccessor.h>

Inheritance diagram for QtMvvm::ISettingsAccessor:

Public Slots
virtual void	sync ()=0
	Synchronizes the settings to the disk or whatever is needed to permanently store them. More...

Signals
void	entryChanged (const QString &key, const QVariant &value)
	Is emitted whenever a settings value was changed, at least via this instance.

void	entryRemoved (const QString &key)
	Is emitted whenever a settings value was removed, at least via this instance.

Public Member Functions
	ISettingsAccessor (QObject *parent=nullptr)
	Constructor.

virtual bool	contains (const QString &key) const =0
	Checks if a value is stored for the given key. More...

virtual QVariant	load (const QString &key, const QVariant &defaultValue={}) const =0
	Loads the value for the given key from the settings. More...

virtual void	save (const QString &key, const QVariant &value)=0
	Stores the given value under the given key in the settings. More...

virtual void	remove (const QString &key)=0
	Removes the key and all its subkeys from the settings. More...

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

virtual void *	qt_metacast (const char *)

virtual int	qt_metacall (QMetaObject::Call, int, void **)

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

Static Public Member Functions
template<typename T >
static void	setDefaultAccessor ()

static void	setDefaultAccessor (int typeId)

static ISettingsAccessor *	createDefaultAccessor (QObject *parent=nullptr)
	Create a new instance of the default accessor type. More...

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Additional Inherited Members
Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties inherited from QObject
	objectName

Detailed Description

An interface to provide a generic way to access settings of any origin.

This class is used by the SettingsViewModel and the qsettingsgenerator to access settings. The interface is meant to be used as proxy for some kind of settings backend (like QSettings), so access is kept generic and you can decide to use a different storage if needed. While this class can be used directly, it is dsigned to only be used as backend for a settings viewmodel or a generated settings instance, and thus lacks many "comfort" methods one would otherwise expect.

Note: All the semantincs desribed below, except for the change signals, are exactly the same as for QSettings, as this interface is modeled after QSettings, in other words, the same rules for keys and values as for QSettings apply to the methods of this interface.

Semantics of keys

Keys follow the following semantics. All keys are of the format group/subgroup/key. Keys may or may not be case sensitive, depending on the plattform. The best approach is to assume keys are case insensitive when storing, but case sensitive when loading. While the keys are seperated into groups and keys, all groups can also serve as keys, i.e. group/subgroup is a valid key as well.

Storing data

You can assume that data passed to save() is serializable via QDataStream. In other words, to convert the variant to binary data, you can simply use operator<< and operator>> of the QVariant. Also, just like with QSettings, the saved data does not have to retain the type. The only condition is, that whatever you load() for the same key as used for storing must be convertible to the same type as the variant, that was passed to the save() method.

Finally, saving data via this method does not have to immediatly store it permanently. However, calling load() with the same key right after save() must always return the same value as passed to it. Permanent storing can be done asynchronously, but should happen automatically without to much time passing after the save() (or remove()), and must always happen before the destruction of this object. Furthermore, users can use the sync() method to immediatly store data permanently and load all changes done externally.

Change signals

Another specialty of this class are the change signals. They must be emitted whenever save() or remove() are called, to ensure at least changes done within the same instance trigger the according change signals. Changes done externally should lead to change signals, but don't have to, if not supported. For example, the DataSyncSettingsAccessor can indeed detect changes as they occur on other instances or externally, and thus emits the signals. QSettings however does not support change signals of any kind, and thus external changes do change the data that can be loaded, but do not emit any signals.

Available implementations

Currently, the following backends are supported:

QSettingsAccessor: Wraps QSettings
DataSyncSettingsAccessor: Part of mvvm datasync core, allows to store and sync settings via datasync
AndroidSettingsAccessor: Wraps the SharedPreferences of the android API

See also: QtMvvm_ISettingsAccessorIID, QSettingsAccessor, DataSyncSettingsAccessor, AndroidSettingsAccessor, SettingsViewModel, DataSyncSettingsViewModel, The qsettingsgenerator Tool

Definition at line 15 of file isettingsaccessor.h.

Member Function Documentation

◆ contains()

QtMvvm::ISettingsAccessor::contains ( const QString & key ) const

pure virtual

Checks if a value is stored for the given key.

Parameters

key	The key of the settings entry to be checked for existance

Returns: true, if a value for that key was stored, false if not

This should only check for values, not for groups, i.e. if key referes to a group that has child keys, but no value by itself, you should still return false.

See also: ISettingsAccessor::load

Implemented in QtMvvm::AndroidSettingsAccessor, QtMvvm::DataSyncSettingsAccessor, and QtMvvm::QSettingsAccessor.

◆ createDefaultAccessor()

QtMvvm::ISettingsAccessor::createDefaultAccessor ( QObject * parent = nullptr )

static

Create a new instance of the default accessor type.

Parameters

parent The parent object to be passed to to accessor constructor

Returns: A newly created instance of the default accessor type, or nullptr

Constructs and returns a new instance of the default accessor type. The default type is QSettingsAccessor, but can be overwritten via setDefaultAccessor(). If the type set like that is invalid or cannot be dynamically constructor, nullptr can be returned.

See also: ISettingsAccessor::setDefaultAccessor

◆ load()

QtMvvm::ISettingsAccessor::load	(	const QString &	key,
		const QVariant &	defaultValue = `{}`
	)		const

pure virtual

Loads the value for the given key from the settings.

Parameters

key	The key of the settings entry to be loaded
defaultValue	A alternative value to be returned if there is no data stored for that key

Returns: The data loaded for the key, or the default value

If the given value does exist, it should be loaded and returned. If the is on data stored for that key, simply return whatever is passed as the default value.

See also: Storing data, ISettingsAccessor::contains, ISettingsAccessor::save

Implemented in QtMvvm::AndroidSettingsAccessor, QtMvvm::DataSyncSettingsAccessor, and QtMvvm::QSettingsAccessor.

◆ remove()

QtMvvm::ISettingsAccessor::remove ( const QString & key )

pure virtual

Removes the key and all its subkeys from the settings.

Parameters

key	The key of the settings entry to be removed

This method should remove the given key and all of its subkeys. If for example the settings contained the values group/subgroup and group/subgroup/key, after this method, both must have been removed. Permanent storing is done asynchronously, but can be forced via sync().

Any implementation of this method must emit the entryRemoved() signal for all the removed entries. I.e. for the example above, it must be emitted for both, group/subgroup and group/subgroup/key.

See also: Storing data, ISettingsAccessor::entryRemoved, ISettingsAccessor::save, ISettingsAccessor::sync

Implemented in QtMvvm::AndroidSettingsAccessor, QtMvvm::DataSyncSettingsAccessor, and QtMvvm::QSettingsAccessor.

◆ save()

QtMvvm::ISettingsAccessor::save	(	const QString &	key,
		const QVariant &	value
	)

pure virtual

Stores the given value under the given key in the settings.

Parameters

key	The key of the settings entry to be saved
value	The data to be stored under that key

Should simply store the passed data under the given key. You dont have to check if the variant is actually serializable, as the meta system will automatically warn the user if thats not the case. Permanent storing is done asynchronously, but can be forced via sync().

Any implementation of this method must emit the entryChanged() signal with the passed data and key.

See also: Storing data, ISettingsAccessor::entryChanged, ISettingsAccessor::load, ISettingsAccessor::remove, ISettingsAccessor::sync

Implemented in QtMvvm::AndroidSettingsAccessor, QtMvvm::DataSyncSettingsAccessor, and QtMvvm::QSettingsAccessor.

◆ setDefaultAccessor() [1/2]

template<typename T >

QtMvvm::ISettingsAccessor::setDefaultAccessor ( )

static

Template Parameters

T	The type to be registered as the default type. Must implement ISettingsAccessor

After setting the type via this method, createDefaultAccessor() will create instances of that type when called.

Note: In order for this to work, the passed type must have an invokable constructor, i.e.
Q_INVOKABLE MySettingsAccessor(QObject *parent = nullptr);

See also: ISettingsAccessor::createDefaultAccessor

Definition at line 57 of file isettingsaccessor.h.

◆ setDefaultAccessor() [2/2]

QtMvvm::ISettingsAccessor::setDefaultAccessor ( int typeId )

static

Parameters

typeId The typeId to be registered as the default type. Must implement ISettingsAccessor

After setting the type via this method, createDefaultAccessor() will create instances of that type when called.

Note: In order for this to work, the passed type must have an invokable constructor, i.e.
Q_INVOKABLE MySettingsAccessor(QObject *parent = nullptr);

See also: ISettingsAccessor::createDefaultAccessor

◆ sync

QtMvvm::ISettingsAccessor::sync ( )

pure virtualslot

Synchronizes the settings to the disk or whatever is needed to permanently store them.

You can call this method to immediatly store any changed data to permanent store. This exists because typically, calls to save() and remove() only "cache" the changes, and then later write them to the permanent store in a single transaction, as this can be an expensive operation. Normally, you don't have to care about this, as this happens automatically, but sometimes you might want to manually perform this step. Thats what this method is for.

See also: ISettingsAccessor::save, ISettingsAccessor::remove, QSettings::sync

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

isettingsaccessor.h
isettingsaccessor.dox

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Semantics of keys

Storing data

Change signals

Available implementations

Member Function Documentation

◆ contains()

◆ createDefaultAccessor()

◆ load()

◆ remove()

◆ save()

◆ setDefaultAccessor() [1/2]

◆ setDefaultAccessor() [2/2]

◆ sync