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

[Jonas Ådahl]

On Thu, Nov 05, 2015 at 08:44:57AM +1000, Peter Hutterer wrote:
> 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.

I disagree. I see wl_pointer.frame to be the grouping of pointer events.
The enter/leave are pointer *focus* events, and have nothing in
particular to do with actual events from the pointer, making them
different enough to make me feel they have very little in common with
the rest of the events, thus are not suitable to be framed by
wl_pointer.frame.

> 
> 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")

I think instead we'll have to start worrying about what events can be
put inside a frame, if another conflicting event will be there, and what
events actually mean if they are part of receiving focus.

If there will ever be a latched state to enter/leave, I expect it to
either be exclusive to those, or have a big "this either extends a focus
event meaning this, or it is a pointer event/extends a pointer event
meaning that". I think that not separating these two concepts (focus
events vs actual pointer events) will just make the semantical
difference less obvious.

About needing it in the end, I can't think of a scenario where we'd
actually need it. The worst case would be that we'd have an event that
can be a latched state to two committing events where the committing
event defines what it actually means, and I don't think that's too bad.


Jonas

> 
> 
> [...]
> 
> > > +    <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