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

[Derek Foreman]

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...

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.

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