Drag and Drop

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

Issues:

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?
Should drag.send() destroy the object? There's nothing to do after the data has been transferred.
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.
Middle-click drag to pop up menu? Ctrl/Shift/Alt drag?
Send a file descriptor over the protocol to let initiator and source exchange data out of band?
Action? Specify action when creating the drag object? Ask action?

New objects, requests and events:

New toplevel dnd global. One method, creates a drag object: dnd.start(new object id, surface, input device, mime types). Starts drag for the device, if it's grabbed by the surface. drag ends when button is released. Caller is responsible for destroying the drag object.
Drag object methods:
drag.destroy(id), destroy drag object.
drag.send(id, data), send drag data.
drag.accept(id, mime type), accept drag offer, called by target surface.
Drag object events:
drag.offer(id, mime-types), sent to potential destination surfaces to offer drag data. If the device leaves the window or the originator cancels the drag, this event is sent with mime-types = NULL.
drag.target(id, mime-type), sent to drag originator when a target surface has accepted the offer. if a previous target goes away, this event is sent with mime-type = NULL.
drag.data(id, data), sent to target, contains dragged data. ends transaction on the target side.

Sequence of events:

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.
The initiator creates a drag object by calling the create_drag method on the dnd global object. As for any client created object, the client allocates the id. The create_drag 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.
The special mime-type application/x-root-target indicates that the initiator is looking for drag events to the root window as well.
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.
As long as the grab is active (or until the initiator cancels the drag by destroying the drag object), the drag object will send offer 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 offer event with an empty list of mime-types to indicate that the device left the surface.
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 accept 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 offer 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.
When a target surface sends an accept request, the drag object will send a target 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 target event with a NULL mime-type will be sent.
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 target event with the application/x-root-target mime-type.
When the grab is released (indicated by the button release event), if the drag has an active target, the initiator calls the send 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 destroy method.
The drop target receives a data event from the drag object with the requested data.

MIME is defined in RFC's 2045-2049. A registry of MIME types is maintained by the Internet Assigned Numbers Authority (IANA).

ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/

root 2012-01-26