1 files changed, 83 insertions, 0 deletions
diff --git a/examples/tools/doc/contiguouscache.qdoc b/examples/tools/doc/contiguouscache.qdoc
new file mode 100644
index 0000000000..f906c7a07f
--- /dev/null
+++ b/examples/tools/doc/contiguouscache.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** 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 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.
+*/