[RFC wayland-protocols] Add pad support to the tablet protocol
Bryce Harrington
bryce at osg.samsung.com
Fri Mar 4 21:40:09 UTC 2016
On Wed, Mar 02, 2016 at 11:06:52AM +1000, Peter Hutterer wrote:
> From: Carlos Garnacho <carlosg at 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).
>
> 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 <carlosg at gnome.org>
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
> 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
More information about the wayland-devel
mailing list