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