; 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'.
This commit is contained in:
Eli Zaretskii
parent
ca2e7409dc
commit
dc7623a59e
2 changed files with 67 additions and 62 deletions
|
|
@ -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.
|
||||
The drop target performed some other unspecified action.
|
||||
|
||||
@item nil
|
||||
The drag-and-drop operation was canceled.
|
||||
@end table
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
|
|
|||
40
lisp/dnd.el
40
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue