[PATCH inputproto 4/4] Document smooth-scrolling support

[Peter Hutterer]

From: Daniel Stone <daniel at fooishbar.org>

Two new axes are added to support smooth scrolling: Rel Vert Scroll and
Rel Horiz Scroll.  Cumulative values of 1.0 with either magnitude on
these axes are considered to be equivalent to one legacy ButtonPress
event on the scroll buttons.

Signed-off-by: Daniel Stone <daniel at fooishbar.org>
Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 specs/XI2proto.txt |   31 +++++++++++++++++++++++++++++--
 1 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 06e09cb..5f3831e 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -115,7 +115,31 @@ XI 1.x was not designed with support for multiple master devices (see Section
 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 '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 Horiz Vert 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.
+
 
 4. The Master/Slave device hierarchy
 ------------------------------------
@@ -1572,7 +1596,10 @@ KeyRelease, ButtonPress, ButtonRelease, Motion.
         valid for KeyPress events.
         PointerEmulated signaps 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.
+        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.
 
 Modifier state in mods is detailed as follows:
 
-- 
1.7.6