Debian Codegraph @

unstable/xdg-shell/xdg-shell-unstable-v6.xml

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <protocol name="xdg_shell_unstable_v6">
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="zxdg_shell_v6" 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="error">
39 <entry name="role" value="0" summary="given wl_surface has another role"/>
40 <entry name="defunct_surfaces" value="1"
41 summary="xdg_shell was destroyed before children"/>
42 <entry name="not_the_topmost_popup" value="2"
43 summary="the client tried to map or destroy a non-topmost popup"/>
44 <entry name="invalid_popup_parent" value="3"
45 summary="the client specified an invalid popup parent surface"/>
46 <entry name="invalid_surface_state" value="4"
47 summary="the client provided an invalid surface state"/>
48 <entry name="invalid_positioner" value="5"
49 summary="the client provided an invalid positioner"/>
50 </enum>
51
52 <request name="destroy" type="destructor">
53 <description summary="destroy xdg_shell">
54 Destroy this xdg_shell object.
55
56 Destroying a bound xdg_shell object while there are surfaces
57 still alive created by this xdg_shell object instance is illegal
58 and will result in a protocol error.
59 </description>
60 </request>
61
62 <request name="create_positioner">
63 <description summary="create a positioner object">
64 Create a positioner object. A positioner object is used to position
65 surfaces relative to some parent surface. See the interface description
66 and xdg_surface.get_popup for details.
67 </description>
68 <arg name="id" type="new_id" interface="zxdg_positioner_v6"/>
69 </request>
70
71 <request name="get_xdg_surface">
72 <description summary="create a shell surface from a surface">
73 This creates an xdg_surface for the given surface. While xdg_surface
74 itself is not a role, the corresponding surface may only be assigned
75 a role extending xdg_surface, such as xdg_toplevel or xdg_popup.
76
77 This creates an xdg_surface for the given surface. An xdg_surface is
78 used as basis to define a role to a given surface, such as xdg_toplevel
79 or xdg_popup. It also manages functionality shared between xdg_surface
80 based surface roles.
81
82 See the documentation of xdg_surface for more details about what an
83 xdg_surface is and how it is used.
84 </description>
85 <arg name="id" type="new_id" interface="zxdg_surface_v6"/>
86 <arg name="surface" type="object" interface="wl_surface"/>
87 </request>
88
89 <request name="pong">
90 <description summary="respond to a ping event">
91 A client must respond to a ping event with a pong request or
92 the client may be deemed unresponsive. See xdg_shell.ping.
93 </description>
94 <arg name="serial" type="uint" summary="serial of the ping event"/>
95 </request>
96
97 <event name="ping">
98 <description summary="check if the client is alive">
99 The ping event asks the client if it's still alive. Pass the
100 serial specified in the event back to the compositor by sending
101 a "pong" request back with the specified serial. See xdg_shell.ping.
102
103 Compositors can use this to determine if the client is still
104 alive. It's unspecified what will happen if the client doesn't
105 respond to the ping request, or in what timeframe. Clients should
106 try to respond in a reasonable amount of time.
107
108 A compositor is free to ping in any way it wants, but a client must
109 always respond to any xdg_shell object it created.
110 </description>
111 <arg name="serial" type="uint" summary="pass this to the pong request"/>
112 </event>
113 </interface>
114
115 <interface name="zxdg_positioner_v6" version="1">
116 <description summary="child surface positioner">
117 The xdg_positioner provides a collection of rules for the placement of a
118 child surface relative to a parent surface. Rules can be defined to ensure
119 the child surface remains within the visible area's borders, and to
120 specify how the child surface changes its position, such as sliding along
121 an axis, or flipping around a rectangle. These positioner-created rules are
122 constrained by the requirement that a child surface must intersect with or
123 be at least partially adjacent to its parent surface.
124
125 See the various requests for details about possible rules.
126
127 At the time of the request, the compositor makes a copy of the rules
128 specified by the xdg_positioner. Thus, after the request is complete the
129 xdg_positioner object can be destroyed or reused; further changes to the
130 object will have no effect on previous usages.
131
132 For an xdg_positioner object to be considered complete, it must have a
133 non-zero size set by set_size, and a non-zero anchor rectangle set by
134 set_anchor_rect. Passing an incomplete xdg_positioner object when
135 positioning a surface raises an error.
136 </description>
137
138 <enum name="error">
139 <entry name="invalid_input" value="0" summary="invalid input provided"/>
140 </enum>
141
142 <request name="destroy" type="destructor">
143 <description summary="destroy the xdg_positioner object">
144 Notify the compositor that the xdg_positioner will no longer be used.
145 </description>
146 </request>
147
148 <request name="set_size">
149 <description summary="set the size of the to-be positioned rectangle">
150 Set the size of the surface that is to be positioned with the positioner
151 object. The size is in surface-local coordinates and corresponds to the
152 window geometry. See xdg_surface.set_window_geometry.
153
154 If a zero or negative size is set the invalid_input error is raised.
155 </description>
156 <arg name="width" type="int" summary="width of positioned rectangle"/>
157 <arg name="height" type="int" summary="height of positioned rectangle"/>
158 </request>
159
160 <request name="set_anchor_rect">
161 <description summary="set the anchor rectangle within the parent surface">
162 Specify the anchor rectangle within the parent surface that the child
163 surface will be placed relative to. The rectangle is relative to the
164 window geometry as defined by xdg_surface.set_window_geometry of the
165 parent surface. The rectangle must be at least 1x1 large.
166
167 When the xdg_positioner object is used to position a child surface, the
168 anchor rectangle may not extend outside the window geometry of the
169 positioned child's parent surface.
170
171 If a zero or negative size is set the invalid_input error is raised.
172 </description>
173 <arg name="x" type="int" summary="x position of anchor rectangle"/>
174 <arg name="y" type="int" summary="y position of anchor rectangle"/>
175 <arg name="width" type="int" summary="width of anchor rectangle"/>
176 <arg name="height" type="int" summary="height of anchor rectangle"/>
177 </request>
178
179 <enum name="anchor" bitfield="true">
180 <entry name="none" value="0"
181 summary="the center of the anchor rectangle"/>
182 <entry name="top" value="1"
183 summary="the top edge of the anchor rectangle"/>
184 <entry name="bottom" value="2"
185 summary="the bottom edge of the anchor rectangle"/>
186 <entry name="left" value="4"
187 summary="the left edge of the anchor rectangle"/>
188 <entry name="right" value="8"
189 summary="the right edge of the anchor rectangle"/>
190 </enum>
191
192 <request name="set_anchor">
193 <description summary="set anchor rectangle anchor edges">
194 Defines a set of edges for the anchor rectangle. These are used to
195 derive an anchor point that the child surface will be positioned
196 relative to. If two orthogonal edges are specified (e.g. 'top' and
197 'left'), then the anchor point will be the intersection of the edges
198 (e.g. the top left position of the rectangle); otherwise, the derived
199 anchor point will be centered on the specified edge, or in the center of
200 the anchor rectangle if no edge is specified.
201
202 If two parallel anchor edges are specified (e.g. 'left' and 'right'),
203 the invalid_input error is raised.
204 </description>
205 <arg name="anchor" type="uint" enum="anchor"
206 summary="bit mask of anchor edges"/>
207 </request>
208
209 <enum name="gravity" bitfield="true">
210 <entry name="none" value="0"
211 summary="center over the anchor edge"/>
212 <entry name="top" value="1"
213 summary="position above the anchor edge"/>
214 <entry name="bottom" value="2"
215 summary="position below the anchor edge"/>
216 <entry name="left" value="4"
217 summary="position to the left of the anchor edge"/>
218 <entry name="right" value="8"
219 summary="position to the right of the anchor edge"/>
220 </enum>
221
222 <request name="set_gravity">
223 <description summary="set child surface gravity">
224 Defines in what direction a surface should be positioned, relative to
225 the anchor point of the parent surface. If two orthogonal gravities are
226 specified (e.g. 'bottom' and 'right'), then the child surface will be
227 placed in the specified direction; otherwise, the child surface will be
228 centered over the anchor point on any axis that had no gravity
229 specified.
230
231 If two parallel gravities are specified (e.g. 'left' and 'right'), the
232 invalid_input error is raised.
233 </description>
234 <arg name="gravity" type="uint" enum="gravity"
235 summary="bit mask of gravity directions"/>
236 </request>
237
238 <enum name="constraint_adjustment" bitfield="true">
239 <description summary="constraint adjustments">
240 The constraint adjustment value define ways the compositor will adjust
241 the position of the surface, if the unadjusted position would result
242 in the surface being partly constrained.
243
244 Whether a surface is considered 'constrained' is left to the compositor
245 to determine. For example, the surface may be partly outside the
246 compositor's defined 'work area', thus necessitating the child surface's
247 position be adjusted until it is entirely inside the work area.
248
249 The adjustments can be combined, according to a defined precedence: 1)
250 Flip, 2) Slide, 3) Resize.
251 </description>
252 <entry name="none" value="0">
253 <description summary="don't move the child surface when constrained">
254 Don't alter the surface position even if it is constrained on some
255 axis, for example partially outside the edge of a monitor.
256 </description>
257 </entry>
258 <entry name="slide_x" value="1">
259 <description summary="move along the x axis until unconstrained">
260 Slide the surface along the x axis until it is no longer constrained.
261
262 First try to slide towards the direction of the gravity on the x axis
263 until either the edge in the opposite direction of the gravity is
264 unconstrained or the edge in the direction of the gravity is
265 constrained.
266
267 Then try to slide towards the opposite direction of the gravity on the
268 x axis until either the edge in the direction of the gravity is
269 unconstrained or the edge in the opposite direction of the gravity is
270 constrained.
271 </description>
272 </entry>
273 <entry name="slide_y" value="2">
274 <description summary="move along the y axis until unconstrained">
275 Slide the surface along the y axis until it is no longer constrained.
276
277 First try to slide towards the direction of the gravity on the y axis
278 until either the edge in the opposite direction of the gravity is
279 unconstrained or the edge in the direction of the gravity is
280 constrained.
281
282 Then try to slide towards the opposite direction of the gravity on the
283 y axis until either the edge in the direction of the gravity is
284 unconstrained or the edge in the opposite direction of the gravity is
285 constrained.
286 </description>
287 </entry>
288 <entry name="flip_x" value="4">
289 <description summary="invert the anchor and gravity on the x axis">
290 Invert the anchor and gravity on the x axis if the surface is
291 constrained on the x axis. For example, if the left edge of the
292 surface is constrained, the gravity is 'left' and the anchor is
293 'left', change the gravity to 'right' and the anchor to 'right'.
294
295 If the adjusted position also ends up being constrained, the resulting
296 position of the flip_x adjustment will be the one before the
297 adjustment.
298 </description>
299 </entry>
300 <entry name="flip_y" value="8">
301 <description summary="invert the anchor and gravity on the y axis">
302 Invert the anchor and gravity on the y axis if the surface is
303 constrained on the y axis. For example, if the bottom edge of the
304 surface is constrained, the gravity is 'bottom' and the anchor is
305 'bottom', change the gravity to 'top' and the anchor to 'top'.
306
307 If the adjusted position also ends up being constrained, the resulting
308 position of the flip_y adjustment will be the one before the
309 adjustment.
310 </description>
311 </entry>
312 <entry name="resize_x" value="16">
313 <description summary="horizontally resize the surface">
314 Resize the surface horizontally so that it is completely
315 unconstrained.
316 </description>
317 </entry>
318 <entry name="resize_y" value="32">
319 <description summary="vertically resize the surface">
320 Resize the surface vertically so that it is completely unconstrained.
321 </description>
322 </entry>
323 </enum>
324
325 <request name="set_constraint_adjustment">
326 <description summary="set the adjustment to be done when constrained">
327 Specify how the window should be positioned if the originally intended
328 position caused the surface to be constrained, meaning at least
329 partially outside positioning boundaries set by the compositor. The
330 adjustment is set by constructing a bitmask describing the adjustment to
331 be made when the surface is constrained on that axis.
332
333 If no bit for one axis is set, the compositor will assume that the child
334 surface should not change its position on that axis when constrained.
335
336 If more than one bit for one axis is set, the order of how adjustments
337 are applied is specified in the corresponding adjustment descriptions.
338
339 The default adjustment is none.
340 </description>
341 <arg name="constraint_adjustment" type="uint"
342 summary="bit mask of constraint adjustments"/>
343 </request>
344
345 <request name="set_offset">
346 <description summary="set surface position offset">
347 Specify the surface position offset relative to the position of the
348 anchor on the anchor rectangle and the anchor on the surface. For
349 example if the anchor of the anchor rectangle is at (x, y), the surface
350 has the gravity bottom|right, and the offset is (ox, oy), the calculated
351 surface position will be (x + ox, y + oy). The offset position of the
352 surface is the one used for constraint testing. See
353 set_constraint_adjustment.
354
355 An example use case is placing a popup menu on top of a user interface
356 element, while aligning the user interface element of the parent surface
357 with some user interface element placed somewhere in the popup surface.
358 </description>
359 <arg name="x" type="int" summary="surface position x offset"/>
360 <arg name="y" type="int" summary="surface position y offset"/>
361 </request>
362 </interface>
363
364 <interface name="zxdg_surface_v6" version="1">
365 <description summary="desktop user interface surface base interface">
366 An interface that may be implemented by a wl_surface, for
367 implementations that provide a desktop-style user interface.
368
369 It provides a base set of functionality required to construct user
370 interface elements requiring management by the compositor, such as
371 toplevel windows, menus, etc. The types of functionality are split into
372 xdg_surface roles.
373
374 Creating an xdg_surface does not set the role for a wl_surface. In order
375 to map an xdg_surface, the client must create a role-specific object
376 using, e.g., get_toplevel, get_popup. The wl_surface for any given
377 xdg_surface can have at most one role, and may not be assigned any role
378 not based on xdg_surface.
379
380 A role must be assigned before any other requests are made to the
381 xdg_surface object.
382
383 The client must call wl_surface.commit on the corresponding wl_surface
384 for the xdg_surface state to take effect.
385
386 Creating an xdg_surface from a wl_surface which has a buffer attached or
387 committed is a client error, and any attempts by a client to attach or
388 manipulate a buffer prior to the first xdg_surface.configure call must
389 also be treated as errors.
390
391 For a surface to be mapped by the compositor, the following conditions
392 must be met: (1) the client has assigned an xdg_surface based role to the
393 surface, (2) the client has set and committed the xdg_surface state and
394 the role dependent state to the surface and (3) the client has committed a
395 buffer to the surface.
396 </description>
397
398 <enum name="error">
399 <entry name="not_constructed" value="1"/>
400 <entry name="already_constructed" value="2"/>
401 <entry name="unconfigured_buffer" value="3"/>
402 </enum>
403
404 <request name="destroy" type="destructor">
405 <description summary="destroy the xdg_surface">
406 Destroy the xdg_surface object. An xdg_surface must only be destroyed
407 after its role object has been destroyed. If the role object still
408 exists when this request is issued, the zxdg_shell_v6.defunct_surfaces
409 is raised.
410 </description>
411 </request>
412
413 <request name="get_toplevel">
414 <description summary="assign the xdg_toplevel surface role">
415 This creates an xdg_toplevel object for the given xdg_surface and gives
416 the associated wl_surface the xdg_toplevel role. If the surface already
417 had a role, the zxdg_shell_v6.role error is raised.
418
419 See the documentation of xdg_toplevel for more details about what an
420 xdg_toplevel is and how it is used.
421 </description>
422 <arg name="id" type="new_id" interface="zxdg_toplevel_v6"/>
423 </request>
424
425 <request name="get_popup">
426 <description summary="assign the xdg_popup surface role">
427 This creates an xdg_popup object for the given xdg_surface and gives the
428 associated wl_surface the xdg_popup role. If the surface already
429 had a role, the zxdg_shell_v6.role error is raised.
430
431 See the documentation of xdg_popup for more details about what an
432 xdg_popup is and how it is used.
433 </description>
434 <arg name="id" type="new_id" interface="zxdg_popup_v6"/>
435 <arg name="parent" type="object" interface="zxdg_surface_v6"/>
436 <arg name="positioner" type="object" interface="zxdg_positioner_v6"/>
437 </request>
438
439 <request name="set_window_geometry">
440 <description summary="set the new window geometry">
441 The window geometry of a surface is its "visible bounds" from the
442 user's perspective. Client-side decorations often have invisible
443 portions like drop-shadows which should be ignored for the
444 purposes of aligning, placing and constraining windows.
445
446 The window geometry is double-buffered state, see wl_surface.commit.
447
448 Once the window geometry of the surface is set, it is not possible to
449 unset it, and it will remain the same until set_window_geometry is
450 called again, even if a new subsurface or buffer is attached.
451
452 If never set, the value is the full bounds of the surface,
453 including any subsurfaces. This updates dynamically on every
454 commit. This unset is meant for extremely simple clients.
455
456 The arguments are given in the surface-local coordinate space of
457 the wl_surface associated with this xdg_surface.
458
459 The width and height must be greater than zero. Setting an invalid size
460 will raise an error. When applied, the effective window geometry will be
461 the set window geometry clamped to the bounding rectangle of the
462 combined geometry of the surface of the xdg_surface and the associated
463 subsurfaces.
464 </description>
465 <arg name="x" type="int"/>
466 <arg name="y" type="int"/>
467 <arg name="width" type="int"/>
468 <arg name="height" type="int"/>
469 </request>
470
471 <request name="ack_configure">
472 <description summary="ack a configure event">
473 When a configure event is received, if a client commits the
474 surface in response to the configure event, then the client
475 must make an ack_configure request sometime before the commit
476 request, passing along the serial of the configure event.
477
478 For instance, for toplevel surfaces the compositor might use this
479 information to move a surface to the top left only when the client has
480 drawn itself for the maximized or fullscreen state.
481
482 If the client receives multiple configure events before it
483 can respond to one, it only has to ack the last configure event.
484
485 A client is not required to commit immediately after sending
486 an ack_configure request - it may even ack_configure several times
487 before its next surface commit.
488
489 A client may send multiple ack_configure requests before committing, but
490 only the last request sent before a commit indicates which configure
491 event the client really is responding to.
492
493 If an invalid serial is used, the zxdg_shell_v6.invalid_surface_state
494 error is raised.
495 </description>
496 <arg name="serial" type="uint" summary="the serial from the configure event"/>
497 </request>
498
499 <event name="configure">
500 <description summary="suggest a surface change">
501 The configure event marks the end of a configure sequence. A configure
502 sequence is a set of one or more events configuring the state of the
503 xdg_surface, including the final xdg_surface.configure event.
504
505 Where applicable, xdg_surface surface roles will during a configure
506 sequence extend this event as a latched state sent as events before the
507 xdg_surface.configure event. Such events should be considered to make up
508 a set of atomically applied configuration states, where the
509 xdg_surface.configure commits the accumulated state.
510
511 Clients should arrange their surface for the new states, and then send
512 an ack_configure request with the serial sent in this configure event at
513 some point before committing the new surface.
514
515 If the client receives multiple configure events before it can respond
516 to one, it is free to discard all but the last event it received.
517 </description>
518 <arg name="serial" type="uint" summary="serial of the configure event"/>
519 </event>
520 </interface>
521
522 <interface name="zxdg_toplevel_v6" version="1">
523 <description summary="toplevel surface">
524 This interface defines an xdg_surface role which allows a surface to,
525 among other things, set window-like properties such as maximize,
526 fullscreen, and minimize, set application-specific metadata like title and
527 id, and well as trigger user interactive operations such as interactive
528 resize and move.
529 </description>
530
531 <request name="destroy" type="destructor">
532 <description summary="destroy the xdg_toplevel">
533 Unmap and destroy the window. The window will be effectively
534 hidden from the user's point of view, and all state like
535 maximization, fullscreen, and so on, will be lost.
536 </description>
537 </request>
538
539 <request name="set_parent">
540 <description summary="set the parent of this surface">
541 Set the "parent" of this surface. This window should be stacked
542 above a parent. The parent surface must be mapped as long as this
543 surface is mapped.
544
545 Parent windows should be set on dialogs, toolboxes, or other
546 "auxiliary" surfaces, so that the parent is raised when the dialog
547 is raised.
548 </description>
549 <arg name="parent" type="object" interface="zxdg_toplevel_v6" allow-null="true"/>
550 </request>
551
552 <request name="set_title">
553 <description summary="set surface title">
554 Set a short title for the surface.
555
556 This string may be used to identify the surface in a task bar,
557 window list, or other user interface elements provided by the
558 compositor.
559
560 The string must be encoded in UTF-8.
561 </description>
562 <arg name="title" type="string"/>
563 </request>
564
565 <request name="set_app_id">
566 <description summary="set application ID">
567 Set an application identifier for the surface.
568
569 The app ID identifies the general class of applications to which
570 the surface belongs. The compositor can use this to group multiple
571 surfaces together, or to determine how to launch a new application.
572
573 For D-Bus activatable applications, the app ID is used as the D-Bus
574 service name.
575
576 The compositor shell will try to group application surfaces together
577 by their app ID. As a best practice, it is suggested to select app
578 ID's that match the basename of the application's .desktop file.
579 For example, "org.freedesktop.FooViewer" where the .desktop file is
580 "org.freedesktop.FooViewer.desktop".
581
582 See the desktop-entry specification [0] for more details on
583 application identifiers and how they relate to well-known D-Bus
584 names and .desktop files.
585
586 [0] http://standards.freedesktop.org/desktop-entry-spec/
587 </description>
588 <arg name="app_id" type="string"/>
589 </request>
590
591 <request name="show_window_menu">
592 <description summary="show the window menu">
593 Clients implementing client-side decorations might want to show
594 a context menu when right-clicking on the decorations, giving the
595 user a menu that they can use to maximize or minimize the window.
596
597 This request asks the compositor to pop up such a window menu at
598 the given position, relative to the local surface coordinates of
599 the parent surface. There are no guarantees as to what menu items
600 the window menu contains.
601
602 This request must be used in response to some sort of user action
603 like a button press, key press, or touch down event.
604 </description>
605 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
606 <arg name="serial" type="uint" summary="the serial of the user event"/>
607 <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
608 <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
609 </request>
610
611 <request name="move">
612 <description summary="start an interactive move">
613 Start an interactive, user-driven move of the surface.
614
615 This request must be used in response to some sort of user action
616 like a button press, key press, or touch down event. The passed
617 serial is used to determine the type of interactive move (touch,
618 pointer, etc).
619
620 The server may ignore move requests depending on the state of
621 the surface (e.g. fullscreen or maximized), or if the passed serial
622 is no longer valid.
623
624 If triggered, the surface will lose the focus of the device
625 (wl_pointer, wl_touch, etc) used for the move. It is up to the
626 compositor to visually indicate that the move is taking place, such as
627 updating a pointer cursor, during the move. There is no guarantee
628 that the device focus will return when the move is completed.
629 </description>
630 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
631 <arg name="serial" type="uint" summary="the serial of the user event"/>
632 </request>
633
634 <enum name="resize_edge">
635 <description summary="edge values for resizing">
636 These values are used to indicate which edge of a surface
637 is being dragged in a resize operation.
638 </description>
639 <entry name="none" value="0"/>
640 <entry name="top" value="1"/>
641 <entry name="bottom" value="2"/>
642 <entry name="left" value="4"/>
643 <entry name="top_left" value="5"/>
644 <entry name="bottom_left" value="6"/>
645 <entry name="right" value="8"/>
646 <entry name="top_right" value="9"/>
647 <entry name="bottom_right" value="10"/>
648 </enum>
649
650 <request name="resize">
651 <description summary="start an interactive resize">
652 Start a user-driven, interactive resize of the surface.
653
654 This request must be used in response to some sort of user action
655 like a button press, key press, or touch down event. The passed
656 serial is used to determine the type of interactive resize (touch,
657 pointer, etc).
658
659 The server may ignore resize requests depending on the state of
660 the surface (e.g. fullscreen or maximized).
661
662 If triggered, the client will receive configure events with the
663 "resize" state enum value and the expected sizes. See the "resize"
664 enum value for more details about what is required. The client
665 must also acknowledge configure events using "ack_configure". After
666 the resize is completed, the client will receive another "configure"
667 event without the resize state.
668
669 If triggered, the surface also will lose the focus of the device
670 (wl_pointer, wl_touch, etc) used for the resize. It is up to the
671 compositor to visually indicate that the resize is taking place,
672 such as updating a pointer cursor, during the resize. There is no
673 guarantee that the device focus will return when the resize is
674 completed.
675
676 The edges parameter specifies how the surface should be resized,
677 and is one of the values of the resize_edge enum. The compositor
678 may use this information to update the surface position for
679 example when dragging the top left corner. The compositor may also
680 use this information to adapt its behavior, e.g. choose an
681 appropriate cursor image.
682 </description>
683 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
684 <arg name="serial" type="uint" summary="the serial of the user event"/>
685 <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
686 </request>
687
688 <enum name="state">
689 <description summary="types of state on the surface">
690 The different state values used on the surface. This is designed for
691 state values like maximized, fullscreen. It is paired with the
692 configure event to ensure that both the client and the compositor
693 setting the state can be synchronized.
694
695 States set in this way are double-buffered, see wl_surface.commit.
696 </description>
697 <entry name="maximized" value="1" summary="the surface is maximized">
698 <description summary="the surface is maximized">
699 The surface is maximized. The window geometry specified in the configure
700 event must be obeyed by the client. If the window geometry is not obyed,
701 the zxdg_shell_v6.invalid_surface_state error is raised.
702 </description>
703 </entry>
704 <entry name="fullscreen" value="2" summary="the surface is fullscreen">
705 <description summary="the surface is fullscreen">
706 The surface is fullscreen. See set_fullscreen for more information.
707 </description>
708 </entry>
709 <entry name="resizing" value="3" summary="the surface is being resized">
710 <description summary="the surface is being resized">
711 The surface is being resized. The window geometry specified in the
712 configure event is a maximum; the client cannot resize beyond it. If the
713 client attempts to resize above it, the zxdg_shell_v6.invalid_surface_state
714 error is raised.
715 Clients that have aspect ratio or cell sizing configuration can use
716 a smaller size, however.
717 </description>
718 </entry>
719 <entry name="activated" value="4" summary="the surface is now activated">
720 <description summary="the surface is now activated">
721 Client window decorations should be painted as if the window is
722 active. Do not assume this means that the window actually has
723 keyboard or pointer focus.
724 </description>
725 </entry>
726 </enum>
727
728 <request name="set_max_size">
729 <description summary="set the maximum size">
730 Set a maximum size for the window.
731
732 The client can specify a maximum size so that the compositor does
733 not try to configure the window beyond this size.
734
735 The width and height arguments are in window geometry coordinates.
736 See xdg_surface.set_window_geometry.
737
738 Values set in this way are double-buffered, see wl_surface.commit.
739
740 The compositor can use this information to allow or disallow
741 different states like maximize or fullscreen and draw accurate
742 animations.
743
744 Similarly, a tiling window manager may use this information to
745 place and resize client windows in a more effective way.
746
747 The client should not rely on the compositor to obey the maximum
748 size. The compositor may decide to ignore the values set by the
749 client and request a larger size.
750
751 If never set, or a value of zero in the request, means that the
752 client has no expected maximum size in the given dimension.
753 As a result, a client wishing to reset the maximum size
754 to an unspecified state can use zero for width and height in the
755 request.
756
757 Requesting a maximum size to be smaller than the minimum size of
758 a surface is illegal and will result in a protocol error.
759
760 The width and height must be greater than or equal to zero. Using
761 strictly negative values for width and height will result in the
762 zxdg_shell_v6.invalid_surface_state error being raised.
763 </description>
764 <arg name="width" type="int"/>
765 <arg name="height" type="int"/>
766 </request>
767
768 <request name="set_min_size">
769 <description summary="set the minimum size">
770 Set a minimum size for the window.
771
772 The client can specify a minimum size so that the compositor does
773 not try to configure the window below this size.
774
775 The width and height arguments are in window geometry coordinates.
776 See xdg_surface.set_window_geometry.
777
778 Values set in this way are double-buffered, see wl_surface.commit.
779
780 The compositor can use this information to allow or disallow
781 different states like maximize or fullscreen and draw accurate
782 animations.
783
784 Similarly, a tiling window manager may use this information to
785 place and resize client windows in a more effective way.
786
787 The client should not rely on the compositor to obey the minimum
788 size. The compositor may decide to ignore the values set by the
789 client and request a smaller size.
790
791 If never set, or a value of zero in the request, means that the
792 client has no expected minimum size in the given dimension.
793 As a result, a client wishing to reset the minimum size
794 to an unspecified state can use zero for width and height in the
795 request.
796
797 Requesting a minimum size to be larger than the maximum size of
798 a surface is illegal and will result in a protocol error.
799
800 The width and height must be greater than or equal to zero. Using
801 strictly negative values for width and height will result in the
802 zxdg_shell_v6.invalid_surface_state error being raised.
803 </description>
804 <arg name="width" type="int"/>
805 <arg name="height" type="int"/>
806 </request>
807
808 <request name="set_maximized">
809 <description summary="maximize the window">
810 Maximize the surface.
811
812 After requesting that the surface should be maximized, the compositor
813 will respond by emitting a configure event with the "maximized" state
814 and the required window geometry. The client should then update its
815 content, drawing it in a maximized state, i.e. without shadow or other
816 decoration outside of the window geometry. The client must also
817 acknowledge the configure when committing the new content (see
818 ack_configure).
819
820 It is up to the compositor to decide how and where to maximize the
821 surface, for example which output and what region of the screen should
822 be used.
823
824 If the surface was already maximized, the compositor will still emit
825 a configure event with the "maximized" state.
826
827 Note that unrelated compositor side state changes may cause
828 configure events to be emitted at any time, meaning trying to
829 match this request to a specific future configure event is
830 futile.
831 </description>
832 </request>
833
834 <request name="unset_maximized">
835 <description summary="unmaximize the window">
836 Unmaximize the surface.
837
838 After requesting that the surface should be unmaximized, the compositor
839 will respond by emitting a configure event without the "maximized"
840 state. If available, the compositor will include the window geometry
841 dimensions the window had prior to being maximized in the configure
842 request. The client must then update its content, drawing it in a
843 regular state, i.e. potentially with shadow, etc. The client must also
844 acknowledge the configure when committing the new content (see
845 ack_configure).
846
847 It is up to the compositor to position the surface after it was
848 unmaximized; usually the position the surface had before maximizing, if
849 applicable.
850
851 If the surface was already not maximized, the compositor will still
852 emit a configure event without the "maximized" state.
853
854 Note that unrelated changes in the state of compositor may cause
855 configure events to be emitted by the compositor between processing
856 this request and emitting corresponding configure event, so trying
857 to match the request with the event is futile.
858 </description>
859 </request>
860
861 <request name="set_fullscreen">
862 <description summary="set the window as fullscreen on a monitor">
863 Make the surface fullscreen.
864
865 You can specify an output that you would prefer to be fullscreen.
866 If this value is NULL, it's up to the compositor to choose which
867 display will be used to map this surface.
868
869 If the surface doesn't cover the whole output, the compositor will
870 position the surface in the center of the output and compensate with
871 black borders filling the rest of the output.
872 </description>
873 <arg name="output" type="object" interface="wl_output" allow-null="true"/>
874 </request>
875 <request name="unset_fullscreen" />
876
877 <request name="set_minimized">
878 <description summary="set the window as minimized">
879 Request that the compositor minimize your surface. There is no
880 way to know if the surface is currently minimized, nor is there
881 any way to unset minimization on this surface.
882
883 If you are looking to throttle redrawing when minimized, please
884 instead use the wl_surface.frame event for this, as this will
885 also work with live previews on windows in Alt-Tab, Expose or
886 similar compositor features.
887 </description>
888 </request>
889
890 <event name="configure">
891 <description summary="suggest a surface change">
892 This configure event asks the client to resize its toplevel surface or
893 to change its state. The configured state should not be applied
894 immediately. See xdg_surface.configure for details.
895
896 The width and height arguments specify a hint to the window
897 about how its surface should be resized in window geometry
898 coordinates. See set_window_geometry.
899
900 If the width or height arguments are zero, it means the client
901 should decide its own window dimension. This may happen when the
902 compositor needs to configure the state of the surface but doesn't
903 have any information about any previous or expected dimension.
904
905 The states listed in the event specify how the width/height
906 arguments should be interpreted, and possibly how it should be
907 drawn.
908
909 Clients must send an ack_configure in response to this event. See
910 xdg_surface.configure and xdg_surface.ack_configure for details.
911 </description>
912 <arg name="width" type="int"/>
913 <arg name="height" type="int"/>
914 <arg name="states" type="array"/>
915 </event>
916
917 <event name="close">
918 <description summary="surface wants to be closed">
919 The close event is sent by the compositor when the user
920 wants the surface to be closed. This should be equivalent to
921 the user clicking the close button in client-side decorations,
922 if your application has any.
923
924 This is only a request that the user intends to close the
925 window. The client may choose to ignore this request, or show
926 a dialog to ask the user to save their data, etc.
927 </description>
928 </event>
929 </interface>
930
931 <interface name="zxdg_popup_v6" version="1">
932 <description summary="short-lived, popup surfaces for menus">
933 A popup surface is a short-lived, temporary surface. It can be used to
934 implement for example menus, popovers, tooltips and other similar user
935 interface concepts.
936
937 A popup can be made to take an explicit grab. See xdg_popup.grab for
938 details.
939
940 When the popup is dismissed, a popup_done event will be sent out, and at
941 the same time the surface will be unmapped. See the xdg_popup.popup_done
942 event for details.
943
944 Explicitly destroying the xdg_popup object will also dismiss the popup and
945 unmap the surface. Clients that want to dismiss the popup when another
946 surface of their own is clicked should dismiss the popup using the destroy
947 request.
948
949 The parent surface must have either the xdg_toplevel or xdg_popup surface
950 role.
951
952 A newly created xdg_popup will be stacked on top of all previously created
953 xdg_popup surfaces associated with the same xdg_toplevel.
954
955 The parent of an xdg_popup must be mapped (see the xdg_surface
956 description) before the xdg_popup itself.
957
958 The x and y arguments passed when creating the popup object specify
959 where the top left of the popup should be placed, relative to the
960 local surface coordinates of the parent surface. See
961 xdg_surface.get_popup. An xdg_popup must intersect with or be at least
962 partially adjacent to its parent surface.
963
964 The client must call wl_surface.commit on the corresponding wl_surface
965 for the xdg_popup state to take effect.
966 </description>
967
968 <enum name="error">
969 <entry name="invalid_grab" value="0"
970 summary="tried to grab after being mapped"/>
971 </enum>
972
973 <request name="destroy" type="destructor">
974 <description summary="remove xdg_popup interface">
975 This destroys the popup. Explicitly destroying the xdg_popup
976 object will also dismiss the popup, and unmap the surface.
977
978 If this xdg_popup is not the "topmost" popup, a protocol error
979 will be sent.
980 </description>
981 </request>
982
983 <request name="grab">
984 <description summary="make the popup take an explicit grab">
985 This request makes the created popup take an explicit grab. An explicit
986 grab will be dismissed when the user dismisses the popup, or when the
987 client destroys the xdg_popup. This can be done by the user clicking
988 outside the surface, using the keyboard, or even locking the screen
989 through closing the lid or a timeout.
990
991 If the compositor denies the grab, the popup will be immediately
992 dismissed.
993
994 This request must be used in response to some sort of user action like a
995 button press, key press, or touch down event. The serial number of the
996 event should be passed as 'serial'.
997
998 The parent of a grabbing popup must either be an xdg_toplevel surface or
999 another xdg_popup with an explicit grab. If the parent is another
1000 xdg_popup it means that the popups are nested, with this popup now being
1001 the topmost popup.
1002
1003 Nested popups must be destroyed in the reverse order they were created
1004 in, e.g. the only popup you are allowed to destroy at all times is the
1005 topmost one.
1006
1007 When compositors choose to dismiss a popup, they may dismiss every
1008 nested grabbing popup as well. When a compositor dismisses popups, it
1009 will follow the same dismissing order as required from the client.
1010
1011 The parent of a grabbing popup must either be another xdg_popup with an
1012 active explicit grab, or an xdg_popup or xdg_toplevel, if there are no
1013 explicit grabs already taken.
1014
1015 If the topmost grabbing popup is destroyed, the grab will be returned to
1016 the parent of the popup, if that parent previously had an explicit grab.
1017
1018 If the parent is a grabbing popup which has already been dismissed, this
1019 popup will be immediately dismissed. If the parent is a popup that did
1020 not take an explicit grab, an error will be raised.
1021
1022 During a popup grab, the client owning the grab will receive pointer
1023 and touch events for all their surfaces as normal (similar to an
1024 "owner-events" grab in X11 parlance), while the top most grabbing popup
1025 will always have keyboard focus.
1026 </description>
1027 <arg name="seat" type="object" interface="wl_seat"
1028 summary="the wl_seat of the user event"/>
1029 <arg name="serial" type="uint" summary="the serial of the user event"/>
1030 </request>
1031
1032 <event name="configure">
1033 <description summary="configure the popup surface">
1034 This event asks the popup surface to configure itself given the
1035 configuration. The configured state should not be applied immediately.
1036 See xdg_surface.configure for details.
1037
1038 The x and y arguments represent the position the popup was placed at
1039 given the xdg_positioner rule, relative to the upper left corner of the
1040 window geometry of the parent surface.
1041 </description>
1042 <arg name="x" type="int"
1043 summary="x position relative to parent surface window geometry"/>
1044 <arg name="y" type="int"
1045 summary="y position relative to parent surface window geometry"/>
1046 <arg name="width" type="int" summary="window geometry width"/>
1047 <arg name="height" type="int" summary="window geometry height"/>
1048 </event>
1049
1050 <event name="popup_done">
1051 <description summary="popup interaction is done">
1052 The popup_done event is sent out when a popup is dismissed by the
1053 compositor. The client should destroy the xdg_popup object at this
1054 point.
1055 </description>
1056 </event>
1057
1058 </interface>
1059 </protocol>