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>

1 files changed, 115 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
+*/