ei_gesture_pinch

Pinch Gesture Object

Interface for pinch gesture requests and events.

This interface is only provided once per device and where a client requests ei_gesture_pinch.release the interface does not get re-initialized. An EIS implementation may adjust the behavior of the device (including removing the device) if the interface is released.

Note that for a client to receive objects of this type, it must announce support for this interface in ei_handshake.interface_version.

Requests

ei_gesture_pinch.release

Since Version1 Request Opcode0

ei_gesture_pinch.release()

Notification that the client is no longer interested in pinch gestures. The EIS implementation will release any resources related to this gesture and send the ei_gesture_pinch.destroyed event once complete.

ei_gesture_pinch.begin

Since Version1 Request Opcode1

ei_gesture_pinch.begin(fingers)

Argument	Type	Summary
fingers	`uint32`	number of fingers

Note

This request is only available for clients of ei_handshake.context_type.sender.

Starts a new pinch gesture with the given number of fingers.

The finger count for pinch gestures must be between 2 and 5 (inclusive).

Only one pinch gesture may be active at any time, it is a protocol violation to send a ei_gesture_pinch.begin request before terminating the previous gesture (if any) with ei_gesture_pinch.end.

A pinch gesture may be aborted by the EIS implementation with an ei_gesture_pinch.aborted event.

ei_gesture_pinch.update

Since Version1 Request Opcode2

ei_gesture_pinch.update(dx, dy, scale, degrees)

Argument	Type	Summary
dx	`float`	the delta x movement in logical pixels
dy	`float`	the delta y movement in logical pixels
scale	`float`	the scale relative to the initial finger position
degrees	`float`	the rotation angle in degrees clockwise

Note

This request is only available for clients of ei_handshake.context_type.sender.

Moves the gesture’s logical center by the given delta and/or updates the logical scale of the gesture and/or logically rotates the gesture.

The gesture’s scale is an absolute normalized scale. Each pinch gesture starts at the scale of 1.0, subsequent events increase or decrease that scale as the pinch is widened or reduced. For example a scale of 2.0 indicates the fingers are now twice as far apart relative to the corresponding ei_gesture_pinch.begin.

The rotation is the relative angle, in degrees, compared to the previous ei_gesture_pinch.begin or ei_gesture_pinch.update. A positive angle indicates clockwise rotation, a negative angle counterclockwise rotation.

This request may be sent at most once per device frame and only after a gesture has begun via ei_gesture_pinch.begin and only before the gesture terminates with ei_gesture_pinch.end.

This request must not be sent in the same frame as begin or end.

ei_gesture_pinch.end

Since Version1 Request Opcode3

ei_gesture_pinch.end(is_cancelled)

Argument	Type	Summary
is_cancelled	`uint32`	1 if the gesture was cancelled or 0 otherwise

Note

This request is only available for clients of ei_handshake.context_type.sender.

Logically ends this gesture.

Events

ei_gesture_pinch.destroyed

Since Version1 Event Opcode0

ei_gesture_pinch.destroyed(serial)

Argument	Type	Summary
serial	`uint32`	this event’s serial number

Destructor

Immediately after sending this request, the object is considered destroyed by the EIS implementation. It must no longer be used by the client.

This gesture has been removed and a client should release all associated resources.

This ei_gesture_pinch object will be destroyed by the EIS implementation immediately after this event is sent and as such the client must not attempt to use it after that point.

ei_gesture_pinch.aborted

Since Version1 Event Opcode1

ei_gesture_pinch.aborted(serial)

Argument	Type	Summary
serial	`uint32`	this event’s serial number

Note

This event is only available for clients of ei_handshake.context_type.sender.

The current gesture has been aborted by the EIS implementation. The client must discard the current gesture and not send further ei_gesture_pinch.update and ei_gesture_pinch.end events. Due to the asynchronous nature of the protocol, an EIS implementation must allow for ei_gesture_pinch.update and ei_gesture_pinch.end events to be received after sending ei_gesture_pinch.aborted. These events must be discarded.

The client may begin a new gesture in the future using ei_gesture_pinch.begin.

ei_gesture_pinch.begin

Since Version1 Event Opcode2

ei_gesture_pinch.begin(fingers)

Argument	Type	Summary
fingers	`uint32`	number of fingers

Note

This event is only available for clients of ei_handshake.context_type.receiver.

See the ei_gesture_pinch.begin request for details.

ei_gesture_pinch.update

Since Version1 Event Opcode3

ei_gesture_pinch.update(dx, dy, scale, degrees)

Argument	Type	Summary
dx	`float`	the delta x movement in logical pixels
dy	`float`	the delta y movement in logical pixels
scale	`float`	the scale relative to the initial finger position
degrees	`float`	the rotation angle in degrees clockwise

Note

This event is only available for clients of ei_handshake.context_type.receiver.

See the ei_gesture_pinch.update request for details.

ei_gesture_pinch.end

Since Version1 Event Opcode4

ei_gesture_pinch.end(is_cancelled)

Argument	Type	Summary
is_cancelled	`uint32`	1 if the gesture was cancelled or 0 otherwise

Note

This event is only available for clients of ei_handshake.context_type.receiver.

See the ei_gesture_pinch.end request for details.