- 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>