Improve DND documentation

* doc/lispref/frames.texi (Drag and Drop):
* src/xfns.c (Fx_begin_drag): Document that x-begin-drag may
return immediately if no mouse buttons are held down.

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index e8765cf958e8ad7c11faacf17f0b667c69859470..e87e247496745d3ad5d4775e8a660e70fdd24072 100644 (file)
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4067,7 +4067,9 @@ drag-and-drop operation ends, either because the drop was successful,
 or because the drop was rejected.  The drop occurs when all mouse
 buttons are released on top of an X window other than @var{frame} (the
 @dfn{drop target}), or any X window if @var{allow-current-frame} is
-non-@code{nil}.
+non-@code{nil}.  If no mouse buttons are held down when the
+drag-and-drop operation begins, this function may immediately return
+@code{nil}.
 
 @var{targets} is a list of strings describing selection targets, much
 like the @var{data-type} argument to @code{gui-get-selection}, that

diff --git a/src/xfns.c b/src/xfns.c
index 47321a1d6b2b83c90a9b46c4b2ddf63405ce1eba..4b5d30bca256c7c7d4fa510d070f0b253cc5b2e9 100644 (file)
--- a/src/xfns.c
+++ b/src/xfns.c
@@ -6827,7 +6827,12 @@ instead.
 
 If ALLOW-CURRENT-FRAME is not specified or nil, then the drop target
 is allowed to be FRAME.  Otherwise, no action will be taken if the
-mouse buttons are released on top of FRAME.  */)
+mouse buttons are released on top of FRAME.
+
+This function will sometimes return immediately if no mouse buttons
+are currently held down, and should only be called in situations where
+it is known that some are being held down down, such as immediately
+after a `down-mouse-1' event.  */)
   (Lisp_Object targets, Lisp_Object action, Lisp_Object frame,
    Lisp_Object return_frame, Lisp_Object allow_current_frame)
 {