Move model types into their own library

The model types are not part of the core QML runtime and should only be
loaded if you explicitly import them. We cannot enforce that in Qt5 as
some of them are available from the QtQml import, but we can change it
in Qt6.

Change-Id: I1e49e84d748e352537ec2d4af901c034c91d038f
Reviewed-by: Erik Verbruggen <erik.verbruggen@me.com>

1 files changed, 110 insertions, 0 deletions

diff --git a/src/qmlmodels/qqmlitemmodels.qdoc b/src/qmlmodels/qqmlitemmodels.qdoc
new file mode 100644
index 0000000000..f6e1b0b1b9
--- /dev/null
+++ b/src/qmlmodels/qqmlitemmodels.qdoc
@@ -0,0 +1,110 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://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 https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qmodelindex-and-related-classes-in-qml.html
+    \title QModelIndex and related Classes 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.
+
+    Below you will find an overview of the API exposed to QML for these classes.
+    For more information, refer to their C++ documentation.
+
+    \note Since all these types are exposed as \l{Q_GADGET}{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.
+
+    \section1 QModelIndex and QPersistentModelIndex Types
+
+    \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 are their C++ counterparts.
+
+    \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 objects. You can, however, store QPersistentModelIndexe
+    objects in a safe way.
+
+    \section1 QModelIndexList Type
+
+    \l QModelIndexList is exposed in QML as a JavaScript array. Conversions are
+    automatically made from and to C++. In fact, any JavaScript array can be
+    converted back to QModelIndexList, with non-QModelIndex objects replaced by
+    invalid \l{QModelIndex}es.
+
+    \note QModelIndex to QPersistentModelIndex conversion happens when accessing
+    the array elements because any QModelIndexList property retains reference
+    semantics when exposed this way.
+
+    \section1 \l QItemSelectionRange Type
+
+    \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 are their C++ counterparts. In addition,
+    we also expose the following functions:
+
+    \list
+    \li bool \b{contains}(QModelIndex \e index)
+    \li bool \b{contains}(int \e row, int \e column, QModelIndex \e parentIndex)
+    \li bool \b{intersects}(QItemSelectionRange \e other)
+    \li QItemSelectionRange \b{intersected}(QItemSelectionRange \e other)
+    \endlist
+
+    \section1 QItemSelection Type
+
+    Similarly to QModelIndexList, \l QItemSelection is exposed in QML as a JavaScript
+    array of QItemSelectionRange objects. Conversions are automatically made from and to C++.
+    In fact, any JavaScript array can be converted back to QItemSelection, with
+    non-QItemSelectionRange objects replaced by empty \l {QItemSelectionRange}s.
+
+
+    \sa ItemSelectionModel
+*/