SwipeControl drop-in class for Harmattan

This drop-in class abstracts away the things you need to do to disable Swipe in your Harmattan full-screen game. Apparently there is a QML screen.allowSwipe property, but I could not get it to work, so I wrote this little drop-in class.

Update 2013-06-05: Added SDL 1.2 version for swipe locking in non-Qt apps.

Usage (SDL 1.2 version)

Compile sdl_swipe.cpp with your application, and #include "sdl_swipe.h" in your main module.

Create your SDLSwipe instance after you created the window (using SDL_SetVideoMode()), and then use void SDLSwipe::lock(bool) to lock swiping or call bool SDLSwipe:locked() to check if swiping is locked:

int
main(int argc, char *argv[])
{
    // ... call SDL_SetVideoMode(...) ...
    SDLSwipe swipe;

    while (true) {
        // ... process input ...
        swipe.lock(gameplay_is_running);
        // ... render, swap buffers, etc ...
    }
}

Usage (Qt 4 version)

To use this in your QML-based C++ application, download the two files below and place them somewhere in your project. In this example, I'm placing it in the folder swipe/ below the folder where my QMake .pro file sits, so that your project folder looks something like this:

.../myproject.pro
.../swipe/swipecontrol.cc
.../swipe/swipecontrol.h

When you have got that, add the following snippet to your QMake project file (e.g. myproject.pro):

DEPENDPATH += swipe
INCLUDEPATH += swipe

SOURCES += swipe/swipecontrol.cc
HEADERS += swipe/swipecontrol.h

With this, QMake compiles SwipeControl into your application and also makes the header file (swipecontrol.h) visible to your #include instructions. Which brings us to the next step: Open the C++ file in which you create the declarative view (e.g. QDeclarativeView) and add the following at the top of your file:

#include "swipecontrol.h"

Assuming you declare your view as local variable (as in QDeclarativeView view;), you can write the following after the declaration:

SwipeControl *swipe = new SwipeControl(&view);

This creates a new SwipeControl instance for the view and also automatically exposes itself to the view's rootContext() as swipeControl (if you don't want this behavior, use false as the second parameter to the SwipeControl constructor).

With this setup in place, you can now either directly set and unset the lock on the swipe object using setLocked() or the locked property. Usually, you want to set the locked state from QML, so somewhere in your QML you should add a binding for the locked property of the swipeControl object that has been exposed to the root context, like this:

Binding {
    target: swipeControl
    property: 'locked'
    value: playingTheGame
}

Replace playingTheGame with an expression that becomes true wenn you want the swipe lock to be in effect. Congratulations! You have now successfully set up SwipeControl in your QML project. Check out the code for more details - it's trivial ;)

Be sure to read up on the fullscreen design pattern in the Harmattan UX Guidelines - always provide a way to re-enable swipe again, or your user might get stuck in your app.

Downloads

Apps using SwipeControl

Thomas Perl · 2011-11-16