On Wed, Oct 10, 2012 at 11:29:13PM +0300, Ander Conselvan de Oliveira wrote: > From: Ander Conselvan de Oliveira <[email protected]> > > Replace the outdated section about drag and drop support with a > rewritten section covering the data source/offer mechanism and > wl_data_device, explaining how selection and drag ang drop works.
Thanks Ander, that was long overdue :) Kristian > --- > doc/Wayland/en_US/Protocol.xml | 259 > +++++++++++++++------------------------- > 1 file changed, 99 insertions(+), 160 deletions(-) > > diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml > index 1c22e0e..b5cd7a1 100644 > --- a/doc/Wayland/en_US/Protocol.xml > +++ b/doc/Wayland/en_US/Protocol.xml > @@ -341,171 +341,29 @@ > </listitem> > </itemizedlist> > </section> > - <section id="sect-Protocol-Drag-and-Drop"> > - <title>Drag and Drop</title> > + <section id="sect-Protocol-data-sharing"> > + <title>Data sharing between client (selection and drag and drop)</title> > <para> > - Multi-device aware. Orthogonal to rest of wayland, as it is its own > - toplevel object. Since the compositor determines the drag target, it > - works with transformed surfaces (dragging to a scaled down window in > - expose mode, for example). > + 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. > </para> > <para> > - See <xref linkend="protocol-spec-interface-wl_data_offer"/>, > - <xref linkend="protocol-spec-interface-wl_data_source"/> and > - <xref linkend="protocol-spec-interface-wl_data_offer"/> for > - protocol descriptions. > + The next section explains the negotiation between data source and data > + offer objects. <xref linkend="sect-Protocol-data-sharing-devices"/> > + 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. > </para> > <para> > - Issues: > - <itemizedlist> > - <listitem> > - <para> > - we can set the cursor image to the current cursor + dragged > - object, which will last as long as the drag, but maybe an request to > - attach an image to the cursor will be more convenient? > - </para> > - </listitem> > - <listitem> > - <para> > - Should drag.send() destroy the object? There's nothing to do > - after the data has been transferred. > - </para> > - </listitem> > - <listitem> > - <para> > - How do we marshal several mime-types? We could make the drag > - setup a multi-step operation: dnd.create, drag.offer(mime-type1), > - drag.offer(mime-type2), drag.activate(). The drag object could send > - multiple offer events on each motion event. Or we could just > - implement an array type, but that's a pain to work with. > - </para> > - </listitem> > - <listitem> > - <para> > - Middle-click drag to pop up menu? Ctrl/Shift/Alt drag? > - </para> > - </listitem> > - <listitem> > - <para> > - Send a file descriptor over the protocol to let initiator and > - source exchange data out of band? > - </para> > - </listitem> > - <listitem> > - <para> > - Action? Specify action when creating the drag object? Ask > - action? > - </para> > - </listitem> > - </itemizedlist> > - </para> > - <para> > - Sequence of events: > - <orderedlist> > - <listitem> > - <para> > - The initiator surface receives a click (which grabs the input > - device to that surface) and then enough motion to decide that a drag > - is starting. Wayland has no subwindows, so it's entirely up to the > - application to decide whether or not a draggable object within the > - surface was clicked. > - </para> > - </listitem> > - <listitem> > - <para> > - The initiator creates a drag object by calling the > - <function>create_drag</function> method on the dnd global > - object. As for any client created object, the client allocates > - the id. The <function>create_drag</function> method also takes > - the originating surface, the device that's dragging and the > - mime-types supported. If the surface > - has indeed grabbed the device passed in, the server will create an > - active drag object for the device. If the grab was released in the > - meantime, the drag object will be in-active, that is, the same state > - as when the grab is released. In that case, the client will receive > - a button up event, which will let it know that the drag finished. > - To the client it will look like the drag was immediately cancelled > - by the grab ending. > - </para> > - <para> > - The special mime-type application/x-root-target indicates that the > - initiator is looking for drag events to the root window as well. > - </para> > - </listitem> > - <listitem> > - <para> > - To indicate the object being dragged, the initiator can replace > - the pointer image with an larger image representing the data being > - dragged with the cursor image overlaid. The pointer image will > - remain in place as long as the grab is in effect, since the > - initiating surface keeps pointer focus, and no other surface > - receives enter events. > - </para> > - </listitem> > - <listitem> > - <para> > - As long as the grab is active (or until the initiator cancels > - the drag by destroying the drag object), the drag object will send > - <function>offer</function> events to surfaces it moves across. As > for motion > - events, these events contain the surface local coordinates of the > - device as well as the list of mime-types offered. When a device > - leaves a surface, it will send an <function>offer</function> event > with an empty > - list of mime-types to indicate that the device left the surface. > - </para> > - </listitem> > - <listitem> > - <para> > - If a surface receives an offer event and decides that it's in an > - area that can accept a drag event, it should call the > - <function>accept</function> method on the drag object in the event. > The surface > - passes a mime-type in the request, picked from the list in the offer > - event, to indicate which of the types it wants. At this point, the > - surface can update the appearance of the drop target to give > - feedback to the user that the drag has a valid target. If the > - <function>offer</function> event moves to a different drop target > (the surface > - decides the offer coordinates is outside the drop target) or leaves > - the surface (the offer event has an empty list of mime-types) it > - should revert the appearance of the drop target to the inactive > - state. A surface can also decide to retract its drop target (if the > - drop target disappears or moves, for example), by calling the accept > - method with a NULL mime-type. > - </para> > - </listitem> > - <listitem> > - <para> > - When a target surface sends an <function>accept</function> request, > the drag > - object will send a <function>target</function> event to the > initiator surface. > - This tells the initiator that the drag currently has a potential > - target and which of the offered mime-types the target wants. The > - initiator can change the pointer image or drag source appearance to > - reflect this new state. If the target surface retracts its drop > - target of if the surface disappears, a <function>target</function> > event with a > - NULL mime-type will be sent. > - </para> > - <para> > - If the initiator listed application/x-root-target as a valid > - mime-type, dragging into the root window will make the drag object > - send a <function>target</function> event with the > application/x-root-target > - mime-type. > - </para> > - </listitem> > - <listitem> > - <para> > - When the grab is released (indicated by the button release > - event), if the drag has an active target, the initiator calls the > - <function>send</function> method on the drag object to send the > data to be > - transferred by the drag operation, in the format requested by the > - target. The initiator can then destroy the drag object by calling > - the <function>destroy</function> method. > - </para> > - </listitem> > - <listitem> > - <para> > - The drop target receives a <function>data</function> event from the > drag > - object with the requested data. > - </para> > - </listitem> > - </orderedlist> > + See <xref linkend="protocol-spec-interface-wl_data_offer"/>, > + <xref linkend="protocol-spec-interface-wl_data_source"/>, > + <xref linkend="protocol-spec-interface-wl_data_device"/> and > + <xref linkend="protocol-spec-interface-wl_data_device_manager"/> for > + protocol descriptions. > </para> > <para> > MIME is defined in RFC's 2045-2049. A > @@ -513,5 +371,86 @@ > registry of MIME types</ulink> is maintained by the Internet Assigned > Numbers Authority (IANA). > </para> > + <section> > + <title>Data negotiation</title> > + <para> > + 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 <function>wl_data_source.offer</function> > + request. On the receiving end, the data offer object will generate one > + <function>wl_data_offer.offer</function> event for each supported mime > + type. > + </para> > + <para> > + The actual data transfer happens when the receiving client sends a > + <function>wl_data_offer.receive</function> request. This request takes > + a mime type and an fd as arguments. This request will generate a > + <function>wl_data_source.send</function> 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. > + </para> > + </section> > + <section id="sect-Protocol-data-sharing-devices"> > + <title>Data devices</title> > + <para> > + 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 > + creating data sources. > + </para> > + <para> > + Clients are informed of new data offers through the > + <function>wl_data_device.data_offer</function> 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. > + </para> > + <section> > + <title>Selection</title> > + <para> > + Each data device has a selection data source. Clients create a data > + source object using the device manager and may set it as the > + current selection for a given data device. Whenever the current > + selection changes, the client with keyboard focus receives a > + <function>wl_data_device.selection</function> event. This event is > + also generated on a client immediately before it receives keyboard > + focus. > + </para> > + <para> > + The data offer is introduced with > + <function>wl_data_device.data_offer</function> event before the > + selection event. > + </para> > + </section> > + <section> > + <title>Drag and Drop</title> > + <para> > + A drag and drop operation is started using the > + <function>wl_data_device.start_drag</function> 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 > + argument to start_drag, and data offers associated with it are > + supplied to clients surfaces under the pointer in the > + <function>wl_data_device.enter</function> event. The data offer > + is introduced to the client prior to the enter event with the > + <function>wl_data_device.data_offer</function> event. > + </para> > + <para> > + Clients are expected to provide feedback to the data sending client > + by calling the <function>wl_data_offer.accept</function> request with > + a mime type it accepts. If none of the advertised mime types is > + supported by the receiving client, it should supply NULL to the > + accept request. The accept request causes the sending client to > + receive a <function>wl_data_source.target</function> event with the > + chosen mime type. > + </para> > + <para> > + When the drag ends, the receiving client receives a > + <function>wl_data_device.drop</function> event at which it is expect > + to trasnfer the data using the > + <function>wl_data_offer.receive</function> request. > + </para> > + </section> > + </section> > </section> > </chapter> > -- > 1.7.9.5 > > _______________________________________________ > wayland-devel mailing list > [email protected] > http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
