wl_tablet draft v2

[Peter Hutterer]

On Thu, Jul 17, 2014 at 11:48:03AM -0700, Bill Spitzak wrote:
> On 07/13/2014 12:17 PM, Lyude wrote:
> 
> >	- proximity_out
> >	  Sent whenever the tool leaves the proximity of the tablet or moves
> >	  out of the client surface. When the tool goes out of proximity,
> >	  button release events are sent before the initial proximity_out
> >	  event for each button that was held down before the tablet tool left
> >	  proximity. Following that, an up event will be sent if the tool was
> >	  in contact with the surface of the tablet before it went out of
> >	  proximity. In addition, axis updates always come before a
> >	  proximity-out event.
> >	  Arguments:
> >		- Name: time
> >		  Type: uint
> >		  The time of the event with millisecond granularity.
> 
> This design has the same bug as current enter/leave events (and X
> enter/leave, too): a client has to look ahead in the events if it wants to
> update highlighting without blinking. Basically it needs to see if the leave
> event is due to the pointer entering another surface it owns. Right now the
> only solution is to use a look-ahead api to peek at the events after a leave
> to see if there is an enter there. I think it would be nice if such
> look-ahead was not required by the most basic functions of a toolkit.
> 
> To fix this, proximity-out needs some kind of indicator, such as a surface
> id, so that the client can know that a proximity-in event is coming, and
> thus it can ignore the proximity-out. If the new surface id is used (and
> zero for surfaces belonging to a different client) then only one event is
> needed: proximity-changed.
> 
> >	- down
> >	  Sent when the tool makes contact with the surface of the tablet.
> >	  Arguments:
> >		- Name: time
> >		  Type: uint
> >		  The time of the event with millisecond granularity.
> >
> >	- up
> >	  Sent when the tool is no longer making contact with the surface of
> >	  the tablet.
> >		- Name: time
> >		  Type: uint
> >		  The time of the event with millisecond granularity.
> >	- button
> >	  Sent whenever a button on the tool is pressed or released.
> >	  Arguments:
> >		- Name: button
> >		  Type: uint
> >		  The button whose state has changed
> >
> >		- Name: state
> >		  Type: uint
> >		  Whether the button was pressed or released
> >
> >		- Name: time
> >		  Type: uint
> >		  The time of the event with millisecond granularity.
> 
> Why not make the tip be a "button", so these events can be unified?
> 
> A count of how many buttons are currently down would help a lot. It would
> allow recovery if an event is lost, and avoid the need for the careful

if an event is lost, you have a bug in the client and that shouldn't be
papered over. a number doesn't help you anyway, you still don't know _which_
buttons are down, so I really don't see the point of this.

if you get duplicate up or down events over the protocol that's a bug in the
compositor.

> matching of pairs of events which is consuming a lot of code in wayland and
> libinput. Such pair-enforcement is really complex and bug prone, so all
> toolkits I have seen ignore it, they just maintain a map of what buttons are
> down, and widgets are prepared to handle multiple up and down events for the
> same button. The same simplification can be done to wayland and libinput, by
> sending a count. Values of 0 (and 1 on push events) will allow a client to
> resync any errors in their map.
> 
> >Ideas:
> >- wl_tablet_tool
> >   This is something that hasn't really been decided on. Basically, the concept
> >   of this is a lot similar to the concept of how tablet tools are currently
> >   handled in libinput, we return a struct with all of the tool information
> >   inside it, instead of just providing a separate tool type variable and
> >   serial number we provide an entire object, which may or may not be easier
> >   for the client to work with.
> >	Enumerators:
> >	- wl_tablet_tool_type:
> >		- pen
> >		- eraser
> >		- brush
> >		- pencil
> >		- airbrush
> >		- finger
> >		- mouse
> >		- lens
> 
> It seems like each tool should be a different device. Ie the api should
> support the entry of two different tools, and the pushing of the tip of both
> of them. The above api does not, because the push event does not indicate
> which tool.

tablets don't have multiple tools in-prox at the same time, so the tool
currently in proximity is the one generating the event. If you swap from pen
to airbrush you get a prox out, then a prox in.

Cheers,
   Peter