🛠️🐜 Antkeeper superbuild with dependencies included https://antkeeper.com
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

225 lines
10 KiB

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