Changeset View
Changeset View
Standalone View
Standalone View
src/client/protocols/xdg-shell-unstable-v6.xml
- This file was added.
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 a 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. | ||||
408 | </description> | ||||
409 | </request> | ||||
410 | | ||||
411 | <request name="get_toplevel"> | ||||
412 | <description summary="assign the xdg_toplevel surface role"> | ||||
413 | This creates an xdg_toplevel object for the given xdg_surface and gives | ||||
414 | the associated wl_surface the xdg_toplevel role. | ||||
415 | | ||||
416 | See the documentation of xdg_toplevel for more details about what an | ||||
417 | xdg_toplevel is and how it is used. | ||||
418 | </description> | ||||
419 | <arg name="id" type="new_id" interface="zxdg_toplevel_v6"/> | ||||
420 | </request> | ||||
421 | | ||||
422 | <request name="get_popup"> | ||||
423 | <description summary="assign the xdg_popup surface role"> | ||||
424 | This creates an xdg_popup object for the given xdg_surface and gives the | ||||
425 | associated wl_surface the xdg_popup role. | ||||
426 | | ||||
427 | See the documentation of xdg_popup for more details about what an | ||||
428 | xdg_popup is and how it is used. | ||||
429 | </description> | ||||
430 | <arg name="id" type="new_id" interface="zxdg_popup_v6"/> | ||||
431 | <arg name="parent" type="object" interface="zxdg_surface_v6"/> | ||||
432 | <arg name="positioner" type="object" interface="zxdg_positioner_v6"/> | ||||
433 | </request> | ||||
434 | | ||||
435 | <request name="set_window_geometry"> | ||||
436 | <description summary="set the new window geometry"> | ||||
437 | The window geometry of a surface is its "visible bounds" from the | ||||
438 | user's perspective. Client-side decorations often have invisible | ||||
439 | portions like drop-shadows which should be ignored for the | ||||
440 | purposes of aligning, placing and constraining windows. | ||||
441 | | ||||
442 | The window geometry is double buffered, and will be applied at the | ||||
443 | time wl_surface.commit of the corresponding wl_surface is called. | ||||
444 | | ||||
445 | Once the window geometry of the surface is set, it is not possible to | ||||
446 | unset it, and it will remain the same until set_window_geometry is | ||||
447 | called again, even if a new subsurface or buffer is attached. | ||||
448 | | ||||
449 | If never set, the value is the full bounds of the surface, | ||||
450 | including any subsurfaces. This updates dynamically on every | ||||
451 | commit. This unset is meant for extremely simple clients. | ||||
452 | | ||||
453 | The arguments are given in the surface-local coordinate space of | ||||
454 | the wl_surface associated with this xdg_surface. | ||||
455 | | ||||
456 | The width and height must be greater than zero. Setting an invalid size | ||||
457 | will raise an error. When applied, the effective window geometry will be | ||||
458 | the set window geometry clamped to the bounding rectangle of the | ||||
459 | combined geometry of the surface of the xdg_surface and the associated | ||||
460 | subsurfaces. | ||||
461 | </description> | ||||
462 | <arg name="x" type="int"/> | ||||
463 | <arg name="y" type="int"/> | ||||
464 | <arg name="width" type="int"/> | ||||
465 | <arg name="height" type="int"/> | ||||
466 | </request> | ||||
467 | | ||||
468 | <request name="ack_configure"> | ||||
469 | <description summary="ack a configure event"> | ||||
470 | When a configure event is received, if a client commits the | ||||
471 | surface in response to the configure event, then the client | ||||
472 | must make an ack_configure request sometime before the commit | ||||
473 | request, passing along the serial of the configure event. | ||||
474 | | ||||
475 | For instance, for toplevel surfaces the compositor might use this | ||||
476 | information to move a surface to the top left only when the client has | ||||
477 | drawn itself for the maximized or fullscreen state. | ||||
478 | | ||||
479 | If the client receives multiple configure events before it | ||||
480 | can respond to one, it only has to ack the last configure event. | ||||
481 | | ||||
482 | A client is not required to commit immediately after sending | ||||
483 | an ack_configure request - it may even ack_configure several times | ||||
484 | before its next surface commit. | ||||
485 | | ||||
486 | A client may send multiple ack_configure requests before committing, but | ||||
487 | only the last request sent before a commit indicates which configure | ||||
488 | event the client really is responding to. | ||||
489 | </description> | ||||
490 | <arg name="serial" type="uint" summary="the serial from the configure event"/> | ||||
491 | </request> | ||||
492 | | ||||
493 | <event name="configure"> | ||||
494 | <description summary="suggest a surface change"> | ||||
495 | The configure event marks the end of a configure sequence. A configure | ||||
496 | sequence is a set of one or more events configuring the state of the | ||||
497 | xdg_surface, including the final xdg_surface.configure event. | ||||
498 | | ||||
499 | Where applicable, xdg_surface surface roles will during a configure | ||||
500 | sequence extend this event as a latched state sent as events before the | ||||
501 | xdg_surface.configure event. Such events should be considered to make up | ||||
502 | a set of atomically applied configuration states, where the | ||||
503 | xdg_surface.configure commits the accumulated state. | ||||
504 | | ||||
505 | Clients should arrange their surface for the new states, and then send | ||||
506 | an ack_configure request with the serial sent in this configure event at | ||||
507 | some point before committing the new surface. | ||||
508 | | ||||
509 | If the client receives multiple configure events before it can respond | ||||
510 | to one, it is free to discard all but the last event it received. | ||||
511 | </description> | ||||
512 | <arg name="serial" type="uint" summary="serial of the configure event"/> | ||||
513 | </event> | ||||
514 | </interface> | ||||
515 | | ||||
516 | <interface name="zxdg_toplevel_v6" version="1"> | ||||
517 | <description summary="toplevel surface"> | ||||
518 | This interface defines an xdg_surface role which allows a surface to, | ||||
519 | among other things, set window-like properties such as maximize, | ||||
520 | fullscreen, and minimize, set application-specific metadata like title and | ||||
521 | id, and well as trigger user interactive operations such as interactive | ||||
522 | resize and move. | ||||
523 | </description> | ||||
524 | | ||||
525 | <request name="destroy" type="destructor"> | ||||
526 | <description summary="destroy the xdg_toplevel"> | ||||
527 | Unmap and destroy the window. The window will be effectively | ||||
528 | hidden from the user's point of view, and all state like | ||||
529 | maximization, fullscreen, and so on, will be lost. | ||||
530 | </description> | ||||
531 | </request> | ||||
532 | | ||||
533 | <request name="set_parent"> | ||||
534 | <description summary="set the parent of this surface"> | ||||
535 | Set the "parent" of this surface. This window should be stacked | ||||
536 | above a parent. The parent surface must be mapped as long as this | ||||
537 | surface is mapped. | ||||
538 | | ||||
539 | Parent windows should be set on dialogs, toolboxes, or other | ||||
540 | "auxiliary" surfaces, so that the parent is raised when the dialog | ||||
541 | is raised. | ||||
542 | </description> | ||||
543 | <arg name="parent" type="object" interface="zxdg_toplevel_v6" allow-null="true"/> | ||||
544 | </request> | ||||
545 | | ||||
546 | <request name="set_title"> | ||||
547 | <description summary="set surface title"> | ||||
548 | Set a short title for the surface. | ||||
549 | | ||||
550 | This string may be used to identify the surface in a task bar, | ||||
551 | window list, or other user interface elements provided by the | ||||
552 | compositor. | ||||
553 | | ||||
554 | The string must be encoded in UTF-8. | ||||
555 | </description> | ||||
556 | <arg name="title" type="string"/> | ||||
557 | </request> | ||||
558 | | ||||
559 | <request name="set_app_id"> | ||||
560 | <description summary="set application ID"> | ||||
561 | Set an application identifier for the surface. | ||||
562 | | ||||
563 | The app ID identifies the general class of applications to which | ||||
564 | the surface belongs. The compositor can use this to group multiple | ||||
565 | surfaces together, or to determine how to launch a new application. | ||||
566 | | ||||
567 | For D-Bus activatable applications, the app ID is used as the D-Bus | ||||
568 | service name. | ||||
569 | | ||||
570 | The compositor shell will try to group application surfaces together | ||||
571 | by their app ID. As a best practice, it is suggested to select app | ||||
572 | ID's that match the basename of the application's .desktop file. | ||||
573 | For example, "org.freedesktop.FooViewer" where the .desktop file is | ||||
574 | "org.freedesktop.FooViewer.desktop". | ||||
575 | | ||||
576 | See the desktop-entry specification [0] for more details on | ||||
577 | application identifiers and how they relate to well-known D-Bus | ||||
578 | names and .desktop files. | ||||
579 | | ||||
580 | [0] http://standards.freedesktop.org/desktop-entry-spec/ | ||||
581 | </description> | ||||
582 | <arg name="app_id" type="string"/> | ||||
583 | </request> | ||||
584 | | ||||
585 | <request name="show_window_menu"> | ||||
586 | <description summary="show the window menu"> | ||||
587 | Clients implementing client-side decorations might want to show | ||||
588 | a context menu when right-clicking on the decorations, giving the | ||||
589 | user a menu that they can use to maximize or minimize the window. | ||||
590 | | ||||
591 | This request asks the compositor to pop up such a window menu at | ||||
592 | the given position, relative to the local surface coordinates of | ||||
593 | the parent surface. There are no guarantees as to what menu items | ||||
594 | the window menu contains. | ||||
595 | | ||||
596 | This request must be used in response to some sort of user action | ||||
597 | like a button press, key press, or touch down event. | ||||
598 | </description> | ||||
599 | <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> | ||||
600 | <arg name="serial" type="uint" summary="the serial of the user event"/> | ||||
601 | <arg name="x" type="int" summary="the x position to pop up the window menu at"/> | ||||
602 | <arg name="y" type="int" summary="the y position to pop up the window menu at"/> | ||||
603 | </request> | ||||
604 | | ||||
605 | <request name="move"> | ||||
606 | <description summary="start an interactive move"> | ||||
607 | Start an interactive, user-driven move of the surface. | ||||
608 | | ||||
609 | This request must be used in response to some sort of user action | ||||
610 | like a button press, key press, or touch down event. The passed | ||||
611 | serial is used to determine the type of interactive move (touch, | ||||
612 | pointer, etc). | ||||
613 | | ||||
614 | The server may ignore move requests depending on the state of | ||||
615 | the surface (e.g. fullscreen or maximized), or if the passed serial | ||||
616 | is no longer valid. | ||||
617 | | ||||
618 | If triggered, the surface will lose the focus of the device | ||||
619 | (wl_pointer, wl_touch, etc) used for the move. It is up to the | ||||
620 | compositor to visually indicate that the move is taking place, such as | ||||
621 | updating a pointer cursor, during the move. There is no guarantee | ||||
622 | that the device focus will return when the move is completed. | ||||
623 | </description> | ||||
624 | <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> | ||||
625 | <arg name="serial" type="uint" summary="the serial of the user event"/> | ||||
626 | </request> | ||||
627 | | ||||
628 | <enum name="resize_edge"> | ||||
629 | <description summary="edge values for resizing"> | ||||
630 | These values are used to indicate which edge of a surface | ||||
631 | is being dragged in a resize operation. | ||||
632 | </description> | ||||
633 | <entry name="none" value="0"/> | ||||
634 | <entry name="top" value="1"/> | ||||
635 | <entry name="bottom" value="2"/> | ||||
636 | <entry name="left" value="4"/> | ||||
637 | <entry name="top_left" value="5"/> | ||||
638 | <entry name="bottom_left" value="6"/> | ||||
639 | <entry name="right" value="8"/> | ||||
640 | <entry name="top_right" value="9"/> | ||||
641 | <entry name="bottom_right" value="10"/> | ||||
642 | </enum> | ||||
643 | | ||||
644 | <request name="resize"> | ||||
645 | <description summary="start an interactive resize"> | ||||
646 | Start a user-driven, interactive resize of the surface. | ||||
647 | | ||||
648 | This request must be used in response to some sort of user action | ||||
649 | like a button press, key press, or touch down event. The passed | ||||
650 | serial is used to determine the type of interactive resize (touch, | ||||
651 | pointer, etc). | ||||
652 | | ||||
653 | The server may ignore resize requests depending on the state of | ||||
654 | the surface (e.g. fullscreen or maximized). | ||||
655 | | ||||
656 | If triggered, the client will receive configure events with the | ||||
657 | "resize" state enum value and the expected sizes. See the "resize" | ||||
658 | enum value for more details about what is required. The client | ||||
659 | must also acknowledge configure events using "ack_configure". After | ||||
660 | the resize is completed, the client will receive another "configure" | ||||
661 | event without the resize state. | ||||
662 | | ||||
663 | If triggered, the surface also will lose the focus of the device | ||||
664 | (wl_pointer, wl_touch, etc) used for the resize. It is up to the | ||||
665 | compositor to visually indicate that the resize is taking place, | ||||
666 | such as updating a pointer cursor, during the resize. There is no | ||||
667 | guarantee that the device focus will return when the resize is | ||||
668 | completed. | ||||
669 | | ||||
670 | The edges parameter specifies how the surface should be resized, | ||||
671 | and is one of the values of the resize_edge enum. The compositor | ||||
672 | may use this information to update the surface position for | ||||
673 | example when dragging the top left corner. The compositor may also | ||||
674 | use this information to adapt its behavior, e.g. choose an | ||||
675 | appropriate cursor image. | ||||
676 | </description> | ||||
677 | <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> | ||||
678 | <arg name="serial" type="uint" summary="the serial of the user event"/> | ||||
679 | <arg name="edges" type="uint" summary="which edge or corner is being dragged"/> | ||||
680 | </request> | ||||
681 | | ||||
682 | <enum name="state"> | ||||
683 | <description summary="types of state on the surface"> | ||||
684 | The different state values used on the surface. This is designed for | ||||
685 | state values like maximized, fullscreen. It is paired with the | ||||
686 | configure event to ensure that both the client and the compositor | ||||
687 | setting the state can be synchronized. | ||||
688 | | ||||
689 | States set in this way are double-buffered. They will get applied on | ||||
690 | the next commit. | ||||
691 | </description> | ||||
692 | <entry name="maximized" value="1" summary="the surface is maximized"> | ||||
693 | <description summary="the surface is maximized"> | ||||
694 | The surface is maximized. The window geometry specified in the configure | ||||
695 | event must be obeyed by the client. | ||||
696 | </description> | ||||
697 | </entry> | ||||
698 | <entry name="fullscreen" value="2" summary="the surface is fullscreen"> | ||||
699 | <description summary="the surface is fullscreen"> | ||||
700 | The surface is fullscreen. The window geometry specified in the configure | ||||
701 | event must be obeyed by the client. | ||||
702 | </description> | ||||
703 | </entry> | ||||
704 | <entry name="resizing" value="3" summary="the surface is being resized"> | ||||
705 | <description summary="the surface is being resized"> | ||||
706 | The surface is being resized. The window geometry specified in the | ||||
707 | configure event is a maximum; the client cannot resize beyond it. | ||||
708 | Clients that have aspect ratio or cell sizing configuration can use | ||||
709 | a smaller size, however. | ||||
710 | </description> | ||||
711 | </entry> | ||||
712 | <entry name="activated" value="4" summary="the surface is now activated"> | ||||
713 | <description summary="the surface is now activated"> | ||||
714 | Client window decorations should be painted as if the window is | ||||
715 | active. Do not assume this means that the window actually has | ||||
716 | keyboard or pointer focus. | ||||
717 | </description> | ||||
718 | </entry> | ||||
719 | </enum> | ||||
720 | | ||||
721 | <request name="set_max_size"> | ||||
722 | <description summary="set the maximum size"> | ||||
723 | Set a maximum size for the window. | ||||
724 | | ||||
725 | The client can specify a maximum size so that the compositor does | ||||
726 | not try to configure the window beyond this size. | ||||
727 | | ||||
728 | The width and height arguments are in window geometry coordinates. | ||||
729 | See xdg_surface.set_window_geometry. | ||||
730 | | ||||
731 | Values set in this way are double-buffered. They will get applied | ||||
732 | on the next commit. | ||||
733 | | ||||
734 | The compositor can use this information to allow or disallow | ||||
735 | different states like maximize or fullscreen and draw accurate | ||||
736 | animations. | ||||
737 | | ||||
738 | Similarly, a tiling window manager may use this information to | ||||
739 | place and resize client windows in a more effective way. | ||||
740 | | ||||
741 | The client should not rely on the compositor to obey the maximum | ||||
742 | size. The compositor may decide to ignore the values set by the | ||||
743 | client and request a larger size. | ||||
744 | | ||||
745 | If never set, or a value of zero in the request, means that the | ||||
746 | client has no expected maximum size in the given dimension. | ||||
747 | As a result, a client wishing to reset the maximum size | ||||
748 | to an unspecified state can use zero for width and height in the | ||||
749 | request. | ||||
750 | | ||||
751 | Requesting a maximum size to be smaller than the minimum size of | ||||
752 | a surface is illegal and will result in a protocol error. | ||||
753 | | ||||
754 | The width and height must be greater than or equal to zero. Using | ||||
755 | strictly negative values for width and height will result in a | ||||
756 | protocol error. | ||||
757 | </description> | ||||
758 | <arg name="width" type="int"/> | ||||
759 | <arg name="height" type="int"/> | ||||
760 | </request> | ||||
761 | | ||||
762 | <request name="set_min_size"> | ||||
763 | <description summary="set the minimum size"> | ||||
764 | Set a minimum size for the window. | ||||
765 | | ||||
766 | The client can specify a minimum size so that the compositor does | ||||
767 | not try to configure the window below this size. | ||||
768 | | ||||
769 | The width and height arguments are in window geometry coordinates. | ||||
770 | See xdg_surface.set_window_geometry. | ||||
771 | | ||||
772 | Values set in this way are double-buffered. They will get applied | ||||
773 | on the next commit. | ||||
774 | | ||||
775 | The compositor can use this information to allow or disallow | ||||
776 | different states like maximize or fullscreen and draw accurate | ||||
777 | animations. | ||||
778 | | ||||
779 | Similarly, a tiling window manager may use this information to | ||||
780 | place and resize client windows in a more effective way. | ||||
781 | | ||||
782 | The client should not rely on the compositor to obey the minimum | ||||
783 | size. The compositor may decide to ignore the values set by the | ||||
784 | client and request a smaller size. | ||||
785 | | ||||
786 | If never set, or a value of zero in the request, means that the | ||||
787 | client has no expected minimum size in the given dimension. | ||||
788 | As a result, a client wishing to reset the minimum size | ||||
789 | to an unspecified state can use zero for width and height in the | ||||
790 | request. | ||||
791 | | ||||
792 | Requesting a minimum size to be larger than the maximum size of | ||||
793 | a surface is illegal and will result in a protocol error. | ||||
794 | | ||||
795 | The width and height must be greater than or equal to zero. Using | ||||
796 | strictly negative values for width and height will result in a | ||||
797 | protocol error. | ||||
798 | </description> | ||||
799 | <arg name="width" type="int"/> | ||||
800 | <arg name="height" type="int"/> | ||||
801 | </request> | ||||
802 | | ||||
803 | <request name="set_maximized"> | ||||
804 | <description summary="maximize the window"> | ||||
805 | Maximize the surface. | ||||
806 | | ||||
807 | After requesting that the surface should be maximized, the compositor | ||||
808 | will respond by emitting a configure event with the "maximized" state | ||||
809 | and the required window geometry. The client should then update its | ||||
810 | content, drawing it in a maximized state, i.e. without shadow or other | ||||
811 | decoration outside of the window geometry. The client must also | ||||
812 | acknowledge the configure when committing the new content (see | ||||
813 | ack_configure). | ||||
814 | | ||||
815 | It is up to the compositor to decide how and where to maximize the | ||||
816 | surface, for example which output and what region of the screen should | ||||
817 | be used. | ||||
818 | | ||||
819 | If the surface was already maximized, the compositor will still emit | ||||
820 | a configure event with the "maximized" state. | ||||
821 | </description> | ||||
822 | </request> | ||||
823 | | ||||
824 | <request name="unset_maximized"> | ||||
825 | <description summary="unmaximize the window"> | ||||
826 | Unmaximize the surface. | ||||
827 | | ||||
828 | After requesting that the surface should be unmaximized, the compositor | ||||
829 | will respond by emitting a configure event without the "maximized" | ||||
830 | state. If available, the compositor will include the window geometry | ||||
831 | dimensions the window had prior to being maximized in the configure | ||||
832 | request. The client must then update its content, drawing it in a | ||||
833 | regular state, i.e. potentially with shadow, etc. The client must also | ||||
834 | acknowledge the configure when committing the new content (see | ||||
835 | ack_configure). | ||||
836 | | ||||
837 | It is up to the compositor to position the surface after it was | ||||
838 | unmaximized; usually the position the surface had before maximizing, if | ||||
839 | applicable. | ||||
840 | | ||||
841 | If the surface was already not maximized, the compositor will still | ||||
842 | emit a configure event without the "maximized" state. | ||||
843 | </description> | ||||
844 | </request> | ||||
845 | | ||||
846 | <request name="set_fullscreen"> | ||||
847 | <description summary="set the window as fullscreen on a monitor"> | ||||
848 | Make the surface fullscreen. | ||||
849 | | ||||
850 | You can specify an output that you would prefer to be fullscreen. | ||||
851 | If this value is NULL, it's up to the compositor to choose which | ||||
852 | display will be used to map this surface. | ||||
853 | | ||||
854 | If the surface doesn't cover the whole output, the compositor will | ||||
855 | position the surface in the center of the output and compensate with | ||||
856 | black borders filling the rest of the output. | ||||
857 | </description> | ||||
858 | <arg name="output" type="object" interface="wl_output" allow-null="true"/> | ||||
859 | </request> | ||||
860 | <request name="unset_fullscreen" /> | ||||
861 | | ||||
862 | <request name="set_minimized"> | ||||
863 | <description summary="set the window as minimized"> | ||||
864 | Request that the compositor minimize your surface. There is no | ||||
865 | way to know if the surface is currently minimized, nor is there | ||||
866 | any way to unset minimization on this surface. | ||||
867 | | ||||
868 | If you are looking to throttle redrawing when minimized, please | ||||
869 | instead use the wl_surface.frame event for this, as this will | ||||
870 | also work with live previews on windows in Alt-Tab, Expose or | ||||
871 | similar compositor features. | ||||
872 | </description> | ||||
873 | </request> | ||||
874 | | ||||
875 | <event name="configure"> | ||||
876 | <description summary="suggest a surface change"> | ||||
877 | This configure event asks the client to resize its toplevel surface or | ||||
878 | to change its state. The configured state should not be applied | ||||
879 | immediately. See xdg_surface.configure for details. | ||||
880 | | ||||
881 | The width and height arguments specify a hint to the window | ||||
882 | about how its surface should be resized in window geometry | ||||
883 | coordinates. See set_window_geometry. | ||||
884 | | ||||
885 | If the width or height arguments are zero, it means the client | ||||
886 | should decide its own window dimension. This may happen when the | ||||
887 | compositor needs to configure the state of the surface but doesn't | ||||
888 | have any information about any previous or expected dimension. | ||||
889 | | ||||
890 | The states listed in the event specify how the width/height | ||||
891 | arguments should be interpreted, and possibly how it should be | ||||
892 | drawn. | ||||
893 | | ||||
894 | Clients must send an ack_configure in response to this event. See | ||||
895 | xdg_surface.configure and xdg_surface.ack_configure for details. | ||||
896 | </description> | ||||
897 | <arg name="width" type="int"/> | ||||
898 | <arg name="height" type="int"/> | ||||
899 | <arg name="states" type="array"/> | ||||
900 | </event> | ||||
901 | | ||||
902 | <event name="close"> | ||||
903 | <description summary="surface wants to be closed"> | ||||
904 | The close event is sent by the compositor when the user | ||||
905 | wants the surface to be closed. This should be equivalent to | ||||
906 | the user clicking the close button in client-side decorations, | ||||
907 | if your application has any. | ||||
908 | | ||||
909 | This is only a request that the user intends to close the | ||||
910 | window. The client may choose to ignore this request, or show | ||||
911 | a dialog to ask the user to save their data, etc. | ||||
912 | </description> | ||||
913 | </event> | ||||
914 | </interface> | ||||
915 | | ||||
916 | <interface name="zxdg_popup_v6" version="1"> | ||||
917 | <description summary="short-lived, popup surfaces for menus"> | ||||
918 | A popup surface is a short-lived, temporary surface. It can be used to | ||||
919 | implement for example menus, popovers, tooltips and other similar user | ||||
920 | interface concepts. | ||||
921 | | ||||
922 | A popup can be made to take an explicit grab. See xdg_popup.grab for | ||||
923 | details. | ||||
924 | | ||||
925 | When the popup is dismissed, a popup_done event will be sent out, and at | ||||
926 | the same time the surface will be unmapped. See the xdg_popup.popup_done | ||||
927 | event for details. | ||||
928 | | ||||
929 | Explicitly destroying the xdg_popup object will also dismiss the popup and | ||||
930 | unmap the surface. Clients that want to dismiss the popup when another | ||||
931 | surface of their own is clicked should dismiss the popup using the destroy | ||||
932 | request. | ||||
933 | | ||||
934 | The parent surface must have either the xdg_toplevel or xdg_popup surface | ||||
935 | role. | ||||
936 | | ||||
937 | A newly created xdg_popup will be stacked on top of all previously created | ||||
938 | xdg_popup surfaces associated with the same xdg_toplevel. | ||||
939 | | ||||
940 | The parent of an xdg_popup must be mapped (see the xdg_surface | ||||
941 | description) before the xdg_popup itself. | ||||
942 | | ||||
943 | The x and y arguments passed when creating the popup object specify | ||||
944 | where the top left of the popup should be placed, relative to the | ||||
945 | local surface coordinates of the parent surface. See | ||||
946 | xdg_surface.get_popup. An xdg_popup must intersect with or be at least | ||||
947 | partially adjacent to its parent surface. | ||||
948 | | ||||
949 | The client must call wl_surface.commit on the corresponding wl_surface | ||||
950 | for the xdg_popup state to take effect. | ||||
951 | </description> | ||||
952 | | ||||
953 | <enum name="error"> | ||||
954 | <entry name="invalid_grab" value="0" | ||||
955 | summary="tried to grab after being mapped"/> | ||||
956 | </enum> | ||||
957 | | ||||
958 | <request name="destroy" type="destructor"> | ||||
959 | <description summary="remove xdg_popup interface"> | ||||
960 | This destroys the popup. Explicitly destroying the xdg_popup | ||||
961 | object will also dismiss the popup, and unmap the surface. | ||||
962 | | ||||
963 | If this xdg_popup is not the "topmost" popup, a protocol error | ||||
964 | will be sent. | ||||
965 | </description> | ||||
966 | </request> | ||||
967 | | ||||
968 | <request name="grab"> | ||||
969 | <description summary="make the popup take an explicit grab"> | ||||
970 | This request makes the created popup take an explicit grab. An explicit | ||||
971 | grab will be dismissed when the user dismisses the popup, or when the | ||||
972 | client destroys the xdg_popup. This can be done by the user clicking | ||||
973 | outside the surface, using the keyboard, or even locking the screen | ||||
974 | through closing the lid or a timeout. | ||||
975 | | ||||
976 | If the compositor denies the grab, the popup will be immediately | ||||
977 | dismissed. | ||||
978 | | ||||
979 | This request must be used in response to some sort of user action like a | ||||
980 | button press, key press, or touch down event. The serial number of the | ||||
981 | event should be passed as 'serial'. | ||||
982 | | ||||
983 | The parent of a grabbing popup must either be an xdg_toplevel surface or | ||||
984 | another xdg_popup with an explicit grab. If the parent is another | ||||
985 | xdg_popup it means that the popups are nested, with this popup now being | ||||
986 | the topmost popup. | ||||
987 | | ||||
988 | Nested popups must be destroyed in the reverse order they were created | ||||
989 | in, e.g. the only popup you are allowed to destroy at all times is the | ||||
990 | topmost one. | ||||
991 | | ||||
992 | When compositors choose to dismiss a popup, they may dismiss every | ||||
993 | nested grabbing popup as well. When a compositor dismisses popups, it | ||||
994 | will follow the same dismissing order as required from the client. | ||||
995 | | ||||
996 | The parent of a grabbing popup must either be another xdg_popup with an | ||||
997 | active explicit grab, or an xdg_popup or xdg_toplevel, if there are no | ||||
998 | explicit grabs already taken. | ||||
999 | | ||||
1000 | If the topmost grabbing popup is destroyed, the grab will be returned to | ||||
1001 | the parent of the popup, if that parent previously had an explicit grab. | ||||
1002 | | ||||
1003 | If the parent is a grabbing popup which has already been dismissed, this | ||||
1004 | popup will be immediately dismissed. If the parent is a popup that did | ||||
1005 | not take an explicit grab, an error will be raised. | ||||
1006 | | ||||
1007 | During a popup grab, the client owning the grab will receive pointer | ||||
1008 | and touch events for all their surfaces as normal (similar to an | ||||
1009 | "owner-events" grab in X11 parlance), while the top most grabbing popup | ||||
1010 | will always have keyboard focus. | ||||
1011 | </description> | ||||
1012 | <arg name="seat" type="object" interface="wl_seat" | ||||
1013 | summary="the wl_seat of the user event"/> | ||||
1014 | <arg name="serial" type="uint" summary="the serial of the user event"/> | ||||
1015 | </request> | ||||
1016 | | ||||
1017 | <event name="configure"> | ||||
1018 | <description summary="configure the popup surface"> | ||||
1019 | This event asks the popup surface to configure itself given the | ||||
1020 | configuration. The configured state should not be applied immediately. | ||||
1021 | See xdg_surface.configure for details. | ||||
1022 | | ||||
1023 | The x and y arguments represent the position the popup was placed at | ||||
1024 | given the xdg_positioner rule, relative to the upper left corner of the | ||||
1025 | window geometry of the parent surface. | ||||
1026 | </description> | ||||
1027 | <arg name="x" type="int" | ||||
1028 | summary="x position relative to parent surface window geometry"/> | ||||
1029 | <arg name="y" type="int" | ||||
1030 | summary="y position relative to parent surface window geometry"/> | ||||
1031 | <arg name="width" type="int" summary="window geometry width"/> | ||||
1032 | <arg name="height" type="int" summary="window geometry height"/> | ||||
1033 | </event> | ||||
1034 | | ||||
1035 | <event name="popup_done"> | ||||
1036 | <description summary="popup interaction is done"> | ||||
1037 | The popup_done event is sent out when a popup is dismissed by the | ||||
1038 | compositor. The client should destroy the xdg_popup object at this | ||||
1039 | point. | ||||
1040 | </description> | ||||
1041 | </event> | ||||
1042 | | ||||
1043 | </interface> | ||||
1044 | </protocol> |