Add propagateComposedEvents property to MouseArea

While necessary, advanced event propagation isn't the common use case.
Now needs to be explicitly enabled.

Task-number: QTBUG-21081
Change-Id: Ibd8b4974934116dbfa32cc5e72037fd9b11015b4
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

3 files changed, 49 insertions, 6 deletions

diff --git a/src/declarative/items/qquickmousearea.cpp b/src/declarative/items/qquickmousearea.cpp
index 19e7fd457b..8d4f3e86b0 100644
--- a/src/declarative/items/qquickmousearea.cpp
+++ b/src/declarative/items/qquickmousearea.cpp
@@ -184,7 +184,7 @@ QQuickDragAttached *QQuickDrag::qmlAttachedProperties(QObject *obj)
 QQuickMouseAreaPrivate::QQuickMouseAreaPrivate()
 : absorb(true), hovered(false), pressed(false), longPress(false),
   moved(false), stealMouse(false), doubleClick(false), preventStealing(false),
-  drag(0)
+  propagateComposedEvents(false), drag(0)
 {
 }
 
@@ -233,6 +233,8 @@ bool QQuickMouseAreaPrivate::isClickConnected()
 void QQuickMouseAreaPrivate::propagate(QQuickMouseEvent* event, PropagateType t)
 {
     Q_Q(QQuickMouseArea);
+    if (!propagateComposedEvents)
+        return;
     QPointF scenePos = q->mapToScene(QPointF(event->x(), event->y()));
     propagateHelper(event, canvas->rootItem(), scenePos, t);
 }
@@ -357,14 +359,11 @@ bool QQuickMouseAreaPrivate::propagateHelper(QQuickMouseEvent *ev, QQuickItem *i
   Behavioral Change in QtQuick 2.0
 
   From QtQuick 2.0, the signals clicked, doubleClicked and pressAndHold have a different interaction
-  model with regards to the delivery of events to multiple overlapping MouseAreas. These signals will now propagate
+  model with regards to the delivery of events to multiple overlapping MouseAreas. These signals can now propagate
   to all MouseAreas in the area, in painting order, until accepted by one of them. A signal is accepted by
   default if there is a signal handler for it, use mouse.accepted = false; to ignore. This propagation
   can send the signal to MouseAreas other than the one which accepted the press event, although that MouseArea
-  will receive the signal first.
-
-  Note that to get the same behavior as a QtQuick 1.0 MouseArea{} with regard to absorbing all mouse events, you will
-  now need to add empty signal handlers for these three signals.
+  will receive the signal first. This behavior can be enabled by setting propagateComposedEvents to true.
 
     \sa MouseEvent, {declarative/touchinteraction/mousearea}{MouseArea example}
 */
@@ -603,6 +602,44 @@ void QQuickMouseArea::setPreventStealing(bool prevent)
     }
 }
 
+
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::propagateComposedEvents
+    This property holds whether composed mouse events will automatically propagate to
+    other MouseAreas.
+
+    MouseArea contains several composed events, clicked, doubleClicked,
+    and pressAndHold. These can propagate via a separate mechanism to basic
+    mouse events, like pressed, which they are composed of.
+
+    If propagateComposedEvents is set to true, then composed events will be automatically
+    propagated to other MouseAreas in the same location in the scene. They are propagated
+    in painting order until an item accepts them. Unlike pressed handling, events will
+    not be automatically accepted if no handler is present.
+
+    This property greatly simplifies the usecase of when you want to have overlapping MouseAreas
+    handling the composed events together. For example: if you want one MouseArea to handle click
+    signals and the other to handle pressAndHold, or if you want one MouseArea to handle click most
+    of the time, but pass it through when certain conditions are met.
+
+    By default this property is false.
+*/
+bool QQuickMouseArea::propagateComposedEvents() const
+{
+    Q_D(const QQuickMouseArea);
+    return d->propagateComposedEvents;
+}
+
+void QQuickMouseArea::setPropagateComposedEvents(bool prevent)
+{
+    Q_D(QQuickMouseArea);
+    if (prevent != d->propagateComposedEvents) {
+        d->propagateComposedEvents = prevent;
+        setKeepMouseGrab(d->propagateComposedEvents && d->absorb);
+        emit propagateComposedEventsChanged();
+    }
+}
+
 /*!
     \qmlproperty MouseButtons QtQuick2::MouseArea::pressedButtons
     This property holds the mouse buttons currently pressed.
diff --git a/src/declarative/items/qquickmousearea_p.h b/src/declarative/items/qquickmousearea_p.h
index 6f15ff6eb4..b8fa7d5ce8 100644
--- a/src/declarative/items/qquickmousearea_p.h
+++ b/src/declarative/items/qquickmousearea_p.h
@@ -137,6 +137,7 @@ class Q_DECLARATIVE_EXPORT QQuickMouseArea : public QQuickItem
     Q_PROPERTY(bool hoverEnabled READ hoverEnabled WRITE setHoverEnabled NOTIFY hoverEnabledChanged)
     Q_PROPERTY(QQuickDrag *drag READ drag CONSTANT) //### add flicking to QQuickDrag or add a QDeclarativeFlick ???
     Q_PROPERTY(bool preventStealing READ preventStealing WRITE setPreventStealing NOTIFY preventStealingChanged)
+    Q_PROPERTY(bool propagateComposedEvents READ propagateComposedEvents WRITE setPropagateComposedEvents NOTIFY propagateComposedEventsChanged)
 
 public:
     QQuickMouseArea(QQuickItem *parent=0);
@@ -164,6 +165,9 @@ public:
     bool preventStealing() const;
     void setPreventStealing(bool prevent);
 
+    bool propagateComposedEvents() const;
+    void setPropagateComposedEvents(bool propagate);
+
 Q_SIGNALS:
     void hoveredChanged();
     void pressedChanged();
@@ -174,6 +178,7 @@ Q_SIGNALS:
     void mouseXChanged(QQuickMouseEvent *mouse);
     void mouseYChanged(QQuickMouseEvent *mouse);
     void preventStealingChanged();
+    void propagateComposedEventsChanged();
 
     void pressed(QQuickMouseEvent *mouse);
     void pressAndHold(QQuickMouseEvent *mouse);
diff --git a/src/declarative/items/qquickmousearea_p_p.h b/src/declarative/items/qquickmousearea_p_p.h
index 9f81bf976f..c1c53c4302 100644
--- a/src/declarative/items/qquickmousearea_p_p.h
+++ b/src/declarative/items/qquickmousearea_p_p.h
@@ -95,6 +95,7 @@ public:
     bool stealMouse : 1;
     bool doubleClick : 1;
     bool preventStealing : 1;
+    bool propagateComposedEvents : 1;
     QQuickDrag *drag;
     QPointF startScene;
     QPointF targetStartPos;