diff options
Diffstat (limited to 'thirdparty/wayland-protocols/unstable')
14 files changed, 2398 insertions, 0 deletions
diff --git a/thirdparty/wayland-protocols/unstable/idle-inhibit/README b/thirdparty/wayland-protocols/unstable/idle-inhibit/README new file mode 100644 index 0000000000..396e871626 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/idle-inhibit/README @@ -0,0 +1,4 @@ +Screensaver inhibition protocol + +Maintainers: +Bryce Harrington <bryce@osg.samsung.com> diff --git a/thirdparty/wayland-protocols/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml new file mode 100644 index 0000000000..9c06cdcba6 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="idle_inhibit_unstable_v1"> + + <copyright> + Copyright © 2015 Samsung Electronics Co., Ltd + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + </copyright> + + <interface name="zwp_idle_inhibit_manager_v1" version="1"> + <description summary="control behavior when display idles"> + This interface permits inhibiting the idle behavior such as screen + blanking, locking, and screensaving. The client binds the idle manager + globally, then creates idle-inhibitor objects for each surface. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the idle inhibitor object"> + Destroy the inhibit manager. + </description> + </request> + + <request name="create_inhibitor"> + <description summary="create a new inhibitor object"> + Create a new inhibitor object associated with the given surface. + </description> + <arg name="id" type="new_id" interface="zwp_idle_inhibitor_v1"/> + <arg name="surface" type="object" interface="wl_surface" + summary="the surface that inhibits the idle behavior"/> + </request> + + </interface> + + <interface name="zwp_idle_inhibitor_v1" version="1"> + <description summary="context object for inhibiting idle behavior"> + An idle inhibitor prevents the output that the associated surface is + visible on from being set to a state where it is not visually usable due + to lack of user interaction (e.g. blanked, dimmed, locked, set to power + save, etc.) Any screensaver processes are also blocked from displaying. + + If the surface is destroyed, unmapped, becomes occluded, loses + visibility, or otherwise becomes not visually relevant for the user, the + idle inhibitor will not be honored by the compositor; if the surface + subsequently regains visibility the inhibitor takes effect once again. + Likewise, the inhibitor isn't honored if the system was already idled at + the time the inhibitor was established, although if the system later + de-idles and re-idles the inhibitor will take effect. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the idle inhibitor object"> + Remove the inhibitor effect from the associated wl_surface. + </description> + </request> + + </interface> +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/pointer-constraints/README b/thirdparty/wayland-protocols/unstable/pointer-constraints/README new file mode 100644 index 0000000000..8a242f8d7e --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/pointer-constraints/README @@ -0,0 +1,4 @@ +Pointer constraints protocol + +Maintainers: +Jonas Ådahl <jadahl@gmail.com> diff --git a/thirdparty/wayland-protocols/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml new file mode 100644 index 0000000000..efd64b6603 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml @@ -0,0 +1,339 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="pointer_constraints_unstable_v1"> + + <copyright> + Copyright © 2014 Jonas Ådahl + Copyright © 2015 Red Hat Inc. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + </copyright> + + <description summary="protocol for constraining pointer motions"> + This protocol specifies a set of interfaces used for adding constraints to + the motion of a pointer. Possible constraints include confining pointer + motions to a given region, or locking it to its current position. + + In order to constrain the pointer, a client must first bind the global + interface "wp_pointer_constraints" which, if a compositor supports pointer + constraints, is exposed by the registry. Using the bound global object, the + client uses the request that corresponds to the type of constraint it wants + to make. See wp_pointer_constraints for more details. + + Warning! The protocol described in this file is experimental and backward + incompatible changes may be made. Backward compatible changes may be added + together with the corresponding interface version bump. Backward + incompatible changes are done by bumping the version number in the protocol + and interface names and resetting the interface version. Once the protocol + is to be declared stable, the 'z' prefix and the version number in the + protocol and interface names are removed and the interface version number is + reset. + </description> + + <interface name="zwp_pointer_constraints_v1" version="1"> + <description summary="constrain the movement of a pointer"> + The global interface exposing pointer constraining functionality. It + exposes two requests: lock_pointer for locking the pointer to its + position, and confine_pointer for locking the pointer to a region. + + The lock_pointer and confine_pointer requests create the objects + wp_locked_pointer and wp_confined_pointer respectively, and the client can + use these objects to interact with the lock. + + For any surface, only one lock or confinement may be active across all + wl_pointer objects of the same seat. If a lock or confinement is requested + when another lock or confinement is active or requested on the same surface + and with any of the wl_pointer objects of the same seat, an + 'already_constrained' error will be raised. + </description> + + <enum name="error"> + <description summary="wp_pointer_constraints error values"> + These errors can be emitted in response to wp_pointer_constraints + requests. + </description> + <entry name="already_constrained" value="1" + summary="pointer constraint already requested on that surface"/> + </enum> + + <enum name="lifetime"> + <description summary="constraint lifetime"> + These values represent different lifetime semantics. They are passed + as arguments to the factory requests to specify how the constraint + lifetimes should be managed. + </description> + <entry name="oneshot" value="1"> + <description summary="the pointer constraint is defunct once deactivated"> + A oneshot pointer constraint will never reactivate once it has been + deactivated. See the corresponding deactivation event + (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for + details. + </description> + </entry> + <entry name="persistent" value="2"> + <description summary="the pointer constraint may reactivate"> + A persistent pointer constraint may again reactivate once it has + been deactivated. See the corresponding deactivation event + (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for + details. + </description> + </entry> + </enum> + + <request name="destroy" type="destructor"> + <description summary="destroy the pointer constraints manager object"> + Used by the client to notify the server that it will no longer use this + pointer constraints object. + </description> + </request> + + <request name="lock_pointer"> + <description summary="lock pointer to a position"> + The lock_pointer request lets the client request to disable movements of + the virtual pointer (i.e. the cursor), effectively locking the pointer + to a position. This request may not take effect immediately; in the + future, when the compositor deems implementation-specific constraints + are satisfied, the pointer lock will be activated and the compositor + sends a locked event. + + The protocol provides no guarantee that the constraints are ever + satisfied, and does not require the compositor to send an error if the + constraints cannot ever be satisfied. It is thus possible to request a + lock that will never activate. + + There may not be another pointer constraint of any kind requested or + active on the surface for any of the wl_pointer objects of the seat of + the passed pointer when requesting a lock. If there is, an error will be + raised. See general pointer lock documentation for more details. + + The intersection of the region passed with this request and the input + region of the surface is used to determine where the pointer must be + in order for the lock to activate. It is up to the compositor whether to + warp the pointer or require some kind of user interaction for the lock + to activate. If the region is null the surface input region is used. + + A surface may receive pointer focus without the lock being activated. + + The request creates a new object wp_locked_pointer which is used to + interact with the lock as well as receive updates about its state. See + the the description of wp_locked_pointer for further information. + + Note that while a pointer is locked, the wl_pointer objects of the + corresponding seat will not emit any wl_pointer.motion events, but + relative motion events will still be emitted via wp_relative_pointer + objects of the same seat. wl_pointer.axis and wl_pointer.button events + are unaffected. + </description> + <arg name="id" type="new_id" interface="zwp_locked_pointer_v1"/> + <arg name="surface" type="object" interface="wl_surface" + summary="surface to lock pointer to"/> + <arg name="pointer" type="object" interface="wl_pointer" + summary="the pointer that should be locked"/> + <arg name="region" type="object" interface="wl_region" allow-null="true" + summary="region of surface"/> + <arg name="lifetime" type="uint" enum="lifetime" summary="lock lifetime"/> + </request> + + <request name="confine_pointer"> + <description summary="confine pointer to a region"> + The confine_pointer request lets the client request to confine the + pointer cursor to a given region. This request may not take effect + immediately; in the future, when the compositor deems implementation- + specific constraints are satisfied, the pointer confinement will be + activated and the compositor sends a confined event. + + The intersection of the region passed with this request and the input + region of the surface is used to determine where the pointer must be + in order for the confinement to activate. It is up to the compositor + whether to warp the pointer or require some kind of user interaction for + the confinement to activate. If the region is null the surface input + region is used. + + The request will create a new object wp_confined_pointer which is used + to interact with the confinement as well as receive updates about its + state. See the the description of wp_confined_pointer for further + information. + </description> + <arg name="id" type="new_id" interface="zwp_confined_pointer_v1"/> + <arg name="surface" type="object" interface="wl_surface" + summary="surface to lock pointer to"/> + <arg name="pointer" type="object" interface="wl_pointer" + summary="the pointer that should be confined"/> + <arg name="region" type="object" interface="wl_region" allow-null="true" + summary="region of surface"/> + <arg name="lifetime" type="uint" enum="lifetime" summary="confinement lifetime"/> + </request> + </interface> + + <interface name="zwp_locked_pointer_v1" version="1"> + <description summary="receive relative pointer motion events"> + The wp_locked_pointer interface represents a locked pointer state. + + While the lock of this object is active, the wl_pointer objects of the + associated seat will not emit any wl_pointer.motion events. + + This object will send the event 'locked' when the lock is activated. + Whenever the lock is activated, it is guaranteed that the locked surface + will already have received pointer focus and that the pointer will be + within the region passed to the request creating this object. + + To unlock the pointer, send the destroy request. This will also destroy + the wp_locked_pointer object. + + If the compositor decides to unlock the pointer the unlocked event is + sent. See wp_locked_pointer.unlock for details. + + When unlocking, the compositor may warp the cursor position to the set + cursor position hint. If it does, it will not result in any relative + motion events emitted via wp_relative_pointer. + + If the surface the lock was requested on is destroyed and the lock is not + yet activated, the wp_locked_pointer object is now defunct and must be + destroyed. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the locked pointer object"> + Destroy the locked pointer object. If applicable, the compositor will + unlock the pointer. + </description> + </request> + + <request name="set_cursor_position_hint"> + <description summary="set the pointer cursor position hint"> + Set the cursor position hint relative to the top left corner of the + surface. + + If the client is drawing its own cursor, it should update the position + hint to the position of its own cursor. A compositor may use this + information to warp the pointer upon unlock in order to avoid pointer + jumps. + + The cursor position hint is double buffered. The new hint will only take + effect when the associated surface gets it pending state applied. See + wl_surface.commit for details. + </description> + <arg name="surface_x" type="fixed" + summary="surface-local x coordinate"/> + <arg name="surface_y" type="fixed" + summary="surface-local y coordinate"/> + </request> + + <request name="set_region"> + <description summary="set a new lock region"> + Set a new region used to lock the pointer. + + The new lock region is double-buffered. The new lock region will + only take effect when the associated surface gets its pending state + applied. See wl_surface.commit for details. + + For details about the lock region, see wp_locked_pointer. + </description> + <arg name="region" type="object" interface="wl_region" allow-null="true" + summary="region of surface"/> + </request> + + <event name="locked"> + <description summary="lock activation event"> + Notification that the pointer lock of the seat's pointer is activated. + </description> + </event> + + <event name="unlocked"> + <description summary="lock deactivation event"> + Notification that the pointer lock of the seat's pointer is no longer + active. If this is a oneshot pointer lock (see + wp_pointer_constraints.lifetime) this object is now defunct and should + be destroyed. If this is a persistent pointer lock (see + wp_pointer_constraints.lifetime) this pointer lock may again + reactivate in the future. + </description> + </event> + </interface> + + <interface name="zwp_confined_pointer_v1" version="1"> + <description summary="confined pointer object"> + The wp_confined_pointer interface represents a confined pointer state. + + This object will send the event 'confined' when the confinement is + activated. Whenever the confinement is activated, it is guaranteed that + the surface the pointer is confined to will already have received pointer + focus and that the pointer will be within the region passed to the request + creating this object. It is up to the compositor to decide whether this + requires some user interaction and if the pointer will warp to within the + passed region if outside. + + To unconfine the pointer, send the destroy request. This will also destroy + the wp_confined_pointer object. + + If the compositor decides to unconfine the pointer the unconfined event is + sent. The wp_confined_pointer object is at this point defunct and should + be destroyed. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the confined pointer object"> + Destroy the confined pointer object. If applicable, the compositor will + unconfine the pointer. + </description> + </request> + + <request name="set_region"> + <description summary="set a new confine region"> + Set a new region used to confine the pointer. + + The new confine region is double-buffered. The new confine region will + only take effect when the associated surface gets its pending state + applied. See wl_surface.commit for details. + + If the confinement is active when the new confinement region is applied + and the pointer ends up outside of newly applied region, the pointer may + warped to a position within the new confinement region. If warped, a + wl_pointer.motion event will be emitted, but no + wp_relative_pointer.relative_motion event. + + The compositor may also, instead of using the new region, unconfine the + pointer. + + For details about the confine region, see wp_confined_pointer. + </description> + <arg name="region" type="object" interface="wl_region" allow-null="true" + summary="region of surface"/> + </request> + + <event name="confined"> + <description summary="pointer confined"> + Notification that the pointer confinement of the seat's pointer is + activated. + </description> + </event> + + <event name="unconfined"> + <description summary="pointer unconfined"> + Notification that the pointer confinement of the seat's pointer is no + longer active. If this is a oneshot pointer confinement (see + wp_pointer_constraints.lifetime) this object is now defunct and should + be destroyed. If this is a persistent pointer confinement (see + wp_pointer_constraints.lifetime) this pointer confinement may again + reactivate in the future. + </description> + </event> + </interface> + +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/pointer-gestures/README b/thirdparty/wayland-protocols/unstable/pointer-gestures/README new file mode 100644 index 0000000000..a419632b0f --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/pointer-gestures/README @@ -0,0 +1,4 @@ +Pointer gestures protocol + +Maintainers: +Carlos Garnacho <carlosg@gnome.org> diff --git a/thirdparty/wayland-protocols/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml new file mode 100644 index 0000000000..f92a116059 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml @@ -0,0 +1,253 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="pointer_gestures_unstable_v1"> + + <interface name="zwp_pointer_gestures_v1" version="3"> + <description summary="touchpad gestures"> + A global interface to provide semantic touchpad gestures for a given + pointer. + + Three gestures are currently supported: swipe, pinch, and hold. + Pinch and swipe gestures follow a three-stage cycle: begin, update, + end, hold gestures follow a two-stage cycle: begin and end. All + gestures are identified by a unique id. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + </description> + + <request name="get_swipe_gesture"> + <description summary="get swipe gesture"> + Create a swipe gesture object. See the + wl_pointer_gesture_swipe interface for details. + </description> + <arg name="id" type="new_id" interface="zwp_pointer_gesture_swipe_v1"/> + <arg name="pointer" type="object" interface="wl_pointer"/> + </request> + + <request name="get_pinch_gesture"> + <description summary="get pinch gesture"> + Create a pinch gesture object. See the + wl_pointer_gesture_pinch interface for details. + </description> + <arg name="id" type="new_id" interface="zwp_pointer_gesture_pinch_v1"/> + <arg name="pointer" type="object" interface="wl_pointer"/> + </request> + + <!-- Version 2 additions --> + + <request name="release" type="destructor" since="2"> + <description summary="destroy the pointer gesture object"> + Destroy the pointer gesture object. Swipe, pinch and hold objects + created via this gesture object remain valid. + </description> + </request> + + <!-- Version 3 additions --> + + <request name="get_hold_gesture" since="3"> + <description summary="get hold gesture"> + Create a hold gesture object. See the + wl_pointer_gesture_hold interface for details. + </description> + <arg name="id" type="new_id" interface="zwp_pointer_gesture_hold_v1"/> + <arg name="pointer" type="object" interface="wl_pointer"/> + </request> + + </interface> + + <interface name="zwp_pointer_gesture_swipe_v1" version="2"> + <description summary="a swipe gesture object"> + A swipe gesture object notifies a client about a multi-finger swipe + gesture detected on an indirect input device such as a touchpad. + The gesture is usually initiated by multiple fingers moving in the + same direction but once initiated the direction may change. + The precise conditions of when such a gesture is detected are + implementation-dependent. + + A gesture consists of three stages: begin, update (optional) and end. + There cannot be multiple simultaneous hold, pinch or swipe gestures on a + same pointer/seat, how compositors prevent these situations is + implementation-dependent. + + A gesture may be cancelled by the compositor or the hardware. + Clients should not consider performing permanent or irreversible + actions until the end of a gesture has been received. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the pointer swipe gesture object"/> + </request> + + <event name="begin"> + <description summary="multi-finger swipe begin"> + This event is sent when a multi-finger swipe gesture is detected + on the device. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="fingers" type="uint" summary="number of fingers"/> + </event> + + <event name="update"> + <description summary="multi-finger swipe motion"> + This event is sent when a multi-finger swipe gesture changes the + position of the logical center. + + The dx and dy coordinates are relative coordinates of the logical + center of the gesture compared to the previous event. + </description> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/> + <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/> + </event> + + <event name="end"> + <description summary="multi-finger swipe end"> + This event is sent when a multi-finger swipe gesture ceases to + be valid. This may happen when one or more fingers are lifted or + the gesture is cancelled. + + When a gesture is cancelled, the client should undo state changes + caused by this gesture. What causes a gesture to be cancelled is + implementation-dependent. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/> + </event> + </interface> + + <interface name="zwp_pointer_gesture_pinch_v1" version="2"> + <description summary="a pinch gesture object"> + A pinch gesture object notifies a client about a multi-finger pinch + gesture detected on an indirect input device such as a touchpad. + The gesture is usually initiated by multiple fingers moving towards + each other or away from each other, or by two or more fingers rotating + around a logical center of gravity. The precise conditions of when + such a gesture is detected are implementation-dependent. + + A gesture consists of three stages: begin, update (optional) and end. + There cannot be multiple simultaneous hold, pinch or swipe gestures on a + same pointer/seat, how compositors prevent these situations is + implementation-dependent. + + A gesture may be cancelled by the compositor or the hardware. + Clients should not consider performing permanent or irreversible + actions until the end of a gesture has been received. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the pinch gesture object"/> + </request> + + <event name="begin"> + <description summary="multi-finger pinch begin"> + This event is sent when a multi-finger pinch gesture is detected + on the device. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="fingers" type="uint" summary="number of fingers"/> + </event> + + <event name="update"> + <description summary="multi-finger pinch motion"> + This event is sent when a multi-finger pinch gesture changes the + position of the logical center, the rotation or the relative scale. + + The dx and dy coordinates are relative coordinates in the + surface coordinate space of the logical center of the gesture. + + The scale factor is an absolute scale compared to the + pointer_gesture_pinch.begin event, e.g. a scale of 2 means the fingers + are now twice as far apart as on pointer_gesture_pinch.begin. + + The rotation is the relative angle in degrees clockwise compared to the previous + pointer_gesture_pinch.begin or pointer_gesture_pinch.update event. + </description> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/> + <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/> + <arg name="scale" type="fixed" summary="scale relative to the initial finger position"/> + <arg name="rotation" type="fixed" summary="angle in degrees cw relative to the previous event"/> + </event> + + <event name="end"> + <description summary="multi-finger pinch end"> + This event is sent when a multi-finger pinch gesture ceases to + be valid. This may happen when one or more fingers are lifted or + the gesture is cancelled. + + When a gesture is cancelled, the client should undo state changes + caused by this gesture. What causes a gesture to be cancelled is + implementation-dependent. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/> + </event> + + </interface> + + <interface name="zwp_pointer_gesture_hold_v1" version="3"> + <description summary="a hold gesture object"> + A hold gesture object notifies a client about a single- or + multi-finger hold gesture detected on an indirect input device such as + a touchpad. The gesture is usually initiated by one or more fingers + being held down without significant movement. The precise conditions + of when such a gesture is detected are implementation-dependent. + + In particular, this gesture may be used to cancel kinetic scrolling. + + A hold gesture consists of two stages: begin and end. Unlike pinch and + swipe there is no update stage. + There cannot be multiple simultaneous hold, pinch or swipe gestures on a + same pointer/seat, how compositors prevent these situations is + implementation-dependent. + + A gesture may be cancelled by the compositor or the hardware. + Clients should not consider performing permanent or irreversible + actions until the end of a gesture has been received. + </description> + + <request name="destroy" type="destructor" since="3"> + <description summary="destroy the hold gesture object"/> + </request> + + <event name="begin" since="3"> + <description summary="multi-finger hold begin"> + This event is sent when a hold gesture is detected on the device. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="fingers" type="uint" summary="number of fingers"/> + </event> + + <event name="end" since="3"> + <description summary="multi-finger hold end"> + This event is sent when a hold gesture ceases to + be valid. This may happen when the holding fingers are lifted or + the gesture is cancelled, for example if the fingers move past an + implementation-defined threshold, the finger count changes or the hold + gesture changes into a different type of gesture. + + When a gesture is cancelled, the client may need to undo state changes + caused by this gesture. What causes a gesture to be cancelled is + implementation-dependent. + </description> + <arg name="serial" type="uint"/> + <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> + <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/> + </event> + + </interface> +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/primary-selection/README b/thirdparty/wayland-protocols/unstable/primary-selection/README new file mode 100644 index 0000000000..ae0a4020ca --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/primary-selection/README @@ -0,0 +1,4 @@ +Primary selection protocol + +Maintainers: +Simon Ser <contact@emersion.fr> diff --git a/thirdparty/wayland-protocols/unstable/primary-selection/primary-selection-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/primary-selection/primary-selection-unstable-v1.xml new file mode 100644 index 0000000000..e5a39e34ce --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/primary-selection/primary-selection-unstable-v1.xml @@ -0,0 +1,225 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="wp_primary_selection_unstable_v1"> + <copyright> + Copyright © 2015, 2016 Red Hat + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + </copyright> + + <description summary="Primary selection protocol"> + This protocol provides the ability to have a primary selection device to + match that of the X server. This primary selection is a shortcut to the + common clipboard selection, where text just needs to be selected in order + to allow copying it elsewhere. The de facto way to perform this action + is the middle mouse button, although it is not limited to this one. + + Clients wishing to honor primary selection should create a primary + selection source and set it as the selection through + wp_primary_selection_device.set_selection whenever the text selection + changes. In order to minimize calls in pointer-driven text selection, + it should happen only once after the operation finished. Similarly, + a NULL source should be set when text is unselected. + + wp_primary_selection_offer objects are first announced through the + wp_primary_selection_device.data_offer event. Immediately after this event, + the primary data offer will emit wp_primary_selection_offer.offer events + to let know of the mime types being offered. + + When the primary selection changes, the client with the keyboard focus + will receive wp_primary_selection_device.selection events. Only the client + with the keyboard focus will receive such events with a non-NULL + wp_primary_selection_offer. Across keyboard focus changes, previously + focused clients will receive wp_primary_selection_device.events with a + NULL wp_primary_selection_offer. + + In order to request the primary selection data, the client must pass + a recent serial pertaining to the press event that is triggering the + operation, if the compositor deems the serial valid and recent, the + wp_primary_selection_source.send event will happen in the other end + to let the transfer begin. The client owning the primary selection + should write the requested data, and close the file descriptor + immediately. + + If the primary selection owner client disappeared during the transfer, + the client reading the data will receive a + wp_primary_selection_device.selection event with a NULL + wp_primary_selection_offer, the client should take this as a hint + to finish the reads related to the no longer existing offer. + + The primary selection owner should be checking for errors during + writes, merely cancelling the ongoing transfer if any happened. + </description> + + <interface name="zwp_primary_selection_device_manager_v1" version="1"> + <description summary="X primary selection emulation"> + The primary selection device manager is a singleton global object that + provides access to the primary selection. It allows to create + wp_primary_selection_source objects, as well as retrieving the per-seat + wp_primary_selection_device objects. + </description> + + <request name="create_source"> + <description summary="create a new primary selection source"> + Create a new primary selection source. + </description> + <arg name="id" type="new_id" interface="zwp_primary_selection_source_v1"/> + </request> + + <request name="get_device"> + <description summary="create a new primary selection device"> + Create a new data device for a given seat. + </description> + <arg name="id" type="new_id" interface="zwp_primary_selection_device_v1"/> + <arg name="seat" type="object" interface="wl_seat"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the primary selection device manager"> + Destroy the primary selection device manager. + </description> + </request> + </interface> + + <interface name="zwp_primary_selection_device_v1" version="1"> + <request name="set_selection"> + <description summary="set the primary selection"> + Replaces the current selection. The previous owner of the primary + selection will receive a wp_primary_selection_source.cancelled event. + + To unset the selection, set the source to NULL. + </description> + <arg name="source" type="object" interface="zwp_primary_selection_source_v1" allow-null="true"/> + <arg name="serial" type="uint" summary="serial of the event that triggered this request"/> + </request> + + <event name="data_offer"> + <description summary="introduce a new wp_primary_selection_offer"> + Introduces a new wp_primary_selection_offer object that may be used + to receive the current primary selection. Immediately following this + event, the new wp_primary_selection_offer object will send + wp_primary_selection_offer.offer events to describe the offered mime + types. + </description> + <arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/> + </event> + + <event name="selection"> + <description summary="advertise a new primary selection"> + The wp_primary_selection_device.selection event is sent to notify the + client of a new primary selection. This event is sent after the + wp_primary_selection.data_offer event introducing this object, and after + the offer has announced its mimetypes through + wp_primary_selection_offer.offer. + + The data_offer is valid until a new offer or NULL is received + or until the client loses keyboard focus. The client must destroy the + previous selection data_offer, if any, upon receiving this event. + </description> + <arg name="id" type="object" interface="zwp_primary_selection_offer_v1" allow-null="true"/> + </event> + + <request name="destroy" type="destructor"> + <description summary="destroy the primary selection device"> + Destroy the primary selection device. + </description> + </request> + </interface> + + <interface name="zwp_primary_selection_offer_v1" version="1"> + <description summary="offer to transfer primary selection contents"> + A wp_primary_selection_offer represents an offer to transfer the contents + of the primary selection clipboard to the client. Similar to + wl_data_offer, the offer also describes the mime types that the data can + be converted to and provides the mechanisms for transferring the data + directly to the client. + </description> + + <request name="receive"> + <description summary="request that the data is transferred"> + To transfer the contents of the primary selection clipboard, the client + issues this request and indicates the mime type that it wants to + receive. The transfer happens through the passed file descriptor + (typically created with the pipe system call). The source client writes + the data in the mime type representation requested and then closes the + file descriptor. + + The receiving client reads from the read end of the pipe until EOF and + closes its end, at which point the transfer is complete. + </description> + <arg name="mime_type" type="string"/> + <arg name="fd" type="fd"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the primary selection offer"> + Destroy the primary selection offer. + </description> + </request> + + <event name="offer"> + <description summary="advertise offered mime type"> + Sent immediately after creating announcing the + wp_primary_selection_offer through + wp_primary_selection_device.data_offer. One event is sent per offered + mime type. + </description> + <arg name="mime_type" type="string"/> + </event> + </interface> + + <interface name="zwp_primary_selection_source_v1" version="1"> + <description summary="offer to replace the contents of the primary selection"> + The source side of a wp_primary_selection_offer, it provides a way to + describe the offered data and respond to requests to transfer the + requested contents of the primary selection clipboard. + </description> + + <request name="offer"> + <description summary="add an offered mime type"> + This request adds a mime type to the set of mime types advertised to + targets. Can be called several times to offer multiple types. + </description> + <arg name="mime_type" type="string"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the primary selection source"> + Destroy the primary selection source. + </description> + </request> + + <event name="send"> + <description summary="send the primary selection contents"> + Request for the current primary selection contents from the client. + Send the specified mime type over the passed file descriptor, then + close it. + </description> + <arg name="mime_type" type="string"/> + <arg name="fd" type="fd"/> + </event> + + <event name="cancelled"> + <description summary="request for primary selection contents was canceled"> + This primary selection source is no longer valid. The client should + clean up and destroy this primary selection source. + </description> + </event> + </interface> +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/relative-pointer/README b/thirdparty/wayland-protocols/unstable/relative-pointer/README new file mode 100644 index 0000000000..64c42a126e --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/relative-pointer/README @@ -0,0 +1,4 @@ +Relative pointer protocol + +Maintainers: +Jonas Ådahl <jadahl@gmail.com> diff --git a/thirdparty/wayland-protocols/unstable/relative-pointer/relative-pointer-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/relative-pointer/relative-pointer-unstable-v1.xml new file mode 100644 index 0000000000..ca6f81d12a --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/relative-pointer/relative-pointer-unstable-v1.xml @@ -0,0 +1,136 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="relative_pointer_unstable_v1"> + + <copyright> + Copyright © 2014 Jonas Ådahl + Copyright © 2015 Red Hat Inc. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + </copyright> + + <description summary="protocol for relative pointer motion events"> + This protocol specifies a set of interfaces used for making clients able to + receive relative pointer events not obstructed by barriers (such as the + monitor edge or other pointer barriers). + + To start receiving relative pointer events, a client must first bind the + global interface "wp_relative_pointer_manager" which, if a compositor + supports relative pointer motion events, is exposed by the registry. After + having created the relative pointer manager proxy object, the client uses + it to create the actual relative pointer object using the + "get_relative_pointer" request given a wl_pointer. The relative pointer + motion events will then, when applicable, be transmitted via the proxy of + the newly created relative pointer object. See the documentation of the + relative pointer interface for more details. + + Warning! The protocol described in this file is experimental and backward + incompatible changes may be made. Backward compatible changes may be added + together with the corresponding interface version bump. Backward + incompatible changes are done by bumping the version number in the protocol + and interface names and resetting the interface version. Once the protocol + is to be declared stable, the 'z' prefix and the version number in the + protocol and interface names are removed and the interface version number is + reset. + </description> + + <interface name="zwp_relative_pointer_manager_v1" version="1"> + <description summary="get relative pointer objects"> + A global interface used for getting the relative pointer object for a + given pointer. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the relative pointer manager object"> + Used by the client to notify the server that it will no longer use this + relative pointer manager object. + </description> + </request> + + <request name="get_relative_pointer"> + <description summary="get a relative pointer object"> + Create a relative pointer interface given a wl_pointer object. See the + wp_relative_pointer interface for more details. + </description> + <arg name="id" type="new_id" interface="zwp_relative_pointer_v1"/> + <arg name="pointer" type="object" interface="wl_pointer"/> + </request> + </interface> + + <interface name="zwp_relative_pointer_v1" version="1"> + <description summary="relative pointer object"> + A wp_relative_pointer object is an extension to the wl_pointer interface + used for emitting relative pointer events. It shares the same focus as + wl_pointer objects of the same seat and will only emit events when it has + focus. + </description> + + <request name="destroy" type="destructor"> + <description summary="release the relative pointer object"/> + </request> + + <event name="relative_motion"> + <description summary="relative pointer motion"> + Relative x/y pointer motion from the pointer of the seat associated with + this object. + + A relative motion is in the same dimension as regular wl_pointer motion + events, except they do not represent an absolute position. For example, + moving a pointer from (x, y) to (x', y') would have the equivalent + relative motion (x' - x, y' - y). If a pointer motion caused the + absolute pointer position to be clipped by for example the edge of the + monitor, the relative motion is unaffected by the clipping and will + represent the unclipped motion. + + This event also contains non-accelerated motion deltas. The + non-accelerated delta is, when applicable, the regular pointer motion + delta as it was before having applied motion acceleration and other + transformations such as normalization. + + Note that the non-accelerated delta does not represent 'raw' events as + they were read from some device. Pointer motion acceleration is device- + and configuration-specific and non-accelerated deltas and accelerated + deltas may have the same value on some devices. + + Relative motions are not coupled to wl_pointer.motion events, and can be + sent in combination with such events, but also independently. There may + also be scenarios where wl_pointer.motion is sent, but there is no + relative motion. The order of an absolute and relative motion event + originating from the same physical motion is not guaranteed. + + If the client needs button events or focus state, it can receive them + from a wl_pointer object of the same seat that the wp_relative_pointer + object is associated with. + </description> + <arg name="utime_hi" type="uint" + summary="high 32 bits of a 64 bit timestamp with microsecond granularity"/> + <arg name="utime_lo" type="uint" + summary="low 32 bits of a 64 bit timestamp with microsecond granularity"/> + <arg name="dx" type="fixed" + summary="the x component of the motion vector"/> + <arg name="dy" type="fixed" + summary="the y component of the motion vector"/> + <arg name="dx_unaccel" type="fixed" + summary="the x component of the unaccelerated motion vector"/> + <arg name="dy_unaccel" type="fixed" + summary="the y component of the unaccelerated motion vector"/> + </event> + </interface> + +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/tablet/README b/thirdparty/wayland-protocols/unstable/tablet/README new file mode 100644 index 0000000000..7ba8e77a13 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/tablet/README @@ -0,0 +1,4 @@ +Tablet protocol + +Maintainers: +Peter Hutterer <peter.hutterer@who-t.net> diff --git a/thirdparty/wayland-protocols/unstable/tablet/tablet-unstable-v2.xml b/thirdparty/wayland-protocols/unstable/tablet/tablet-unstable-v2.xml new file mode 100644 index 0000000000..ccbb5412a5 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/tablet/tablet-unstable-v2.xml @@ -0,0 +1,1178 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="tablet_unstable_v2"> + + <copyright> + Copyright 2014 © Stephen "Lyude" Chandler Paul + Copyright 2015-2016 © Red Hat, Inc. + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation files + (the "Software"), to deal in the Software without restriction, + including without limitation the rights to use, copy, modify, merge, + publish, distribute, sublicense, and/or sell copies of the Software, + and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice (including the + next paragraph) shall be included in all copies or substantial + portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + </copyright> + + <description summary="Wayland protocol for graphics tablets"> + This description provides a high-level overview of the interplay between + the interfaces defined this protocol. For details, see the protocol + specification. + + More than one tablet may exist, and device-specifics matter. Tablets are + not represented by a single virtual device like wl_pointer. A client + binds to the tablet manager object which is just a proxy object. From + that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat) + and that returns the actual interface that has all the tablets. With + this indirection, we can avoid merging wp_tablet into the actual Wayland + protocol, a long-term benefit. + + The wp_tablet_seat sends a "tablet added" event for each tablet + connected. That event is followed by descriptive events about the + hardware; currently that includes events for name, vid/pid and + a wp_tablet.path event that describes a local path. This path can be + used to uniquely identify a tablet or get more information through + libwacom. Emulated or nested tablets can skip any of those, e.g. a + virtual tablet may not have a vid/pid. The sequence of descriptive + events is terminated by a wp_tablet.done event to signal that a client + may now finalize any initialization for that tablet. + + Events from tablets require a tool in proximity. Tools are also managed + by the tablet seat; a "tool added" event is sent whenever a tool is new + to the compositor. That event is followed by a number of descriptive + events about the hardware; currently that includes capabilities, + hardware id and serial number, and tool type. Similar to the tablet + interface, a wp_tablet_tool.done event is sent to terminate that initial + sequence. + + Any event from a tool happens on the wp_tablet_tool interface. When the + tool gets into proximity of the tablet, a proximity_in event is sent on + the wp_tablet_tool interface, listing the tablet and the surface. That + event is followed by a motion event with the coordinates. After that, + it's the usual motion, axis, button, etc. events. The protocol's + serialisation means events are grouped by wp_tablet_tool.frame events. + + Two special events (that don't exist in X) are down and up. They signal + "tip touching the surface". For tablets without real proximity + detection, the sequence is: proximity_in, motion, down, frame. + + When the tool leaves proximity, a proximity_out event is sent. If any + button is still down, a button release event is sent before this + proximity event. These button events are sent in the same frame as the + proximity event to signal to the client that the buttons were held when + the tool left proximity. + + If the tool moves out of the surface but stays in proximity (i.e. + between windows), compositor-specific grab policies apply. This usually + means that the proximity-out is delayed until all buttons are released. + + Moving a tool physically from one tablet to the other has no real effect + on the protocol, since we already have the tool object from the "tool + added" event. All the information is already there and the proximity + events on both tablets are all a client needs to reconstruct what + happened. + + Some extra axes are normalized, i.e. the client knows the range as + specified in the protocol (e.g. [0, 65535]), the granularity however is + unknown. The current normalized axes are pressure, distance, and slider. + + Other extra axes are in physical units as specified in the protocol. + The current extra axes with physical units are tilt, rotation and + wheel rotation. + + Since tablets work independently of the pointer controlled by the mouse, + the focus handling is independent too and controlled by proximity. + The wp_tablet_tool.set_cursor request sets a tool-specific cursor. + This cursor surface may be the same as the mouse cursor, and it may be + the same across tools but it is possible to be more fine-grained. For + example, a client may set different cursors for the pen and eraser. + + Tools are generally independent of tablets and it is + compositor-specific policy when a tool can be removed. Common approaches + will likely include some form of removing a tool when all tablets the + tool was used on are removed. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + </description> + + <interface name="zwp_tablet_manager_v2" version="1"> + <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 + actual tablets, use wp_tablet_manager.get_tablet_seat. + </description> + + <request name="get_tablet_seat"> + <description summary="get the tablet seat"> + Get the wp_tablet_seat object for the given seat. This object + provides access to all graphics tablets in this seat. + </description> + <arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v2"/> + <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the tablets for" /> + </request> + + <request name="destroy" type="destructor"> + <description summary="release the memory for the tablet manager object"> + Destroy the wp_tablet_manager object. Objects created from this + object are unaffected and should be destroyed separately. + </description> + </request> + </interface> + + <interface name="zwp_tablet_seat_v2" version="1"> + <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 + wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events. + </description> + + <request name="destroy" type="destructor"> + <description summary="release the memory for the tablet seat object"> + Destroy the wp_tablet_seat object. Objects created from this + object are unaffected and should be destroyed separately. + </description> + </request> + + <event name="tablet_added"> + <description summary="new device notification"> + This event is sent whenever a new tablet becomes available on this + seat. This event only provides the object id of the tablet, any + static information about the tablet (device name, vid/pid, etc.) is + sent through the wp_tablet interface. + </description> + <arg name="id" type="new_id" interface="zwp_tablet_v2" summary="the newly added graphics tablet"/> + </event> + + <event name="tool_added"> + <description summary="a new tool has been used with a tablet"> + This event is sent whenever a tool that has not previously been used + with a tablet comes into use. This event only provides the object id + of the tool; any static information about the tool (capabilities, + type, etc.) is sent through the wp_tablet_tool interface. + </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. 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"> + <description summary="a physical tablet tool"> + An object that represents a physical tool that has been, or is + currently in use with a tablet in this seat. Each wp_tablet_tool + object stays valid until the client destroys it; the compositor + reuses the wp_tablet_tool object to indicate that the object's + respective physical tool has come into proximity of a tablet again. + + A wp_tablet_tool object's relation to a physical tool depends on the + tablet's ability to report serial numbers. If the tablet supports + this capability, then the object represents a specific physical tool + and can be identified even when used on multiple tablets. + + A tablet tool has a number of static characteristics, e.g. tool type, + hardware_serial and capabilities. These capabilities are sent in an + event sequence after the wp_tablet_seat.tool_added event before any + actual events from this tool. This initial event sequence is + terminated by a wp_tablet_tool.done event. + + Tablet tool events are grouped by wp_tablet_tool.frame events. + Any events received before a wp_tablet_tool.frame event should be + considered part of the same hardware state change. + </description> + + <request name="set_cursor"> + <description summary="set the tablet tool's surface"> + Sets the surface of the cursor used for this tool on the given + tablet. This request only takes effect if the tool is in proximity + of one of the requesting client's surfaces or the surface parameter + is the current pointer surface. If there was a previous surface set + with this request it is replaced. If surface is NULL, the cursor + image is hidden. + + The parameters hotspot_x and hotspot_y define the position of the + pointer surface relative to the pointer location. Its top-left corner + is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the + coordinates of the pointer location, in surface-local coordinates. + + On surface.attach requests to the pointer surface, hotspot_x and + hotspot_y are decremented by the x and y parameters passed to the + request. Attach must be confirmed by wl_surface.commit as usual. + + The hotspot can also be updated by passing the currently set pointer + surface to this request with new values for hotspot_x and hotspot_y. + + The current and pending input regions of the wl_surface are cleared, + and wl_surface.set_input_region is ignored until the wl_surface is no + longer used as the cursor. When the use as a cursor ends, the current + and pending input regions become undefined, and the wl_surface is + unmapped. + + This request gives the surface the role of a wp_tablet_tool cursor. A + surface may only ever be used as the cursor surface for one + wp_tablet_tool. If the surface already has another role or has + previously been used as cursor surface for a different tool, a + protocol error is raised. + </description> + <arg name="serial" type="uint" summary="serial of the proximity_in event"/> + <arg name="surface" type="object" interface="wl_surface" allow-null="true"/> + <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/> + <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the tool object"> + This destroys the client's resource for this tool object. + </description> + </request> + + <enum name="type"> + <description summary="a physical tool type"> + Describes the physical type of a tool. The physical type of a tool + generally defines its base usage. + + The mouse tool represents a mouse-shaped tool that is not a relative + device but bound to the tablet's surface, providing absolute + coordinates. + + The lens tool is a mouse-shaped tool with an attached lens to + provide precision focus. + </description> + <entry name="pen" value="0x140" summary="Pen"/> + <entry name="eraser" value="0x141" summary="Eraser"/> + <entry name="brush" value="0x142" summary="Brush"/> + <entry name="pencil" value="0x143" summary="Pencil"/> + <entry name="airbrush" value="0x144" summary="Airbrush"/> + <entry name="finger" value="0x145" summary="Finger"/> + <entry name="mouse" value="0x146" summary="Mouse"/> + <entry name="lens" value="0x147" summary="Lens"/> + </enum> + + <event name="type"> + <description summary="tool type"> + The tool type is the high-level type of the tool and usually decides + the interaction expected from this tool. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/> + </event> + + <event name="hardware_serial"> + <description summary="unique hardware serial number of the tool"> + If the physical tool can be identified by a unique 64-bit serial + number, this event notifies the client of this serial number. + + If multiple tablets are available in the same seat and the tool is + uniquely identifiable by the serial number, that tool may move + between tablets. + + Otherwise, if the tool has no serial number and this event is + missing, the tool is tied to the tablet it first comes into + proximity with. Even if the physical tool is used on multiple + tablets, separate wp_tablet_tool objects will be created, one per + tablet. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/> + <arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/> + </event> + + <event name="hardware_id_wacom"> + <description summary="hardware id notification in Wacom's format"> + This event notifies the client of a hardware id available on this tool. + + The hardware id is a device-specific 64-bit id that provides extra + information about the tool in use, beyond the wl_tool.type + enumeration. The format of the id is specific to tablets made by + Wacom Inc. For example, the hardware id of a Wacom Grip + Pen (a stylus) is 0x802. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/> + <arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/> + </event> + + <enum name="capability"> + <description summary="capability flags for a tool"> + Describes extra capabilities on a tablet. + + Any tool must provide x and y values, extra axes are + device-specific. + </description> + <entry name="tilt" value="1" summary="Tilt axes"/> + <entry name="pressure" value="2" summary="Pressure axis"/> + <entry name="distance" value="3" summary="Distance axis"/> + <entry name="rotation" value="4" summary="Z-rotation axis"/> + <entry name="slider" value="5" summary="Slider axis"/> + <entry name="wheel" value="6" summary="Wheel axis"/> + </enum> + + <event name="capability"> + <description summary="tool capability notification"> + This event notifies the client of any capabilities of this tool, + beyond the main set of x/y axes and tip up/down detection. + + One event is sent for each extra capability available on this tool. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="capability" type="uint" enum="capability" summary="the capability"/> + </event> + + <event name="done"> + <description summary="tool description events sequence complete"> + This event signals the end of the initial burst of descriptive + events. A client may consider the static description of the tool to + be complete and finalize initialization of the tool. + </description> + </event> + + <event name="removed"> + <description summary="tool removed"> + This event is sent when the tool is removed from the system and will + send no further events. Should the physical tool come back into + proximity later, a new wp_tablet_tool object will be created. + + It is compositor-dependent when a tool is removed. A compositor may + remove a tool on proximity out, tablet removal or any other reason. + A compositor may also keep a tool alive until shutdown. + + If the tool is currently in proximity, a proximity_out event will be + sent before the removed event. See wp_tablet_tool.proximity_out for + the handling of any buttons logically down. + + When this event is received, the client must wp_tablet_tool.destroy + the object. + </description> + </event> + + <event name="proximity_in"> + <description summary="proximity in event"> + Notification that this tool is focused on a certain surface. + + This event can be received when the tool has moved from one surface to + another, or when the tool has come back into proximity above the + surface. + + If any button is logically down when the tool comes into proximity, + the respective button event is sent after the proximity_in event but + within the same frame as the proximity_in event. + </description> + <arg name="serial" type="uint"/> + <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="The tablet the tool is in proximity of"/> + <arg name="surface" type="object" interface="wl_surface" summary="The current surface the tablet tool is over"/> + </event> + + <event name="proximity_out"> + <description summary="proximity out event"> + Notification that this tool has either left proximity, or is no + longer focused on a certain surface. + + When the tablet tool leaves proximity of the tablet, button release + events are sent for each button that was held down at the time of + leaving proximity. These events are sent before the proximity_out + event but within the same wp_tablet.frame. + + If the tool stays within proximity of the tablet, but the focus + changes from one surface to another, a button release event may not + be sent until the button is actually released or the tool leaves the + proximity of the tablet. + </description> + </event> + + <event name="down"> + <description summary="tablet tool is making contact"> + Sent whenever the tablet tool comes in contact with the surface of the + tablet. + + If the tool is already in contact with the tablet when entering the + input region, the client owning said region will receive a + wp_tablet.proximity_in event, followed by a wp_tablet.down + event and a wp_tablet.frame event. + + Note that this event describes logical contact, not physical + contact. On some devices, a compositor may not consider a tool in + logical contact until a minimum physical pressure threshold is + exceeded. + </description> + <arg name="serial" type="uint"/> + </event> + + <event name="up"> + <description summary="tablet tool is no longer making contact"> + Sent whenever the tablet tool stops making contact with the surface of + the tablet, or when the tablet tool moves out of the input region + and the compositor grab (if any) is dismissed. + + If the tablet tool moves out of the input region while in contact + with the surface of the tablet and the compositor does not have an + ongoing grab on the surface, the client owning said region will + receive a wp_tablet.up event, followed by a wp_tablet.proximity_out + event and a wp_tablet.frame event. If the compositor has an ongoing + grab on this device, this event sequence is sent whenever the grab + is dismissed in the future. + + Note that this event describes logical contact, not physical + contact. On some devices, a compositor may not consider a tool out + of logical contact until physical pressure falls below a specific + threshold. + </description> + </event> + + <event name="motion"> + <description summary="motion event"> + Sent whenever a tablet tool moves. + </description> + <arg name="x" type="fixed" summary="surface-local x coordinate"/> + <arg name="y" type="fixed" summary="surface-local y coordinate"/> + </event> + + <event name="pressure"> + <description summary="pressure change event"> + Sent whenever the pressure axis on a tool changes. The value of this + event is normalized to a value between 0 and 65535. + + Note that pressure may be nonzero even when a tool is not in logical + contact. See the down and up events for more details. + </description> + <arg name="pressure" type="uint" summary="The current pressure value"/> + </event> + + <event name="distance"> + <description summary="distance change event"> + Sent whenever the distance axis on a tool changes. The value of this + event is normalized to a value between 0 and 65535. + + Note that distance may be nonzero even when a tool is not in logical + contact. See the down and up events for more details. + </description> + <arg name="distance" type="uint" summary="The current distance value"/> + </event> + + <event name="tilt"> + <description summary="tilt change event"> + Sent whenever one or both of the tilt axes on a tool change. Each tilt + value is in degrees, relative to the z-axis of the tablet. + The angle is positive when the top of a tool tilts along the + positive x or y axis. + </description> + <arg name="tilt_x" type="fixed" summary="The current value of the X tilt axis"/> + <arg name="tilt_y" type="fixed" summary="The current value of the Y tilt axis"/> + </event> + + <event name="rotation"> + <description summary="z-rotation change event"> + Sent whenever the z-rotation axis on the tool changes. The + rotation value is in degrees clockwise from the tool's + logical neutral position. + </description> + <arg name="degrees" type="fixed" summary="The current rotation of the Z axis"/> + </event> + + <event name="slider"> + <description summary="Slider position change event"> + Sent whenever the slider position on the tool changes. The + value is normalized between -65535 and 65535, with 0 as the logical + neutral position of the slider. + + The slider is available on e.g. the Wacom Airbrush tool. + </description> + <arg name="position" type="int" summary="The current position of slider"/> + </event> + + <event name="wheel"> + <description summary="Wheel delta event"> + 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 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. + + Clients should choose either value and avoid mixing degrees and + clicks. The compositor may accumulate values smaller than a logical + click and emulate click events when a certain threshold is met. + Thus, wl_tablet_tool.wheel events with non-zero clicks values may + have different degrees values. + </description> + <arg name="degrees" type="fixed" summary="The wheel delta in degrees"/> + <arg name="clicks" type="int" summary="The wheel delta in discrete clicks"/> + </event> + + <enum name="button_state"> + <description summary="physical button state"> + Describes the physical state of a button that produced the button event. + </description> + <entry name="released" value="0" summary="button is not pressed"/> + <entry name="pressed" value="1" summary="button is pressed"/> + </enum> + + <event name="button"> + <description summary="button event"> + Sent whenever a button on the tool is pressed or released. + + If a button is held down when the tool moves in or out of proximity, + button events are generated by the compositor. See + wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for + details. + </description> + <arg name="serial" type="uint"/> + <arg name="button" type="uint" summary="The button whose state has changed"/> + <arg name="state" type="uint" enum="button_state" summary="Whether the button was pressed or released"/> + </event> + + <event name="frame"> + <description summary="frame event"> + Marks the end of a series of axis and/or button updates from the + tablet. The Wayland protocol requires axis updates to be sent + sequentially, however all events within a frame should be considered + one hardware event. + </description> + <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/> + </event> + + <enum name="error"> + <entry name="role" value="0" summary="given wl_surface has another role"/> + </enum> + </interface> + + <interface name="zwp_tablet_v2" version="1"> + <description summary="graphics tablet device"> + The wp_tablet interface represents one graphics tablet device. The + tablet interface itself does not generate events; all events are + generated by wp_tablet_tool objects when in proximity above a tablet. + + A tablet has a number of static characteristics, e.g. device name and + pid/vid. These capabilities are sent in an event sequence after the + wp_tablet_seat.tablet_added event. This initial event sequence is + terminated by a wp_tablet.done event. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the tablet object"> + This destroys the client's resource for this tablet object. + </description> + </request> + + <event name="name"> + <description summary="tablet device name"> + This event is sent in the initial burst of events before the + wp_tablet.done event. + </description> + <arg name="name" type="string" summary="the device name"/> + </event> + + <event name="id"> + <description summary="tablet device USB vendor/product id"> + This event is sent in the initial burst of events before the + wp_tablet.done event. + </description> + <arg name="vid" type="uint" summary="USB vendor id"/> + <arg name="pid" type="uint" summary="USB product id"/> + </event> + + <event name="path"> + <description summary="path to the device"> + A system-specific device path that indicates which device is behind + this wp_tablet. This information may be used to gather additional + information about the device, e.g. through libwacom. + + A device may have more than one device path. If so, multiple + wp_tablet.path events are sent. A device may be emulated and not + have a device path, and in that case this event will not be sent. + + The format of the path is unspecified, it may be a device node, a + sysfs path, or some other identifier. It is up to the client to + identify the string provided. + + This event is sent in the initial burst of events before the + wp_tablet.done event. + </description> + <arg name="path" type="string" summary="path to local device"/> + </event> + + <event name="done"> + <description summary="tablet description events sequence complete"> + This event is sent immediately to signal the end of the initial + burst of descriptive events. A client may consider the static + description of the tablet to be complete and finalize initialization + of the tablet. + </description> + </event> + + <event name="removed"> + <description summary="tablet removed event"> + Sent when the tablet has been removed from the system. When a tablet + is removed, some tools may be removed. + + When this event is received, the client must wp_tablet.destroy + the object. + </description> + </event> + </interface> + + <interface name="zwp_tablet_pad_ring_v2" version="1"> + <description summary="pad ring"> + A circular interaction area, such as the touch ring on the Wacom Intuos + Pro series tablets. + + 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_group.mode_switch event from the corresponding + group is received, or whenever the ring is mapped to a different + action. See wp_tablet_pad_group.mode_switch for more details. + + 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 serial argument will be that of the last + wp_tablet_pad_group.mode_switch event received for the group of this + ring. Requests providing other serials than the most recent one will be + ignored. + </description> + <arg name="description" type="string" summary="ring description"/> + <arg name="serial" type="uint" summary="serial of the mode switch event"/> + </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" enum="source" 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="degrees" type="fixed" summary="the current angle in degrees"/> + </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> + </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="1"> + <description summary="pad strip"> + A linear interaction area, such as the strips found in Wacom Cintiq + models. + + 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_group.mode_switch event from the corresponding + group is received, or whenever the strip is mapped to a different + action. See wp_tablet_pad_group.mode_switch for more details. + + Clients are encouraged to provide context-aware descriptions for + the actions associated with the strip, and 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 serial argument will be that of the last + wp_tablet_pad_group.mode_switch event received for the group of this + strip. Requests providing other serials than the most recent one will be + ignored. + </description> + <arg name="description" type="string" summary="strip description"/> + <arg name="serial" type="uint" summary="serial of the mode switch event"/> + </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" enum="source" 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> + </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_group_v2" version="1"> + <description summary="a set of buttons, rings and strips"> + A pad group describes a distinct (sub)set of buttons, rings and strips + present in the tablet. The criteria of this grouping is usually positional, + eg. if a tablet has buttons on the left and right side, 2 groups will be + presented. The physical arrangement of groups is undisclosed and may + change on the fly. + + Pad groups will announce their features during pad initialization. Between + the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the + pad group will announce the buttons, rings and strips contained in it, + plus the number of supported modes. + + Modes are a mechanism to allow multiple groups of actions for every element + in the pad group. The number of groups and available modes in each is + persistent across device plugs. The current mode is user-switchable, it + will be announced through the wp_tablet_pad_group.mode_switch event both + whenever it is switched, and after wp_tablet_pad.enter. + + The current mode logically applies to all elements in the pad group, + although it is at clients' discretion whether to actually perform different + actions, and/or issue the respective .set_feedback requests to notify the + compositor. See the wp_tablet_pad_group.mode_switch event for more details. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the pad object"> + Destroy the wp_tablet_pad_group object. Objects created from this object + are unaffected and should be destroyed separately. + </description> + </request> + + <event name="buttons"> + <description summary="buttons announced"> + Sent on wp_tablet_pad_group initialization to announce the available + buttons in the group. Button indices start at 0, a button may only be + in one group at a time. + + This event is first sent in the initial burst of events before the + wp_tablet_pad_group.done event. + + Some buttons are reserved by the compositor. These buttons may not be + assigned to any wp_tablet_pad_group. Compositors may broadcast this + event in the case of changes to the mapping of these reserved buttons. + If the compositor happens to reserve all buttons in a group, this event + will be sent with an empty array. + </description> + <arg name="buttons" type="array" summary="buttons in this group"/> + </event> + + <event name="ring"> + <description summary="ring announced"> + 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. + </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 group. + + This event is sent in the initial burst of events before the + wp_tablet_pad_group.done event. + </description> + <arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/> + </event> + + <event name="modes"> + <description summary="mode-switch ability announced"> + Sent on wp_tablet_pad_group initialization to announce that the pad + group 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_group.mode_switch event to toggle between these + configurations. Mode indices start at 0. + + Switching modes is compositor-dependent. See the + wp_tablet_pad_group.mode_switch event for more details. + + This event is sent in the initial burst of events before the + wp_tablet_pad_group.done event. This event is only sent when more than + more than one mode is available. + </description> + <arg name="modes" type="uint" summary="the number of modes"/> + </event> + + <event name="done"> + <description summary="tablet group description events sequence complete"> + This event is sent immediately to signal the end of the initial + burst of descriptive events. A client may consider the static + description of the tablet to be complete and finalize initialization + of the tablet group. + </description> + </event> + + <event name="mode_switch"> + <description summary="mode switch event"> + 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 compositor will also send this event after wp_tablet_pad.enter on + each group in order to notify of the current mode. Groups that only + feature one mode will use mode=0 when emitting this event. + + 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 strip 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" summary="the new mode of the pad"/> + </event> + </interface> + + <interface name="zwp_tablet_pad_v2" version="1"> + <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. + + All pad features (buttons, rings and strips) are logically divided into + groups and all pads have at least one group. The available groups are + notified through the wp_tablet_pad.group event; the compositor will + emit one event per group before emitting wp_tablet_pad.done. + + Groups may have multiple modes. Modes allow clients to map multiple + actions to a single pad feature. Only one mode can be active per group, + although different groups may have different active modes. + </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_group.mode_switch event from the corresponding + group is received, or whenever a button is mapped to a different + action. See wp_tablet_pad_group.mode_switch for more details. + + 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). + + Button indices start at 0. Setting the feedback string on a button + that is reserved by the compositor (i.e. not belonging to any + wp_tablet_pad_group) does not generate an error but the compositor + is free to ignore the request. + + 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 serial argument will be that of the last + wp_tablet_pad_group.mode_switch event received for the group of this + button. Requests providing other serials than the most recent one will + be ignored. + </description> + <arg name="button" type="uint" summary="button index"/> + <arg name="description" type="string" summary="button description"/> + <arg name="serial" type="uint" summary="serial of the mode switch event"/> + </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="group"> + <description summary="group announced"> + Sent on wp_tablet_pad initialization to announce available groups. + One event is sent for each pad group available. + + This event is sent in the initial burst of events before the + wp_tablet_pad.done event. At least one group will be announced. + </description> + <arg name="pad_group" type="new_id" interface="zwp_tablet_pad_group_v2"/> + </event> + + <event name="path"> + <description summary="path to the device"> + A system-specific device path that indicates which device is behind + this wp_tablet_pad. This information may be used to gather additional + information about the device, e.g. through libwacom. + + The format of the path is unspecified, it may be a device node, a + sysfs path, or some other identifier. It is up to the client to + identify the string provided. + + This event is sent in the initial burst of events before the + wp_tablet_pad.done event. + </description> + <arg name="path" type="string" summary="path to local device"/> + </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="uint" summary="the number of buttons"/> + </event> + + <event name="done"> + <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"> + <description summary="physical button state"> + Describes the physical state of a button that caused 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"> + <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="the index of the button that changed state"/> + <arg name="state" type="uint" enum="button_state"/> + </event> + + <event name="enter"> + <description summary="enter event"> + Notification that this pad is focused on the specified surface. + </description> + <arg name="serial" type="uint" summary="serial number of the enter event"/> + <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="the tablet the pad is attached to"/> + <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is focused on"/> + </event> + + <event name="leave"> + <description summary="leave event"> + Notification that this pad is no longer focused on the specified + surface. + </description> + <arg name="serial" type="uint" summary="serial number of the leave event"/> + <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is no longer focused on"/> + </event> + + <event name="removed"> + <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 destroy all rings, strips + and groups that were offered by this pad, and issue wp_tablet_pad.destroy + the pad itself. + </description> + </event> + </interface> +</protocol> diff --git a/thirdparty/wayland-protocols/unstable/xdg-decoration/README b/thirdparty/wayland-protocols/unstable/xdg-decoration/README new file mode 100644 index 0000000000..73f0c52044 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/xdg-decoration/README @@ -0,0 +1,4 @@ +xdg_decoration protocol + +Maintainers: +Simon Ser <contact@emersion.fr> diff --git a/thirdparty/wayland-protocols/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml b/thirdparty/wayland-protocols/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml new file mode 100644 index 0000000000..e5967751d7 --- /dev/null +++ b/thirdparty/wayland-protocols/unstable/xdg-decoration/xdg-decoration-unstable-v1.xml @@ -0,0 +1,156 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="xdg_decoration_unstable_v1"> + <copyright> + Copyright © 2018 Simon Ser + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + </copyright> + + <interface name="zxdg_decoration_manager_v1" version="1"> + <description summary="window decoration manager"> + This interface allows a compositor to announce support for server-side + decorations. + + A window decoration is a set of window controls as deemed appropriate by + the party managing them, such as user interface components used to move, + resize and change a window's state. + + A client can use this protocol to request being decorated by a supporting + compositor. + + If compositor and client do not negotiate the use of a server-side + decoration using this protocol, clients continue to self-decorate as they + see fit. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroy the decoration manager object"> + Destroy the decoration manager. This doesn't destroy objects created + with the manager. + </description> + </request> + + <request name="get_toplevel_decoration"> + <description summary="create a new toplevel decoration object"> + Create a new decoration object associated with the given toplevel. + + Creating an xdg_toplevel_decoration from an xdg_toplevel which has a + buffer attached or committed is a client error, and any attempts by a + client to attach or manipulate a buffer prior to the first + xdg_toplevel_decoration.configure event must also be treated as + errors. + </description> + <arg name="id" type="new_id" interface="zxdg_toplevel_decoration_v1"/> + <arg name="toplevel" type="object" interface="xdg_toplevel"/> + </request> + </interface> + + <interface name="zxdg_toplevel_decoration_v1" version="1"> + <description summary="decoration object for a toplevel surface"> + The decoration object allows the compositor to toggle server-side window + decorations for a toplevel surface. The client can request to switch to + another mode. + + The xdg_toplevel_decoration object must be destroyed before its + xdg_toplevel. + </description> + + <enum name="error"> + <entry name="unconfigured_buffer" value="0" + summary="xdg_toplevel has a buffer attached before configure"/> + <entry name="already_constructed" value="1" + summary="xdg_toplevel already has a decoration object"/> + <entry name="orphaned" value="2" + summary="xdg_toplevel destroyed before the decoration object"/> + </enum> + + <request name="destroy" type="destructor"> + <description summary="destroy the decoration object"> + Switch back to a mode without any server-side decorations at the next + commit. + </description> + </request> + + <enum name="mode"> + <description summary="window decoration modes"> + These values describe window decoration modes. + </description> + <entry name="client_side" value="1" + summary="no server-side window decoration"/> + <entry name="server_side" value="2" + summary="server-side window decoration"/> + </enum> + + <request name="set_mode"> + <description summary="set the decoration mode"> + Set the toplevel surface decoration mode. This informs the compositor + that the client prefers the provided decoration mode. + + After requesting a decoration mode, the compositor will respond by + emitting an xdg_surface.configure event. The client should then update + its content, drawing it without decorations if the received mode is + server-side decorations. The client must also acknowledge the configure + when committing the new content (see xdg_surface.ack_configure). + + The compositor can decide not to use the client's mode and enforce a + different mode instead. + + Clients whose decoration mode depend on the xdg_toplevel state may send + a set_mode request in response to an xdg_surface.configure event and wait + for the next xdg_surface.configure event to prevent unwanted state. + Such clients are responsible for preventing configure loops and must + make sure not to send multiple successive set_mode requests with the + same decoration mode. + </description> + <arg name="mode" type="uint" enum="mode" summary="the decoration mode"/> + </request> + + <request name="unset_mode"> + <description summary="unset the decoration mode"> + Unset the toplevel surface decoration mode. This informs the compositor + that the client doesn't prefer a particular decoration mode. + + This request has the same semantics as set_mode. + </description> + </request> + + <event name="configure"> + <description summary="suggest a surface change"> + The configure event asks the client to change its decoration mode. The + configured state should not be applied immediately. Clients must send an + ack_configure in response to this event. See xdg_surface.configure and + xdg_surface.ack_configure for details. + + A configure event can be sent at any time. The specified mode must be + obeyed by the client. + </description> + <arg name="mode" type="uint" enum="mode" summary="the decoration mode"/> + </event> + </interface> +</protocol> |