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