Debian Codegraph @

unstable/xdg-shell/xdg-shell-unstable-v5.xml

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