From 65eef9d817d3db2ae7c61cd02075d46cf7bd9f90 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Kristian=20H=C3=B8gsberg?= Date: Sun, 21 Oct 2012 22:08:08 -0400 Subject: [PATCH] wayland: Add protocol documentation for various interfaces --- protocol/wayland.xml | 107 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 94 insertions(+), 13 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 019816d..6171670 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -44,13 +44,23 @@ + + This request creates a registry object that allows the client + to list and bind the global objects available from the + compositor. + The error event is sent out when a fatal (non-recoverable) - error has occurred. + 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. @@ -72,13 +82,39 @@ - Server has deleted the id and client can now reuse it. + 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 + + 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 + regitry. 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. + + Binds a new, client-created object to the server using @name as @@ -90,14 +126,7 @@ - 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. 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. + Notify the client of global objects. @@ -106,7 +135,13 @@ - Notify the client of removed global objects. + 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. @@ -262,6 +297,15 @@ + + 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. + + Indicate that the client can accept the given mime-type, or @@ -273,6 +317,16 @@ + + 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. + @@ -290,6 +344,13 @@ + + 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. + + This request adds a mime-type to the set of mime-types @@ -326,7 +387,8 @@ - Another selection became active. + This data source has been replaced by another data source. + The client should clean up and destroy this data source. @@ -387,6 +449,13 @@ + + 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. + + @@ -394,9 +463,21 @@ - + + + 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. + + + + 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. + -- 2.7.4