Struct InputManipulator

pub struct InputManipulator(/* private fields */);

Expand description

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 dependant manipulator and the manipulator the dependant is linked to is called the 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.

To receive both click and multi-click messages on a node, you need to configure the click manipulator to wait for the failure of the multi-click manipulator:

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.

See: ClickManipulator, DragAndDropManipulator, LongPressManipulator, MultiClickManipulator, PanManipulator, PinchManipulator

§InputManipulator examples

The key manipulator:

The multi-key manipulator:

Methods from Deref<Target = Object>§

pub fn as_ptr(&self) -> *mut ObjectWrapper

pub fn as_wrapper(&self) -> &ObjectWrapper

pub fn as_object(&self) -> &Object

Represents any type inheriting from Object as &Object. This is useful for comparisions when PartialEq traits failed to compare objects of different types.

let child = screen.get_child(0)?;
let parent = child.get_parent()?.into_error(ErrorKind::ObjectNotFound)?;
// assert_eq!(screen, parent); // <- Fails to compile!
assert_eq!(screen.as_object(), parent.as_object());

pub fn get_native(&self) -> Result<NonNull<c_void>, Error>

Gets a pointer to the backing C++ instance.

pub fn is_stale(&self) -> bool

Checks whether the weak reference has expired.

pub fn get_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<<T as VariantConstraint>::RetArg, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers.

Base value is affected by the following inputs where the highest entry in the list determines the base value:

Local value set with setProperty or loaded from kzb
Value set by a style affecting the property.
Value defined by class metadata.

Modifiers are not applied, the highest-priority base value is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.

§Arguments

property_type - The property type identifying the property to retrieve.

§Returns

The evaluated property value.

pub fn get_optional_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<Option<<T as VariantConstraint>::RetArg>, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers, but does not default to the value in property metadata if there are no inputs to the property value.

If there is no value sources, None is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.