Say hello to Qt.labs.settings

Change-Id: Id4970555b2cbbc2df893dd6269fb8b884ce06e45
Reviewed-by: Alan Alpert (Personal) <416365416c@gmail.com>

7 files changed, 599 insertions, 1 deletions

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 <QtQml/qqmlextensionplugin.h>
+#include <QtQml/qqml.h>
+
+#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<QQmlSettings>(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 <qcoreevent.h>
+#include <qsettings.h>
+#include <qpointer.h>
+#include <qdebug.h>
+#include <qhash.h>
+
+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 <QGuiApplication>
+    #include <QQmlApplicationEngine>
+
+    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<QSettings> settings;
+    QHash<const char *, QVariant> changedProperties;
+};
+
+QQmlSettingsPrivate::QQmlSettingsPrivate()
+    : q_ptr(0), timerId(0), initialized(false)
+{
+}
+
+QSettings *QQmlSettingsPrivate::instance() const
+{
+    if (!settings) {
+        QQmlSettings *q = const_cast<QQmlSettings*>(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<const char *, QVariant>::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 <QtQml/qqml.h>
+#include <QtCore/qobject.h>
+#include <QtCore/qscopedpointer.h>
+#include <QtQml/qqmlparserstatus.h>
+
+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<QQmlSettingsPrivate> 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)