source: trunk/doc/src/examples/qml-folderlistmodel.qdoc

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** 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.
**
** 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}
*/