[PATCH v3 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol

[Peter Hutterer]

On Tue, May 17, 2016 at 01:30:03AM +0200, Carlos Garnacho wrote:
> Hey :),
> 
> On Wed, May 11, 2016 at 4:51 AM, Peter Hutterer
> <peter.hutterer at who-t.net> wrote:
> > From: Carlos Garnacho <carlosg at gnome.org>
> >
> > The pad's interface is similar to the tool interface, a client is notified of
> > the pad after the tablet_added event.
> >
> > The pad has three functionalities: buttons, rings and strips.
> > Buttons are fairly straightforward, rings and strips are separate interfaces
> > with a pointer-axis-like source/value/frame events.
> > The two interfaces are effectively identical but for the actual value they
> > send (degrees vs normalized position).
> >
> > Buttons are sequentially indexed starting with zero, unlike other protocols
> > where a linux/input.h-style semantic event code is used. Since we expect all
> > buttons to have client-specific functionality, an additional event tells the
> > client when a given button index is not available, usually because the
> > compositor assignes some function to it (e.g. mode switching, see below).
> >
> > Specific to the pad device is the set_feedback request which enables a client
> > to set a user-defined string to display for an OSD on the current mappings.
> > This request is available for buttons, rings and strips.
> >
> > Finally, the pad supports "modes", effectively sets of button/ring/strip
> > configurations.
> >
> > Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v2:
> > - change to v2 of the protocol
> > - various comments and suggestions for improved wording incorporated
> > - ring is in wl_fixed degrees now (was int, in 0.01 of a degree)
> > - button events changed to sequential indices
> > - new buttons_reserved event
> >
> >  unstable/tablet/tablet-unstable-v2.xml | 436 +++++++++++++++++++++++++++++++++
> >  1 file changed, 436 insertions(+)
> >

..

> > +    <event name="buttons_reserved">
> > +      <description summary="reserved button indices">
> > +       Sent on wp_tablet_pad initialization and/or at a later time to notify the
> > +       client of reserved buttons.
> > +
> > +       Compositors may consume some buttons for global actions, those
> > +       global actions will not trigger wl_tablet_pad.button events (e.g.
> > +       the button to switch between modes, if any). This event notifies the
> > +       client that some button indices are reserved by the compositor and
> > +       will not generate events visible to the client. Button indices start
> > +       at 0.
> > +
> > +       This event may is sent in the initial burst of events before the
> > +       wp_tablet_pad.done event and/or at any later time when the
> > +       compositor changes the list of reserved buttons. This event is only
> > +       sent when the compositor reserves at least one button.
> > +      </description>
> > +      <arg name="buttons_reserved" type="array" summary="the reserved button indices"/>
> > +    </event>
> > +
> > +    <event name="modes">
> 
> After some hands-on experience, I see this API in libwacom:
> 
> int libwacom_get_ring_num_modes(const WacomDevice *device);
> int libwacom_get_ring2_num_modes(const WacomDevice *device);
> int libwacom_get_strips_num_modes(const WacomDevice *device);
> 
> This makes me think, are there devices with more than one of these
> modes? In that case I guess would be better to move .modes and .mode
> to wp_tablet_pad_ring/strip than exposing the NxM combinations here. I
> guess it also means renouncing to making these modes affect anything
> else than the ring/strip.
> 
> If we move these events there, I wonder if we better add .done events
> there too, or it suffices with wp_tablet_pad.done. I'd expect all
> device characteristics to be announced before wp_tablet_pad.done
> anyway.

the only device that had two rings and modes was the 24HD and both had 4
modes iirc. that device isn't on sale anymore and given the current gen of
wacom tablets I doubt it comes back.

however, the 22hd has two touch strips at the back and two mode switch
buttons. I don't think there's much of a use-case for having different
numbers of modes but having the modes switch independently is certainly
something we should support.

the next step is then the buttons of course: on the 22hd I'd expect only the
right set of buttons to switch mode when the center button is pressed, but
the strip could/should be paird with that right set of buttons.
so we effectively need something like button groups within the pad, and the
strip/ring (and later LEDs) could be part of that button group.

The two options we have here is to either nest them within the tablet_pad
with most of the current pad events/requests move to the button group:
wp_tablet_manager
  wp_tablet_seat
    wp_tablet_pad
      wp_tablet_pad_button_group
        wp_tablet_pad_ring
        wp_tablet_pad_strip


An alternative would be to provide multiple tablet_pads for the same
physical device, one for each virtual button group. That just avoids one
nesting layer at the cost of less clarity of what belongs to what. OTOH,
does that matter? because the only case we have where can have two
physically separate pads connected to the same tablet is two EKRs.
Any opinions? I'd prefer the button group approach for its clarity even
though in 90% of the use-cases it's just a (minor) overhead.

Cheers,
   Peter