diff options
Diffstat (limited to 'examples/widgets/doc/src/fetchmore.qdoc')
-rw-r--r-- | examples/widgets/doc/src/fetchmore.qdoc | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/examples/widgets/doc/src/fetchmore.qdoc b/examples/widgets/doc/src/fetchmore.qdoc new file mode 100644 index 0000000000..7ea0b30edf --- /dev/null +++ b/examples/widgets/doc/src/fetchmore.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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$ +** +****************************************************************************/ + +/*! + \example itemviews/fetchmore + \title Fetch More Example + + The Fetch More example shows how two add items to an item view + model on demand. + + \image fetchmore-example.png + + The user of the example can enter a directory in the \uicontrol + Directory line edit. The contents of the directory will + be listed in the list view below. + + When you have large - or perhaps even infinite - data sets, you + will need to add items to the model in batches, and preferably only + when the items are needed by the view (i.e., when they are visible + in the view). + + In this example, we implement \c FileListModel - an item view + model containing the entries of a directory. We also have \c + Window, which sets up the GUI and feeds the model with + directories. + + Let's take a tour of \c {FileListModel}'s code. + + \section1 FileListModel Class Definition + + The \c FileListModel inherits QAbstractListModel and contains the + contents of a directory. It will add items to itself only when + requested to do so by the view. + + \snippet itemviews/fetchmore/filelistmodel.h 0 + + The secret lies in the reimplementation of + \l{QAbstractItemModel::}{fetchMore()} and + \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel. + These functions are called by the item view when it needs more + items. + + The \c setDirPath() function sets the directory the model will + work on. We emit \c numberPopulated() each time we add a batch of + items to the model. + + We keep all directory entries in \c fileList. \c fileCount is the + number of items that have been added to the model. + + \section1 FileListModel Class Implementation + + We start by checking out the \c setDirPath(). + + \snippet itemviews/fetchmore/filelistmodel.cpp 0 + + We use a QDir to get the contents of the directory. We need to + inform QAbstractItemModel that we want to remove all items - if + any - from the model. + + \snippet itemviews/fetchmore/filelistmodel.cpp 1 + + The \c canFetchMore() function is called by the view when it needs + more items. We return true if there still are entries that we have + not added to the model; otherwise, we return false. + + And now, the \c fetchMore() function itself: + + \snippet itemviews/fetchmore/filelistmodel.cpp 2 + + We first calculate the number of items to fetch. + \l{QAbstractItemModel::}{beginInsertRows()} and + \l{QAbstractItemModel::}{endInsertRows()} are mandatory for + QAbstractItemModel to keep up with the row insertions. Finally, we + emit \c numberPopulated(), which is picked up by \c Window. + + To complete the tour, we also look at \c rowCount() and \c data(). + + \snippet itemviews/fetchmore/filelistmodel.cpp 4 + + Notice that the row count is only the items we have added so far, + i.e., not the number of entries in the directory. + + In \c data(), we return the appropriate entry from the \c + fileList. We also separate the batches with a different background + color. +*/ + |