[PATCH RFC inputproto v2] Use flags for smooth scrolling, not axis labels.

[Peter Hutterer]

Using labels only to mark smooth scrolling axes disallows scrolling from
hardware events (e.g. a mouse wheel). If those axes are marked as scrolling
axes instead, the clients lose information which hardware axis this event
corresponds to.

For example, on Wacom devices, the client can benefit from smooth scrolling
on the strip or wheel event but may still require the knowledge whether the
axis is a vertical strip (e.g. Intuos3) or a absolute scrolling wheel (e.g.
Intuos4).

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
Changes to v1:
- Clarify: _emulated_ events are marked with XIPointerEmulated, not just
  button events
- Clarify: scroll valuator emulation is implementation-specific for multiple
  identical scroll valuators
- don't mention names for virtual valuators, that's an implementation detail

 XI2.h              |    4 ++++
 XI2proto.h         |    4 +++-
 specs/XI2proto.txt |   46 +++++++++++++++++++++++++++++++---------------
 3 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/XI2.h b/XI2.h
index 29ffdd1..819e68f 100644
--- a/XI2.h
+++ b/XI2.h
@@ -142,6 +142,10 @@
 #define XIButtonClass                           1
 #define XIValuatorClass                         2
 
+/* Axis flags */
+#define XIAxisVertScroll                        (1 << 0)
+#define XIAxisHorizScroll                       (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 8977e87..03ead01 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -186,9 +186,11 @@ typedef struct {
     uint8_t     mode;           /**< ModeRelative or ModeAbsolute */
     uint8_t     pad1;
     uint16_t    pad2;
+/* XI2.1:
+    uint32_t    flags;
+ */
 } xXIValuatorInfo;
 
-
 /**
  * Used to select for events on a given window.
  * Struct is followed by (mask_len * CARD8), with each bit set representing
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index b07a908..3d77467 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -126,20 +126,26 @@ 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 'Rel Vert Scroll' and 'Rel Horiz Scroll' valuators
-to provide scroll events with more precision than the button events.  If these
-valuators are present on a device, the server must provide two-way emulation
-between these valuators and the legacy button events.  A cumulative value of
-1.0 in either magnitude is considered to be equivalent to one button event for
-the legacy events, e.g., -2.0 on 'Rel Vert Scroll' sends two button
-press/release events for button 4.  Likewise, a button press event for
-button 7 generates a Rel Horiz Scroll valuator event with a value of +1.0.
-
-Any server providing this behaviour marks all button 4/5/6/7 events with the
-XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag for raw
-events, to hint that applications should be using the new valuators in
-preference to the buttons.
-
+Newer X servers may provide scrolling information through specific
+valuators to provide scroll events with more precision than the button
+events. Valuators for axes sending scrolling information should have the
+VertScroll or HorizScroll axis flag set.
+
+If scrolling valuators are present on a device, the server must provide
+two-way emulation between these valuators and the legacy button events. A
+cumulative value of 1.0 in either magnitude is considered to be equivalent
+to one button event for the legacy events, e.g. -2.0 on an axis marked with
+VertScroll sends two button press/release events for button 4. Likewise, a
+button press event for button 7 generates an event on the HorizScroll
+valuator with a value of +1.0.
+
+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.
+
+The behavior of scroll button emulation if there is more than one VertScroll
+or more than one HorizScroll axes on the same device is implementation-
+dependent.
 
 4. The Master/Slave device hierarchy
 ------------------------------------
@@ -352,7 +358,13 @@ If major_version is less than 2, a BadValue error occurs.
                   min:                  FP3232
                   max:                  FP3232
                   value:                FP3232
-                  resolution:           CARD32 }
+                  resolution:           CARD32
+                  flags*:               SETofAXISFLAGS }
+
+    * since XI 2.1
+
+    AXISFLAGS { VertScroll, HorizScroll }
+
 
 XIQueryDevice details information about the requested input devices.
 
@@ -452,6 +464,10 @@ The following classes may occur only once: ButtonClass, KeyClass
         Relative or Absolute.
     value
         Last published axis value (if mode is absolute).
+    flags
+        A set of flags describing additional axis information
+        VertScroll: This axis is a vertical scrolling axis
+        HorizScroll: This axis is a horizontal scrolling axis
 
 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.
-- 
1.7.6