1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_shell">
3
4 <copyright>
5 Copyright © 2008-2013 Kristian Høgsberg
6 Copyright © 2013 Rafael Antognolli
7 Copyright © 2013 Jasper St. Pierre
8 Copyright © 2010-2013 Intel Corporation
9
10 Permission to use, copy, modify, distribute, and sell this
11 software and its documentation for any purpose is hereby granted
12 without fee, provided that the above copyright notice appear in
13 all copies and that both that copyright notice and this permission
14 notice appear in supporting documentation, and that the name of
15 the copyright holders not be used in advertising or publicity
16 pertaining to distribution of the software without specific,
17 written prior permission. The copyright holders make no
18 representations about the suitability of this software for any
19 purpose. It is provided "as is" without express or implied
20 warranty.
21
22 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
23 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
24 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
25 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
26 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
27 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
28 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
29 THIS SOFTWARE.
30 </copyright>
31
32 <interface name="xdg_shell" version="1">
33 <description summary="create desktop-style surfaces">
34 xdg_shell allows clients to turn a wl_surface into a "real window"
35 which can be dragged, resized, stacked, and moved around by the
36 user. Everything about this interface is suited towards traditional
37 desktop environments.
38 </description>
39
40 <enum name="version">
41 <description summary="latest protocol version">
42 The 'current' member of this enum gives the version of the
43 protocol. Implementations can compare this to the version
44 they implement using static_assert to ensure the protocol and
45 implementation versions match.
46 </description>
47 <entry name="current" value="5" summary="Always the latest version"/>
48 </enum>
49
50 <enum name="error">
51 <entry name="role" value="0" summary="given wl_surface has another role"/>
52 <entry name="defunct_surfaces" value="1" summary="xdg_shell was destroyed before children"/>
53 <entry name="not_the_topmost_popup" value="2" summary="the client tried to map or destroy a non-topmost popup"/>
54 <entry name="invalid_popup_parent" value="3" summary="the client specified an invalid popup parent surface"/>
55 </enum>
56
57 <request name="destroy" type="destructor">
58 <description summary="destroy xdg_shell">
59 Destroy this xdg_shell object.
60
61 Destroying a bound xdg_shell object while there are surfaces
62 still alive created by this xdg_shell object instance is illegal
63 and will result in a protocol error.
64 </description>
65 </request>
66
67 <request name="use_unstable_version">
68 <description summary="enable use of this unstable version">
69 Negotiate the unstable version of the interface. This
70 mechanism is in place to ensure client and server agree on the
71 unstable versions of the protocol that they speak or exit
72 cleanly if they don't agree. This request will go away once
73 the xdg-shell protocol is stable.
74 </description>
75 <arg name="version" type="int"/>
76 </request>
77
78 <request name="get_xdg_surface">
79 <description summary="create a shell surface from a surface">
80 This creates an xdg_surface for the given surface and gives it the
81 xdg_surface role. See the documentation of xdg_surface for more details.
82 </description>
83 <arg name="id" type="new_id" interface="xdg_surface"/>
84 <arg name="surface" type="object" interface="wl_surface"/>
85 </request>
86
87 <request name="get_xdg_popup">
88 <description summary="create a popup for a surface">
89 This creates an xdg_popup for the given surface and gives it the
90 xdg_popup role. See the documentation of xdg_popup for more details.
91
92 This request must be used in response to some sort of user action
93 like a button press, key press, or touch down event.
94 </description>
95 <arg name="id" type="new_id" interface="xdg_popup"/>
96 <arg name="surface" type="object" interface="wl_surface"/>
97 <arg name="parent" type="object" interface="wl_surface"/>
98 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
99 <arg name="serial" type="uint" summary="the serial of the user event"/>
100 <arg name="x" type="int"/>
101 <arg name="y" type="int"/>
102 </request>
103
104 <event name="ping">
105 <description summary="check if the client is alive">
106 The ping event asks the client if it's still alive. Pass the
107 serial specified in the event back to the compositor by sending
108 a "pong" request back with the specified serial.
109
110 Compositors can use this to determine if the client is still
111 alive. It's unspecified what will happen if the client doesn't
112 respond to the ping request, or in what timeframe. Clients should
113 try to respond in a reasonable amount of time.
114 </description>
115 <arg name="serial" type="uint" summary="pass this to the pong request"/>
116 </event>
117
118 <request name="pong">
119 <description summary="respond to a ping event">
120 A client must respond to a ping event with a pong request or
121 the client may be deemed unresponsive.
122 </description>
123 <arg name="serial" type="uint" summary="serial of the ping event"/>
124 </request>
125 </interface>
126
127 <interface name="xdg_surface" version="1">
128 <description summary="A desktop window">
129 An interface that may be implemented by a wl_surface, for
130 implementations that provide a desktop-style user interface.
131
132 It provides requests to treat surfaces like windows, allowing to set
133 properties like maximized, fullscreen, minimized, and to move and resize
134 them, and associate metadata like title and app id.
135
136 The client must call wl_surface.commit on the corresponding wl_surface
137 for the xdg_surface state to take effect. Prior to committing the new
138 state, it can set up initial configuration, such as maximizing or setting
139 a window geometry.
140
141 Even without attaching a buffer the compositor must respond to initial
142 committed configuration, for instance sending a configure event with
143 expected window geometry if the client maximized its surface during
144 initialization.
145
146 For a surface to be mapped by the compositor the client must have
147 committed both an xdg_surface state and a buffer.
148 </description>
149
150 <request name="destroy" type="destructor">
151 <description summary="Destroy the xdg_surface">
152 Unmap and destroy the window. The window will be effectively
153 hidden from the user's point of view, and all state like
154 maximization, fullscreen, and so on, will be lost.
155 </description>
156 </request>
157
158 <request name="set_parent">
159 <description summary="set the parent of this surface">
160 Set the "parent" of this surface. This window should be stacked
161 above a parent. The parent surface must be mapped as long as this
162 surface is mapped.
163
164 Parent windows should be set on dialogs, toolboxes, or other
165 "auxiliary" surfaces, so that the parent is raised when the dialog
166 is raised.
167 </description>
168 <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
169 </request>
170
171 <request name="set_title">
172 <description summary="set surface title">
173 Set a short title for the surface.
174
175 This string may be used to identify the surface in a task bar,
176 window list, or other user interface elements provided by the
177 compositor.
178
179 The string must be encoded in UTF-8.
180 </description>
181 <arg name="title" type="string"/>
182 </request>
183
184 <request name="set_app_id">
185 <description summary="set application ID">
186 Set an application identifier for the surface.
187
188 The app ID identifies the general class of applications to which
189 the surface belongs. The compositor can use this to group multiple
190 surfaces together, or to determine how to launch a new application.
191
192 See the desktop-entry specification [0] for more details on
193 application identifiers and how they relate to well-known D-Bus
194 names and .desktop files.
195
196 [0] http://standards.freedesktop.org/desktop-entry-spec/
197 </description>
198 <arg name="app_id" type="string"/>
199 </request>
200
201 <request name="show_window_menu">
202 <description summary="show the window menu">
203 Clients implementing client-side decorations might want to show
204 a context menu when right-clicking on the decorations, giving the
205 user a menu that they can use to maximize or minimize the window.
206
207 This request asks the compositor to pop up such a window menu at
208 the given position, relative to the local surface coordinates of
209 the parent surface. There are no guarantees as to what menu items
210 the window menu contains.
211
212 This request must be used in response to some sort of user action
213 like a button press, key press, or touch down event.
214 </description>
215
216 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
217 <arg name="serial" type="uint" summary="the serial of the user event"/>
218 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
219 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
220 </request>
221
222 <request name="move">
223 <description summary="start an interactive move">
224 Start an interactive, user-driven move of the surface.
225
226 This request must be used in response to some sort of user action
227 like a button press, key press, or touch down event.
228
229 The server may ignore move requests depending on the state of
230 the surface (e.g. fullscreen or maximized).
231 </description>
232 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
233 <arg name="serial" type="uint" summary="the serial of the user event"/>
234 </request>
235
236 <enum name="resize_edge">
237 <description summary="edge values for resizing">
238 These values are used to indicate which edge of a surface
239 is being dragged in a resize operation. The server may
240 use this information to adapt its behavior, e.g. choose
241 an appropriate cursor image.
242 </description>
243 <entry name="none" value="0"/>
244 <entry name="top" value="1"/>
245 <entry name="bottom" value="2"/>
246 <entry name="left" value="4"/>
247 <entry name="top_left" value="5"/>
248 <entry name="bottom_left" value="6"/>
249 <entry name="right" value="8"/>
250 <entry name="top_right" value="9"/>
251 <entry name="bottom_right" value="10"/>
252 </enum>
253
254 <request name="resize">
255 <description summary="start an interactive resize">
256 Start a user-driven, interactive resize of the surface.
257
258 This request must be used in response to some sort of user action
259 like a button press, key press, or touch down event.
260
261 The server may ignore resize requests depending on the state of
262 the surface (e.g. fullscreen or maximized).
263 </description>
264 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
265 <arg name="serial" type="uint" summary="the serial of the user event"/>
266 <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
267 </request>
268
269 <enum name="state">
270 <description summary="types of state on the surface">
271 The different state values used on the surface. This is designed for
272 state values like maximized, fullscreen. It is paired with the
273 configure event to ensure that both the client and the compositor
274 setting the state can be synchronized.
275
276 States set in this way are double-buffered. They will get applied on
277 the next commit.
278
279 Desktop environments may extend this enum by taking up a range of
280 values and documenting the range they chose in this description.
281 They are not required to document the values for the range that they
282 chose. Ideally, any good extensions from a desktop environment should
283 make its way into standardization into this enum.
284
285 The current reserved ranges are:
286
287 0x0000 - 0x0FFF: xdg-shell core values, documented below.
288 0x1000 - 0x1FFF: GNOME
289 </description>
290 <entry name="maximized" value="1" summary="the surface is maximized">
291 The surface is maximized. The window geometry specified in the configure
292 event must be obeyed by the client.
293 </entry>
294 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
295 The surface is fullscreen. The window geometry specified in the configure
296 event must be obeyed by the client.
297 </entry>
298 <entry name="resizing" value="3">
299 The surface is being resized. The window geometry specified in the
300 configure event is a maximum; the client cannot resize beyond it.
301 Clients that have aspect ratio or cell sizing configuration can use
302 a smaller size, however.
303 </entry>
304 <entry name="activated" value="4">
305 Client window decorations should be painted as if the window is
306 active. Do not assume this means that the window actually has
307 keyboard or pointer focus.
308 </entry>
309 </enum>
310
311 <event name="configure">
312 <description summary="suggest a surface change">
313 The configure event asks the client to resize its surface or to
314 change its state.
315
316 The width and height arguments specify a hint to the window
317 about how its surface should be resized in window geometry
318 coordinates. See set_window_geometry.
319
320 If the width or height arguments are zero, it means the client
321 should decide its own window dimension. This may happen when the
322 compositor need to configure the state of the surface but doesn't
323 have any information about any previous or expected dimension.
324
325 The states listed in the event specify how the width/height
326 arguments should be interpreted, and possibly how it should be
327 drawn.
328
329 Clients should arrange their surface for the new size and
330 states, and then send a ack_configure request with the serial
331 sent in this configure event at some point before committing
332 the new surface.
333
334 If the client receives multiple configure events before it
335 can respond to one, it is free to discard all but the last
336 event it received.
337 </description>
338
339 <arg name="width" type="int"/>
340 <arg name="height" type="int"/>
341 <arg name="states" type="array"/>
342 <arg name="serial" type="uint"/>
343 </event>
344
345 <request name="ack_configure">
346 <description summary="ack a configure event">
347 When a configure event is received, if a client commits the
348 surface in response to the configure event, then the client
349 must make a ack_configure request before the commit request,
350 passing along the serial of the configure event.
351
352 For instance, the compositor might use this information to move
353 a surface to the top left only when the client has drawn itself
354 for the maximized or fullscreen state.
355
356 If the client receives multiple configure events before it
357 can respond to one, it only has to ack the last configure event.
358 </description>
359 <arg name="serial" type="uint" summary="the serial from the configure event"/>
360 </request>
361
362 <request name="set_window_geometry">
363 <description summary="set the new window geometry">
364 The window geometry of a window is its "visible bounds" from the
365 user's perspective. Client-side decorations often have invisible
366 portions like drop-shadows which should be ignored for the
367 purposes of aligning, placing and constraining windows.
368
369 The window geometry is double buffered, and will be applied at the
370 time wl_surface.commit of the corresponding wl_surface is called.
371
372 Once the window geometry of the surface is set once, it is not
373 possible to unset it, and it will remain the same until
374 set_window_geometry is called again, even if a new subsurface or
375 buffer is attached.
376
377 If never set, the value is the full bounds of the surface,
378 including any subsurfaces. This updates dynamically on every
379 commit. This unset mode is meant for extremely simple clients.
380
381 If responding to a configure event, the window geometry in here
382 must respect the sizing negotiations specified by the states in
383 the configure event.
384
385 The arguments are given in the surface local coordinate space of
386 the wl_surface associated with this xdg_surface.
387
388 The width and height must be greater than zero.
389 </description>
390 <arg name="x" type="int"/>
391 <arg name="y" type="int"/>
392 <arg name="width" type="int"/>
393 <arg name="height" type="int"/>
394 </request>
395
396 <request name="set_maximized" />
397 <request name="unset_maximized" />
398
399 <request name="set_fullscreen">
400 <description summary="set the window as fullscreen on a monitor">
401 Make the surface fullscreen.
402
403 You can specify an output that you would prefer to be fullscreen.
404 If this value is NULL, it's up to the compositor to choose which
405 display will be used to map this surface.
406
407 If the surface doesn't cover the whole output, the compositor will
408 position the surface in the center of the output and compensate with
409 black borders filling the rest of the output.
410 </description>
411 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
412 </request>
413 <request name="unset_fullscreen" />
414
415 <request name="set_minimized">
416 <description summary="set the window as minimized">
417 Request that the compositor minimize your surface. There is no
418 way to know if the surface is currently minimized, nor is there
419 any way to unset minimization on this surface.
420
421 If you are looking to throttle redrawing when minimized, please
422 instead use the wl_surface.frame event for this, as this will
423 also work with live previews on windows in Alt-Tab, Expose or
424 similar compositor features.
425 </description>
426 </request>
427
428 <event name="close">
429 <description summary="surface wants to be closed">
430 The close event is sent by the compositor when the user
431 wants the surface to be closed. This should be equivalent to
432 the user clicking the close button in client-side decorations,
433 if your application has any...
434
435 This is only a request that the user intends to close your
436 window. The client may choose to ignore this request, or show
437 a dialog to ask the user to save their data...
438 </description>
439 </event>
440 </interface>
441
442 <interface name="xdg_popup" version="1">
443 <description summary="short-lived, popup surfaces for menus">
444 A popup surface is a short-lived, temporary surface that can be
445 used to implement menus. It takes an explicit grab on the surface
446 that will be dismissed when the user dismisses the popup. This can
447 be done by the user clicking outside the surface, using the keyboard,
448 or even locking the screen through closing the lid or a timeout.
449
450 When the popup is dismissed, a popup_done event will be sent out,
451 and at the same time the surface will be unmapped. The xdg_popup
452 object is now inert and cannot be reactivated, so clients should
453 destroy it. Explicitly destroying the xdg_popup object will also
454 dismiss the popup and unmap the surface.
455
456 Clients will receive events for all their surfaces during this
457 grab (which is an "owner-events" grab in X11 parlance). This is
458 done so that users can navigate through submenus and other
459 "nested" popup windows without having to dismiss the topmost
460 popup.
461
462 Clients that want to dismiss the popup when another surface of
463 their own is clicked should dismiss the popup using the destroy
464 request.
465
466 The parent surface must have either an xdg_surface or xdg_popup
467 role.
468
469 Specifying an xdg_popup for the parent means that the popups are
470 nested, with this popup now being the topmost popup. Nested
471 popups must be destroyed in the reverse order they were created
472 in, e.g. the only popup you are allowed to destroy at all times
473 is the topmost one.
474
475 If there is an existing popup when creating a new popup, the
476 parent must be the current topmost popup.
477
478 A parent surface must be mapped before the new popup is mapped.
479
480 When compositors choose to dismiss a popup, they will likely
481 dismiss every nested popup as well. When a compositor dismisses
482 popups, it will follow the same dismissing order as required
483 from the client.
484
485 The x and y arguments passed when creating the popup object specify
486 where the top left of the popup should be placed, relative to the
487 local surface coordinates of the parent surface. See
488 xdg_shell.get_xdg_popup.
489
490 The client must call wl_surface.commit on the corresponding wl_surface
491 for the xdg_popup state to take effect.
492
493 For a surface to be mapped by the compositor the client must have
494 committed both the xdg_popup state and a buffer.
495 </description>
496
497 <request name="destroy" type="destructor">
498 <description summary="remove xdg_popup interface">
499 This destroys the popup. Explicitly destroying the xdg_popup
500 object will also dismiss the popup, and unmap the surface.
501
502 If this xdg_popup is not the "topmost" popup, a protocol error
503 will be sent.
504 </description>
505 </request>
506
507 <event name="popup_done">
508 <description summary="popup interaction is done">
509 The popup_done event is sent out when a popup is dismissed by the
510 compositor. The client should destroy the xdg_popup object at this
511 point.
512 </description>
513 </event>
514
515 </interface>
516</protocol>
