1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example itemviews/fetchmore

    44     \title Fetch More Example

    45 

    46     The Fetch More example shows how two add items to an item view

    47     model on demand.

    48 

    49     \image fetchmore-example.png

    50 

    51     The user of the example can enter a directory in the \gui

    52     Directory line edit. The contents of the directory will

    53     be listed in the list view below.

    54 

    55     When you have large - or perhaps even infinite - data sets, you

    56     will need to add items to the model in batches, and preferably only

    57     when the items are needed by the view (i.e., when they are visible

    58     in the view).

    59 

    60     In this example, we implement \c FileListModel - an item view

    61     model containing the entries of a directory. We also have \c

    62     Window, which sets up the GUI and feeds the model with

    63     directories.

    64 

    65     Let's take a tour of \c {FileListModel}'s code.

    66 

    67     \section1 FileListModel Class Definition

    68 

    69     The \c FileListModel inherits QAbstractListModel and contains the

    70     contents of a directory. It will add items to itself only when

    71     requested to do so by the view.

    72 

    73     \snippet examples/itemviews/fetchmore/filelistmodel.h 0

    74 

    75     The secret lies in the reimplementation of

    76     \l{QAbstractItemModel::}{fetchMore()} and

    77     \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel.

    78     These functions are called by the item view when it needs more

    79     items. 

    80 

    81     The \c setDirPath() function sets the directory the model will

    82     work on. We emit \c numberPopulated() each time we add a batch of

    83     items to the model.

    84 

    85     We keep all directory entries in \c fileList. \c fileCount is the

    86     number of items that have been added to the model.

    87 

    88     \section1 FileListModel Class Implementation

    89 

    90     We start by checking out the \c setDirPath().

    91 

    92     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 0

    93 

    94     We use a QDir to get the contents of the directory. We need to

    95     inform QAbstractItemModel that we want to remove all items - if

    96     any - from the model.

    97 

    98     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 1

    99 

   100     The \c canFetchMore() function is called by the view when it needs

   101     more items. We return true if there still are entries that we have

   102     not added to the model; otherwise, we return false.

   103 

   104     And now, the \c fetchMore() function itself:

   105 

   106     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 2

   107 

   108     We first calculate the number of items to fetch.

   109     \l{QAbstractItemModel::}{beginInsertRows()} and

   110     \l{QAbstractItemModel::}{endInsertRows()} are mandatory for

   111     QAbstractItemModel to keep up with the row insertions. Finally, we

   112     emit \c numberPopulated(), which is picked up by \c Window.

   113 

   114     To complete the tour, we also look at \c rowCount() and \c data().

   115 

   116     \snippet examples/itemviews/fetchmore/filelistmodel.cpp 4

   117 

   118     Notice that the row count is only the items we have added so far,

   119     i.e., not the number of entries in the directory.

   120 

   121     In \c data(), we return the appropriate entry from the \c

   122     fileList. We also separate the batches with a different background

   123     color.

   124 */

   125