qt-everywhere-src-5.15.1/qtbase/examples/widgets/doc/src/fetchmore.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example itemviews/fetchmore
    \title Fetch More Example
    \ingroup examples-itemviews
    \brief The Fetch More example shows how to add items to an item view
    model on demand.

    \image fetchmore-example.png


    This example consists of a dialog where you can enter a directory
    name in the \uicontrol Directory edit field. The application loads and
    visualizes all files it finds as you are typing. It is not required
    to press [Enter] to launch the search.

    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.
*/