WARNING: USE THIS SOFTWARE AT YOUR OWN RISK! THIS IS EXPERIMENTAL SOFTWARE NOT INTENDED FOR PRODUCTION USE! Zuble is currently an early stage prototype. As such Zuble is minimally tested and inherently unstable. It is provided for experimental, development, and demonstration purposes only. | Zuble QML Types | Zuble C++ Classes | Zuble Overview |
Zuble
0.1
Zuble Framework C++/QML extension API
|
Wraps the QSettings class and implements a JSON-based backend for storing the settings data. More...
#include <ZSettings.h>
Classes | |
class | SettingsBundle |
This inner class allows ZSettings to store settings bundles. More... | |
Signals | |
void | settingsModified (const QString &path) |
Sent whenever the settings file is modified by this or other programs. More... | |
void | updateValue (const QString &settingPath, const QString &settingName, QVariant oldValue, QVariant newValue) |
Sent whenever ZSettings values are modified by this or other ZSettings objects within this Qt/QML process. More... | |
Public Member Functions | |
ZSettings (QObject *parent=nullptr) | |
virtual | ~ZSettings () |
QVariant | getTags () |
QString | getFileName () const |
QStringList | getAllKeys () const |
QStringList | getChildKeys () const |
QStringList | getChildGroups () const |
bool | getWritable () const |
int | getFormat () const |
int | getScope () const |
QString | getOrganizationName () const |
QString | getApplicationName () const |
Q_INVOKABLE bool | open (int scope=static_cast< int >(QSettings::UserScope), const QString &application=QString(), const QString &organization=QString()) |
Opens the settings object in the platform-specific configuration file location. More... | |
Q_INVOKABLE bool | open (const QString &filePath) |
Opens the settings object in the specified file location. More... | |
Q_INVOKABLE bool | setFileWatcher (bool enabled) |
Enables or disables the file system watcher. This method must be called to enable this object to emit the settingsModified() signal. More... | |
Q_INVOKABLE void | clear () |
Q_INVOKABLE void | sync () |
Q_INVOKABLE int | status () const |
Q_INVOKABLE void | setValue (const QString &key, const QVariant &value) |
Q_INVOKABLE QVariant | value (const QString &key, const QVariant &defaultValue=QVariant()) const |
Q_INVOKABLE void | remove (const QString &key) |
Q_INVOKABLE bool | contains (const QString &key) const |
Q_INVOKABLE void | beginGroup (const QString &prefix) |
Q_INVOKABLE void | endGroup () |
Q_INVOKABLE QString | group () const |
Q_INVOKABLE int | beginReadArray (const QString &prefix) |
Q_INVOKABLE void | beginWriteArray (const QString &prefix, int size=-1) |
Q_INVOKABLE void | endArray () |
Q_INVOKABLE void | setArrayIndex (int i) |
Q_INVOKABLE bool | hasBundle (const QString &id) const |
Q_INVOKABLE bool | insertBundle (const QString &id, QVariant bundle) |
Q_INVOKABLE QVariant | bundle (const QString &id) const |
Q_INVOKABLE QVariant | allBundles () const |
Static Public Member Functions | |
static void | registerType () |
Registers ZSettings as a QML type. More... | |
static void | zInit () |
Initialize static variables. More... | |
static bool | readFunc (QIODevice &device, QSettings::SettingsMap &map) |
Read function for Zuble's custom settings format. More... | |
static bool | writeFunc (QIODevice &device, const QSettings::SettingsMap &map) |
Write function for Zuble's custom settings format. More... | |
static bool | containsBundle (const QString &id) |
static bool | insertBundle (const QString &id, const QString &metaPath, QSettings::Scope scope=QSettings::UserScope, const QString organization=QString(), const QString application=QString()) |
Adds the specified settings bundle to the settings repository. More... | |
static bool | insertBundle (const QString &id, const QString &meta, const QString &dataPath, bool metaAtomic=false) |
Inserts the specified settings bundle into the settings repository. More... | |
static QVariant | getBundle (const QString &id) |
static ZSettings * | getBundleSettings (const QString &id) |
Returns the ZSettings object for the specified settings bundle ID. Caller takes ownership of the ZSettings object and is responsible to delete the object or call its deleteLater() method. More... | |
static QString | getBundleMetapath (const QString &id) |
static QString | getBundleMetadata (const QString &id) |
static QVariant | getAllBundles () |
static bool | mapConfigSettings (const char *configFilePath) |
static bool | realizeSettings (const QString &id, const SettingsBundle &settingsBundle) |
Creates the default settings values for keys in the settings metadata that don't exist in the settings file. More... | |
static QString | scopeToText (QSettings::Scope scope) |
static QSettings::Scope | textToScope (const QString &text) |
Protected Member Functions | |
void | validateStatus () const |
bool | open (const SettingsBundle &settingsBundle) |
bool | validateOpen () |
void | validateWatcher () const |
void | onFileChanged (const QString &path) |
Static Protected Member Functions | |
static void | createTags () |
static void | dumpMap (const QSettings::SettingsMap &map) |
static void | dumpGroup (const QString &groupKey, const QVariant &group) |
static QString | rectifySettingsDataPath (const QString &dataPath) |
static bool | ensureFileExists (const QString &filePath) |
Protected Attributes | |
QSettings * | m_s |
Pointer to the encapsulated QSettings object. More... | |
bool | m_watching |
True if this settings object is currently watching it's source file, false otherwise. More... | |
Static Protected Attributes | |
static QVariant | m_tags |
QVariantMap of ZSettings enumerations for use by Javascript programs. More... | |
static QSettings::Format | m_format = QSettings::InvalidFormat |
QSettings custom format value assigned to Zuble for this application instance. This is the value returned from QSettings::registerFormat() More... | |
static const QString | m_ext = "zbl" |
File extension for Zuble's custom JSON format files: ".zbl". More... | |
static qint64 | m_maxFileSize = 1024 * 1000 |
Maximum size settings file that Zuble will try to read. More... | |
static bundleMap | m_bundles |
Maps settings bundle ID values to the associated bundle. More... | |
static ZFileSystemWatcher * | m_watcher = nullptr |
Monitors settings data files for updates from this and other applications. More... | |
Properties | |
QVariant | tags |
Obtain a dictionary of constants used by this object. More... | |
QVariant | fileName |
Obtain name of the storage location that backs this settings object. More... | |
QStringList | allKeys |
Obtain. More... | |
QStringList | childKeys |
Obtain. More... | |
QStringList | childGroups |
Obtain. More... | |
bool | isWritable |
Obtain. More... | |
int | format |
Obtain. More... | |
int | scope |
Obtain. More... | |
QString | organizationName |
Obtain. More... | |
QString | applicationName |
Obtain. More... | |
Private Types | |
typedef QMap< QString, SettingsBundle > | bundleMap |
Wraps the QSettings class and implements a JSON-based backend for storing the settings data.
Definition at line 44 of file ZSettings.h.
|
private |
Definition at line 87 of file ZSettings.h.
|
explicit |
Definition at line 53 of file ZSettings.cpp.
Referenced by getBundleSettings().
|
virtual |
Definition at line 74 of file ZSettings.cpp.
QVariant Zbl::ZSettings::allBundles | ( | ) | const |
Definition at line 763 of file ZSettings.cpp.
void Zbl::ZSettings::beginGroup | ( | const QString & | prefix | ) |
Definition at line 1149 of file ZSettings.cpp.
int Zbl::ZSettings::beginReadArray | ( | const QString & | prefix | ) |
Definition at line 1173 of file ZSettings.cpp.
void Zbl::ZSettings::beginWriteArray | ( | const QString & | prefix, |
int | size = -1 |
||
) |
Definition at line 1181 of file ZSettings.cpp.
QVariant Zbl::ZSettings::bundle | ( | const QString & | id | ) | const |
Definition at line 756 of file ZSettings.cpp.
Referenced by getBundle(), getBundleSettings(), and insertBundle().
void Zbl::ZSettings::clear | ( | ) |
Definition at line 1085 of file ZSettings.cpp.
bool Zbl::ZSettings::contains | ( | const QString & | key | ) | const |
Definition at line 1141 of file ZSettings.cpp.
Referenced by realizeSettings().
|
static |
Definition at line 525 of file ZSettings.cpp.
Referenced by hasBundle(), and Zbl::ZblLogManager::setApplicationObject().
|
staticprotected |
Definition at line 120 of file ZSettings.cpp.
Referenced by zInit().
|
staticprotected |
Definition at line 277 of file ZSettings.cpp.
Referenced by dumpMap().
|
staticprotected |
Definition at line 247 of file ZSettings.cpp.
Referenced by readFunc(), and writeFunc().
void Zbl::ZSettings::endArray | ( | ) |
Definition at line 1189 of file ZSettings.cpp.
void Zbl::ZSettings::endGroup | ( | ) |
Definition at line 1157 of file ZSettings.cpp.
|
staticprotected |
Definition at line 406 of file ZSettings.cpp.
Referenced by open().
|
static |
Definition at line 731 of file ZSettings.cpp.
Referenced by allBundles().
QStringList Zbl::ZSettings::getAllKeys | ( | ) | const |
Definition at line 1205 of file ZSettings.cpp.
Referenced by getChildKeys().
QString Zbl::ZSettings::getApplicationName | ( | ) | const |
Definition at line 1261 of file ZSettings.cpp.
|
static |
Definition at line 627 of file ZSettings.cpp.
Referenced by bundle(), and getAllBundles().
|
static |
Definition at line 721 of file ZSettings.cpp.
Referenced by Zbl::ZblApp::bundleMetadata().
|
static |
Definition at line 713 of file ZSettings.cpp.
Referenced by Zbl::ZblApp::bundleMetapath().
|
static |
Returns the ZSettings object for the specified settings bundle ID. Caller takes ownership of the ZSettings object and is responsible to delete the object or call its deleteLater() method.
id | The settings bundle for which a ZSettings object is requested. |
Definition at line 645 of file ZSettings.cpp.
Referenced by Zbl::ZblApp::bundleSettings(), Zbl::ZblLogManager::isCommandLineLogging(), Zbl::ZblLogManager::loadFilterRules(), Zbl::ZblLogManager::saveFilterRules(), Zbl::ZblLogManager::updateApplicationSettings(), and Zbl::ZblLogManager::updateLogProfileSettings().
QStringList Zbl::ZSettings::getChildGroups | ( | ) | const |
Definition at line 1221 of file ZSettings.cpp.
QStringList Zbl::ZSettings::getChildKeys | ( | ) | const |
Definition at line 1213 of file ZSettings.cpp.
QString Zbl::ZSettings::getFileName | ( | ) | const |
Definition at line 142 of file ZSettings.cpp.
Referenced by Zbl::ZblLogManager::onZubleSettingsModified().
int Zbl::ZSettings::getFormat | ( | ) | const |
Definition at line 1237 of file ZSettings.cpp.
QString Zbl::ZSettings::getOrganizationName | ( | ) | const |
Definition at line 1253 of file ZSettings.cpp.
int Zbl::ZSettings::getScope | ( | ) | const |
Definition at line 1245 of file ZSettings.cpp.
QVariant Zbl::ZSettings::getTags | ( | ) |
Definition at line 137 of file ZSettings.cpp.
bool Zbl::ZSettings::getWritable | ( | ) | const |
Definition at line 1229 of file ZSettings.cpp.
QString Zbl::ZSettings::group | ( | ) | const |
Definition at line 1165 of file ZSettings.cpp.
bool Zbl::ZSettings::hasBundle | ( | const QString & | id | ) | const |
Definition at line 749 of file ZSettings.cpp.
|
static |
Adds the specified settings bundle to the settings repository.
id | |
metaPath | |
scope | |
organization | |
application |
Definition at line 530 of file ZSettings.cpp.
Referenced by Zbl::ZApplication::initDefaultApplicationSettings(), Zbl::ZblLogManager::loadCurrentLogProfile(), and mapConfigSettings().
|
static |
Inserts the specified settings bundle into the settings repository.
This loads the settings metadata and settings file and then creates and initializes any key/value pairs that don't already exist in the settings file.
If the settings file doesn't currently exist it will be created. The setings metadata can be specified as a text string or a path to a metadata file.
id | The user-defined settings id (typically a URI) that will be used to reference this settings bundle. |
meta | The settings metadata or a path to a file that contains the settings metadata, depending on the state of the metaAtomic parameter. |
dataPath | The path to the settings file. This file will be created if it doesn't exist. |
metaAtomic | Set this to true if the meta parameter contains metadata or false if the meta parameter is a path to a meta data file. |
Definition at line 573 of file ZSettings.cpp.
bool Zbl::ZSettings::insertBundle | ( | const QString & | id, |
QVariant | bundle | ||
) |
Definition at line 619 of file ZSettings.cpp.
|
static |
Definition at line 770 of file ZSettings.cpp.
Referenced by Zbl::Zblcore::mapConfigSettings().
|
protected |
Definition at line 88 of file ZSettings.cpp.
Referenced by ZSettings().
bool Zbl::ZSettings::open | ( | int | scope = static_cast<int>(QSettings::UserScope) , |
const QString & | application = QString() , |
||
const QString & | organization = QString() |
||
) |
Opens the settings object in the platform-specific configuration file location.
scope | |
application | |
organization |
Definition at line 304 of file ZSettings.cpp.
Referenced by getBundleSettings(), open(), and realizeSettings().
bool Zbl::ZSettings::open | ( | const QString & | filePath | ) |
Opens the settings object in the specified file location.
filePath | Path to the settings file to open. |
Definition at line 457 of file ZSettings.cpp.
|
protected |
Definition at line 490 of file ZSettings.cpp.
|
static |
Read function for Zuble's custom settings format.
device | |
map |
Definition at line 164 of file ZSettings.cpp.
Referenced by ZSettings().
|
static |
Creates the default settings values for keys in the settings metadata that don't exist in the settings file.
id | Bundle ID |
settingsBundle | Reference to a SettingsBundle object |
Definition at line 945 of file ZSettings.cpp.
Referenced by insertBundle().
|
staticprotected |
Definition at line 930 of file ZSettings.cpp.
Referenced by mapConfigSettings().
|
static |
Registers ZSettings as a QML type.
Definition at line 82 of file ZSettings.cpp.
Referenced by Zbl::Zblcore::registerTypes().
void Zbl::ZSettings::remove | ( | const QString & | key | ) |
Definition at line 1133 of file ZSettings.cpp.
|
static |
Definition at line 1063 of file ZSettings.cpp.
void Zbl::ZSettings::setArrayIndex | ( | int | i | ) |
Definition at line 1197 of file ZSettings.cpp.
bool Zbl::ZSettings::setFileWatcher | ( | bool | enabled | ) |
Enables or disables the file system watcher. This method must be called to enable this object to emit the settingsModified() signal.
ZSettings can optionally watch for changes to a settings file made by this or other system processes and send the settingsModified() signal. Calling this method is an expensive operation because the embedded ZFileSystemWatcher object uses a mutex to add and remove watcher objects. Therefore you should only enable the file system watcher if you are connecting to the settingsModified() signal. It is disabled by default.
enabled | true enables the settingsModified signal, false disables it |
Definition at line 386 of file ZSettings.cpp.
Referenced by Zbl::ZblLogManager::updateApplicationSettings(), Zbl::ZblLogManager::updateLogProfileSettings(), and ~ZSettings().
|
signal |
Sent whenever the settings file is modified by this or other programs.
path | Path to the settings file. |
Referenced by onFileChanged(), Zbl::ZblLogManager::updateApplicationSettings(), and Zbl::ZblLogManager::updateLogProfileSettings().
void Zbl::ZSettings::setValue | ( | const QString & | key, |
const QVariant & | value | ||
) |
Definition at line 1109 of file ZSettings.cpp.
Referenced by realizeSettings().
int Zbl::ZSettings::status | ( | ) | const |
Definition at line 1101 of file ZSettings.cpp.
Referenced by ensureFileExists(), mapConfigSettings(), validateOpen(), and writeFunc().
void Zbl::ZSettings::sync | ( | ) |
Definition at line 1093 of file ZSettings.cpp.
|
static |
Definition at line 1073 of file ZSettings.cpp.
Referenced by mapConfigSettings().
|
signal |
Sent whenever ZSettings values are modified by this or other ZSettings objects within this Qt/QML process.
WARNING: changes made by calling QSettings objects directly can't be detected by ZSettings so this signal won't be sent. Use the ZSettings::settingsModified() signal to detect such changes instead.
settingPath | path to the settings file |
settingName | name of the settings object |
oldValue | previous value of the setting |
newValue | new value of the setting |
Referenced by setValue().
|
protected |
Definition at line 499 of file ZSettings.cpp.
Referenced by open().
|
inlineprotected |
Definition at line 518 of file ZSettings.h.
Referenced by beginGroup(), beginReadArray(), beginWriteArray(), clear(), contains(), endArray(), endGroup(), getAllKeys(), getApplicationName(), getChildGroups(), getChildKeys(), getFileName(), getFormat(), getOrganizationName(), getScope(), getWritable(), group(), remove(), setArrayIndex(), setValue(), status(), sync(), and value().
|
inlineprotected |
Definition at line 525 of file ZSettings.h.
Referenced by setFileWatcher().
QVariant Zbl::ZSettings::value | ( | const QString & | key, |
const QVariant & | defaultValue = QVariant() |
||
) | const |
Definition at line 1124 of file ZSettings.cpp.
Referenced by dumpGroup(), dumpMap(), Zbl::ZblLogManager::loadCurrentLogProfile(), Zbl::ZblLogManager::onZubleSettingsModified(), realizeSettings(), and setValue().
|
static |
Write function for Zuble's custom settings format.
device | |
map |
Definition at line 212 of file ZSettings.cpp.
Referenced by ZSettings().
|
static |
Initialize static variables.
Definition at line 113 of file ZSettings.cpp.
|
staticprotected |
Maps settings bundle ID values to the associated bundle.
Definition at line 498 of file ZSettings.h.
Referenced by containsBundle(), getAllBundles(), getBundle(), getBundleMetadata(), getBundleMetapath(), getBundleSettings(), and insertBundle().
|
staticprotected |
File extension for Zuble's custom JSON format files: ".zbl".
Definition at line 486 of file ZSettings.h.
Referenced by ZSettings().
|
staticprotected |
QSettings custom format value assigned to Zuble for this application instance. This is the value returned from QSettings::registerFormat()
Definition at line 480 of file ZSettings.h.
Referenced by open(), and ZSettings().
|
staticprotected |
Maximum size settings file that Zuble will try to read.
Definition at line 492 of file ZSettings.h.
Referenced by readFunc().
|
protected |
Pointer to the encapsulated QSettings object.
Definition at line 472 of file ZSettings.h.
Referenced by beginGroup(), beginReadArray(), beginWriteArray(), clear(), contains(), endArray(), endGroup(), getAllKeys(), getApplicationName(), getChildGroups(), getChildKeys(), getFileName(), getFormat(), getOrganizationName(), getScope(), getWritable(), group(), onFileChanged(), open(), remove(), setArrayIndex(), setFileWatcher(), setValue(), status(), sync(), validateOpen(), and value().
|
staticprotected |
QVariantMap of ZSettings enumerations for use by Javascript programs.
Definition at line 466 of file ZSettings.h.
Referenced by createTags(), and getTags().
|
staticprotected |
Monitors settings data files for updates from this and other applications.
Definition at line 505 of file ZSettings.h.
Referenced by onFileChanged(), setFileWatcher(), and ZSettings().
|
protected |
True if this settings object is currently watching it's source file, false otherwise.
Definition at line 511 of file ZSettings.h.
Referenced by setFileWatcher(), and ~ZSettings().
|
read |
Obtain.
Definition at line 126 of file ZSettings.h.
|
read |
Obtain.
Definition at line 168 of file ZSettings.h.
|
read |
Obtain.
Definition at line 138 of file ZSettings.h.
|
read |
Obtain.
Definition at line 132 of file ZSettings.h.
|
read |
Obtain name of the storage location that backs this settings object.
Definition at line 117 of file ZSettings.h.
|
read |
Obtain.
Definition at line 150 of file ZSettings.h.
|
read |
Obtain.
Definition at line 144 of file ZSettings.h.
|
read |
Obtain.
Definition at line 162 of file ZSettings.h.
|
read |
|
read |
Obtain a dictionary of constants used by this object.
Definition at line 111 of file ZSettings.h.
Zuble documentation copyright © 2019 Bob Dinitto. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Zuble is a derivative work of Qt version 5. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.