[PATCH v7 wayland] protocol: add wl_pointer.frame, axis_source, axis_stop, and axis_discrete
Jonas Ådahl
jadahl at gmail.com
Sun Jan 10 23:11:36 PST 2016
On Fri, Jan 08, 2016 at 02:43:10PM +1000, Peter Hutterer wrote:
> ping - can we merge this now?
I think so. If no one objects I will land this tomorrow.
Jonas
>
> 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