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

[Peter Hutterer]

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>
Reviewed-by: Yong Bakos <ybakos at humanoriented.com>
---
Changes to v1:
- indentation and typo fixes
- removed the blurb that stated the default behaviour when the event is
  missing.

 protocol/wayland.xml | 73 ++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 8 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 29b63be..780d2f4 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,71 @@
 	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 'inverted'.
+
+	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 usually 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.
+
+	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 +2251,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