From: Eli Zaretskii Date: Fri, 3 Jun 2022 11:50:11 +0000 (+0300) Subject: ; Improve documentation of new drag-and-drop APIs X-Git-Tag: emacs-29.0.90~1910^2~261 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=dc7623a59e5e90d310cb1c338790a3df5f90e891;p=emacs.git ; Improve documentation of new drag-and-drop APIs * lisp/dnd.el (dnd-begin-text-drag, dnd-begin-file-drag): * doc/lispref/frames.texi (Drag and Drop): Improve wording of documentation of 'dnd-begin-text-drag' and 'dnd-begin-file-drag'. --- diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 33592e75041..9f7666ac63c 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -4094,36 +4094,19 @@ specific drag-n-drop protocol being used. Plain text may be On capable window systems, Emacs also supports dragging contents from its frames to windows of other applications. +@cindex drop target, in drag-and-drop operations @defun dnd-begin-text-drag text &optional frame action allow-same-frame This function begins dragging text from @var{frame} to another program -(the drop target), and returns until it is dropped or the -drag-and-drop operation is cancelled. - -The return value is the action that the drop target actually -performed, which can be one of the following symbols: - -@table @code -@item copy -The drop target inserted @var{text}. - -@item move -The drop target inserted @var{text}, but in addition the caller should -delete @var{text} from wherever it originated, such as a buffer. - -@item private -The drop target performed an unspecified action. -@end table - -@code{nil} can also be returned if the drag-and-drop operation was -cancelled. - -@var{text} is the text that will be inserted by the drop target. +(known as the @dfn{drop target}), and returns the result of +drag-and-drop operation when the text is dropped or the drag-and-drop +operation is canceled. @var{text} is the text that will be inserted +by the drop target. @var{action} must be one of the symbols @code{copy} or @code{move}, where @code{copy} means that @var{text} should be inserted by the drop target, and @code{move} means the same as @code{copy}, but in addition the caller may have to delete @var{text} from its source as explained -above. +below. @var{frame} is the frame where the mouse is currently held down, or @code{nil}, which means to use the selected frame. This function may @@ -4133,13 +4116,46 @@ only called immediately after a @code{down-mouse-1} or similar event event was generated (@pxref{Click Events}). @var{allow-same-frame} specifies whether or not drops on top of -@var{frame} itself won't be ignored. +@var{frame} itself are to be ignored. + +The return value specifies the action that the drop target actually +performed, and optionally what the caller should do. It can be one of +the following symbols: + +@table @code +@item copy +The drop target inserted the dropped text. + +@item move +The drop target inserted the dropped text, but in addition the caller +should delete @var{text} from wherever it originated, such as its +buffer. + +@item private +The drop target performed some other unspecified action. + +@item nil +The drag-and-drop operation was canceled. +@end table + @end defun @defun dnd-begin-file-drag file &optional frame action allow-same-frame This function begins dragging @var{file} from @var{frame} to another -program, and returns until it is dropped or the drag-and-drop -operation is cancelled. +program, and returns the result of the drag-and-drop operation when +the file is dropped or the drag-and-drop operation is canceled. + +If @var{file} is a remote file, then a temporary copy will be made. + +@var{action} must be one of the symbols @code{copy}, @code{move} or +@code{link}, where @code{copy} means that @var{file} should be opened +or copied by the drop target, @code{move} means the drop target should +move the file to another location, and @code{link} means the drop +target should create a symbolic link to @var{file}. It is an error to +specify @code{link} as the action if @var{file} is a remote file. + +@var{frame} and @var{allow-same-frame} have the same meaning as in +@code{dnd-begin-text-drag}. The return value is the action that the drop target actually performed, which can be one of the following symbols: @@ -4156,23 +4172,12 @@ The drop target (usually a file manager) created a symbolic link to @var{file}. @item private -The drop target performed an unspecified action. -@end table +The drop target performed some other unspecified action. -@code{nil} can also be returned if the drag-and-drop operation was -cancelled. - -If @var{file} is a remote file, then a temporary copy will be made. - -@var{action} must be one of the symbols @code{copy}, @code{move} or -@code{link}, where @code{copy} means that @var{file} should be opened -or copied by the drop target, @code{move} means the drop target should -move the file to another location, and @code{link} means the drop -target should create a symbolic link to @var{file}. It is an error to -specify @code{link} as the action if @var{file} is a remote file. +@item nil +The drag-and-drop operation was canceled. +@end table -@var{frame} and @var{allow-same-frame} mean the same as in -@code{dnd-begin-text-drag}. @end defun @defun dnd-begin-drag-files files &optional frame action allow-same-frame @@ -4184,7 +4189,7 @@ dropping multiple files, then the first file will be used instead. @cindex initiating drag-and-drop, low-level The high-level interfaces described above are implemented on top of a lower-level primitive. If you need to drag content other than files -or text, the low-level interface @code{x-begin-drag} can be used +or text, use the low-level interface @code{x-begin-drag} instead. However, using it will require detailed knowledge of the data types and actions used by the programs to transfer content via drag-and-drop on each platform you want to support. diff --git a/lisp/dnd.el b/lisp/dnd.el index c5d5788dc49..14d80ac6c57 100644 --- a/lisp/dnd.el +++ b/lisp/dnd.el @@ -313,10 +313,10 @@ in that list instead." "Begin dragging TEXT from FRAME. Initate a drag-and-drop operation allowing the user to drag text from Emacs to another program (the drop target), then block until -the drop happens or is cancelled. +the drop is completed or is cancelled. -Return the action that the drop target actually performed, which -can be one of the following symbols: +If the drop completed, return the action that the drop target +actually performed, which can be one of the following symbols: - `copy', which means TEXT was inserted by the drop target. @@ -331,13 +331,13 @@ Return nil if the drop was cancelled. TEXT is a string containing text that will be inserted by the program where the drop happened. FRAME is the frame where the -mouse is currently held down, or nil (which means to use the -current frame). ACTION is one of the symbols `copy' or `move', +mouse is currently held down, or nil, which stands for the +current frame. ACTION is one of the symbols `copy' or `move', where `copy' means that the text should be inserted by the drop -target, and `move' means the the same as copy, but in addition +target, and `move' means the the same as `copy', but in addition the caller might have to delete TEXT from its source after this -function returns. If ALLOW-SAME-FRAME is nil, any drops on FRAME -itself will be ignored. +function returns. If ALLOW-SAME-FRAME is nil, ignore any drops +on FRAME itself. This function might return immediately if no mouse buttons are currently being held down. It should only be called upon a @@ -367,7 +367,7 @@ currently being held down. It should only be called upon a (defun dnd-begin-file-drag (file &optional frame action allow-same-frame) "Begin dragging FILE from FRAME. -Initate a drag-and-drop operation allowing the user to drag files +Initate a drag-and-drop operation allowing the user to drag a file from Emacs to another program (the drop target), then block until the drop happens or is cancelled. @@ -387,17 +387,17 @@ can be one of the following symbols: Return nil if the drop was cancelled. -FILE is the file name that will be inserted by the program where -the drop happened. If it is a remote file, a temporary copy will -be made. FRAME is the frame where the mouse is currently held -down, or nil (which means to use the current frame). ACTION is -one of the symbols `copy', `move' or `link', where `copy' means -that the file should be opened or copied by the drop target, -`move' means the drop target should move the file to another -location, and `link' means the drop target should create a -symbolic link to FILE. It is an error to specify `link' as the -action if FILE is a remote file. If ALLOW-SAME-FRAME is nil, any -drops on FRAME itself will be ignored. +FILE is the file name that will be sent to the program where the +drop happened. If it is a remote file, Emacs will make a +temporary copy and pass that. FRAME is the frame where the mouse +is currently held down, or nil (which means to use the current +frame). ACTION is one of the symbols `copy', `move' or `link', +where `copy' means that the file should be opened or copied by +the drop target, `move' means the drop target should move the +file to another location, and `link' means the drop target should +create a symbolic link to FILE. It is an error to specify `link' +as the action if FILE is a remote file. If ALLOW-SAME-FRAME is +nil, any drops on FRAME itself will be ignored. This function might return immediately if no mouse buttons are currently being held down. It should only be called upon a