1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** 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 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\title FolderListModel - a C++ model plugin
\example src/imports/folderlistmodel
This plugin shows how to make a C++ model available to QML. It presents
a simple file list for a single folder (directory) and allows the presented
folder to be changed.
\image declarative-folderlistmodel.png The FolderListModel used to choose a QML file
We do not explain the model implementation in detail, but rather focus on the mechanics of
making the model available to QML.
\section1 Usage from QML
The type we are creating can be used from QML like this:
\snippet doc/src/snippets/declarative/folderlistmodel.qml 0
\section1 Defining the Model
We are subclassing QAbstractListModel which will allow us to give data to QML and
send notifications when the data changes:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class begin
As you see, we also inherit the QDeclarativeParserStatus interface, so that we
can delay initial processing until we have all properties set (via componentComplete() below).
The first thing to do when devising a new type for QML is to define the properties
you want the type to have:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class props
The purposes of each of these should be pretty obvious - in QML we will set the folder
to display (a file: URL), and the kinds of files we want to show in the view of the model.
Next are the constructor, destructor, and standard QAbstractListModel subclassing requirements:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h abslistmodel
The data() function is where we provide model values. The rowCount() function
is also a standard part of the QAbstractListModel interface, but we also want to provide
a simpler count property:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h count
Then we have the functions for the remaining properties which we defined above:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h prop funcs
Imperative actions upon the model are made available to QML via a Q_INVOKABLE tag on
a normal member function. The isFolder(index) function says whether the value at \e index
is a folder:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h isfolder
Then we have the QDeclarativeParserStatus interface:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h parserstatus
Then the NOTIFY function for the folders property. The implementation will emit this
when the folder property is changed.
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h notifier
The class ends with some implementation details:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class end
Lastly, the boilerplare to declare the type for QML use:
\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h qml decl
\section1 Connecting the Model to QML
To make this class available to QML, we only need to make a simple subclass of QDeclarativeExtensionPlugin:
\snippet src/imports/folderlistmodel/plugin.cpp class decl
and then use the standard Qt plugin export macro:
\snippet src/imports/folderlistmodel/plugin.cpp plugin export decl
Finally, in order for QML to connect the "import" statement to our plugin, we list it in the qmldir file:
\l{src/imports/folderlistmodel/qmldir}
This qmldir file and the compiled plugin will be installed in \c $QTDIR/imports/Qt/labs/folderlistmodel/ where
the QML engine will find it (since \c $QTDIR/imports is the value of QLibraryInf::libraryPath()).
\section1 Implementing the Model
We'll not discuss the model implementation in detail, as it is not specific to QML - any Qt C++ model
can be interfaced to QML.
This implementation is basically just takes the krufty old QDirModel,
which is a tree with lots of detailed roles and re-presents it as a simpler list model where
each item is just a fileName and a filePath (as a file: URL rather than a plain file, since QML
works with URLs for all content).
\l{src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp}
*/
|
