From 351257e7553817ea77a7d2d9738456200fc08b68 Mon Sep 17 00:00:00 2001
From: Martin Jones <martin.jones@nokia.com>
Date: Wed, 5 Aug 2009 17:05:59 +1000
Subject: Document keepMouseFocus

---
 src/declarative/fx/qfxitem.cpp | 20 ++++++++++++++++++--
 src/declarative/fx/qfxitem.h   |  6 +++---
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/declarative/fx/qfxitem.cpp b/src/declarative/fx/qfxitem.cpp
index b081edc..3411f03 100644
--- a/src/declarative/fx/qfxitem.cpp
+++ b/src/declarative/fx/qfxitem.cpp
@@ -1281,8 +1281,10 @@ void QFxItem::setBaselineOffset(qreal offset)
 */
 
 /*!
-  Returns a value indicating whether the mouse should
-  remain with this item.
+  Returns a value indicating whether mouse input should
+  remain with this item exclusively.
+
+  \sa setKeepMouseGrab
  */
 bool QFxItem::keepMouseGrab() const
 {
@@ -1293,6 +1295,20 @@ bool QFxItem::keepMouseGrab() const
 /*!
   The flag indicating whether the mouse should remain
   with this item is set to \a keep.
+
+  This is useful for items that wish to grab and keep mouse
+  interaction following a predefined gesture.  For example,
+  an item that is interested in horizontal mouse movement
+  may set keepMouseGrab to true once a threshold has been
+  exceeded.  Once keepMouseGrab has been set to true, filtering
+  items will not react to mouse events.
+
+  If the item does not indicate that it wishes to retain mouse grab,
+  a filtering item may steal the grab. For example, Flickable may attempt
+  to steal a mouse grab if it detects that the user has begun to
+  move the viewport.
+
+  \sa keepMouseGrab
  */
 void QFxItem::setKeepMouseGrab(bool keep)
 {
diff --git a/src/declarative/fx/qfxitem.h b/src/declarative/fx/qfxitem.h
index 4a26c9b..82819ee 100644
--- a/src/declarative/fx/qfxitem.h
+++ b/src/declarative/fx/qfxitem.h
@@ -163,9 +163,6 @@ public:
 
     QmlList<QGraphicsTransform *> *transform();
 
-    bool keepMouseGrab() const;
-    void setKeepMouseGrab(bool);
-
     qreal width() const;
     void setWidth(qreal);
 
@@ -205,6 +202,9 @@ protected:
     virtual QVariant itemChange(GraphicsItemChange, const QVariant &);
     virtual void mouseUngrabEvent();
 
+    bool keepMouseGrab() const;
+    void setKeepMouseGrab(bool);
+
     void setImplicitWidth(qreal);
     bool widthValid() const; // ### better name?
     void setImplicitHeight(qreal);
-- 
cgit v0.12