Merge branch 'master' into contiguouscache

6 files changed, 289 insertions, 23 deletions

diff --git a/doc/src/examples/collidingmice-example.qdoc b/doc/src/examples/collidingmice-example.qdoc
index 7ea2ca2..657a204 100644
--- a/doc/src/examples/collidingmice-example.qdoc
+++ b/doc/src/examples/collidingmice-example.qdoc
@@ -66,7 +66,7 @@
 
     \section1 Mouse Class Definition
 
-    The \c mouse class inherits both QObject and QGraphicsItem. The
+    The \c mouse class inherits from QGraphicsItem. The
     QGraphicsItem class is the base class for all graphical items in
     the Graphics View framework, and provides a light-weight
     foundation for writing your own custom items.
@@ -78,14 +78,11 @@
     {QGraphicsItem::}{boundingRect()}, which returns an estimate of
     the area painted by the item, and \l {QGraphicsItem::}{paint()},
     which implements the actual painting. In addition, we reimplement
-    the \l {QGraphicsItem::}{shape()} function to return an accurate
+    the \l {QGraphicsItem::}{shape()} and \l {QGraphicsItem::}{advance()}.
+    We reimplement \l {QGraphicsItem::}{shape()} to return an accurate
     shape of our mouse item; the default implementation simply returns
-    the item's bounding rectangle.
-
-    The rationale for deriving from QObject in addition to
-    QGraphicsItem is to be able to animate our items by reimplementing
-    QObject's \l {QObject::}{timerEvent()} function and use
-    QObject::startTimer() to generate timer events.
+    the item's bounding rectangle. We reimplement \l {QGraphicsItem::}{advance()}
+    to handle the animation so it all happens on one update.
 
     \section1 Mouse Class Definition
 
@@ -105,19 +102,18 @@
     calling the item's \l {QGraphicsItem::rotate()}{rotate()} function
     we alter the direction in which the mouse will start moving.
 
-    In the end we call QObject's \l {QObject::}{startTimer()}
-    function, emitting a timer event every 1000/33 millisecond. This
-    enables us to animate our mouse item using our reimplementation of
-    the \l {QObject::}{timerEvent()} function; whenever a mouse
-    receives a timer event it will trigger \l
-    {QObject::}{timerEvent()}:
-
+	When the QGraphicsScene decides to advance the scene a frame it will call 
+	QGraphicsItem::advance() on each of the items. This enables us to animate
+	our mouse using our reimplementation of the advance() function.
+	
     \snippet examples/graphicsview/collidingmice/mouse.cpp 4
     \snippet examples/graphicsview/collidingmice/mouse.cpp 5
     \snippet examples/graphicsview/collidingmice/mouse.cpp 6
 
-    First we ensure that the mice stays within a circle with a radius
-    of 150 pixels.
+    First, we don't bother doing any advance if the step is 0 since we want to our advance in 
+	the actual advance (advance() is called twice, once with step == 0 indicating that items 
+	are about to advance and with step == 1 for the actual advance). We also ensure that the 
+	mice stays within a circle with a radius of 150 pixels.
 
     Note the \l {QGraphicsItem::mapFromScene()}{mapFromScene()}
     function provided by QGraphicsItem. This function maps a position
@@ -275,5 +271,12 @@
     In the end, we set the application window's title and size before
     we enter the main event loop using the QApplication::exec()
     function.
-*/
 
+	Finally, we create a QTimer and connect its timeout() signal to the advance()
+	slot of the scene. Every time the timer fires, the scene will advance one frame.
+	We then tell the timer to fire every 1000/33 millisecond. This will 
+	give us a frame rate of 30 frames a second, which is fast enough for most animations. 
+	Doing the animation with a single timer connect to advance the scene ensures that all the 
+	mice are moved at one point and, more importantly, only one update is sent to the screen 
+	after all the mice have moved.
+*/
\ No newline at end of file
diff --git a/doc/src/examples/fancybrowser.qdoc b/doc/src/examples/fancybrowser.qdoc
new file mode 100644
index 0000000..9001c20
--- /dev/null
+++ b/doc/src/examples/fancybrowser.qdoc
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** 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 webkit/fancybrowser
+    \title Fancy Browser Example
+
+    The Fancy Browser example shows how to use jQuery with QtWebKit to
+    make a web browser with some special effects and content manipulation.
+
+    \image fancybrowser-example.png
+
+*/
diff --git a/doc/src/examples/flowlayout.qdoc b/doc/src/examples/flowlayout.qdoc
index 557ba39..3e7ec22 100644
--- a/doc/src/examples/flowlayout.qdoc
+++ b/doc/src/examples/flowlayout.qdoc
@@ -43,8 +43,117 @@
     \example layouts/flowlayout
     \title Flow Layout Example
 
-    The Flow Layout example demonstrates a custom layout that arranges child widgets from
-    left to right and top to bottom in a top-level widget.
+    The Flow Layout example demonstrates a custom layout that arranges child 
+    widgets from left to right and top to bottom in a top-level widget.
+
+    \image flowlayout-example.png Screenshot of the Flow Layout example
+
+    The items are first laid out horizontally and then vertically when each line
+    in the layout runs out of space. 
+
+	The Flowlayout class mainly uses QLayout and QWidgetItem, while the
+	Window uses QWidget and QLabel. We will only document the definition 
+	and implementation of \c FlowLayout below.
+
+    \section1 FlowLayout Class Definition
+    
+    The \c FlowLayout class inherits QLayout. It is a custom layout class 
+    that arranges its child widgets horizontally and vertically. 
+
+    \snippet examples/layouts/flowlayout/flowlayout.h 0
+
+    We reimplement functions inherited from QLayout. These functions add items to
+    the layout and handle their orientation and geometry. 
+    
+    We also declare two private methods, \c doLayout() and \c smartSpacing().
+    \c doLayout() lays out the layout items, while the \c
+    smartSpacing() function calculates the spacing between them.
+
+    \section1 FlowLayout Class Implementation 
+
+    We start off by looking at the constructor:
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 1
+
+    In the constructor we call \c setContentsMargins() to set the left, top,
+    right and bottom margin. By default, QLayout uses values provided by
+    the current style (see QStyle::PixelMetric). 
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 2
+
+    In this example we reimplement \c addItem(), which is a pure virtual 
+    function. When using \c addItem() the ownership of the layout items is 
+    transferred to the layout, and it is therefore the layout's 
+    responsibility to delete them. 
+    
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 3
+    
+    \c addItem() is implemented to add items to the layout. 
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 4
+
+    We implement \c horizontalSpacing() and \c verticalSpacing() to get
+    hold of the spacing between the widgets inside the layout. If the value 
+    is less than or equal to 0, this value will be used. If not, 
+    \c smartSpacing() will be called to calculate the spacing.
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 5
+    
+    We then implement \c count() to return the number of items in the 
+    layout. To navigate the list of items we use \c itemAt() and 
+    takeAt() to remove and return items from the list. If an item is 
+    removed, the remaining items will be renumbered. All three 
+    functions are pure virtual functions from QLayout.
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 6
+
+    \c expandingDirections() returns the \l{Qt::Orientation}s in which the
+    layout can make use of more space than its \c sizeHint().
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 7
+
+    To adjust to widgets of which height is dependent on width, we implement \c
+    heightForWidth(). The function \c hasHeightForWidth() is used to test for this
+    dependency, and \c heightForWidth() passes the width on to \c doLayout() which
+    in turn uses the width as an argument for the layout rect, i.e., the bounds in
+    which the items are laid out. This rect does not include the layout margin().
+    
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 8
+
+    \c setGeometry() is normally used to do the actual layout, i.e., calculate
+    the geometry of the layout's items. In this example, it calls \c doLayout()
+    and passes the layout rect.
+
+    \c sizeHint() returns the preferred size of the layout and \c minimumSize()
+    returns the minimum size of the layout.
+
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 9
+
+    \c doLayout() handles the layout if \c horizontalSpacing() or \c
+    verticalSpacing() don't return the default value. It uses 
+    \c getContentsMargins() to calculate the area available to the 
+    layout items. 
+ 
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 10
+
+	It then sets the proper amount of spacing for each widget in the 
+	layout, based on the current style. 
+	
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 11
+
+	The position of each item in the layout is then calculated by 
+	adding the items width and the line height to the initial x and y 
+	coordinates. This in turn lets us find out whether the next item 
+	will fit on the current line or if it must be moved down to the next. 
+	We also find the height of the current line based on the widgets height. 
+	
+    \snippet examples/layouts/flowlayout/flowlayout.cpp 12
+
+	\c smartSpacing() is designed to get the default spacing for either 
+	the top-level layouts or the sublayouts. The default spacing for 
+	top-level layouts, when the parent is a QWidget, will be determined 
+	by querying the style. The default spacing for sublayouts, when 
+	the parent is a QLayout, will be determined by querying the spacing 
+	of the parent layout.
 
-    \image flowlayout-example.png
 */
diff --git a/doc/src/examples/googlechat.qdoc b/doc/src/examples/googlechat.qdoc
new file mode 100644
index 0000000..f2d61cf
--- /dev/null
+++ b/doc/src/examples/googlechat.qdoc
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** 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 webkit/googlechat
+    \title Google Chat Example
+
+    The Google Chat example shows how to use implement a simple Google Chat
+    client with QtWebKit.
+
+    \image googlechat-example.png
+
+*/
diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc
new file mode 100644
index 0000000..a9b09f9
--- /dev/null
+++ b/doc/src/examples/googlesuggest.qdoc
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** 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 network/googlesuggest
+    \title Google Suggest Example
+
+    The Google Suggest example shows how to use the network access manager
+    to get the list of suggested search terms from Google.
+
+    \image googlesuggest-example.png
+
+*/
diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc
index 7059043..fb3a1c1 100644
--- a/doc/src/examples/qxmlstreambookmarks.qdoc
+++ b/doc/src/examples/qxmlstreambookmarks.qdoc
@@ -103,8 +103,9 @@
 
     The \c read() function accepts a QIODevice and sets it using
     \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process
-    of reading only takes place in event the file is a valid XBEL 1.0
-    file. Otherwise, the \l{QXmlStreamReader::raiseError()}
+    of reading only takes place if the file is a valid XBEL 1.0 file. 
+    Note that the XML input needs to be well-formed to be accepted by 
+    QXmlStreamReader. Otherwise, the \l{QXmlStreamReader::raiseError()}
     {raiseError()} function is used to display an error message.
 
     \snippet examples/xml/streambookmarks/xbelreader.cpp 1