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

[Jonas Ådahl]

On Thu, Nov 05, 2015 at 12:21:29PM -0600, Derek Foreman wrote:
> On 04/11/15 07:24 PM, Jonas Ådahl wrote:
> > 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.
> 
> They're quite similar in that they're coming from the same protocol
> object.  What's the benefit in having a separate frame mechanism for
> enter/leave should they need extension later?
> 
> To me the focus events feel more like "seat" events than pointer events,
> but they're still coming from the pointer object...

The benefit is a clearer semantical difference, i.e. that enter/leave
are *not* regular pointer events, they are strictly focus events, and
that wl_pointer.frame frames events from the actual pointer.

> 
> FWIW I agree with Peter on this one.  I think it'll just be more
> complicated (and potentially confusing to compositor/toolkit authors?)
> to have some wl_pointer events framed by one frame event, and others
> possibly by another should we choose to extend them later.
> 
> AIUI, pointer frame was born out of wanting to be more general than axis
> frame.  If we're going to draw the line at "just some wl_pointer events
> are managed by this frame" I think I'd rather see it go back to axis_frame.

I don't think so. I think it can be useful for the relative pointer
interface for example.


Jonas

> 
> >>
> >> 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.
> 
> I think we should just state that leave/enter can't share with "input"
> events and be done with it...
> 
> > 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.
> 
> Someone without complete knowledge looking at a WAYLAND_DEBUG=1 logfile
> might interpret:
> 
> enter
> motion
> frame
> 
> in one of two different ways... (depending on whether they realize enter
> is not governed by frames or not - a naive reader would probably assume
> it's framed though, since it's coming from the same source)
> 
> enter
> frame
> motion
> frame
> 
> is unambiguous...
> 
> > 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.
> 
> I can't currently think of any reason to extend enter/leave - the only
> additional information I can think of we could send with such an event
> would be the reason it happened (hotplug, hot unplug, window open,
> window close, motion-in, motion-out) and these would seem to be useless
> to an application.
> 
> Derek
> 
> > 
> > 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
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel at lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> > 
>