1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qmodelindex-and-related-classes-in-qml.html
6 \title QModelIndex and related Classes in QML
8 Since Qt 5.5, QModelIndex and QPersistentModelIndex are exposed in QML as
9 value-based types. Also exposed in a similar fashion are QModelIndexList,
10 QItemSelectionRange and QItemSelection. All objects from these types can
11 be passed back and forth between QML and C++ as \c var properties or plain
14 Below you will find an overview of the API exposed to QML for these classes.
15 For more information, refer to their C++ documentation.
17 \note Since all these types are exposed as \l{Q_GADGET}{gadgets}, there are no property
18 change notification signals emitted. Therefore binding to their properties
19 may not give the expected results. This is especially true for QPersistentModelIndex.
21 \section1 QModelIndex and QPersistentModelIndex Types
26 \li \b parent : QModelIndex
28 \li \b model : QAbstractItemModel
29 \li \b internalId : quint64
32 All these properties are read-only, as are their C++ counterparts. In addition,
33 we also expose the following functions:
36 \li QVariant \b{data}(int \e role) (since Qt 6.7)
39 \note The usual caveats apply to QModelIndex in QML. If the underlying model changes
40 or gets deleted, it may become dangerous to access its properties. Therefore, you
41 should not store any QModelIndex objects. You can, however, store QPersistentModelIndexe
42 objects in a safe way.
44 \section1 QModelIndexList Type
46 QModelIndexList is exposed in QML as a JavaScript array. Conversions are
47 automatically made from and to C++. In fact, any JavaScript array can be
48 converted back to QModelIndexList, with non-QModelIndex objects replaced by
49 invalid \l{QModelIndex}es.
51 \note QModelIndex to QPersistentModelIndex conversion happens when accessing
52 the array elements because any QModelIndexList property retains reference
53 semantics when exposed this way.
55 \section1 \l QItemSelectionRange Type
64 \li \b topLeft : QPersistentModelIndex
65 \li \b bottomRight : QPersistentModelIndex
66 \li \b parent : QModelIndex
69 \li \b model : QAbstractItemModel
72 All these properties are read-only, as are their C++ counterparts. In addition,
73 we also expose the following functions:
76 \li bool \b{contains}(QModelIndex \e index)
77 \li bool \b{contains}(int \e row, int \e column, QModelIndex \e parentIndex)
78 \li bool \b{intersects}(QItemSelectionRange \e other)
79 \li QItemSelectionRange \b{intersected}(QItemSelectionRange \e other)
82 \section1 QItemSelection Type
84 Similarly to QModelIndexList, \l QItemSelection is exposed in QML as a JavaScript
85 array of QItemSelectionRange objects. Conversions are automatically made from and to C++.
86 In fact, any JavaScript array can be converted back to QItemSelection, with
87 non-QItemSelectionRange objects replaced by empty \l {QItemSelectionRange}s.
90 \sa ItemSelectionModel