1 files changed, 83 insertions, 0 deletions
diff --git a/doc/src/examples/contiguouscache.qdoc b/doc/src/examples/contiguouscache.qdoc
new file mode 100644
index 0000000000..2200b92e9a
--- /dev/null
+++ b/doc/src/examples/contiguouscache.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example tools/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 examples/tools/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 examples/tools/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.
+*/