[wayland-protocols] tablet: specify the tool button numbers are simply sequentially numbered

Submitted by Peter Hutterer on Nov. 4, 2016, 1:46 a.m.

Details

Message ID 20161104014638.GA10081@jelly.local
State New
Headers show
Series "tablet: specify the tool button numbers are simply sequentially numbered" ( rev: 1 ) in Wayland

Not browsing as part of any series.

Commit Message

Peter Hutterer Nov. 4, 2016, 1:46 a.m.
We're using sequentially numbered buttons for the pad because actual tablets
are quite varied in how the present buttons (BTN_A, BTN_0, etc.). For this
reason, libinput numbers pad buttons sequentially.

Let's do the same for tablet tools. Unfortunately libinput doesn't do this, so
the mapping is up to the compositor but at least we can get the wayland
protocol right. The ony event codes a tool currently sends are BTN_STYLUS and
BTN_STYLUS2 anyway, so it's already sequentially numbered with a make-pretend
fancy name.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
This is something Carlos and I discussed at XDC, TLDR: it doesn't make much
sense sending BTN_STYLUS for a tool but button index 0 for the pad.

I didn't bump the version number here because it either
a) doesn't matter to clients
b) needs a interface version bump, but then probably a) applies
c) needs a full tablet-unstable-v3.xml but that seems excessive.

Not 100% which one of those applies, Carlos will know more since he's doing
the mutter/GTK bits. Weston doesn't care, we don't have a tablet
implementation yet.

 unstable/tablet/tablet-unstable-v2.xml | 4 ++++
 1 file changed, 4 insertions(+)

Patch hide | download patch | download mbox

diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
index 728a3df..e7a15bd 100644
--- a/unstable/tablet/tablet-unstable-v2.xml
+++ b/unstable/tablet/tablet-unstable-v2.xml
@@ -555,6 +555,8 @@ 
 	button events are generated by the compositor. See
 	wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
 	details.
+
+	Buttons are indexed sequentially, starting at button 0.
       </description>
 
       <arg name="serial" type="uint"/>
@@ -1141,6 +1143,8 @@ 
     <event name="button">
       <description summary="physical button state">
 	Sent whenever the physical state of a button changes.
+
+	Buttons are indexed sequentially, starting at button 0.
       </description>
       <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
       <arg name="button" type="uint" summary="the index of the button that changed state"/>

Comments

Hi Peter,

> On Nov 3, 2016, at 6:46 PM, Peter Hutterer <peter.hutterer@who-t.net> wrote:
> 
> We're using sequentially numbered buttons for the pad because actual tablets
> are quite varied in how the present buttons (BTN_A, BTN_0, etc.). For this
> reason, libinput numbers pad buttons sequentially.
> 
> Let's do the same for tablet tools. Unfortunately libinput doesn't do this, so
> the mapping is up to the compositor but at least we can get the wayland
> protocol right. The ony event codes a tool currently sends are BTN_STYLUS and
> BTN_STYLUS2 anyway, so it's already sequentially numbered with a make-pretend
> fancy name.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

Reviewed-by: Yong Bakos <ybakos@humanoriented.com>

(Although I defer the versioning choice to those wiser than me.)

yong


> ---
> This is something Carlos and I discussed at XDC, TLDR: it doesn't make much
> sense sending BTN_STYLUS for a tool but button index 0 for the pad.
> 
> I didn't bump the version number here because it either
> a) doesn't matter to clients
> b) needs a interface version bump, but then probably a) applies
> c) needs a full tablet-unstable-v3.xml but that seems excessive.
> 
> Not 100% which one of those applies, Carlos will know more since he's doing
> the mutter/GTK bits. Weston doesn't care, we don't have a tablet
> implementation yet.
> 
> unstable/tablet/tablet-unstable-v2.xml | 4 ++++
> 1 file changed, 4 insertions(+)
> 
> diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> index 728a3df..e7a15bd 100644
> --- a/unstable/tablet/tablet-unstable-v2.xml
> +++ b/unstable/tablet/tablet-unstable-v2.xml
> @@ -555,6 +555,8 @@
> 	button events are generated by the compositor. See
> 	wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
> 	details.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>       </description>
> 
>       <arg name="serial" type="uint"/>
> @@ -1141,6 +1143,8 @@
>     <event name="button">
>       <description summary="physical button state">
> 	Sent whenever the physical state of a button changes.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>       </description>
>       <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
>       <arg name="button" type="uint" summary="the index of the button that changed state"/>
> -- 
> 2.9.3
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
On 11/03/2016 06:46 PM, Peter Hutterer wrote:
> We're using sequentially numbered buttons for the pad because actual tablets
> are quite varied in how the present buttons (BTN_A, BTN_0, etc.). For this
> reason, libinput numbers pad buttons sequentially.
> 
> Let's do the same for tablet tools. Unfortunately libinput doesn't do this, so
> the mapping is up to the compositor but at least we can get the wayland
> protocol right. The ony event codes a tool currently sends are BTN_STYLUS and
> BTN_STYLUS2 anyway, so it's already sequentially numbered with a make-pretend
> fancy name.
> 

This sounds fine from the viewpoint of making things consistent, but I'm
a still a little hesitant about making such a change. I don't want to
throw away semantic information which could be valuable to clients. If
there's one thing I've learned from X11 and xf86-input-wacom its that
sequentially numbered buttons only work if the buttons are effectively
interchangeable (example: ExpressKeys, whose functions are arbitrarily
defined by the client; anti-example: mouse buttons, whose functions are
defined by tradition[1]).

Are the two buttons on a stylus arbitrarily interchangeable? My
immediate gut feeling is "yes"[2], but I don't want to be too hasty in
changing protocol. If a stylus is introduced with a third button that
has some specific intended functionality, is it added to the sequential
button list or do we define a new event that gets sent when that button
is pressed? Does it depend on how the kernel defines it?

I'm willing to give this an acked-by but I'd like to hear your thoughts
back first :)

> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
> ---
> This is something Carlos and I discussed at XDC, TLDR: it doesn't make much
> sense sending BTN_STYLUS for a tool but button index 0 for the pad.
> 
> I didn't bump the version number here because it either
> a) doesn't matter to clients
> b) needs a interface version bump, but then probably a) applies
> c) needs a full tablet-unstable-v3.xml but that seems excessive.
> 
> Not 100% which one of those applies, Carlos will know more since he's doing
> the mutter/GTK bits. Weston doesn't care, we don't have a tablet
> implementation yet.
> 

Shouldn't changing the starting point for button numbers from 0x14B
(BTN_STYLUS) to 0 necessitate a version change? I haven't looked at
Mutter/GTK, but my in-development Xwayland patches[3] would break from
the change.


[1]: Oh, you have a four-button mouse with left/right/forward/back
buttons? Well, I hope the last two are reported as the 6th and 7th mouse
button or else they aren't going to work right.

[2]: A couple of reasons: "BTN_STYLUS" and "BTN_STYLUS2" sound pretty
interchangeable, the buttons have no "obvious" or "traditional"
semantics, and the default right/middle mapping on Linux is opposite to
Windows but I haven't heard any complaints.

[3]: Hopefully my queue of higher-priority tasks will clear up soon(TM)
and I can get back to finishing them...

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

>  unstable/tablet/tablet-unstable-v2.xml | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> index 728a3df..e7a15bd 100644
> --- a/unstable/tablet/tablet-unstable-v2.xml
> +++ b/unstable/tablet/tablet-unstable-v2.xml
> @@ -555,6 +555,8 @@
>  	button events are generated by the compositor. See
>  	wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
>  	details.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>        </description>
>  
>        <arg name="serial" type="uint"/>
> @@ -1141,6 +1143,8 @@
>      <event name="button">
>        <description summary="physical button state">
>  	Sent whenever the physical state of a button changes.
> +
> +	Buttons are indexed sequentially, starting at button 0.
>        </description>
>        <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
>        <arg name="button" type="uint" summary="the index of the button that changed state"/>
>
On Fri, Nov 04, 2016 at 09:55:14AM -0700, Jason Gerecke wrote:
> On 11/03/2016 06:46 PM, Peter Hutterer wrote:
> > We're using sequentially numbered buttons for the pad because actual tablets
> > are quite varied in how the present buttons (BTN_A, BTN_0, etc.). For this
> > reason, libinput numbers pad buttons sequentially.
> > 
> > Let's do the same for tablet tools. Unfortunately libinput doesn't do this, so
> > the mapping is up to the compositor but at least we can get the wayland
> > protocol right. The ony event codes a tool currently sends are BTN_STYLUS and
> > BTN_STYLUS2 anyway, so it's already sequentially numbered with a make-pretend
> > fancy name.
> > 
> 
> This sounds fine from the viewpoint of making things consistent, but I'm
> a still a little hesitant about making such a change. I don't want to
> throw away semantic information which could be valuable to clients. If
> there's one thing I've learned from X11 and xf86-input-wacom its that
> sequentially numbered buttons only work if the buttons are effectively
> interchangeable (example: ExpressKeys, whose functions are arbitrarily
> defined by the client; anti-example: mouse buttons, whose functions are
> defined by tradition[1]).
> 
> Are the two buttons on a stylus arbitrarily interchangeable? My
> immediate gut feeling is "yes"[2], but I don't want to be too hasty in
> changing protocol. If a stylus is introduced with a third button that
> has some specific intended functionality, is it added to the sequential
> button list or do we define a new event that gets sent when that button
> is pressed? Does it depend on how the kernel defines it?
> 
> I'm willing to give this an acked-by but I'd like to hear your thoughts
> back first :)

ok, first, I admit, I forgot about the puck. So we have *some* semantic
information right now in that BTN_STYLUS2 is different from BTN_MIDDLE
whereas they'd both be button index 1 in the proposed protocol. Right now
you can tell by the tool type which one is which and we could encode some
requirements into the protocol, e.g. a mouse with 2 buttons has L+R, 3
buttons has LMR, etc. yep, that "urgh" feeling is correct. so let's try
something else :)

the basic problem we have is that 1) some buttons are merely numbered (pad
buttons), 2) some buttons are semantic (BTN_RIGHT) and 3) some buttons are
both (BTN_STYLUS2 is semantic and numbered).

That's one of the problem with evdev itself, everything has to be semantic
unless it fits into [BTN_0, BTN_9]. For axes that's worse because we don't
have enough north of the ABS_MISC range.

so right now I'm thinking of maybe using some *optional* semantic
labelling, though I haven't thought about it in detail just yet. Benjamin
and I shortly discussed this at XDC regarding the kernel evdev protocol but
we deferred until later.

anyway, first thought for wayland could be something like:
* buttons are sequentially numbered by default, starting at 0
* an extra wl_foo.button_name event is sent (when? who knows...) and
  contains some semantic button label. To avoid having to redefine everything
  maybe this could be similar to the keymap_format style, where we have a
  type of "xkb_v1" to signal xkb compatible. So something like:

  <enum name="button_label_format">
     <entry name="evdev" value="1" summary="linux/input.h equivalent EV_KEY descriptor, e.g. BTN_LEFT"/>
  </enum>

  <event name="button_label">
     <arg name="index" type="uint" summary="button index number">
     <arg name="label_format" type="enum" summary="button label format">
     <arg name="label" type="uint" summary="button label">
  </event>


This would fix 1 and 2 but not really 3. That would require some extra
dimension of "sequence within label". which is what we have in the pad
protocol for rings/strips, but not for buttons. Adding this to the protocol
is possible though.

The interesting bit is that this can be bolted on to the side and even for
the wl_pointer.button events. There's nothing stopping us from having a
wp_button_label_v1 protocol defined that sends events before the
wl_pointer.frame or wl_tablet_tool.frame. Which means we can even use it for
those that currently require linux/input.h code.
(or the whole thing is switched, linux/input.h is default and the button
label defines it as "just a sequential button of that type")

This is a first train of thought only so far, I assume it'll get derailed a
few times before arriving at a station.

Cheers,
   Peter


> > Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
> > ---
> > This is something Carlos and I discussed at XDC, TLDR: it doesn't make much
> > sense sending BTN_STYLUS for a tool but button index 0 for the pad.
> > 
> > I didn't bump the version number here because it either
> > a) doesn't matter to clients
> > b) needs a interface version bump, but then probably a) applies
> > c) needs a full tablet-unstable-v3.xml but that seems excessive.
> > 
> > Not 100% which one of those applies, Carlos will know more since he's doing
> > the mutter/GTK bits. Weston doesn't care, we don't have a tablet
> > implementation yet.
> > 
> 
> Shouldn't changing the starting point for button numbers from 0x14B
> (BTN_STYLUS) to 0 necessitate a version change? I haven't looked at
> Mutter/GTK, but my in-development Xwayland patches[3] would break from
> the change.
> 
> 
> [1]: Oh, you have a four-button mouse with left/right/forward/back
> buttons? Well, I hope the last two are reported as the 6th and 7th mouse
> button or else they aren't going to work right.
> 
> [2]: A couple of reasons: "BTN_STYLUS" and "BTN_STYLUS2" sound pretty
> interchangeable, the buttons have no "obvious" or "traditional"
> semantics, and the default right/middle mapping on Linux is opposite to
> Windows but I haven't heard any complaints.
> 
> [3]: Hopefully my queue of higher-priority tasks will clear up soon(TM)
> and I can get back to finishing them...
> 
> Jason
> ---
> 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....
> 
> >  unstable/tablet/tablet-unstable-v2.xml | 4 ++++
> >  1 file changed, 4 insertions(+)
> > 
> > diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> > index 728a3df..e7a15bd 100644
> > --- a/unstable/tablet/tablet-unstable-v2.xml
> > +++ b/unstable/tablet/tablet-unstable-v2.xml
> > @@ -555,6 +555,8 @@
> >  	button events are generated by the compositor. See
> >  	wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
> >  	details.
> > +
> > +	Buttons are indexed sequentially, starting at button 0.
> >        </description>
> >  
> >        <arg name="serial" type="uint"/>
> > @@ -1141,6 +1143,8 @@
> >      <event name="button">
> >        <description summary="physical button state">
> >  	Sent whenever the physical state of a button changes.
> > +
> > +	Buttons are indexed sequentially, starting at button 0.
> >        </description>
> >        <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
> >        <arg name="button" type="uint" summary="the index of the button that changed state"/>
> >