QScroller merge, part 1

This merge consists of the actual kinetic scroller implementation, its
autotests plus a few examples.  QAbstractScrollArea and QAbstractItemView
have been extended to support the new scroll events.

The complete history is in
http://scm.dev.nokia.troll.no/projects/qt/repos/rgriebls-qt-flickgesture/logs/4.7-flickgesture

(part 2 is the QML Flickable replacement / part 3 is QWebView support)

Task-number: QTBUG-9054
Reviewed-by: Ralf Engels

1 files changed, 109 insertions, 0 deletions

diff --git a/doc/src/examples/wheel.qdoc b/doc/src/examples/wheel.qdoc
new file mode 100644
index 0000000..1ea85fc
--- /dev/null
+++ b/doc/src/examples/wheel.qdoc
@@ -0,0 +1,109 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 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$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
+**
+** 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 scroller/wheel
+    \title Wheel Scroller Example
+
+    The Wheel Scroller Example shows how to use QScroller, QScrollEvent
+    and QScrollPrepareEvent to implement smooth scrolling for a
+    custom Widget.
+
+    \section1 Basics
+
+    The QScroller class is the main part of the smooth scrolling
+    mechanism in Qt. It keeps track of the current scroll position and
+    speed and updates the object through events.
+    QScroller will get touch events via the QFlickGesture.
+    It will query the target object through a QScrollPrepareEvent for
+    the scroll area and other information.
+    QScroller will send QScrollEvents to inform the target object about
+    the current scroll position.
+    The target object (usually a QWidget or a QGraphicsObject) will
+    then need to update it's graphical representation to reflect the
+    new scroll position.
+
+    \section1 The Wheel Widget class
+
+    To demonstrate how to use the QScroller we implement a QWidget that
+    looks and works like the wheel of a slot machine.
+    The wheel can be started via touch events and will continue getting
+    slower.
+    Additionally the wheel should appear as if no border exists (which
+    would seem unnatural) and the scrolling should snap to center one
+    item.
+
+    In the widget we need to grab the QFlickGesture. The gesture itself
+    will setAcceptTouchEvents for us, so we don't need to do that here.
+
+    \snippet examples/scroller/wheel/wheelwidget.cpp 0
+
+    The widget will get gesture events but in addition we also will
+    get the events from QScroller.
+    We will need to accept the QScrollPrepareEvent to indicate that
+    a scrolling should really be started from the given position.
+
+    \snippet examples/scroller/wheel/wheelwidget.cpp 1
+
+    We should call all three set functions form QScrollPrepareEvent.
+
+    \list
+    \o \c setViewportSize to indicate our viewport size. Actually the
+     given code could be improved by giving our size minus the borders.
+    \o \c setMaxContentPos to indicate the maximum values for the scroll
+     position. The minimum values are implicitely set to 0.
+     In our example we give a very high number here and hope that the user
+     is not patient enough to scroll until the very end.
+    \o \c setContentPos to indicate the current scroll position.
+     We give a position in the middle of the huge scroll area.
+     Actually we give this position every time a new scroll is started so
+     the user will only reach the end if he continuously scrolls in one
+     direction which is not very likely.
+    \endlist
+
+    The handling of the QScrollEvent is a lengthly code not fully shown here.
+    \snippet examples/scroller/wheel/wheelwidget.cpp 2
+
+    In principle it does three steps.
+    \list
+    \o It calculates and updates the current scroll position as given by
+     QScroller.
+    \o It repaints the widget so that the new position is shown.
+    \o It centers the item as soon as the scrolling stopps.
+    \endlist
+
+    The following code does the centering.
+    \snippet examples/scroller/wheel/wheelwidget.cpp 3
+
+    We check if the scrolling is finished which is indicated in the
+    QScrollEvent by the \c isLast flag.
+    We then check if the item is not already centered and if not start a new
+    scroll by calling QScroller::scrollTo.
+
+    As you can see the QScroller can be used for other things besides simple
+    scroll areas.
+*/