[PATCH] doc: Update drag and drop section and add info about selections
Kristian Høgsberg
hoegsberg at gmail.com
Wed Oct 10 13:45:39 PDT 2012
On Wed, Oct 10, 2012 at 11:29:13PM +0300, Ander Conselvan de Oliveira wrote:
> From: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira at intel.com>
>
> 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
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list