[PATCH v2 libinput 2/5] Add the LIBINPUT_DEVICE_CAP_TABLET_PAD capability and matching interface

Fri Apr 15 01:19:23 UTC 2016

On Thu, Apr 14, 2016 at 03:33:38PM -0700, Jason Gerecke wrote:
> On 04/10/2016 09:15 PM, Peter Hutterer wrote:
> > This interface handles the buttons on the physical tablet itself, including
> > the touch ring and the strip.
> > 
> > A notable difference to other libinput interfaces here is that we do not use
> > linux/input.h event codes for buttons. Instead, the buttons are merely
> > numbered sequentially, starting at button 1. This means:
> > * the API is different, instead of get_button() we have get_button_number() to
> >   drive the point home
> > * there is no seat button count. pads are inherently different devices and
> >   compositors should treat them as such. The seat button count makes sense
> >   when you want to know how many devices have BTN_LEFT down, but it makes no
> >   sense for buttons where all the semantics are handled by the compositor
> >   anyway.
> > 
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v1:
> > - squashed left-handed patch (previously separate) into this one
> > - change from linux/input.h-style button numbering to simple sequential
> >   numbers
> > - dropped the seat button count bits
> > 
> >  doc/tablet-support.dox |  31 ++++-
> >  src/libinput-private.h |  18 +++
> >  src/libinput.c         | 257 ++++++++++++++++++++++++++++++++++++++++
> >  src/libinput.h         | 313 ++++++++++++++++++++++++++++++++++++++++++++++++-
> >  src/libinput.sym       |  19 +++
> >  test/litest.c          |   9 ++
> >  tools/event-debug.c    |  81 +++++++++++++
> >  tools/event-gui.c      |   4 +
> >  8 files changed, 729 insertions(+), 3 deletions(-)
> > 
> > diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
> > index 35b9230..8bfdf58 100644
> > --- a/doc/tablet-support.dox
> > +++ b/doc/tablet-support.dox
> > @@ -8,7 +8,7 @@ Apple iPad.
> >  
> >  @image html tablet.svg "Illustration of a graphics tablet"
> >  
> > - at section tablet-tools Tablet buttons vs. tablet tools
> > + at section tablet-tools Pad buttons vs. tablet tools
> >  
> >  Most tablets provide two types of devices. The pysical tablet often provides
> >  a number of buttons and a touch ring or strip. Interaction on the drawing
> > @@ -17,6 +17,12 @@ The libinput interface exposed by devices with the @ref
> >  LIBINPUT_DEVICE_CAP_TABLET_TOOL capability applies only to events generated
> >  by tools.
> >  
> > +Buttons, rings or strips on the physical tablet hardware (the "pad") are
> > +exposed by devices with the @ref LIBINPUT_DEVICE_CAP_TABLET_PAD capability.
> > +Pad events do not require a tool to be in proximity. Note that both
> > +capabilities may exist on the same device though usually they are split
> > +across multiple kernel devices.
> > +
> >  Touch events on the tablet integrated into a screen itself are exposed
> >  through the @ref LIBINPUT_DEVICE_CAP_TOUCH capability. Touch events on a
> >  standalone tablet are exposed through the @ref LIBINPUT_DEVICE_CAP_POINTER
> > @@ -25,7 +31,7 @@ node for the touch device, resulting in a separate libinput device.
> >  See libinput_device_get_device_group() for information on how to associate
> >  the touch part with other devices exposed by the same physical hardware.
> >  
> > - at section tablet-tip Tool tip events vs. button events
> > + at section tablet-tip Tool tip events vs. tool button events
> >  
> >  The primary use of a tablet tool is to draw on the surface of the tablet.
> >  When the tool tip comes into contact with the surface, libinput sends an
> > @@ -113,6 +119,8 @@ tablets however extends further than the user may lift the mouse, i.e. the
> >  tool may not be lifted out of physical proximity. For such tools, libinput 
> >  provides software-emulated proximity. 
> >  
> > +Events from the pad do not require proximity, they may be sent any time.
> > +
> >  @section tablet-pressure-offset Pressure offset on worn-out tools
> >  
> >  When a tool is used for an extended period it can wear down physically. A
> > @@ -209,4 +217,23 @@ libinput_event_tablet_tool_get_y_transformed() the resulting value may be
> >  less than 0 or larger than the upper range provided. It is up to the caller
> >  to test for this and handle or ignore these events accordingly.
> >  
> > + at section tablet-pad-buttons Tablet pad button numbers
> > +
> > +Tablet Pad buttons are numbered sequentially, starting with button 0. Thus
> > +button numbers returned by libinput_event_tablet_pad_get_button_number()
> > +have no semantic meaning, a notable difference to the button codes returned
> > +by other libinput interfaces (e.g. libinput_event_tablet_tool_get_button()).
> > +
> > +The Linux kernel requires all input events to have semantic event codes,
> > +but generic buttons like those on a pad cannot easily be assigned semantic
> > +codes. The kernel supports generic codes in the form of BTN_0 through to
> > +BTN_9 and additional unnamed space up until code 0x10f. Additional generic
> > +buttons are available as BTN_A in the range dedicated for gamepads and
> > +joysticks. Thus, tablet with a large number of buttons have to map across
> > +two semantic ranges, have to use unnamed kernel button codes or risk leaking
> > +into an unrelated range. libinput transparently maps the kernel event codes
> > +into a sequential button range on the pad. Callers should use external
> > +sources like libwacom to associate button numbers to their position on the
> > +tablet.
> > +
> 
> Might it be a good idea to mention that although there are no semantics
> to libinput's pad buttons, some buttons may still have an expected
> default behavior (e.g. mode switch) which can be discovered through
> libwacom?

I added this paragraph:
Some buttons may have expected default behaviors. For example, on Wacom
Intuos Pro series tablets, the button inside the touch ring is expected to
switch between a mode switch. Mode switching is a feature implemented in the
caller and libinput does not provide specific handling. Callers should use
external sources like libwacom to identify which buttons have semantic
behaviors.

typos fixed as requested, thanks

Cheers,
   Peter