doc/src/examples/qml-folderlistmodel.qdoc

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