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

Jason Gerecke killertofu at gmail.com
Thu Jul 7 21:30:09 UTC 2016

On 06/30/2016 05:16 AM, Jonas Ådahl wrote:
> On Thu, Jun 30, 2016 at 01:10:33PM +0200, Carlos Garnacho wrote:
>> Hi!,
>> On Thu, Jun 30, 2016 at 6:27 AM, Jonas Ådahl <jadahl at gmail.com> wrote:
>>> On Tue, Jun 28, 2016 at 11:21:50PM +0200, Carlos Garnacho wrote:
>>>> 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 groups, effectively sets of button/ring/strip
>>>> configurations. Those groups may have multiple modes each, so that
>>>> users/clients may map several actions to a single element.
>>>> Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
>>>> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
>>>> Reviewed-by: Jason Gerecke <jason.gerecke at wacom.com>
>>>> ---
> ... snip ...
>>>> +
>>>> +    <event name="ring">
>>>> +      <description summary="ring announced">
>>>> +     Sent on wp_tablet_pad_group initialization to announce available rings.
>>>> +     One event is sent for each ring available on this pad group.
>>>> +
>>>> +     This event is sent in the initial burst of events before the
>>>> +     wp_tablet_pad_group.done event. This event is only sent when at least
>>>> +     one ring is available.
>>> The last sentence is redundant. It already says that there'll be one
>>> event per ring, thus no rings, no events. It also makes it slightly
>>> unclear (by the description alone) whethere multiple rings will result
>>> in multiple events.
>> Agreed, removed. As for the last part... I guess the "One event is
>> sent for each ring available..." bit makes it clear enough already?
> Yes, I think that part makes it clear. It was only the part you now
> removed that made it possible to doubt the first part for a second.
> ... snip ...
>>>> +
>>>> +    <event name="mode_switch">
>>>> +      <description summary="mode switch event">
>>>> +     Notification that the mode was switched.
>>>> +
>>>> +     A mode applies to all buttons, rings and strips in a group
>>>> +     simultaneously, but a client is not required to assign different actions
>>>> +     for each mode. For example, a client may have mode-specific button
>>>> +     mappings but map the ring to vertical scrolling in all modes. Mode
>>>> +     indices start at 0.
>>>> +
>>>> +     Switching modes is compositor-dependent. The compositor may provide
>>>> +     visual cues to the client about the mode, e.g. by toggling LEDs on
>>>> +     the tablet device. Mode-switching may be software-controlled or
>>>> +     controlled by one or more physical buttons. For example, on a Wacom
>>>> +     Intuos Pro, the button inside the ring may be assigned to switch
>>>> +     between modes.
>>>> +
>>>> +     The current mode is compositor-global, the compositor will also send
>>> Isn't it just seat global? And why would this event be on the pad group
>>> and not on the seat wide interface?
>> perhaps I should expand that first phrase :).
>> The extent of the current mode is pretty much group local, it only
>> affects the buttons/rings/strips that have been announced through this
>> group.
>> However, the current mode of every given group is global to all
>> clients. If you have a client focused with a group in mode=1, focus
>> another client, switch that group to mode=3 and go back to the first
>> client, you'll receive a .mode_switch with mode=3 after
>> wp_tablet_pad.enter.
>> This could be considered similar to keyboard modifiers, you don't
>> reset those (eg. caps lock) when focusing another client, the current
>> state is rather propagated to the newly focused client.
>> I'm replacing the beginning of that paragraph with this:
>> "Compositors will globally track the current mode that every
>> wp_tablet_pad_group has. This event will also be sent after
>> wp_tablet_pad.enter for all groups in the pad in order to..."
> I see. Any reason on why it needs to be compositor global? Couldn't that
> be a decision left to the compositor? Either way, the new wording makes
> me understand whats going on, so it now looks good to me.

...Before I forget (and before I disappear on vacation next week...)

At least at the current moment there's no particular reason the mode has
to be globally tracked. Its the policy used by libinput, but a
compositor could, if it wanted to, track the modes per-application or
based on some other policy.

Peter and Benjamin have been working on kernel patches to change how the
wacom driver handles LED switching though, and perhaps a global mode
will be required by the new API. I haven't had a spare moment to read
through the patches yet unfortunately...

Now instead of four in the eights place /
you’ve got three, ‘Cause you added one /
(That is to say, eight) to the two, /
But you can’t take seven from three, /
So you look at the sixty-fours....

>>> On the other hand, in the pad group interface it says that "The current
>>> mode logically applies to all elements in the pad group", which sounds a
>>> bit contradicting.
>> After the explanation and the change above, does this make more sense
>> to you now?
> Yes. It was all about it sounding like the mode itself was both
> compositor wide and group specific that made it confusing.
> ... snip ...
>>>> +    <description summary="a set of buttons, rings and strips">
>>>> +      A pad device is a set of buttons, rings and strips
>>>> +      usually physically present on the tablet device itself. Some
>>>> +      exceptions exist where the pad device is physically detached, e.g. the
>>>> +      Wacom ExpressKey Remote.
>>>> +
>>>> +      Pad devices have no axes that control the cursor and are generally
>>>> +      auxiliary devices to the tool devices used on the tablet surface.
>>>> +
>>>> +      A pad device has a number of static characteristics, e.g. the number
>>>> +      of rings. These capabilities are sent in an event sequence after the
>>>> +      wp_tablet_seat.pad_added event before any actual events from this pad.
>>>> +      This initial event sequence is terminated by a wp_tablet_pad.done
>>>> +      event.
>>>> +
>>>> +      All pad features (buttons, rings and strips) are logically divided into
>>>> +      groups and all pads have at least one group. The available groups are
>>>> +      notified through the wp_tablet_pad.group event; the compositor will
>>>> +      emit one event per group before emitting wp_tablet_pad.done.
>>>> +
>>>> +      Groups may have multiple modes. Modes allow clients to map multiple
>>>> +      actions to a single pad feature. Only one mode can be active per group,
>>>> +      although different groups may have different active modes.
>>> This is contradictive with the above text saying that the current mode
>>> is compositor-wide.
>> Same than above, after the rewording above, do you see any change needed here?
> No changes needed. It all makes sense now!
> Jonas
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel

More information about the wayland-devel mailing list