| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="relative_pointer_unstable_v1"> |
| 3 |
|
| 4 |
<copyright> |
| 5 |
Copyright © 2014 Jonas Ådahl |
| 6 |
Copyright © 2015 Red Hat Inc. |
| 7 |
|
| 8 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 9 |
copy of this software and associated documentation files (the "Software"), |
| 10 |
to deal in the Software without restriction, including without limitation |
| 11 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 12 |
and/or sell copies of the Software, and to permit persons to whom the |
| 13 |
Software is furnished to do so, subject to the following conditions: |
| 14 |
|
| 15 |
The above copyright notice and this permission notice (including the next |
| 16 |
paragraph) shall be included in all copies or substantial portions of the |
| 17 |
Software. |
| 18 |
|
| 19 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 20 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 21 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 22 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 23 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 24 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 25 |
DEALINGS IN THE SOFTWARE. |
| 26 |
</copyright> |
| 27 |
|
| 28 |
<description summary="protocol for relative pointer motion events"> |
| 29 |
This protocol specifies a set of interfaces used for making clients able to |
| 30 |
receive relative pointer events not obstructed by barriers (such as the |
| 31 |
monitor edge or other pointer barriers). |
| 32 |
|
| 33 |
To start receiving relative pointer events, a client must first bind the |
| 34 |
global interface "wp_relative_pointer_manager" which, if a compositor |
| 35 |
supports relative pointer motion events, is exposed by the registry. After |
| 36 |
having created the relative pointer manager proxy object, the client uses |
| 37 |
it to create the actual relative pointer object using the |
| 38 |
"get_relative_pointer" request given a wl_pointer. The relative pointer |
| 39 |
motion events will then, when applicable, be transmitted via the proxy of |
| 40 |
the newly created relative pointer object. See the documentation of the |
| 41 |
relative pointer interface for more details. |
| 42 |
|
| 43 |
Warning! The protocol described in this file is experimental and backward |
| 44 |
incompatible changes may be made. Backward compatible changes may be added |
| 45 |
together with the corresponding interface version bump. Backward |
| 46 |
incompatible changes are done by bumping the version number in the protocol |
| 47 |
and interface names and resetting the interface version. Once the protocol |
| 48 |
is to be declared stable, the 'z' prefix and the version number in the |
| 49 |
protocol and interface names are removed and the interface version number is |
| 50 |
reset. |
| 51 |
</description> |
| 52 |
|
| 53 |
<interface name="zwp_relative_pointer_manager_v1" version="1"> |
| 54 |
<description summary="get relative pointer objects"> |
| 55 |
A global interface used for getting the relative pointer object for a |
| 56 |
given pointer. |
| 57 |
</description> |
| 58 |
|
| 59 |
<request name="destroy" type="destructor"> |
| 60 |
<description summary="destroy the relative pointer manager object"> |
| 61 |
Used by the client to notify the server that it will no longer use this |
| 62 |
relative pointer manager object. |
| 63 |
</description> |
| 64 |
</request> |
| 65 |
|
| 66 |
<request name="get_relative_pointer"> |
| 67 |
<description summary="get a relative pointer object"> |
| 68 |
Create a relative pointer interface given a wl_pointer object. See the |
| 69 |
wp_relative_pointer interface for more details. |
| 70 |
</description> |
| 71 |
<arg name="id" type="new_id" interface="zwp_relative_pointer_v1"/> |
| 72 |
<arg name="pointer" type="object" interface="wl_pointer"/> |
| 73 |
</request> |
| 74 |
</interface> |
| 75 |
|
| 76 |
<interface name="zwp_relative_pointer_v1" version="1"> |
| 77 |
<description summary="relative pointer object"> |
| 78 |
A wp_relative_pointer object is an extension to the wl_pointer interface |
| 79 |
used for emitting relative pointer events. It shares the same focus as |
| 80 |
wl_pointer objects of the same seat and will only emit events when it has |
| 81 |
focus. |
| 82 |
</description> |
| 83 |
|
| 84 |
<request name="destroy" type="destructor"> |
| 85 |
<description summary="release the relative pointer object"/> |
| 86 |
</request> |
| 87 |
|
| 88 |
<event name="relative_motion"> |
| 89 |
<description summary="relative pointer motion"> |
| 90 |
Relative x/y pointer motion from the pointer of the seat associated with |
| 91 |
this object. |
| 92 |
|
| 93 |
A relative motion is in the same dimension as regular wl_pointer motion |
| 94 |
events, except they do not represent an absolute position. For example, |
| 95 |
moving a pointer from (x, y) to (x', y') would have the equivalent |
| 96 |
relative motion (x' - x, y' - y). If a pointer motion caused the |
| 97 |
absolute pointer position to be clipped by for example the edge of the |
| 98 |
monitor, the relative motion is unaffected by the clipping and will |
| 99 |
represent the unclipped motion. |
| 100 |
|
| 101 |
This event also contains non-accelerated motion deltas. The |
| 102 |
non-accelerated delta is, when applicable, the regular pointer motion |
| 103 |
delta as it was before having applied motion acceleration and other |
| 104 |
transformations such as normalization. |
| 105 |
|
| 106 |
Note that the non-accelerated delta does not represent 'raw' events as |
| 107 |
they were read from some device. Pointer motion acceleration is device- |
| 108 |
and configuration-specific and non-accelerated deltas and accelerated |
| 109 |
deltas may have the same value on some devices. |
| 110 |
|
| 111 |
Relative motions are not coupled to wl_pointer.motion events, and can be |
| 112 |
sent in combination with such events, but also independently. There may |
| 113 |
also be scenarios where wl_pointer.motion is sent, but there is no |
| 114 |
relative motion. The order of an absolute and relative motion event |
| 115 |
originating from the same physical motion is not guaranteed. |
| 116 |
|
| 117 |
If the client needs button events or focus state, it can receive them |
| 118 |
from a wl_pointer object of the same seat that the wp_relative_pointer |
| 119 |
object is associated with. |
| 120 |
</description> |
| 121 |
<arg name="utime_hi" type="uint" |
| 122 |
summary="high 32 bits of a 64 bit timestamp with microsecond granularity"/> |
| 123 |
<arg name="utime_lo" type="uint" |
| 124 |
summary="low 32 bits of a 64 bit timestamp with microsecond granularity"/> |
| 125 |
<arg name="dx" type="fixed" |
| 126 |
summary="the x component of the motion vector"/> |
| 127 |
<arg name="dy" type="fixed" |
| 128 |
summary="the y component of the motion vector"/> |
| 129 |
<arg name="dx_unaccel" type="fixed" |
| 130 |
summary="the x component of the unaccelerated motion vector"/> |
| 131 |
<arg name="dy_unaccel" type="fixed" |
| 132 |
summary="the y component of the unaccelerated motion vector"/> |
| 133 |
</event> |
| 134 |
</interface> |
| 135 |
|
| 136 |
</protocol> |