1 files changed, 70 insertions, 0 deletions
diff --git a/doc/src/examples/offsetvector.qdoc b/doc/src/examples/offsetvector.qdoc
new file mode 100644
index 0000000..256569e
--- /dev/null
+++ b/doc/src/examples/offsetvector.qdoc
@@ -0,0 +1,70 @@
+/****************************************************************************
+**
+** 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/offsetvector
+    \title Offset Vector Example
+
+    The Offset Vector example shows how to use QOffsetVector 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 QOffsetVector 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 QOffsetVector 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/offsetvector/randomlistmodel.cpp 0
+
+    After getting the row the class determines if the row is in the bounds
+    of the offset vector'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, and
+    the above code would cause every row between where the cache was last centered
+    to where the cache is currently centered to be cached before the requested
+    row is reached.
+
+    Using QOffsetVector::lastIndex() and QOffsetVector::firstIndex() allows
+    the example to determine where the list the vector is currently over.  These values
+    don't represent the indexes into the vector own memory, but rather a virtual
+    infinite array that the vector represents.
+
+    By using QOffsetVector::append() and QOffsetVector::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 vector range.  QOffsetVector::insert() can
+    potentially remove more than one item from the cache as QOffsetVector 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/offsetvector/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 vector range.
+*/