src/declarative/util/qdeclarativepropertymap.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qdeclarativepropertymap.h"
  43
  44 #include <private/qmetaobjectbuilder_p.h>
  45 #include <private/qdeclarativeopenmetaobject_p.h>
  46
  47 #include <QDebug>
  48
  49 QT_BEGIN_NAMESPACE
  50
  51 //QDeclarativePropertyMapMetaObject lets us listen for changes coming from QML
  52 //so we can emit the changed signal.
  53 class QDeclarativePropertyMapMetaObject : public QDeclarativeOpenMetaObject
  54 {
  55 public:
  56     QDeclarativePropertyMapMetaObject(QDeclarativePropertyMap *obj, QDeclarativePropertyMapPrivate *objPriv);
  57
  58 protected:
  59     virtual void propertyWritten(int index);
  60     virtual void propertyCreated(int, QMetaPropertyBuilder &);
  61     virtual int createProperty(const char *, const char *);
  62 private:
  63     QDeclarativePropertyMap *map;
  64     QDeclarativePropertyMapPrivate *priv;
  65 };
  66
  67 class QDeclarativePropertyMapPrivate : public QObjectPrivate
  68 {
  69     Q_DECLARE_PUBLIC(QDeclarativePropertyMap)
  70 public:
  71     QDeclarativePropertyMapMetaObject *mo;
  72     QStringList keys;
  73     void emitChanged(const QString &key, const QVariant &value);
  74     bool validKeyName(const QString& name);
  75 };
  76
  77 bool QDeclarativePropertyMapPrivate::validKeyName(const QString& name)
  78 {
  79     //The following strings shouldn't be used as property names
  80     return  name != QLatin1String("keys")
  81          && name != QLatin1String("valueChanged")
  82          && name != QLatin1String("QObject")
  83          && name != QLatin1String("destroyed")
  84          && name != QLatin1String("deleteLater");
  85 }
  86
  87 void QDeclarativePropertyMapPrivate::emitChanged(const QString &key, const QVariant &value)
  88 {
  89     Q_Q(QDeclarativePropertyMap);
  90     emit q->valueChanged(key, value);
  91 }
  92
  93 QDeclarativePropertyMapMetaObject::QDeclarativePropertyMapMetaObject(QDeclarativePropertyMap *obj, QDeclarativePropertyMapPrivate *objPriv) : QDeclarativeOpenMetaObject(obj)
  94 {
  95     map = obj;
  96     priv = objPriv;
  97 }
  98
  99 void QDeclarativePropertyMapMetaObject::propertyWritten(int index)
 100 {
 101     priv->emitChanged(QString::fromUtf8(name(index)), operator[](index));
 102 }
 103
 104 void QDeclarativePropertyMapMetaObject::propertyCreated(int, QMetaPropertyBuilder &b)
 105 {
 106     priv->keys.append(QString::fromUtf8(b.name()));
 107 }
 108
 109 int QDeclarativePropertyMapMetaObject::createProperty(const char *name, const char *value)
 110 {
 111     if (!priv->validKeyName(QString::fromUtf8(name)))
 112         return -1;
 113     return QDeclarativeOpenMetaObject::createProperty(name, value);
 114 }
 115
 116 /*!
 117     \class QDeclarativePropertyMap
 118     \brief The QDeclarativePropertyMap class allows you to set key-value pairs that can be used in QML bindings.
 119
 120     QDeclarativePropertyMap provides a convenient way to expose domain data to the UI layer.
 121     The following example shows how you might declare data in C++ and then
 122     access it in QML.
 123
 124     In the C++ file:
 125     \code
 126     // create our data
 127     QDeclarativePropertyMap ownerData;
 128     ownerData.insert("name", QVariant(QString("John Smith")));
 129     ownerData.insert("phone", QVariant(QString("555-5555")));
 130
 131     // expose it to the UI layer
 132     QDeclarativeView view;
 133     QDeclarativeContext *ctxt = view.rootContext();
 134     ctxt->setContextProperty("owner", &ownerData);
 135
 136     view.setSource(QUrl::fromLocalFile("main.qml"));
 137     view.show();
 138     \endcode
 139
 140     Then, in \c main.qml:
 141     \code
 142     Text { text: owner.name + " " + owner.phone }
 143     \endcode
 144
 145     The binding is dynamic - whenever a key's value is updated, anything bound to that
 146     key will be updated as well.
 147
 148     To detect value changes made in the UI layer you can connect to the valueChanged() signal.
 149     However, note that valueChanged() is \bold NOT emitted when changes are made by calling insert()
 150     or clear() - it is only emitted when a value is updated from QML.
 151
 152     \note It is not possible to remove keys from the map; once a key has been added, you can only
 153     modify or clear its associated value.
 154 */
 155
 156 /*!
 157     Constructs a bindable map with parent object \a parent.
 158 */
 159 QDeclarativePropertyMap::QDeclarativePropertyMap(QObject *parent)
 160 : QObject(*(new QDeclarativePropertyMapPrivate), parent)
 161 {
 162     Q_D(QDeclarativePropertyMap);
 163     d->mo = new QDeclarativePropertyMapMetaObject(this, d);
 164 }
 165
 166 /*!
 167     Destroys the bindable map.
 168 */
 169 QDeclarativePropertyMap::~QDeclarativePropertyMap()
 170 {
 171 }
 172
 173 /*!
 174     Clears the value (if any) associated with \a key.
 175 */
 176 void QDeclarativePropertyMap::clear(const QString &key)
 177 {
 178     Q_D(QDeclarativePropertyMap);
 179     d->mo->setValue(key.toUtf8(), QVariant());
 180 }
 181
 182 /*!
 183     Returns the value associated with \a key.
 184
 185     If no value has been set for this key (or if the value has been cleared),
 186     an invalid QVariant is returned.
 187 */
 188 QVariant QDeclarativePropertyMap::value(const QString &key) const
 189 {
 190     Q_D(const QDeclarativePropertyMap);
 191     return d->mo->value(key.toUtf8());
 192 }
 193
 194 /*!
 195     Sets the value associated with \a key to \a value.
 196
 197     If the key doesn't exist, it is automatically created.
 198 */
 199 void QDeclarativePropertyMap::insert(const QString &key, const QVariant &value)
 200 {
 201     Q_D(QDeclarativePropertyMap);
 202
 203     if (d->validKeyName(key)) {
 204         d->mo->setValue(key.toUtf8(), value);
 205     } else {
 206         qWarning() << "Creating property with name"
 207                    << key
 208                    << "is not permitted, conflicts with internal symbols.";
 209     }
 210 }
 211
 212 /*!
 213     Returns the list of keys.
 214
 215     Keys that have been cleared will still appear in this list, even though their
 216     associated values are invalid QVariants.
 217 */
 218 QStringList QDeclarativePropertyMap::keys() const
 219 {
 220     Q_D(const QDeclarativePropertyMap);
 221     return d->keys;
 222 }
 223
 224 /*!
 225     \overload
 226
 227     Same as size().
 228 */
 229 int QDeclarativePropertyMap::count() const
 230 {
 231     Q_D(const QDeclarativePropertyMap);
 232     return d->keys.count();
 233 }
 234
 235 /*!
 236     Returns the number of keys in the map.
 237
 238     \sa isEmpty(), count()
 239 */
 240 int QDeclarativePropertyMap::size() const
 241 {
 242     Q_D(const QDeclarativePropertyMap);
 243     return d->keys.size();
 244 }
 245
 246 /*!
 247     Returns true if the map contains no keys; otherwise returns
 248     false.
 249
 250     \sa size()
 251 */
 252 bool QDeclarativePropertyMap::isEmpty() const
 253 {
 254     Q_D(const QDeclarativePropertyMap);
 255     return d->keys.isEmpty();
 256 }
 257
 258 /*!
 259     Returns true if the map contains \a key.
 260
 261     \sa size()
 262 */
 263 bool QDeclarativePropertyMap::contains(const QString &key) const
 264 {
 265     Q_D(const QDeclarativePropertyMap);
 266     return d->keys.contains(key);
 267 }
 268
 269 /*!
 270     Returns the value associated with the key \a key as a modifiable
 271     reference.
 272
 273     If the map contains no item with key \a key, the function inserts
 274     an invalid QVariant into the map with key \a key, and
 275     returns a reference to it.
 276
 277     \sa insert(), value()
 278 */
 279 QVariant &QDeclarativePropertyMap::operator[](const QString &key)
 280 {
 281     //### optimize
 282     Q_D(QDeclarativePropertyMap);
 283     QByteArray utf8key = key.toUtf8();
 284     if (!d->keys.contains(key))
 285         insert(key, QVariant());//force creation -- needed below
 286
 287     return (*(d->mo))[utf8key];
 288 }
 289
 290 /*!
 291     \overload
 292
 293     Same as value().
 294 */
 295 QVariant QDeclarativePropertyMap::operator[](const QString &key) const
 296 {
 297     return value(key);
 298 }
 299
 300 /*!
 301     \fn void QDeclarativePropertyMap::valueChanged(const QString &key, const QVariant &value)
 302     This signal is emitted whenever one of the values in the map is changed. \a key
 303     is the key corresponding to the \a value that was changed.
 304
 305     \note valueChanged() is \bold NOT emitted when changes are made by calling insert()
 306     or clear() - it is only emitted when a value is updated from QML.
 307 */
 308
 309 QT_END_NAMESPACE