<?xml version="1.0" encoding="UTF-8"?>
<protocol name="wayland">
- <!-- The core global object. This is a special singleton object.
- It is used for internal wayland protocol features. -->
+ <copyright>
+ Copyright © 2008-2011 Kristian Høgsberg
+ Copyright © 2010-2011 Intel Corporation
+
+ Permission to use, copy, modify, distribute, and sell this
+ software and its documentation for any purpose is hereby granted
+ without fee, provided that the above copyright notice appear in
+ all copies and that both that copyright notice and this permission
+ notice appear in supporting documentation, and that the name of
+ the copyright holders not be used in advertising or publicity
+ pertaining to distribution of the software without specific,
+ written prior permission. The copyright holders make no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied
+ warranty.
+
+ THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+ SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+ AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ THIS SOFTWARE.
+ </copyright>
+
<interface name="wl_display" version="1">
- <request name="bind">
- <arg name="id" type="uint"/>
- <arg name="interface" type="string"/>
- <arg name="version" type="uint"/>
- </request>
+ <description summary="core global object">
+ The core global object. This is a special singleton object. It
+ is used for internal Wayland protocol features.
+ </description>
- <!-- sync is an just an echo, which will reply with a sync event.
- Since requests are handled in-order, this can be used as a
- barrier to ensure all previous requests have ben handled.
- The key argument can be used to correlate between multiple
- sync invocations. -->
<request name="sync">
- <arg name="key" type="uint"/>
+ <description summary="asynchronous roundtrip">
+ The sync request asks the server to emit the 'done' event
+ on the provided wl_callback object. Since requests are
+ handled in-order, this can be used as a barrier to ensure all
+ previous requests have been handled.
+ </description>
+ <arg name="callback" type="new_id" interface="wl_callback"/>
</request>
- <!-- Request notification when the next frame is displayed.
- Useful for throttling redrawing operations, and driving
- animations. The notification will only be posted for one
- frame unless requested again. -->
- <request name="frame">
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="key" type="uint"/>
+ <request name="get_registry">
+ <description summary="get global registry object">
+ This request creates a registry object that allows the client
+ to list and bind the global objects available from the
+ compositor.
+ </description>
+ <arg name="callback" type="new_id" interface="wl_registry"/>
</request>
- <!-- A fatal error has occurred. -->
<event name="error">
- <arg name="object_id" type="object" interface="wl_object"/>
+ <description summary="fatal error event">
+ The error event is sent out when a fatal (non-recoverable)
+ error has occurred. The @object_id argument is the object
+ where the error occurred, most often in response to a request
+ to that object. The @code identifies the error and is defined
+ by the object interface. As such, each interface defines its
+ own set of error codes. The @message is an brief description
+ of the error, for (debugging) convenience.
+ </description>
+ <arg name="object_id" type="object"/>
<arg name="code" type="uint"/>
<arg name="message" type="string"/>
</event>
<enum name="error">
- <entry name="invalid_object" value="0"/>
- <entry name="invalid_method" value="1"/>
- <entry name="no_memory" value="2"/>
+ <description summary="global error values">
+ These errors are global and can be emitted in response to any
+ server request.
+ </description>
+ <entry name="invalid_object" value="0"
+ summary="server couldn't find object"/>
+ <entry name="invalid_method" value="1"
+ summary="method doesn't exist on the specified interface"/>
+ <entry name="no_memory" value="2"
+ summary="server is out of memory"/>
</enum>
- <!-- Notify the client of global objects. These are objects that
- are created by the server. Globals are published on the
- initial client connection sequence, upon device hotplugs,
- device disconnects, reconfiguration or other events. The
- server will always announce an object before the object sends
- out events. -->
+ <event name="delete_id">
+ <description summary="acknowledge object id deletion">
+ This event is used internally by the object ID management
+ logic. When a client deletes an object, the server will send
+ this event to acknowledge that it has seen the delete request.
+ When the client receive this event, it will know that it can
+ safely reuse the object ID
+ </description>
+ <arg name="id" type="uint" />
+ </event>
+ </interface>
+
+ <interface name="wl_registry" version="1">
+ <description summary="global registry object">
+ The global registry object. The server has a number of global
+ objects that are available to all clients. These objects
+ typically represent an actual object in the server (for example,
+ an input device) or they are singleton objects that provides
+ extension functionality.
+
+ When a client creates a registry object, the registry object
+ will emit a global event for each global currently in the
+ registry. Globals come and go as a result of device hotplugs,
+ reconfiguration or other events, and the registry will send out
+ @global and @global_remove events to keep the client up to date
+ with the changes. To mark the end of the initial burst of
+ events, the client can use the wl_display.sync request
+ immediately after calling wl_display.get_registry.
+
+ A client can 'bind' to a global object by using the bind
+ request. This creates a client side handle that lets the object
+ emit events to the client and lets the client invoke requests on
+ the object.
+ </description>
+
+ <request name="bind">
+ <description summary="bind an object to the display">
+ Binds a new, client-created object to the server using @name as
+ the identifier.
+ </description>
+ <arg name="name" type="uint" summary="unique number id for object"/>
+ <arg name="id" type="new_id"/>
+ </request>
+
<event name="global">
- <arg name="id" type="new_id" interface="wl_object"/>
- <arg name="name" type="string"/>
+ <description summary="announce global object">
+ Notify the client of global objects.
+ </description>
+ <arg name="name" type="uint"/>
+ <arg name="interface" type="string"/>
<arg name="version" type="uint"/>
</event>
- <!-- Notify the client of removed global objects. -->
<event name="global_remove">
- <arg name="id" type="uint" />
- </event>
-
- <!-- Internal, deprecated, and will be changed. This is an object
- IDs range that is used by the client to allocate object IDs
- in "new_id" type arguments. The server sends range
- allocations to the client before the next range is about to
- be depleted. -->
- <event name="range">
- <arg name="base" type="uint"/>
+ <description summary="announce removal of global object">
+ Notify the client of removed global objects. This event
+ notifies the client that the global identifies by @name is no
+ longer available. If the client bound to the global using the
+ 'bind' request, the client should now destroy that object.
+ The object remains valid and requests to the object will be
+ ignored until the client destroys it, to avoid races between
+ the global going away and a client sending a request to it.
+ </description>
+ <arg name="name" type="uint"/>
</event>
+ </interface>
- <!-- A reply to the frame or sync request. The key is the one
- used in the request. time is in millisecond units, and
- denotes the time when the frame was posted on the
- display. time can be used to estimaate frame rate, determine
- how much to advance animations and compensate for jitter. -->
- <event name="key">
- <arg name="key" type="uint"/>
- <arg name="time" type="uint"/>
+ <interface name="wl_callback" version="1">
+ <event name="done">
+ <arg name="serial" type="uint"/>
</event>
</interface>
-
- <!-- A compositor. This object is a global. The compositor is in
- charge of combining the contents of multiple surfaces into one
- displayable output. -->
<interface name="wl_compositor" version="1">
- <!-- Factory request for a surface objects. A surface is akin to a
- window. -->
+ <description summary="the compositor singleton">
+ A compositor. This object is a singleton global. The
+ compositor is in charge of combining the contents of multiple
+ surfaces into one displayable output.
+ </description>
+
<request name="create_surface">
+ <description summary="create new surface">
+ Ask the compositor to create a new surface.
+ </description>
<arg name="id" type="new_id" interface="wl_surface"/>
</request>
- <enum name="visual">
- <entry name="argb32" value="0"/>
- <entry name="premultiplied_argb32" value="1"/>
- <entry name="xrgb32" value="2"/>
- </enum>
+ <request name="create_region">
+ <description summary="create new region">
+ Ask the compositor to create a new region.
+ </description>
+ <arg name="id" type="new_id" interface="wl_region"/>
+ </request>
+ </interface>
- <event name="token_visual">
- <arg name="id" type="new_id" interface="wl_object"/>
- <arg name="token" type="uint"/>
- </event>
+ <interface name="wl_shm_pool" version="1">
+ <description summary="a shared memory pool">
+ The wl_shm_pool object encapsulates a piece of memory shared
+ between the compositor and client. Through the wl_shm_pool
+ object, the client can allocate shared memory wl_buffer objects.
+ The objects will share the same underlying mapped memory.
+ Reusing the mapped memory avoids the setup/teardown overhead and
+ is useful when interactively resizing a surface or for many
+ small buffers.
+ </description>
+
+ <request name="create_buffer">
+ <description summary="create wl_buffer from pool">
+ Create a wl_buffer from the pool. The buffer is created a
+ offset bytes into the pool and has width and height as
+ specified. The stride arguments specifies the number of bytes
+ from beginning of one row to the beginning of the next. The
+ format is the pixel format of the buffer and must be one of
+ those advertised through the wl_shm.format event.
+
+ A buffer will keep a reference to the pool it was created from
+ so it is valid to destroy the pool immediately after creating
+ a buffer from it.
+ </description>
+
+ <arg name="id" type="new_id" interface="wl_buffer"/>
+ <arg name="offset" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ <arg name="stride" type="int"/>
+ <arg name="format" type="uint"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pool">
+ Destroy the pool.
+ </description>
+ </request>
+
+ <request name="resize">
+ <description summary="change the size of the pool mapping">
+ This request will cause the server to remap the backing memory
+ for the pool from the fd passed when the pool was creating but
+ using the new size.
+ </description>
+
+ <arg name="size" type="int"/>
+ </request>
</interface>
- <!-- Shared memory support -->
<interface name="wl_shm" version="1">
+ <description summary="shared memory support">
+ Support for shared memory buffers.
+ </description>
+
<enum name="error">
- <entry name="invalid_visual" value="0"/>
+ <entry name="invalid_format" value="0"/>
<entry name="invalid_stride" value="1"/>
<entry name="invalid_fd" value="2"/>
</enum>
- <!-- Transfer a shm buffer to the server. The allocated buffer
- would include at least stride * height bytes starting at the
- beginning of fd. The file descriptor is transferred over the
- socket using AF_UNIX magical features. width, height, stride
- and visual describe the respective properties of the pixel
- data contained in the buffer. -->
- <request name="create_buffer">
- <arg name="id" type="new_id" interface="wl_buffer"/>
+ <enum name="format">
+ <entry name="argb8888" value="0"/>
+ <entry name="xrgb8888" value="1"/>
+ </enum>
+
+ <request name="create_pool">
+ <description summary="create a shm pool">
+ This creates wl_shm_pool object, which can be used to create
+ shared memory based wl_buffer objects. The server will mmap
+ size bytes of the passed fd, to use as backing memory for then
+ pool.
+ </description>
+
+ <arg name="id" type="new_id" interface="wl_shm_pool"/>
<arg name="fd" type="fd"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
- <arg name="stride" type="uint"/>
- <arg name="visual" type="object" interface="wl_visual"/>
+ <arg name="size" type="int"/>
</request>
- </interface>
+ <event name="format">
+ <arg name="format" type="uint"/>
+ </event>
+ </interface>
- <!-- A pixel buffer. Created using the drm, shm or similar objects.
- It has a size, visual and contents, but not a location on the
- screen. -->
<interface name="wl_buffer" version="1">
- <!-- Notify the server that the specified area of the buffers
- contents have changed. To describe a more complicated area
- of damage, break down the region into rectangles and use this
- request several times.
- -->
- <request name="damage">
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
+ <description summary="content for a wl_surface">
+ A buffer provides the content for a wl_surface. Buffers are
+ created through factory interfaces such as wl_drm, wl_shm or
+ similar. It has a width and a height and can be attached to a
+ wl_surface, but the mechanism by which a client provides and
+ updates the contents is defined by the buffer factory interface.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy a buffer">
+ Destroy a buffer. If and how you need to release the backing
+ storage is defined by the buffer factory interface.
+
+ For possible side-effects to a surface, see wl_surface.attach.
+ </description>
+ </request>
+
+ <event name="release">
+ <description summary="compositor releases buffer">
+ Sent when this wl_buffer is no longer used by the compositor.
+ The client is now free to re-use or destroy this buffer and its
+ backing storage.
+
+ If a client receives a release event before the frame callback
+ requested in the same wl_surface.commit that attaches this
+ wl_buffer to a surface, then the client is immediately free to
+ re-use the buffer and its backing storage, and does not need a
+ second buffer for the next surface content update. Typically
+ this is possible, when the compositor maintains a copy of the
+ wl_surface contents, e.g. as a GL texture. This is an important
+ optimization for GL(ES) compositors with wl_shm clients.
+ </description>
+ </event>
+ </interface>
+
+
+ <interface name="wl_data_offer" version="1">
+ <description summary="offer to transfer data">
+ A wl_data_offer represents a piece of data offered for transfer
+ by another client (the source client). It is used by the
+ copy-and-paste and drag-and-drop mechanisms. The offer
+ describes the different mime types that the data can be
+ converted to and provides the mechanism for transferring the
+ data directly from the source client.
+ </description>
+
+ <request name="accept">
+ <description summary="accept one of the offered mime-types">
+ Indicate that the client can accept the given mime-type, or
+ NULL for not accepted. Use for feedback during drag and drop.
+ </description>
+
+ <arg name="serial" type="uint"/>
+ <arg name="type" type="string" allow-null="true"/>
+ </request>
+
+ <request name="receive">
+ <description summary="request that the data is transferred">
+ To transfer the offered data, the client issues this request
+ and indicates the mime-type it wants to receive. The transfer
+ happens through the passed fd (typically a pipe(7) file
+ descriptor). The source client writes the data in the
+ mime-type representation requested and then closes the fd.
+ The receiving client reads from the read end of the pipe until
+ EOF and the closes its end, at which point the transfer is
+ complete.
+ </description>
+ <arg name="mime_type" type="string"/>
+ <arg name="fd" type="fd"/>
</request>
- <!-- Destroy a buffer. This will invalidate the object id. -->
<request name="destroy" type="destructor"/>
- <!-- Sent when an attached buffer is no longer used by the compositor. -->
- <event name="release"/>
+ <event name="offer">
+ <description summary="advertise offered mime-type">
+ Sent immediately after creating the wl_data_offer object. One
+ event per offered mime type.
+ </description>
+
+ <arg name="type" type="string"/>
+ </event>
</interface>
- <interface name="wl_shell" version="1">
- <request name="move">
+ <interface name="wl_data_source" version="1">
+ <description summary="offer to transfer data">
+ The wl_data_source object is the source side of a wl_data_offer.
+ It is created by the source client in a data transfer and
+ provides a way to describe the offered data and a way to respond
+ to requests to transfer the data.
+ </description>
+
+ <request name="offer">
+ <description summary="add an offered mime type">
+ This request adds a mime-type to the set of mime-types
+ advertised to targets. Can be called several times to offer
+ multiple types.
+ </description>
+ <arg name="type" type="string"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the data source">
+ Destroy the data source.
+ </description>
+ </request>
+
+ <event name="target">
+ <description summary="a target accepts an offered mime-type">
+ Sent when a target accepts pointer_focus or motion events. If
+ a target does not accept any of the offered types, type is NULL.
+ </description>
+
+ <arg name="mime_type" type="string" allow-null="true"/>
+ </event>
+
+ <event name="send">
+ <description summary="send the data">
+ Request for data from another client. Send the data as the
+ specified mime-type over the passed fd, then close the fd.
+ </description>
+
+ <arg name="mime_type" type="string"/>
+ <arg name="fd" type="fd"/>
+ </event>
+
+ <event name="cancelled">
+ <description summary="selection was cancelled">
+ This data source has been replaced by another data source.
+ The client should clean up and destroy this data source.
+ </description>
+ </event>
+
+ </interface>
+
+ <interface name="wl_data_device" version="1">
+ <request name="start_drag">
+ <description summary="start drag and drop operation">
+ This request asks the compositor to start a drag and drop
+ operation on behalf of the client.
+
+ The source argument is the data source that provides the data
+ for the eventual data transfer. If source is NULL, enter, leave
+ and motion events are sent only to the client that initiated the
+ drag and the client is expected to handle the data passing
+ internally.
+
+ The origin surface is the surface where the drag originates and
+ the client must have an active implicit grab that matches the
+ serial.
+
+ The icon surface is an optional (can be nil) surface that
+ provides an icon to be moved around with the cursor. Initially,
+ the top-left corner of the icon surface is placed at the cursor
+ hotspot, but subsequent wl_surface.attach request can move the
+ relative position. Attach requests must be confirmed with
+ wl_surface.commit as usual.
+
+ The current and pending input regions of the icon wl_surface are
+ cleared, and wl_surface.set_input_region is ignored until the
+ wl_surface is no longer used as the icon surface. When the use
+ as an icon ends, the the current and pending input regions
+ become undefined, and the wl_surface is unmapped.
+ </description>
+ <arg name="source" type="object" interface="wl_data_source" allow-null="true"/>
+ <arg name="origin" type="object" interface="wl_surface"/>
+ <arg name="icon" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="serial" type="uint"/>
+ </request>
+
+ <request name="set_selection">
+ <arg name="source" type="object" interface="wl_data_source" allow-null="true"/>
+ <arg name="serial" type="uint"/>
+ </request>
+
+ <event name="data_offer">
+ <description summary="introduce a new wl_data_offer">
+ The data_offer event introduces a new wl_data_offer object,
+ which will subsequently be used in either the
+ data_device.enter event (for drag and drop) or the
+ data_device.selection event (for selections). Immediately
+ following the data_device_data_offer event, the new data_offer
+ object will send out data_offer.offer events to describe the
+ mime-types it offers.
+ </description>
+
+ <arg name="id" type="new_id" interface="wl_data_offer"/>
+ </event>
+
+ <event name="enter">
+ <description summary="initiate drag and drop session">
+ This event is sent when an active drag-and-drop pointer enters
+ a surface owned by the client. The position of the pointer at
+ enter time is provided by the @x an @y arguments, in surface
+ local coordinates.
+ </description>
+
+ <arg name="serial" type="uint"/>
<arg name="surface" type="object" interface="wl_surface"/>
- <arg name="input_device" type="object" interface="wl_input_device"/>
+ <arg name="x" type="fixed"/>
+ <arg name="y" type="fixed"/>
+ <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/>
+ </event>
+
+ <event name="leave">
+ <description summary="end drag and drop session">
+ This event is sent when the drag-and-drop pointer leaves the
+ surface and the session ends. The client must destroy the
+ wl_data_offer introduced at enter time at this point.
+ </description>
+ </event>
+
+ <event name="motion">
+ <description summary="drag and drop session motion">
+ This event is sent when the drag-and-drop pointer moves within
+ the currently focused surface. The new position of the pointer
+ is provided by the @x an @y arguments, in surface local
+ coordinates.
+ </description>
<arg name="time" type="uint"/>
+ <arg name="x" type="fixed"/>
+ <arg name="y" type="fixed"/>
+ </event>
+
+ <event name="drop"/>
+
+ <event name="selection">
+ <description summary="advertise new selection">
+ The selection event is sent out to notify the client of a new
+ wl_data_offer for the selection for this device. The
+ data_device.data_offer and the data_offer.offer events are
+ sent out immediately before this event to introduce the data
+ offer object. The selection event is sent to a client
+ immediately before receiving keyboard focus and when a new
+ selection is set while the client has keyboard focus. The
+ data_offer is valid until a new data_offer or NULL is received
+ or until the client loses keyboard focus.
+ </description>
+ <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/>
+ </event>
+ </interface>
+
+ <interface name="wl_data_device_manager" version="1">
+ <description summary="data transfer interface">
+ The wl_data_device_manager is a a singleton global object that
+ provides access to inter-client data transfer mechanisms such as
+ copy and paste and drag and drop. These mechanisms are tied to
+ a wl_seat and this interface lets a client get a wl_data_device
+ corresponding to a wl_seat.
+ </description>
+
+ <request name="create_data_source">
+ <arg name="id" type="new_id" interface="wl_data_source"/>
+ </request>
+
+ <request name="get_data_device">
+ <arg name="id" type="new_id" interface="wl_data_device"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+
+ <interface name="wl_shell" version="1">
+ <request name="get_shell_surface">
+ <arg name="id" type="new_id" interface="wl_shell_surface"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+ </interface>
+
+ <interface name="wl_shell_surface" version="1">
+
+ <description summary="desktop style meta data interface">
+ An interface implemented by a wl_surface. On server side the
+ object is automatically destroyed when the related wl_surface is
+ destroyed. On client side, wl_shell_surface_destroy() must be
+ called before destroying the wl_surface object.
+ </description>
+
+ <request name="pong">
+ <description summary="respond to a ping event">
+ A client must respond to a ping event with a pong request or
+ the client may be deemed unresponsive.
+ </description>
+ <arg name="serial" type="uint"/>
+ </request>
+
+ <request name="move">
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
</request>
<enum name="resize">
</enum>
<request name="resize">
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
- <!-- edges is an enum, need to get the values in here -->
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
<arg name="edges" type="uint"/>
</request>
- <request name="create_drag">
- <arg name="id" type="new_id" interface="wl_drag"/>
+ <request name="set_toplevel">
+ <description summary="make the surface a top level surface">
+ Make the surface a toplevel window.
+ </description>
</request>
- <request name="create_selection">
- <arg name="id" type="new_id" interface="wl_selection"/>
+ <enum name="transient">
+ <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
+ </enum>
+
+ <request name="set_transient">
+ <description summary="make the surface a transient surface">
+ Map the surface relative to an existing surface. The x and y
+ arguments specify the locations of the upper left corner of
+ the surface relative to the upper left corner of the parent
+ surface. The flags argument controls overflow/clipping
+ behaviour when the surface would intersect a screen edge,
+ panel or such. And possibly whether the offset only
+ determines the initial position or if the surface is locked to
+ that relative position during moves.
+ </description>
+
+ <arg name="parent" type="object" interface="wl_surface"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="flags" type="uint"/>
</request>
- <!-- Make the surface visible as a toplevel window. -->
- <request name="set_toplevel">
- <arg name="surface" type="object" interface="wl_surface"/>
+ <request name="set_fullscreen">
+ <description summary="make the surface a fullscreen surface">
+ Map the surface as a fullscreen surface. If an output parameter is
+ given then the surface will be made fullscreen on that output. If the
+ client does not specify the output then the compositor will apply its
+ policy - usually choosing the output on which the surface has the
+ biggest surface area.
+
+ The client may specify a method to resolve a size conflict between the
+ output size and the surface size - this is provided through the
+ fullscreen_method parameter.
+
+ The framerate parameter is used only when the fullscreen_method is set
+ to "driver", to indicate the preferred framerate. framerate=0 indicates
+ that the app does not care about framerate. The framerate is
+ specified in mHz, that is framerate of 60000 is 60Hz.
+
+ The compositor must reply to this request with a configure event with
+ the dimensions for the output on which the surface will be made fullscreen.
+ </description>
+ <arg name="method" type="uint"/>
+ <arg name="framerate" type="uint"/>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request>
- <!-- Map the surface relative to an existing surface. The x and y
- arguments specify the locations of the upper left corner of
- the surface relative to the upper left corner of the parent
- surface. The flags argument controls overflow/clipping
- behaviour when the surface would intersect a screen edge,
- panel or such. And possibly whether the offset only
- determines the initial position or if the surface is locked
- to that relative position during moves. -->
- <request name="set_transient">
- <arg name="surface" type="object" interface="wl_surface"/>
+ <enum name="fullscreen_method">
+ <description summary="different method to set the surface fullscreen">
+ Hints to indicate compositor how to deal with a conflict between the
+ dimensions for the surface and the dimensions of the output. As a hint
+ the compositor is free to ignore this parameter.
+
+ "default" The client has no preference on fullscreen behavior,
+ policies are determined by compositor.
+
+ "scale" The client prefers scaling by the compositor. Scaling would
+ always preserve surface's aspect ratio with surface centered on the
+ output
+
+ "driver" The client wants to switch video mode to the smallest mode
+ that can fit the client buffer. If the sizes do not match the
+ compositor must add black borders.
+
+ "fill" The surface is centered on the output on the screen with no
+ scaling. If the surface is of insufficient size the compositor must
+ add black borders.
+ </description>
+ <entry name="default" value="0"/>
+ <entry name="scale" value="1"/>
+ <entry name="driver" value="2"/>
+ <entry name="fill" value="3"/>
+ </enum>
+
+ <request name="set_popup">
+ <description summary="make the surface a popup surface">
+ Popup surfaces. Will switch an implicit grab into
+ owner-events mode, and grab will continue after the implicit
+ grab ends (button released). Once the implicit grab is over,
+ the popup grab continues until the window is destroyed or a
+ mouse button is pressed in any other clients window. A click
+ in any of the clients surfaces is reported as normal, however,
+ clicks in other clients surfaces will be discarded and trigger
+ the callback.
+
+ TODO: Grab keyboard too, maybe just terminate on any click
+ inside or outside the surface?
+ </description>
+
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="serial" type="uint"/>
<arg name="parent" type="object" interface="wl_surface"/>
<arg name="x" type="int"/>
<arg name="y" type="int"/>
<arg name="flags" type="uint"/>
</request>
- <!-- Map the surface as a fullscreen surface. There are a number
- of options here: on which output? if the surface size doesn't
- match the output size, do we scale, change resolution, or add
- black borders? is that something the client controls? what
- about transient surfaces, do they float on top of the
- fullscreen? what if there's already a fullscreen surface on
- the output, maybe you can only go fullscreen if you're
- active? -->
- <request name="set_fullscreen">
- <arg name="surface" type="object" interface="wl_surface"/>
+ <request name="set_maximized">
+ <description summary="make the surface a maximized surface">
+ A request from the client to notify the compositor the maximized
+ operation. The compositor will reply with a configure event telling
+ the expected new surface size. The operation is completed on the
+ next buffer attach to this surface.
+ A maximized client will fill the fullscreen of the output it is bound
+ to, except the panel area. This is the main difference between
+ a maximized shell surface and a fullscreen shell surface.
+ </description>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
</request>
- <!-- The configure event asks the client to resize its surface.
- The size is a hint, in the sense that the client is free to
- ignore it if it doesn't resize, pick a smaller size (to
- satisfy aspect ration or resize in steps of NxM pixels). The
- client is free to dismiss all but the last configure event it
- received. -->
+ <request name="set_title">
+ <description summary="set surface title">
+ </description>
+ <arg name="title" type="string"/>
+ </request>
+
+ <request name="set_class">
+ <description summary="set surface class">
+ The surface class identifies the general class of applications
+ to which the surface belongs. The class is the file name of
+ the applications .desktop file (absolute path if non-standard
+ location).
+ </description>
+ <arg name="class_" type="string"/>
+ </request>
+
+ <event name="ping">
+ <description summary="ping client">
+ Ping a client to check if it is receiving events and sending
+ requests. A client is expected to reply with a pong request.
+ </description>
+ <arg name="serial" type="uint"/>
+ </event>
+
<event name="configure">
- <arg name="time" type="uint"/>
+ <description summary="suggest resize">
+ The configure event asks the client to resize its surface.
+ The size is a hint, in the sense that the client is free to
+ ignore it if it doesn't resize, pick a smaller size (to
+ satisfy aspect ratio or resize in steps of NxM pixels). The
+ client is free to dismiss all but the last configure event it
+ received.
+ </description>
+
<arg name="edges" type="uint"/>
- <arg name="surface" type="object" interface="wl_surface"/>
<arg name="width" type="int"/>
<arg name="height" type="int"/>
</event>
+
+ <event name="popup_done">
+ <description summary="popup interaction is done">
+ The popup_done event is sent out when a popup grab is broken,
+ that is, when the users clicks a surface that doesn't belong
+ to the client owning the popup surface.
+ </description>
+ </event>
</interface>
- <interface name="wl_selection" version="1">
- <!-- Add an offered mime type. Can be called several times to
- offer multiple types, but must be called before 'activate'. -->
- <request name="offer">
- <arg name="type" type="string"/>
+ <interface name="wl_surface" version="1">
+ <description summary="an onscreen surface">
+ A surface. This is an image that is displayed on the screen.
+ It has a location, size and pixel contents.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="delete surface">
+ Deletes the surface and invalidates its object id.
+ </description>
</request>
- <!-- Can the selection be activated for multiple devices? -->
- <request name="activate">
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
+ <request name="attach">
+ <description summary="set the surface contents">
+ Set the contents of a buffer into this surface. The x and y
+ arguments specify the location of the new pending buffer's upper
+ left corner, relative to the current buffer's upper left corner. In
+ other words, the x and y, and the width and height of the wl_buffer
+ together define in which directions the surface's size changes.
+
+ Surface contents are double-buffered state, see wl_surface.commit.
+
+ The initial surface contents are void; there is no content.
+ wl_surface.attach assigns the given wl_buffer as the pending wl_buffer.
+ wl_surface.commit applies the pending wl_buffer as the new
+ surface contents, and the size of the surface becomes the size of
+ the wl_buffer. The wl_buffer is also kept as pending, until
+ changed by wl_surface.attach or the wl_buffer is destroyed.
+
+ Committing a pending wl_buffer allows the compositor to read the
+ pixels in the wl_buffer. The compositor may access the pixels at any
+ time after the wl_surface.commit request. When the compositor will
+ not access the pixels anymore, it will send the wl_buffer.release
+ event. Only after receiving wl_buffer.release, the client may re-use
+ the wl_buffer. A wl_buffer, that has been attached and then replaced
+ by another attach instead of committed, will not receive a release
+ event, and is not used by the compositor.
+
+ Destroying the wl_buffer after wl_buffer.release does not change the
+ surface contents, even if the wl_buffer is still pending for the
+ next commit. In such case, the next commit does not change the
+ surface contents. However, if the client destroys the wl_buffer
+ before receiving wl_buffer.release, the surface contents become
+ undefined immediately.
+
+ Only if wl_surface.attach is sent with a nil wl_buffer, the
+ following wl_surface.commit will remove the surface content.
+ </description>
+
+ <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
</request>
- <!-- Destroy the selection. -->
- <request name="destroy" type="destructor"/>
-
- <!-- Another client pasted the selection, send the mime-type over
- the passed fd. -->
- <event name="send">
- <arg name="mime_type" type="string"/>
- <arg name="fd" type="fd"/>
- </event>
-
- <!-- Another selection became active. -->
- <event name="cancelled"/>
- </interface>
+ <request name="damage">
+ <description summary="mark part of the surface damaged">
+ This request is used to describe the regions where the pending
+ buffer (or if pending buffer is none, the current buffer as updated
+ in-place) on the next wl_surface.commit will be different from the
+ current buffer, and needs to be repainted. The pending buffer can be
+ set by wl_surface.attach. The compositor ignores the parts of the
+ damage that fall outside of the surface.
+
+ Damage is double-buffered state, see wl_surface.commit.
+
+ The initial value for pending damage is empty: no damage.
+ wl_surface.damage adds pending damage: the new pending damage is the
+ union of old pending damage and the given rectangle.
+ wl_surface.commit assigns pending damage as the current damage, and
+ clears pending damage. The server will clear the current damage as
+ it repaints the surface.
+ </description>
- <interface name="wl_selection_offer" version="1">
- <!-- Called to receive the selection data as the specified type.
- Sends the pipe fd to the compositor, which forwards it to the
- source in the 'send' event -->
- <request name="receive">
- <arg name="mime_type" type="string"/>
- <arg name="fd" type="fd"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
</request>
- <!-- Sent before the keyboard_focus event to announce the types
- offered. One event per offered mime type. A mime type of
- NULL means the selection offer is going away. -->
- <event name="offer">
- <arg name="type" type="string"/>
- </event>
+ <request name="frame">
+ <description summary="request repaint feedback">
+ Request notification when the next frame is displayed. Useful
+ for throttling redrawing operations, and driving animations.
+ The frame request will take effect on the next wl_surface.commit.
+ The notification will only be posted for one frame unless
+ requested again.
+
+ A server should avoid signalling the frame callbacks if the
+ surface is not visible in any way, e.g. the surface is off-screen,
+ or completely obscured by other opaque surfaces.
+
+ A client can request a frame callback even without an attach,
+ damage, or any other state changes. wl_surface.commit triggers a
+ display update, so the callback event will arrive after the next
+ output refresh where the surface is visible.
+ </description>
+
+ <arg name="callback" type="new_id" interface="wl_callback"/>
+ </request>
- <event name="keyboard_focus">
- <arg name="input_device" type="object" interface="wl_input_device"/>
- </event>
- </interface>
+ <request name="set_opaque_region">
+ <description summary="set opaque region">
+ This request sets the region of the surface that contains
+ opaque content. The opaque region is an optimization hint for
+ the compositor that lets it optimize out redrawing of content
+ behind opaque regions. Setting an opaque region is not
+ required for correct behaviour, but marking transparent
+ content as opaque will result in repaint artifacts.
+ The compositor ignores the parts of the opaque region that fall
+ outside of the surface.
+
+ Opaque region is double-buffered state, see wl_surface.commit.
+
+ wl_surface.set_opaque_region changes the pending opaque region.
+ wl_surface.commit copies the pending region to the current region.
+ Otherwise the pending and current regions are never changed.
+
+ The initial value for opaque region is empty. Setting the pending
+ opaque region has copy semantics, and the wl_region object can be
+ destroyed immediately. A nil wl_region causes the pending opaque
+ region to be set to empty.
+ </description>
+
+ <arg name="region" type="object" interface="wl_region" allow-null="true"/>
+ </request>
- <interface name="wl_drag" version="1">
- <!-- Add an offered mime type. Can be called several times to
- offer multiple types, but must be called before 'activate'. -->
- <request name="offer">
- <arg name="type" type="string"/>
+ <request name="set_input_region">
+ <description summary="set input region">
+ This request sets the region of the surface that can receive
+ pointer and touch events. Input events happening outside of
+ this region will try the next surface in the server surface
+ stack. The compositor ignores the parts of the input region that
+ fall outside of the surface.
+
+ Input region is double-buffered state, see wl_surface.commit.
+
+ wl_surface.set_input_region changes the pending input region.
+ wl_surface.commit copies the pending region to the current region.
+ Otherwise the pending and current regions are never changed,
+ except cursor and icon surfaces are special cases, see
+ wl_pointer.set_cursor and wl_data_device.start_drag.
+
+ The initial value for input region is infinite. That means the whole
+ surface will accept input. Setting the pending input region has copy
+ semantics, and the wl_region object can be destroyed immediately. A
+ nil wl_region causes the input region to be set to infinite.
+ </description>
+
+ <arg name="region" type="object" interface="wl_region" allow-null="true"/>
</request>
- <request name="activate">
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="input_device" type="object" interface="wl_input_device"/>
- <arg name="time" type="uint"/>
+ <request name="commit">
+ <description summary="commit pending surface state">
+ Surface state (input, opaque, and damage regions, attached buffers,
+ etc.) is double-buffered. Protocol requests modify the pending
+ state, as opposed to current state in use by the compositor. Commit
+ request atomically applies all pending state, replacing the current
+ state. After commit, the new pending state is as documented for each
+ related request.
+
+ On commit, a pending wl_buffer is applied first, all other state
+ second. This means that all coordinates in double-buffered state are
+ relative to the new wl_buffer coming into use, except for
+ wl_surface.attach itself. If the pending wl_buffer is none, the
+ coordinates are relative to the current surface contents.
+
+ All requests that need a commit to become effective are documented
+ to affect double-buffered state.
+
+ Other interfaces may add further double-buffered surface state.
+ </description>
</request>
- <!-- Destroy the drag and cancel the session. -->
- <request name="destroy" type="destructor"/>
+ <event name="enter">
+ <description summary="surface enters an output">
+ This is emitted whenever a surface's creation, movement, or resizing
+ results in some part of it being within the scanout region of an
+ output.
+ </description>
+ <arg name="output" type="object" interface="wl_output"/>
+ </event>
- <!-- Sent when a target accepts pointer_focus or motion events.
- If a target does not accept any of the offered types, type is
- NULL -->
- <event name="target">
- <arg name="mime_type" type="string"/>
+ <event name="leave">
+ <description summary="surface leaves an output">
+ This is emitted whenever a surface's creation, movement, or resizing
+ results in it no longer having any part of it within the scanout region
+ of an output.
+ </description>
+ <arg name="output" type="object" interface="wl_output"/>
</event>
+ </interface>
- <!-- Sent when the drag is finished. The final mime type is that
- of the last target event. If that was NULL, no drag target
- was valid when the drag finished, fd is undefined and the
- source should not send data. The event is also sent in case
- a drag source tries to activate a drag after the grab was
- released, in which case mime_type will also be NULL. -->
- <event name="finish">
- <arg name="fd" type="fd"/>
+ <interface name="wl_seat" version="1">
+ <description summary="seat">
+ A group of keyboards, pointer (mice, for example) and touch
+ devices . This object is published as a global during start up,
+ or when such a device is hot plugged. A seat typically has a
+ pointer and maintains a keyboard_focus and a pointer_focus.
+ </description>
+
+ <enum name="capability">
+ <description summary="seat capability bitmask">
+ This is a bitmask of capabilities this seat has; if a member is
+ set, then it is present on the seat.
+ </description>
+ <entry name="pointer" value="1" summary="wl_pointer"/>
+ <entry name="keyboard" value="2" summary="wl_keyboard"/>
+ <entry name="touch" value="4" summary="wl_touch"/>
+ </enum>
+
+
+ <event name="capabilities">
+ <description summary="seat capabilities changed">
+ This is emitted whenever a seat gains or loses the pointer,
+ keyboard or touch capabilities. The argument is a wl_seat_caps_mask
+ enum containing the complete set of capabilities this seat has.
+ </description>
+ <arg name="capabilities" type="uint"/>
</event>
- <event name="reject"/>
- </interface>
+ <request name="get_pointer">
+ <description summary="return pointer object">
+ The ID provided will be initialized to the wl_pointer interface
+ for this seat.
+ </description>
+ <arg name="id" type="new_id" interface="wl_pointer"/>
+ </request>
+ <request name="get_keyboard">
+ <description summary="return pointer object">
+ The ID provided will be initialized to the wl_keyboard interface
+ for this seat.
+ </description>
+ <arg name="id" type="new_id" interface="wl_keyboard"/>
+ </request>
- <interface name="wl_drag_offer" version="1">
- <!-- Call to accept the offer of the given type -->
- <request name="accept">
- <arg name="time" type="uint"/>
- <arg name="type" type="string"/>
+ <request name="get_touch">
+ <description summary="return pointer object">
+ The ID provided will be initialized to the wl_touch interface
+ for this seat.
+ </description>
+ <arg name="id" type="new_id" interface="wl_touch"/>
</request>
+ </interface>
- <!-- Called to initiate the drag finish sequence. Sends the pipe
- fd to the compositor, which forwards it to the source in the
- 'finish' event -->
- <request name="receive">
- <arg name="fd" type="fd"/>
+ <interface name="wl_pointer" version="1">
+ <request name="set_cursor">
+ <description summary="set the pointer surface">
+ Set the pointer surface, i.e., the surface that contains the
+ pointer image (cursor). This request only takes effect if the pointer
+ focus for this device is one of the requesting client's surfaces
+ or the surface parameter is the current pointer surface. If
+ there was a previous surface set with this request it is
+ replaced. If surface is NULL, the pointer image is hidden.
+
+ The parameters hotspot_x and hotspot_y define the position of
+ the pointer surface relative to the pointer location. Its
+ top-left corner is always at (x, y) - (hotspot_x, hotspot_y),
+ where (x, y) are the coordinates of the pointer location.
+
+ On surface.attach requests to the pointer surface, hotspot_x
+ and hotspot_y are decremented by the x and y parameters
+ passed to the request. Attach must be confirmed by
+ wl_surface.commit as usual.
+
+ The hotspot can also be updated by passing the currently set
+ pointer surface to this request with new values for hotspot_x
+ and hotspot_y.
+
+ The current and pending input regions of the wl_surface are
+ cleared, and wl_surface.set_input_region is ignored until the
+ wl_surface is no longer used as the cursor. When the use as a
+ cursor ends, the current and pending input regions become
+ undefined, and the wl_surface is unmapped.
+ </description>
+
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="hotspot_x" type="int"/>
+ <arg name="hotspot_y" type="int"/>
</request>
- <!-- Called to reject a drop -->
- <request name="reject"/>
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's pointer is focused on a certain
+ surface. When an seat's focus enters a surface, the pointer image
+ is undefined and a client should respond to this event by setting
+ an appropriate pointer image.
+ </description>
- <!-- Sent before the pointer_focus event to announce the types
- offered. One event per offered mime type. -->
- <event name="offer">
- <arg name="type" type="string"/>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="surface_x" type="fixed"/>
+ <arg name="surface_y" type="fixed"/>
</event>
- <!-- Similar to device::pointer_focus. Sent to potential target
- surfaces to offer drag data. If the device leaves the
- window, the drag stops or the originator cancels the drag,
- this event is sent with the NULL surface, at which point the
- drag object may no longer be valid. -->
- <event name="pointer_focus">
- <arg name="time" type="uint"/>
+ <event name="leave">
+ <description summary="leave event">
+ </description>
+ <arg name="serial" type="uint"/>
<arg name="surface" type="object" interface="wl_surface"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
</event>
- <!-- Similar to device::motion. Sent to potential target surfaces
- as the drag pointer moves around in the surface. -->
<event name="motion">
+ <description summary="pointer motion event">
+ Notification of pointer location change. The arguments surface_[xy]
+ are the location relative to the focused surface.
+ </description>
+
<arg name="time" type="uint"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
+ <arg name="surface_x" type="fixed"/>
+ <arg name="surface_y" type="fixed"/>
</event>
- <!-- Sent to indicate that the drag is finishing. The last
- motion/pointer_focus event gives the location of the drop.
- Target must respond with the 'receive' request, which sends
- an fd to the source for writing the drag data. -->
- <event name="drop"/>
- </interface>
+ <enum name="button_state">
+ <description summary="physical button state">
+ Describes the physical state of a button which provoked the button
+ event.
+ </description>
+ <entry name="released" value="0" summary="button is not pressed"/>
+ <entry name="pressed" value="1" summary="button is pressed"/>
+ </enum>
+ <event name="button">
+ <description summary="pointer button event">
+ Mouse button click and release notifications. The location
+ of the click is given by the last motion or pointer_focus event.
+ </description>
- <!-- A surface. This is an image that is displayed on the screen.
- It has a location, size and pixel contents. Similar to a window. -->
- <interface name="wl_surface" version="1">
- <!-- Deletes the surface and invalidates its object id. -->
- <request name="destroy" type="destructor"/>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint"/>
+ <arg name="button" type="uint"/>
+ <arg name="state" type="uint"/>
+ </event>
- <!-- Copy the contents of a buffer into this surface. The x and y
- arguments specify the location of the new buffers upper left
- corner, relative to the old buffers upper left corner. -->
- <request name="attach">
- <arg name="buffer" type="object" interface="wl_buffer"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- </request>
+ <enum name="axis">
+ <description summary="axis types"/>
+ <entry name="vertical_scroll" value="0"/>
+ <entry name="horizontal_scroll" value="1"/>
+ </enum>
- <!-- After attaching a new buffer, this request is used to
- describe the regions where the new buffer is different from
- the previous buffer and needs to be repainted. Coordinates
- are relative to the new buffer. -->
- <request name="damage">
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
- </request>
- </interface>
+ <event name="axis">
+ <description summary="axis event">
+ Scroll and other axis notifications.
+ For scroll events (vertical and horizontal scroll axes), the
+ value parameter is the length of a vector along the specified
+ axis in a coordinate space identical to those of motion events,
+ representing a relative movement along the specified axis.
- <!-- A group of keyboards and pointer devices (mice, for
- example). This object is published as a global during start up,
- or when such a device is hot plugged. A input_device group
- typically has a pointer and maintains a keyboard_focus and a
- pointer_focus. -->
- <interface name="wl_input_device" version="1">
- <!-- Set the pointer's image. This request only takes effect if
- the pointer focus for this device is one of the requesting
- clients surfaces. -->
- <request name="attach">
- <arg name="time" type="uint"/>
- <arg name="buffer" type="object" interface="wl_buffer"/>
- <arg name="hotspot_x" type="int"/>
- <arg name="hotspot_y" type="int"/>
- </request>
+ For devices that support movements non-parallel to axes multiple
+ axis events will be emitted.
+
+ When applicable, for example for touch pads, the server can
+ choose to emit scroll events where the motion vector is
+ equivalent to a motion event vector.
+
+ When applicable, clients can transform its view relative to the
+ scroll distance.
+ </description>
- <!-- Notification of pointer location change.
- x,y are the absolute location on the screen.
- surface_[xy] are the location relative to the focused surface. -->
- <event name="motion">
<arg name="time" type="uint"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
+ <arg name="axis" type="uint"/>
+ <arg name="value" type="fixed"/>
</event>
+ </interface>
- <!-- Mouse button click and release notifications. The location
- of the click is given by the last motion or pointer_focus
- event. -->
- <event name="button">
- <arg name="time" type="uint"/>
- <arg name="button" type="uint"/>
- <arg name="state" type="uint"/>
+ <interface name="wl_keyboard" version="1">
+ <description summary="keyboard input device">
+ </description>
+
+ <enum name="keymap_format">
+ <description summary="keyboard mapping format">
+ This enum specifies the format of the keymap provided to the client
+ with the wl_keyboard::keymap event.
+ </description>
+ <entry name="xkb_v1" value="1" description="libxkbcommon compatible"/>
+ </enum>
+
+ <event name="keymap">
+ <description summary="keyboard mapping">
+ This event provides a file descriptor to the client which can be
+ memory-mapped to provide a keyboard mapping description.
+ </description>
+ <arg name="format" type="uint"/>
+ <arg name="fd" type="fd"/>
+ <arg name="size" type="uint"/>
+ </event>
+
+ <event name="enter">
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="keys" type="array"/>
</event>
- <!-- Keyboard press. -->
+ <event name="leave">
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <enum name="key_state">
+ <description summary="physical key state">
+ Describes the physical state of a key which provoked the key event.
+ </description>
+ <entry name="released" value="0" summary="key is not pressed"/>
+ <entry name="pressed" value="1" summary="key is pressed"/>
+ </enum>
+
<event name="key">
+ <description summary="key event">
+ A key was pressed or released.
+ </description>
+
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="key" type="uint"/>
<arg name="state" type="uint"/>
</event>
- <!-- Notification that this input device's pointer is focused on
- certain surface. When an input_device enters a surface, the
- pointer image is undefined and a client should respond to
- this event by setting an apropriate pointer image. -->
- <event name="pointer_focus">
- <arg name="time" type="uint"/>
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="surface_x" type="int"/>
- <arg name="surface_y" type="int"/>
+ <event name="modifiers">
+ <description summary="modifier and group state">
+ Notifies clients that the modifier and/or group state has
+ changed, and it should update its local state.
+ </description>
+
+ <arg name="serial" type="uint"/>
+ <arg name="mods_depressed" type="uint"/>
+ <arg name="mods_latched" type="uint"/>
+ <arg name="mods_locked" type="uint"/>
+ <arg name="group" type="uint"/>
</event>
+ </interface>
- <event name="keyboard_focus">
- <arg name="time" type="uint"/>
- <arg name="surface" type="object" interface="wl_surface"/>
- <arg name="keys" type="array"/>
- </event>
+ <interface name="wl_touch" version="1">
+ <description summary="touch screen input device">
+ </description>
- <event name="touch_down">
+ <event name="down">
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
<arg name="id" type="int" />
- <arg name="x" type="int" />
- <arg name="y" type="int" />
+ <arg name="x" type="fixed" />
+ <arg name="y" type="fixed" />
</event>
- <event name="touch_up">
+ <event name="up">
+ <arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="id" type="int" />
</event>
- <event name="touch_motion">
+ <event name="motion">
<arg name="time" type="uint"/>
<arg name="id" type="int" />
- <arg name="x" type="int" />
- <arg name="y" type="int" />
+ <arg name="x" type="fixed" />
+ <arg name="y" type="fixed" />
</event>
- <!-- Indicates the end of a contact point list. -->
- <event name="touch_frame"/>
+ <event name="frame">
+ <description summary="end of touch frame event">
+ Indicates the end of a contact point list.
+ </description>
+ </event>
- <!-- Sent if the compositor decides the touch stream is a global
- gesture. No further events are sent to the clients from that
- particular gesture. -->
- <event name="touch_cancel"/>
+ <event name="cancel">
+ <description summary="touch session cancelled">
+ Sent if the compositor decides the touch stream is a global
+ gesture. No further events are sent to the clients from that
+ particular gesture.
+ </description>
+ </event>
</interface>
- <!-- An output describes part of the compositor geometry. The
- compositor work in the 'compositor coordinate system' and an
- output corresponds to rectangular area in that space that is
- actually visible. This typically corresponds to a monitor that
- displays part of the compositor space. This object is
- published as global during start up, or when a screen is hot
- plugged. -->
<interface name="wl_output" version="1">
+ <description summary="compositor output region">
+ An output describes part of the compositor geometry. The
+ compositor work in the 'compositor coordinate system' and an
+ output corresponds to rectangular area in that space that is
+ actually visible. This typically corresponds to a monitor that
+ displays part of the compositor space. This object is published
+ as global during start up, or when a screen is hot plugged.
+ </description>
<enum name="subpixel">
<entry name="unknown" value="0"/>
<entry name="vertical_bgr" value="5"/>
</enum>
+ <enum name="transform">
+ <description summary="transform from framebuffer to output">
+ This describes the transform that a compositor will apply to a
+ surface to compensate for the rotation or mirroring of an
+ output device.
+
+ The flipped values correspond to an initial flip around a
+ vertical axis followed by rotation.
+
+ The purpose is mainly to allow clients render accordingly and
+ tell the compositor, so that for fullscreen surfaces, the
+ compositor will still be able to scan out directly from client
+ surfaces.
+ </description>
+
+ <entry name="normal" value="0"/>
+ <entry name="90" value="1"/>
+ <entry name="180" value="2"/>
+ <entry name="270" value="3"/>
+ <entry name="flipped" value="4"/>
+ <entry name="flipped_90" value="5"/>
+ <entry name="flipped_180" value="6"/>
+ <entry name="flipped_270" value="7"/>
+ </enum>
+
<event name="geometry">
- <arg name="x" type="int"/>
- <arg name="y" type="int"/>
- <arg name="physical_width" type="int"/>
- <arg name="physical_height" type="int"/>
- <arg name="subpixel" type="int"/>
- <arg name="make" type="string"/>
- <arg name="model" type="string"/>
+ <description summary="properties of the output"/>
+ <arg name="x" type="int"
+ summary="x position within the global compositor space"/>
+ <arg name="y" type="int"
+ summary="y position within the global compositor space"/>
+ <arg name="physical_width" type="int"
+ summary="width in millimeters of the output"/>
+ <arg name="physical_height" type="int"
+ summary="height in millimeters of the output"/>
+ <arg name="subpixel" type="int"
+ summary="subpixel orientation of the output"/>
+ <arg name="make" type="string"
+ summary="textual description of the manufacturer"/>
+ <arg name="model" type="string"
+ summary="textual description of the model"/>
+ <arg name="transform" type="int"
+ summary="transform that maps framebuffer to output"/>
</event>
- <!-- Values for the flags bitfield of the mode event. -->
<enum name="mode">
- <entry name="current" value="0x1"/>
- <entry name="preferred" value="0x2"/>
+ <description summary="values for the flags bitfield in the mode event"/>
+ <entry name="current" value="0x1"
+ summary="indicates this is the current mode"/>
+ <entry name="preferred" value="0x2"
+ summary="indicates this is the preferred mode"/>
</enum>
<event name="mode">
- <arg name="flags" type="uint"/>
- <arg name="width" type="int"/>
- <arg name="height" type="int"/>
- <arg name="refresh" type="int"/>
+ <description summary="advertise available modes for the output">
+ The mode event describes an available mode for the output.
+ The event is sent when binding to the output object and there
+ will always be one mode, the current mode. The event is sent
+ again if an output changes mode, for the mode that is now
+ current. In other words, the current mode is always the last
+ mode that was received with the current flag set.
+ </description>
+ <arg name="flags" type="uint" summary="mask of wl_output_mode flags"/>
+ <arg name="width" type="int" summary="width of the mode in pixels"/>
+ <arg name="height" type="int" summary="height of the mode in pixels"/>
+ <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
</event>
</interface>
+ <interface name="wl_region" version="1">
+ <description summary="region interface">
+ Region.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy region">
+ Destroy the region. This will invalidate the object id.
+ </description>
+ </request>
+
+ <request name="add">
+ <description summary="add rectangle to region">
+ Add the specified rectangle to the region
+ </description>
- <!-- A visual is the pixel format. The different visuals are
- currently only identified by the order they are advertised by
- the 'global' events. We need something better. -->
- <interface name="wl_visual" version="1"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="subtract">
+ <description summary="subtract rectangle from region">
+ Subtract the specified rectangle from the region
+ </description>
+
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ </interface>
</protocol>