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

[Peter Hutterer]

On Wed, Nov 04, 2015 at 09:57:35AM +0800, Jonas Ådahl wrote:
> On Wed, Oct 28, 2015 at 03:34:31PM +1000, Peter Hutterer wrote:
[...]
> > +    <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 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.
> 
> I like the idea of wl_pointer.frame in general, but I don't like this
> part, because enter/leave really shouldn't be seen as pointer events at
> all. For example a window closing because of whatever reason will result
> in a wl_pointer.enter on the window that happened to be below. This has
> nothing to do with the pointer device, it is just about the pointer
> focus.
> 
> The reason you have made the enter/leave events be dispatched state
> events to the frame event is, as you wrote above, to make it possible
> for extensions to extend the enter/leave events, but they can already do
> so by making those extensions latched events appending state to the
> enter or leave events. If we need to make some extension that adds
> something to receiving or loosing focus, I think they'd be worth their
> own events with their own semantics.

I understand it's not pretty for the enter/leave semantics, but I'd argue
that it's potentially more confusing to have it to apply to all wl_pointer
events except enter/leave than just apply to all.

This way it's also a catchall event that we don't have to worry about later
down the road. Latching events is possible but again there is the
inconsistency of "everything is grouped by frame, except enter/leave which
is latched to enter/leave". And the version handling if we later need it
after all ("latch to enter until v7, otherwise use frame")


[...]

> > +    <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.
> 
> Could be worth mentioning that axis value will always be identical to
> the axis value of the associated axis event.

Added "The axis number is identical to the axis number in the associated
axis event". The term axis value is a big ambiguous since we use it to refer
to the delta.

Cheers,
   Peter