| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="wp_primary_selection_unstable_v1"> |
| 3 |
<copyright> |
| 4 |
Copyright © 2015, 2016 Red Hat |
| 5 |
|
| 6 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 7 |
copy of this software and associated documentation files (the "Software"), |
| 8 |
to deal in the Software without restriction, including without limitation |
| 9 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 10 |
and/or sell copies of the Software, and to permit persons to whom the |
| 11 |
Software is furnished to do so, subject to the following conditions: |
| 12 |
|
| 13 |
The above copyright notice and this permission notice (including the next |
| 14 |
paragraph) shall be included in all copies or substantial portions of the |
| 15 |
Software. |
| 16 |
|
| 17 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 18 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 19 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 20 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 21 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 22 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 23 |
DEALINGS IN THE SOFTWARE. |
| 24 |
</copyright> |
| 25 |
|
| 26 |
<description summary="Primary selection protocol"> |
| 27 |
This protocol provides the ability to have a primary selection device to |
| 28 |
match that of the X server. This primary selection is a shortcut to the |
| 29 |
common clipboard selection, where text just needs to be selected in order |
| 30 |
to allow copying it elsewhere. The de facto way to perform this action |
| 31 |
is the middle mouse button, although it is not limited to this one. |
| 32 |
|
| 33 |
Clients wishing to honor primary selection should create a primary |
| 34 |
selection source and set it as the selection through |
| 35 |
wp_primary_selection_device.set_selection whenever the text selection |
| 36 |
changes. In order to minimize calls in pointer-driven text selection, |
| 37 |
it should happen only once after the operation finished. Similarly, |
| 38 |
a NULL source should be set when text is unselected. |
| 39 |
|
| 40 |
wp_primary_selection_offer objects are first announced through the |
| 41 |
wp_primary_selection_device.data_offer event. Immediately after this event, |
| 42 |
the primary data offer will emit wp_primary_selection_offer.offer events |
| 43 |
to let know of the mime types being offered. |
| 44 |
|
| 45 |
When the primary selection changes, the client with the keyboard focus |
| 46 |
will receive wp_primary_selection_device.selection events. Only the client |
| 47 |
with the keyboard focus will receive such events with a non-NULL |
| 48 |
wp_primary_selection_offer. Across keyboard focus changes, previously |
| 49 |
focused clients will receive wp_primary_selection_device.events with a |
| 50 |
NULL wp_primary_selection_offer. |
| 51 |
|
| 52 |
In order to request the primary selection data, the client must pass |
| 53 |
a recent serial pertaining to the press event that is triggering the |
| 54 |
operation, if the compositor deems the serial valid and recent, the |
| 55 |
wp_primary_selection_source.send event will happen in the other end |
| 56 |
to let the transfer begin. The client owning the primary selection |
| 57 |
should write the requested data, and close the file descriptor |
| 58 |
immediately. |
| 59 |
|
| 60 |
If the primary selection owner client disappeared during the transfer, |
| 61 |
the client reading the data will receive a |
| 62 |
wp_primary_selection_device.selection event with a NULL |
| 63 |
wp_primary_selection_offer, the client should take this as a hint |
| 64 |
to finish the reads related to the no longer existing offer. |
| 65 |
|
| 66 |
The primary selection owner should be checking for errors during |
| 67 |
writes, merely cancelling the ongoing transfer if any happened. |
| 68 |
</description> |
| 69 |
|
| 70 |
<interface name="zwp_primary_selection_device_manager_v1" version="1"> |
| 71 |
<description summary="X primary selection emulation"> |
| 72 |
The primary selection device manager is a singleton global object that |
| 73 |
provides access to the primary selection. It allows to create |
| 74 |
wp_primary_selection_source objects, as well as retrieving the per-seat |
| 75 |
wp_primary_selection_device objects. |
| 76 |
</description> |
| 77 |
|
| 78 |
<request name="create_source"> |
| 79 |
<description summary="create a new primary selection source"> |
| 80 |
Create a new primary selection source. |
| 81 |
</description> |
| 82 |
<arg name="id" type="new_id" interface="zwp_primary_selection_source_v1"/> |
| 83 |
</request> |
| 84 |
|
| 85 |
<request name="get_device"> |
| 86 |
<description summary="create a new primary selection device"> |
| 87 |
Create a new data device for a given seat. |
| 88 |
</description> |
| 89 |
<arg name="id" type="new_id" interface="zwp_primary_selection_device_v1"/> |
| 90 |
<arg name="seat" type="object" interface="wl_seat"/> |
| 91 |
</request> |
| 92 |
|
| 93 |
<request name="destroy" type="destructor"> |
| 94 |
<description summary="destroy the primary selection device manager"> |
| 95 |
Destroy the primary selection device manager. |
| 96 |
</description> |
| 97 |
</request> |
| 98 |
</interface> |
| 99 |
|
| 100 |
<interface name="zwp_primary_selection_device_v1" version="1"> |
| 101 |
<request name="set_selection"> |
| 102 |
<description summary="set the primary selection"> |
| 103 |
Replaces the current selection. The previous owner of the primary |
| 104 |
selection will receive a wp_primary_selection_source.cancelled event. |
| 105 |
|
| 106 |
To unset the selection, set the source to NULL. |
| 107 |
</description> |
| 108 |
<arg name="source" type="object" interface="zwp_primary_selection_source_v1" allow-null="true"/> |
| 109 |
<arg name="serial" type="uint" summary="serial of the event that triggered this request"/> |
| 110 |
</request> |
| 111 |
|
| 112 |
<event name="data_offer"> |
| 113 |
<description summary="introduce a new wp_primary_selection_offer"> |
| 114 |
Introduces a new wp_primary_selection_offer object that may be used |
| 115 |
to receive the current primary selection. Immediately following this |
| 116 |
event, the new wp_primary_selection_offer object will send |
| 117 |
wp_primary_selection_offer.offer events to describe the offered mime |
| 118 |
types. |
| 119 |
</description> |
| 120 |
<arg name="offer" type="new_id" interface="zwp_primary_selection_offer_v1"/> |
| 121 |
</event> |
| 122 |
|
| 123 |
<event name="selection"> |
| 124 |
<description summary="advertise a new primary selection"> |
| 125 |
The wp_primary_selection_device.selection event is sent to notify the |
| 126 |
client of a new primary selection. This event is sent after the |
| 127 |
wp_primary_selection.data_offer event introducing this object, and after |
| 128 |
the offer has announced its mimetypes through |
| 129 |
wp_primary_selection_offer.offer. |
| 130 |
|
| 131 |
The data_offer is valid until a new offer or NULL is received |
| 132 |
or until the client loses keyboard focus. The client must destroy the |
| 133 |
previous selection data_offer, if any, upon receiving this event. |
| 134 |
</description> |
| 135 |
<arg name="id" type="object" interface="zwp_primary_selection_offer_v1" allow-null="true"/> |
| 136 |
</event> |
| 137 |
|
| 138 |
<request name="destroy" type="destructor"> |
| 139 |
<description summary="destroy the primary selection device"> |
| 140 |
Destroy the primary selection device. |
| 141 |
</description> |
| 142 |
</request> |
| 143 |
</interface> |
| 144 |
|
| 145 |
<interface name="zwp_primary_selection_offer_v1" version="1"> |
| 146 |
<description summary="offer to transfer primary selection contents"> |
| 147 |
A wp_primary_selection_offer represents an offer to transfer the contents |
| 148 |
of the primary selection clipboard to the client. Similar to |
| 149 |
wl_data_offer, the offer also describes the mime types that the data can |
| 150 |
be converted to and provides the mechanisms for transferring the data |
| 151 |
directly to the client. |
| 152 |
</description> |
| 153 |
|
| 154 |
<request name="receive"> |
| 155 |
<description summary="request that the data is transferred"> |
| 156 |
To transfer the contents of the primary selection clipboard, the client |
| 157 |
issues this request and indicates the mime type that it wants to |
| 158 |
receive. The transfer happens through the passed file descriptor |
| 159 |
(typically created with the pipe system call). The source client writes |
| 160 |
the data in the mime type representation requested and then closes the |
| 161 |
file descriptor. |
| 162 |
|
| 163 |
The receiving client reads from the read end of the pipe until EOF and |
| 164 |
closes its end, at which point the transfer is complete. |
| 165 |
</description> |
| 166 |
<arg name="mime_type" type="string"/> |
| 167 |
<arg name="fd" type="fd"/> |
| 168 |
</request> |
| 169 |
|
| 170 |
<request name="destroy" type="destructor"> |
| 171 |
<description summary="destroy the primary selection offer"> |
| 172 |
Destroy the primary selection offer. |
| 173 |
</description> |
| 174 |
</request> |
| 175 |
|
| 176 |
<event name="offer"> |
| 177 |
<description summary="advertise offered mime type"> |
| 178 |
Sent immediately after creating announcing the |
| 179 |
wp_primary_selection_offer through |
| 180 |
wp_primary_selection_device.data_offer. One event is sent per offered |
| 181 |
mime type. |
| 182 |
</description> |
| 183 |
<arg name="mime_type" type="string"/> |
| 184 |
</event> |
| 185 |
</interface> |
| 186 |
|
| 187 |
<interface name="zwp_primary_selection_source_v1" version="1"> |
| 188 |
<description summary="offer to replace the contents of the primary selection"> |
| 189 |
The source side of a wp_primary_selection_offer, it provides a way to |
| 190 |
describe the offered data and respond to requests to transfer the |
| 191 |
requested contents of the primary selection clipboard. |
| 192 |
</description> |
| 193 |
|
| 194 |
<request name="offer"> |
| 195 |
<description summary="add an offered mime type"> |
| 196 |
This request adds a mime type to the set of mime types advertised to |
| 197 |
targets. Can be called several times to offer multiple types. |
| 198 |
</description> |
| 199 |
<arg name="mime_type" type="string"/> |
| 200 |
</request> |
| 201 |
|
| 202 |
<request name="destroy" type="destructor"> |
| 203 |
<description summary="destroy the primary selection source"> |
| 204 |
Destroy the primary selection source. |
| 205 |
</description> |
| 206 |
</request> |
| 207 |
|
| 208 |
<event name="send"> |
| 209 |
<description summary="send the primary selection contents"> |
| 210 |
Request for the current primary selection contents from the client. |
| 211 |
Send the specified mime type over the passed file descriptor, then |
| 212 |
close it. |
| 213 |
</description> |
| 214 |
<arg name="mime_type" type="string"/> |
| 215 |
<arg name="fd" type="fd"/> |
| 216 |
</event> |
| 217 |
|
| 218 |
<event name="cancelled"> |
| 219 |
<description summary="request for primary selection contents was canceled"> |
| 220 |
This primary selection source is no longer valid. The client should |
| 221 |
clean up and destroy this primary selection source. |
| 222 |
</description> |
| 223 |
</event> |
| 224 |
</interface> |
| 225 |
</protocol> |