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

[Yong Bakos]

Hi Peter,

> On Aug 1, 2017, at 3:35 AM, Peter Hutterer <peter.hutterer at who-t.net> 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>

Other than two minor nits noted below. This is:

Reviewed-by: Yong Bakos <ybakos at humanoriented.com>

But others will certainly need to chime in here.

yong


> ---
> 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

Stray space that misaligns the dash bullet point.


> +	  wl_pointer.axis vertical_scroll up scroll up event ('natural
> +	  scrolling'), the physical direction is 'parallel'.
> +
> +	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
> +	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

This event is optional. (full stop) When not...


> +	relative direction of 'identical'.
> +
> +	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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel