zwp_tablet_tool_v2 button definitions

[Chris Morgan]

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

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?

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

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

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

— Chris