zwp_tablet_tool_v2 button definitions

[Peter Hutterer]

On Sat, Mar 22, 2025 at 01:16:02PM +0530, Chris Morgan wrote:
> This is all in the context of the zwp_tablet_tool_v2 interface,
> based on implementing tablet-v2 for smithay-client-toolkit this week.
> 
> Whereas 'type' is enumerated:
> 
>     event type {
>         tool_type: uint<zwp_tablet_tool_v2.type>,
>     }
> 
>     enum type {
>         pen = 0x140,
>         eraser = 0x141,
>         brush = 0x142,
>         …
>     }
> 
> (and the values happen to correspond to linux/input-event-codes.h,
> which fact is not mentioned, for better or for worse:
> BTN_TOOL_*, except that BTN_TOOL_RUBBER is named eraser)—
> 
> Yet 'button' is just a uint, with no explanation whatsoever:
> 
>     event button {
>         …
>         /// The button whose state has changed
>         button: uint,
>         …
>     }
> 
> I was perplexed at my pen emitting 331 and 332,
> having expected something like 0 and 1, or 1 and 2;
> until I discovered the codes matched BTN_STYLUS and BTN_STYLUS2.
> 
> I found a thread on this list from the time of initial implementation:
> <https://lists.freedesktop.org/archives/wayland-devel/2016-November/031734.html>.
> The discussion revealed some of why it didn’t end up an enum,
> but seemed to kinda tail off inconclusively with a “do what you wish”,
> and we’ve ended up with input event codes, but undocumented.
> (The thread also reminded me that styli are not the only tablet tools:
> I presume mouse tools would use mouse button codes;
> and I’m curious what finger tools would do, or if there are others.)

fwiw, including the "finger" tool in the "type" enum was a mistake -
realistically this one will never be set since any finger-like tool
currently emulates a pointer instead.

And yes, the Wacom "puck" mouse and the lens cursor will give you
BTN_LEFT and friends. Neither of those are available anymore (they're
10+y old) and afaik there are no replacements so they're very much
outgoing tools.

> Some questions:
> 
>  1. Is there any canonical source of information about what codes may be used?
>     Or are these things just held together by shadowy convention and duct tape?

linux/input-event-codes.h. Realistically you will get BTN_STYLUS through
to BTN_STYLUS3 on tools (haven't seen a 4-button pen yet) and
BTN_LEFT/RIGHT/MIDDLE for the mouse. I can't remember if there are any
with more than 3 buttons, if so you will get BTN_SIDE/EXTRA/etc.

Those evdev codes are basically wrong anyway since for the vast majority
of devices the source is a numeric HID button without any context and 
BTN_SIDE is by default mapped to "back" anyway. But they are what we
have.

>  2. The web’s Pointer Events API treats eraser as a button,
>     but I get the impression that here they’d be modelled as a separate tool;
>     is this correct?
>     (My pen doesn’t have an eraser.)

Yes, erasers are a separate tool in the tablet protocol.
Erasers come in two varieties: Invert and Button. Invert is what e.g. Wacom
has on most of it's tablet where the eraser is on the tail end of the
stylus (like an eraser on a real pencil). Those have been around for
decades now and they usually have a different tool ID to the pen (check
libwacom for that). To use the eraser you obviously need to flip then
pen around and bring the eraser into proximity. Those erasers don't have
buttons, only the tip (BTN_TOUCH or pressure-based)

When (iirc) the MS Surface tablets came out a decade(-ish) ago they
came with a simpler pen that had one button mapped as an eraser. MS in
their wisdom decreed that pressing that button... flips the pen around
and brings the eraser into proximity. This is (required to be)
implemented in firmware:
https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-pen-states

Those eraser buttons use the same tool ID (though the vast majority of
devices with eraser buttons don't have tool ids anyway).

>From wayland/libinput's POV there is no difference between the two -
they're a separate tool of type eraser.

See https://gitlab.freedesktop.org/libinput/libinput/-/merge_requests/1158
for currently ongoing work to unbutton the eraser buttons but 
that won't have an effect on the API.

>  3. Can we improve the documentation in wayland-protocols,
>     to at least specify where button codes come from,
>     and which codes are expected and/or plausible?
>     (I can contribute, but need clarity on such values first.)

:thumbs up:

>  4. *Is* it possible to turn it into an enum?
>     (Depending on the strength of the customs,
>     this may not be wise even if possible.
>     But even in that case, I’m still idly curious.)

The main problem with an enum is that (afaik) it's not well handled what
happens if the value is outside the enum. Having the enum externally
managed (linux/input-event-codes.h) means we can pass them through which
realistically is what the majority of implementations do right now
anyway. Values outside do happen, if irregularly, the tablet protocol
predates BTN_STYLUS3 by almost 2y.

So I'm really not sure having those in a protocol-enum defined gains us
much. A blurb in the documentation detailing which ones an
implementation would definitely have to expect OTOH would be quite
useful.

Cheers,
  Peter