Merge remote-tracking branch 'inputproto/master' into multitouch-devel

Conflicts:
	XI2.h
	XI2proto.h
	specs/XI2proto.txt

Signed-off-by: Chase Douglas <chase.douglas@canonical.com>

3 files changed, 172 insertions, 24 deletions

diff --git a/XI2.h b/XI2.h
index 43c5836..ca5ce07 100644
--- a/XI2.h
+++ b/XI2.h
@@ -35,8 +35,7 @@
    See commit libXi-1.4.2-21-ge8531dd */
 
 #define XI_2_Major                              2
-#define XI_2_Minor                              0
-#define XI_2_1_Minor                            1
+#define XI_2_Minor                              1
 
 /* Property event flags */
 #define XIPropertyDeleted                       0
@@ -148,9 +147,18 @@
 #define XIKeyClass                              0
 #define XIButtonClass                           1
 #define XIValuatorClass                         2
+#define XIScrollClass                           3
 #define XITouchClass                            8
 #define XITouchValuatorClass                    9
 
+/* Scroll class types */
+#define XIScrollTypeVertical                    1
+#define XIScrollTypeHorizontal                  2
+
+/* Scroll class flags */
+#define XIScrollFlagNoEmulation                 (1 << 0)
+#define XIScrollFlagPreferred                   (1 << 1)
+
 /* Device event flags (common) */
 /* Device event flags (key events only) */
 #define XIKeyRepeat                             (1 << 16)
diff --git a/XI2proto.h b/XI2proto.h
index 6991fda..023acc8 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -189,6 +189,22 @@ typedef struct {
     uint16_t    pad2;
 } xXIValuatorInfo;
 
+/***
+ * Denotes a scroll valuator on a device.
+ * One XIScrollInfo describes exactly one scroll valuator that must have a
+ * XIValuatorInfo struct.
+ */
+typedef struct {
+    uint16_t    type;           /**< Always ValuatorClass         */
+    uint16_t    length;         /**< Length in 4 byte units       */
+    uint16_t    sourceid;       /**< source device for this class */
+    uint16_t    number;         /**< Valuator number              */
+    uint16_t    scroll_type;    /**< ::XIScrollTypeVertical, ::XIScrollTypeHorizontal */
+    uint16_t    pad0;
+    uint32_t    flags;          /**< ::XIScrollFlagEmulate, ::XIScrollFlagPreferred   */
+    FP3232      increment;      /**< Increment for one unit of scrolling              */
+} xXIScrollInfo;
+
 /**
  * Denotes multitouch capability on a device.
  */
@@ -948,7 +964,7 @@ typedef struct
     uint16_t    deviceid;
     Time        time;
     uint32_t    detail;
-    uint16_t    pad0;
+    uint16_t    sourceid;               /**< The source device (XI 2.1) */
     uint16_t    valuators_len;          /**< Length of trailing valuator
                                              mask in 4 byte units */
     uint32_t    flags;                  /**< ::XIKeyRepeat */
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index ca72559..e555e46 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -56,9 +56,16 @@ used on applications employing the core protocol. XI2 addresses both of these
 issues by enabling devices to be both extended and core devices and providing
 device information in each event (with the exception of core events).
 
-[[intro-xi21]]
-X Input Extension version 2.1 (XI 2.1)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+2.1 Changes
+-----------
+Changes introduced by version 2.1
+
+- RawEvents are sent regardless of the grab state.
+
+2.2 Changes
+-----------
+Changes introduced by version 2.2
+
 XI 2.1 introduces support for multi-touch devices. The traditional
 pointer/keyboard approach enforced by XI 2.0 with the master/slave device
 hierarchy is not always suitable for multi-touch devices that can provide a
@@ -92,10 +99,44 @@ support for this version. Touch devices may generate emulated pointer events
 alongside XI 2.1 touch events to support older clients; see Section
 <<multitouch-processing,Touch event delivery>>.
 
+//                            ❧❧❧❧❧❧❧❧❧❧❧
+
+2. Notations used in this document
+----------------------------------
+
+Notation for requests:
+
+    ┌───
+        Name of request
+            name of request field:       type of request field
+            name of request field:       type of request field
+            ▶
+            name of reply field:         type of reply field
+    └───
+
+Notation for events:
 
-[[interop-xi1]]
-Interoperability between version 1.x and 2.0
---------------------------------------------
+    ┌───
+        Name of event
+            name of field:               type of field
+            name of field:               type of field
+    └───
+
+Complex fields are specified in the following notation:
+
+          name of field:                  COMPLEXFIELDTYPE
+
+or, if multiple of these fields exist:
+
+          name of field:                  LISTofCOMPLEXFIELDTYPE
+
+    COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
+                         name of subfield:   type of subfield }
+
+//                            ❧❧❧❧❧❧❧❧❧❧❧
+
+3. Interoperability between version 1.x and 2.0
+-----------------------------------------------
 
 There is little interaction between 1.x and 2.x versions of the X Input
 Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as
@@ -112,7 +153,7 @@ These fields include:
 - devices with a deviceid of greater than 127 are invisible to XI1 clients.
 - key events and key grabs featuring larger than 255 can only be sent to XI2
   clients.
-- no subpixel information is avialable to XI1 clients. If motion events are in
+- no subpixel information is available to XI1 clients. If motion events are in
   a subpixel range only, the server may omit these events and an XI 1.x client
   will not receive events until the pixel boundary is crossed.
 
@@ -136,6 +177,42 @@ result, only the first master pointer and master keyboard are visible to XI
 1.x clients; all other master devices are invisible and cannot be accessed
 from XI 1.x calls.
 
+3.4 Smooth scrolling
+~~~~~~~~~~~~~~~~~~~~
+
+Historically, X implemented scrolling events by using button press events:
+button 4 was one “click” of the scroll wheel upwards, button 5 was downwards,
+button 6 was one unit of scrolling left, and button 7 was one unit of scrolling
+right.  This was sufficient for scroll wheel mice, but not for touchpads which
+are able to provide scrolling events through multi-finger drag gestures, or
+simply dragging your finger along a designated strip along the side of the
+touchpad.
+
+Newer X servers may provide scrolling information through valuators to
+provide scroll events with more precision than the button events. Valuators
+for axes sending scrolling information must have one ScrollClass for each
+scrolling axis.
+
+If scrolling valuators are present on a device, the server must provide
+two-way emulation between these valuators and the legacy button events for
+each delta unit of scrolling.
+
+One unit of scrolling in either direction is considered to be equivalent to
+one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type
+Vertical sends two button press/release events for button 4. Likewise, a
+button press event for button 7 generates an event on the Horizontal
+valuator with a value of +1.0. The server may accumulate deltas of less than
+one unit of scrolling.
+
+Any server providing this behaviour marks emulated button or valuator events
+with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag
+for raw events, to hint at applications which event is a hardware event.
+
+If more than one scroll valuator of the same type is present on a device,
+the valuator marked with Preferred is used to convert legacy button events
+into scroll valuator events. If no valuator is marked Preferred or more than
+one valuator is marked with Preferred, this should be considered a driver
+bug and the behaviour is implementation-dependent.
 
 [[hierachy]]
 The Master/Slave device hierarchy
@@ -576,7 +653,7 @@ If major_version is less than 2, a BadValue error occurs.
                  name:                  LISTofCHAR8
                  classes:               LISTofCLASS }
 
-    CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, TOUCHCLASS* }
+    CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, SCROLLCLASS, TOUCHCLASS }
 
     BUTTONCLASS { type:                 ButtonClass
                   length:               CARD16
@@ -599,9 +676,22 @@ If major_version is less than 2, a BadValue error occurs.
                   min:                  FP3232
                   max:                  FP3232
                   value:                FP3232
-                  resolution:           CARD32 }
+                  resolution:           CARD32
+                  mode:                 CARD8 }
 
-    TOUCHCLASS* { type:                 TouchClass
+    SCROLLCLASS* {type:                 ScrollClass
+                  length:               CARD16
+                  sourceid:             CARD16
+                  axisnumber:           CARD16
+                  scroll_type:          SCROLLTYPE
+                  flags:                SETofSCROLLFLAGS
+                  increment:            FP3232 }
+
+    SCROLLTYPE { Vertical, Horizontal }
+
+    SCROLLFLAGS { NoEmulation, Preferred }
+
+    TOUCHCLASS† { type:                 TouchClass
                   length:               CARD16
                   sourceid:             CARD16
                   mode:                 TOUCHMODE
@@ -609,9 +699,10 @@ If major_version is less than 2, a BadValue error occurs.
                   num_props:            CARD16
                   props:                LISTofATOM }
 
-    TOUCHMODE* { DirectTouch, DependentTouch }
+    TOUCHMODE { DirectTouch, DependentTouch }
 
-* since XI 2.1
+    * since XI 2.1
+    † since XI 2.2
 
 XIQueryDevice details information about the requested input devices.
 
@@ -715,7 +806,27 @@ The following classes may occur only once: ButtonClass, KeyClass
 An axis in Relative mode may specify min and max as a hint to the
 client. If no min and max information is available, both must be 0.
 
-    XI 2.1:
+    ScrollClass:
+    type
+        Always ScrollClass.
+    axisnumber
+        Axis number that is referred to. This axis number must be listed in
+        the ValuatorClassInfo.
+    scroll_type:
+        Vertical for a vertical scrolling axis, Horizontal for a horizontal
+        scrolling axis.
+    flags:
+        A set of flags that apply to this scroll axis.
+        NoEmulation: no legacy scroll button events are generated for events
+                     on this scrolling axis.
+        Preferred: This axis is the preferred axis for emulating valuator
+                   events from legacy scroll button events.
+    increment:
+        The valuator delta equivalent to one positive unit of scrolling.
+
+A ScrollClass may only exist if the device has at least one ValuatorClass
+and each axisnumber listed in any ScrollClass. Only one ScrollClass may
+exist per ValuatorClass.
 
     TouchClass:
     type
@@ -1910,7 +2021,7 @@ master device, or by a physical device changing capabilities at runtime.
         Details the available classes provided by the device.  The order the
         classes are provided in is undefined.
 
-For a detailed description of classes, see the XQueryDevice request.
+For a detailed description of classes, see the XIQueryDevice request.
 
 [[events-deviceevent]]
     ┌───
@@ -2000,11 +2111,13 @@ KeyRelease, ButtonPress, ButtonRelease, Motion.
         KeyRepeat means that this event is for repeating purposes, and
         the physical state of the key has not changed.  This is only
         valid for KeyPress events.
-        PointerEmulated means that this event is an emulated pointer event
-        caused by a touch device. A client listening to touch events and pointer
-        events should ignore PointerEmulated events to avoid duplicate
-        processing.  This is only valid for pointer events (MotionNotify,
-        ButtonPress, ButtonRelease).
+        PointerEmulated signals that the event has been emulated from another
+        XI 2.x event for legacy client support, and that this event should
+        be ignored if the client listens for these events.  This flag is
+        set on scroll ButtonPress and RawButtonPress events (buttons 4, 5, 6
+        and 7) if a smooth-scrolling event on the Rel Vert Scroll or
+        Rel Horiz Scroll axes was also generated. It is also set on Motion,
+        ButtonPress, and ButtonRelease events generated by direct touch devices.
         TouchAccepted (for TouchEnd events only) means that the current owner
         of the touch stream has “accepted” it, and this client will not receive
         any further events from that touch sequence.
@@ -2066,6 +2179,7 @@ Touch events do not generate enter/leave events.
         RawEvent
             EVENTHEADER
             detail:                    CARD32
+            sourceid*:                 DEVICEID
             flags:                     DEVICEEVENTFLAGS
             valuators_len:             CARD16
             valuators:                 SETofVALUATORMASK
@@ -2073,19 +2187,29 @@ Touch events do not generate enter/leave events.
             axisvalues_raw:            LISTofFP3232
     └───
 
+    * since XI 2.1
+
 A RawEvent provides the information provided by the driver to the
 client. RawEvent provides both the raw data as supplied by the driver and
 transformed data as used in the server. Transformations include, but are
 not limited to, axis clipping and acceleration.
 Transformed valuator data may be equivalent to raw data. In this case,
 both raw and transformed valuator data is provided.
-RawEvents are sent exclusively to all root windows or to the client
-that grabbed the device only.
+RawEvents are sent exclusively to all root windows.
+Clients supporting XI 2.0 receive raw events when the device is not grabbed,
+or when the device is grabbed by the client but not when the device is
+grabbed by another client.
+Clients supporting XI 2.1 or later receive raw events at all times, even
+when the device is grabbed by another client.
+
 
     eventtype
         The type of event that occured on the device.
     detail
         The button number, keycode or touch ID*.
+    sourceid
+        The source device that originally generated the event. The sourceid
+        is undefined for clients not supporting XI 2.1.
     flags
         Flags as described in DeviceEvent.
     valuators_len