Gestures
Gestures are predefined patterns. Xenko can recognize gestures and trigger corresponding events. For example, in a strategy game, the player can drag and drop a unit to the battlefield with a drag gesture. Gestures can use one or several fingers.
Note
All lengths, speeds and error margins of configuration files must use normalized values.
By default, the input system doesn't recognize gestures, as this requires CPU time.
To turn on gesture recognition:
- Create an instance of the configuration class for the gesture you want to recognize. For example, for the drag gesture, create an instance of GestureConfigDrag.
- Configure the class parameters.
- Add the gesture configuration to the collection.
Warning
After you activate recognition for a gesture, you can't modify the gesture's parameters. If you need to do this, delete the gesture from the Gestures collection and create a new entry with new parameters.
Delete the gesture from the collection.
Gesture recognition
When the input system detects a gesture, it adds a GestureEvent to the list of . The event contains information about the gesture and its state, such as its location and the number of fingers used.
Note
Each gesture has its own associated gesture event class (see below).
The GestureEvent.Type field indicates which gesture has been recognized. You can then cast the base gesture event into the gesture-specific event type to have gesture-type-specific information about the event.
Xenko can detect several gestures simultaneously, so the event list can contain more than one item in an update.
The list is cleared with every update, so you don't need to clear it manually.
In the classes, you can configure parameters including:
the number of fingers the gesture uses
the number and duration of taps the gesture uses
Note
Each gesture has its own configuration class with specific configuration parameters (see below).
Types of gesture
Xenko supports two main types of gesture:
Discrete gestures (tap, flick, long press) trigger a single event.
Continuous gestures (drag and composite) trigger a series of events when the user changes the direction of the gesture.
Discrete gestures
Tap
The user touches the screen and quickly removes their finger.
Configuration class: GestureConfigTap
Event class:
The number of fingers on the screen can't vary during the gesture. To set the number of fingers required for a tap, modify RequiredNumberOfFingers.
Tip
To distinguish single taps from multi-taps, the system uses latency in tap events. To disable this, set the field to 0.
Flick
The user touches the screen, performs a quick straight translation, and withdraws their finger(s).
Configuration class: GestureConfigFlick
Event class:
The number of fingers on the screen can't during the gesture.
To set a minimum length for the flick gesture, use GestureConfigFlick.MinimumFlickLength.
To restrict the direction of the flick to vertical or horizontal, use .
Long press
The user touches the screen and maintains pressure without removing their finger for a certain period of time (the default time is one second).
Configuration class: GestureConfigLongPress
Event class:
The number of fingers on the screen can't vary during the gesture.
To change the minimum press length for the long press gesture, modify GestureConfigLongPress.RequiredPressTime.
Drag
The user touches the screen, performs a translation, and withdraws their finger(s).
Event class:
The number of fingers on the screen can't vary during the gesture.
To detect smaller drags, decrease GestureConfigDrag.MinimumDragDistance.
To restrict the direction of the drag to vertical or horizontal, use .
Composite
The user touches the screen with two fingers and moves them independently.
Configuration class: GestureConfigComposite
Event class:
The composite gesture requires exactly two fingers on the screen. It's triggered when the system detects one of the three basic actions:
- Translation: the user translates two fingers together in the same direction.
- Scale: the user moves two fingers closer together or further apart.
- Rotation: the user rotates two fingers around a center point.
A gesture always has one of four states:
Began
Changed
Ended
Occurred
Discrete gestures (tap, flick, long press) always have the state occurred. Continuous gestures (drag and composite) always begin with the state began, followed by any changed states, and end with the ended state.
To query the current state of a gesture, use the GestureEvent.State field of the triggered gesture event.
Example code
Activate or deactivate gesture recognition
To create the configuration of a gesture you want to recognize:
Each configuration class has a parameterless constructor that corresponds to the default gesture configuration. You can use special constructors for frequently-modified parameters.
Warning
We don't recommend you modify other fields as this might break the input system. But if you need to, you can modify them using the corresponding properties.
Access gesture events
You can access the list of events triggered by recognized gestures using the collection. The collection is automatically cleared at every update.
Use the GestureEvent.Type field to identity the gesture type, then cast it to the appropriate event type to get extra information about the event.
Identify the gesture state
Use the field to get gesture event state.