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

[Peter Hutterer]

On Fri, Nov 04, 2016 at 09:55:14AM -0700, Jason Gerecke wrote:
> 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 :)

ok, first, I admit, I forgot about the puck. So we have *some* semantic
information right now in that BTN_STYLUS2 is different from BTN_MIDDLE
whereas they'd both be button index 1 in the proposed protocol. Right now
you can tell by the tool type which one is which and we could encode some
requirements into the protocol, e.g. a mouse with 2 buttons has L+R, 3
buttons has LMR, etc. yep, that "urgh" feeling is correct. so let's try
something else :)

the basic problem we have is that 1) some buttons are merely numbered (pad
buttons), 2) some buttons are semantic (BTN_RIGHT) and 3) some buttons are
both (BTN_STYLUS2 is semantic and numbered).

That's one of the problem with evdev itself, everything has to be semantic
unless it fits into [BTN_0, BTN_9]. For axes that's worse because we don't
have enough north of the ABS_MISC range.

so right now I'm thinking of maybe using some *optional* semantic
labelling, though I haven't thought about it in detail just yet. Benjamin
and I shortly discussed this at XDC regarding the kernel evdev protocol but
we deferred until later.

anyway, first thought for wayland could be something like:
* buttons are sequentially numbered by default, starting at 0
* an extra wl_foo.button_name event is sent (when? who knows...) and
  contains some semantic button label. To avoid having to redefine everything
  maybe this could be similar to the keymap_format style, where we have a
  type of "xkb_v1" to signal xkb compatible. So something like:

  <enum name="button_label_format">
     <entry name="evdev" value="1" summary="linux/input.h equivalent EV_KEY descriptor, e.g. BTN_LEFT"/>
  </enum>

  <event name="button_label">
     <arg name="index" type="uint" summary="button index number">
     <arg name="label_format" type="enum" summary="button label format">
     <arg name="label" type="uint" summary="button label">
  </event>


This would fix 1 and 2 but not really 3. That would require some extra
dimension of "sequence within label". which is what we have in the pad
protocol for rings/strips, but not for buttons. Adding this to the protocol
is possible though.

The interesting bit is that this can be bolted on to the side and even for
the wl_pointer.button events. There's nothing stopping us from having a
wp_button_label_v1 protocol defined that sends events before the
wl_pointer.frame or wl_tablet_tool.frame. Which means we can even use it for
those that currently require linux/input.h code.
(or the whole thing is switched, linux/input.h is default and the button
label defines it as "just a sequential button of that type")

This is a first train of thought only so far, I assume it'll get derailed a
few times before arriving at a station.

Cheers,
   Peter


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