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 a 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 Mapping an xdg_surface-based role surface is defined as making it 430 possible for the surface to be shown by the compositor. Note that 431 a mapped surface is not guaranteed to be visible once it is mapped. 432 433 For an xdg_surface to be mapped by the compositor, the following 434 conditions must be met: 435 (1) the client has assigned an xdg_surface-based role to the surface 436 (2) the client has set and committed the xdg_surface state and the 437 role-dependent state to the surface 438 (3) the client has committed a buffer to the surface 439 440 A newly-unmapped surface is considered to have met condition (1) out 441 of the 3 required conditions for mapping a surface if its role surface 442 has not been destroyed. 443 </description> 444 445 <enum name="error"> 446 <entry name="not_constructed" value="1"/> 447 <entry name="already_constructed" value="2"/> 448 <entry name="unconfigured_buffer" value="3"/> 449 </enum> 450 451 <request name="destroy" type="destructor"> 452 <description summary="destroy the xdg_surface"> 453 Destroy the xdg_surface object. An xdg_surface must only be destroyed 454 after its role object has been destroyed. 455 </description> 456 </request> 457 458 <request name="get_toplevel"> 459 <description summary="assign the xdg_toplevel surface role"> 460 This creates an xdg_toplevel object for the given xdg_surface and gives 461 the associated wl_surface the xdg_toplevel role. 462 463 See the documentation of xdg_toplevel for more details about what an 464 xdg_toplevel is and how it is used. 465 </description> 466 <arg name="id" type="new_id" interface="xdg_toplevel"/> 467 </request> 468 469 <request name="get_popup"> 470 <description summary="assign the xdg_popup surface role"> 471 This creates an xdg_popup object for the given xdg_surface and gives 472 the associated wl_surface the xdg_popup role. 473 474 If null is passed as a parent, a parent surface must be specified using 475 some other protocol, before committing the initial state. 476 477 See the documentation of xdg_popup for more details about what an 478 xdg_popup is and how it is used. 479 </description> 480 <arg name="id" type="new_id" interface="xdg_popup"/> 481 <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/> 482 <arg name="positioner" type="object" interface="xdg_positioner"/> 483 </request> 484 485 <request name="set_window_geometry"> 486 <description summary="set the new window geometry"> 487 The window geometry of a surface is its "visible bounds" from the 488 user's perspective. Client-side decorations often have invisible 489 portions like drop-shadows which should be ignored for the 490 purposes of aligning, placing and constraining windows. 491 492 The window geometry is double buffered, and will be applied at the 493 time wl_surface.commit of the corresponding wl_surface is called. 494 495 When maintaining a position, the compositor should treat the (x, y) 496 coordinate of the window geometry as the top left corner of the window. 497 A client changing the (x, y) window geometry coordinate should in 498 general not alter the position of the window. 499 500 Once the window geometry of the surface is set, it is not possible to 501 unset it, and it will remain the same until set_window_geometry is 502 called again, even if a new subsurface or buffer is attached. 503 504 If never set, the value is the full bounds of the surface, 505 including any subsurfaces. This updates dynamically on every 506 commit. This unset is meant for extremely simple clients. 507 508 The arguments are given in the surface-local coordinate space of 509 the wl_surface associated with this xdg_surface. 510 511 The width and height must be greater than zero. Setting an invalid size 512 will raise an error. When applied, the effective window geometry will be 513 the set window geometry clamped to the bounding rectangle of the 514 combined geometry of the surface of the xdg_surface and the associated 515 subsurfaces. 516 </description> 517 <arg name="x" type="int"/> 518 <arg name="y" type="int"/> 519 <arg name="width" type="int"/> 520 <arg name="height" type="int"/> 521 </request> 522 523 <request name="ack_configure"> 524 <description summary="ack a configure event"> 525 When a configure event is received, if a client commits the 526 surface in response to the configure event, then the client 527 must make an ack_configure request sometime before the commit 528 request, passing along the serial of the configure event. 529 530 For instance, for toplevel surfaces the compositor might use this 531 information to move a surface to the top left only when the client has 532 drawn itself for the maximized or fullscreen state. 533 534 If the client receives multiple configure events before it 535 can respond to one, it only has to ack the last configure event. 536 537 A client is not required to commit immediately after sending 538 an ack_configure request - it may even ack_configure several times 539 before its next surface commit. 540 541 A client may send multiple ack_configure requests before committing, but 542 only the last request sent before a commit indicates which configure 543 event the client really is responding to. 544 </description> 545 <arg name="serial" type="uint" summary="the serial from the configure event"/> 546 </request> 547 548 <event name="configure"> 549 <description summary="suggest a surface change"> 550 The configure event marks the end of a configure sequence. A configure 551 sequence is a set of one or more events configuring the state of the 552 xdg_surface, including the final xdg_surface.configure event. 553 554 Where applicable, xdg_surface surface roles will during a configure 555 sequence extend this event as a latched state sent as events before the 556 xdg_surface.configure event. Such events should be considered to make up 557 a set of atomically applied configuration states, where the 558 xdg_surface.configure commits the accumulated state. 559 560 Clients should arrange their surface for the new states, and then send 561 an ack_configure request with the serial sent in this configure event at 562 some point before committing the new surface. 563 564 If the client receives multiple configure events before it can respond 565 to one, it is free to discard all but the last event it received. 566 </description> 567 <arg name="serial" type="uint" summary="serial of the configure event"/> 568 </event> 569 570 </interface> 571 572 <interface name="xdg_toplevel" version="3"> 573 <description summary="toplevel surface"> 574 This interface defines an xdg_surface role which allows a surface to, 575 among other things, set window-like properties such as maximize, 576 fullscreen, and minimize, set application-specific metadata like title and 577 id, and well as trigger user interactive operations such as interactive 578 resize and move. 579 580 Unmapping an xdg_toplevel means that the surface cannot be shown 581 by the compositor until it is explicitly mapped again. 582 All active operations (e.g., move, resize) are canceled and all 583 attributes (e.g. title, state, stacking, ...) are discarded for 584 an xdg_toplevel surface when it is unmapped. 585 586 Attaching a null buffer to a toplevel unmaps the surface. 587 </description> 588 589 <request name="destroy" type="destructor"> 590 <description summary="destroy the xdg_toplevel"> 591 This request destroys the role surface and unmaps the surface; 592 see "Unmapping" behavior in interface section for details. 593 </description> 594 </request> 595 596 <request name="set_parent"> 597 <description summary="set the parent of this surface"> 598 Set the "parent" of this surface. This surface should be stacked 599 above the parent surface and all other ancestor surfaces. 600 601 Parent windows should be set on dialogs, toolboxes, or other 602 "auxiliary" surfaces, so that the parent is raised when the dialog 603 is raised. 604 605 Setting a null parent for a child window removes any parent-child 606 relationship for the child. Setting a null parent for a window which 607 currently has no parent is a no-op. 608 609 If the parent is unmapped then its children are managed as 610 though the parent of the now-unmapped parent has become the 611 parent of this surface. If no parent exists for the now-unmapped 612 parent then the children are managed as though they have no 613 parent surface. 614 </description> 615 <arg name="parent" type="object" interface="xdg_toplevel" allow-null="true"/> 616 </request> 617 618 <request name="set_title"> 619 <description summary="set surface title"> 620 Set a short title for the surface. 621 622 This string may be used to identify the surface in a task bar, 623 window list, or other user interface elements provided by the 624 compositor. 625 626 The string must be encoded in UTF-8. 627 </description> 628 <arg name="title" type="string"/> 629 </request> 630 631 <request name="set_app_id"> 632 <description summary="set application ID"> 633 Set an application identifier for the surface. 634 635 The app ID identifies the general class of applications to which 636 the surface belongs. The compositor can use this to group multiple 637 surfaces together, or to determine how to launch a new application. 638 639 For D-Bus activatable applications, the app ID is used as the D-Bus 640 service name. 641 642 The compositor shell will try to group application surfaces together 643 by their app ID. As a best practice, it is suggested to select app 644 ID's that match the basename of the application's .desktop file. 645 For example, "org.freedesktop.FooViewer" where the .desktop file is 646 "org.freedesktop.FooViewer.desktop". 647 648 Like other properties, a set_app_id request can be sent after the 649 xdg_toplevel has been mapped to update the property. 650 651 See the desktop-entry specification [0] for more details on 652 application identifiers and how they relate to well-known D-Bus 653 names and .desktop files. 654 655 [0] http://standards.freedesktop.org/desktop-entry-spec/ 656 </description> 657 <arg name="app_id" type="string"/> 658 </request> 659 660 <request name="show_window_menu"> 661 <description summary="show the window menu"> 662 Clients implementing client-side decorations might want to show 663 a context menu when right-clicking on the decorations, giving the 664 user a menu that they can use to maximize or minimize the window. 665 666 This request asks the compositor to pop up such a window menu at 667 the given position, relative to the local surface coordinates of 668 the parent surface. There are no guarantees as to what menu items 669 the window menu contains. 670 671 This request must be used in response to some sort of user action 672 like a button press, key press, or touch down event. 673 </description> 674 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> 675 <arg name="serial" type="uint" summary="the serial of the user event"/> 676 <arg name="x" type="int" summary="the x position to pop up the window menu at"/> 677 <arg name="y" type="int" summary="the y position to pop up the window menu at"/> 678 </request> 679 680 <request name="move"> 681 <description summary="start an interactive move"> 682 Start an interactive, user-driven move of the surface. 683 684 This request must be used in response to some sort of user action 685 like a button press, key press, or touch down event. The passed 686 serial is used to determine the type of interactive move (touch, 687 pointer, etc). 688 689 The server may ignore move requests depending on the state of 690 the surface (e.g. fullscreen or maximized), or if the passed serial 691 is no longer valid. 692 693 If triggered, the surface will lose the focus of the device 694 (wl_pointer, wl_touch, etc) used for the move. It is up to the 695 compositor to visually indicate that the move is taking place, such as 696 updating a pointer cursor, during the move. There is no guarantee 697 that the device focus will return when the move is completed. 698 </description> 699 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> 700 <arg name="serial" type="uint" summary="the serial of the user event"/> 701 </request> 702 703 <enum name="resize_edge"> 704 <description summary="edge values for resizing"> 705 These values are used to indicate which edge of a surface 706 is being dragged in a resize operation. 707 </description> 708 <entry name="none" value="0"/> 709 <entry name="top" value="1"/> 710 <entry name="bottom" value="2"/> 711 <entry name="left" value="4"/> 712 <entry name="top_left" value="5"/> 713 <entry name="bottom_left" value="6"/> 714 <entry name="right" value="8"/> 715 <entry name="top_right" value="9"/> 716 <entry name="bottom_right" value="10"/> 717 </enum> 718 719 <request name="resize"> 720 <description summary="start an interactive resize"> 721 Start a user-driven, interactive resize of the surface. 722 723 This request must be used in response to some sort of user action 724 like a button press, key press, or touch down event. The passed 725 serial is used to determine the type of interactive resize (touch, 726 pointer, etc). 727 728 The server may ignore resize requests depending on the state of 729 the surface (e.g. fullscreen or maximized). 730 731 If triggered, the client will receive configure events with the 732 "resize" state enum value and the expected sizes. See the "resize" 733 enum value for more details about what is required. The client 734 must also acknowledge configure events using "ack_configure". After 735 the resize is completed, the client will receive another "configure" 736 event without the resize state. 737 738 If triggered, the surface also will lose the focus of the device 739 (wl_pointer, wl_touch, etc) used for the resize. It is up to the 740 compositor to visually indicate that the resize is taking place, 741 such as updating a pointer cursor, during the resize. There is no 742 guarantee that the device focus will return when the resize is 743 completed. 744 745 The edges parameter specifies how the surface should be resized, 746 and is one of the values of the resize_edge enum. The compositor 747 may use this information to update the surface position for 748 example when dragging the top left corner. The compositor may also 749 use this information to adapt its behavior, e.g. choose an 750 appropriate cursor image. 751 </description> 752 <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/> 753 <arg name="serial" type="uint" summary="the serial of the user event"/> 754 <arg name="edges" type="uint" enum="resize_edge" summary="which edge or corner is being dragged"/> 755 </request> 756 757 <enum name="state"> 758 <description summary="types of state on the surface"> 759 The different state values used on the surface. This is designed for 760 state values like maximized, fullscreen. It is paired with the 761 configure event to ensure that both the client and the compositor 762 setting the state can be synchronized. 763 764 States set in this way are double-buffered. They will get applied on 765 the next commit. 766 </description> 767 <entry name="maximized" value="1" summary="the surface is maximized"> 768 <description summary="the surface is maximized"> 769 The surface is maximized. The window geometry specified in the configure 770 event must be obeyed by the client. 771 772 The client should draw without shadow or other 773 decoration outside of the window geometry. 774 </description> 775 </entry> 776 <entry name="fullscreen" value="2" summary="the surface is fullscreen"> 777 <description summary="the surface is fullscreen"> 778 The surface is fullscreen. The window geometry specified in the 779 configure event is a maximum; the client cannot resize beyond it. For 780 a surface to cover the whole fullscreened area, the geometry 781 dimensions must be obeyed by the client. For more details, see 782 xdg_toplevel.set_fullscreen. 783 </description> 784 </entry> 785 <entry name="resizing" value="3" summary="the surface is being resized"> 786 <description summary="the surface is being resized"> 787 The surface is being resized. The window geometry specified in the 788 configure event is a maximum; the client cannot resize beyond it. 789 Clients that have aspect ratio or cell sizing configuration can use 790 a smaller size, however. 791 </description> 792 </entry> 793 <entry name="activated" value="4" summary="the surface is now activated"> 794 <description summary="the surface is now activated"> 795 Client window decorations should be painted as if the window is 796 active. Do not assume this means that the window actually has 797 keyboard or pointer focus. 798 </description> 799 </entry> 800 <entry name="tiled_left" value="5" since="2"> 801 <description summary="the surface is tiled"> 802 The window is currently in a tiled layout and the left edge is 803 considered to be adjacent to another part of the tiling grid. 804 </description> 805 </entry> 806 <entry name="tiled_right" value="6" since="2"> 807 <description summary="the surface is tiled"> 808 The window is currently in a tiled layout and the right edge is 809 considered to be adjacent to another part of the tiling grid. 810 </description> 811 </entry> 812 <entry name="tiled_top" value="7" since="2"> 813 <description summary="the surface is tiled"> 814 The window is currently in a tiled layout and the top edge is 815 considered to be adjacent to another part of the tiling grid. 816 </description> 817 </entry> 818 <entry name="tiled_bottom" value="8" since="2"> 819 <description summary="the surface is tiled"> 820 The window is currently in a tiled layout and the bottom edge is 821 considered to be adjacent to another part of the tiling grid. 822 </description> 823 </entry> 824 </enum> 825 826 <request name="set_max_size"> 827 <description summary="set the maximum size"> 828 Set a maximum size for the window. 829 830 The client can specify a maximum size so that the compositor does 831 not try to configure the window beyond this size. 832 833 The width and height arguments are in window geometry coordinates. 834 See xdg_surface.set_window_geometry. 835 836 Values set in this way are double-buffered. They will get applied 837 on the next commit. 838 839 The compositor can use this information to allow or disallow 840 different states like maximize or fullscreen and draw accurate 841 animations. 842 843 Similarly, a tiling window manager may use this information to 844 place and resize client windows in a more effective way. 845 846 The client should not rely on the compositor to obey the maximum 847 size. The compositor may decide to ignore the values set by the 848 client and request a larger size. 849 850 If never set, or a value of zero in the request, means that the 851 client has no expected maximum size in the given dimension. 852 As a result, a client wishing to reset the maximum size 853 to an unspecified state can use zero for width and height in the 854 request. 855 856 Requesting a maximum size to be smaller than the minimum size of 857 a surface is illegal and will result in a protocol error. 858 859 The width and height must be greater than or equal to zero. Using 860 strictly negative values for width and height will result in a 861 protocol error. 862 </description> 863 <arg name="width" type="int"/> 864 <arg name="height" type="int"/> 865 </request> 866 867 <request name="set_min_size"> 868 <description summary="set the minimum size"> 869 Set a minimum size for the window. 870 871 The client can specify a minimum size so that the compositor does 872 not try to configure the window below this size. 873 874 The width and height arguments are in window geometry coordinates. 875 See xdg_surface.set_window_geometry. 876 877 Values set in this way are double-buffered. They will get applied 878 on the next commit. 879 880 The compositor can use this information to allow or disallow 881 different states like maximize or fullscreen and draw accurate 882 animations. 883 884 Similarly, a tiling window manager may use this information to 885 place and resize client windows in a more effective way. 886 887 The client should not rely on the compositor to obey the minimum 888 size. The compositor may decide to ignore the values set by the 889 client and request a smaller size. 890 891 If never set, or a value of zero in the request, means that the 892 client has no expected minimum size in the given dimension. 893 As a result, a client wishing to reset the minimum size 894 to an unspecified state can use zero for width and height in the 895 request. 896 897 Requesting a minimum size to be larger than the maximum size of 898 a surface is illegal and will result in a protocol error. 899 900 The width and height must be greater than or equal to zero. Using 901 strictly negative values for width and height will result in a 902 protocol error. 903 </description> 904 <arg name="width" type="int"/> 905 <arg name="height" type="int"/> 906 </request> 907 908 <request name="set_maximized"> 909 <description summary="maximize the window"> 910 Maximize the surface. 911 912 After requesting that the surface should be maximized, the compositor 913 will respond by emitting a configure event. Whether this configure 914 actually sets the window maximized is subject to compositor policies. 915 The client must then update its content, drawing in the configured 916 state. The client must also acknowledge the configure when committing 917 the new content (see ack_configure). 918 919 It is up to the compositor to decide how and where to maximize the 920 surface, for example which output and what region of the screen should 921 be used. 922 923 If the surface was already maximized, the compositor will still emit 924 a configure event with the "maximized" state. 925 926 If the surface is in a fullscreen state, this request has no direct 927 effect. It may alter the state the surface is returned to when 928 unmaximized unless overridden by the compositor. 929 </description> 930 </request> 931 932 <request name="unset_maximized"> 933 <description summary="unmaximize the window"> 934 Unmaximize the surface. 935 936 After requesting that the surface should be unmaximized, the compositor 937 will respond by emitting a configure event. Whether this actually 938 un-maximizes the window is subject to compositor policies. 939 If available and applicable, the compositor will include the window 940 geometry dimensions the window had prior to being maximized in the 941 configure event. The client must then update its content, drawing it in 942 the configured state. The client must also acknowledge the configure 943 when committing the new content (see ack_configure). 944 945 It is up to the compositor to position the surface after it was 946 unmaximized; usually the position the surface had before maximizing, if 947 applicable. 948 949 If the surface was already not maximized, the compositor will still 950 emit a configure event without the "maximized" state. 951 952 If the surface is in a fullscreen state, this request has no direct 953 effect. It may alter the state the surface is returned to when 954 unmaximized unless overridden by the compositor. 955 </description> 956 </request> 957 958 <request name="set_fullscreen"> 959 <description summary="set the window as fullscreen on an output"> 960 Make the surface fullscreen. 961 962 After requesting that the surface should be fullscreened, the 963 compositor will respond by emitting a configure event. Whether the 964 client is actually put into a fullscreen state is subject to compositor 965 policies. The client must also acknowledge the configure when 966 committing the new content (see ack_configure). 967 968 The output passed by the request indicates the client's preference as 969 to which display it should be set fullscreen on. If this value is NULL, 970 it's up to the compositor to choose which display will be used to map 971 this surface. 972 973 If the surface doesn't cover the whole output, the compositor will 974 position the surface in the center of the output and compensate with 975 with border fill covering the rest of the output. The content of the 976 border fill is undefined, but should be assumed to be in some way that 977 attempts to blend into the surrounding area (e.g. solid black). 978 979 If the fullscreened surface is not opaque, the compositor must make 980 sure that other screen content not part of the same surface tree (made 981 up of subsurfaces, popups or similarly coupled surfaces) are not 982 visible below the fullscreened surface. 983 </description> 984 <arg name="output" type="object" interface="wl_output" allow-null="true"/> 985 </request> 986 987 <request name="unset_fullscreen"> 988 <description summary="unset the window as fullscreen"> 989 Make the surface no longer fullscreen. 990 991 After requesting that the surface should be unfullscreened, the 992 compositor will respond by emitting a configure event. 993 Whether this actually removes the fullscreen state of the client is 994 subject to compositor policies. 995 996 Making a surface unfullscreen sets states for the surface based on the following: 997 * the state(s) it may have had before becoming fullscreen 998 * any state(s) decided by the compositor 999 * any state(s) requested by the client while the surface was fullscreen 1000 1001 The compositor may include the previous window geometry dimensions in 1002 the configure event, if applicable. 1003 1004 The client must also acknowledge the configure when committing the new 1005 content (see ack_configure). 1006 </description> 1007 </request> 1008 1009 <request name="set_minimized"> 1010 <description summary="set the window as minimized"> 1011 Request that the compositor minimize your surface. There is no 1012 way to know if the surface is currently minimized, nor is there 1013 any way to unset minimization on this surface. 1014 1015 If you are looking to throttle redrawing when minimized, please 1016 instead use the wl_surface.frame event for this, as this will 1017 also work with live previews on windows in Alt-Tab, Expose or 1018 similar compositor features. 1019 </description> 1020 </request> 1021 1022 <event name="configure"> 1023 <description summary="suggest a surface change"> 1024 This configure event asks the client to resize its toplevel surface or 1025 to change its state. The configured state should not be applied 1026 immediately. See xdg_surface.configure for details. 1027 1028 The width and height arguments specify a hint to the window 1029 about how its surface should be resized in window geometry 1030 coordinates. See set_window_geometry. 1031 1032 If the width or height arguments are zero, it means the client 1033 should decide its own window dimension. This may happen when the 1034 compositor needs to configure the state of the surface but doesn't 1035 have any information about any previous or expected dimension. 1036 1037 The states listed in the event specify how the width/height 1038 arguments should be interpreted, and possibly how it should be 1039 drawn. 1040 1041 Clients must send an ack_configure in response to this event. See 1042 xdg_surface.configure and xdg_surface.ack_configure for details. 1043 </description> 1044 <arg name="width" type="int"/> 1045 <arg name="height" type="int"/> 1046 <arg name="states" type="array"/> 1047 </event> 1048 1049 <event name="close"> 1050 <description summary="surface wants to be closed"> 1051 The close event is sent by the compositor when the user 1052 wants the surface to be closed. This should be equivalent to 1053 the user clicking the close button in client-side decorations, 1054 if your application has any. 1055 1056 This is only a request that the user intends to close the 1057 window. The client may choose to ignore this request, or show 1058 a dialog to ask the user to save their data, etc. 1059 </description> 1060 </event> 1061 </interface> 1062 1063 <interface name="xdg_popup" version="3"> 1064 <description summary="short-lived, popup surfaces for menus"> 1065 A popup surface is a short-lived, temporary surface. It can be used to 1066 implement for example menus, popovers, tooltips and other similar user 1067 interface concepts. 1068 1069 A popup can be made to take an explicit grab. See xdg_popup.grab for 1070 details. 1071 1072 When the popup is dismissed, a popup_done event will be sent out, and at 1073 the same time the surface will be unmapped. See the xdg_popup.popup_done 1074 event for details. 1075 1076 Explicitly destroying the xdg_popup object will also dismiss the popup and 1077 unmap the surface. Clients that want to dismiss the popup when another 1078 surface of their own is clicked should dismiss the popup using the destroy 1079 request. 1080 1081 A newly created xdg_popup will be stacked on top of all previously created 1082 xdg_popup surfaces associated with the same xdg_toplevel. 1083 1084 The parent of an xdg_popup must be mapped (see the xdg_surface 1085 description) before the xdg_popup itself. 1086 1087 The client must call wl_surface.commit on the corresponding wl_surface 1088 for the xdg_popup state to take effect. 1089 </description> 1090 1091 <enum name="error"> 1092 <entry name="invalid_grab" value="0" 1093 summary="tried to grab after being mapped"/> 1094 </enum> 1095 1096 <request name="destroy" type="destructor"> 1097 <description summary="remove xdg_popup interface"> 1098 This destroys the popup. Explicitly destroying the xdg_popup 1099 object will also dismiss the popup, and unmap the surface. 1100 1101 If this xdg_popup is not the "topmost" popup, a protocol error 1102 will be sent. 1103 </description> 1104 </request> 1105 1106 <request name="grab"> 1107 <description summary="make the popup take an explicit grab"> 1108 This request makes the created popup take an explicit grab. An explicit 1109 grab will be dismissed when the user dismisses the popup, or when the 1110 client destroys the xdg_popup. This can be done by the user clicking 1111 outside the surface, using the keyboard, or even locking the screen 1112 through closing the lid or a timeout. 1113 1114 If the compositor denies the grab, the popup will be immediately 1115 dismissed. 1116 1117 This request must be used in response to some sort of user action like a 1118 button press, key press, or touch down event. The serial number of the 1119 event should be passed as 'serial'. 1120 1121 The parent of a grabbing popup must either be an xdg_toplevel surface or 1122 another xdg_popup with an explicit grab. If the parent is another 1123 xdg_popup it means that the popups are nested, with this popup now being 1124 the topmost popup. 1125 1126 Nested popups must be destroyed in the reverse order they were created 1127 in, e.g. the only popup you are allowed to destroy at all times is the 1128 topmost one. 1129 1130 When compositors choose to dismiss a popup, they may dismiss every 1131 nested grabbing popup as well. When a compositor dismisses popups, it 1132 will follow the same dismissing order as required from the client. 1133 1134 The parent of a grabbing popup must either be another xdg_popup with an 1135 active explicit grab, or an xdg_popup or xdg_toplevel, if there are no 1136 explicit grabs already taken. 1137 1138 If the topmost grabbing popup is destroyed, the grab will be returned to 1139 the parent of the popup, if that parent previously had an explicit grab. 1140 1141 If the parent is a grabbing popup which has already been dismissed, this 1142 popup will be immediately dismissed. If the parent is a popup that did 1143 not take an explicit grab, an error will be raised. 1144 1145 During a popup grab, the client owning the grab will receive pointer 1146 and touch events for all their surfaces as normal (similar to an 1147 "owner-events" grab in X11 parlance), while the top most grabbing popup 1148 will always have keyboard focus. 1149 </description> 1150 <arg name="seat" type="object" interface="wl_seat" 1151 summary="the wl_seat of the user event"/> 1152 <arg name="serial" type="uint" summary="the serial of the user event"/> 1153 </request> 1154 1155 <event name="configure"> 1156 <description summary="configure the popup surface"> 1157 This event asks the popup surface to configure itself given the 1158 configuration. The configured state should not be applied immediately. 1159 See xdg_surface.configure for details. 1160 1161 The x and y arguments represent the position the popup was placed at 1162 given the xdg_positioner rule, relative to the upper left corner of the 1163 window geometry of the parent surface. 1164 1165 For version 2 or older, the configure event for an xdg_popup is only 1166 ever sent once for the initial configuration. Starting with version 3, 1167 it may be sent again if the popup is setup with an xdg_positioner with 1168 set_reactive requested, or in response to xdg_popup.reposition requests. 1169 </description> 1170 <arg name="x" type="int" 1171 summary="x position relative to parent surface window geometry"/> 1172 <arg name="y" type="int" 1173 summary="y position relative to parent surface window geometry"/> 1174 <arg name="width" type="int" summary="window geometry width"/> 1175 <arg name="height" type="int" summary="window geometry height"/> 1176 </event> 1177 1178 <event name="popup_done"> 1179 <description summary="popup interaction is done"> 1180 The popup_done event is sent out when a popup is dismissed by the 1181 compositor. The client should destroy the xdg_popup object at this 1182 point. 1183 </description> 1184 </event> 1185 1186 <!-- Version 3 additions --> 1187 1188 <request name="reposition" since="3"> 1189 <description summary="recalculate the popup's location"> 1190 Reposition an already-mapped popup. The popup will be placed given the 1191 details in the passed xdg_positioner object, and a 1192 xdg_popup.repositioned followed by xdg_popup.configure and 1193 xdg_surface.configure will be emitted in response. Any parameters set 1194 by the previous positioner will be discarded. 1195 1196 The passed token will be sent in the corresponding 1197 xdg_popup.repositioned event. The new popup position will not take 1198 effect until the corresponding configure event is acknowledged by the 1199 client. See xdg_popup.repositioned for details. The token itself is 1200 opaque, and has no other special meaning. 1201 1202 If multiple reposition requests are sent, the compositor may skip all 1203 but the last one. 1204 1205 If the popup is repositioned in response to a configure event for its 1206 parent, the client should send an xdg_positioner.set_parent_configure 1207 and possibly a xdg_positioner.set_parent_size request to allow the 1208 compositor to properly constrain the popup. 1209 1210 If the popup is repositioned together with a parent that is being 1211 resized, but not in response to a configure event, the client should 1212 send a xdg_positioner.set_parent_size request. 1213 </description> 1214 <arg name="positioner" type="object" interface="xdg_positioner"/> 1215 <arg name="token" type="uint" summary="reposition request token"/> 1216 </request> 1217 1218 <event name="repositioned" since="3"> 1219 <description summary="signal the completion of a repositioned request"> 1220 The repositioned event is sent as part of a popup configuration 1221 sequence, together with xdg_popup.configure and lastly 1222 xdg_surface.configure to notify the completion of a reposition request. 1223 1224 The repositioned event is to notify about the completion of a 1225 xdg_popup.reposition request. The token argument is the token passed 1226 in the xdg_popup.reposition request. 1227 1228 Immediately after this event is emitted, xdg_popup.configure and 1229 xdg_surface.configure will be sent with the updated size and position, 1230 as well as a new configure serial. 1231 1232 The client should optionally update the content of the popup, but must 1233 acknowledge the new popup configuration for the new position to take 1234 effect. See xdg_surface.ack_configure for details. 1235 </description> 1236 <arg name="token" type="uint" summary="reposition request token"/> 1237 </event> 1238 1239 </interface> 1240</protocol> 1241