1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="gtk_primary_selection"> 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="gtk_primary_selection_device_manager" 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="gtk_primary_selection_source"/> 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="gtk_primary_selection_device"/> 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="gtk_primary_selection_device" 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 selection 104 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="gtk_primary_selection_source" 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="gtk_primary_selection_offer"/> 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="gtk_primary_selection_offer" 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="gtk_primary_selection_offer" 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 source 150 will transferthat the 151 data can be converted to and provides the mechanisms for transferring the 152 data directly to the client. 153 </description> 154 155 <request name="receive"> 156 <description summary="request that the data is transferred"> 157 To transfer the contents of the primary selection clipboard, the client 158 issues this request and indicates the mime type that it wants to 159 receive. The transfer happens through the passed file descriptor 160 (typically created with the pipe system call). The source client writes 161 the data in the mime type representation requested and then closes the 162 file descriptor. 163 164 The receiving client reads from the read end of the pipe until EOF and 165 closes its end, at which point the transfer is complete. 166 </description> 167 <arg name="mime_type" type="string"/> 168 <arg name="fd" type="fd"/> 169 </request> 170 171 <request name="destroy" type="destructor"> 172 <description summary="destroy the primary selection offer"> 173 Destroy the primary selection offer. 174 </description> 175 </request> 176 177 <event name="offer"> 178 <description summary="advertise offered mime type"> 179 Sent immediately after creating announcing the wp_primary_selection_offer 180 through wp_primary_selection_device.data_offer. One event is sent per 181 offered mime type. 182 </description> 183 <arg name="mime_type" type="string"/> 184 </event> 185 </interface> 186 187 <interface name="gtk_primary_selection_source" 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> 226