Magnum::Platform::TwoFingerGesture class new in Git master
#include <Magnum/Platform/Gesture.h>

Two-finger gesture recognition.

Tracks position of a primary finger and an arbitrary secondary finger based on pointer events passed to pressEvent(), releaseEvent() and moveEvent(). Once two fingers are pressed, the instance is contextually convertible to true, and position(), direction(), relativeTranslation(), relativeRotation() and relativeScaling() contain gesture properties. Example usage:

void MyApplication::pointerPressEvent(PointerEvent& event) {
    _gesture.pressEvent(event);

    …
}

void MyApplication::pointerReleaseEvent(PointerEvent& event) {
    _gesture.releaseEvent(event);

    …
}

void MyApplication::pointerMoveEvent(PointerMoveEvent& event) {
    _gesture.moveEvent(event);

    /* A gesture is recognized, perform appropriate action */
    if(_gesture) {
        translateSomething(_gesture.relativeTranslation());
        rotateSomething(_gesture.relativeRotation());
        scaleSomething(_gesture.relativeScaling());

        event.setAccepted();
        redraw();
        return;
    }

    …
}

The interface is designed primarily for *Application subclasses and their PointerEvent and PointerMoveEvent instances, but works also with any other types that provide appropriate source(), isPrimary(), id() and position() members.

Constructors, destructors, conversion operators

operator bool() const explicit
Whether the internal state represents a two-finger gesture.

Public functions

template<class PointerEvent>
auto pressEvent(const PointerEvent& event) -> bool
Handle a press event.
template<class PointerEvent>
auto releaseEvent(const PointerEvent& event) -> bool
Handle a release event.
template<class PointerMoveEvent>
auto moveEvent(const PointerMoveEvent& event) -> bool
Handle a move event.
auto fingerCount() const -> UnsignedInt
Count of known pressed fingers.
auto isGesture() const -> bool
Whether the internal state represents a two-finger gesture.
auto position() const -> Vector2
Centroid between the two known pressed finger positions.
auto direction() const -> Vector2
Direction from the center to the primary finger position.
auto relativeTranslation() const -> Vector2
Translation of the centroid relative to the previous finger positions.
auto relativeRotation() const -> Complex
Rotation relative to the previous finger positions.
auto relativeScaling() const -> Float
Scaling relative to the previous finger positions.

Function documentation

Magnum::Platform::TwoFingerGesture::operator bool() const explicit

Whether the internal state represents a two-finger gesture.

Returns true if both the primary and a secondary finger are pressed, false otherwise. Same as operator bool().

template<class PointerEvent>
bool Magnum::Platform::TwoFingerGesture::pressEvent(const PointerEvent& event)

Handle a press event.

Accepts a pointer event instance such as the one coming from Platform::Sdl2Application::pointerPressEvent(). If the event comes from a primary finger, replaces the internal state with it, waiting for the secondary finger press to happen. If the event comes from a secondary finger, it's used only a primary finger is known, there's no known secondary finger ID yet. or the ID matches the known secondary finger ID. Events that don't come from a touch source are ignored. Returns true if the event was used, false if not.

The function doesn't modify the event in any way. If needed, it's up to the caller to call setAccepted().

template<class PointerEvent>
bool Magnum::Platform::TwoFingerGesture::releaseEvent(const PointerEvent& event)

Handle a release event.

Accepts a pointer event instance such as the one coming from Platform::Sdl2Application::pointerReleaseEvent(). If the release comes from a primary finger whose ID is known, resets the state for both the primary and secondary touch, waiting for a primary finger press to happen again. Otherwise, if the release comes from a secondary finger whose ID is known. resets just the secondary finger state, waiting for a different secondary finger press to happen. Events that don't come from a touch source are ignored. Returns true if the event was used, false if not.

The function doesn't modify the event in any way. If needed, it's up to the caller to call setAccepted().

template<class PointerMoveEvent>
bool Magnum::Platform::TwoFingerGesture::moveEvent(const PointerMoveEvent& event)

Handle a move event.

Accepts a pointer move event instance such as the one coming from Platform::Sdl2Application::pointerMoveEvent(). If the move comes from a primary finger whose ID is known or from a secondary finger whose ID is known, updates given finger state. Events that don't come from a touch source are ignored. Returns true if the event was used, false if not.

The function doesn't modify the event in any way. If needed, it's up to the caller to call setAccepted().

UnsignedInt Magnum::Platform::TwoFingerGesture::fingerCount() const

Count of known pressed fingers.

Is 0 if pressEvent() wasn't called yet or releaseEvent() happened for the primary finger, 1 if only the primary finger is pressed or a secondary finger was released and 2 if both the primary and a secondary finger is currently pressed.

bool Magnum::Platform::TwoFingerGesture::isGesture() const

Whether the internal state represents a two-finger gesture.

Returns true if both the primary and a secondary finger are pressed, false otherwise. Same as operator bool().

Vector2 Magnum::Platform::TwoFingerGesture::position() const

Centroid between the two known pressed finger positions.

If only one or no fingers are pressed — i.e., isGesture() is false — returns a NaN vector.

Vector2 Magnum::Platform::TwoFingerGesture::direction() const

Direction from the center to the primary finger position.

Negate the return value to get direction from the center to the secondary finger. If only one or no fingers are pressed — i.e., isGesture() is false — returns a NaN vector.

Vector2 Magnum::Platform::TwoFingerGesture::relativeTranslation() const

Translation of the centroid relative to the previous finger positions.

If there was no movement since the press, returns a zero vector. If only one or no fingers are pressed — i.e., isGesture() is false — returns a NaN vector.

Complex Magnum::Platform::TwoFingerGesture::relativeRotation() const

Rotation relative to the previous finger positions.

Note that given the event coordinates are in a Y down coordinate, positive rotation angle is clockwise. If there was no movement since the press, returns an identity rotation. If only one or no fingers are pressed — i.e., isGesture() is false — returns a complex NaN.

The function returns a Complex instead of an angle as the angle would likely be converted back to a rotation representation anyway. Use Complex::toMatrix(), Complex::transformVector() or Complex::angle() if a different representation is needed.

Float Magnum::Platform::TwoFingerGesture::relativeScaling() const

Scaling relative to the previous finger positions.

The returned value is always positive. Values less than 1.0f are when the points are getting closer, values larger than 1.0f are when the points are getting further apart. If there was no movement since the press, returns 1.0f. If only one or no fingers are pressed — i.e., isGesture() is false — returns a NaN.