On Wed, Mar 02, 2016 at 11:06:52AM +1000, Peter Hutterer wrote: > From: Carlos Garnacho <[email protected]> > > 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). > > 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 <[email protected]> > Signed-off-by: Peter Hutterer <[email protected]> > --- > First version of a tablet pad protocol to use the buttons on the pad itself > and the rings/strips, if any. > > A couple of comments to keep in mind: > * frame events are inside ring/strip. a pad.frame would be nicer but that > would require mixing events from interface, I don't think that's a good > idea. > * the modes are simply sent as numbers and we expect the clients to update > accordingly. This comes with a couple of side-effects, unsure at this > point whether they're features or drawbacks :) > * if a client doesn't use mode switching we'll still see the LEDs cycle on > mode button press. > * the set_feedback requests is for the current mode only, the compositor > cannot know the various strings until it cycled through all modes. this > may be an issue. > * the button list is not mode-specific. a button that is mapped to a > compositor function in one specific mode only will still appear in the > list and a client may want to set features for it. There is no feedback > to the client that this doesn't work. The same goes for the ring/strip > if they're to be mapped to compositor actions. > * given the limitations of the linux/input.h event codes I'm tempted to > switch to simple button numbers for pad buttons. > > unstable/tablet/tablet-unstable-v1.xml | 424 > ++++++++++++++++++++++++++++++++- > 1 file changed, 422 insertions(+), 2 deletions(-) > > diff --git a/unstable/tablet/tablet-unstable-v1.xml > b/unstable/tablet/tablet-unstable-v1.xml > index 988f949..e23c09a 100644 > --- a/unstable/tablet/tablet-unstable-v1.xml > +++ b/unstable/tablet/tablet-unstable-v1.xml > @@ -112,7 +112,7 @@ > version number in the protocol and interface names are removed and the > interface version number is reset. > </description> > - <interface name="zwp_tablet_manager_v1" version="1"> > + <interface name="zwp_tablet_manager_v1" version="2"> > <description summary="controller object for graphic tablet devices"> > An object that provides access to the graphics tablets available on > this > system. Any tablet is associated with a seat, to get access to the > @@ -136,7 +136,7 @@ > </request> > </interface> > > - <interface name="zwp_tablet_seat_v1" version="1"> > + <interface name="zwp_tablet_seat_v1" version="2"> > <description summary="controller object for graphic tablet devices of a > seat"> > An object that provides access to the graphics tablets available on > this > seat. After binding to this interface, the compositor sends a set of > @@ -169,6 +169,23 @@ > </description> > <arg name="id" type="new_id" interface="zwp_tablet_tool_v1" > summary="the newly added tablet tool"/> > </event> > + > + <!-- version 2 additions --> > + > + <event name="pad_added" since="2"> > + <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, 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, any further features > + (buttons, strips, rings) is send through the wp_tablet_pad interface.
is sent > + </description> > + <arg name="id" type="new_id" interface="zwp_tablet_pad_v1" > summary="the newly added pad"/> > + </event> > </interface> > > <interface name="zwp_tablet_tool_v1" version="1"> > @@ -619,4 +636,407 @@ > </description> > </event> > </interface> > + > + <interface name="zwp_tablet_pad_ring_v1" version="2"> > + <description summary="pad ring"> > + A circular interaction area. > + > + Events on a ring are logically grouped by the wl_tablet_pad_ring.frame > + event. > + </description> Could you elaborate here on what exactly a 'ring' is? I assume it's the ipod style dial thingee, although from the other events I gather it's related to text input in some fashion? Even if it might be remedial, a definition of the term would likely be beneficial at this point. > + <request name="set_feedback" since="2"> > + <description summary="set compositor feedback"> > + Requests the compositor to use this feedback UTF-8 encoded string > + associated to this ring. > + > + Clients are encouraged to provide context-aware descriptions for > + the actions associated to the ring, compositors may use this > + information to offer visual feedback about the button layout > + (eg. on-screen displays). > + > + The string offered is considered user visible, general > + internationalization rules apply. > + > + This request should be issued immediately after a > + wp_tablet_pad.enter, or whenever the ring is mapped to a different > + action. > + </description> > + <arg name="description" type="string" summary="ring description"/> > + </request> > + > + <request name="destroy" type="destructor" since="2"> > + <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" since="2"> > + <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" since="2"> > + <description summary="angle changed"> > + Sent whenever the angle on a ring changes. > + > + The angle is provided in 0.01 of a degree clockwise from the logical > + north of the ring in the pad's current rotation. > + </description> > + <arg name="angle" type="uint" summary="The current angle"/> > + </event> > + > + <event name="stop" since="2"> > + <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" since="2"> > + <description summary="end of a ring event sequence"> > + Indicates the end of a set of 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 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_v1" 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> Here too a basic definition of what a strip is would be nice. "A linear interaction area" gives me a clue, but I'm not visualizing it exactly or connecting it to UI I'm already familiar with. (So I'm a luddite...) > + <request name="set_feedback" since="2"> > + <description summary="set compositor feedback"> > + Requests the compositor to use this feedback UTF-8 encoded string By 'this' you're referring to the input parameter, but might be clearer to say "use the provided feedback..." or something? > + associated to this strip. associated with this ? > + Clients are encouraged to provide context-aware descriptions for > + the actions associated to the strip, compositors may use this ditto > + information to offer visual feedback about the button layout > + (eg. on-screen displays). > + > + The string offered is considered user visible, general > + internationalization rules apply. visible; general or visible, so general > + This request should be issued immediately after a > + wp_tablet_pad.enter, or whenever the strip is mapped to a different > + action. > + </description> > + <arg name="description" type="string" summary="strip description"/> > + </request> > + > + <request name="destroy" type="destructor" since="2"> > + <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" since="2"> > + <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 the finger off the device. lifts their finger > + 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" since="2"> > + <description summary="position changed"> > + Sent whenever the position on a strip changes. > + > + The position is normalized to a range of [0, 0xFFFF], 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" since="2"> > + <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" since="2"> > + <description summary="end of a strip event sequence"> > + Indicates the end of a set of 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_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 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_v1" 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" since="2"> > + <description summary="set compositor feedback"> > + Requests the compositor to use this feedback UTF-8 encoded string > + associated to this button. associated with > + Clients are encouraged to provide context-aware descriptions for > + the actions associated to each button, compositors may use this ditto > + information to offer visual feedback on the button layout > + (e.g. on-screen displays). > + > + The feedback string is considered user visible, general > + internationalization rules apply. visible, so general > + This request should be issued immediately after a > + wp_tablet_pad.enter event or whenever a button is mapped to a > + different action. > + </description> > + <arg name="button" type="uint" summary="button code"/> > + <arg name="description" type="string" summary="button description"/> > + </request> > + > + <request name="destroy" type="destructor" since="2"> > + <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" since="2"> > + <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_tool.done event. > + </description> > + <arg name="ring" type="new_id" interface="zwp_tablet_seat_ring_v1"/> > + </event> > + > + <event name="strip" since="2"> > + <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_tool.done event. > + </description> > + <arg name="strip" type="new_id" interface="zwp_tablet_seat_strip_v1"/> > + </event> > + > + <event name="buttons" since="2"> > + <description summary="buttons announced"> > + Sent on wp_tablet_pad initialization to announce the available buttons. > + Compositors may consume some buttons for global actions, those > + will not be announced in this event (e.g. the button to switch > + between modes, if any). > + > + This event is sent in the initial burst of events before the > + wp_tablet_tool.done event. > + </description> > + <arg name="buttons" type="array" summary="the available buttons"/> > + </event> > + > + <event name="modes" since="2"> > + <description summary="buttons announced"> > + Sent on wp_tablet_pad initialization to announce that the pad > + may switch between modes. A client may use a mode to store a > + specific configuration for buttons, rings and strips and use the > + wl_tablet_pad.mode event to toggle between these configurations. > + > + Switching modes is compositor-dependent. See the wp_tablet_pad.mode > + event for more details. > + > + This event is sent in the initial burst of events before the > + wp_tablet_tool.done event. > + </description> > + <arg name="buttons" type="array" summary="the available buttons"/> > + </event> > + > + <event name="done" since="2"> > + <description summary="pad description event sequence complete"> > + This event signals the end of the initial burst of descriptive > + events. A client may consider the static description of the pad to > + be complete and finalize initialization of the pad. > + </description> > + </event> > + > + <enum name="button_state" since="2"> > + <description summary="physical button state"> > + Describes the physical state of a button which provoked the button > + event. which invoked the ? (Although I do like the mental imagery of provoking button events...) > + </description> > + <entry name="released" value="0" summary="The button is not pressed"/> > + <entry name="pressed" value="1" summary="The button is pressed"/> > + </enum> > + > + <event name="button" since="2"> > + <description summary="physical button state"> > + Sent whenever the physical state of a button changes. > + </description> > + <arg name="time" type="uint" summary="The time of the event with > millisecond granularity"/> Do you mean to say, "The time of the event in milliseconds"? > + <arg name="button" type="uint" summary="button pressed"/> > + <arg name="state" type="uint" enum="button_state"/> > + </event> > + > + <event name="mode" since="2"> > + <description summary="mode switch event"> > + Notification that the mode was switched. > + > + A mode applies to all buttons, rings and strips 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. > + > + 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 by > + assigning one or more physical buttons. For example, on a Wacom > + Intuos Pro, the button inside the ring may be assigned to switch > + between modes. > + > + If a button action in the new mode differs to the action in the > + previous mode, the client should immediately issue a > + wp_tablet_pad.set_feedback request for each changed button. differs from the action > + If a ring or button action in the new mode differs to the action in ditto > + the previous mode, the client should immediately issue a > + wp_tablet_ring.set_feedback or wp_tablet_strip.set_feedback request > + for each changed ring or strip. > + </description> > + <arg name="time" type="uint" summary="The time of the event with > millisecond granularity"/> ...in milliseconds? > + <arg name="serial" type="uint"/> > + <arg name="mode" type="uint"/> > + </event> > + > + <event name="enter" since="2"> > + <description summary="enter event"> > + Notification that this pad is focused on a certain surface. Notification that this pad is focused on the specified surface. > + </description> > + <arg name="serial" type="uint"/> > + <arg name="tablet" type="object" interface="zwp_tablet_v1" > summary="The tablet the pad is attached to"/> > + <arg name="surface" type="object" interface="wl_surface"/> > + </event> > + > + <event name="leave" since="2"> > + <description summary="enter event"> > + Notification that this pad is no longer focused on a certain > + surface. on the specified surface > + </description> > + <arg name="serial" type="uint"/> > + <arg name="surface" type="object" interface="wl_surface"/> > + </event> > + > + <event name="removed" since="2"> > + <description summary="pad removed event"> > + Sent when the pad has been removed from the system. When a tablet > + is removed, its pad(s) will be removed too. > + > + When this event is received, the client must wp_tablet_pad.destroy > + the object, and wp_tablet_pad_strip.destroy/wp_tablet_pad_ring.destroy > + on all strips/rings offered by this pad. > + </description> > + </event> > + </interface> > </protocol> > -- > 2.5.0 Bryce _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
