[PATCH wayland-protocols] tablet: specify the tool button numbers are simply sequentially numbered

[Jason Gerecke]

On 11/03/2016 06:46 PM, Peter Hutterer wrote:
> We're using sequentially numbered buttons for the pad because actual tablets
> are quite varied in how the present buttons (BTN_A, BTN_0, etc.). For this
> reason, libinput numbers pad buttons sequentially.
> 
> Let's do the same for tablet tools. Unfortunately libinput doesn't do this, so
> the mapping is up to the compositor but at least we can get the wayland
> protocol right. The ony event codes a tool currently sends are BTN_STYLUS and
> BTN_STYLUS2 anyway, so it's already sequentially numbered with a make-pretend
> fancy name.
> 

This sounds fine from the viewpoint of making things consistent, but I'm
a still a little hesitant about making such a change. I don't want to
throw away semantic information which could be valuable to clients. If
there's one thing I've learned from X11 and xf86-input-wacom its that
sequentially numbered buttons only work if the buttons are effectively
interchangeable (example: ExpressKeys, whose functions are arbitrarily
defined by the client; anti-example: mouse buttons, whose functions are
defined by tradition[1]).

Are the two buttons on a stylus arbitrarily interchangeable? My
immediate gut feeling is "yes"[2], but I don't want to be too hasty in
changing protocol. If a stylus is introduced with a third button that
has some specific intended functionality, is it added to the sequential
button list or do we define a new event that gets sent when that button
is pressed? Does it depend on how the kernel defines it?

I'm willing to give this an acked-by but I'd like to hear your thoughts
back first :)

> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
> This is something Carlos and I discussed at XDC, TLDR: it doesn't make much
> sense sending BTN_STYLUS for a tool but button index 0 for the pad.
> 
> I didn't bump the version number here because it either
> a) doesn't matter to clients
> b) needs a interface version bump, but then probably a) applies
> c) needs a full tablet-unstable-v3.xml but that seems excessive.
> 
> Not 100% which one of those applies, Carlos will know more since he's doing
> the mutter/GTK bits. Weston doesn't care, we don't have a tablet
> implementation yet.
> 

Shouldn't changing the starting point for button numbers from 0x14B
(BTN_STYLUS) to 0 necessitate a version change? I haven't looked at
Mutter/GTK, but my in-development Xwayland patches[3] would break from
the change.


[1]: Oh, you have a four-button mouse with left/right/forward/back
buttons? Well, I hope the last two are reported as the 6th and 7th mouse
button or else they aren't going to work right.

[2]: A couple of reasons: "BTN_STYLUS" and "BTN_STYLUS2" sound pretty
interchangeable, the buttons have no "obvious" or "traditional"
semantics, and the default right/middle mapping on Linux is opposite to
Windows but I haven't heard any complaints.

[3]: Hopefully my queue of higher-priority tasks will clear up soon(TM)
and I can get back to finishing them...

Jason
---
Now instead of four in the eights place /
you’ve got three, ‘Cause you added one /
(That is to say, eight) to the two, /
But you can’t take seven from three, /
So you look at the sixty-fours....

>  unstable/tablet/tablet-unstable-v2.xml | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> index 728a3df..e7a15bd 100644
> --- a/unstable/tablet/tablet-unstable-v2.xml
> +++ b/unstable/tablet/tablet-unstable-v2.xml
> @@ -555,6 +555,8 @@
>  	button events are generated by the compositor. See
>  	wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
>  	details.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>        </description>
>  
>        <arg name="serial" type="uint"/>
> @@ -1141,6 +1143,8 @@
>      <event name="button">
>        <description summary="physical button state">
>  	Sent whenever the physical state of a button changes.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>        </description>
>        <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
>        <arg name="button" type="uint" summary="the index of the button that changed state"/>
>