From: Matthias Clasen Date: Sat, 30 Mar 2013 05:11:31 +0000 (-0400) Subject: doc: Improve various sections of the documentation X-Git-Tag: 1.0.90~53 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=390e7a7a42adce1ae93f83921c5d74b46ac4064d;p=platform%2Fupstream%2Fwayland.git doc: Improve various sections of the documentation --- diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml index 955b054..9bc8232 100644 --- a/doc/Wayland/en_US/Protocol.xml +++ b/doc/Wayland/en_US/Protocol.xml @@ -196,19 +196,10 @@
Creating Objects - - - - client allocates object ID, uses range protocol - - - - - server tracks how many IDs are left in current range, sends - new range when client is about to run out. - - - + Each object has a unique ID. The IDs are allocated by the + client, from a range of IDs. The server tracks how many + IDs are left in the current range and sends a new range + when the client is about to run out.
@@ -222,24 +213,22 @@
- Surface + Surfaces - Created by the client. + Surfaces are created by the client. See for the protocol description. - - Needs a way to set input region, opaque region. -
Input - Represents a group of input devices, including mice, keyboards. Has a - keyboard and pointer focus. Global object. Pointer events are - delivered in both screen coordinates and surface local coordinates. + A seat represents a group of input devices including mice, + keyboards and touchscreens. It has a keyboard and pointer + focus. Seats are global objects. Pointer events are delivered + in surface local coordinates. See for the @@ -331,21 +320,23 @@
- Data sharing between client (selection and drag and drop) + Data sharing between clients - The Wayland 1.0 protocol provides its clients a mechanism for sharing - data that allows the implementation of selection and drag and drop. - The client providing the data creates a wl_data_source object and the - clients obtaining the data will see it as wl_data_offer object. This - interface allows the clients to agree on a mutually supported mime type - and transfer the data through an fd that is passed through the protocol. + The Wayland protocol provides clients a mechanism for sharing + data that allows the implementation of copy-paste and + drag-and-drop. The client providing the data creates a + wl_data_source object and the clients + obtaining the data will see it as wl_data_offer + object. This interface allows the clients to agree on a mutually + supported mime type and transfer the data via a file descriptor + that is passed through the protocol. - The next section explains the negotiation between data source and data - offer objects. - explains how these objects are created and passed to different client - using the wl_data_device interface, that implements selection and drag - and drop support. + The next section explains the negotiation between data source and + data offer objects. + explains how these objects are created and passed to different + clients using the wl_data_device interface + that implements copy-paste and drag-and-drop support. See , @@ -363,7 +354,7 @@
Data negotiation - A client providing data to other clients will create a wl_data_source + A client providing data to other clients will create a wl_data_source object and advertise the mime types for the formats it supports for that data through the wl_data_source.offer request. On the receiving end, the data offer object will generate one @@ -373,18 +364,18 @@ The actual data transfer happens when the receiving client sends a wl_data_offer.receive request. This request takes - a mime type and an fd as arguments. This request will generate a + a mime type and a file descriptor as arguments. This request will generate a wl_data_source.send event on the sending client with the same arguments, and the latter client is expected to write its - data to the given fd using the chosen mime type. + data to the given file descriptor using the chosen mime type.
Data devices Data devices glue data sources and offers together. A data device is - associated with a wl_seat and is obtained by the clients using the - wl_data_device_manager factory object, which is also responsible for + associated with a wl_seat and is obtained by the clients using the + wl_data_device_manager factory object, which is also responsible for creating data sources. @@ -392,7 +383,7 @@ wl_data_device.data_offer event. After this event is generated the data offer will advertise the available mime types. New data offers are introduced prior to their use for - selection or drag and drop. + copy-paste or drag-and-drop.
Selection @@ -414,7 +405,7 @@
Drag and Drop - A drag and drop operation is started using the + A drag-and-drop operation is started using the wl_data_device.start_drag request. This requests causes a pointer grab that will generate enter, motion and leave events on the data device. A data source is supplied as