SDL
200 строк · 9.0 Кб
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_foreign_unstable_v2">3
4<copyright>5Copyright © 2015-2016 Red Hat Inc.
6
7Permission is hereby granted, free of charge, to any person obtaining a
8copy of this software and associated documentation files (the "Software"),
9to deal in the Software without restriction, including without limitation
10the rights to use, copy, modify, merge, publish, distribute, sublicense,
11and/or sell copies of the Software, and to permit persons to whom the
12Software is furnished to do so, subject to the following conditions:
13
14The above copyright notice and this permission notice (including the next
15paragraph) shall be included in all copies or substantial portions of the
16Software.
17
18THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24DEALINGS IN THE SOFTWARE.
25</copyright>26
27<description summary="Protocol for exporting xdg surface handles">28This protocol specifies a way for making it possible to reference a surface
29of a different client. With such a reference, a client can, by using the
30interfaces provided by this protocol, manipulate the relationship between
31its own surfaces and the surface of some other client. For example, stack
32some of its own surface above the other clients surface.
33
34In order for a client A to get a reference of a surface of client B, client
35B must first export its surface using xdg_exporter.export_toplevel. Upon
36doing this, client B will receive a handle (a unique string) that it may
37share with client A in some way (for example D-Bus). After client A has
38received the handle from client B, it may use xdg_importer.import_toplevel
39to create a reference to the surface client B just exported. See the
40corresponding requests for details.
41
42A possible use case for this is out-of-process dialogs. For example when a
43sandboxed client without file system access needs the user to select a file
44on the file system, given sandbox environment support, it can export its
45surface, passing the exported surface handle to an unsandboxed process that
46can show a file browser dialog and stack it above the sandboxed client's
47surface.
48
49Warning! The protocol described in this file is experimental and backward
50incompatible changes may be made. Backward compatible changes may be added
51together with the corresponding interface version bump. Backward
52incompatible changes are done by bumping the version number in the protocol
53and interface names and resetting the interface version. Once the protocol
54is to be declared stable, the 'z' prefix and the version number in the
55protocol and interface names are removed and the interface version number is
56reset.
57</description>58
59<interface name="zxdg_exporter_v2" version="1">60<description summary="interface for exporting surfaces">61A global interface used for exporting surfaces that can later be imported
62using xdg_importer.
63</description>64
65<request name="destroy" type="destructor">66<description summary="destroy the xdg_exporter object">67Notify the compositor that the xdg_exporter object will no longer be
68used.
69</description>70</request>71
72<enum name="error">73<description summary="error values">74These errors can be emitted in response to invalid xdg_exporter
75requests.
76</description>77<entry name="invalid_surface" value="0" summary="surface is not an xdg_toplevel"/>78</enum>79
80<request name="export_toplevel">81<description summary="export a toplevel surface">82The export_toplevel request exports the passed surface so that it can later be
83imported via xdg_importer. When called, a new xdg_exported object will
84be created and xdg_exported.handle will be sent immediately. See the
85corresponding interface and event for details.
86
87A surface may be exported multiple times, and each exported handle may
88be used to create an xdg_imported multiple times. Only xdg_toplevel
89equivalent surfaces may be exported, otherwise an invalid_surface
90protocol error is sent.
91</description>92<arg name="id" type="new_id" interface="zxdg_exported_v2"93summary="the new xdg_exported object"/>94<arg name="surface" type="object" interface="wl_surface"95summary="the surface to export"/>96</request>97</interface>98
99<interface name="zxdg_importer_v2" version="1">100<description summary="interface for importing surfaces">101A global interface used for importing surfaces exported by xdg_exporter.
102With this interface, a client can create a reference to a surface of
103another client.
104</description>105
106<request name="destroy" type="destructor">107<description summary="destroy the xdg_importer object">108Notify the compositor that the xdg_importer object will no longer be
109used.
110</description>111</request>112
113<request name="import_toplevel">114<description summary="import a toplevel surface">115The import_toplevel request imports a surface from any client given a handle
116retrieved by exporting said surface using xdg_exporter.export_toplevel.
117When called, a new xdg_imported object will be created. This new object
118represents the imported surface, and the importing client can
119manipulate its relationship using it. See xdg_imported for details.
120</description>121<arg name="id" type="new_id" interface="zxdg_imported_v2"122summary="the new xdg_imported object"/>123<arg name="handle" type="string"124summary="the exported surface handle"/>125</request>126</interface>127
128<interface name="zxdg_exported_v2" version="1">129<description summary="an exported surface handle">130An xdg_exported object represents an exported reference to a surface. The
131exported surface may be referenced as long as the xdg_exported object not
132destroyed. Destroying the xdg_exported invalidates any relationship the
133importer may have established using xdg_imported.
134</description>135
136<request name="destroy" type="destructor">137<description summary="unexport the exported surface">138Revoke the previously exported surface. This invalidates any
139relationship the importer may have set up using the xdg_imported created
140given the handle sent via xdg_exported.handle.
141</description>142</request>143
144<event name="handle">145<description summary="the exported surface handle">146The handle event contains the unique handle of this exported surface
147reference. It may be shared with any client, which then can use it to
148import the surface by calling xdg_importer.import_toplevel. A handle
149may be used to import the surface multiple times.
150</description>151<arg name="handle" type="string" summary="the exported surface handle"/>152</event>153</interface>154
155<interface name="zxdg_imported_v2" version="1">156<description summary="an imported surface handle">157An xdg_imported object represents an imported reference to surface exported
158by some client. A client can use this interface to manipulate
159relationships between its own surfaces and the imported surface.
160</description>161
162<enum name="error">163<description summary="error values">164These errors can be emitted in response to invalid xdg_imported
165requests.
166</description>167<entry name="invalid_surface" value="0" summary="surface is not an xdg_toplevel"/>168</enum>169
170<request name="destroy" type="destructor">171<description summary="destroy the xdg_imported object">172Notify the compositor that it will no longer use the xdg_imported
173object. Any relationship that may have been set up will at this point
174be invalidated.
175</description>176</request>177
178<request name="set_parent_of">179<description summary="set as the parent of some surface">180Set the imported surface as the parent of some surface of the client.
181The passed surface must be an xdg_toplevel equivalent, otherwise an
182invalid_surface protocol error is sent. Calling this function sets up
183a surface to surface relation with the same stacking and positioning
184semantics as xdg_toplevel.set_parent.
185</description>186<arg name="surface" type="object" interface="wl_surface"187summary="the child surface"/>188</request>189
190<event name="destroyed">191<description summary="the imported surface handle has been destroyed">192The imported surface handle has been destroyed and any relationship set
193up has been invalidated. This may happen for various reasons, for
194example if the exported surface or the exported surface handle has been
195destroyed, if the handle used for importing was invalid.
196</description>197</event>198</interface>199
200</protocol>201