[RFC PATCH wayland] protocol: add wl_pointer's axis relative physical direction

Wed Aug 2 09:15:12 UTC 2017

On Tue, Aug 01, 2017 at 11:35:55AM +0100, Peter Hutterer wrote:
> This event adds the physical direction of the axis motion, relative to the
> axis event we get. Right now, when natural scrolling is enabled things like
> volume sliders move the wrong way round.
> 
> By adding the axis motion direction, we can have toolkits swap the scroll
> direction for applicable widgets, getting the right behavior on all widgets.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  protocol/wayland.xml | 76 ++++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 68 insertions(+), 8 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 29b63be..4c58589 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1651,7 +1651,7 @@
>      </request>
>     </interface>
>  
> -  <interface name="wl_seat" version="6">
> +  <interface name="wl_seat" version="7">
>      <description summary="group of input devices">
>        A seat is a group of keyboards, pointer and touch devices. This
>        object is published as a global during start up, or when such a
> @@ -1760,7 +1760,7 @@
>  
>    </interface>
>  
> -  <interface name="wl_pointer" version="6">
> +  <interface name="wl_pointer" version="7">
>      <description summary="pointer input device">
>        The wl_pointer interface represents one or more input devices,
>        such as mice, which control the pointer location and pointer_focus
> @@ -2022,8 +2022,9 @@
>  	axis event sequence, no event is sent.
>  	Only one wl_pointer.axis_source event is permitted per frame.
>  
> -	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
> -	not guaranteed.
> +	The order of wl_pointer.axis_relative_direction,
> +	wl_pointer.axis_discrete and wl_pointer.axis_source is not
> +	guaranteed.
>        </description>
>        <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
>      </event>
> @@ -2075,15 +2076,74 @@
>  	The axis number is identical to the axis number in the associated
>  	axis event.
>  
> -	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
> -	not guaranteed.
> +	The order of wl_pointer.axis_relative_direction,
> +	wl_pointer.axis_discrete and wl_pointer.axis_source is not
> +	guaranteed.
>        </description>
>        <arg name="axis" type="uint" enum="axis" summary="axis type"/>
>        <arg name="discrete" type="int" summary="number of steps"/>
>      </event>
> +
> +    <!-- Version 7 additions -->
> +    <enum name="axis_relative_direction">
> +      <description summary="axis relative direction">
> +	This specifies the direction of the physical motion that caused a
> +        wl_pointer.axis event, relative to the wl_pointer.axis direction.
> +      </description>
> +      <entry name="identical" value="0"
> +          summary="physical motion matches axis direction"/>
> +      <entry name="inverted" value="1"
> +	     summary="physical motion is the inverse of the axis direction"/>
> +    </enum>
> +
> +    <event name="axis_relative_direction" since="7">
> +      <description summary="axis relative physical direction event">
> +	Relative directional information of the entity causing the axis
> +	motion.
> +
> +	For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
> +	event specifies the movement direction of the entity causing the
> +	wl_pointer.axis event. For example:
> +	- if a user's fingers on a touchpad move down and this
> +	  causes a wl_pointer.axis vertical_scroll down event, the physical
> +	  direction is 'identical'
> +	 - if a user's fingers on a touchpad move down and this causes a
> +	  wl_pointer.axis vertical_scroll up scroll up event ('natural
> +	  scrolling'), the physical direction is 'parallel'.

I guess you mean inverted here.

> +
> +	A client may use this information to adjust scroll motion of
> +	components. Specifically, enabling natural scrolling causes the
> +	content to change direction compared to traditional scrolling.
> +	Some widgets like volume control sliders should match the physical

Could loosen up the wording here I guess, and say "may want to" as this
should be no UI designing guideline.

> +	direction regardless of whether natural scrolling is active.
> +	This event enables clients to match the scroll direction of a widget
> +	to the physical direction.
> +
> +	This event does not occur on its own, it is coupled with a
> +	wl_pointer.axis event that represents this axis value.
> +	The protocol guarantees that each axis_relative_direction event is
> +	always followed by exactly one axis event with the same
> +	axis number within the same wl_pointer.frame. Note that the protocol
> +	allows for other events to occur between the axis_relative_direction
> +	and its coupled axis event.
> +
> +	This event is optional, when not present a client should assume a
> +	relative direction of 'identical'.

I think we discussed this offline, but for the record one point
regarding this paragraph is leaving this undefined in a "should not make
any physical direction assumptions" kind of way.

Otherwise, I think this makes sense.

(There are also a couple of tabs vs spaces wars in this patch).

Jonas

> +
> +	The axis number is identical to the axis number in the associated
> +	axis event.
> +
> +	The order of wl_pointer.axis_relative_direction,
> +	wl_pointer.axis_discrete and wl_pointer.axis_source is not
> +	guaranteed.
> +      </description>
> +      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
> +      <arg name="direction" type="uint" enum="axis_relative_direction"
> +	  summary="physical direction relative to axis motion"/>
> +    </event>
>    </interface>
>  
> -  <interface name="wl_keyboard" version="6">
> +  <interface name="wl_keyboard" version="7">
>      <description summary="keyboard input device">
>        The wl_keyboard interface represents one or more keyboards
>        associated with a seat.
> @@ -2194,7 +2254,7 @@
>      </event>
>    </interface>
>  
> -  <interface name="wl_touch" version="6">
> +  <interface name="wl_touch" version="7">
>      <description summary="touchscreen input device">
>        The wl_touch interface represents a touchscreen
>        associated with a seat.
> -- 
> 2.13.3
> 