diff options
author | Gabriel de Dietrich <gabriel.dedietrich@theqtcompany.com> | 2015-01-15 19:46:56 +0100 |
---|---|---|
committer | Caroline Chao <caroline.chao@theqtcompany.com> | 2015-02-12 11:10:04 +0000 |
commit | 005931905af62fb354c012594f9420d0acabbee3 (patch) | |
tree | 400f3a3c34bf6c47f579199655575b0d2517aa98 /src/qml/types | |
parent | c5796292adf7cb7f2ce6f95fb83a9da89ecaa730 (diff) |
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>
Diffstat (limited to 'src/qml/types')
-rw-r--r-- | src/qml/types/qqmlitemmodels.qdoc | 115 | ||||
-rw-r--r-- | src/qml/types/qqmlmodelindexvaluetype.cpp | 60 | ||||
-rw-r--r-- | src/qml/types/qqmlmodelindexvaluetype_p.h | 215 | ||||
-rw-r--r-- | src/qml/types/types.pri | 2 |
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 \ |