--- a/src/hbcore/gestures/hbswipegesture.cpp	Fri Jun 11 13:58:22 2010 +0300
+++ b/src/hbcore/gestures/hbswipegesture.cpp	Wed Jun 23 18:33:25 2010 +0300
@@ -34,14 +34,86 @@
     @hbcore
     \class HbSwipeGesture
 
-    \brief HbSwipeGesture is an extension to Qt standard HbSwipeGesture
+    \brief The HbSwipeGesture class provides support for receiving a swipe
+    (flick) gesture.
+    
+    HbSwipeGesture is an extension to Qt standard QSwipeGesture. It is
+    optimized for mobile touch screens, and also supports recognition of
+    mouse events for development purposes. Moreover, HbSwipeGesture
+    has convenience functions for handling the QSwipeGesture properties
+    (horizontalDirection, verticalDirection, swipeAngle) directly in scene
+    coordinates. They remove the need for any manual conversions from the
+    screen (global) coordinates offered by the QSwipeGesture base class
+    properties.
+    
+    The swipe gesture is designed to be used as a single-shot gesture which
+    is activated after a flick and release. No events are sent until the
+    gesture is finished. Swipe should be used when feedback during the
+    gesture is not possible or desired.
+
+    \section _usecases_hbswipegesture Using the HbSwipeGesture class
+    
+    This example shows how to make a custom widget recognize the swipe
+    gesture. The custom widget in the example derives from HbWidget.
+    
+    <ol>
+    <li>
+    Register for swipe gestures by using the base class function
+    QGraphicsObject::grabGesture(). QGraphicsObject::grabGesture() can be
+    called several times with different arguments, if the widget is
+    interested in other gesture types as well.
+   
+    \code
+    // This widget is interested in swipe and tap gestures.
+    grabGesture(Qt::SwipeGesture);
+    grabGesture(Qt::TapGesture);
+    \endcode
+    </li>
+    
+    <li>
+    Reimplement HbWidgetBase::gestureEvent() to handle gestures that are
+    meaningful for your custom widget.
+   
+    \code
+    void MyWidget::gestureEvent(QGestureEvent *event)
+    {
+        if (HbSwipeGesture *swipe = qobject_cast<HbSwipeGesture *>
+            (event->gesture(Qt::SwipeGesture))) {
+       
+            switch (swipe->state()) {
+           
+            case Qt::GestureStarted: // fall-through
+            case Qt::GestureUpdated: // fall-through
+            case Qt::GestureCanceled:
+                break;
+            case Qt::GestureFinished:             
+                // Emit a signal to show the swipe movement.           
+                break;
+            default:
+                break;
+            }           
+        }
+       
+        // Handle other gesture types that have been grabbed. There may be
+        // several, since all gestures that are active at the same moment
+        // are sent within the same gesture event.
+        if (HbTapGesture *tap = qobject_cast<HbTapGesture *>
+            (event->gesture(Qt::TapGesture))) {
+            // handle the tap gesture
+        }
+       
+    }   
+    \endcode
+    </li>
+    </ol>
+        
     \sa QSwipeGesture
 */
 
 const int KHbDirectionThreshold = 45; // degrees
 
 /*!
-    \brief HbSwipeGesture constructor
+    Constructor.
     \param parent Owner for gesture
 */
 HbSwipeGesture::HbSwipeGesture(QObject *parent)
@@ -52,7 +124,7 @@
 }
 
 /*!
-    \brief HbSwipeGesture constructor
+    Constructor required by the shared d-pointer paradigm.
     \param dd Private data
     \param parent Owner for gesture
 */
@@ -63,7 +135,7 @@
 }
 
 /*!
-    \brief HbSwipeGesture destructor
+    Destructor.
 */
 HbSwipeGesture::~HbSwipeGesture()
 {
@@ -71,8 +143,8 @@
 }
 
 /*!
-    \property sceneHorizontalDirection
-    \brief Horizontal direction of swipe in scene coordinates.
+    Returns the horizontal direction of the swipe gesture
+    relative to scene coordinates.
 
     \sa QSwipeGesture::horizontalDirection()
 */
@@ -86,8 +158,8 @@
         return QSwipeGesture::NoDirection;
 }
 /*!
-    \property sceneVerticalDirection
-    \brief Vertical direction of swipe in scene coordinates.
+    Returns the vertical direction of the swipe gesture
+    relative to scene coordinates.
     \sa QSwipeGesture::verticalDirection()
 */
 QSwipeGesture::SwipeDirection HbSwipeGesture::sceneVerticalDirection() const
@@ -101,15 +173,21 @@
 }
 
 /*!
-    \property sceneSwipeAngle
-    \brief Angle for swipe in scene coordinates.
-    \sa QSwipeGesture::swipeAngle()
+    Returns the angle for the swipe gesture in degrees,
+    taking into account any scene transformations.
+    \sa setSceneSwipeAngle(), QSwipeGesture::swipeAngle()
 */
 qreal HbSwipeGesture::sceneSwipeAngle() const
 {
     return d_ptr->mSceneSwipeAngle;
 }
 
+/*!
+    Sets the angle for the swipe gesture.
+    This function is used by the framework gesture recognition logic,
+    and it should not be used by the widget receiving the gesture.
+    \sa sceneSwipeAngle(), QSwipeGesture::setSwipeAngle()
+*/
 void HbSwipeGesture::setSceneSwipeAngle(qreal value)
 {
     d_ptr->mSceneSwipeAngle = value;
@@ -118,7 +196,7 @@
 
 /*!
     \deprecated
-    \property speed
+    Returns the speed.
 */
 qreal HbSwipeGesture::speed() const
 {    
@@ -126,6 +204,10 @@
     return 1;
 }
 
+/*!
+    \deprecated
+    Sets the speed.
+*/
 void HbSwipeGesture::setSpeed(qreal speed)
 {
     Q_UNUSED (speed);
@@ -134,7 +216,7 @@
 
 /*!
     \deprecated
-    \property touchPointCount
+    Returns the touchPointCount.
 */
 int HbSwipeGesture::touchPointCount() const
 {
@@ -142,6 +224,10 @@
     return 0;
 }
 
+/*!
+    \deprecated
+    Sets the touchPointCount.
+*/
 void HbSwipeGesture::setTouchPointCount(int touchPointCount)
 {
     HB_DEPRECATED("HbSwipeGesture::setTouchPointCount is deprecated");