1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="xdg_shell">
3
4 <copyright>
5 Copyright (c) 2008-2013 Kristian Hogsberg
6 Copyright (c) 2013 Rafael Antognolli
7 Copyright (c) 2013 Jasper St. Pierre
8 Copyright (c) 2010-2013 Intel Corporation
9 Copyright (c) 2015-2017 Samsung Electronics Co., Ltd
10 Copyright (c) 2015-2017 Red Hat Inc.
11
12 Permission is hereby granted, free of charge, to any person obtaining a
13 copy of this software and associated documentation files (the "Software"),
14 to deal in the Software without restriction, including without limitation
15 the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 and/or sell copies of the Software, and to permit persons to whom the
17 Software is furnished to do so, subject to the following conditions:
18
19 The above copyright notice and this permission notice (including the next
20 paragraph) shall be included in all copies or substantial portions of the
21 Software.
22
23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 DEALINGS IN THE SOFTWARE.
30 </copyright>
31
32 <interface name="xdg_wm_base" version="7">
33 <description summary="create desktop-style surfaces">
34 The xdg_wm_base interface is exposed as a global object enabling clients
35 to turn their wl_surfaces into windows in a desktop environment. It
36 defines the basic functionality needed for clients and the compositor to
37 create windows that can be dragged, resized, maximized, etc, as well as
38 creating transient windows such as popup menus.
39 </description>
40
41 <enum name="error">
42 <entry name="role" value="0" summary="given wl_surface has another role"/>
43 <entry name="defunct_surfaces" value="1"
44 summary="xdg_wm_base was destroyed before children"/>
45 <entry name="not_the_topmost_popup" value="2"
46 summary="the client tried to map or destroy a non-topmost popup"/>
47 <entry name="invalid_popup_parent" value="3"
48 summary="the client specified an invalid popup parent surface"/>
49 <entry name="invalid_surface_state" value="4"
50 summary="the client provided an invalid surface state"/>
51 <entry name="invalid_positioner" value="5"
52 summary="the client provided an invalid positioner"/>
53 <entry name="unresponsive" value="6"
54 summary="the client didn't respond to a ping event in time"/>
55 </enum>
56
57 <request name="destroy" type="destructor">
58 <description summary="destroy xdg_wm_base">
59 Destroy this xdg_wm_base object.
60
61 Destroying a bound xdg_wm_base object while there are surfaces
62 still alive created by this xdg_wm_base object instance is illegal
63 and will result in a defunct_surfaces error.
64 </description>
65 </request>
66
67 <request name="create_positioner">
68 <description summary="create a positioner object">
69 Create a positioner object. A positioner object is used to position
70 surfaces relative to some parent surface. See the interface description
71 and xdg_surface.get_popup for details.
72 </description>
73 <arg name="id" type="new_id" interface="xdg_positioner"/>
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. While xdg_surface
79 itself is not a role, the corresponding surface may only be assigned
80 a role extending xdg_surface, such as xdg_toplevel or xdg_popup. It is
81 illegal to create an xdg_surface for a wl_surface which already has an
82 assigned role and this will result in a role error.
83
84 This creates an xdg_surface for the given surface. An xdg_surface is
85 used as basis to define a role to a given surface, such as xdg_toplevel
86 or xdg_popup. It also manages functionality shared between xdg_surface
87 based surface roles.
88
89 See the documentation of xdg_surface for more details about what an
90 xdg_surface is and how it is used.
91 </description>
92 <arg name="id" type="new_id" interface="xdg_surface"/>
93 <arg name="surface" type="object" interface="wl_surface"/>
94 </request>
95
96 <request name="pong">
97 <description summary="respond to a ping event">
98 A client must respond to a ping event with a pong request or
99 the client may be deemed unresponsive. See xdg_wm_base.ping
100 and xdg_wm_base.error.unresponsive.
101 </description>
102 <arg name="serial" type="uint" summary="serial of the ping event"/>
103 </request>
104
105 <event name="ping">
106 <description summary="check if the client is alive">
107 The ping event asks the client if it's still alive. Pass the
108 serial specified in the event back to the compositor by sending
109 a "pong" request back with the specified serial. See xdg_wm_base.pong.
110
111 Compositors can use this to determine if the client is still
112 alive. It's unspecified what will happen if the client doesn't
113 respond to the ping request, or in what timeframe. Clients should
114 try to respond in a reasonable amount of time. The "unresponsive"
115 error is provided for compositors that wish to disconnect unresponsive
116 clients.
117
118 A compositor is free to ping in any way it wants, but a client must
119 always respond to any xdg_wm_base object it created.
120 </description>
121 <arg name="serial" type="uint" summary="pass this to the pong request"/>
122 </event>
123 </interface>
124
125 <interface name="xdg_positioner" version="7">
126 <description summary="child surface positioner">
127 The xdg_positioner provides a collection of rules for the placement of a
128 child surface relative to a parent surface. Rules can be defined to ensure
129 the child surface remains within the visible area's borders, and to
130 specify how the child surface changes its position, such as sliding along
131 an axis, or flipping around a rectangle. These positioner-created rules are
132 constrained by the requirement that a child surface must intersect with or
133 be at least partially adjacent to its parent surface.
134
135 See the various requests for details about possible rules.
136
137 At the time of the request, the compositor makes a copy of the rules
138 specified by the xdg_positioner. Thus, after the request is complete the
139 xdg_positioner object can be destroyed or reused; further changes to the
140 object will have no effect on previous usages.
141
142 For an xdg_positioner object to be considered complete, it must have a
143 non-zero size set by set_size, and a non-zero anchor rectangle set by
144 set_anchor_rect. Passing an incomplete xdg_positioner object when
145 positioning a surface raises an invalid_positioner error.
146 </description>
147
148 <enum name="error">
149 <entry name="invalid_input" value="0" summary="invalid input provided"/>
150 </enum>
151
152 <request name="destroy" type="destructor">
153 <description summary="destroy the xdg_positioner object">
154 Notify the compositor that the xdg_positioner will no longer be used.
155 </description>
156 </request>
157
158 <request name="set_size">
159 <description summary="set the size of the to-be positioned rectangle">
160 Set the size of the surface that is to be positioned with the positioner
161 object. The size is in surface-local coordinates and corresponds to the
162 window geometry. See xdg_surface.set_window_geometry.
163
164 If a zero or negative size is set the invalid_input error is raised.
165 </description>
166 <arg name="width" type="int" summary="width of positioned rectangle"/>
167 <arg name="height" type="int" summary="height of positioned rectangle"/>
168 </request>
169
170 <request name="set_anchor_rect">
171 <description summary="set the anchor rectangle within the parent surface">
172 Specify the anchor rectangle within the parent surface that the child
173 surface will be placed relative to. The rectangle is relative to the
174 window geometry as defined by xdg_surface.set_window_geometry of the
175 parent surface.
176
177 When the xdg_positioner object is used to position a child surface, the
178 anchor rectangle may not extend outside the window geometry of the
179 positioned child's parent surface.
180
181 If a negative size is set the invalid_input error is raised.
182 </description>
183 <arg name="x" type="int" summary="x position of anchor rectangle"/>
184 <arg name="y" type="int" summary="y position of anchor rectangle"/>
185 <arg name="width" type="int" summary="width of anchor rectangle"/>
186 <arg name="height" type="int" summary="height of anchor rectangle"/>
187 </request>
188
189 <enum name="anchor">
190 <entry name="none" value="0"/>
191 <entry name="top" value="1"/>
192 <entry name="bottom" value="2"/>
193 <entry name="left" value="3"/>
194 <entry name="right" value="4"/>
195 <entry name="top_left" value="5"/>
196 <entry name="bottom_left" value="6"/>
197 <entry name="top_right" value="7"/>
198 <entry name="bottom_right" value="8"/>
199 </enum>
200
201 <request name="set_anchor">
202 <description summary="set anchor rectangle anchor">
203 Defines the anchor point for the anchor rectangle. The specified anchor
204 is used derive an anchor point that the child surface will be
205 positioned relative to. If a corner anchor is set (e.g. 'top_left' or
206 'bottom_right'), the anchor point will be at the specified corner;
207 otherwise, the derived anchor point will be centered on the specified
208 edge, or in the center of the anchor rectangle if no edge is specified.
209 </description>
210 <arg name="anchor" type="uint" enum="anchor"
211 summary="anchor"/>
212 </request>
213
214 <enum name="gravity">
215 <entry name="none" value="0"/>
216 <entry name="top" value="1"/>
217 <entry name="bottom" value="2"/>
218 <entry name="left" value="3"/>
219 <entry name="right" value="4"/>
220 <entry name="top_left" value="5"/>
221 <entry name="bottom_left" value="6"/>
222 <entry name="top_right" value="7"/>
223 <entry name="bottom_right" value="8"/>
224 </enum>
225
226 <request name="set_gravity">
227 <description summary="set child surface gravity">
228 Defines in what direction a surface should be positioned, relative to
229 the anchor point of the parent surface. If a corner gravity is
230 specified (e.g. 'bottom_right' or 'top_left'), then the child surface
231 will be placed towards the specified gravity; otherwise, the child
232 surface will be centered over the anchor point on any axis that had no
233 gravity specified. If the gravity is not in the 'gravity' enum, an
234 invalid_input error is raised.
235 </description>
236 <arg name="gravity" type="uint" enum="gravity"
237 summary="gravity direction"/>
238 </request>
239
240 <enum name="constraint_adjustment" bitfield="true">
241 <description summary="constraint adjustments">
242 The constraint adjustment value define ways the compositor will adjust
243 the position of the surface, if the unadjusted position would result
244 in the surface being partly constrained.
245
246 Whether a surface is considered 'constrained' is left to the compositor
247 to determine. For example, the surface may be partly outside the
248 compositor's defined 'work area', thus necessitating the child surface's
249 position be adjusted until it is entirely inside the work area.
250
251 The adjustments can be combined, according to a defined precedence: 1)
252 Flip, 2) Slide, 3) Resize.
253 </description>
254 <entry name="none" value="0">
255 <description summary="don't move the child surface when constrained">
256 Don't alter the surface position even if it is constrained on some
257 axis, for example partially outside the edge of an output.
258 </description>
259 </entry>
260 <entry name="slide_x" value="1">
261 <description summary="move along the x axis until unconstrained">
262 Slide the surface along the x axis until it is no longer constrained.
263
264 First try to slide towards the direction of the gravity on the x axis
265 until either the edge in the opposite direction of the gravity is
266 unconstrained or the edge in the direction of the gravity is
267 constrained.
268
269 Then try to slide towards the opposite direction of the gravity on the
270 x axis until either the edge in the direction of the gravity is
271 unconstrained or the edge in the opposite direction of the gravity is
272 constrained.
273 </description>
274 </entry>
275 <entry name="slide_y" value="2">
276 <description summary="move along the y axis until unconstrained">
277 Slide the surface along the y axis until it is no longer constrained.
278
279 First try to slide towards the direction of the gravity on the y axis
280 until either the edge in the opposite direction of the gravity is
281 unconstrained or the edge in the direction of the gravity is
282 constrained.
283
284 Then try to slide towards the opposite direction of the gravity on the
285 y axis until either the edge in the direction of the gravity is
286 unconstrained or the edge in the opposite direction of the gravity is
287 constrained.
288 </description>
289 </entry>
290 <entry name="flip_x" value="4">
291 <description summary="invert the anchor and gravity on the x axis">
292 Invert the anchor and gravity on the x axis if the surface is
293 constrained on the x axis. For example, if the left edge of the
294 surface is constrained, the gravity is 'left' and the anchor is
295 'left', change the gravity to 'right' and the anchor to 'right'.
296
297 If the adjusted position also ends up being constrained, the resulting
298 position of the flip_x adjustment will be the one before the
299 adjustment.
300 </description>
301 </entry>
302 <entry name="flip_y" value="8">
303 <description summary="invert the anchor and gravity on the y axis">
304 Invert the anchor and gravity on the y axis if the surface is
305 constrained on the y axis. For example, if the bottom edge of the
306 surface is constrained, the gravity is 'bottom' and the anchor is
307 'bottom', change the gravity to 'top' and the anchor to 'top'.
308
309 The adjusted position is calculated given the original anchor
310 rectangle and offset, but with the new flipped anchor and gravity
311 values.
312
313 If the adjusted position also ends up being constrained, the resulting
314 position of the flip_y adjustment will be the one before the
315 adjustment.
316 </description>
317 </entry>
318 <entry name="resize_x" value="16">
319 <description summary="horizontally resize the surface">
320 Resize the surface horizontally so that it is completely
321 unconstrained.
322 </description>
323 </entry>
324 <entry name="resize_y" value="32">
325 <description summary="vertically resize the surface">
326 Resize the surface vertically so that it is completely unconstrained.
327 </description>
328 </entry>
329 </enum>
330
331 <request name="set_constraint_adjustment">
332 <description summary="set the adjustment to be done when constrained">
333 Specify how the window should be positioned if the originally intended
334 position caused the surface to be constrained, meaning at least
335 partially outside positioning boundaries set by the compositor. The
336 adjustment is set by constructing a bitmask describing the adjustment to
337 be made when the surface is constrained on that axis.
338
339 If no bit for one axis is set, the compositor will assume that the child
340 surface should not change its position on that axis when constrained.
341
342 If more than one bit for one axis is set, the order of how adjustments
343 are applied is specified in the corresponding adjustment descriptions.
344
345 The default adjustment is none.
346 </description>
347 <arg name="constraint_adjustment" type="uint" enum="constraint_adjustment"
348 summary="bit mask of constraint adjustments"/>
349 </request>
350
351 <request name="set_offset">
352 <description summary="set surface position offset">
353 Specify the surface position offset relative to the position of the
354 anchor on the anchor rectangle and the anchor on the surface. For
355 example if the anchor of the anchor rectangle is at (x, y), the surface
356 has the gravity bottom|right, and the offset is (ox, oy), the calculated
357 surface position will be (x + ox, y + oy). The offset position of the
358 surface is the one used for constraint testing. See
359 set_constraint_adjustment.
360
361 An example use case is placing a popup menu on top of a user interface
362 element, while aligning the user interface element of the parent surface
363 with some user interface element placed somewhere in the popup surface.
364 </description>
365 <arg name="x" type="int" summary="surface position x offset"/>
366 <arg name="y" type="int" summary="surface position y offset"/>
367 </request>
368
369 <!-- Version 3 additions -->
370
371 <request name="set_reactive" since="3">
372 <description summary="continuously reconstrain the surface">
373 When set reactive, the surface is reconstrained if the conditions used
374 for constraining changed, e.g. the parent window moved.
375
376 If the conditions changed and the popup was reconstrained, an
377 xdg_popup.configure event is sent with updated geometry, followed by an
378 xdg_surface.configure event.
379 </description>
380 </request>
381
382 <request name="set_parent_size" since="3">
383 <description summary="">
384 Set the parent window geometry the compositor should use when
385 positioning the popup. The compositor may use this information to
386 determine the future state the popup should be constrained using. If
387 this doesn't match the dimension of the parent the popup is eventually
388 positioned against, the behavior is undefined.
389
390 The arguments are given in the surface-local coordinate space.
391 </description>
392 <arg name="parent_width" type="int"
393 summary="future window geometry width of parent"/>
394 <arg name="parent_height" type="int"
395 summary="future window geometry height of parent"/>
396 </request>
397
398 <request name="set_parent_configure" since="3">
399 <description summary="set parent configure this is a response to">
400 Set the serial of an xdg_surface.configure event this positioner will be
401 used in response to. The compositor may use this information together
402 with set_parent_size to determine what future state the popup should be
403 constrained using.
404 </description>
405 <arg name="serial" type="uint"
406 summary="serial of parent configure event"/>
407 </request>
408 </interface>
409
410 <interface name="xdg_surface" version="7">
411 <description summary="desktop user interface surface base interface">
412 An interface that may be implemented by a wl_surface, for
413 implementations that provide a desktop-style user interface.
414
415 It provides a base set of functionality required to construct user
416 interface elements requiring management by the compositor, such as
417 toplevel windows, menus, etc. The types of functionality are split into
418 xdg_surface roles.
419
420 Creating an xdg_surface does not set the role for a wl_surface. In order
421 to map an xdg_surface, the client must create a role-specific object
422 using, e.g., get_toplevel, get_popup. The wl_surface for any given
423 xdg_surface can have at most one role, and may not be assigned any role
424 not based on xdg_surface.
425
426 A role must be assigned before any other requests are made to the
427 xdg_surface object.
428
429 The client must call wl_surface.commit on the corresponding wl_surface
430 for the xdg_surface state to take effect.
431
432 Creating an xdg_surface from a wl_surface which has a buffer attached or
433 committed is a client error, and any attempts by a client to attach or
434 manipulate a buffer prior to the first xdg_surface.configure call must
435 also be treated as errors.
436
437 After creating a role-specific object and setting it up (e.g. by sending
438 the title, app ID, size constraints, parent, etc), the client must
439 perform an initial commit without any buffer attached. The compositor
440 will reply with initial wl_surface state such as
441 wl_surface.preferred_buffer_scale followed by an xdg_surface.configure
442 event. The client must acknowledge it and is then allowed to attach a
443 buffer to map the surface.
444
445 Mapping an xdg_surface-based role surface is defined as making it
446 possible for the surface to be shown by the compositor. Note that
447 a mapped surface is not guaranteed to be visible once it is mapped.
448
449 For an xdg_surface to be mapped by the compositor, the following
450 conditions must be met:
451 (1) the client has assigned an xdg_surface-based role to the surface
452 (2) the client has set and committed the xdg_surface state and the
453 role-dependent state to the surface
454 (3) the client has committed a buffer to the surface
455
456 A newly-unmapped surface is considered to have met condition (1) out
457 of the 3 required conditions for mapping a surface if its role surface
458 has not been destroyed, i.e. the client must perform the initial commit
459 again before attaching a buffer.
460 </description>
461
462 <enum name="error">
463 <entry name="not_constructed" value="1"
464 summary="Surface was not fully constructed"/>
465 <entry name="already_constructed" value="2"
466 summary="Surface was already constructed"/>
467 <entry name="unconfigured_buffer" value="3"
468 summary="Attaching a buffer to an unconfigured surface"/>
469 <entry name="invalid_serial" value="4"
470 summary="Invalid serial number when acking a configure event"/>
471 <entry name="invalid_size" value="5"
472 summary="Width or height was zero or negative"/>
473 <entry name="defunct_role_object" value="6"
474 summary="Surface was destroyed before its role object"/>
475 </enum>
476
477 <request name="destroy" type="destructor">
478 <description summary="destroy the xdg_surface">
479 Destroy the xdg_surface object. An xdg_surface must only be destroyed
480 after its role object has been destroyed, otherwise
481 a defunct_role_object error is raised.
482 </description>
483 </request>
484
485 <request name="get_toplevel">
486 <description summary="assign the xdg_toplevel surface role">
487 This creates an xdg_toplevel object for the given xdg_surface and gives
488 the associated wl_surface the xdg_toplevel role.
489
490 See the documentation of xdg_toplevel for more details about what an
491 xdg_toplevel is and how it is used.
492 </description>
493 <arg name="id" type="new_id" interface="xdg_toplevel"/>
494 </request>
495
496 <request name="get_popup">
497 <description summary="assign the xdg_popup surface role">
498 This creates an xdg_popup object for the given xdg_surface and gives
499 the associated wl_surface the xdg_popup role.
500
501 If null is passed as a parent, a parent surface must be specified using
502 some other protocol, before committing the initial state.
503
504 See the documentation of xdg_popup for more details about what an
505 xdg_popup is and how it is used.
506 </description>
507 <arg name="id" type="new_id" interface="xdg_popup"/>
508 <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
509 <arg name="positioner" type="object" interface="xdg_positioner"/>
510 </request>
511
512 <request name="set_window_geometry">
513 <description summary="set the new window geometry">
514 The window geometry of a surface is its "visible bounds" from the
515 user's perspective. Client-side decorations often have invisible
516 portions like drop-shadows which should be ignored for the
517 purposes of aligning, placing and constraining windows. Note that
518 in some situations, compositors may clip rendering to the window
519 geometry, so the client should avoid putting functional elements
520 outside of it.
521
522 The window geometry is double-buffered state, see wl_surface.commit.
523
524 When maintaining a position, the compositor should treat the (x, y)
525 coordinate of the window geometry as the top left corner of the window.
526 A client changing the (x, y) window geometry coordinate should in
527 general not alter the position of the window.
528
529 Once the window geometry of the surface is set, it is not possible to
530 unset it, and it will remain the same until set_window_geometry is
531 called again, even if a new subsurface or buffer is attached.
532
533 If never set, the value is the full bounds of the surface,
534 including any subsurfaces. This updates dynamically on every
535 commit. This unset is meant for extremely simple clients.
536
537 The arguments are given in the surface-local coordinate space of
538 the wl_surface associated with this xdg_surface, and may extend outside
539 of the wl_surface itself to mark parts of the subsurface tree as part of
540 the window geometry.
541
542 When applied, the effective window geometry will be the set window
543 geometry clamped to the bounding rectangle of the combined
544 geometry of the surface of the xdg_surface and the associated
545 subsurfaces.
546
547 The effective geometry will not be recalculated unless a new call to
548 set_window_geometry is done and the new pending surface state is
549 subsequently applied.
550
551 The width and height of the effective window geometry must be
552 greater than zero. Setting an invalid size will raise an
553 invalid_size error.
554 </description>
555 <arg name="x" type="int"/>
556 <arg name="y" type="int"/>
557 <arg name="width" type="int"/>
558 <arg name="height" type="int"/>
559 </request>
560
561 <request name="ack_configure">
562 <description summary="ack a configure event">
563 When a configure event is received, if a client commits the
564 surface in response to the configure event, then the client
565 must make an ack_configure request sometime before the commit
566 request, passing along the serial of the configure event.
567
568 For instance, for toplevel surfaces the compositor might use this
569 information to move a surface to the top left only when the client has
570 drawn itself for the maximized or fullscreen state.
571
572 If the client receives multiple configure events before it
573 can respond to one, it only has to ack the last configure event.
574 Acking a configure event that was never sent raises an invalid_serial
575 error.
576
577 A client is not required to commit immediately after sending
578 an ack_configure request - it may even ack_configure several times
579 before its next surface commit.
580
581 A client may send multiple ack_configure requests before committing, but
582 only the last request sent before a commit indicates which configure
583 event the client really is responding to.
584
585 Sending an ack_configure request consumes the serial number sent with
586 the request, as well as serial numbers sent by all configure events
587 sent on this xdg_surface prior to the configure event referenced by
588 the committed serial.
589
590 It is an error to issue multiple ack_configure requests referencing a
591 serial from the same configure event, or to issue an ack_configure
592 request referencing a serial from a configure event issued before the
593 event identified by the last ack_configure request for the same
594 xdg_surface. Doing so will raise an invalid_serial error.
595 </description>
596 <arg name="serial" type="uint" summary="the serial from the configure event"/>
597 </request>
598
599 <event name="configure">
600 <description summary="suggest a surface change">
601 The configure event marks the end of a configure sequence. A configure
602 sequence is a set of one or more events configuring the state of the
603 xdg_surface, including the final xdg_surface.configure event.
604
605 Where applicable, xdg_surface surface roles will during a configure
606 sequence extend this event as a latched state sent as events before the
607 xdg_surface.configure event. Such events should be considered to make up
608 a set of atomically applied configuration states, where the
609 xdg_surface.configure commits the accumulated state.
610
611 Clients should arrange their surface for the new states, and then send
612 an ack_configure request with the serial sent in this configure event at
613 some point before committing the new surface.
614
615 If the client receives multiple configure events before it can respond
616 to one, it is free to discard all but the last event it received.
617 </description>
618 <arg name="serial" type="uint" summary="serial of the configure event"/>
619 </event>
620
621 </interface>
622
623 <interface name="xdg_toplevel" version="7">
624 <description summary="toplevel surface">
625 This interface defines an xdg_surface role which allows a surface to,
626 among other things, set window-like properties such as maximize,
627 fullscreen, and minimize, set application-specific metadata like title and
628 id, and well as trigger user interactive operations such as interactive
629 resize and move.
630
631 A xdg_toplevel by default is responsible for providing the full intended
632 visual representation of the toplevel, which depending on the window
633 state, may mean things like a title bar, window controls and drop shadow.
634
635 Unmapping an xdg_toplevel means that the surface cannot be shown
636 by the compositor until it is explicitly mapped again.
637 All active operations (e.g., move, resize) are canceled and all
638 attributes (e.g. title, state, stacking, ...) are discarded for
639 an xdg_toplevel surface when it is unmapped. The xdg_toplevel returns to
640 the state it had right after xdg_surface.get_toplevel. The client
641 can re-map the toplevel by performing a commit without any buffer
642 attached, waiting for a configure event and handling it as usual (see
643 xdg_surface description).
644
645 Attaching a null buffer to a toplevel unmaps the surface.
646 </description>
647
648 <request name="destroy" type="destructor">
649 <description summary="destroy the xdg_toplevel">
650 This request destroys the role surface and unmaps the surface;
651 see "Unmapping" behavior in interface section for details.
652 </description>
653 </request>
654
655 <enum name="error">
656 <entry name="invalid_resize_edge" value="0" summary="provided value is
657 not a valid variant of the resize_edge enum"/>
658 <entry name="invalid_parent" value="1"
659 summary="invalid parent toplevel"/>
660 <entry name="invalid_size" value="2"
661 summary="client provided an invalid min or max size"/>
662 </enum>
663
664 <request name="set_parent">
665 <description summary="set the parent of this surface">
666 Set the "parent" of this surface. This surface should be stacked
667 above the parent surface and all other ancestor surfaces.
668
669 Parent surfaces should be set on dialogs, toolboxes, or other
670 "auxiliary" surfaces, so that the parent is raised when the dialog
671 is raised.
672
673 Setting a null parent for a child surface unsets its parent. Setting
674 a null parent for a surface which currently has no parent is a no-op.
675
676 Only mapped surfaces can have child surfaces. Setting a parent which
677 is not mapped is equivalent to setting a null parent. If a surface
678 becomes unmapped, its children's parent is set to the parent of
679 the now-unmapped surface. If the now-unmapped surface has no parent,
680 its children's parent is unset. If the now-unmapped surface becomes
681 mapped again, its parent-child relationship is not restored.
682
683 The parent toplevel must not be one of the child toplevel's
684 descendants, and the parent must be different from the child toplevel,
685 otherwise the invalid_parent protocol error is raised.
686 </description>
687 <arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/>
688 </request>
689
690 <request name="set_title">
691 <description summary="set surface title">
692 Set a short title for the surface.
693
694 This string may be used to identify the surface in a task bar,
695 window list, or other user interface elements provided by the
696 compositor.
697
698 The string must be encoded in UTF-8.
699 </description>
700 <arg name="title" type="string"/>
701 </request>
702
703 <request name="set_app_id">
704 <description summary="set application ID">
705 Set an application identifier for the surface.
706
707 The app ID identifies the general class of applications to which
708 the surface belongs. The compositor can use this to group multiple
709 surfaces together, or to determine how to launch a new application.
710
711 For D-Bus activatable applications, the app ID is used as the D-Bus
712 service name.
713
714 The compositor shell will try to group application surfaces together
715 by their app ID. As a best practice, it is suggested to select app
716 ID's that match the basename of the application's .desktop file.
717 For example, "org.freedesktop.FooViewer" where the .desktop file is
718 "org.freedesktop.FooViewer.desktop".
719
720 Like other properties, a set_app_id request can be sent after the
721 xdg_toplevel has been mapped to update the property.
722
723 See the desktop-entry specification [0] for more details on
724 application identifiers and how they relate to well-known D-Bus
725 names and .desktop files.
726
727 [0] https://standards.freedesktop.org/desktop-entry-spec/
728 </description>
729 <arg name="app_id" type="string"/>
730 </request>
731
732 <request name="show_window_menu">
733 <description summary="show the window menu">
734 Clients implementing client-side decorations might want to show
735 a context menu when right-clicking on the decorations, giving the
736 user a menu that they can use to maximize or minimize the window.
737
738 This request asks the compositor to pop up such a window menu at
739 the given position, relative to the local surface coordinates of
740 the parent surface. There are no guarantees as to what menu items
741 the window menu contains, or even if a window menu will be drawn
742 at all.
743
744 This request must be used in response to some sort of user action
745 like a button press, key press, or touch down event.
746 </description>
747 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
748 <arg name="serial" type="uint" summary="the serial of the user event"/>
749 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
750 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
751 </request>
752
753 <request name="move">
754 <description summary="start an interactive move">
755 Start an interactive, user-driven move of the surface.
756
757 This request must be used in response to some sort of user action
758 like a button press, key press, or touch down event. The passed
759 serial is used to determine the type of interactive move (touch,
760 pointer, etc).
761
762 The server may ignore move requests depending on the state of
763 the surface (e.g. fullscreen or maximized), or if the passed serial
764 is no longer valid.
765
766 If triggered, the surface will lose the focus of the device
767 (wl_pointer, wl_touch, etc) used for the move. It is up to the
768 compositor to visually indicate that the move is taking place, such as
769 updating a pointer cursor, during the move. There is no guarantee
770 that the device focus will return when the move is completed.
771 </description>
772 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
773 <arg name="serial" type="uint" summary="the serial of the user event"/>
774 </request>
775
776 <enum name="resize_edge">
777 <description summary="edge values for resizing">
778 These values are used to indicate which edge of a surface
779 is being dragged in a resize operation.
780 </description>
781 <entry name="none" value="0"/>
782 <entry name="top" value="1"/>
783 <entry name="bottom" value="2"/>
784 <entry name="left" value="4"/>
785 <entry name="top_left" value="5"/>
786 <entry name="bottom_left" value="6"/>
787 <entry name="right" value="8"/>
788 <entry name="top_right" value="9"/>
789 <entry name="bottom_right" value="10"/>
790 </enum>
791
792 <request name="resize">
793 <description summary="start an interactive resize">
794 Start a user-driven, interactive resize of the surface.
795
796 This request must be used in response to some sort of user action
797 like a button press, key press, or touch down event. The passed
798 serial is used to determine the type of interactive resize (touch,
799 pointer, etc).
800
801 The server may ignore resize requests depending on the state of
802 the surface (e.g. fullscreen or maximized).
803
804 If triggered, the client will receive configure events with the
805 "resize" state enum value and the expected sizes. See the "resize"
806 enum value for more details about what is required. The client
807 must also acknowledge configure events using "ack_configure". After
808 the resize is completed, the client will receive another "configure"
809 event without the resize state.
810
811 If triggered, the surface also will lose the focus of the device
812 (wl_pointer, wl_touch, etc) used for the resize. It is up to the
813 compositor to visually indicate that the resize is taking place,
814 such as updating a pointer cursor, during the resize. There is no
815 guarantee that the device focus will return when the resize is
816 completed.
817
818 The edges parameter specifies how the surface should be resized, and
819 is one of the values of the resize_edge enum. Values not matching
820 a variant of the enum will cause the invalid_resize_edge protocol error.
821 The compositor may use this information to update the surface position
822 for example when dragging the top left corner. The compositor may also
823 use this information to adapt its behavior, e.g. choose an appropriate
824 cursor image.
825 </description>
826 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
827 <arg name="serial" type="uint" summary="the serial of the user event"/>
828 <arg name="edges" type="uint" enum="resize_edge" summary="which edge or corner is being dragged"/>
829 </request>
830
831 <enum name="state">
832 <description summary="types of state on the surface">
833 The different state values used on the surface. This is designed for
834 state values like maximized, fullscreen. It is paired with the
835 configure event to ensure that both the client and the compositor
836 setting the state can be synchronized.
837
838 States set in this way are double-buffered, see wl_surface.commit.
839 </description>
840 <entry name="maximized" value="1" summary="the surface is maximized">
841 <description summary="the surface is maximized">
842 The surface is maximized. The window geometry specified in the configure
843 event must be obeyed by the client, or the xdg_wm_base.invalid_surface_state
844 error is raised.
845
846 The client should draw without shadow or other
847 decoration outside of the window geometry.
848 </description>
849 </entry>
850 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
851 <description summary="the surface is fullscreen">
852 The surface is fullscreen. The window geometry specified in the
853 configure event is a maximum; the client cannot resize beyond it. For
854 a surface to cover the whole fullscreened area, the geometry
855 dimensions must be obeyed by the client. For more details, see
856 xdg_toplevel.set_fullscreen.
857 </description>
858 </entry>
859 <entry name="resizing" value="3" summary="the surface is being resized">
860 <description summary="the surface is being resized">
861 The surface is being resized. The window geometry specified in the
862 configure event is a maximum; the client cannot resize beyond it.
863 Clients that have aspect ratio or cell sizing configuration can use
864 a smaller size, however.
865 </description>
866 </entry>
867 <entry name="activated" value="4" summary="the surface is now activated">
868 <description summary="the surface is now activated">
869 Client window decorations should be painted as if the window is
870 active. Do not assume this means that the window actually has
871 keyboard or pointer focus.
872 </description>
873 </entry>
874 <entry name="tiled_left" value="5" since="2">
875 <description summary="the surface's left edge is tiled">
876 The window is currently in a tiled layout and the left edge is
877 considered to be adjacent to another part of the tiling grid.
878
879 The client should draw without shadow or other decoration outside of
880 the window geometry on the left edge.
881 </description>
882 </entry>
883 <entry name="tiled_right" value="6" since="2">
884 <description summary="the surface's right edge is tiled">
885 The window is currently in a tiled layout and the right edge is
886 considered to be adjacent to another part of the tiling grid.
887
888 The client should draw without shadow or other decoration outside of
889 the window geometry on the right edge.
890 </description>
891 </entry>
892 <entry name="tiled_top" value="7" since="2">
893 <description summary="the surface's top edge is tiled">
894 The window is currently in a tiled layout and the top edge is
895 considered to be adjacent to another part of the tiling grid.
896
897 The client should draw without shadow or other decoration outside of
898 the window geometry on the top edge.
899 </description>
900 </entry>
901 <entry name="tiled_bottom" value="8" since="2">
902 <description summary="the surface's bottom edge is tiled">
903 The window is currently in a tiled layout and the bottom edge is
904 considered to be adjacent to another part of the tiling grid.
905
906 The client should draw without shadow or other decoration outside of
907 the window geometry on the bottom edge.
908 </description>
909 </entry>
910 <entry name="suspended" value="9" since="6">
911 <description summary="surface repaint is suspended">
912 The surface is currently not ordinarily being repainted; for
913 example because its content is occluded by another window, or its
914 outputs are switched off due to screen locking.
915 </description>
916 </entry>
917 <entry name="constrained_left" value="10" since="7">
918 <description summary="the surface's left edge is constrained">
919 The left edge of the window is currently constrained, meaning it
920 shouldn't attempt to resize from that edge. It can for example mean
921 it's tiled next to a monitor edge on the constrained side of the
922 window.
923 </description>
924 </entry>
925 <entry name="constrained_right" value="11" since="7">
926 <description summary="the surface's right edge is constrained">
927 The right edge of the window is currently constrained, meaning it
928 shouldn't attempt to resize from that edge. It can for example mean
929 it's tiled next to a monitor edge on the constrained side of the
930 window.
931 </description>
932 </entry>
933 <entry name="constrained_top" value="12" since="7">
934 <description summary="the surface's top edge is constrained">
935 The top edge of the window is currently constrained, meaning it
936 shouldn't attempt to resize from that edge. It can for example mean
937 it's tiled next to a monitor edge on the constrained side of the
938 window.
939 </description>
940 </entry>
941 <entry name="constrained_bottom" value="13" since="7">
942 <description summary="the surface's bottom edge is constrained">
943 The bottom edge of the window is currently constrained, meaning it
944 shouldn't attempt to resize from that edge. It can for example mean
945 it's tiled next to a monitor edge on the constrained side of the
946 window.
947 </description>
948 </entry>
949 </enum>
950
951 <request name="set_max_size">
952 <description summary="set the maximum size">
953 Set a maximum size for the window.
954
955 The client can specify a maximum size so that the compositor does
956 not try to configure the window beyond this size.
957
958 The width and height arguments are in window geometry coordinates.
959 See xdg_surface.set_window_geometry.
960
961 Values set in this way are double-buffered, see wl_surface.commit.
962
963 The compositor can use this information to allow or disallow
964 different states like maximize or fullscreen and draw accurate
965 animations.
966
967 Similarly, a tiling window manager may use this information to
968 place and resize client windows in a more effective way.
969
970 The client should not rely on the compositor to obey the maximum
971 size. The compositor may decide to ignore the values set by the
972 client and request a larger size.
973
974 If never set, or a value of zero in the request, means that the
975 client has no expected maximum size in the given dimension.
976 As a result, a client wishing to reset the maximum size
977 to an unspecified state can use zero for width and height in the
978 request.
979
980 Requesting a maximum size to be smaller than the minimum size of
981 a surface is illegal and will result in an invalid_size error.
982
983 The width and height must be greater than or equal to zero. Using
984 strictly negative values for width or height will result in a
985 invalid_size error.
986 </description>
987 <arg name="width" type="int"/>
988 <arg name="height" type="int"/>
989 </request>
990
991 <request name="set_min_size">
992 <description summary="set the minimum size">
993 Set a minimum size for the window.
994
995 The client can specify a minimum size so that the compositor does
996 not try to configure the window below this size.
997
998 The width and height arguments are in window geometry coordinates.
999 See xdg_surface.set_window_geometry.
1000
1001 Values set in this way are double-buffered, see wl_surface.commit.
1002
1003 The compositor can use this information to allow or disallow
1004 different states like maximize or fullscreen and draw accurate
1005 animations.
1006
1007 Similarly, a tiling window manager may use this information to
1008 place and resize client windows in a more effective way.
1009
1010 The client should not rely on the compositor to obey the minimum
1011 size. The compositor may decide to ignore the values set by the
1012 client and request a smaller size.
1013
1014 If never set, or a value of zero in the request, means that the
1015 client has no expected minimum size in the given dimension.
1016 As a result, a client wishing to reset the minimum size
1017 to an unspecified state can use zero for width and height in the
1018 request.
1019
1020 Requesting a minimum size to be larger than the maximum size of
1021 a surface is illegal and will result in an invalid_size error.
1022
1023 The width and height must be greater than or equal to zero. Using
1024 strictly negative values for width and height will result in a
1025 invalid_size error.
1026 </description>
1027 <arg name="width" type="int"/>
1028 <arg name="height" type="int"/>
1029 </request>
1030
1031 <request name="set_maximized">
1032 <description summary="maximize the window">
1033 Maximize the surface.
1034
1035 After requesting that the surface should be maximized, the compositor
1036 will respond by emitting a configure event. Whether this configure
1037 actually sets the window maximized is subject to compositor policies.
1038 The client must then update its content, drawing in the configured
1039 state. The client must also acknowledge the configure when committing
1040 the new content (see ack_configure).
1041
1042 It is up to the compositor to decide how and where to maximize the
1043 surface, for example which output and what region of the screen should
1044 be used.
1045
1046 If the surface was already maximized, the compositor will still emit
1047 a configure event with the "maximized" state.
1048
1049 If the surface is in a fullscreen state, this request has no direct
1050 effect. It may alter the state the surface is returned to when
1051 unmaximized unless overridden by the compositor.
1052 </description>
1053 </request>
1054
1055 <request name="unset_maximized">
1056 <description summary="unmaximize the window">
1057 Unmaximize the surface.
1058
1059 After requesting that the surface should be unmaximized, the compositor
1060 will respond by emitting a configure event. Whether this actually
1061 un-maximizes the window is subject to compositor policies.
1062 If available and applicable, the compositor will include the window
1063 geometry dimensions the window had prior to being maximized in the
1064 configure event. The client must then update its content, drawing it in
1065 the configured state. The client must also acknowledge the configure
1066 when committing the new content (see ack_configure).
1067
1068 It is up to the compositor to position the surface after it was
1069 unmaximized; usually the position the surface had before maximizing, if
1070 applicable.
1071
1072 If the surface was already not maximized, the compositor will still
1073 emit a configure event without the "maximized" state.
1074
1075 If the surface is in a fullscreen state, this request has no direct
1076 effect. It may alter the state the surface is returned to when
1077 unmaximized unless overridden by the compositor.
1078 </description>
1079 </request>
1080
1081 <request name="set_fullscreen">
1082 <description summary="set the window as fullscreen on an output">
1083 Make the surface fullscreen.
1084
1085 After requesting that the surface should be fullscreened, the
1086 compositor will respond by emitting a configure event. Whether the
1087 client is actually put into a fullscreen state is subject to compositor
1088 policies. The client must also acknowledge the configure when
1089 committing the new content (see ack_configure).
1090
1091 The output passed by the request indicates the client's preference as
1092 to which display it should be set fullscreen on. If this value is NULL,
1093 it's up to the compositor to choose which display will be used to map
1094 this surface.
1095
1096 If the surface doesn't cover the whole output, the compositor will
1097 position the surface in the center of the output and compensate with
1098 with border fill covering the rest of the output. The content of the
1099 border fill is undefined, but should be assumed to be in some way that
1100 attempts to blend into the surrounding area (e.g. solid black).
1101
1102 If the fullscreened surface is not opaque, the compositor must make
1103 sure that other screen content not part of the same surface tree (made
1104 up of subsurfaces, popups or similarly coupled surfaces) are not
1105 visible below the fullscreened surface.
1106 </description>
1107 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
1108 </request>
1109
1110 <request name="unset_fullscreen">
1111 <description summary="unset the window as fullscreen">
1112 Make the surface no longer fullscreen.
1113
1114 After requesting that the surface should be unfullscreened, the
1115 compositor will respond by emitting a configure event.
1116 Whether this actually removes the fullscreen state of the client is
1117 subject to compositor policies.
1118
1119 Making a surface unfullscreen sets states for the surface based on the following:
1120 * the state(s) it may have had before becoming fullscreen
1121 * any state(s) decided by the compositor
1122 * any state(s) requested by the client while the surface was fullscreen
1123
1124 The compositor may include the previous window geometry dimensions in
1125 the configure event, if applicable.
1126
1127 The client must also acknowledge the configure when committing the new
1128 content (see ack_configure).
1129 </description>
1130 </request>
1131
1132 <request name="set_minimized">
1133 <description summary="set the window as minimized">
1134 Request that the compositor minimize your surface. There is no
1135 way to know if the surface is currently minimized, nor is there
1136 any way to unset minimization on this surface.
1137
1138 If you are looking to throttle redrawing when minimized, please
1139 instead use the wl_surface.frame event for this, as this will
1140 also work with live previews on windows in Alt-Tab, Expose or
1141 similar compositor features.
1142 </description>
1143 </request>
1144
1145 <event name="configure">
1146 <description summary="suggest a surface change">
1147 This configure event asks the client to resize its toplevel surface or
1148 to change its state. The configured state should not be applied
1149 immediately. See xdg_surface.configure for details.
1150
1151 The width and height arguments specify a hint to the window
1152 about how its surface should be resized in window geometry
1153 coordinates. See set_window_geometry.
1154
1155 If the width or height arguments are zero, it means the client
1156 should decide its own window dimension. This may happen when the
1157 compositor needs to configure the state of the surface but doesn't
1158 have any information about any previous or expected dimension.
1159
1160 The states listed in the event specify how the width/height
1161 arguments should be interpreted, and possibly how it should be
1162 drawn.
1163
1164 Clients must send an ack_configure in response to this event. See
1165 xdg_surface.configure and xdg_surface.ack_configure for details.
1166 </description>
1167 <arg name="width" type="int"/>
1168 <arg name="height" type="int"/>
1169 <arg name="states" type="array"/>
1170 </event>
1171
1172 <event name="close">
1173 <description summary="surface wants to be closed">
1174 The close event is sent by the compositor when the user
1175 wants the surface to be closed. This should be equivalent to
1176 the user clicking the close button in client-side decorations,
1177 if your application has any.
1178
1179 This is only a request that the user intends to close the
1180 window. The client may choose to ignore this request, or show
1181 a dialog to ask the user to save their data, etc.
1182 </description>
1183 </event>
1184
1185 <!-- Version 4 additions -->
1186
1187 <event name="configure_bounds" since="4">
1188 <description summary="recommended window geometry bounds">
1189 The configure_bounds event may be sent prior to a xdg_toplevel.configure
1190 event to communicate the bounds a window geometry size is recommended
1191 to constrain to.
1192
1193 The passed width and height are in surface coordinate space. If width
1194 and height are 0, it means bounds is unknown and equivalent to as if no
1195 configure_bounds event was ever sent for this surface.
1196
1197 The bounds can for example correspond to the size of a monitor excluding
1198 any panels or other shell components, so that a surface isn't created in
1199 a way that it cannot fit.
1200
1201 The bounds may change at any point, and in such a case, a new
1202 xdg_toplevel.configure_bounds will be sent, followed by
1203 xdg_toplevel.configure and xdg_surface.configure.
1204 </description>
1205 <arg name="width" type="int"/>
1206 <arg name="height" type="int"/>
1207 </event>
1208
1209 <!-- Version 5 additions -->
1210
1211 <enum name="wm_capabilities" since="5">
1212 <entry name="window_menu" value="1" summary="show_window_menu is available"/>
1213 <entry name="maximize" value="2" summary="set_maximized and unset_maximized are available"/>
1214 <entry name="fullscreen" value="3" summary="set_fullscreen and unset_fullscreen are available"/>
1215 <entry name="minimize" value="4" summary="set_minimized is available"/>
1216 </enum>
1217
1218 <event name="wm_capabilities" since="5">
1219 <description summary="compositor capabilities">
1220 This event advertises the capabilities supported by the compositor. If
1221 a capability isn't supported, clients should hide or disable the UI
1222 elements that expose this functionality. For instance, if the
1223 compositor doesn't advertise support for minimized toplevels, a button
1224 triggering the set_minimized request should not be displayed.
1225
1226 The compositor will ignore requests it doesn't support. For instance,
1227 a compositor which doesn't advertise support for minimized will ignore
1228 set_minimized requests.
1229
1230 Compositors must send this event once before the first
1231 xdg_surface.configure event. When the capabilities change, compositors
1232 must send this event again and then send an xdg_surface.configure
1233 event.
1234
1235 The configured state should not be applied immediately. See
1236 xdg_surface.configure for details.
1237
1238 The capabilities are sent as an array of 32-bit unsigned integers in
1239 native endianness.
1240 </description>
1241 <arg name="capabilities" type="array" summary="array of 32-bit capabilities"/>
1242 </event>
1243 </interface>
1244
1245 <interface name="xdg_popup" version="7">
1246 <description summary="short-lived, popup surfaces for menus">
1247 A popup surface is a short-lived, temporary surface. It can be used to
1248 implement for example menus, popovers, tooltips and other similar user
1249 interface concepts.
1250
1251 A popup can be made to take an explicit grab. See xdg_popup.grab for
1252 details.
1253
1254 When the popup is dismissed, a popup_done event will be sent out, and at
1255 the same time the surface will be unmapped. See the xdg_popup.popup_done
1256 event for details.
1257
1258 Explicitly destroying the xdg_popup object will also dismiss the popup and
1259 unmap the surface. Clients that want to dismiss the popup when another
1260 surface of their own is clicked should dismiss the popup using the destroy
1261 request.
1262
1263 A newly created xdg_popup will be stacked on top of all previously created
1264 xdg_popup surfaces associated with the same xdg_toplevel.
1265
1266 The parent of an xdg_popup must be mapped (see the xdg_surface
1267 description) before the xdg_popup itself.
1268
1269 The client must call wl_surface.commit on the corresponding wl_surface
1270 for the xdg_popup state to take effect.
1271 </description>
1272
1273 <enum name="error">
1274 <entry name="invalid_grab" value="0"
1275 summary="tried to grab after being mapped"/>
1276 </enum>
1277
1278 <request name="destroy" type="destructor">
1279 <description summary="remove xdg_popup interface">
1280 This destroys the popup. Explicitly destroying the xdg_popup
1281 object will also dismiss the popup, and unmap the surface.
1282
1283 If this xdg_popup is not the "topmost" popup, the
1284 xdg_wm_base.not_the_topmost_popup protocol error will be sent.
1285 </description>
1286 </request>
1287
1288 <request name="grab">
1289 <description summary="make the popup take an explicit grab">
1290 This request makes the created popup take an explicit grab. An explicit
1291 grab will be dismissed when the user dismisses the popup, or when the
1292 client destroys the xdg_popup. This can be done by the user clicking
1293 outside the surface, using the keyboard, or even locking the screen
1294 through closing the lid or a timeout.
1295
1296 If the compositor denies the grab, the popup will be immediately
1297 dismissed.
1298
1299 This request must be used in response to some sort of user action like a
1300 button press, key press, or touch down event. The serial number of the
1301 event should be passed as 'serial'.
1302
1303 The parent of a grabbing popup must either be an xdg_toplevel surface or
1304 another xdg_popup with an explicit grab. If the parent is another
1305 xdg_popup it means that the popups are nested, with this popup now being
1306 the topmost popup.
1307
1308 Nested popups must be destroyed in the reverse order they were created
1309 in, e.g. the only popup you are allowed to destroy at all times is the
1310 topmost one.
1311
1312 When compositors choose to dismiss a popup, they may dismiss every
1313 nested grabbing popup as well. When a compositor dismisses popups, it
1314 will follow the same dismissing order as required from the client.
1315
1316 If the topmost grabbing popup is destroyed, the grab will be returned to
1317 the parent of the popup, if that parent previously had an explicit grab.
1318
1319 If the parent is a grabbing popup which has already been dismissed, this
1320 popup will be immediately dismissed. If the parent is a popup that did
1321 not take an explicit grab, an error will be raised.
1322
1323 During a popup grab, the client owning the grab will receive pointer
1324 and touch events for all their surfaces as normal (similar to an
1325 "owner-events" grab in X11 parlance), while the top most grabbing popup
1326 will always have keyboard focus.
1327 </description>
1328 <arg name="seat" type="object" interface="wl_seat"
1329 summary="the wl_seat of the user event"/>
1330 <arg name="serial" type="uint" summary="the serial of the user event"/>
1331 </request>
1332
1333 <event name="configure">
1334 <description summary="configure the popup surface">
1335 This event asks the popup surface to configure itself given the
1336 configuration. The configured state should not be applied immediately.
1337 See xdg_surface.configure for details.
1338
1339 The x and y arguments represent the position the popup was placed at
1340 given the xdg_positioner rule, relative to the upper left corner of the
1341 window geometry of the parent surface.
1342
1343 For version 2 or older, the configure event for an xdg_popup is only
1344 ever sent once for the initial configuration. Starting with version 3,
1345 it may be sent again if the popup is setup with an xdg_positioner with
1346 set_reactive requested, or in response to xdg_popup.reposition requests.
1347 </description>
1348 <arg name="x" type="int"
1349 summary="x position relative to parent surface window geometry"/>
1350 <arg name="y" type="int"
1351 summary="y position relative to parent surface window geometry"/>
1352 <arg name="width" type="int" summary="window geometry width"/>
1353 <arg name="height" type="int" summary="window geometry height"/>
1354 </event>
1355
1356 <event name="popup_done">
1357 <description summary="popup interaction is done">
1358 The popup_done event is sent out when a popup is dismissed by the
1359 compositor. The client should destroy the xdg_popup object at this
1360 point.
1361 </description>
1362 </event>
1363
1364 <!-- Version 3 additions -->
1365
1366 <request name="reposition" since="3">
1367 <description summary="recalculate the popup's location">
1368 Reposition an already-mapped popup. The popup will be placed given the
1369 details in the passed xdg_positioner object, and a
1370 xdg_popup.repositioned followed by xdg_popup.configure and
1371 xdg_surface.configure will be emitted in response. Any parameters set
1372 by the previous positioner will be discarded.
1373
1374 The passed token will be sent in the corresponding
1375 xdg_popup.repositioned event. The new popup position will not take
1376 effect until the corresponding configure event is acknowledged by the
1377 client. See xdg_popup.repositioned for details. The token itself is
1378 opaque, and has no other special meaning.
1379
1380 If multiple reposition requests are sent, the compositor may skip all
1381 but the last one.
1382
1383 If the popup is repositioned in response to a configure event for its
1384 parent, the client should send an xdg_positioner.set_parent_configure
1385 and possibly an xdg_positioner.set_parent_size request to allow the
1386 compositor to properly constrain the popup.
1387
1388 If the popup is repositioned together with a parent that is being
1389 resized, but not in response to a configure event, the client should
1390 send an xdg_positioner.set_parent_size request.
1391 </description>
1392 <arg name="positioner" type="object" interface="xdg_positioner"/>
1393 <arg name="token" type="uint" summary="reposition request token"/>
1394 </request>
1395
1396 <event name="repositioned" since="3">
1397 <description summary="signal the completion of a repositioned request">
1398 The repositioned event is sent as part of a popup configuration
1399 sequence, together with xdg_popup.configure and lastly
1400 xdg_surface.configure to notify the completion of a reposition request.
1401
1402 The repositioned event is to notify about the completion of a
1403 xdg_popup.reposition request. The token argument is the token passed
1404 in the xdg_popup.reposition request.
1405
1406 Immediately after this event is emitted, xdg_popup.configure and
1407 xdg_surface.configure will be sent with the updated size and position,
1408 as well as a new configure serial.
1409
1410 The client should optionally update the content of the popup, but must
1411 acknowledge the new popup configuration for the new position to take
1412 effect. See xdg_surface.ack_configure for details.
1413 </description>
1414 <arg name="token" type="uint" summary="reposition request token"/>
1415 </event>
1416
1417 </interface>
1418</protocol>
