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

[Peter Hutterer]

After starting to write some more documentation on the smooth scrolling and
trying to implement evdev support for it, I ran into an issue. evdev
currently exports axes as the kernel labels them, allowing for clients to
know _what_ an axis is (as opposed to XI 1.x where axis 3 was pressure only
by convention, not knowledge).

The current smooth scrolling proposal does not cater for this. If we label
an axis as 'Rel Vert Scroll' axis we gain smooth scrolling but lose the
information what this axis really is on the hardware. This matters e.g. on
Intuos devices (scroll strip vs. ring).

I think the real decision on whether an axis is scrolling or not
should be a flag on the axis itself. This way we can flag REL_HWHEEL as
HorizScrolling axis.

The axis labels can be used for virtual axes such as used by synaptics but
cannot be the only decider for scrolling.
---
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>
---
 XI2proto.h         |    4 +++-
 specs/XI2proto.txt |   37 ++++++++++++++++++++++++++++---------
 2 files changed, 31 insertions(+), 10 deletions(-)

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..4e2f184 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -126,20 +126,29 @@ 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.
+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. Devices that do not have scrolling
+axes may label emulated scrolling axes with the 'Rel Vert Scroll' and 'Rel
+Horiz Scroll' axis labels. These axes must also have the VertScroll or
+HorizScroll axis flag set to mark them as scrolling valuators.
+
+If valuators flagged as 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 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.
 
+The behavior of the server if there is more than one VertScroll or more than
+one HorizScroll axes on the same device is undefined.
 
 4. The Master/Slave device hierarchy
 ------------------------------------
@@ -352,7 +361,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 +467,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