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
|
/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\title FolderListModel - a C++ model plugin
\example src/imports/folderlistmodel
\brief The FolderListModel plugin example 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 FolderListModel can be used from QML like this:
\snippet doc/src/snippets/declarative/folderlistmodel.qml 0
This displays a list of all subfolders and QML files in the current folder.
The FolderListModel \c folder property can be set to change the folder that
is currently displayed.
\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}
*/
|
