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
Classes | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | Properties | Private Types | List of all members
Zbl::ZSettings Class Reference

Wraps the QSettings class and implements a JSON-based backend for storing the settings data. More...

#include <ZSettings.h>

Inheritance diagram for Zbl::ZSettings:
Inheritance graph
[legend]
Collaboration diagram for Zbl::ZSettings:
Collaboration graph
[legend]

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 ZSettingsgetBundleSettings (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 ZFileSystemWatcherm_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, SettingsBundlebundleMap
 

Detailed Description

Wraps the QSettings class and implements a JSON-based backend for storing the settings data.

Definition at line 44 of file ZSettings.h.

Member Typedef Documentation

◆ bundleMap

typedef QMap<QString, SettingsBundle> Zbl::ZSettings::bundleMap
private

Definition at line 87 of file ZSettings.h.

Constructor & Destructor Documentation

◆ ZSettings()

Zbl::ZSettings::ZSettings ( QObject *  parent = nullptr)
explicit

Definition at line 53 of file ZSettings.cpp.

Referenced by getBundleSettings().

◆ ~ZSettings()

Zbl::ZSettings::~ZSettings ( )
virtual

Definition at line 74 of file ZSettings.cpp.

Member Function Documentation

◆ allBundles()

QVariant Zbl::ZSettings::allBundles ( ) const

Definition at line 763 of file ZSettings.cpp.

◆ beginGroup()

void Zbl::ZSettings::beginGroup ( const QString &  prefix)

Definition at line 1149 of file ZSettings.cpp.

◆ beginReadArray()

int Zbl::ZSettings::beginReadArray ( const QString &  prefix)

Definition at line 1173 of file ZSettings.cpp.

◆ beginWriteArray()

void Zbl::ZSettings::beginWriteArray ( const QString &  prefix,
int  size = -1 
)

Definition at line 1181 of file ZSettings.cpp.

◆ bundle()

QVariant Zbl::ZSettings::bundle ( const QString &  id) const

Definition at line 756 of file ZSettings.cpp.

Referenced by getBundle(), getBundleSettings(), and insertBundle().

◆ clear()

void Zbl::ZSettings::clear ( )

Definition at line 1085 of file ZSettings.cpp.

◆ contains()

bool Zbl::ZSettings::contains ( const QString &  key) const

Definition at line 1141 of file ZSettings.cpp.

Referenced by realizeSettings().

◆ containsBundle()

bool Zbl::ZSettings::containsBundle ( const QString &  id)
static

Definition at line 525 of file ZSettings.cpp.

Referenced by hasBundle(), and Zbl::ZblLogManager::setApplicationObject().

◆ createTags()

void Zbl::ZSettings::createTags ( )
staticprotected

Definition at line 120 of file ZSettings.cpp.

Referenced by zInit().

◆ dumpGroup()

void Zbl::ZSettings::dumpGroup ( const QString &  groupKey,
const QVariant &  group 
)
staticprotected

Definition at line 277 of file ZSettings.cpp.

Referenced by dumpMap().

◆ dumpMap()

void Zbl::ZSettings::dumpMap ( const QSettings::SettingsMap &  map)
staticprotected

Definition at line 247 of file ZSettings.cpp.

Referenced by readFunc(), and writeFunc().

◆ endArray()

void Zbl::ZSettings::endArray ( )

Definition at line 1189 of file ZSettings.cpp.

◆ endGroup()

void Zbl::ZSettings::endGroup ( )

Definition at line 1157 of file ZSettings.cpp.

◆ ensureFileExists()

bool Zbl::ZSettings::ensureFileExists ( const QString &  filePath)
staticprotected

Definition at line 406 of file ZSettings.cpp.

Referenced by open().

◆ getAllBundles()

QVariant Zbl::ZSettings::getAllBundles ( )
static

Definition at line 731 of file ZSettings.cpp.

Referenced by allBundles().

◆ getAllKeys()

QStringList Zbl::ZSettings::getAllKeys ( ) const

Definition at line 1205 of file ZSettings.cpp.

Referenced by getChildKeys().

◆ getApplicationName()

QString Zbl::ZSettings::getApplicationName ( ) const

Definition at line 1261 of file ZSettings.cpp.

◆ getBundle()

QVariant Zbl::ZSettings::getBundle ( const QString &  id)
static

Definition at line 627 of file ZSettings.cpp.

Referenced by bundle(), and getAllBundles().

◆ getBundleMetadata()

QString Zbl::ZSettings::getBundleMetadata ( const QString &  id)
static

Definition at line 721 of file ZSettings.cpp.

Referenced by Zbl::ZblApp::bundleMetadata().

◆ getBundleMetapath()

QString Zbl::ZSettings::getBundleMetapath ( const QString &  id)
static

Definition at line 713 of file ZSettings.cpp.

Referenced by Zbl::ZblApp::bundleMetapath().

◆ getBundleSettings()

ZSettings * Zbl::ZSettings::getBundleSettings ( const QString &  id)
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.

Parameters
idThe settings bundle for which a ZSettings object is requested.
Returns
A ZSettings object for the specified bundle, or NULL if an error occurred.

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().

◆ getChildGroups()

QStringList Zbl::ZSettings::getChildGroups ( ) const

Definition at line 1221 of file ZSettings.cpp.

◆ getChildKeys()

QStringList Zbl::ZSettings::getChildKeys ( ) const

Definition at line 1213 of file ZSettings.cpp.

◆ getFileName()

QString Zbl::ZSettings::getFileName ( ) const

Definition at line 142 of file ZSettings.cpp.

Referenced by Zbl::ZblLogManager::onZubleSettingsModified().

◆ getFormat()

int Zbl::ZSettings::getFormat ( ) const

Definition at line 1237 of file ZSettings.cpp.

◆ getOrganizationName()

QString Zbl::ZSettings::getOrganizationName ( ) const

Definition at line 1253 of file ZSettings.cpp.

◆ getScope()

int Zbl::ZSettings::getScope ( ) const

Definition at line 1245 of file ZSettings.cpp.

◆ getTags()

QVariant Zbl::ZSettings::getTags ( )

Definition at line 137 of file ZSettings.cpp.

◆ getWritable()

bool Zbl::ZSettings::getWritable ( ) const

Definition at line 1229 of file ZSettings.cpp.

◆ group()

QString Zbl::ZSettings::group ( ) const

Definition at line 1165 of file ZSettings.cpp.

◆ hasBundle()

bool Zbl::ZSettings::hasBundle ( const QString &  id) const

Definition at line 749 of file ZSettings.cpp.

◆ insertBundle() [1/3]

bool Zbl::ZSettings::insertBundle ( const QString &  id,
const QString &  metaPath,
QSettings::Scope  scope = QSettings::UserScope,
const QString  organization = QString(),
const QString  application = QString() 
)
static

Adds the specified settings bundle to the settings repository.

Parameters
id
metaPath
scope
organization
application
Returns

Definition at line 530 of file ZSettings.cpp.

Referenced by Zbl::ZApplication::initDefaultApplicationSettings(), Zbl::ZblLogManager::loadCurrentLogProfile(), and mapConfigSettings().

◆ insertBundle() [2/3]

bool Zbl::ZSettings::insertBundle ( const QString &  id,
const QString &  meta,
const QString &  dataPath,
bool  metaAtomic = false 
)
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.

Parameters
idThe user-defined settings id (typically a URI) that will be used to reference this settings bundle.
metaThe settings metadata or a path to a file that contains the settings metadata, depending on the state of the metaAtomic parameter.
dataPathThe path to the settings file. This file will be created if it doesn't exist.
metaAtomicSet this to true if the meta parameter contains metadata or false if the meta parameter is a path to a meta data file.
Returns
true if settings bundle was inserted successfully, false if an error occurred

Definition at line 573 of file ZSettings.cpp.

◆ insertBundle() [3/3]

bool Zbl::ZSettings::insertBundle ( const QString &  id,
QVariant  bundle 
)

Definition at line 619 of file ZSettings.cpp.

◆ mapConfigSettings()

bool Zbl::ZSettings::mapConfigSettings ( const char *  configFilePath)
static

Definition at line 770 of file ZSettings.cpp.

Referenced by Zbl::Zblcore::mapConfigSettings().

◆ onFileChanged()

void Zbl::ZSettings::onFileChanged ( const QString &  path)
protected

Definition at line 88 of file ZSettings.cpp.

Referenced by ZSettings().

◆ open() [1/3]

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.

Parameters
scope
application
organization
Returns
true if settings object opened successfully, false if failed

Definition at line 304 of file ZSettings.cpp.

Referenced by getBundleSettings(), open(), and realizeSettings().

◆ open() [2/3]

bool Zbl::ZSettings::open ( const QString &  filePath)

Opens the settings object in the specified file location.

Parameters
filePathPath to the settings file to open.
Returns
true if settings object opened successfully, false if failed

Definition at line 457 of file ZSettings.cpp.

◆ open() [3/3]

bool Zbl::ZSettings::open ( const SettingsBundle settingsBundle)
protected

Definition at line 490 of file ZSettings.cpp.

◆ readFunc()

bool Zbl::ZSettings::readFunc ( QIODevice &  device,
QSettings::SettingsMap &  map 
)
static

Read function for Zuble's custom settings format.

Parameters
device
map
Returns

Definition at line 164 of file ZSettings.cpp.

Referenced by ZSettings().

◆ realizeSettings()

bool Zbl::ZSettings::realizeSettings ( const QString &  id,
const SettingsBundle settingsBundle 
)
static

Creates the default settings values for keys in the settings metadata that don't exist in the settings file.

Parameters
idBundle ID
settingsBundleReference to a SettingsBundle object
Returns
true if success, false if failed

Definition at line 945 of file ZSettings.cpp.

Referenced by insertBundle().

◆ rectifySettingsDataPath()

QString Zbl::ZSettings::rectifySettingsDataPath ( const QString &  dataPath)
staticprotected

Definition at line 930 of file ZSettings.cpp.

Referenced by mapConfigSettings().

◆ registerType()

void Zbl::ZSettings::registerType ( )
static

Registers ZSettings as a QML type.

Definition at line 82 of file ZSettings.cpp.

Referenced by Zbl::Zblcore::registerTypes().

◆ remove()

void Zbl::ZSettings::remove ( const QString &  key)

Definition at line 1133 of file ZSettings.cpp.

◆ scopeToText()

QString Zbl::ZSettings::scopeToText ( QSettings::Scope  scope)
static

Definition at line 1063 of file ZSettings.cpp.

◆ setArrayIndex()

void Zbl::ZSettings::setArrayIndex ( int  i)

Definition at line 1197 of file ZSettings.cpp.

◆ setFileWatcher()

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.

Parameters
enabledtrue 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().

◆ settingsModified

void Zbl::ZSettings::settingsModified ( const QString &  path)
signal

Sent whenever the settings file is modified by this or other programs.

Parameters
pathPath to the settings file.

Referenced by onFileChanged(), Zbl::ZblLogManager::updateApplicationSettings(), and Zbl::ZblLogManager::updateLogProfileSettings().

◆ setValue()

void Zbl::ZSettings::setValue ( const QString &  key,
const QVariant &  value 
)

Definition at line 1109 of file ZSettings.cpp.

Referenced by realizeSettings().

◆ status()

int Zbl::ZSettings::status ( ) const

Definition at line 1101 of file ZSettings.cpp.

Referenced by ensureFileExists(), mapConfigSettings(), validateOpen(), and writeFunc().

◆ sync()

void Zbl::ZSettings::sync ( )

Definition at line 1093 of file ZSettings.cpp.

◆ textToScope()

QSettings::Scope Zbl::ZSettings::textToScope ( const QString &  text)
static

Definition at line 1073 of file ZSettings.cpp.

Referenced by mapConfigSettings().

◆ updateValue

void Zbl::ZSettings::updateValue ( const QString &  settingPath,
const QString &  settingName,
QVariant  oldValue,
QVariant  newValue 
)
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.

Parameters
settingPathpath to the settings file
settingNamename of the settings object
oldValueprevious value of the setting
newValuenew value of the setting

Referenced by setValue().

◆ validateOpen()

bool Zbl::ZSettings::validateOpen ( )
protected

Definition at line 499 of file ZSettings.cpp.

Referenced by open().

◆ validateStatus()

void Zbl::ZSettings::validateStatus ( ) const
inlineprotected

◆ validateWatcher()

void Zbl::ZSettings::validateWatcher ( ) const
inlineprotected

Definition at line 525 of file ZSettings.h.

Referenced by setFileWatcher().

◆ value()

QVariant Zbl::ZSettings::value ( const QString &  key,
const QVariant &  defaultValue = QVariant() 
) const

◆ writeFunc()

bool Zbl::ZSettings::writeFunc ( QIODevice &  device,
const QSettings::SettingsMap &  map 
)
static

Write function for Zuble's custom settings format.

Parameters
device
map
Returns

Definition at line 212 of file ZSettings.cpp.

Referenced by ZSettings().

◆ zInit()

void Zbl::ZSettings::zInit ( )
static

Initialize static variables.

Definition at line 113 of file ZSettings.cpp.

Member Data Documentation

◆ m_bundles

ZSettings::bundleMap Zbl::ZSettings::m_bundles
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().

◆ m_ext

const QString Zbl::ZSettings::m_ext = "zbl"
staticprotected

File extension for Zuble's custom JSON format files: ".zbl".

Definition at line 486 of file ZSettings.h.

Referenced by ZSettings().

◆ m_format

QSettings::Format Zbl::ZSettings::m_format = QSettings::InvalidFormat
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().

◆ m_maxFileSize

qint64 Zbl::ZSettings::m_maxFileSize = 1024 * 1000
staticprotected

Maximum size settings file that Zuble will try to read.

Definition at line 492 of file ZSettings.h.

Referenced by readFunc().

◆ m_s

QSettings* Zbl::ZSettings::m_s
protected

◆ m_tags

QVariant Zbl::ZSettings::m_tags
staticprotected

QVariantMap of ZSettings enumerations for use by Javascript programs.

Definition at line 466 of file ZSettings.h.

Referenced by createTags(), and getTags().

◆ m_watcher

ZFileSystemWatcher * Zbl::ZSettings::m_watcher = nullptr
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().

◆ m_watching

bool Zbl::ZSettings::m_watching
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().

Property Documentation

◆ allKeys

QStringList Zbl::ZSettings::allKeys
read

Obtain.

Definition at line 126 of file ZSettings.h.

◆ applicationName

QString Zbl::ZSettings::applicationName
read

Obtain.

Definition at line 168 of file ZSettings.h.

◆ childGroups

QStringList Zbl::ZSettings::childGroups
read

Obtain.

Definition at line 138 of file ZSettings.h.

◆ childKeys

QStringList Zbl::ZSettings::childKeys
read

Obtain.

Definition at line 132 of file ZSettings.h.

◆ fileName

QVariant Zbl::ZSettings::fileName
read

Obtain name of the storage location that backs this settings object.

Definition at line 117 of file ZSettings.h.

◆ format

int Zbl::ZSettings::format
read

Obtain.

Definition at line 150 of file ZSettings.h.

◆ isWritable

bool Zbl::ZSettings::isWritable
read

Obtain.

Definition at line 144 of file ZSettings.h.

◆ organizationName

QString Zbl::ZSettings::organizationName
read

Obtain.

Definition at line 162 of file ZSettings.h.

◆ scope

int Zbl::ZSettings::scope
read

Obtain.

Definition at line 156 of file ZSettings.h.

Referenced by getBundleSettings().

◆ tags

QVariant Zbl::ZSettings::tags
read

Obtain a dictionary of constants used by this object.

Definition at line 111 of file ZSettings.h.


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