@w{@code{(@var{key} @var{type} @var{value})}}. In this list,
@var{key} must be the name of the data being transferred, generally
that of a MIME type, for example @samp{"text/plain"}, and @var{type}
-is a symbol or a number designating the type of the data, thus also
+is a symbol or a number designating the type of the data; thus also
governing the interpretation of @var{value}; following is a list of
valid data types and how each of them will cause @var{value} to be
interpreted.
@cindex XDS
@cindex direct save protocol
@vindex x-dnd-direct-save-function
- When Emacs runs on the X window system, it supports the X Direct
-Save (@acronym{XDS}) protocol, which allows users to save a file by
-dragging and dropping it onto an Emacs window, such as a Dired window.
-To comply with the unique requirements of @acronym{XDS}, these
-drag-and-drop requests are processed specially: instead of being
-handled according to @code{x-dnd-types-alist}, they are handled by the
-@dfn{direct-save function} that is the value of the variable
-@code{x-dnd-direct-save-function}. The value should be a function of
-two arguments, @var{need-name} and @var{filename}. The @acronym{XDS}
-protocol uses a two-step procedure for dragging files:
+ The X Direct Save (@acronym{XDS}) protocol enables programs to
+devolve responsibility for naming a dropped file file upon the
+recipient. When such a drop transpires, DND handlers and the forgoing
+X-specific interface are largely circumvented, tasking a different
+function with responding to the drop.
+
+@defvar x-dnd-direct-save-function
+This variable should be set to a function that registers and names
+files dropped using the @acronym{XDS} protocol in a two-step
+procedure. It is provided two arguments, @var{need-name} and
+@var{filename}.
@enumerate 1
@item
there.
@end enumerate
-The default value of @code{x-dnd-direct-save-function} is
+Its default @code{x-dnd-direct-save-function} is
@code{x-dnd-save-direct}.
+@end defvar
@defun x-dnd-save-direct need-name filename
When called with the @var{need-name} argument non-@code{nil}, this
@end defun
@cindex initiating drag-and-drop
- On capable window systems, Emacs also supports dragging contents
-from its frames to windows of other applications.
+ It is also possible to drag content from Emacs to other programs
+whenever this is supported for the current window-system. The
+functions which provide for this are as follows:
@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
-(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.
+This function commences a drag-and-drop operation from @var{frame} to
+another program (dubbed the @dfn{drop target}), and returns when
+@var{text} is dropped or the operation is canceled.
@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
-below.
+target, and @code{move} means the same as @code{copy}, but furthermore
+enjoins the caller to delete @var{text} from its source as explained
+in the list 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
-return immediately if no mouse buttons are held down, so it should be
-only called immediately after a @code{down-mouse-1} or similar event
-(@pxref{Mouse Events}), with @var{frame} set to the frame where that
-event was generated (@pxref{Click Events}).
+@code{nil}, which means to use the selected frame. Since this
+function is liable to return promptly if no mouse buttons are held
+down, it should be only called in response to a @code{down-mouse-1} or
+analogous event (@pxref{Mouse Events}), with @var{frame} set to the
+frame where that event was generated (@pxref{Click Events}).
-@var{allow-same-frame} specifies whether or not drops on top of
-@var{frame} itself are to be ignored.
+If @var{allow-same-frame} is @code{nil}, drops on top of @var{frame}
+will be disregarded.
-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:
+The return value reflects the action that the drop target actually
+performed, and thus also what action, if any, the caller should in
+turn take. It is 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.
+The drop target inserted the dropped text, and the caller should
+delete @var{text} from the buffer where it was extracted from, if
+applicable.
@item private
-The drop target performed some other unspecified action.
+The drop target took some other unspecified action.
@item nil
The drag-and-drop operation was canceled.
@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 the result of the drag-and-drop operation when
-the file is dropped or the drag-and-drop operation is canceled.
+This function commences a drag-and-drop operation from @var{frame} to
+another program (dubbed the @dfn{drop target}), and returns when
+@var{file} is dropped or the operation is canceled.
-If @var{file} is a remote file, then a temporary copy will be made.
+If @var{file} is a remote file, then a temporary local 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
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}.
+@var{frame} and @var{allow-same-frame} mean the same as they do in
+calls to @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:
+performed, which is one of the following symbols:
@table @code
@item copy
@end defun
@defun dnd-direct-save file name &optional frame allow-same-frame
-This function is similar to @code{dnd-begin-file-drag} (with the
-default action of copy), but instead of specifying the action you
-specify the name of the copy created by the target program in
-@code{name}.
+The behavior of this function is akin to that of
+@code{dnd-begin-file-drag} (when the default action @code{copy} is
+used), except that it accepts a name under which the copy is meant to
+be filed.
@end defun
@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, 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.
+a lower-level primitive. The low-level interface @code{x-begin-drag}
+is also available for dragging content besides text and files. It
+demands detailed knowledge of the data types and actions understood by
+programs on each platform its callers wish to support.
@defun x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip
This function begins a drag from @var{frame}, and returns 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
-the drop target can request from Emacs (@pxref{Window System
+@var{targets} is a list of strings representing selection targets,
+much like the @var{data-type} argument to @code{gui-get-selection},
+that the drop target can request from Emacs (@pxref{Window System
Selections}).
-@var{action} is a symbol describing the action recommended to the
-target. It can either be @code{XdndActionCopy}, which
-means to copy the contents of the selection @code{XdndSelection} to
-the drop target; or @code{XdndActionMove}, which means copy as with
-@code{XdndActionCopy}, and in addition the caller should delete
-whatever was stored in that selection after copying it.
+@var{action} is a symbol designating the action recommended to the
+target. It can either be @code{XdndActionCopy} or
+@code{XdndActionMove}; both imply copying the contents of the
+selection @code{XdndSelection} to the drop target, but the latter
+moreover conveys a promise to delete the contents of the selection
+after the copying.
@var{action} may also be an alist which associates between symbols
-describing the available actions, and strings that the drop target is
-expected to present to the user to choose between the available
-actions.
+representing available actions, and strings that the drop target
+presents to the user for him to select between those actions.
If @var{return-frame} is non-@code{nil} and the mouse moves over an
Emacs frame after first moving out of @var{frame}, then the frame to
which the mouse moves will be returned immediately. If
-@var{return-frame} is the symbol @code{now}, then any frame underneath
+@var{return-frame} is the symbol @code{now}, then any frame beneath
the mouse pointer will be returned without waiting for the mouse to
first move out of @var{frame}. @var{return-frame} is useful when you
want to treat dragging content from one frame to another specially,
-while also being able to drag content to other programs, but it is not
-guaranteed to work on all systems and with all window managers.
+while also dragging content to other programs, but it is not
+guaranteed to function on all systems and with all window managers.
If @var{follow-tooltip} is non-@code{nil}, the position of any tooltip
-(such as one shown by @code{tooltip-show}) will follow the location of
-the mouse pointer whenever it moves during the drag-and-drop
+(such as one displayed by @code{tooltip-show}) will follow the
+location of the mouse pointer as it moves during the drag-and-drop
operation. The tooltip will be hidden once all mouse buttons are
released.
If the drop was rejected or no drop target was found, this function
-returns @code{nil}. Otherwise, it returns a symbol describing the
-action the target chose to perform, which can differ from @var{action}
-if that isn't supported by the drop target. @code{XdndActionPrivate}
-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}.
+returns @code{nil}. Otherwise, it returns a symbol representing the
+action the target opted to take, which can differ from @var{action} if
+that isn't supported by the drop target. @code{XdndActionPrivate} is
+also a valid return value in addition to @code{XdndActionCopy} and
+@code{XdndActionMove}; it suggests that the drop target opted for an
+indeterminate action, and no further action is required of the caller.
+
+The caller must cooperate with the target to complete the action
+selected by the target. For example, callers should delete any buffer
+text that was dragged if this function returns @code{XdndActionMove},
+and likewise for other drag data where comparable criteria apply.
@end defun
@cindex drag and drop protocols, X
- On X Windows, several different drag-and-drop protocols are
-supported by @code{x-begin-drag}. When dragging content that is known
-to not be supported by a specific drag-and-drop protocol, it might be
-desirable to turn that protocol off, by changing the values of the
-following variables:
+ The function @code{x-begin-drag} leverages several drag-and-drop
+protocols ``behind the scenes''. When dragging content that is known
+to not be supported by a specific drag-and-drop protocol, that
+protocol can be disabled by changing the values of the following
+variables:
@defvar x-dnd-disable-motif-protocol
When this is non-@code{nil}, the Motif drag and drop protocols are
doesn't support any drag-and-drop protocol at all.
A side effect is that Emacs will become the owner of the primary
-selection upon such a drop. If that is not desired, then the drop
-emulation can be disabled by setting this variable to @code{nil}.
+selection upon such a drop. Such emulation can be disabled by setting
+this variable to @code{nil}.
@end defvar
@node Color Names
projects / emacs.git / commitdiff