Re: zwp_tablet_tool_v2 button definitions

2025-03-23 Thread 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,
> }
> 
> 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:
> .
> 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 

[ANNOUNCE] libinput 1.28.0

2025-03-23 Thread Peter Hutterer
libinput 1.28.0 is now available.

The big new feature in this release is three-finger drag for touchpads. When
enabled three fingers down on the touchpad will logically hold the left mouse
button down, any movement of the fingers then moves the pointer for a drag.
For some users this is a more precise and easier-to-trigger interaction than
e.g. tap-and-drag.

On tablets the pressure range is now correctly tracked per tablet. Previously
moving the same physical stylus between two tablets with different pressure 
ranges
caused the stylus to send incorrect pressure data.

And then we have of course the usual collection of bug fixes and
device-specific quirks.

As usual, the git shortlog is below.


José Expósito (3):
  quirks: Disable MT_TOOL_PALM for the Yoga Slim 7i Carbon
  quirks: Add Apple Magic Trackpad v2 2024
  quirks: Add Apple Magic Trackpad v2 USB-C (2024)

Kirill Primak (1):
  tablet: add missing event types in tool/pad event docs

Marge Yang (1):
  quirks: add quirk for Dell Haptics Touchpad.

Mingcong Bai (1):
  quirks: raise AttrTrackpointMultiplier for ThinkPad T470/T480/A485 to 0.75

Peter Hutterer (72):
  util: add etrace to trace to stderr
  test: log litest_checkpoint to stderr
  util: Add a multivalue special type
  test: move a switch case up for better grouping
  test: force an unnecessary abort after litest_abort_msg()
  test: implement support for parametrizing tests
  evdev: print the EV_SYN with better alignment to other messages
  test: fix a typo in a comment
  test: change the x/y type from int to double in a helper
  doc/user: link to the explanation why we can't change the tap default
  test: switch touchpad tests to use parameters
  test: change switch tests to use parameters
  test: change tap tests to use parameters
  test: switch touchpad button tests to use parameters
  test: fix --filter-params handling
  test: slightly improve the failure message for litest_assert_not_null
  Improve the event queuing debugging a bit
  tools/per-slot-delta: use dataclasses and enums
  tools/per-slot-delta: remove some duplication for axis handling
  tools/per-slot-delta: use a Point class for slot position/delta
  tools/per-slot-delta: refactor the printing of a slot
  tools/per-slot-delta: optionally show the distance to the original point
  util: add truefalse and yesno macros for easy string conversion
  test: switch the tablet tests to parametrized tests
  test: use litest_checkpoint to annotate a test case
  tablet: always unset the various statuses if we're leaving proximity
  Replace strneq() with hardcoded lengths with strstartswith()
  tools/record: record HID_BPF properties too
  test: honor NO_COLOR and FORCE_COLOR for output colorization
  test: highlight the interesting part of the backtrace
  test: a boolean parameter is always true/false
  triage-policies: update to handle a few more things in MRs as well
  test: add a litest_with_parameters helper macro
  pad: be more robust to kernel bugs of multiple EV_ABS
  test: make litest_parameters fetching more type-safe
  tools/list-devices: allow listing some devices only
  tools/list-devices: reword the man page a bit
  tools/list-devices: add helper to print aligned values
  tools/list-devices: add missing config options to the output
  test: fix litest_test_param_get_double
  test: fix the touchpad finger positions for a test
  touchpad: cancel any ongoing gesture if we're about to send a button
  gestures: rename a helper function
  gestures: localize a set of variables better
  gestures: disambiguate between a tap timeout and a hold timeout
  touchpad: implement support for three-finger drag
  gestures: if 3fg drag fingers are in a nice position, start dragging
  quirks: add quirk for the RazerBlade182024 Keyboard
  test: rename the 12WX test device short name and enum
  tablet: track pressure ranges per tablet
  test: remove duplicate empty lines from the test/ directory
  pre-commit: add a hook for checking for duplicate empty lines
  doc: fix two duplicated references
  tools: support sendevents mode in debug-events
  tools/list-devices: print vid/pid as well
  test: don't include an internal header in the totem tests
  test: add a note that the Huion PIDs are shared
  test: standardize the wacom device names
  test: stringify the LITEST_ value as the device's name
  test: mark _litest_checkpoint as printf function
  test: vary the colors in the test output a bit
  test: print events discarded while waiting for another event type
  util: add strdup_printf helper functions
  tools/debug-events: make the print_ functions return the printed string
  tools/debug-events: separate event handling from event printing
  Move the event printing out