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

[Peter Hutterer]

On Thu, Jun 09, 2011 at 06:26:01PM +0100, Daniel Stone wrote:
> 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>
> ---
>  specs/XI2proto.txt |   31 +++++++++++++++++++++++++++++--
>  1 files changed, 29 insertions(+), 2 deletions(-)
> 
> diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
> index 63277ca..b37c914 100644
> --- a/specs/XI2proto.txt
> +++ b/specs/XI2proto.txt
> @@ -116,7 +116,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 provided, 

s/provided/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 would send two button press/release events

s/would send/sends/

(might as well be strict about it)

> +for button 4.  Likewise, a button press event for button 7 should also generate
> +a Rel Horiz Scroll valuator event with a value of +1.0.

s/should generate/generates/

> +
> +Any server providing this behaviour should mark all button 4/5/6/7 events with

s/should mark/marks/

> +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
>  ------------------------------------
> @@ -1593,7 +1617,10 @@ KeyRelease, ButtonPress, ButtonRelease, Motion.
>          valid for KeyPress events.
>          PointerEmulated means 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 will
> +        be set on scroll ButtonPress and RawButtonPress events (buttons 4,

s/will be/is/

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net> otherwise though

Cheers,
  Peter

> +        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.5.3
> 
> _______________________________________________
> xorg-devel at lists.x.org: X.Org development
> Archives: http://lists.x.org/archives/xorg-devel
> Info: http://lists.x.org/mailman/listinfo/xorg-devel
>