Rename OffsetVector to ContiguousCache

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/src/examples/contiguouscache.qdoc b/doc/src/examples/contiguouscache.qdoc
new file mode 100644
index 0000000000..22c97fa7e9
--- /dev/null
+++ b/doc/src/examples/contiguouscache.qdoc
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the $MODULE$ of the Qt Toolkit.
+**
+** $TROLLTECH_DUAL_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_words.lastIndex())
+        m_words.append(fetchWord(m_words.lastIndex()+1);
+    while (row < m_words.firstIndex())
+        m_words.prepend(fetchWord(m_words.firstIndex()-1);
+    \endcode
+
+    However a list will often jump rows if the scroll bar is used directly, resulting in
+    the code above to cause every row between where the cache was last centered
+    to the requested row to be fetched before the requested row is fetched.
+
+    Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows
+    the example to determine where in the list the cache is currently over.  These values
+    don't represent the indexes into the cache 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 cache:
+
+    \snippet examples/tools/contiguouscache/randomlistmodel.cpp 1
+
+    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.
+
+    It is also worth considering pre-fetching items into the cache outside of the
+    applications paint routine.  This can be done either with a separate thread
+    or using a QTimer to incrementally expand the range of the thread prior to
+    rows being requested out of the current cache range.
+*/