Hey :), On Wed, May 11, 2016 at 4:51 AM, Peter Hutterer <peter.hutte...@who-t.net> wrote: > From: Carlos Garnacho <carl...@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 <carl...@gnome.org> > Signed-off-by: Peter Hutterer <peter.hutte...@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(+) > > diff --git a/unstable/tablet/tablet-unstable-v2.xml > b/unstable/tablet/tablet-unstable-v2.xml > index d3f57ff..388b4d2 100644 > --- a/unstable/tablet/tablet-unstable-v2.xml > +++ b/unstable/tablet/tablet-unstable-v2.xml > @@ -172,6 +172,22 @@ > </description> > <arg name="id" type="new_id" interface="zwp_tablet_tool_v2" > summary="the newly added tablet tool"/> > </event> > + > + <event name="pad_added"> > + <description summary="new pad notification"> > + 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; and all further > + features (buttons, strips, rings) are sent through the wp_tablet_pad > + interface. > + </description> > + <arg name="id" type="new_id" interface="zwp_tablet_pad_v2" > summary="the newly added pad"/> > + </event> > </interface> > > <interface name="zwp_tablet_tool_v2" version="1"> > @@ -636,4 +652,424 @@ > </event> > </interface> > > + <interface name="zwp_tablet_pad_ring_v2" version="1"> > + <description summary="pad ring"> > + A circular interaction area. > + > + Events on a ring are logically grouped by the wl_tablet_pad_ring.frame > + event. > + </description> > + > + <request name="set_feedback"> > + <description summary="set compositor feedback"> > + 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 an UTF-8 encoded string to be > + associated with this ring, and is considered user visible; general > + internationalization rules apply. > + </description> > + <arg name="description" type="string" summary="ring description"/> > + </request> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy the ring object"> > + This destroys the client's resource for this ring object. > + </description> > + </request> > + > + <enum name="source"> > + <description summary="ring axis source"> > + 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. > + </description> > + <entry name="finger" value="1" summary="finger"/> > + </enum> > + > + <event name="source"> > + <description summary="ring event source"> > + 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 is > + wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event > + will be sent when the user lifts the finger off the device. > + > + This event is optional. If the source is unknown for an interaction, > + no event is sent. > + </description> > + <arg name="source" type="uint" summary="the event source"/> > + </event> > + > + <event name="angle"> > + <description summary="angle changed"> > + Sent whenever the angle on a ring changes. > + > + The angle is provided in degrees clockwise from the logical > + north of the ring in the pad's current rotation. > + </description> > + <arg name="angle" type="fixed" summary="the current angle"/> > + </event> > + > + <event name="stop"> > + <description summary="interaction stopped"> > + Stop notification for ring events. > + > + For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop > + event is sent to notify a client that the interaction with the ring > + has terminated. > + This enables the client to implement kinetic scrolling. > + See the wp_tablet_pad_ring.source documentation for information on > + when this event may be generated. > + > + Any wp_tablet_pad_ring.angle events with the same source after this > + event should be considered as the start of a new interaction. > + </description> > + <arg name="source" type="uint" enum="source" summary="the event > source"/> > + </event> > + > + <event name="frame"> > + <description summary="end of a ring event sequence"> > + Indicates the end of a set of ring events that logically belong > + together. A client is expected to accumulate the data in all events > + within the frame before proceeding. > + > + All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event > belong > + logically together. For example, on termination of a finger > interaction > + on a ring the compositor will send a wp_tablet_pad_ring.source event, > + a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame > + event. > + > + A wp_tablet_pad_ring.frame event is sent for every logical event > + group, even if the group only contains a single wp_tablet_pad_ring > + event. Specifically, a client may get a sequence: angle, frame, > + angle, frame, etc. > + </description> > + <arg name="time" type="uint" summary="timestamp with millisecond > granularity"/> > + </event> > + </interface> > + > + <interface name="zwp_tablet_pad_strip_v2" version="2"> > + <description summary="pad strip"> > + A linear interaction area. > + > + Events on a strip are logically grouped by the > wl_tablet_pad_strip.frame > + event. > + </description> > + > + <request name="set_feedback"> > + <description summary="set compositor feedback"> > + Requests the compositor to use the provided feedback string > + associated with this strip. This request should be issued > + immediately after a wp_tablet_pad.enter, or whenever the strip is > + mapped to a different action. > + > + Clients are encouraged to provide context-aware descriptions for > + the actions associated with the strip, compositors may use this > + information to offer visual feedback about the button layout > + (eg. on-screen displays). > + > + The provided string 'description' is an UTF-8 encoded string to be > + associated with this ring, and is considered user visible; general > + internationalization rules apply. > + </description> > + <arg name="description" type="string" summary="strip description"/> > + </request> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy the strip object"> > + This destroys the client's resource for this strip object. > + </description> > + </request> > + > + <enum name="source"> > + <description summary="strip axis source"> > + Describes the source types for strip events. This indicates to the > + client how a strip event was physically generated; a client may > + adjust the user interface accordingly. For example, events > + from a "finger" source may trigger kinetic scrolling. > + </description> > + <entry name="finger" value="1" summary="finger"/> > + </enum> > + > + <event name="source"> > + <description summary="strip event source"> > + Source information for strip events. > + > + This event does not occur on its own. It is sent before a > + wp_tablet_pad_strip.frame event and carries the source information > + for all events within that frame. > + > + The source specifies how this event was generated. If the source is > + wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event > + will be sent when the user lifts their finger off the device. > + > + This event is optional. If the source is unknown for an interaction, > + no event is sent. > + </description> > + <arg name="source" type="uint" summary="the event source"/> > + </event> > + > + <event name="position"> > + <description summary="position changed"> > + Sent whenever the position on a strip changes. > + > + The position is normalized to a range of [0, 65535], the 0-value > + represents the top-most and/or left-most position of the strip in > + the pad's current rotation. > + </description> > + <arg name="position" type="uint" summary="the current position"/> > + </event> > + > + <event name="stop"> > + <description summary="interaction stopped"> > + Stop notification for strip events. > + > + For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop > + event is sent to notify a client that the interaction with the strip > + has terminated. This enables the client to implement kinetic > + scrolling. See the wp_tablet_pad_strip.source documentation for > + information on when this event may be generated. > + > + Any wp_tablet_pad_strip.position events with the same source after > this > + event should be considered as the start of a new interaction. > + </description> > + <arg name="source" type="uint" enum="source" summary="the event > source"/> > + </event> > + > + <event name="frame"> > + <description summary="end of a strip event sequence"> > + Indicates the end of a set of events that represent one logical > + hardware strip event. A client is expected to accumulate the data > + in all events within the frame before proceeding. > + > + All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame > event belong > + logically together. For example, on termination of a finger > interaction > + on a strip the compositor will send a wp_tablet_pad_strip.source > event, > + a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame > + event. > + > + A wp_tablet_pad_strip.frame event is sent for every logical event > + group, even if the group only contains a single wp_tablet_pad_strip > + event. Specifically, a client may get a sequence: position, frame, > + position, frame, etc. > + </description> > + <arg name="time" type="uint" summary="timestamp with millisecond > granularity"/> > + </event> > + </interface> > + > + <interface name="zwp_tablet_pad_v2" version="2"> > + <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. > + </description> > + > + <request name="set_feedback"> > + <description summary="set compositor feedback"> > + Requests the compositor to use the provided feedback string > + associated with this button. This request should be issued > + immediately after a wp_tablet_pad.enter event or whenever a button > + is mapped to a different action. > + > + Clients are encouraged to provide context-aware descriptions for > + the actions associated with each button, and compositors may use > + this information to offer visual feedback on the button layout > + (e.g. on-screen displays). > + > + The provided string 'description' is an UTF-8 encoded string to be > + associated with this ring, and is considered user visible; general > + internationalization rules apply. > + </description> > + <arg name="button" type="uint" summary="button code"/> > + <arg name="description" type="string" summary="button description"/> > + </request> > + > + <request name="destroy" type="destructor"> > + <description summary="destroy the pad object"> > + Destroy the wp_tablet_pad object. Objects created from this object > + are unaffected and should be destroyed separately. > + </description> > + </request> > + > + <event name="ring"> > + <description summary="ring announced"> > + Sent on wp_tablet_pad initialization to announce available rings. > + One event is sent for each ring available on this pad. > + > + This event is sent in the initial burst of events before the > + wp_tablet_pad.done event. This event is only sent when at least one > + ring is available. > + </description> > + <arg name="ring" type="new_id" interface="zwp_tablet_pad_ring_v2"/> > + </event> > + > + <event name="strip"> > + <description summary="strip announced"> > + Sent on wp_tablet_pad initialization to announce available strips. > + One event is sent for each strip available on this pad. > + > + This event is sent in the initial burst of events before the > + wp_tablet_pad.done event. This event is only sent when at least one > + strip is available. > + </description> > + <arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/> > + </event> > + > + <event name="buttons"> > + <description summary="buttons announced"> > + Sent on wp_tablet_pad initialization to announce the available > + buttons. > + > + This event is sent in the initial burst of events before the > + wp_tablet_pad.done event. This event is only sent when at least one > + button is available. > + </description> > + <arg name="buttons" type="int" summary="the number of buttons"/> > + </event> > + > + <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. Cheers, Carlos _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel