[PATCH v2 wayland-protocols] Add pad support to the tablet protocol
Bryce Harrington
bryce at osg.samsung.com
Thu Apr 21 18:55:49 UTC 2016
On Tue, Apr 19, 2016 at 03:00:38PM +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>
Looks pretty good. A few grammar suggestions below. With those fixed,
Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
> Changes to v1:
> - typos fixed
>
> unstable/tablet/tablet-unstable-v1.xml | 423 ++++++++++++++++++++++++++++++++-
> 1 file changed, 421 insertions(+), 2 deletions(-)
>
> diff --git a/unstable/tablet/tablet-unstable-v1.xml b/unstable/tablet/tablet-unstable-v1.xml
> index 907126c..36b9ae8 100644
> --- a/unstable/tablet/tablet-unstable-v1.xml
> +++ b/unstable/tablet/tablet-unstable-v1.xml
> @@ -115,7 +115,7 @@
> 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. All tablets are associated with a seat, to get access to the
> @@ -139,7 +139,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
> @@ -172,6 +172,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
The comma after pad should be a semicolon.
And debatably maybe 'any' should be 'all'.
> + (buttons, strips, rings) is sent through the wp_tablet_pad interface.
are 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">
> @@ -638,4 +655,406 @@
> </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>
> +
> + <request name="set_feedback" since="2">
> + <description summary="set compositor feedback">
> + Requests the compositor to use the provided feedback UTF-8 encoded
> + string associated with this ring.
Request that the compositor use the provided...
> + Clients are encouraged to provide context-aware descriptions for
> + the actions associated with the ring, compositors may use this
semicolon after ring
> + 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 string is described both here and in the first sentence. It might
be better to move the "UTF-8 encoded string" definition out of the first
sentence and put it here. Should probably also reference the string by
its name to be totally clear; i.e. something like,
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.
Also that last bit about internationalization seems like it could be
stronger; I'm not entirely sure what you are pointing out here; are you
just indicating that the string might be in a language other than
English and/or need translation applied to it? Perhaps a pointer to a
reference would help here.
Also, this makes me wonder if we do need to call out the
internationalization rules for this string, are there other strings in
our protocols that should be similarly flagged? If so, we might want to
have a standard reference to point to; if not, then maybe it's not
important to flag it here?
> + This request should be issued immediately after a
> + wp_tablet_pad.enter, or whenever the ring is mapped to a different
> + action.
Perhaps this sentance would fit well with the first sentence?
> + </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>
> +
> + <request name="set_feedback" since="2">
> + <description summary="set compositor feedback">
> + Requests the compositor to use the provided feedback UTF-8 encoded
> + string associated with this strip.
> +
> + 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 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 strip is mapped to a different
> + action.
Same comments as with the other setter.
> + </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 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" 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 the provided feedback UTF-8 encoded
> + string associated with this button.
> +
> + Clients are encouraged to provide context-aware descriptions for
> + the actions associated with each button, compositors may use this
> + 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.
> +
> + This request should be issued immediately after a
> + wp_tablet_pad.enter event or whenever a button is mapped to a
> + different action.
Same comments as for the other setter
> + </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.
> + </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"/>
> + <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 from the action in the
> + previous mode, the client should immediately issue a
> + wp_tablet_pad.set_feedback request for each changed button.
> +
> + If a ring or button action in the new mode differs from the action
> + in 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"/>
> + <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 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 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.
No comma needed after removed.
> + 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.
Whitespace needs a fix here.
> + </description>
> + </event>
> + </interface>
> </protocol>
> --
> 2.5.5
More information about the wayland-devel
mailing list