protocol/wayland.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <protocol name="wayland">
   3
   4   <copyright>
   5     Copyright © 2008-2011 Kristian Høgsberg
   6     Copyright © 2010-2011 Intel Corporation
   7
   8     Permission to use, copy, modify, distribute, and sell this
   9     software and its documentation for any purpose is hereby granted
  10     without fee, provided that\n the above copyright notice appear in
  11     all copies and that both that copyright notice and this permission
  12     notice appear in supporting documentation, and that the name of
  13     the copyright holders not be used in advertising or publicity
  14     pertaining to distribution of the software without specific,
  15     written prior permission.  The copyright holders make no
  16     representations about the suitability of this software for any
  17     purpose.  It is provided "as is" without express or implied
  18     warranty.
  19
  20     THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  21     SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22     FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  23     SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  24     WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
  25     AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  26     ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  27     THIS SOFTWARE.
  28   </copyright>
  29
  30   <interface name="wl_display" version="1">
  31     <description summary="core global object">
  32       The core global object.  This is a special singleton object.  It
  33       is used for internal wayland protocol features.
  34     </description>
  35     <request name="bind">
  36       <description summary="bind an object to the display">
  37         Binds a new, client created object to the server using @name as
  38         the identifier.
  39       </description>
  40       <arg name="name" type="uint" summary="unique number id for object"/>
  41       <arg name="interface" type="string"/>
  42       <arg name="version" type="uint"/>
  43       <arg name="id" type="new_id" interface="wl_object"/>
  44     </request>
  45
  46     <request name="sync">
  47       <description summary="asynchronous roundtrip">
  48         The sync request asks the server to invoke the 'done' request
  49         on the provided wl_callback object.  Since requests are
  50         handled in-order, this can be used as a barrier to ensure all
  51         previous requests have been handled.
  52       </description>
  53       <arg name="callback" type="new_id" interface="wl_callback"/>
  54     </request>
  55
  56     <event name="error">
  57       <description summary="fatal error event">
  58         The error event is sent out when a fatal (non-recoverable)
  59         error has occurred.
  60       </description>
  61       <arg name="object_id" type="object" interface="wl_object"/>
  62       <arg name="code" type="uint"/>
  63       <arg name="message" type="string"/>
  64     </event>
  65
  66     <enum name="error">
  67       <description summary="global error values">
  68         These errors are global and can be emitted in response to any
  69         server request.
  70       </description>
  71       <entry name="invalid_object" value="0"
  72              summary="server couldn't find object"/>
  73       <entry name="invalid_method" value="1"
  74              summary="method doesn't exist on the specified interface"/>
  75       <entry name="no_memory" value="2"
  76              summary="server is out of memory"/>
  77     </enum>
  78
  79     <event name="global">
  80       <description summary="announce global object">
  81         Notify the client of global objects.  These are objects that
  82         are created by the server.  Globals are published on the
  83         initial client connection sequence, upon device hotplugs,
  84         device disconnects, reconfiguration or other events.  A client
  85         can 'bind' to a global object by using the bind request.  This
  86         creates a client side handle that lets the object emit events
  87         to the client and lets the client invoke requests on the
  88         object.
  89       </description>
  90       <arg name="name" type="uint"/>
  91       <arg name="interface" type="string"/>
  92       <arg name="version" type="uint"/>
  93     </event>
  94
  95     <event name="global_remove">
  96       <description summary="announce removal of global object">
  97         Notify the client of removed global objects.
  98       </description>
  99       <arg name="name" type="uint"/>
 100     </event>
 101
 102     <event name="delete_id">
 103       <description summary="acknowledge object id deletion">
 104         Server has deleted the id and client can now reuse it.
 105       </description>
 106       <arg name="id" type="uint" />
 107     </event>
 108   </interface>
 109
 110   <interface name="wl_callback" version="1">
 111     <event name="done">
 112       <arg name="time" type="uint"/>
 113     </event>
 114   </interface>
 115
 116   <interface name="wl_compositor" version="1">
 117     <description summary="the compositor singleton">
 118       A compositor.  This object is a singleton global.  The
 119       compositor is in charge of combining the contents of multiple
 120       surfaces into one displayable output.
 121     </description>
 122
 123     <request name="create_surface">
 124       <description summary="create new surface">
 125         Ask the compositor to create a new surface.
 126       </description>
 127       <arg name="id" type="new_id" interface="wl_surface"/>
 128     </request>
 129   </interface>
 130
 131   <interface name="wl_shm" version="1">
 132     <description summary="shared memory support">
 133       Support for shared memory buffers.
 134     </description>
 135
 136     <enum name="error">
 137       <entry name="invalid_format" value="0"/>
 138       <entry name="invalid_stride" value="1"/>
 139       <entry name="invalid_fd" value="2"/>
 140     </enum>
 141
 142     <enum name="format">
 143       <entry name="argb8888" value="0"/>
 144       <entry name="xrgb8888" value="1"/>
 145     </enum>
 146
 147     <request name="create_buffer">
 148       <description summary="create a wl_buffer">
 149         Transfer a shm buffer to the server.  The allocated buffer
 150         would include at least stride * height bytes starting at the
 151         beginning of fd.  The file descriptor is transferred over the
 152         socket using AF_UNIX magical features. width, height, stride
 153         and format describe the respective properties of the pixel
 154         data contained in the buffer.
 155       </description>
 156
 157       <arg name="id" type="new_id" interface="wl_buffer"/>
 158       <arg name="fd" type="fd"/>
 159       <arg name="width" type="int"/>
 160       <arg name="height" type="int"/>
 161       <arg name="stride" type="uint"/>
 162       <arg name="format" type="uint"/>
 163     </request>
 164
 165     <event name="format">
 166       <arg name="format" type="uint"/>
 167     </event>
 168   </interface>
 169
 170   <interface name="wl_buffer" version="1">
 171     <description summary="content for a wl_surface">
 172       A buffer provides the content for a wl_surface.  Buffers are
 173       created through factory interfaces such as wl_drm, wl_shm or
 174       similar.  It has a width and a height and can be attached to a
 175       wl_surface, but the mechnism by which a client provides and
 176       updates the contents is defined by the buffer factory interface
 177     </description>
 178
 179     <request name="damage">
 180       <description summary="mark part of the buffer damaged">
 181         Notify the server that the specified area of the buffers
 182         contents have changed.  To describe a more complicated area of
 183         damage, break down the region into rectangles and use this
 184         request several times.
 185       </description>
 186
 187       <arg name="x" type="int"/>
 188       <arg name="y" type="int"/>
 189       <arg name="width" type="int"/>
 190       <arg name="height" type="int"/>
 191     </request>
 192
 193     <request name="destroy" type="destructor">
 194       <description summary="destroy a buffer">
 195         Destroy a buffer.  This will invalidate the object id.
 196       </description>
 197     </request>
 198
 199     <event name="release">
 200       <description summary="compositor releses buffer">
 201         Sent when an attached buffer is no longer used by the compositor.
 202       </description>
 203     </event>
 204   </interface>
 205
 206
 207   <interface name="wl_data_offer" version="1">
 208     <request name="accept">
 209       <description summary="accept one of the offered mime-types">
 210         Indicate that the client can accept the given mime-type, or
 211         NULL for not accepted.  Use for feedback during drag and drop.
 212       </description>
 213
 214       <arg name="time" type="uint"/>
 215       <arg name="type" type="string"/>
 216     </request>
 217
 218     <request name="receive">
 219       <arg name="mime_type" type="string"/>
 220       <arg name="fd" type="fd"/>
 221     </request>
 222
 223     <request name="destroy" type="destructor"/>
 224
 225     <event name="offer">
 226       <description summary="advertise offered mime-type">
 227         Sent immediately after creating the wl_data_offer object.  One
 228         event per offered mime type.
 229       </description>
 230
 231       <arg name="type" type="string"/>
 232     </event>
 233   </interface>
 234
 235   <interface name="wl_data_source" version="1">
 236     <request name="offer">
 237       <description summary="add an offered mime type">
 238         This request adds a mime-type to the set of mime-types
 239         advertised to targets.  Can be called several times to offer
 240         multiple types.
 241       </description>
 242       <arg name="type" type="string"/>
 243     </request>
 244
 245     <request name="destroy" type="destructor">
 246       <description summary="destroy the data source">
 247         Destroy the data source.
 248       </description>
 249     </request>
 250
 251     <event name="target">
 252       <description summary="a target accepts an offered mime-type">
 253         Sent when a target accepts pointer_focus or motion events.  If
 254         a target does not accept any of the offered types, type is NULL.
 255       </description>
 256
 257       <arg name="mime_type" type="string"/>
 258     </event>
 259
 260     <event name="send">
 261       <description summary="send the data">
 262         Request for data from another client.  Send the data as the
 263         specified mime-type over the passed fd, then close the fd.
 264       </description>
 265
 266       <arg name="mime_type" type="string"/>
 267       <arg name="fd" type="fd"/>
 268     </event>
 269
 270     <event name="cancelled">
 271       <description summary="selection was cancelled">
 272         Another selection became active.
 273       </description>
 274     </event>
 275
 276   </interface>
 277
 278   <interface name="wl_data_device" version="1">
 279     <request name="start_drag">
 280       <arg name="source" type="object" interface="wl_data_source"/>
 281       <arg name="surface" type="object" interface="wl_surface"/>
 282       <arg name="time" type="uint"/>
 283     </request>
 284
 285     <request name="attach">
 286       <arg name="time" type="uint"/>
 287       <arg name="buffer" type="object" interface="wl_buffer"/>
 288       <arg name="x" type="int"/>
 289       <arg name="y" type="int"/>
 290     </request>
 291
 292     <request name="set_selection">
 293       <arg name="source" type="object" interface="wl_data_source"/>
 294       <arg name="time" type="uint"/>
 295     </request>
 296
 297     <event name="data_offer">
 298       <description summary="introduce a new wl_data_offer">
 299         The data_offer event introduces a new wl_data_offer object,
 300         which will subsequently be used in either the
 301         data_device.enter event (for drag and drop) or the
 302         data_device.selection event (for selections).  Immediately
 303         following the data_device_data_offer event, the new data_offer
 304         object will send out data_offer.offer events to describe the
 305         mime-types it offers.
 306       </description>
 307
 308       <arg name="id" type="new_id" interface="wl_data_offer"/>
 309     </event>
 310
 311     <event name="enter">
 312       <arg name="time" type="uint"/>
 313       <arg name="surface" type="object" interface="wl_surface"/>
 314       <arg name="x" type="int"/>
 315       <arg name="y" type="int"/>
 316       <arg name="id" type="object" interface="wl_data_offer"/>
 317     </event>
 318
 319     <event name="leave"/>
 320
 321     <event name="motion">
 322       <arg name="time" type="uint"/>
 323       <arg name="x" type="int"/>
 324       <arg name="y" type="int"/>
 325     </event>
 326
 327     <event name="drop"/>
 328
 329     <event name="selection">
 330       <description summary="advertise new selection">
 331         The selection event is sent out to notify the client of a new
 332         wl_data_offer for the selection for this device.  The
 333         data_device.data_offer and the data_offer.offer events are
 334         sent out immediately before this event to introduce the data
 335         offer object.  The selection event is sent to a client
 336         immediately before receiving keyboard focus and when a new
 337         selection is set while the client has keyboard focus.  The
 338         data_offer is valid until a new data_offer or NULL is received
 339         or until the client loses keyboard focus.
 340       </description>
 341       <arg name="id" type="object" interface="wl_data_offer"/>
 342     </event>
 343   </interface>
 344
 345   <interface name="wl_data_device_manager" version="1">
 346     <request name="create_data_source">
 347       <arg name="id" type="new_id" interface="wl_data_source"/>
 348     </request>
 349
 350     <request name="get_data_device">
 351       <arg name="id" type="new_id" interface="wl_data_device"/>
 352       <arg name="input_device" type="object" interface="wl_input_device"/>
 353     </request>
 354   </interface>
 355
 356   <interface name="wl_shell" version="1">
 357     <request name="get_shell_surface">
 358       <arg name="id" type="new_id" interface="wl_shell_surface"/>
 359       <arg name="surface" type="object" interface="wl_surface"/>
 360     </request>
 361   </interface>
 362
 363   <interface name="wl_shell_surface" version="1">
 364
 365     <description summary="desktop style meta data interface">
 366       An interface implemented by a wl_surface.  On server side the
 367       object is automatically destroyed when the related wl_surface is
 368       destroyed.  On client side, wl_shell_surface_destroy() must be
 369       called before destroying the wl_surface object.
 370     </description>
 371
 372     <request name="move">
 373       <arg name="input_device" type="object" interface="wl_input_device"/>
 374       <arg name="time" type="uint"/>
 375     </request>
 376
 377     <enum name="resize">
 378       <entry name="none" value="0"/>
 379       <entry name="top" value="1"/>
 380       <entry name="bottom" value="2"/>
 381       <entry name="left" value="4"/>
 382       <entry name="top_left" value="5"/>
 383       <entry name="bottom_left" value="6"/>
 384       <entry name="right" value="8"/>
 385       <entry name="top_right" value="9"/>
 386       <entry name="bottom_right" value="10"/>
 387     </enum>
 388
 389     <request name="resize">
 390       <arg name="input_device" type="object" interface="wl_input_device"/>
 391       <arg name="time" type="uint"/>
 392       <arg name="edges" type="uint"/>
 393     </request>
 394
 395     <request name="set_toplevel">
 396       <description summary="make the surface a top level surface">
 397         Make the surface a toplevel window.
 398       </description>
 399     </request>
 400
 401     <request name="set_transient">
 402       <description summary="make the surface a transient surface">
 403         Map the surface relative to an existing surface. The x and y
 404         arguments specify the locations of the upper left corner of
 405         the surface relative to the upper left corner of the parent
 406         surface.  The flags argument controls overflow/clipping
 407         behaviour when the surface would intersect a screen edge,
 408         panel or such.  And possibly whether the offset only
 409         determines the initial position or if the surface is locked to
 410         that relative position during moves.
 411       </description>
 412
 413       <arg name="parent" type="object" interface="wl_shell_surface"/>
 414       <arg name="x" type="int"/>
 415       <arg name="y" type="int"/>
 416       <arg name="flags" type="uint"/>
 417     </request>
 418
 419     <request name="set_fullscreen">
 420       <description summary="make the surface a fullscreen surface">
 421         Map the surface as a fullscreen surface.  There are a number
 422         of options here: on which output? if the surface size doesn't
 423         match the output size, do we scale, change resolution, or add
 424         black borders? is that something the client controls?  what
 425         about transient surfaces, do they float on top of the
 426         fullscreen? what if there's already a fullscreen surface on
 427         the output, maybe you can only go fullscreen if you're active?
 428       </description>
 429     </request>
 430
 431     <request name="set_popup">
 432       <description summary="make the surface a popup surface">
 433         Popup surfaces.  Will switch an implicit grab into
 434         owner-events mode, and grab will continue after the implicit
 435         grab ends (button released).  Once the implicit grab is over,
 436         the popup grab continues until the window is destroyed or a
 437         mouse button is pressed in any other clients window.  A click
 438         in any of the clients surfaces is reported as normal, however,
 439         clicks in other clients surfaces will be discarded and trigger
 440         the callback.
 441
 442         TODO: Grab keyboard too, maybe just terminate on any click
 443         inside or outside the surface?
 444       </description>
 445
 446       <arg name="input_device" type="object" interface="wl_input_device"/>
 447       <arg name="time" type="uint"/>
 448       <arg name="parent" type="object" interface="wl_shell_surface"/>
 449       <arg name="x" type="int"/>
 450       <arg name="y" type="int"/>
 451       <arg name="flags" type="uint"/>
 452     </request>
 453
 454     <event name="configure">
 455       <description summary="suggest resize">
 456         The configure event asks the client to resize its surface.
 457         The size is a hint, in the sense that the client is free to
 458         ignore it if it doesn't resize, pick a smaller size (to
 459         satisfy aspect ration or resize in steps of NxM pixels).  The
 460         client is free to dismiss all but the last configure event it
 461         received.
 462       </description>
 463
 464       <arg name="time" type="uint"/>
 465       <arg name="edges" type="uint"/>
 466       <arg name="width" type="int"/>
 467       <arg name="height" type="int"/>
 468     </event>
 469
 470     <event name="popup_done">
 471       <description summary="popup interaction is done">
 472         The popup_done event is sent out when a popup grab is broken,
 473         that is, when the users clicks a surface that doesn't belong
 474         to the client owning the popup surface.
 475       </description>
 476     </event>
 477   </interface>
 478
 479   <interface name="wl_surface" version="1">
 480     <description summary="an onscreen surface">
 481       A surface.  This is an image that is displayed on the screen.
 482       It has a location, size and pixel contents.
 483     </description>
 484
 485     <request name="destroy" type="destructor">
 486       <description summary="delete surface">
 487         Deletes the surface and invalidates its object id.
 488       </description>
 489     </request>
 490
 491     <request name="attach">
 492       <description summary="set the surface contents">
 493         Copy the contents of a buffer into this surface. The x and y
 494         arguments specify the location of the new buffers upper left
 495         corner, relative to the old buffers upper left corner.
 496       </description>
 497
 498       <arg name="buffer" type="object" interface="wl_buffer"/>
 499       <arg name="x" type="int"/>
 500       <arg name="y" type="int"/>
 501     </request>
 502
 503     <request name="damage">
 504       <description summary="mark part of the surface damaged">
 505         After attaching a new buffer, this request is used to describe
 506         the regions where the new buffer is different from the
 507         previous buffer and needs to be repainted.  Coordinates are
 508         relative to the new buffer.
 509       </description>
 510
 511       <arg name="x" type="int"/>
 512       <arg name="y" type="int"/>
 513       <arg name="width" type="int"/>
 514       <arg name="height" type="int"/>
 515     </request>
 516
 517     <request name="frame">
 518       <description summary="request repaint feedback">
 519         Request notification when the next frame is displayed.  Useful
 520         for throttling redrawing operations, and driving animations.
 521         The notification will only be posted for one frame unless
 522         requested again.
 523       </description>
 524
 525       <arg name="callback" type="new_id" interface="wl_callback"/>
 526     </request>
 527
 528   </interface>
 529
 530   <interface name="wl_input_device" version="1">
 531     <description summary="input device group">
 532       A group of keyboards and pointer devices (mice, for
 533       example). This object is published as a global during start up,
 534       or when such a device is hot plugged.  A input_device group
 535       typically has a pointer and maintains a keyboard_focus and a
 536       pointer_focus.
 537     </description>
 538
 539     <request name="attach">
 540       <description summary="set the pointer image">
 541         Set the pointer's image.  This request only takes effect if
 542         the pointer focus for this device is one of the requesting
 543         clients surfaces.
 544       </description>
 545
 546       <arg name="time" type="uint"/>
 547       <arg name="buffer" type="object" interface="wl_buffer"/>
 548       <arg name="hotspot_x" type="int"/>
 549       <arg name="hotspot_y" type="int"/>
 550     </request>
 551
 552     <event name="motion">
 553       <description summary="pointer motion event">
 554         Notification of pointer location change.  x,y are the absolute
 555         location on the screen.  surface_[xy] are the location
 556         relative to the focused surface.
 557       </description>
 558
 559       <arg name="time" type="uint"/>
 560       <arg name="x" type="int"/>
 561       <arg name="y" type="int"/>
 562       <arg name="surface_x" type="int"/>
 563       <arg name="surface_y" type="int"/>
 564     </event>
 565
 566     <event name="button">
 567       <description summary="pointer button event">
 568         Mouse button click and release notifications.  The location
 569         of the click is given by the last motion or pointer_focus event.
 570       </description>
 571
 572       <arg name="time" type="uint"/>
 573       <arg name="button" type="uint"/>
 574       <arg name="state" type="uint"/>
 575     </event>
 576
 577     <event name="key">
 578       <description summary="key event">
 579         A key was pressed or released.
 580       </description>
 581
 582       <arg name="time" type="uint"/>
 583       <arg name="key" type="uint"/>
 584       <arg name="state" type="uint"/>
 585     </event>
 586
 587     <event name="pointer_focus">
 588       <description summary="pointer focus change event">
 589         Notification that this input device's pointer is focused on
 590         certain surface. When an input_device enters a surface, the
 591         pointer image is undefined and a client should respond to this
 592         event by setting an apropriate pointer image.
 593       </description>
 594
 595       <arg name="time" type="uint"/>
 596       <arg name="surface" type="object" interface="wl_surface"/>
 597       <arg name="x" type="int"/>
 598       <arg name="y" type="int"/>
 599       <arg name="surface_x" type="int"/>
 600       <arg name="surface_y" type="int"/>
 601     </event>
 602
 603     <event name="keyboard_focus">
 604       <arg name="time" type="uint"/>
 605       <arg name="surface" type="object" interface="wl_surface"/>
 606       <arg name="keys" type="array"/>
 607     </event>
 608
 609     <event name="touch_down">
 610       <arg name="time" type="uint"/>
 611       <arg name="surface" type="object" interface="wl_surface"/>
 612       <arg name="id" type="int" />
 613       <arg name="x" type="int" />
 614       <arg name="y" type="int" />
 615     </event>
 616
 617     <event name="touch_up">
 618       <arg name="time" type="uint"/>
 619       <arg name="id" type="int" />
 620     </event>
 621
 622     <event name="touch_motion">
 623       <arg name="time" type="uint"/>
 624       <arg name="id" type="int" />
 625       <arg name="x" type="int" />
 626       <arg name="y" type="int" />
 627     </event>
 628
 629     <event name="touch_frame">
 630       <description summary="end of touch frame event">
 631         Indicates the end of a contact point list.
 632       </description>
 633     </event>
 634
 635     <event name="touch_cancel">
 636       <description summary="touch session cancelled">
 637         Sent if the compositor decides the touch stream is a global
 638         gesture. No further events are sent to the clients from that
 639         particular gesture.
 640       </description>
 641     </event>
 642   </interface>
 643
 644
 645   <interface name="wl_output" version="1">
 646     <description summary="composior output region">
 647       An output describes part of the compositor geometry.  The
 648       compositor work in the 'compositor coordinate system' and an
 649       output corresponds to rectangular area in that space that is
 650       actually visible.  This typically corresponds to a monitor that
 651       displays part of the compositor space.  This object is published
 652       as global during start up, or when a screen is hot plugged.
 653     </description>
 654
 655     <enum name="subpixel">
 656       <entry name="unknown" value="0"/>
 657       <entry name="none" value="1"/>
 658       <entry name="horizontal_rgb" value="2"/>
 659       <entry name="horizontal_bgr" value="3"/>
 660       <entry name="vertical_rgb" value="4"/>
 661       <entry name="vertical_bgr" value="5"/>
 662     </enum>
 663
 664     <event name="geometry">
 665       <arg name="x" type="int"/>
 666       <arg name="y" type="int"/>
 667       <arg name="physical_width" type="int"/>
 668       <arg name="physical_height" type="int"/>
 669       <arg name="subpixel" type="int"/>
 670       <arg name="make" type="string"/>
 671       <arg name="model" type="string"/>
 672     </event>
 673
 674     <enum name="mode">
 675       <description summary="values for the flags bitfield in the mode event"/>
 676       <entry name="current" value="0x1"/>
 677       <entry name="preferred" value="0x2"/>
 678     </enum>
 679
 680     <event name="mode">
 681       <arg name="flags" type="uint"/>
 682       <arg name="width" type="int"/>
 683       <arg name="height" type="int"/>
 684       <arg name="refresh" type="int"/>
 685     </event>
 686   </interface>
 687
 688 </protocol>