Improve documentation on what callers of `x-begin-drag' should do

* doc/lispref/frames.texi (Drag and Drop):
* src/xfns.c (Fx_begin_drag): Improve documentation of how the
chosen action should be performed.

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index e87e247496745d3ad5d4775e8a660e70fdd24072..20e9c17f1f9465367d894226b63a326ed1c9c766 100644 (file)
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4106,6 +4106,10 @@ is also a valid return value in addition to @code{XdndActionCopy} and
 @code{XdndActionMove}; it means that the drop target chose to perform
 an unspecified action, and no further processing is required by the
 caller.
+
+The caller must cooperate with the target to fully perform the action
+chosen by the target.  For example, callers should delete the buffer
+text that was dragged if this function returns @code{XdndActionMove}.
 @end defun
 
 @node Color Names

diff --git a/src/xfns.c b/src/xfns.c
index 60b22ff145d149a16f0de12a4141906be0a50020..9f218d2b7fe038726a18bcfc37104eebe54d993b 100644 (file)
--- a/src/xfns.c
+++ b/src/xfns.c
@@ -6792,8 +6792,9 @@ buttons are released, then return the action chosen by the target, or
 starts when the mouse is pressed on FRAME, and the contents of the
 selection `XdndSelection' will be sent to the X window underneath the
 mouse pointer (the drop target) when the mouse button is released.
-ACTION is a symbol which tells the target what the source will do, and
-can be one of the following:
+
+ACTION is a symbol which tells the target what it should do, and can
+be one of the following:
 
  - `XdndActionCopy', which means to copy the contents from the drag
    source (FRAME) to the drop target.
@@ -6805,6 +6806,10 @@ can be one of the following:
 `XdndActionPrivate' is also a valid return value, and means that the
 drop target chose to perform an unspecified or unknown action.
 
+The source is also expected to cooperate with the target to perform
+the action chosen by the target.  For example, callers should delete
+the buffer text that was dragged if `XdndActionMove' is returned.
+
 There are also some other valid values of ACTION that depend on
 details of both the drop target's implementation details and that of
 Emacs.  For that reason, they are not mentioned here.  Consult