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.hutte...@who-t.net> > Reviewed-by: Carlos Garnacho <carl...@gnome.org>
Reviewed-by: Jonas Ådahl <jad...@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 > _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
