Merge branch 'master' of git@scm.dev.nokia.troll.no:qt/qt

4 files changed, 131 insertions, 25 deletions

diff --git a/doc/src/examples/contiguouscache.qdoc b/doc/src/examples/contiguouscache.qdoc
new file mode 100644
index 0000000..fbfde3f
--- /dev/null
+++ b/doc/src/examples/contiguouscache.qdoc
@@ -0,0 +1,97 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/
diff --git a/doc/src/layout.qdoc b/doc/src/layout.qdoc
index 55dfd8b..196999b 100644
--- a/doc/src/layout.qdoc
+++ b/doc/src/layout.qdoc
@@ -315,7 +315,11 @@
 
     \snippet doc/src/snippets/code/doc_src_layout.qdoc 1
 
-    First we define two functions that iterate over the layout: \c{itemAt()}
+    First we define \c{count()} to fetch the number of items in the list.
+
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 2
+
+    Then we define two functions that iterate over the layout: \c{itemAt()}
     and \c{takeAt()}. These functions are used internally by the layout system
     to handle deletion of widgets. They are also available for application
     programmers. 
@@ -326,7 +330,7 @@
     structure, we may have to spend more effort defining a linear order for the
     items.
 
-    \snippet doc/src/snippets/code/doc_src_layout.qdoc 2
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 3
 
     \c{addItem()} implements the default placement strategy for layout items.
     This function must be implemented. It is used by QLayout::add(), by the
@@ -336,26 +340,26 @@
     QGridLayout::addItem(), QGridLayout::addWidget(), and
     QGridLayout::addLayout().
 
-    \snippet doc/src/snippets/code/doc_src_layout.qdoc 3
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 4
 
     The layout takes over responsibility of the items added. Since QLayoutItem
     does not inherit QObject, we must delete the items manually. The function
     QLayout::deleteAllItems() uses \c{takeAt()} defined above to delete all the
     items in the layout.
 
-    \snippet doc/src/snippets/code/doc_src_layout.qdoc 4
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 5
 
     The \c{setGeometry()} function actually performs the layout. The rectangle
     supplied as an argument does not include \c{margin()}. If relevant, use
     \c{spacing()} as the distance between items.
 
-    \snippet doc/src/snippets/code/doc_src_layout.qdoc 5
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 6
 
     \c{sizeHint()} and \c{minimumSize()} are normally very similar in
     implementation. The sizes returned by both functions should include
     \c{spacing()}, but not \c{margin()}.
 
-    \snippet doc/src/snippets/code/doc_src_layout.qdoc 6
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 7
 
 
     \section2 Further Notes
diff --git a/doc/src/snippets/code/doc_src_layout.qdoc b/doc/src/snippets/code/doc_src_layout.qdoc
index 48e10e9..fedcf0c 100644
--- a/doc/src/snippets/code/doc_src_layout.qdoc
+++ b/doc/src/snippets/code/doc_src_layout.qdoc
@@ -2,23 +2,21 @@
 #ifndef CARD_H
 #define CARD_H
 
-#include <QLayout>
+#include <QtGui>
 #include <QList>
 
 class CardLayout : public QLayout
 {
 public:
-    CardLayout(QWidget *parent, int dist)
-        : QLayout(parent, 0, dist) {}
-    CardLayout(QLayout *parent, int dist)
-        : QLayout(parent, dist) {}
-    CardLayout(int dist)
-        : QLayout(dist) {}
+    CardLayout(QWidget *parent, int dist): QLayout(parent, 0, dist) {}
+    CardLayout(QLayout *parent, int dist): QLayout(parent, dist) {}
+    CardLayout(int dist): QLayout(dist) {}
     ~CardLayout();
 
     void addItem(QLayoutItem *item);
     QSize sizeHint() const;
     QSize minimumSize() const;
+	QLayoutItem *count() const;
     QLayoutItem *itemAt(int) const;
     QLayoutItem *takeAt(int);
     void setGeometry(const QRect &rect);
@@ -31,11 +29,18 @@ private:
 
 
 //! [1]
-#include "card.h"
+//#include "card.h"
 //! [1]
 
-
 //! [2]
+QLayoutItem *CardLayout::count() const
+{
+	// QList::size() returns the number of QLayoutItems in the list
+    return list.size();
+}
+//! [2]
+
+//! [3]
 QLayoutItem *CardLayout::itemAt(int idx) const
 {
     // QList::value() performs index checking, and returns 0 if we are
@@ -48,26 +53,26 @@ QLayoutItem *CardLayout::takeAt(int idx)
     // QList::take does not do index checking
     return idx >= 0 && idx < list.size() ? list.takeAt(idx) : 0;
 }
-//! [2]
+//! [3]
 
 
-//! [3]
+//! [4]
 void CardLayout::addItem(QLayoutItem *item)
 {
     list.append(item);
 }
-//! [3]
+//! [4]
 
 
-//! [4]
+//! [5]
 CardLayout::~CardLayout()
 {
     deleteAllItems();
 }
-//! [4]
+//! [5]
 
 
-//! [5]
+//! [6]
 void CardLayout::setGeometry(const QRect &r)
 {
     QLayout::setGeometry(r);
@@ -85,10 +90,10 @@ void CardLayout::setGeometry(const QRect &r)
         ++i;
     }
 }
-//! [5]
+//! [6]
 
 
-//! [6]
+//! [7]
 QSize CardLayout::sizeHint() const
 {
     QSize s(0,0);
@@ -116,4 +121,4 @@ QSize CardLayout::minimumSize() const
     }
     return s + n*QSize(spacing(), spacing());
 }
-//! [6]
+//! [7]
\ No newline at end of file
diff --git a/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp b/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp
index c4b6353..2a04f64 100644
--- a/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp
+++ b/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp
@@ -13,7 +13,7 @@ painter->drawPixmap(0, 0, p);
 
 //! [1]
 QPixmap pm;
-if (!QPixmapCache::find("my_big_image", pm)) {
+if (!QPixmapCache::find("my_big_image", &pm)) {
     pm.load("bigimage.png");
     QPixmapCache::insert("my_big_image", pm);
 }