More mouse and key event handling and related documentation

9 files changed, 177 insertions, 86 deletions

diff --git a/examples/declarative/mouseregion/mouse.qml b/examples/declarative/mouseregion/mouse.qml
index 9581da2..7aaf51a 100644
--- a/examples/declarative/mouseregion/mouse.qml
+++ b/examples/declarative/mouseregion/mouse.qml
@@ -1,7 +1,7 @@
 <Rect color="white" width="200" height="200">
     <Rect width="50" height="50" color="red">
         <Text text="Click" anchors.centeredIn="{parent}"/>
-        <MouseRegion onPressed="print('press (x: ' + mouse.x + ' y: ' + mouse.y + ')')"
+        <MouseRegion onPressed="print('press (x: ' + mouse.x + ' y: ' + mouse.y + ' button: ' + (mouse.button == Qt.RightButton ? 'right' : 'left') + ' Shift: ' + (mouse.modifiers &amp; Qt.ShiftModifier ? 'true' : 'false') + ')')"
                      onReleased="print('release (x: ' + mouse.x + ' y: ' + mouse.y + ' isClick: ' + mouse.isClick + ' wasHeld: ' + mouse.wasHeld + ')')"
                      onClicked="print('click (x: ' + mouse.x + ' y: ' + mouse.y + ' wasHeld: ' + mouse.wasHeld + ')')"
                      onDoubleClicked="print('double click (x: ' + mouse.x + ' y: ' + mouse.y + ')')"
diff --git a/src/declarative/canvas/qsimplecanvas.cpp b/src/declarative/canvas/qsimplecanvas.cpp
index 4d2cc5b..572bc43 100644
--- a/src/declarative/canvas/qsimplecanvas.cpp
+++ b/src/declarative/canvas/qsimplecanvas.cpp
@@ -411,6 +411,7 @@ QGraphicsSceneMouseEvent *QSimpleCanvasPrivate::mouseEventToSceneMouseEvent(QMou
     QGraphicsSceneMouseEvent *me = new QGraphicsSceneMouseEvent(t);
     me->setButton(e->button());
     me->setButtons(e->buttons());
+    me->setModifiers(e->modifiers());
     me->setPos(item);
     me->setScreenPos(e->pos());
     me->setScenePos(e->pos());
diff --git a/src/declarative/fx/qfxevents.cpp b/src/declarative/fx/qfxevents.cpp
index a3fa6af..804446b 100644
--- a/src/declarative/fx/qfxevents.cpp
+++ b/src/declarative/fx/qfxevents.cpp
@@ -42,10 +42,74 @@
 #include "qfxevents_p.h"
 
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass KeyEvent QFxKeyEvent
+    \brief The KeyEvent element provides information about a key event.
+
+    For example, the following changes the Item's state property when the Enter
+    key is pressed:
+    \code
+    <Item focus="true">
+        <onKeyPress>if (event.key == Qt.Key_Enter) state = 'ShowDetails';</onKeyPress>
+    </Item>
+    \endcode
+
+    The \l KeyActions element could also be used to achieve the above with
+    a clearer syntax.
+
+    \sa KeyActions
+*/
+
+/*!
+    \internal
+    \class QFxKeyEvent
+*/
+
+/*!
+    \qmlproperty int KeyEvent::key
+
+    This property holds the code of the key that was pressed or released.
+
+    See \l {Qt::Key}{Qt.Key} for the list of keyboard codes. These codes are
+    independent of the underlying window system. Note that this
+    function does not distinguish between capital and non-capital
+    letters, use the text() function (returning the Unicode text the
+    key generated) for this purpose.
+
+    A value of either 0 or \l {Qt::Key_unknown}{Qt.Key_Unknown} means that the event is not
+    the result of a known key; for example, it may be the result of
+    a compose sequence, a keyboard macro, or due to key event
+    compression.
+*/
+
+/*!
+    \qmlproperty string KeyEvent::text
+
+    This property holds the Unicode text that the key generated.
+    The text returned can be an empty string in cases where modifier keys,
+    such as Shift, Control, Alt, and Meta, are being pressed or released.
+    In such cases \c key will contain a valid value
+*/
+
+/*!
+    \qmlproperty bool KeyEvent::isAutoRepeat
+
+    This property holds whether this event comes from an auto-repeating key.
+*/
+
+/*!
+    \qmlproperty int KeyEvent::count
+
+    This property holds the number of keys involved in this event. If \l KeyEvent::text
+    is not empty, this is simply the length of the string.
+*/
 
 /*!
     \qmlclass MouseEvent QFxMouseEvent
     \brief The MouseEvent element provides information about a mouse event.
+
+    The position of the mouse can be found via the x and y properties.
+    The button that caused the event is available via the button property.
 */
 
 /*!
@@ -61,9 +125,58 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \qmlproperty enum button
+    \qmlproperty enum MouseEvent::button
+
+    This property holds the button that caused the event.  It can be one of:
+    \list
+    \o Qt.LeftButton
+    \o Qt.RightButton
+    \o Qt.MidButton
+    \endlist
+*/
+
+/*!
+    \qmlproperty int MouseEvent::buttons
+
+    This property holds the mouse buttons pressed when the event was generated.
+    For mouse move events, this is all buttons that are pressed down. For mouse
+    press and double click events this includes the button that caused the event.
+    For mouse release events this excludes the button that caused the event.
+
+    It contains a bitwise combination of:
+    \list
+    \o Qt.LeftButton
+    \o Qt.RightButton
+    \o Qt.MidButton
+    \endlist
+*/
+
+/*!
+    \qmlproperty int MouseEvent::modifiers
+
+    This property holds the keyboard modifier flags that existed immediately
+    before the event occurred.
+
+    It contains a bitwise combination of:
+    \list
+    \o Qt.NoModifier - No modifier key is pressed.
+    \o Qt.ShiftModifier	- A Shift key on the keyboard is pressed.
+    \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
+    \o Qt.AltModifier - An Alt key on the keyboard is pressed.
+    \o Qt.MetaModifier - A Meta key on the keyboard is pressed.
+    \o Qt.KeypadModifier - A keypad button is pressed.
+    \endlist
 
-    This property holds the button that caused the event.
+    For example, to react to a Shift key + Left mouse button click:
+    \code
+    <MouseRegion>
+        <onClick>
+            <![CDATA[
+                if (mouse.button == Qt.LeftButton && mouse.modifiers & Qt.ShiftModifier) doSomething();
+            ]]>
+        </onclick>
+    </MouseRegion>
+    \endcode
 */
 
 QML_DEFINE_NOCREATE_TYPE(QFxKeyEvent);
diff --git a/src/declarative/fx/qfxevents_p.h b/src/declarative/fx/qfxevents_p.h
index d096a90..30717ef 100644
--- a/src/declarative/fx/qfxevents_p.h
+++ b/src/declarative/fx/qfxevents_p.h
@@ -52,12 +52,12 @@ QT_BEGIN_NAMESPACE
 class QFxKeyEvent : public QObject
 {
     Q_OBJECT
-    Q_PROPERTY(int key READ key);
-    Q_PROPERTY(QString text READ text);
-    Q_PROPERTY(Qt::KeyboardModifiers modifiers READ modifiers);
-    Q_PROPERTY(bool isAutoRepeat READ isAutoRepeat);
-    Q_PROPERTY(int count READ count);
-    Q_PROPERTY(bool accepted READ isAccepted WRITE setAccepted);
+    Q_PROPERTY(int key READ key)
+    Q_PROPERTY(QString text READ text)
+    Q_PROPERTY(int modifiers READ modifiers)
+    Q_PROPERTY(bool isAutoRepeat READ isAutoRepeat)
+    Q_PROPERTY(int count READ count)
+    Q_PROPERTY(bool accepted READ isAccepted WRITE setAccepted)
 
 public:
     QFxKeyEvent(QEvent::Type type, int key, Qt::KeyboardModifiers modifiers, const QString &text=QString(), bool autorep=false, ushort count=1)
@@ -67,7 +67,7 @@ public:
 
     int key() const { return event.key(); }
     QString text() const { return event.text(); }
-    Qt::KeyboardModifiers modifiers() const { return event.modifiers(); }
+    int modifiers() const { return event.modifiers(); }
     bool isAutoRepeat() const { return event.isAutoRepeat(); }
     int count() const { return event.count(); }
 
@@ -83,14 +83,14 @@ QML_DECLARE_TYPE(QFxKeyEvent);
 class QFxMouseEvent : public QObject
 {
     Q_OBJECT
-    Q_PROPERTY(int x READ x);
-    Q_PROPERTY(int y READ y);
-    Q_PROPERTY(Qt::MouseButton button READ button);
-    Q_PROPERTY(Qt::MouseButtons buttons READ buttons);
-    Q_PROPERTY(Qt::KeyboardModifiers modifiers READ modifiers);
-    Q_PROPERTY(bool wasHeld READ wasHeld);
-    Q_PROPERTY(bool isClick READ isClick);
-    Q_PROPERTY(bool accepted READ isAccepted WRITE setAccepted);
+    Q_PROPERTY(int x READ x)
+    Q_PROPERTY(int y READ y)
+    Q_PROPERTY(int button READ button)
+    Q_PROPERTY(int buttons READ buttons)
+    Q_PROPERTY(int modifiers READ modifiers)
+    Q_PROPERTY(bool wasHeld READ wasHeld)
+    Q_PROPERTY(bool isClick READ isClick)
+    Q_PROPERTY(bool accepted READ isAccepted WRITE setAccepted)
 
 public:
     QFxMouseEvent(int x, int y, Qt::MouseButton button, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers
@@ -100,9 +100,9 @@ public:
 
     int x() const { return _x; }
     int y() const { return _y; }
-    Qt::MouseButton button() const { return _button; }
-    Qt::MouseButtons buttons() const { return _buttons; }
-    Qt::KeyboardModifiers modifiers() const { return _modifiers; }
+    int button() const { return _button; }
+    int buttons() const { return _buttons; }
+    int modifiers() const { return _modifiers; }
     bool wasHeld() const { return _wasHeld; }
     bool isClick() const { return _isClick; }
 
diff --git a/src/declarative/fx/qfxitem.cpp b/src/declarative/fx/qfxitem.cpp
index 644e812..e3568e0 100644
--- a/src/declarative/fx/qfxitem.cpp
+++ b/src/declarative/fx/qfxitem.cpp
@@ -322,33 +322,27 @@ void QFxContents::setItem(QFxItem *item)
 */
 
 /*!
-    \fn void QFxItem::keyPress(QObject *event)
+    \qmlsignal Item::onKeyPress(event)
 
-    This signal is emitted when a key is pressed.
+    This handler is called when a key is pressed.
 
-    The key event is available in QML via the QFxKeyEvent \a event
-    property.
+    The key event is available via the KeyEvent \a event.
 
     \qml
     <Item onKeyPress="if (event.key == Qt.Key_Enter) state='Enter'"/>
     \endqml
-
-    \sa keyRelease()
 */
 
 /*!
-    \fn void QFxItem::keyRelease(QObject *event)
+    \qmlsignal Item::onKeyRelease(event)
 
-    This signal is emitted when a key is released.
+    This handler is called when a key is released.
 
-    The key event is available in QML via the QFxKeyEvent \a event
-    property.
+    The key event is available in via the KeyEvent \a event.
 
     \qml
     <Item onKeyRelease="if (event.key == Qt.Key_Enter) state='Enter'"/>
     \endqml
-
-    \sa keyPress()
 */
 
 /*!
diff --git a/src/declarative/fx/qfxkeyactions.cpp b/src/declarative/fx/qfxkeyactions.cpp
index d16c305..3bd7d00 100644
--- a/src/declarative/fx/qfxkeyactions.cpp
+++ b/src/declarative/fx/qfxkeyactions.cpp
@@ -239,12 +239,7 @@ void QFxKeyActions::setEnabled(bool e)
 }
 
 /*!
-    \qmlproperty string KeyActions::keyA
-    \qmlproperty string KeyActions::keyB
-    \qmlproperty string KeyActions::keyC
-    \qmlproperty ... KeyActions::...
-    \qmlproperty string KeyActions::keyY
-    \qmlproperty string KeyActions::keyZ
+    \qmlproperty string KeyActions::keyA...keyZ
 
     The action to take for the given letter.
 
@@ -569,11 +564,7 @@ void QFxKeyActions::setKey_Down(const QString &s)
 }
 
 /*!
-    \qmlproperty string KeyActions::digit0
-    \qmlproperty string KeyActions::digit1
-    \qmlproperty string KeyActions::digit2
-    \qmlproperty ... KeyActions::...
-    \qmlproperty string KeyActions::digit9
+    \qmlproperty string KeyActions::digit0...digit9
 
     The action to take for the given number key.
 
diff --git a/src/declarative/fx/qfxmouseregion.cpp b/src/declarative/fx/qfxmouseregion.cpp
index be56786..f7b6c57 100644
--- a/src/declarative/fx/qfxmouseregion.cpp
+++ b/src/declarative/fx/qfxmouseregion.cpp
@@ -155,7 +155,7 @@ void QFxDrag::setYmax(int m)
     </Rect>
     \endcode
 
-    Many MouseRegion signals pass a \l {qml-mouseevent}{mouse} parameter that contains
+    Many MouseRegion signals pass a \l {MouseEvent}{mouse} parameter that contains
     additional information about the mouse event, such as the position, button,
     and any key modifiers.
 
@@ -163,13 +163,15 @@ void QFxDrag::setYmax(int m)
     example extended so as to give a different color when you right click.
     \code
     <Rect width="100" height="100">
-        <MouseRegion anchors.fill="{parent}" onClick="if(mouse.button=='Right') { parent.color='blue';} else { parent.color = 'red';}"/>
+        <MouseRegion anchors.fill="{parent}" onClick="if(mouse.button==Qt.RightButton) { parent.color='blue';} else { parent.color = 'red';}"/>
     </Rect>
     \endcode
 
     For basic key handling, see \l KeyActions.
 
     MouseRegion is an invisible element: it is never painted.
+
+    \sa MouseEvent
 */
 
 /*!
@@ -201,6 +203,15 @@ void QFxDrag::setYmax(int m)
 */
 
 /*!
+    \qmlsignal MouseRegion::onPositionChanged(mouse)
+
+    This handler is called when the mouse position changes.
+
+    The \l {MouseEvent}{mouse} parameter provides information about the mouse, including the x and y
+    position, and any buttons currently pressed.
+*/
+
+/*!
     \qmlsignal MouseRegion::onClicked(mouse)
 
     This handler is called when there is a click. A click is defined as a press followed by a release,
@@ -215,8 +226,8 @@ void QFxDrag::setYmax(int m)
     \qmlsignal MouseRegion::onPressed(mouse)
 
     This handler is called when there is a press.
-    The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y
-    position of the release of the click, and whether the click wasHeld.
+    The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y
+    position and which button was pressed.
 */
 
 /*!
@@ -231,8 +242,8 @@ void QFxDrag::setYmax(int m)
     \qmlsignal MouseRegion::onPressAndHold(mouse)
 
     This handler is called when there is a long press (currently 800ms).
-    The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y
-    position of the release of the click, and whether the click wasHeld.
+    The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y
+    position of the press, and which button is pressed.
 */
 
 /*!
@@ -309,24 +320,6 @@ void QFxMouseRegion::setEnabled(bool a)
     d->absorb = a;
 }
 
-void QFxMouseRegionPrivate::bindButtonValue(Qt::MouseButton b)
-{
-    Q_Q(QFxMouseRegion);
-    QString bString;
-    switch(b){
-        case Qt::LeftButton:
-            bString = QLatin1String("Left"); break;
-        case Qt::RightButton:
-            bString = QLatin1String("Right"); break;
-        case Qt::MidButton:
-            bString = QLatin1String("Middle"); break;
-        default:
-            bString = QLatin1String("None"); break;
-    }
-    // ### is this needed anymore?
-    qmlContext(q)->setContextProperty(QLatin1String("mouseButton"), bString);
-}
-
 void QFxMouseRegion::mousePressEvent(QGraphicsSceneMouseEvent *event)
 {
     Q_D(QFxMouseRegion);
@@ -348,9 +341,7 @@ void QFxMouseRegion::mousePressEvent(QGraphicsSceneMouseEvent *event)
         // ### we should only start timer if pressAndHold is connected to (but connectNotify doesn't work)
         d->pressAndHoldTimer.start(PressAndHoldDelay, this);
         setKeepMouseGrab(false);
-        d->bindButtonValue(event->button());
         setPressed(true);
-        emit positionChanged();
         event->accept();
     }
 }
@@ -424,7 +415,8 @@ void QFxMouseRegion::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
         }
     }
     d->moved = true;
-    emit positionChanged();
+    QFxMouseEvent me(d->lastPos.x(), d->lastPos.y(), d->lastButton, d->lastButtons, d->lastModifiers, false, d->longPress);
+    emit positionChanged(&me);
     event->accept();
 }
 
@@ -547,9 +539,10 @@ void QFxMouseRegion::setPressed(bool p)
     if(d->pressed != p) {
         d->pressed = p;
         QFxMouseEvent me(d->lastPos.x(), d->lastPos.y(), d->lastButton, d->lastButtons, d->lastModifiers, isclick, d->longPress);
-        if(d->pressed)
+        if(d->pressed) {
+            emit positionChanged(&me);
             emit pressed(&me);
-        else {
+        } else {
             emit released(&me);
             if (isclick)
                 emit clicked(&me);
diff --git a/src/declarative/fx/qfxmouseregion.h b/src/declarative/fx/qfxmouseregion.h
index 2e2a1d4..2ba4a50 100644
--- a/src/declarative/fx/qfxmouseregion.h
+++ b/src/declarative/fx/qfxmouseregion.h
@@ -121,7 +121,7 @@ public:
 Q_SIGNALS:
     void hoveredChanged();
     void pressedChanged();
-    void positionChanged();
+    void positionChanged(QFxMouseEvent *mouse);
 
     void pressed(QFxMouseEvent *mouse);
     void pressAndHold(QFxMouseEvent *mouse);
diff --git a/src/declarative/fx/qfxmouseregion_p.h b/src/declarative/fx/qfxmouseregion_p.h
index e9d1986..d72b423 100644
--- a/src/declarative/fx/qfxmouseregion_p.h
+++ b/src/declarative/fx/qfxmouseregion_p.h
@@ -66,7 +66,7 @@ class QFxMouseRegionPrivate : public QFxItemPrivate
 
 public:
     QFxMouseRegionPrivate()
-      : absorb(true), hovered(false), inside(true), pressed(false), longPress(0), drag(0)
+      : absorb(true), hovered(false), inside(true), pressed(false), longPress(false), drag(0)
     {
     }
 
@@ -77,25 +77,24 @@ public:
         q->setOptions(QSimpleCanvasItem::HoverEvents | QSimpleCanvasItem::MouseEvents);
     }
 
-    void bindButtonValue(Qt::MouseButton);
-
     void saveEvent(QGraphicsSceneMouseEvent *event) {
         lastPos = event->pos();
         lastButton = event->button();
         lastButtons = event->buttons();
         lastModifiers = event->modifiers();
+        qDebug() << "modifiers" << lastModifiers;
     }
 
-    bool absorb;
-    bool hovered;
-    bool inside;
-    bool pressed;
-    bool longPress;
+    bool absorb : 1;
+    bool hovered : 1;
+    bool inside : 1;
+    bool pressed : 1;
+    bool longPress : 1;
+    bool moved : 1;
+    bool dragX : 1;
+    bool dragY : 1;
+    bool dragged : 1;
     QFxDrag drag;
-    bool moved;
-    bool dragX;
-    bool dragY;
-    bool dragged;
     QPointF start;
     QPointF startScene;
     int startX;