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