Gestures in QML | Qt Quick | Tutorials

Native support for gestures is still missing in QML but development is under way as a laboratory project.

In case you have installed a recent version of the Qt Creator, it is most likely that you already have this plugin. It is also available in Qt 4.7.1. The thing is that in the previous it is called "qmlgesturesplugin" and in latter "qmlgestureareaplugin" according to the qmldir file.

In order to try it out, get the examples from gitorious repository:

git clone http://git.gitorious.org/qt-labs/qml-gestures-examples.git

If you are also interested of the sources for gestures plugin, they are available also via gitorious:

git clone http://git.gitorious.org/qt-labs/qml-gesturearea.git

In case you would not have git installed, you can also download the current version from their corresponding gitorious pages, the examples and the plugin.

In case you want to be sure to have the latest cutting edge version, get the plugin sources and build them, below commands for Windows, using Qt 4.7.1 Command Prompt, Linux people know better:

qmake
mingw32-make

In case it fails while trying to copy qmlfile to import/Qt/labs/gestures, that is because of the directory separator. It is OK to copy it by hand as it is the last command. Feel free to copy these files to your Qt 4.7.1 import directory, while overwriting the existing.

As for the documentation, it is best to read the sources of the plugin and go through the examples, while the official documentation is completely off.

As for today, the following elements are available inside the GestureArea:

Pan - a movement of pressing and holding while moving the pointing device on the gesture area
Pinch - used to handle the moving using more than one finger
Swipe - a movement immediately after pressing
Tap - a touch and release without moving
TapAndHold - a touch without releasing or moving for a longer time

Be aware of using elements provided by the auto compete which are ending in ..Gesture. They should not be used.

Each of the elements have the following signals:

onStarted
onUpdated
onCanceled
onFinished

and two properties:

when - a script which is evaluated to see when gesture is to be used
gestureType - int, could be used to create custom gestures

All the signals have one property of object type, called gesture. Now each signal will have different set of properties available in that object. Best resource for those is the source file which handles the filling of that data, qdeclarativegesturerecognizers.cpp, specifically the parts where method setProperty() is used. Easier and more accurate way is shown in the example code, via the function called walkObject.

GestureArea offers several advantages over regular MouseArea, for example the information related to direction in which a certain gesture was made. While GestureArea allows several kinds of gestures to be used at once, it becomes rather trivial to use them together in order to achieve something more tricky.

The example below demonstrates how to use Tap and Pan, previous only to get the initial position and the latter will take care of the rest.

import QtQuick 1.0
import Qt.labs.gestures 2.0

/**
 * Gestures provide the missing functionality
 * over MouseArea which are used in mobile devices.
 */
Rectangle {
    id: main

    width: 800
    height: 480
    color: "darkgreen"

    function walkObject(obj) {
        for (var name in obj) {
            if (obj.hasOwnProperty(name)) {
                console.log("> " + name + " > " + obj[name]);
            }
        }
    }

    Rectangle {
        id: marker
        color: "pink"
        height: 20
        width: 20
        radius: 10
        opacity: 0

        Behavior on opacity {
            NumberAnimation {
                easing.type: Easing.InOutQuad
                duration: 200
            }
        }
    }

    GestureArea {
        id: gArea

        property real initX: 0
        property real initY: 0

        anchors.fill: parent

        Tap {
            onStarted: {
                console.log("Tap onStarted");
                walkObject(gesture);
                gArea.initX = gesture.position.x;
                gArea.initY = gesture.position.y;
            }
            onCanceled: {
                console.log("Tap onCanceled");
            }
            onFinished: {
                console.log("Tap onFinished");
            }
        }

        Pan {
            onStarted: {
                console.log("Pan onStarted");
                marker.opacity = 1;
            }
            onUpdated: {
                console.log("Pan onUpdated");

                marker.x = gesture.lastOffset.x + gArea.initX;
                marker.y = gesture.lastOffset.y + gArea.initY;
            }
            onFinished: {
                console.log("Pan onFinished");
                marker.opacity = 0;
            }
        }

    }

}

Please note: Everything is experimental.