wl_tablet draft v2

[Bill Spitzak]

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