[PATCH v7 wayland] protocol: add wl_pointer.frame, axis_source, axis_stop, and axis_discrete
Peter Hutterer
peter.hutterer at who-t.net
Thu Jan 7 20:43:10 PST 2016
ping - can we merge this now?
On Tue, Dec 08, 2015 at 11:11:07AM +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. The axis_discrete event carries the axis
> information and the discrete value and can occur at any time in the frame
> provided it is ordered before the matching axis event. Specifically, this
> sequence is valid:
>
> wl_pointer.axis_source
> wl_pointer.axis_discrete (vert)
> wl_pointer.axis_discrete (horiz)
> wl_pointer.axis (horiz)
> wl_pointer.axis (vert)
> wl_pointer.frame
>
> Enter and leave event also trigger wl_pointer.frame events, where possible the
> compositor should group leave and subsequent enter into the same frame. This
> indicates to the client that the pointer has moved between surfaces and may
> allow a client to shortcut code otherwise triggerd by the leave or enter
> events.
>
> 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>
> Reviewed-by: Daniel Stone <daniels at collabora.com>
> Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
> Changes to v7:
> - remove notion of latching, now that we have the axis value the discrete
> event can occur any time before the coupled axis event, not just
> immediately before.
> - add documentation for enter/leave event frame grouping.
>
> Note: I left the previous rev-by in here, pls let me know where it doesn't
> apply anymore.
>
> protocol/wayland.xml | 150 +++++++++++++++++++++++++++++++++++++++++++++++++--
> 1 file changed, 147 insertions(+), 3 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index df8ed19..8a62190 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1482,7 +1482,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
> @@ -1649,9 +1649,153 @@
> </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. When a pointer moves from one
> + surface to the another, a compositor should group the
> + wl_pointer.leave event within the same wl_pointer.frame.
> + However, a client must not rely on wl_pointer.leave and
> + wl_pointer.enter being in the same wl_pointer.frame.
> + Compositor-specific policies may require the wl_pointer.leave and
> + wl_pointer.enter event being split across multiple wl_pointer.frame
> + groups.
> + </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" enum="axis" 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 with the same
> + axis number within the same wl_pointer.frame. Note that the protocol
> + allows for other events to occur between the axis_discrete and
> + its coupled axis event, including other axis_discrete or axis
> + events.
> +
> + 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" enum="axis" />
> + <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.
> @@ -1765,7 +1909,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.5.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
More information about the wayland-devel
mailing list