Add Q_GADGET wrappers for QModelIndex & Co.

The complete list of types is,
  * QModelIndex
  * QModelIndexList
  * QPersistentModelIndex
  * QItemSelection
  * QItemSelectionRange

These wrapper types follow the QQmlValueType conventions and
allow us to expose the wrapped types without introducing
meta-type changes. They also allow to customize the string
type representation.

We also extend QQmlValueTypeFactory to return the meta-object
for those types.

Finally, we add two-way meta-type conversion between QModelIndex
and QPersistentModelIndex to get the same interoperability as
in C++ when passing an object of one type to a function requir-
ing an object of the other type.

Change-Id: Iaa7089ea576c901f12715ffa21e4d94603d53755
Reviewed-by: Caroline Chao <caroline.chao@theqtcompany.com>

4 files changed, 392 insertions, 0 deletions

diff --git a/src/qml/types/qqmlitemmodels.qdoc b/src/qml/types/qqmlitemmodels.qdoc
new file mode 100644
index 0000000000..25c9321115
--- /dev/null
+++ b/src/qml/types/qqmlitemmodels.qdoc
@@ -0,0 +1,115 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \chapter QModelIndex & Co. in QML
+
+    Since Qt 5.5, QModelIndex and QPersistentModelIndex are exposed in QML as
+    value-based types. Also exposed in a similar fashion are QModelIndexList,
+    QItemSelectionRange and QItemSelection. All objects from these types can
+    be passed back and forth between QML and C++ as \c var properties or plain
+    JavaScript variables.
+
+    We detail here which API all these classes get exposed in QML. Please refer
+    to the C++ documentation for more information.
+
+    \note Since all these types are exposed as gadgets, there are no property
+    change notification signals emitted. Therefore binding to their properties
+    may not give the expected results. This is especially true for QPersistentModelIndex.
+    It is perfectly possible to bind to properties holding any of those types.
+
+    \section1 \l QModelIndex and \l QPersistentModelIndex
+
+    \list
+    \li \b row : int
+    \li \b column : int
+    \li \b parent : QModelIndex
+    \li \b valid : bool
+    \li \b model : QAbstractItemModel
+    \li \b internalId : quint64
+    \endlist
+
+    All these properties are read-only, as their C++ counterpart.
+
+    \note The usual caveats apply to QModelIndex in QML. If the underlying model changes
+    or gets deleted, it may become dangerous to access its properties. Therefore, you
+    should not store any QModelIndex. You can, however, store QPersistentModelIndexes
+    in a safe way.
+
+    \section1 \l QItemSelectionRange
+
+    \list
+    \li \b top : int
+    \li \b left : int
+    \li \b bottom : int
+    \li \b right : int
+    \li \b width : int
+    \li \b height : int
+    \li \b topLeft : QPersistentModelIndex
+    \li \b bottomRight : QPersistentModelIndex
+    \li \b parent : QModelIndex
+    \li \b valid : bool
+    \li \b empty : bool
+    \li \b model : QAbstractItemModel
+    \endlist
+
+    All these properties are read-only, as their C++ counterpart. In addition,
+    we also expose the following functions:
+
+    \list
+    \li bool \b{contains}(QModelIndex index)
+    \li bool \b{contains}(int row, int column, QModelIndex parentIndex)
+    \li bool \b{intersects}(QItemSelectionRange other)
+    \li QItemSelectionRange \b{intersected}(QItemSelectionRange other)
+    \endlist
+
+    \section1 \l QModelIndexList and \l QItemSelection
+
+    Both \l QModelIndexList and \l QItemSelection expose the following properties
+    and functions as part of their \l QList API:
+
+    \list
+    \li \b length : int
+    \li object \b{at}(int i)
+    \li void \b{append}(object o)
+    \li void \b{prepend}(o)
+    \li void \b{insert}(int i, object o)
+    \li void \b{removeFirst}()
+    \li void \b{removeLast}()
+    \li void \b{removeAt}(int i)
+    \endlist
+
+    In addition, \l QItemSelection also exposes the following functions:
+
+    \list
+    \li void \b{select}(QModelIndex topLeft, QModelIndex bottomRight)
+    \li bool \b{contains}(QModelIndex index)
+    \li void \b{merge}(QItemSelection other, QItemSelectionModel::SelectionFlags command)
+    \endlist
+
+    \sa ItemSelectionModel
+*/
diff --git a/src/qml/types/qqmlmodelindexvaluetype.cpp b/src/qml/types/qqmlmodelindexvaluetype.cpp
new file mode 100644
index 0000000000..03ae05b4b5
--- /dev/null
+++ b/src/qml/types/qqmlmodelindexvaluetype.cpp
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the QtQml module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL21$
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** As a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qqmlmodelindexvaluetype_p.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \internal
+*/
+QString QQmlModelIndexValueType::propertiesString(const QModelIndex &idx)
+{
+    if (!idx.isValid())
+        return QLatin1String("()");
+    return QString(QLatin1String("(%1,%2,0x%3,%4(0x%5))"))
+            .arg(idx.row()).arg(idx.column()).arg(idx.internalId(), 0, 16)
+            .arg(idx.model()->metaObject()->className()).arg(quintptr(idx.model()), 0, 16);
+}
+
+/*!
+    \internal
+*/
+QString QQmlItemSelectionRangeValueType::toString() const
+{
+    return QString(QLatin1String("QItemSelectionRange(%1,%2)"))
+            .arg(reinterpret_cast<const QQmlPersistentModelIndexValueType *>(&v.topLeft())->toString())
+            .arg(reinterpret_cast<const QQmlPersistentModelIndexValueType *>(&v.bottomRight())->toString());
+}
+
+QT_END_NAMESPACE
diff --git a/src/qml/types/qqmlmodelindexvaluetype_p.h b/src/qml/types/qqmlmodelindexvaluetype_p.h
new file mode 100644
index 0000000000..0e655ab3d7
--- /dev/null
+++ b/src/qml/types/qqmlmodelindexvaluetype_p.h
@@ -0,0 +1,215 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the QtQml module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL21$
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** As a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QQMLMODELINDEXVALUETYPE_P_H
+#define QQMLMODELINDEXVALUETYPE_P_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists purely as an
+// implementation detail.  This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
+#include <QtCore/qabstractitemmodel.h>
+#include <QtCore/qitemselectionmodel.h>
+
+QT_BEGIN_NAMESPACE
+
+struct QQmlModelIndexValueType
+{
+    QModelIndex v;
+
+    Q_PROPERTY(int row READ row CONSTANT FINAL)
+    Q_PROPERTY(int column READ column CONSTANT FINAL)
+    Q_PROPERTY(QModelIndex parent READ parent FINAL)
+    Q_PROPERTY(bool valid READ isValid CONSTANT FINAL)
+    Q_PROPERTY(QAbstractItemModel *model READ model CONSTANT FINAL)
+    Q_PROPERTY(quint64 internalId READ internalId CONSTANT FINAL)
+    Q_GADGET
+
+public:
+    Q_INVOKABLE QString toString() const
+    { return QLatin1String("QModelIndex") + propertiesString(v); }
+
+    inline int row() const Q_DECL_NOTHROW { return v.row(); }
+    inline int column() const Q_DECL_NOTHROW { return v.column(); }
+    inline QModelIndex parent() const { return v.parent(); }
+    inline bool isValid() const Q_DECL_NOTHROW { return v.isValid(); }
+    inline QAbstractItemModel *model() const Q_DECL_NOTHROW
+    { return const_cast<QAbstractItemModel *>(v.model()); }
+    quint64 internalId() const { return v.internalId(); }
+
+    static QString propertiesString(const QModelIndex &idx);
+
+    static QPersistentModelIndex toPersistentModelIndex(const QModelIndex &index)
+    { return QPersistentModelIndex(index); }
+};
+
+struct QQmlPersistentModelIndexValueType
+{
+    QPersistentModelIndex v;
+
+    Q_PROPERTY(int row READ row FINAL)
+    Q_PROPERTY(int column READ column FINAL)
+    Q_PROPERTY(QModelIndex parent READ parent FINAL)
+    Q_PROPERTY(bool valid READ isValid FINAL)
+    Q_PROPERTY(QAbstractItemModel *model READ model FINAL)
+    Q_PROPERTY(quint64 internalId READ internalId FINAL)
+    Q_GADGET
+
+public:
+    Q_INVOKABLE QString toString() const
+    { return QLatin1String("QPersistentModelIndex") + QQmlModelIndexValueType::propertiesString(v); }
+
+    inline int row() const { return v.row(); }
+    inline int column() const { return v.column(); }
+    inline QModelIndex parent() const { return v.parent(); }
+    inline bool isValid() const { return v.isValid(); }
+    inline QAbstractItemModel *model() const { return const_cast<QAbstractItemModel *>(v.model()); }
+    inline quint64 internalId() const { return v.internalId(); }
+
+    static const QModelIndex &toModelIndex(const QPersistentModelIndex &index)
+    { return index; }
+};
+
+struct QQmlItemSelectionRangeValueType
+{
+    QItemSelectionRange v;
+
+    Q_PROPERTY(int top READ top FINAL)
+    Q_PROPERTY(int left READ left FINAL)
+    Q_PROPERTY(int bottom READ bottom FINAL)
+    Q_PROPERTY(int right READ right FINAL)
+    Q_PROPERTY(int width READ width FINAL)
+    Q_PROPERTY(int height READ height FINAL)
+    Q_PROPERTY(QPersistentModelIndex topLeft READ topLeft FINAL)
+    Q_PROPERTY(QPersistentModelIndex bottomRight READ bottomRight FINAL)
+    Q_PROPERTY(QModelIndex parent READ parent FINAL)
+    Q_PROPERTY(bool valid READ isValid FINAL)
+    Q_PROPERTY(bool empty READ isEmpty FINAL)
+    Q_PROPERTY(QAbstractItemModel *model READ model FINAL)
+    Q_GADGET
+
+public:
+    Q_INVOKABLE QString toString() const;
+    Q_INVOKABLE inline bool contains(const QModelIndex &index) const
+    { return v.contains(index); }
+    Q_INVOKABLE inline bool contains(int row, int column, const QModelIndex &parentIndex) const
+    { return v.contains(row, column, parentIndex); }
+    Q_INVOKABLE inline bool intersects(const QItemSelectionRange &other) const
+    { return v.intersects(other); }
+    Q_INVOKABLE QItemSelectionRange intersected(const QItemSelectionRange &other) const
+    { return v.intersected(other); }
+
+    inline int top() const { return v.top(); }
+    inline int left() const { return v.left(); }
+    inline int bottom() const { return v.bottom(); }
+    inline int right() const { return v.right(); }
+    inline int width() const { return v.width(); }
+    inline int height() const { return v.height(); }
+    inline QPersistentModelIndex &topLeft() const { return const_cast<QPersistentModelIndex &>(v.topLeft()); }
+    inline QPersistentModelIndex &bottomRight() const { return const_cast<QPersistentModelIndex &>(v.bottomRight()); }
+    inline QModelIndex parent() const { return v.parent(); }
+    inline QAbstractItemModel *model() const { return const_cast<QAbstractItemModel *>(v.model()); }
+    inline bool isValid() const { return v.isValid(); }
+    inline bool isEmpty() const { return v.isEmpty(); }
+};
+
+template<typename V, typename T>
+QString q_listToString(const QList<T> &list, const QLatin1String &typeName)
+{
+    QString result = typeName;
+    result.append(QLatin1Char('('));
+    for (typename QList<T>::size_type i = 0; i < list.count(); ++i) {
+        if (i)
+            result.append(QLatin1String(", "));
+        result.append(reinterpret_cast<const V *>(&list.at(i))->toString());
+    }
+    return result.append(QLatin1Char(')'));
+}
+
+// Invokable QList<T> API forwarding for value types
+#define QLISTVALUETYPE_QML_API(T) \
+    Q_PROPERTY(int length READ length FINAL) \
+    Q_INVOKABLE T at(int i) { return v.at(i); } \
+    Q_INVOKABLE void append(const T &o) { v.append(o); } \
+    Q_INVOKABLE void prepend(const T &o) { v.prepend(o); } \
+    Q_INVOKABLE void insert(int i, const T &o) { v.insert(i, o); } \
+    Q_INVOKABLE void removeFirst() { v.removeFirst(); } \
+    Q_INVOKABLE void removeLast() { v.removeLast(); } \
+    Q_INVOKABLE void removeAt(int i) { v.removeAt(i); } \
+    int length() const { return v.length(); }
+
+struct QQmlModelIndexListValueType
+{
+    QModelIndexList v;
+
+    Q_GADGET
+
+public:
+    Q_INVOKABLE QString toString()
+    { return q_listToString<QQmlModelIndexValueType>(v, QLatin1String("")); }
+
+    QLISTVALUETYPE_QML_API(QModelIndex)
+};
+
+struct QQmlItemSelectionValueType
+{
+    QItemSelection v;
+
+    Q_GADGET
+
+public:
+    Q_INVOKABLE QString toString()
+    { return q_listToString<QQmlItemSelectionRangeValueType>(v, QLatin1String("QItemSelection")); }
+    Q_INVOKABLE void select(const QModelIndex &topLeft, const QModelIndex &bottomRight)
+    { v.select(topLeft, bottomRight); }
+    Q_INVOKABLE bool contains(const QModelIndex &index) const
+    { return v.contains(index); }
+    Q_INVOKABLE void merge(const QItemSelection &other, int command)
+    { v.merge(other, QItemSelectionModel::SelectionFlags(command)); }
+
+    QLISTVALUETYPE_QML_API(QItemSelectionRange)
+};
+
+#undef QLISTVALUETYPE_INVOKABLE_API
+
+QT_END_NAMESPACE
+
+#endif // QQMLMODELINDEXVALUETYPE_P_H
+
diff --git a/src/qml/types/types.pri b/src/qml/types/types.pri
index 3e6153759d..d2e5020738 100644
--- a/src/qml/types/types.pri
+++ b/src/qml/types/types.pri
@@ -5,6 +5,7 @@ SOURCES += \
     $$PWD/qqmllistmodel.cpp \
     $$PWD/qqmllistmodelworkeragent.cpp \
     $$PWD/qqmlmodelsmodule.cpp \
+    $$PWD/qqmlmodelindexvaluetype.cpp \
     $$PWD/qqmlobjectmodel.cpp \
     $$PWD/qqmltimer.cpp \
     $$PWD/qquickpackage.cpp \
@@ -20,6 +21,7 @@ HEADERS += \
     $$PWD/qqmllistmodel_p_p.h \
     $$PWD/qqmllistmodelworkeragent_p.h \
     $$PWD/qqmlmodelsmodule_p.h \
+    $$PWD/qqmlmodelindexvaluetype_p.h \
     $$PWD/qqmlobjectmodel_p.h \
     $$PWD/qqmltimer_p.h \
     $$PWD/qquickpackage_p.h \