qt5base-lts/examples/tools/doc/contiguouscache.qdoc
Iikka Eklund be15856f61 Change copyrights from Nokia to Digia
Change copyrights and license headers from Nokia to Digia

Change-Id: If1cc974286d29fd01ec6c19dd4719a67f4c3f00e
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Reviewed-by: Sergio Ahumada <sergio.ahumada@digia.com>
2012-09-22 19:20:11 +02:00

84 lines
4.0 KiB
Plaintext

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example contiguouscache
\title Contiguous Cache Example
The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for
very large models. In some environments memory is limited and, even when it
isn't, users still dislike an application using excessive memory.
Using QContiguousCache to manage a list, rather than loading
the entire list into memory, allows the application to limit the amount
of memory it uses, regardless of the size of the data set it accesses
The simplest way to use QContiguousCache is to cache as items are requested. When
a view requests an item at row N it is also likely to ask for items at rows near
to N.
\snippet contiguouscache/randomlistmodel.cpp 0
After getting the row, the class determines if the row is in the bounds
of the contiguous cache's current range. It would have been equally valid to
simply have the following code instead.
\code
while (row > m_rows.lastIndex())
m_rows.append(fetchWord(m_rows.lastIndex()+1);
while (row < m_rows.firstIndex())
m_rows.prepend(fetchWord(m_rows.firstIndex()-1);
\endcode
However a list will often jump rows if the scroll bar is used directly, resulting in
the code above causing every row between the old and new rows to be fetched.
Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows
the example to determine what part of the list the cache is currently caching.
These values don't represent the indexes into the cache's own memory, but rather
a virtual infinite array that the cache represents.
By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures
that items that may be still on the screen are not lost when the requested row
has not moved far from the current cache range. QContiguousCache::insert() can
potentially remove more than one item from the cache as QContiguousCache does not
allow for gaps. If your cache needs to quickly jump back and forth between
rows with significant gaps between them consider using QCache instead.
And thats it. A perfectly reasonable cache, using minimal memory for a very large
list. In this case the accessor for getting the words into the cache
generates random information rather than fixed information. This allows you
to see how the cache range is kept for a local number of rows when running the
example.
\snippet contiguouscache/randomlistmodel.cpp 1
It is also worth considering pre-fetching items into the cache outside of the
application's paint routine. This can be done either with a separate thread
or using a QTimer to incrementally expand the range of the cache prior to
rows being requested out of the current cache range.
*/