From 74a66d452488c249db025c7400432ec993482c59 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Mon, 17 Jun 2013 18:26:38 +0200 Subject: Say hello to Qt.labs.settings Change-Id: Id4970555b2cbbc2df893dd6269fb8b884ce06e45 Reviewed-by: Alan Alpert (Personal) <416365416c@gmail.com> --- src/imports/imports.pro | 3 +- src/imports/settings/plugin.cpp | 64 ++++++ src/imports/settings/plugins.qmltypes | 16 ++ src/imports/settings/qmldir | 3 + src/imports/settings/qqmlsettings.cpp | 415 ++++++++++++++++++++++++++++++++++ src/imports/settings/qqmlsettings_p.h | 84 +++++++ src/imports/settings/settings.pro | 15 ++ 7 files changed, 599 insertions(+), 1 deletion(-) create mode 100644 src/imports/settings/plugin.cpp create mode 100644 src/imports/settings/plugins.qmltypes create mode 100644 src/imports/settings/qmldir create mode 100644 src/imports/settings/qqmlsettings.cpp create mode 100644 src/imports/settings/qqmlsettings_p.h create mode 100644 src/imports/settings/settings.pro (limited to 'src/imports') diff --git a/src/imports/imports.pro b/src/imports/imports.pro index 7a922a832e..5bc5d61eb7 100644 --- a/src/imports/imports.pro +++ b/src/imports/imports.pro @@ -3,7 +3,8 @@ TEMPLATE = subdirs SUBDIRS += \ folderlistmodel \ localstorage \ - models + models \ + settings qtHaveModule(quick) { SUBDIRS += \ diff --git a/src/imports/settings/plugin.cpp b/src/imports/settings/plugin.cpp new file mode 100644 index 0000000000..ce955a9e36 --- /dev/null +++ b/src/imports/settings/plugin.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include + +#include "qqmlsettings_p.h" + +QT_BEGIN_NAMESPACE + +class QmlSettingsPlugin : public QQmlExtensionPlugin +{ + Q_OBJECT + Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QQmlExtensionInterface") + +public: + virtual void registerTypes(const char *uri) + { + Q_ASSERT(QByteArray(uri) == QByteArray("Qt.labs.settings")); + qmlRegisterType(uri, 1, 0, "Settings"); + } +}; + +QT_END_NAMESPACE + +#include "plugin.moc" diff --git a/src/imports/settings/plugins.qmltypes b/src/imports/settings/plugins.qmltypes new file mode 100644 index 0000000000..290c4c5570 --- /dev/null +++ b/src/imports/settings/plugins.qmltypes @@ -0,0 +1,16 @@ +import QtQuick.tooling 1.1 + +// This file describes the plugin-supplied types contained in the library. +// It is used for QML tooling purposes only. +// +// This file was auto-generated with the command 'qmlplugindump -notrelocatable Qt.labs.settings 1.0'. + +Module { + Component { + name: "QQmlSettings" + prototype: "QObject" + exports: ["Qt.labs.settings/Settings 1.0"] + exportMetaObjectRevisions: [0] + Property { name: "category"; type: "string" } + } +} diff --git a/src/imports/settings/qmldir b/src/imports/settings/qmldir new file mode 100644 index 0000000000..0d68a0742c --- /dev/null +++ b/src/imports/settings/qmldir @@ -0,0 +1,3 @@ +module Qt.labs.settings +plugin qmlsettingsplugin +typeinfo plugins.qmltypes diff --git a/src/imports/settings/qqmlsettings.cpp b/src/imports/settings/qqmlsettings.cpp new file mode 100644 index 0000000000..f73ab08cf3 --- /dev/null +++ b/src/imports/settings/qqmlsettings.cpp @@ -0,0 +1,415 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qqmlsettings_p.h" +#include +#include +#include +#include +#include + +QT_BEGIN_NAMESPACE + +/*! + \qmlmodule Qt.labs.settings 1.0 + \title Qt Labs Settings QML Types + \ingroup qmlmodules + \brief Provides persistent platform-independent application settings. + + To use this module, import the module with the following line: + + \code + import Qt.labs.settings 1.0 + \endcode +*/ + +/*! + \qmltype Settings + \instantiates QQmlSettings + \inqmlmodule Qt.labs.settings 1.0 + \ingroup settings + \brief Provides persistent platform-independent application settings. + + The Settings type provides persistent platform-independent application settings. + + \note This type is made available by importing the \b Qt.labs.settings module. + \e {Types in the Qt.labs module are not guaranteed to remain compatible + in future versions.} + + Users normally expect an application to remember its settings (window sizes + and positions, options, etc.) across sessions. The Settings type enables you + to save and restore such application settings with the minimum of effort. + + Individual setting values are specified by declaring properties within a + Settings element. All \l {QML Basic Types}{basic type} properties are + supported. The recommended approach is to use property aliases in order + to get automatic property updates both ways. The following example shows + how to use Settings to store and restore the geometry of a window. + + \qml + import QtQuick.Window 2.1 + import Qt.labs.settings 1.0 + + Window { + id: window + + width: 800 + height: 600 + + Settings { + property alias x: window.x + property alias y: window.y + property alias width: window.width + property alias height: window.height + } + } + \endqml + + At first application startup, the window gets default dimensions specified + as 800x600. Notice that no default position is specified - we let the window + manager handle that. Later when the window geometry changes, new values will + be automatically stored to the persistent settings. The second application + run will get initial values from the persistent settings, bringing the window + back to the previous position and size. + + A fully declarative syntax, achieved by using property aliases, comes at the + cost of storing persistent settings whenever the values of aliased properties + change. Normal properties can be used to gain more fine-grained control over + storing the persistent settings. The following example illustrates how to save + a setting on component destruction. + + \qml + import QtQuick 2.1 + import Qt.labs.settings 1.0 + + Item { + id: page + + state: settings.state + + states: [ + State { + name: "active" + // ... + }, + State { + name: "inactive" + // ... + } + ] + + Settings { + id: settings + property string state: "active" + } + + Component.onDestruction: { + settings.state = page.state + } + } + \endqml + + Notice how the default value is now specified in the persistent setting property, + and the actual property is bound to the setting in order to get the initial value + from the persistent settings. + + \section1 Application Identifiers + + Application specific settings are identified by providing application + \l {QCoreApplication::applicationName}{name}, + \l {QCoreApplication::organizationName}{organization} and + \l {QCoreApplication::organizationDomain}{domain}. + + \code + #include + #include + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + app.setOrganizationName("Some Company"); + app.setOrganizationDomain("somecompany.com"); + app.setApplicationName("Amazing Application"); + + QQmlApplicationEngine engine("main.qml"); + return app.exec(); + } + \endcode + + These are typically specified in C++ in the beginning of \c main(), + but can also be controlled in QML via the following properties: + \list + \li \l {Qt::application}{Qt.application.name}, + \li \l {Qt::application}{Qt.application.organization} and + \li \l {Qt::application}{Qt.application.domain}. + \endlist + + \section1 Categories + + Application settings may be divided into logical categories by specifying + a category name via the \l category property. Using logical categories not + only provides a cleaner settings structure, but also prevents possible + conflicts between setting keys. + + \qml + Item { + id: panel + + visible: true + + Settings { + category: "OutputPanel" + property alias visible: panel.visible + // ... + } + } + \endqml + + Instead of ensuring that all settings in the application have unique names, + the settings can be divided into unique categories that may then contain + settings using the same names that are used in other categories - without + a conflict. + + \section1 Notes + + The current implementation is based on \l QSettings. This imposes certain + limitations, such as missing change notifications. Writing a setting value + using one instance of Settings does not update the value in another Settings + instance, even if they are referring to the same setting in the same category. + + The information is stored in the system registry on Windows, and in XML + preferences files on OS X. On other Unix systems, in the absence of a + standard, INI text files are used. See \l QSettings documentation for + more details. + + \sa QSettings +*/ + +// #define SETTINGS_DEBUG + +static const int settingsWriteDelay = 500; + +class QQmlSettingsPrivate +{ + Q_DECLARE_PUBLIC(QQmlSettings) + +public: + QQmlSettingsPrivate(); + + QSettings *instance() const; + + void init(); + void reset(); + + void load(); + void store(); + + void _q_propertyChanged(); + + QQmlSettings *q_ptr; + int timerId; + bool initialized; + QString category; + mutable QPointer settings; + QHash changedProperties; +}; + +QQmlSettingsPrivate::QQmlSettingsPrivate() + : q_ptr(0), timerId(0), initialized(false) +{ +} + +QSettings *QQmlSettingsPrivate::instance() const +{ + if (!settings) { + QQmlSettings *q = const_cast(q_func()); + settings = new QSettings(q); + if (!category.isEmpty()) + settings->beginGroup(category); + if (initialized) + q->d_func()->load(); + } + return settings; +} + +void QQmlSettingsPrivate::init() +{ + if (!initialized) { + load(); + initialized = true; + } +} + +void QQmlSettingsPrivate::reset() +{ + if (initialized && settings && !changedProperties.isEmpty()) + store(); + delete settings; +} + +void QQmlSettingsPrivate::load() +{ + Q_Q(QQmlSettings); + const QMetaObject *mo = q->metaObject(); + const int offset = mo->propertyOffset(); + const int count = mo->propertyCount(); + for (int i = offset; i < count; ++i) { + QMetaProperty property = mo->property(i); + + const QVariant previousValue = property.read(q); + const QVariant currentValue = instance()->value(property.name(), previousValue); + + if (!currentValue.isNull() + && currentValue.canConvert(previousValue.type()) + && previousValue != currentValue) { + property.write(q, currentValue); +#ifdef SETTINGS_DEBUG + qDebug() << "QQmlSettings: load" << property.name() << "setting:" << currentValue << "default:" << previousValue; +#endif + } + + // ensure that a non-existent setting gets written + // even if the property wouldn't change later + if (!instance()->contains(property.name())) + _q_propertyChanged(); + + // setup change notifications on first load + if (!initialized && property.hasNotifySignal()) { + static const int propertyChangedIndex = mo->indexOfSlot("_q_propertyChanged()"); + QMetaObject::connect(q, property.notifySignalIndex(), q, propertyChangedIndex); + } + } +} + +void QQmlSettingsPrivate::store() +{ + QHash::iterator it = changedProperties.begin(); + while (it != changedProperties.end()) { + instance()->setValue(it.key(), it.value()); +#ifdef SETTINGS_DEBUG + qDebug() << "QQmlSettings: store" << it.key() << ":" << it.value(); +#endif + it = changedProperties.erase(it); + } +} + +void QQmlSettingsPrivate::_q_propertyChanged() +{ + Q_Q(QQmlSettings); + const QMetaObject *mo = q->metaObject(); + const int offset = mo->propertyOffset(); + const int count = mo->propertyCount(); + for (int i = offset; i < count; ++i) { + const QMetaProperty &property = mo->property(i); + changedProperties.insert(property.name(), property.read(q)); + #ifdef SETTINGS_DEBUG + qDebug() << "QQmlSettings: cache" << property.name() << ":" << property.read(q); + #endif + } + if (timerId != 0) + q->killTimer(timerId); + timerId = q->startTimer(settingsWriteDelay); +} + +QQmlSettings::QQmlSettings(QObject *parent) + : QObject(parent), d_ptr(new QQmlSettingsPrivate) +{ + Q_D(QQmlSettings); + d->q_ptr = this; +} + +QQmlSettings::~QQmlSettings() +{ + Q_D(QQmlSettings); + d->reset(); // flush pending changes +} + +/*! + \qmlproperty string Settings::category + + This property holds the name of the settings category. + + Categories can be used to group related settings together. +*/ +QString QQmlSettings::category() const +{ + Q_D(const QQmlSettings); + return d->category; +} + +void QQmlSettings::setCategory(const QString &category) +{ + Q_D(QQmlSettings); + if (d->category != category) { + d->reset(); + d->category = category; + if (d->initialized) + d->load(); + } +} + +void QQmlSettings::classBegin() +{ +} + +void QQmlSettings::componentComplete() +{ + Q_D(QQmlSettings); + d->init(); +} + +void QQmlSettings::timerEvent(QTimerEvent *event) +{ + Q_D(QQmlSettings); + if (event->timerId() == d->timerId) { + if (d->changedProperties.isEmpty()) { + killTimer(d->timerId); + d->timerId = 0; + } else { + d->store(); + } + } + QObject::timerEvent(event); +} + +QT_END_NAMESPACE + +#include "moc_qqmlsettings_p.cpp" diff --git a/src/imports/settings/qqmlsettings_p.h b/src/imports/settings/qqmlsettings_p.h new file mode 100644 index 0000000000..b5e25469dc --- /dev/null +++ b/src/imports/settings/qqmlsettings_p.h @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef QQMLSETTINGS_P_H +#define QQMLSETTINGS_P_H + +#include +#include +#include +#include + +QT_BEGIN_NAMESPACE + +class QQmlSettingsPrivate; + +class QQmlSettings : public QObject, public QQmlParserStatus +{ + Q_OBJECT + Q_INTERFACES(QQmlParserStatus) + Q_PROPERTY(QString category READ category WRITE setCategory FINAL) + +public: + explicit QQmlSettings(QObject *parent = 0); + ~QQmlSettings(); + + QString category() const; + void setCategory(const QString &category); + +protected: + void timerEvent(QTimerEvent *event); + + void classBegin(); + void componentComplete(); + +private: + Q_DISABLE_COPY(QQmlSettings) + Q_DECLARE_PRIVATE(QQmlSettings) + QScopedPointer d_ptr; + Q_PRIVATE_SLOT(d_func(), void _q_propertyChanged()) +}; + +QT_END_NAMESPACE + +QML_DECLARE_TYPE(QQmlSettings) + +#endif // QQMLSETTINGS_P_H diff --git a/src/imports/settings/settings.pro b/src/imports/settings/settings.pro new file mode 100644 index 0000000000..29229f59cb --- /dev/null +++ b/src/imports/settings/settings.pro @@ -0,0 +1,15 @@ +CXX_MODULE = qml +TARGET = qmlsettingsplugin +TARGETPATH = Qt/labs/settings +IMPORT_VERSION = 1.0 + +QT = core qml + +HEADERS += \ + qqmlsettings_p.h + +SOURCES += \ + plugin.cpp \ + qqmlsettings.cpp + +load(qml_plugin) -- cgit v1.2.3