Carlos Garnacho authored Jan 15, 2016 and Jonas Ådahl committed Jan 16, 2016

Currently, there's no means for the DnD origin to know whether the
destination is actually finished with the DnD transaction, short of
finalizing it after the first transfer finishes, or leaking it forever.

But this poses other interoperation problems, drag destinations might
be requesting several mimetypes at once, might be just poking to find
out the most suitable format, might want to defer the action to a popup,
might be poking contents early before the selection was dropped...

In addition, data_source.cancelled is suitable for the situations where
the DnD operation fails (not on a drop target, no matching mimetypes,
etc..), but seems undocumented for that use (and unused in weston's DnD).

In order to improve the situation, the drag source should be notified
of all stages of DnD. In addition to documenting the "cancelled" event
for DnD purposes, The following 2 events have been added:

- wl_data_source.dnd_drop_performed: Happens when the operation has been
  physically finished (eg. the button is released), it could be the right
  place to reset the pointer cursor back and undo any other state resulting
  from the initial button press.
- wl_data_source.dnd_finished: Happens when the destination side destroys
  the wl_data_offer, at this point the source can just forget all data
  related to the DnD selection as well, plus optionally deleting the data
  on move operations.

Changes since v6:
  - Turned wl_data_offer.finish calls with 0/NULL state/mimetype an
    error, made it explicit that it will only result in
    wl_data_offer.dnd_finished being sent if successful.

Changes since v5:
  - Further rewording of wl_data_offer.finish and wl_data_offer.accept.
    Added error for untimely wl_data_offer.finish requests.

Changes since v4:
  - Applied rewording suggestions from Jonas Ådahl. Added new
    wl_data_offer.finish request to allow explicit finalization on the
    destination side.

Changes since v3:
  - Renamed dnd_performed to a more descriptive dnd_drop_performed,
    documented backwards compatible behavior on wl_data_offer.accept and
    wl_data_source.cancelled.

Changes since v2:
  - Minor rewording.

Changes since v1:
  - Renamed events to have a common "dnd" namespace. Made dnd_performed to
    happen invariably, data_device.cancelled may still happen afterwards.

Signed-off-by: Carlos Garnacho <carlosg@gnome.org>
Reviewed-by: Michael Catanzaro <mcatanzaro@igalia.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Mike Blumenkrantz <zmike@samsung.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>