The axis_source event determines how an axis event was generated. That enables clients to judge when to use kinetic scrolling.
The axis_stop event notifies a client about the termination of a scroll sequence, likewise needed to calculate kinetic scrolling parameters. 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. To axis_frame event groups separate vertical/horizontal scroll events together. Likewise it enables axis_stop events to be grouped so that the final vector for kinetic scrolling may be calculated correctly. We can't extend the existing wl_pointer.axis events so we introduce a new concept: latching events. These events (axis_source and axis_discrete) are prefixed before a wl_pointer.axis or axis_stop event. The wl_pointer.axis_frame trails the wl_pointer.axis event and groups any preceeding events together. i.e. a sequence may be: wl_pointer.axis_source wl_pointer.axis wl_pointer.axis wl_pointer.axis_frame wl_pointer.axis_source wl_pointer.axis wl_pointer.axis_frame wl_pointer.axis_source wl_pointer.axis wl_pointer.axis_frame wl_pointer.axis_source wl_pointer.axis_stop wl_pointer.axis_stop wl_pointer.axis_frame Note how the first set includes two axis events, with the same source, the second and third set include a single axis change each, the last frame stops both axis movements in the same frame. With wl_pointer.axis_discrete added, a single event may look like this: wl_pointer.axis_source wl_pointer.axis_discrete wl_pointer.axis_axis wl_pointer.axis_frame Clients need to combine the state of all events where needed. Signed-off-by: Peter Hutterer <peter.hutte...@who-t.net> --- Changes to v3: - axis_stop contains a single axis rather than the array of axes stopped. This makes it effectively equivalent to axis, and with the axis_frame event we don't need the array, it's simpler to send multiple events. - added more documentation, see http://lists.freedesktop.org/archives/wayland-devel/2015-July/023324.html - squashed the patch for axis source/discrete/stop together with the patch adding axis frame events, updated the commit message accordingly. - xml fix, axis_discrete had the args inside the <description> tag - actually implemented this version in weston, see follow-up patch :) protocol/wayland.xml | 124 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 59819e9..c321b59 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,127 @@ </description> </request> + <!-- Version 5 additions --> + <event name="axis_frame" since="5"> + <description summary="end of axis set event"> + Indicates the end of a set of wl_pointer.axis events that logically + belong together. + + All wl_pointer.axis, wl_pointer.axis_stop, and + wl_pointer.axis_source before a wl_pointer.axis_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.axis_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. + + Only one wl_pointer.axis_source event is permitted per axis frame. + + A wl_pointer.axis_frame event is sent for every logical axis event + group, even if the group only contains a single wl_pointer.axis or + wl_pointer.axis_stop event. In other words, a client may get the + sequence: axis, axis_frame, axis, axis_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 "continous" 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.axis_frame event and carries the source information for + all events within that frame. A client is expected to accumulate the + data in all events events within the frame before proceeding. + + 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 + be sent but is not guaranteed to be sent. + + This event is optional. If the source is unknown for a particular + axis event sequence, no event is sent. + + The order of wl_pointer.axis_discrete and wl_pointer.axis_source is + not guaranteed. + </description> + <arg name="axis_source" type="uint"/> + </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 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 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 order of wl_pointer.axis_discrete and wl_pointer.axis_source is + not guaranteed. + </description> + <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 +1812,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