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