[PATCH v6 wayland] protocol: add wl_pointer.frame, axis_source, axis_stop, and axis_discrete

Sun Nov 15 22:01:58 PST 2015

On Mon, Nov 16, 2015 at 10:57:24AM +1000, Peter Hutterer wrote:
> The frame event groups separate pointer events together. The primary use-case
> for this at the moment is diagonal scrolling - a vertical/horizontal scroll
> event can be grouped together to calculate the correct motion vector.
> Frame events group all wl_pointer events. An example sequence of motion events
> followed by a diagonal scroll followed by a button event is:
> wl_pointer.motion
> wl_pointer.frame
> wl_pointer.motion
> wl_pointer.frame
> wl_pointer.axis
> wl_pointer.axis
> wl_pointer.frame
> wl_pointer.button
> wl_pointer.frame
> 
> In the future, other extensions may insert additional information about an
> event into the frame. For example, an extension may add information about the
> physical device that generated an event into the frame. For this reason,
> enter/leave events are grouped by a frame event too.
> 
> The axis_source event determines how an axis event was generated. That enables
> clients to judge when to use kinetic scrolling. Only one axis_source event is
> allowed per frame and applies to all events in this frame.
> 
> The axis_stop event notifies a client about the termination of a scroll
> sequence, likewise needed to calculate kinetic scrolling parameters.
> Multiple axis_stop events within the same frame indicate that scrolling has
> stopped in all these axis at the same time.
> 
> The axis_discrete event provides the wheel click count. Previously the axis
> value was some hardcoded number (10), with the discrete steps this enables a
> client to differ between line-based scrolling on a mouse wheel and smooth
> scrolling with a touchpad.
> 
> We can't extend the existing wl_pointer.axis events so we introduce a new
> concept: latching events. These events (currently only axis_discrete)
> are prefixed before a wl_pointer.axis event. A client must build the full
> state of the event until the respective top-level event arrives.
> i.e. a single event frame for a diagonal scroll with discrete information may
> be:
> 
> wl_pointer.axis_source
> wl_pointer.axis_discrete
> wl_pointer.axis
> wl_pointer.axis_discrete
> wl_pointer.axis
> wl_pointer.frame
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> Reviewed-by: Carlos Garnacho <carlosg at gnome.org>

Reviewed-by: Jonas Ådahl <jadahl at gmail.com> with, as discussed on IRC,
just a couple of nits below.

> ---
> Changes to v5:
> - rewordings requested by Bryce and Jonas added (and the copyedits)
> - enum field declared as enum
> 
>  protocol/wayland.xml | 148 +++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 145 insertions(+), 3 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 9c22d45..12962a0 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1411,7 +1411,7 @@
>  
>    </interface>
>  
> -  <interface name="wl_pointer" version="3">
> +  <interface name="wl_pointer" version="5">
>      <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
> @@ -1578,9 +1578,151 @@
>        </description>
>      </request>
>  
> +    <!-- Version 5 additions -->
> +
> +    <event name="frame" since="5">
> +      <description summary="end of a pointer event sequence">
> +	Indicates the end of a set of events that logically belong together.
> +	A client is expected to accumulate the data in all events within the
> +	frame before proceeding.
> +
> +	All wl_pointer events before a wl_pointer.frame event belong
> +	logically together. For example, in a diagonal scroll motion the
> +	compositor will send an optional wl_pointer.axis_source event, two
> +	wl_pointer.axis events (horizontal and vertical) and finally a
> +	wl_pointer.frame event. The client may use this information to
> +	calculate a diagonal vector for scrolling.
> +
> +	When multiple wl_pointer.axis events occur within the same frame,
> +	the motion vector is the combined motion of all events.
> +	When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
> +	the same frame, this indicates that axis movement in one axis has
> +	stopped but continues in the other axis.
> +	When multiple wl_pointer.axis_stop events occur within in the same
> +	frame, this indicates that these axes stopped in the same instance.
> +
> +	A wl_pointer.frame event is sent for every logical event group,
> +	even if the group only contains a single wl_pointer event.
> +	Specifically, a client may get a sequence: motion, frame, button,
> +	frame, axis, frame, axis_stop, frame.
> +
> +	The wl_pointer.enter and wl_pointer.leave events are logical events
> +	generated by the compositor and not the hardware. These events are
> +	also grouped by a wl_pointer.frame.
> +      </description>
> +    </event>
> +
> +    <enum name="axis_source">
> +      <description summary="axis source types">
> +	Describes the source types for axis events. This indicates to the
> +	client how an axis event was physically generated; a client may
> +	adjust the user interface accordingly. For example, scroll events
> +	from a "finger" source may be in a smooth coordinate space with
> +	kinetic scrolling whereas a "wheel" source may be in discrete steps
> +	of a number of lines.
> +
> +	The "continuous" axis source is a device generating events in a
> +	continuous coordinate space, but using something other than a
> +	finger. One example for this source is button-based scrolling where
> +	the vertical motion of a device is converted to scroll events while
> +	a button is held down.
> +      </description>
> +      <entry name="wheel" value="0" summary="A physical wheel" />
> +      <entry name="finger" value="1" summary="Finger on a touch surface" />
> +      <entry name="continuous" value="2" summary="Continuous coordinate space"/>
> +    </enum>
> +
> +    <event name="axis_source" since="5">
> +      <description summary="axis source event">
> +	Source information for scroll and other axes.
> +
> +	This event does not occur on its own. It is sent before a
> +	wl_pointer.frame event and carries the source information for
> +	all events within that frame.
> +
> +	The source specifies how this event was generated. If the source is
> +	wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
> +	sent when the user lifts the finger off the device.
> +
> +	If the source is wl_pointer axis_source.wheel or
> +	wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
> +	or may not be sent. Whether a compositor sends a axis_stop event
> +	for these sources is hardware-specific and implementation-dependent;
> +	clients must not rely on receiving an axis_stop event for these
> +	scroll sources and should treat scroll sequences from these scroll
> +	sources as unterminated by default.
> +
> +	This event is optional. If the source is unknown for a particular
> +	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.
> +      </description>
> +      <arg name="axis_source" type="uint" enum="axis_source"/>
> +    </event>
> +
> +    <event name="axis_stop" since="5">
> +      <description summary="axis stop event">
> +	Stop notification for scroll and other axes.
> +
> +	For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
> +	is sent to notify a client that the axis sequence has terminated.
> +	This enables the client to implement kinetic scrolling.
> +	See the wl_pointer.axis_source documentation for information on when
> +	this event may be generated.
> +
> +	Any wl_pointer.axis events with the same axis_source after this
> +	event should be considered as the start of a new axis motion.
> +
> +	The timestamp is to be interpreted identical to the timestamp in the
> +	wl_pointer.axis event. The timestamp value may be the same as a
> +	preceeding wl_pointer.axis event.
> +      </description>
> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> +      <arg name="axis" type="uint" summary="the axis stopped with this event"/>
> +    </event>
> +
> +    <event name="axis_discrete" since="5">
> +      <description summary="axis click event">
> +	Discrete step information for scroll and other axes.
> +
> +	This event carries the axis value of the wl_pointer.axis event in
> +	discrete steps (e.g. mouse wheel clicks).
> +
> +	This event does not occur on its own, it is coupled with a
> +	wl_pointer.axis event that represents this axis value on a
> +	continuous scale. The protocol guarantees that each axis_discrete
> +	event is always followed by exactly one axis event within the same
> +	wl_pointer.frame.
> +	The coupled axis event is always the first axis event to follow the
> +	axis_discrete event. Note that the protocol otherwise allows for
> +	other events to occur between axis_discrete and the coupled axis
> +	event.

The mid paragraph \n's here and there personally looks a bit odd to me,
and will AFAIK be ignored when showing the generated HTML documentation.

> +
> +	This event does not occur on its own. It is sent before a
> +	wl_pointer.axis event and carries the axis value of the
> +	wl_pointer.axis event in discrete steps (e.g. mouse wheel clicks).

This paragraph repeats what was already mentioned.

Jonas

> +
> +	This event is optional; continuous scrolling devices
> +	like two-finger scrolling on touchpads do not have discrete
> +	steps and do not generate this event.
> +
> +	The discrete value carries the directional information. e.g. a value
> +	of -2 is two steps towards the negative direction of this axis.
> +
> +	The axis number is identical to the axis number in the associate
> +	axis event.
> +
> +	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
> +	not guaranteed.
> +      </description>
> +      <arg name="axis" type="uint"/>
> +      <arg name="discrete" type="int"/>
> +    </event>
>    </interface>
>  
> -  <interface name="wl_keyboard" version="4">
> +  <interface name="wl_keyboard" version="5">
>      <description summary="keyboard input device">
>        The wl_keyboard interface represents one or more keyboards
>        associated with a seat.
> @@ -1694,7 +1836,7 @@
>      </event>
>    </interface>
>  
> -  <interface name="wl_touch" version="3">
> +  <interface name="wl_touch" version="5">
>      <description summary="touchscreen input device">
>        The wl_touch interface represents a touchscreen
>        associated with a seat.
> -- 
> 2.4.3
> 