Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
Hi!, On Thu, Jul 7, 2016 at 11:30 PM, Jason Gerecke wrote: > 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 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 > Signed-off-by: Peter Hutterer > Reviewed-by: Jason Gerecke > --- > >> >> ... snip ... >> > + > + > + > + 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 ... >> > + > + > + > + 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 l
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
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 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 Signed-off-by: Peter Hutterer Reviewed-by: Jason Gerecke --- > > ... snip ... > + + + + 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 ... > + + + + 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...)
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
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 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 > >> Signed-off-by: Peter Hutterer > >> Reviewed-by: Jason Gerecke > >> --- > >> ... snip ... > >> + > >> + > >> + > >> + 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 ... > >> + > >> + > >> + > >> + 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. > > > > > 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
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
Hi!, On Thu, Jun 30, 2016 at 6:27 AM, Jonas Ådahl 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 >> Signed-off-by: Peter Hutterer >> Reviewed-by: Jason Gerecke >> --- >> >> Changes since v3: >> >> - Added wp_tablet_pad_group, this divides buttons/strips/rings into subsets, >> groups may have separate modes which are announced through a mode_switch >> event. >> - Added serial argument to the set_feedback requests, to be obtained from >> the wp_tablet_pad_group.mode_switch events. >> - Now that groups announce the buttons belonging to those, the >> wp_tablet_pad.buttons_reserved event has been removed in favor of implicit >> information (i.e. buttons not belonging to any group are reserved by the >> compositor). >> - Added wp_tablet_pad.path event, similar to wp_tablet.path >> - Button indices are now explicitly mentioned in docs where relevant >> - Fixed several typos and improved docs here and there >> >> unstable/tablet/tablet-unstable-v2.xml | 546 >> - >> 1 file changed, 543 insertions(+), 3 deletions(-) >> >> diff --git a/unstable/tablet/tablet-unstable-v2.xml >> b/unstable/tablet/tablet-unstable-v2.xml >> index 5248c64..63172e2 100644 >> --- a/unstable/tablet/tablet-unstable-v2.xml >> +++ b/unstable/tablet/tablet-unstable-v2.xml >> @@ -172,6 +172,22 @@ >> >>> summary="the newly added tablet tool"/> >> >> + >> + >> + >> + This event is sent whenever a new pad is known to the system. >> Typically, >> + pads are physically attached to tablets and a pad_added event is >> + sent immediately after the wp_tablet_seat.tablet_added. >> + However, some standalone pad devices logically attach to tablets at >> + runtime, and the client must wait for wp_tablet_pad.enter to know >> + the tablet a pad is attached to. >> + >> + This event only provides the object id of the pad. All further >> + features (buttons, strips, rings) are sent through the wp_tablet_pad >> + interface. >> + >> + > summary="the newly added pad"/> >> + >> >> >> >> @@ -508,9 +524,9 @@ >> >> Sent whenever the wheel on the tool emits an event. This event >> contains two values for the same axis change. The degrees value is >> - in degrees in the same orientation as the wl_pointer.vertical_scroll >> - axis. The clicks value is in discrete logical clicks of the mouse >> - wheel. This value may be zero if the movement of the wheel was less >> + in the same orientation as the wl_pointer.vertical_scroll axis. The >> + clicks value is in discrete logical clicks of the mouse wheel. This >> + value may be zero if the movement of the wheel was less > > This change seems unrelated. It indeed is... > >> than one logical click. >> >> Clients should choose either value and avoid mixing degrees and >> @@ -636,4 +652,528 @@ >> >> >> >> + >> + >> + A circular interaction area. >> + >> + Events on a ring are logically grouped by the wl_tablet_pad_ring.frame >> + event. >> + >> + >> + >> + >> + Request that the compositor use the provided feedback string >> + associated with this ring. This request should be issued immediately >> + after a wp_tablet_pad.enter, or whenever the ring is mapped to a >> + different action. >> + >> + Clients are encouraged to provide context-aware descriptions for >> + the actions associated with the ring; compositors may use this >> + information to offer visual feedback about the button layout >> + (eg. on-screen displays). >> + >> + The provided s
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
Hi!, On Thu, Jun 30, 2016 at 5:27 AM, Peter Hutterer 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 >> Signed-off-by: Peter Hutterer >> Reviewed-by: Jason Gerecke >> --- >> >> Changes since v3: >> >> - Added wp_tablet_pad_group, this divides buttons/strips/rings into subsets, >> groups may have separate modes which are announced through a mode_switch >> event. >> - Added serial argument to the set_feedback requests, to be obtained from >> the wp_tablet_pad_group.mode_switch events. >> - Now that groups announce the buttons belonging to those, the >> wp_tablet_pad.buttons_reserved event has been removed in favor of implicit >> information (i.e. buttons not belonging to any group are reserved by the >> compositor). >> - Added wp_tablet_pad.path event, similar to wp_tablet.path >> - Button indices are now explicitly mentioned in docs where relevant >> - Fixed several typos and improved docs here and there >> >> unstable/tablet/tablet-unstable-v2.xml | 546 >> - >> 1 file changed, 543 insertions(+), 3 deletions(-) >> >> diff --git a/unstable/tablet/tablet-unstable-v2.xml >> b/unstable/tablet/tablet-unstable-v2.xml >> index 5248c64..63172e2 100644 >> --- a/unstable/tablet/tablet-unstable-v2.xml >> +++ b/unstable/tablet/tablet-unstable-v2.xml >> @@ -172,6 +172,22 @@ >> >>> summary="the newly added tablet tool"/> >> >> + >> + >> + >> + This event is sent whenever a new pad is known to the system. >> Typically, >> + pads are physically attached to tablets and a pad_added event is >> + sent immediately after the wp_tablet_seat.tablet_added. >> + However, some standalone pad devices logically attach to tablets at >> + runtime, and the client must wait for wp_tablet_pad.enter to know >> + the tablet a pad is attached to. >> + >> + This event only provides the object id of the pad. All further >> + features (buttons, strips, rings) are sent through the wp_tablet_pad >> + interface. >> + >> + > summary="the newly added pad"/> >> + >> >> >> >> @@ -508,9 +524,9 @@ >> >> Sent whenever the wheel on the tool emits an event. This event >> contains two values for the same axis change. The degrees value is >> - in degrees in the same orientation as the wl_pointer.vertical_scroll >> - axis. The clicks value is in discrete logical clicks of the mouse >> - wheel. This value may be zero if the movement of the wheel was less >> + in the same orientation as the wl_pointer.vertical_scroll axis. The >> + clicks value is in discrete logical clicks of the mouse wheel. This >> + value may be zero if the movement of the wheel was less >> than one logical click. > > this hunk looks like rebase detritus Oops, it indeed is. Now I wonder which of your earlier patches this belonged to... >> >> Clients should choose either value and avoid mixing degrees and >> @@ -636,4 +652,528 @@ >> >> >> >> + >> + >> + A circular interaction area. > > I think it'd be best to add " such as the touch ring on the Wacom Intuos Pro > series tablets", just to save us from having to explain what a ring is ;) > Same goes for the strip. Agreed :), added that blurb as-is, and another for strips/cintiqs. > > [...] >> + >> + >> + Describes the source types for ring events. This indicates to the >> + client how a ring event was physically generated; a client may >> + adjust the user interface accordingly. For example, events >> + from a "finger" source may trigger kinetic scrolling. >> + >> + >> + >>
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
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 > Signed-off-by: Peter Hutterer > Reviewed-by: Jason Gerecke > --- > > Changes since v3: > > - Added wp_tablet_pad_group, this divides buttons/strips/rings into subsets, > groups may have separate modes which are announced through a mode_switch > event. > - Added serial argument to the set_feedback requests, to be obtained from > the wp_tablet_pad_group.mode_switch events. > - Now that groups announce the buttons belonging to those, the > wp_tablet_pad.buttons_reserved event has been removed in favor of implicit > information (i.e. buttons not belonging to any group are reserved by the > compositor). > - Added wp_tablet_pad.path event, similar to wp_tablet.path > - Button indices are now explicitly mentioned in docs where relevant > - Fixed several typos and improved docs here and there > > unstable/tablet/tablet-unstable-v2.xml | 546 > - > 1 file changed, 543 insertions(+), 3 deletions(-) > > diff --git a/unstable/tablet/tablet-unstable-v2.xml > b/unstable/tablet/tablet-unstable-v2.xml > index 5248c64..63172e2 100644 > --- a/unstable/tablet/tablet-unstable-v2.xml > +++ b/unstable/tablet/tablet-unstable-v2.xml > @@ -172,6 +172,22 @@ > > summary="the newly added tablet tool"/> > > + > + > + > + This event is sent whenever a new pad is known to the system. Typically, > + pads are physically attached to tablets and a pad_added event is > + sent immediately after the wp_tablet_seat.tablet_added. > + However, some standalone pad devices logically attach to tablets at > + runtime, and the client must wait for wp_tablet_pad.enter to know > + the tablet a pad is attached to. > + > + This event only provides the object id of the pad. All further > + features (buttons, strips, rings) are sent through the wp_tablet_pad > + interface. > + > + summary="the newly added pad"/> > + > > > > @@ -508,9 +524,9 @@ > > Sent whenever the wheel on the tool emits an event. This event > contains two values for the same axis change. The degrees value is > - in degrees in the same orientation as the wl_pointer.vertical_scroll > - axis. The clicks value is in discrete logical clicks of the mouse > - wheel. This value may be zero if the movement of the wheel was less > + in the same orientation as the wl_pointer.vertical_scroll axis. The > + clicks value is in discrete logical clicks of the mouse wheel. This > + value may be zero if the movement of the wheel was less This change seems unrelated. > than one logical click. > > Clients should choose either value and avoid mixing degrees and > @@ -636,4 +652,528 @@ > > > > + > + > + A circular interaction area. > + > + Events on a ring are logically grouped by the wl_tablet_pad_ring.frame > + event. > + > + > + > + > + Request that the compositor use the provided feedback string > + associated with this ring. This request should be issued immediately > + after a wp_tablet_pad.enter, or whenever the ring is mapped to a > + different action. > + > + Clients are encouraged to provide context-aware descriptions for > + the actions associated with the ring; compositors may use this > + information to offer visual feedback about the button layout > + (eg. on-screen displays). > + > + The provided string 'description' is a UTF-8 encoded string to be > + associated with this ring, and is considered user-visible; general > + internationalization rules apply. > + > + The se
Re: [PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
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 > Signed-off-by: Peter Hutterer > Reviewed-by: Jason Gerecke > --- > > Changes since v3: > > - Added wp_tablet_pad_group, this divides buttons/strips/rings into subsets, > groups may have separate modes which are announced through a mode_switch > event. > - Added serial argument to the set_feedback requests, to be obtained from > the wp_tablet_pad_group.mode_switch events. > - Now that groups announce the buttons belonging to those, the > wp_tablet_pad.buttons_reserved event has been removed in favor of implicit > information (i.e. buttons not belonging to any group are reserved by the > compositor). > - Added wp_tablet_pad.path event, similar to wp_tablet.path > - Button indices are now explicitly mentioned in docs where relevant > - Fixed several typos and improved docs here and there > > unstable/tablet/tablet-unstable-v2.xml | 546 > - > 1 file changed, 543 insertions(+), 3 deletions(-) > > diff --git a/unstable/tablet/tablet-unstable-v2.xml > b/unstable/tablet/tablet-unstable-v2.xml > index 5248c64..63172e2 100644 > --- a/unstable/tablet/tablet-unstable-v2.xml > +++ b/unstable/tablet/tablet-unstable-v2.xml > @@ -172,6 +172,22 @@ > > summary="the newly added tablet tool"/> > > + > + > + > + This event is sent whenever a new pad is known to the system. Typically, > + pads are physically attached to tablets and a pad_added event is > + sent immediately after the wp_tablet_seat.tablet_added. > + However, some standalone pad devices logically attach to tablets at > + runtime, and the client must wait for wp_tablet_pad.enter to know > + the tablet a pad is attached to. > + > + This event only provides the object id of the pad. All further > + features (buttons, strips, rings) are sent through the wp_tablet_pad > + interface. > + > + summary="the newly added pad"/> > + > > > > @@ -508,9 +524,9 @@ > > Sent whenever the wheel on the tool emits an event. This event > contains two values for the same axis change. The degrees value is > - in degrees in the same orientation as the wl_pointer.vertical_scroll > - axis. The clicks value is in discrete logical clicks of the mouse > - wheel. This value may be zero if the movement of the wheel was less > + in the same orientation as the wl_pointer.vertical_scroll axis. The > + clicks value is in discrete logical clicks of the mouse wheel. This > + value may be zero if the movement of the wheel was less > than one logical click. this hunk looks like rebase detritus > > Clients should choose either value and avoid mixing degrees and > @@ -636,4 +652,528 @@ > > > > + > + > + A circular interaction area. I think it'd be best to add " such as the touch ring on the Wacom Intuos Pro series tablets", just to save us from having to explain what a ring is ;) Same goes for the strip. [...] > + > + > + Describes the source types for ring events. This indicates to the > + client how a ring event was physically generated; a client may > + adjust the user interface accordingly. For example, events > + from a "finger" source may trigger kinetic scrolling. > + > + > + > + > + > + > + Source information for ring events. > + > + This event does not occur on its own. It is sent before a > + wp_tablet_pad_ring.frame event and carries the source information > + for all events within that frame. > + > + The source specifies how this event was generated. If the source
