doc/src/examples/fetchmore.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     \example itemviews/fetchmore
  30     \title Fetch More Example
  31
  32     \brief The Fetch More example shows how two add items to an item view
  33     model on demand.
  34
  35     \image fetchmore-example.png
  36
  37     The user of the example can enter a directory in the \gui
  38     Directory line edit. The contents of the directory will
  39     be listed in the list view below.
  40
  41     When you have large - or perhaps even infinite - data sets, you
  42     will need to add items to the model in batches, and preferably only
  43     when the items are needed by the view (i.e., when they are visible
  44     in the view).
  45
  46     In this example, we implement \c FileListModel - an item view
  47     model containing the entries of a directory. We also have \c
  48     Window, which sets up the GUI and feeds the model with
  49     directories.
  50
  51     Let's take a tour of \c {FileListModel}'s code.
  52
  53     \section1 FileListModel Class Definition
  54
  55     The \c FileListModel inherits QAbstractListModel and contains the
  56     contents of a directory. It will add items to itself only when
  57     requested to do so by the view.
  58
  59     \snippet examples/itemviews/fetchmore/filelistmodel.h 0
  60
  61     The secret lies in the reimplementation of
  62     \l{QAbstractItemModel::}{fetchMore()} and
  63     \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel.
  64     These functions are called by the item view when it needs more
  65     items.
  66
  67     The \c setDirPath() function sets the directory the model will
  68     work on. We emit \c numberPopulated() each time we add a batch of
  69     items to the model.
  70
  71     We keep all directory entries in \c fileList. \c fileCount is the
  72     number of items that have been added to the model.
  73
  74     \section1 FileListModel Class Implementation
  75
  76     We start by checking out the \c setDirPath().
  77
  78     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 0
  79
  80     We use a QDir to get the contents of the directory. We need to
  81     inform QAbstractItemModel that we want to remove all items - if
  82     any - from the model.
  83
  84     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 1
  85
  86     The \c canFetchMore() function is called by the view when it needs
  87     more items. We return true if there still are entries that we have
  88     not added to the model; otherwise, we return false.
  89
  90     And now, the \c fetchMore() function itself:
  91
  92     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 2
  93
  94     We first calculate the number of items to fetch.
  95     \l{QAbstractItemModel::}{beginInsertRows()} and
  96     \l{QAbstractItemModel::}{endInsertRows()} are mandatory for
  97     QAbstractItemModel to keep up with the row insertions. Finally, we
  98     emit \c numberPopulated(), which is picked up by \c Window.
  99
 100     To complete the tour, we also look at \c rowCount() and \c data().
 101
 102     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 4
 103
 104     Notice that the row count is only the items we have added so far,
 105     i.e., not the number of entries in the directory.
 106
 107     In \c data(), we return the appropriate entry from the \c
 108     fileList. We also separate the batches with a different background
 109     color.
 110 */
 111