1 <?xml version="1.0" encoding="UTF-8"?>
2 <protocol name="xdg_shell">
5 Copyright © 2008-2013 Kristian Høgsberg
6 Copyright © 2013 Rafael Antognolli
7 Copyright © 2013 Jasper St. Pierre
8 Copyright © 2010-2013 Intel Corporation
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
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
32 <interface name="xdg_shell" version="1">
33 <description summary="create desktop-style surfaces">
34 This interface is implemented by servers that provide
35 desktop-style user interfaces.
37 It allows clients to associate a xdg_surface with
42 <description summary="latest protocol version">
43 The 'current' member of this enum gives the version of the
44 protocol. Implementations can compare this to the version
45 they implement using static_assert to ensure the protocol and
46 implementation versions match.
48 <entry name="current" value="4" summary="Always the latest version"/>
52 <request name="use_unstable_version">
53 <description summary="enable use of this unstable version">
54 Negotiate the unstable version of the interface. This
55 mechanism is in place to ensure client and server agree on the
56 unstable versions of the protocol that they speak or exit
57 cleanly if they don't agree. This request will go away once
58 the xdg-shell protocol is stable.
60 <arg name="version" type="int"/>
63 <request name="get_xdg_surface">
64 <description summary="create a shell surface from a surface">
65 Create a shell surface for an existing surface.
67 Only one shell or popup surface can be associated with a given
70 <arg name="id" type="new_id" interface="xdg_surface"/>
71 <arg name="surface" type="object" interface="wl_surface"/>
74 <request name="get_xdg_popup">
75 <description summary="create a shell surface from a surface">
76 Create a popup surface for an existing surface.
78 Only one shell or popup surface can be associated with a given
81 <arg name="id" type="new_id" interface="xdg_popup"/>
82 <arg name="surface" type="object" interface="wl_surface"/>
83 <arg name="parent" type="object" interface="wl_surface"/>
84 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
85 <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
86 <arg name="x" type="int"/>
87 <arg name="y" type="int"/>
88 <arg name="flags" type="uint"/>
92 <description summary="check if the client is alive">
93 The ping event asks the client if it's still alive. Pass the
94 serial specified in the event back to the compositor by sending
95 a "pong" request back with the specified serial.
97 Compositors can use this to determine if the client is still
98 alive. It's unspecified what will happen if the client doesn't
99 respond to the ping request, or in what timeframe. Clients should
100 try to respond in a reasonable amount of time.
102 <arg name="serial" type="uint" summary="pass this to the callback"/>
105 <request name="pong">
106 <description summary="respond to a ping event">
107 A client must respond to a ping event with a pong request or
108 the client may be deemed unresponsive.
110 <arg name="serial" type="uint" summary="serial of the ping event"/>
114 <interface name="xdg_surface" version="1">
116 <description summary="desktop-style metadata interface">
117 An interface that may be implemented by a wl_surface, for
118 implementations that provide a desktop-style user interface.
120 It provides requests to treat surfaces like windows, allowing to set
121 properties like maximized, fullscreen, minimized, and to move and resize
122 them, and associate metadata like title and app id.
124 On the server side the object is automatically destroyed when
125 the related wl_surface is destroyed. On client side,
126 xdg_surface.destroy() must be called before destroying
127 the wl_surface object.
130 <request name="destroy" type="destructor">
131 <description summary="remove xdg_surface interface">
132 The xdg_surface interface is removed from the wl_surface object
133 that was turned into a xdg_surface with
134 xdg_shell.get_xdg_surface request. The xdg_surface properties,
135 like maximized and fullscreen, are lost. The wl_surface loses
136 its role as a xdg_surface. The wl_surface is unmapped.
140 <request name="set_parent">
141 <description summary="surface is a child of another surface">
142 Child surfaces are stacked above their parents, and will be
143 unmapped if the parent is unmapped too. They should not appear
144 on task bars and alt+tab.
146 <arg name="parent" type="object" interface="wl_surface" allow-null="true"/>
149 <request name="set_title">
150 <description summary="set surface title">
151 Set a short title for the surface.
153 This string may be used to identify the surface in a task bar,
154 window list, or other user interface elements provided by the
157 The string must be encoded in UTF-8.
159 <arg name="title" type="string"/>
162 <request name="set_app_id">
163 <description summary="set surface class">
164 Set an id for the surface.
166 The app id identifies the general class of applications to which
169 It should be the ID that appears in the new desktop entry
170 specification, the interface name.
172 <arg name="app_id" type="string"/>
175 <request name="show_window_menu">
176 <description summary="show the window menu">
177 Clients implementing client-side decorations might want to show
178 a context menu when right-clicking on the decorations, giving the
179 user a menu that they can use to maximize or minimize the window.
181 This request asks the compositor to pop up such a window menu at
182 the given position, relative to the parent surface. There are
183 no guarantees as to what the window menu contains.
185 Your surface must have focus on the seat passed in to pop up the
189 <arg name="seat" type="object" interface="wl_seat" summary="the seat to pop the window up on"/>
190 <arg name="serial" type="uint" summary="serial of the event to pop up the window for"/>
191 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
192 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
195 <request name="move">
196 <description summary="start an interactive move">
197 Start a pointer-driven move of the surface.
199 This request must be used in response to a button press event.
200 The server may ignore move requests depending on the state of
201 the surface (e.g. fullscreen or maximized).
203 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
204 <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
207 <enum name="resize_edge">
208 <description summary="edge values for resizing">
209 These values are used to indicate which edge of a surface
210 is being dragged in a resize operation. The server may
211 use this information to adapt its behavior, e.g. choose
212 an appropriate cursor image.
214 <entry name="none" value="0"/>
215 <entry name="top" value="1"/>
216 <entry name="bottom" value="2"/>
217 <entry name="left" value="4"/>
218 <entry name="top_left" value="5"/>
219 <entry name="bottom_left" value="6"/>
220 <entry name="right" value="8"/>
221 <entry name="top_right" value="9"/>
222 <entry name="bottom_right" value="10"/>
225 <request name="resize">
226 <description summary="start an interactive resize">
227 Start a pointer-driven resizing of the surface.
229 This request must be used in response to a button press event.
230 The server may ignore resize requests depending on the state of
231 the surface (e.g. fullscreen or maximized).
233 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/>
234 <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>
235 <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
239 <description summary="types of state on the surface">
240 The different state values used on the surface. This is designed for
241 state values like maximized, fullscreen. It is paired with the
242 configure event to ensure that both the client and the compositor
243 setting the state can be synchronized.
245 States set in this way are double-buffered. They will get applied on
248 Desktop environments may extend this enum by taking up a range of
249 values and documenting the range they chose in this description.
250 They are not required to document the values for the range that they
251 chose. Ideally, any good extensions from a desktop environment should
252 make its way into standardization into this enum.
254 The current reserved ranges are:
256 0x0000 - 0x0FFF: xdg-shell core values, documented below.
257 0x1000 - 0x1FFF: GNOME
259 <entry name="maximized" value="1" summary="the surface is maximized">
260 The surface is maximized. The window geometry specified in the configure
261 event must be obeyed by the client.
263 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
264 The surface is fullscreen. The window geometry specified in the configure
265 event must be obeyed by the client.
267 <entry name="resizing" value="3">
268 The surface is being resized. The window geometry specified in the
269 configure event is a maximum; the client cannot resize beyond it.
270 Clients that have aspect ratio or cell sizing configuration can use
271 a smaller size, however.
273 <entry name="activated" value="4">
274 Client window decorations should be painted as if the window is
275 active. Do not assume this means that the window actually has
276 keyboard or pointer focus.
280 <event name="configure">
281 <description summary="suggest a surface change">
282 The configure event asks the client to resize its surface.
284 The width and height arguments specify a hint to the window
285 about how its surface should be resized in window geometry
286 coordinates. The states listed in the event specify how the
287 width/height arguments should be interpreted.
289 A client should arrange a new surface, and then send a
290 ack_configure request with the serial sent in this configure
291 event before attaching a new surface.
293 If the client receives multiple configure events before it
294 can respond to one, it is free to discard all but the last
298 <arg name="width" type="int"/>
299 <arg name="height" type="int"/>
300 <arg name="states" type="array"/>
301 <arg name="serial" type="uint"/>
304 <request name="ack_configure">
305 <description summary="ack a configure event">
306 When a configure event is received, a client should then ack it
307 using the ack_configure request to ensure that the compositor
308 knows the client has seen the event.
310 By this point, the state is confirmed, and the next attach should
311 contain the buffer drawn for the configure event you are acking.
313 <arg name="serial" type="uint" summary="a serial to configure for"/>
316 <request name="set_window_geometry">
317 <description summary="set the new window geometry">
318 The window geometry of a window is its "visible bounds" from the
319 user's perspective. Client-side decorations often have invisible
320 portions like drop-shadows which should be ignored for the
321 purposes of aligning, placing and constraining windows.
323 The default value is the full bounds of the surface, including any
324 subsurfaces. Once the window geometry of the surface is set once,
325 it is not possible to unset it, and it will remain the same until
326 set_window_geometry is called again, even if a new subsurface or
329 If responding to a configure event, the window geometry in here
330 must respect the sizing negotiations specified by the states in
333 <arg name="x" type="int"/>
334 <arg name="y" type="int"/>
335 <arg name="width" type="int"/>
336 <arg name="height" type="int"/>
339 <request name="set_maximized" />
340 <request name="unset_maximized" />
342 <request name="set_fullscreen">
343 <description summary="set the window as fullscreen on a monitor">
344 Make the surface fullscreen.
346 You can specify an output that you would prefer to be fullscreen.
347 If this value is NULL, it's up to the compositor to choose which
348 display will be used to map this surface.
350 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
352 <request name="unset_fullscreen" />
354 <request name="set_minimized" />
357 <description summary="surface wants to be closed">
358 The close event is sent by the compositor when the user
359 wants the surface to be closed. This should be equivalent to
360 the user clicking the close button in client-side decorations,
361 if your application has any...
363 This is only a request that the user intends to close your
364 window. The client may choose to ignore this request, or show
365 a dialog to ask the user to save their data...
370 <interface name="xdg_popup" version="1">
371 <description summary="desktop-style metadata interface">
372 An interface that may be implemented by a wl_surface, for
373 implementations that provide a desktop-style popups/menus. A popup
374 surface is a transient surface with an added pointer grab.
376 An existing implicit grab will be changed to owner-events mode,
377 and the popup grab will continue after the implicit grab ends
378 (i.e. releasing the mouse button does not cause the popup to be
381 The popup grab continues until the window is destroyed or a mouse
382 button is pressed in any other clients window. A click in any of
383 the clients surfaces is reported as normal, however, clicks in
384 other clients surfaces will be discarded and trigger the callback.
386 The x and y arguments specify the locations of the upper left
387 corner of the surface relative to the upper left corner of the
388 parent surface, in surface local coordinates.
390 xdg_popup surfaces are always transient for another surface.
393 <request name="destroy" type="destructor">
394 <description summary="remove xdg_surface interface">
395 The xdg_surface interface is removed from the wl_surface object
396 that was turned into a xdg_surface with
397 xdg_shell.get_xdg_surface request. The xdg_surface properties,
398 like maximized and fullscreen, are lost. The wl_surface loses
399 its role as a xdg_surface. The wl_surface is unmapped.
403 <event name="popup_done">
404 <description summary="popup interaction is done">
405 The popup_done event is sent out when a popup grab is broken,
406 that is, when the users clicks a surface that doesn't belong
407 to the client owning the popup surface.
409 <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/>