The base class for the Kanzi input manipulators. Use the input manipulators to recognize gestures, such as click or pinch, or hardware key gestures from incoming events. Kanzi has specialized subclasses to handle touch gestures and hardware key gestures. Kanzi converts and handles mouse events as touch gestures.

To use an input manipulator on a node, add it to that node with the Node::addInputManipulator() method. You can add more than one input manipulator to a node, but you can use only one input manipulator to recognize a given gesture type. When you want to handle more than one gesture type on a node, link the input manipulators to each other in order of importance of the gestures that they recognize.

You can link input manipulators sequentially. For example, if you want a node to recognize the pan, double-click, and click gestures in this order, link the ClickManipulator to the MultiClickManipulator, and the MultiClickManipulator to the PanManipulator.

The linking of the manipulators is directional and hierarchical. The linked manipulator is called the \b dependant manipulator and the manipulator the dependant is linked to is called the \b fail manipulator. The dependant manipulator has lower priority than the fail manipulator. Lower priority manipulator succeeds only when the higher priority manipulators fail to recognize a gesture. You can link the two manipulators by calling requireToFail() on the dependant manipulator, passing the fail manipulator as argument. \image html "Input manipulator priority.svg"

To receive both click and multi-click messages on a node, you need to configure the click

If the dependant manipulator supports delay, when it recognizes a gesture and the fail manipulator has not finished recognizing a gesture, the dependant manipulator sets its own state to StateDelayed. When an input manipulator is in the StateDelayed state, it stops handling events and waits until the fail manipulator finishes recognizing its gesture.

If the fail manipulator fails, Kanzi calls the onFail() of the dependant manipulator. In that case the onFail() method generates the message that was delayed. If the fail manipulator succeeds, Kanzi cancels the dependant manipulator.

To add delay functionality to your own input manipulators, when that input manipulator recognizes a gesture and there is an input manipulator on which your input manipulator depends, your input manipulator must first enter the StateDelayed state. In this case, do not send any messages. When the fail manipulator fails, Kanzi calls the onFail() on your input manipulator. Use this method to send delayed messages. When the fail manipulator succeeds, Kanzi cancels your input manipulator.

You can cancel an input manipulator after it enters one of the following states: -StatePossible -StateBegin -StateChange -StateDelayed.

When you cancel an input manipulator, that input manipulator:

• Stops receiving gesture recognition
• Enters the StateCanceled state
• Calls the onCancel() method
• Enters the StateReady state

Kanzi cancels an input manipulator when:

• You call cancel()
• One of the other input manipulators that are attached to the same node enter one of these states:
• StateBegin
• StateChange
• StateEnd.
• An input manipulator is in one of these states and you call reset():
• StateBegin
• StateChange
• StateEnd. Kanzi first cancels and then resets the input manipulator.

Gesture recognition Kanzi dispatches the incoming event data to manipulators attached to nodes in phases:

• Kanzi tunnels the event data to nodes starting from the root node and ending at the hit test node or at the focus node. In this phase only the input manipulators that have the RoutingTunneling routing mode set receive the event data for recognition.
• Kanzi continues to bubble the event data from the hit test or focus node node to the root node, updating the nodes with input manipulators that have the RoutingBubbling routing mode set.
• Kanzi updates the input manipulators that are outside of the hierarchy of the hit test or active focus node.

The touch gesture recognition happens in the notifyTouchInside() or notifyTouchOutside() methods of an input manipulator. Every input manipulator attached to a hit test node receives all the touch points that occurred in the application. In each input manipulator you must set the correct state to inform Kanzi that the input manipulator recognized a gesture. You do this by calling the setState() method with the appropriate State value.

When an input manipulator recognizes a touch event as a starting action of a gesture:

• The input manipulator enters the StatePossible state. Usually every input manipulator takes the first touch point as a possible starting point of the gesture it recognizes. In this phase, every input manipulator in the StatePossible state receives the touch event.
• When the input manipulator recognizes the incoming touch event as a comprehensive gesture, depending on the type of the gesture, this input manipulator sets its state to either StateBegin, StateEnd, or StateFail state.
• Input manipulators which recognize gestures where the touch point location is not changing, such as click or multi-click, and gestures where the touch location is updated, set the state to StateEnd.
• If the gesture recognition fails, input manipulators set the StateFail state value. It is important that you mark the gesture recognition failure in the failing input manipulator. This enables Kanzi to continue dispatching the touch event to the dependant input manipulators. Kanzi calls onFail() method on the dependant input manipulator linked, continuing the gesture recognition in that input manipulator.

Key gesture recognition happens in the notifyKeyInput() method of an input manipulator. Every input manipulator attached to a node that is the focus node of the ascendant node of the focus node receives the key event. To recognize the key event as a key gesture, call the detectKeyGesture() method for each key gesture that your input manipulator handles. The method calls onPartialKeyPressGesture(), onKeyPressGesture(), and onKeyReleaseGesture() when Kanzi recognizes a key event as a partial key press gesture, a full key press gesture, or a key release gesture. A partial key press gesture usually happens with key gestures composed of a key value and key modifiers. Just like with touch gestures, in each input manipulator you must set the correct state to inform Kanzi that the input manipulator recognized a key gesture.

During and on gesture recognition, input manipulators can dispatch messages to the attached node, to inform the subscribed message handlers about the progress of the gesture.

PanManipulator, PinchManipulator

InputManipulator examples

Inherits properties and message types from InputManipulatorMetadata.