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