1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/wayland-protocols/relative-pointer-unstable-v1.xml Mon Jun 25 09:37:25 2018 -0700
1.3 @@ -0,0 +1,136 @@
1.4 +<?xml version="1.0" encoding="UTF-8"?>
1.5 +<protocol name="relative_pointer_unstable_v1">
1.6 +
1.7 + <copyright>
1.8 + Copyright © 2014 Jonas Ådahl
1.9 + Copyright © 2015 Red Hat Inc.
1.10 +
1.11 + Permission is hereby granted, free of charge, to any person obtaining a
1.12 + copy of this software and associated documentation files (the "Software"),
1.13 + to deal in the Software without restriction, including without limitation
1.14 + the rights to use, copy, modify, merge, publish, distribute, sublicense,
1.15 + and/or sell copies of the Software, and to permit persons to whom the
1.16 + Software is furnished to do so, subject to the following conditions:
1.17 +
1.18 + The above copyright notice and this permission notice (including the next
1.19 + paragraph) shall be included in all copies or substantial portions of the
1.20 + Software.
1.21 +
1.22 + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1.23 + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1.24 + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
1.25 + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1.26 + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
1.27 + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
1.28 + DEALINGS IN THE SOFTWARE.
1.29 + </copyright>
1.30 +
1.31 + <description summary="protocol for relative pointer motion events">
1.32 + This protocol specifies a set of interfaces used for making clients able to
1.33 + receive relative pointer events not obstructed by barriers (such as the
1.34 + monitor edge or other pointer barriers).
1.35 +
1.36 + To start receiving relative pointer events, a client must first bind the
1.37 + global interface "wp_relative_pointer_manager" which, if a compositor
1.38 + supports relative pointer motion events, is exposed by the registry. After
1.39 + having created the relative pointer manager proxy object, the client uses
1.40 + it to create the actual relative pointer object using the
1.41 + "get_relative_pointer" request given a wl_pointer. The relative pointer
1.42 + motion events will then, when applicable, be transmitted via the proxy of
1.43 + the newly created relative pointer object. See the documentation of the
1.44 + relative pointer interface for more details.
1.45 +
1.46 + Warning! The protocol described in this file is experimental and backward
1.47 + incompatible changes may be made. Backward compatible changes may be added
1.48 + together with the corresponding interface version bump. Backward
1.49 + incompatible changes are done by bumping the version number in the protocol
1.50 + and interface names and resetting the interface version. Once the protocol
1.51 + is to be declared stable, the 'z' prefix and the version number in the
1.52 + protocol and interface names are removed and the interface version number is
1.53 + reset.
1.54 + </description>
1.55 +
1.56 + <interface name="zwp_relative_pointer_manager_v1" version="1">
1.57 + <description summary="get relative pointer objects">
1.58 + A global interface used for getting the relative pointer object for a
1.59 + given pointer.
1.60 + </description>
1.61 +
1.62 + <request name="destroy" type="destructor">
1.63 + <description summary="destroy the relative pointer manager object">
1.64 + Used by the client to notify the server that it will no longer use this
1.65 + relative pointer manager object.
1.66 + </description>
1.67 + </request>
1.68 +
1.69 + <request name="get_relative_pointer">
1.70 + <description summary="get a relative pointer object">
1.71 + Create a relative pointer interface given a wl_pointer object. See the
1.72 + wp_relative_pointer interface for more details.
1.73 + </description>
1.74 + <arg name="id" type="new_id" interface="zwp_relative_pointer_v1"/>
1.75 + <arg name="pointer" type="object" interface="wl_pointer"/>
1.76 + </request>
1.77 + </interface>
1.78 +
1.79 + <interface name="zwp_relative_pointer_v1" version="1">
1.80 + <description summary="relative pointer object">
1.81 + A wp_relative_pointer object is an extension to the wl_pointer interface
1.82 + used for emitting relative pointer events. It shares the same focus as
1.83 + wl_pointer objects of the same seat and will only emit events when it has
1.84 + focus.
1.85 + </description>
1.86 +
1.87 + <request name="destroy" type="destructor">
1.88 + <description summary="release the relative pointer object"/>
1.89 + </request>
1.90 +
1.91 + <event name="relative_motion">
1.92 + <description summary="relative pointer motion">
1.93 + Relative x/y pointer motion from the pointer of the seat associated with
1.94 + this object.
1.95 +
1.96 + A relative motion is in the same dimension as regular wl_pointer motion
1.97 + events, except they do not represent an absolute position. For example,
1.98 + moving a pointer from (x, y) to (x', y') would have the equivalent
1.99 + relative motion (x' - x, y' - y). If a pointer motion caused the
1.100 + absolute pointer position to be clipped by for example the edge of the
1.101 + monitor, the relative motion is unaffected by the clipping and will
1.102 + represent the unclipped motion.
1.103 +
1.104 + This event also contains non-accelerated motion deltas. The
1.105 + non-accelerated delta is, when applicable, the regular pointer motion
1.106 + delta as it was before having applied motion acceleration and other
1.107 + transformations such as normalization.
1.108 +
1.109 + Note that the non-accelerated delta does not represent 'raw' events as
1.110 + they were read from some device. Pointer motion acceleration is device-
1.111 + and configuration-specific and non-accelerated deltas and accelerated
1.112 + deltas may have the same value on some devices.
1.113 +
1.114 + Relative motions are not coupled to wl_pointer.motion events, and can be
1.115 + sent in combination with such events, but also independently. There may
1.116 + also be scenarios where wl_pointer.motion is sent, but there is no
1.117 + relative motion. The order of an absolute and relative motion event
1.118 + originating from the same physical motion is not guaranteed.
1.119 +
1.120 + If the client needs button events or focus state, it can receive them
1.121 + from a wl_pointer object of the same seat that the wp_relative_pointer
1.122 + object is associated with.
1.123 + </description>
1.124 + <arg name="utime_hi" type="uint"
1.125 + summary="high 32 bits of a 64 bit timestamp with microsecond granularity"/>
1.126 + <arg name="utime_lo" type="uint"
1.127 + summary="low 32 bits of a 64 bit timestamp with microsecond granularity"/>
1.128 + <arg name="dx" type="fixed"
1.129 + summary="the x component of the motion vector"/>
1.130 + <arg name="dy" type="fixed"
1.131 + summary="the y component of the motion vector"/>
1.132 + <arg name="dx_unaccel" type="fixed"
1.133 + summary="the x component of the unaccelerated motion vector"/>
1.134 + <arg name="dy_unaccel" type="fixed"
1.135 + summary="the y component of the unaccelerated motion vector"/>
1.136 + </event>
1.137 + </interface>
1.138 +
1.139 +</protocol>