From 2498b13d929c720510cc446da8afc73dc7154d3c Mon Sep 17 00:00:00 2001 From: Povilas Kanapickas Date: Mon, 21 Sep 2020 04:03:44 +0300 Subject: specs: Add support for gesture events as XI 2.4 Signed-off-by: Povilas Kanapickas --- specs/XI2proto.txt | 465 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 455 insertions(+), 10 deletions(-) (limited to 'specs') diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt index 09928f8..3f37598 100644 --- a/specs/XI2proto.txt +++ b/specs/XI2proto.txt @@ -9,11 +9,13 @@ Authors: - Peter Hutterer (Red Hat) - Daniel Stone (Collabora Ltd.) - Chase Douglas (Canonical, Ltd.) +- Povilas Kanapickas [[history]] History ------- +- v2.4, TODOTODO TODO: Touchpad gesture support added - v2.3, December 2012: Pointer barrier events added - v2.2, March 2012: Multitouch support added - v2.1, December 2011: new raw event behaviour, smooth scrolling support @@ -63,6 +65,11 @@ Changes in version 2.3 - Pointer barrier events added +Changes in version 2.4 +---------------------- + +- Touchpad gesture support added + // ❧❧❧❧❧❧❧❧❧❧❧ Notations used in this document @@ -613,6 +620,122 @@ The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is generated while the device is actively grabbed by any client or a passive grab has activated for this device prior to the event. + +[[touch-gestures]] +Gesture event sequences +~~~~~~~~~~~~~~~~~~~~~~~ + +XI 2.4 introduces support for touch gestures. A touch gesture is a interaction of +two or more fingers that is interpreted by the driver as a gesture such as swipe +or pinch. + +A pinch gesture is executed when two or more fingers are located on the touchpad and are +either changing the relative distance to each other or are changing the relative angle. +Pinch gestures may change both rotation and distance at the same time. + +Swipe gestures are executed when three or more fingers are moved synchronously in the +same direction. + +A single device may only support either touch or gesture events. Gestures are supported +only on dependent devices as direct touch devices do not expose enough +context about the gestures by design (see <> +for explanation of the properties of direct and dependent devices). + +Gesture events are only available to clients supporting version 2.4 or later of +the X Input Extension. Clients must use the XIQueryVersion request to announce +support for this version. + +Gesture event processing differs from normal event processing in a few ways. +The most notable differences are that gesture events are processed partially +out-of-band from pointer and keyboard events. + +A single device must not support both touch and gesture events. + + +[[gesture-lifecycle]] +Gesture event lifecycle +~~~~~~~~~~~~~~~~~~~~~~~ + +Gesture input follows a three-stage cycle: + + begin - update - update - ... - end + +i.e. “begin” the sequence when the device interprets interaction on it as a gesture, +“update” the current gesture location or properties any number of times, and finally +“end” the sequence when the interation stops or is no longer a gesture. +Within this document, the term "gesture sequence" is used to describe the above sequence +of events. + +Two gesture types are supported: swipe and pinch. +In the protocol, there's a separate event type for each of the three stages and gesture types: + + - GesturePinchBegin + - GesturePinchUpdate + - GesturePinchEnd + - GestureSwipeBegin + - GestureSwipeUpdate + - GestureSwipeEnd + +In this document we will use the following abbreviations: + + - GestureFOOBegin refers to either GesturePinchBegin or GestureSwipeBegin + - GestureFOOUpdate refers to either GesturePinchUpdate or GestureSwipeUpdate + - GestureFOOEnd refers to either GesturePinchEnd or GestureSwipeEnd + +A gesture sequence always generates GestureFOOBegin and GestureFOOEnd events, and may +also generate GestureFOOUpdate events. Clients must select for all three of these events +simultaneously. + +When a gesture starts, the client is sent a GestureFOOBegin event detailing the position +of the gesture, as well as the initial properties of the gesture. Note that the +logical state of the device (as seen through the input protocol) may lag the physical +state if event processing is affected by grabs. + +Only one gesture sequence may be active on a specific input device at a time. + +Whenever the gesture position or any other property of the gesture changes, +a GestureFOOUpdate event is sent to the client listening +to events for that gesture with the updated information. + +When the gesture has logically ended, or a client will otherwise not receive +any more events for a given gesture, a GestureFOOEnd event will be sent to +that client. + +If a gesture does not physically end but changes the number of touches, a +GestureFOOEnd event with the cancel flag set is sent tot he client, followed +by a GestureFOOBegin event. This may happen when e.g. at the beginning of a +4 finger gesture, a 3 finger gesture is recognized for a short moment. +Clients are expected to undo any actions caused by the cancelled gesture. + +Passive gesture grabs are similar to standard input event grabs in that they +take precedence over event selections and are searched from the root window +to the child window (as opposed to selections, which start their search at the +child window and continue up to the root window). See the +<> request documentation for more +information on passive grab activation. + +Only one client may select for gesture events from a given device on a window. + +Events originating from a single gesture sequence will generally be sent to a single +client. The only exception is when GestureFOOBegin is grabbed and replayed to +a subsequent client. In this case, all replaying clients will get GestureFOOBegin and +GestureFOOEnd events and the final client will get whole gesture sequence. + +The decision what client will be sent the gesture sequence happens when the +GestureFOOBegin event is received. First, any active device grab is chosen. +If no grab is active, the first passive grab is chosen searching from the root +window to the deepest child window. If no grab is found, then the first event +selection is chosen going from the deepest child to the root window. + +If gesture events are not included in the mask of the chosen grab, +then no client will receive events for the gesture sequence. +A core or a XI 1.x pointer grab will cause the gesture sequence to be discarded. + +If there are simultaneous gesture event sequences from multiple devices, the +master device will ignore all gesture sequences except the first. Specifically, if +GestureFOOBegin is received when a gesture is already active, all events +relating to the new gesture sequence will be discarded. + [[glossary-notations]] Notations used in this document ------------------------------- @@ -768,7 +891,7 @@ XIQueryDevice name: LISTofCHAR8 classes: LISTofCLASS } - CLASS { BUTTONCLASS, KEYCLASS, VALUATORCLASS, SCROLLCLASS, TOUCHCLASS } + CLASS { BUTTONCLASS, KEYCLASS, VALUATORCLASS, SCROLLCLASS, TOUCHCLASS, GESTURECLASS } BUTTONCLASS { type: ButtonClass length: CARD16 @@ -814,8 +937,14 @@ XIQueryDevice TOUCHMODE { DirectTouch, DependentTouch } + GESTURECLASS³ { type: GestureClass + length: CARD16 + sourceid: CARD16 + num_touches: CARD16 } + ¹ since XI 2.1 ² since XI 2.2 + ³ since XI 2.4 XIQueryDevice details information about the requested input devices. @@ -958,6 +1087,20 @@ exist per ValuatorClass. Devices with a TouchClass emit touch events with the same axes as pointer events. + GestureClass: + type + Always GestureClass. + length + Length in 4 byte units. + sourceid + The device this class originates from. + num_touches + The maximum number of touchpoints in a gesture that the device may send. + If num_touches is 0, the number of supported touches is unknown or + unlimited. + +Devices with a GestureClass emit gesture events. + [[requests-selectevents]] XISelectEvents ^^^^^^^^^^^^^^ @@ -1011,6 +1154,18 @@ overlaps a current selection by another client (e.g. selecting for a specific device when another client has a selection for XIAllDevices), a BadAccess error occurs. +A client selecting for any of XI_GesturePinchBegin, XI_GesturePinchUpdate, or XI_GesturePinchEnd +must select for all three events at the same time, else a BadValue error +will be generated. + +A client selecting for any of XI_GestureSwipeBegin, XI_GestureSwipeUpdate, or XI_GestureSwipeEnd +must select for all three events at the same time, else a BadValue error +will be generated. + +If the selection for gesture events overlaps a current selection by another client +(e.g. selecting for a specific device when another client has a selection for +XIAllDevices), a BadAccess error occurs. + [[requests-getselectedevents]] XIGetSelectedEvents ^^^^^^^^^^^^^^^^^^^ @@ -1554,7 +1709,9 @@ you pass to the event-mode argument: SyncDevice: If the specified device is frozen and actively grabbed by the client, event processing for that device continues normally until the next - event is reported to the client. At this time, the specified device + button press or release, or key press or release, or a gesture begin or end + event (depending on the grab) is reported to the client. + At this time, the specified device again appears to freeze. However, if the reported event causes the grab to be released, the specified device does not freeze. SyncDevice has no effect if the specified device is not frozen by the @@ -1569,6 +1726,8 @@ you pass to the event-mode argument: grab-window of the grab just released. The request has no effect if the specified device is not grabbed by the client or if it is not frozen as the result of an event. + In case of gesture begin event being replayed, the original grabbing + client will receive a GesturePinchEnd or GestureSwipeEnd event. AsyncPairedDevice If the paired master device is frozen by the client, event processing for it continues as usual. If the paired device is frozen multiple @@ -1646,12 +1805,14 @@ XIPassiveGrabDevice └─── GRABTYPE { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter, - GrabtypeFocusIn, GrabtypeTouchBegin¹ } + GrabtypeFocusIn, GrabtypeTouchBegin¹, + GrabtypeGesturePinchBegin², GrabtypeGestureSwipeBegin² } GRABMODIFIERINFO { status: Access modifiers: SETofMODIFIERMASK } ¹ since XI 2.2 + ² since XI 2.4 Establish an explicit passive grab for a button or keycode on the specified input device. @@ -1665,7 +1826,8 @@ on the specified input device. detail In the case of GrabtypeButton, specifies the button number to grab for. In the case of GrabtypeKeycode, specifies the key code to grab for. - The value must be 0 for GrabtypeEnter, GrabtypeFocusIn, and GrabtypeTouchBegin. + The value must be 0 for GrabtypeEnter, GrabtypeFocusIn, GrabtypeTouchBegin, + GrabtypeGesturePinchBegin and GrabtypeGestureSwipeBegin. grab_type The type of grab to establish. grab_window @@ -1750,6 +1912,15 @@ Otherwise, if grab_type is GrabtypeTouchBegin, a touch grab begins if: - a passive grab of the same grab_type + modifier combination does not does not exist on an ancestor of grab_window. +Otherwise, if grab_type is GrabtypeGesturePinchBegin or GrabtypeGestureSwipeBegin, +a gesture grab begins if: + + - the device is not actively grabbed, and + - the specified modifier keys are down, and + - a specific gesture begins in grab_window or a descendant of grab_window, and + - a passive grab of the same grab_type + modifier combination does not + does not exist on an ancestor of grab_window. + Ownership of the touch sequence is granted to the grabbing client if: - a TouchBegin or pointer grab for an emulated touch sequence of a @@ -1769,6 +1940,8 @@ pointer or focus leaves the window and all of its descendants, independent of the state of modifier keys. A GrabtypeTouchBegin grab is released when the touch sequence ends or the client uses XIAllowEvents with mode RejectTouch. +A GrabtypeGesturePinchBegin and GrabtypeGestureSwipeBegin grab are +released when the gesture sequence ends. Note that the logical state of a device (as seen by means of the protocol) may lag the physical state if device event processing is frozen. @@ -1784,8 +1957,12 @@ other client already has issued an XIPassiveGrabDevice request of grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, or XIGrabtypeTouchBegin with the same grab_window and the same modifier combination, the failed modifier combinations are returned -in modifiers_return. If num_modifiers_return is zero, all passive -grabs have been successful. +in modifiers_return. +If some other client already has issued an XIPassiveGrabDevice request of +grab_type XIGrabtypeGesturePinchBegin or XIGrabtypeGestureSwipeBegin +with the same grab_window, and the same modifier combination, +the failed modifier combinations are returned in modifiers_return. +If num_modifiers_return is zero, all passive grabs have been successful. If a button grab or enter grab activates, EnterNotify and LeaveNotify events with mode Grab are generated as if the pointer were to suddenly @@ -1833,9 +2010,10 @@ Release an explicit passive grab on the specified input device. deviceid The device to establish the passive grab on. detail - The button number or key code to ungrab. - Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and - GrabtypeTouchBegin. + In the case of GrabtypeButton, specifies the button number to ungrab. + In the case of GrabtypeKeycode, specifies the key code to ungrab. + The value must be 0 for GrabtypeEnter, GrabtypeFocusIn, GrabtypeTouchBegin, + GrabtypeGesturePinchBegin and GrabtypeGestureSwipeBegin. grab_type The type of grab to establish. grab_window @@ -2096,6 +2274,15 @@ Version 2.3: - BarrierHit (see <>) - BarrierLeave (see <>) +Version 2.4 + + - GesturePinchBegin (see <