procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve Drag and Drop preamble in the Lisp reference manual

Browse source 
* doc/lispref/frames.texi (Drag and Drop): Reword contents and
clear up some ambiguities and redundancies.
This commit is contained in:
Po Lu 2022-10-28 22:22:59 +08:00
parent c0f7a276cf
commit e8b59a9bb9
1 changed files with 58 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
doc/lispref/frames.texi
View file

@ -4058,70 +4058,83 @@ amount of different data types on the clipboard.
When the user drops something from another application over Emacs,
Emacs will try to insert any text and open any URL that was dropped.
If text was dropped, then it will always be inserted at the location
of the mouse pointer when the drop happened, or saved in the kill ring
if insertion failed (which can happen if the buffer is read-only). If
it was an URL, then Emacs tries to call an appropriate handler
function by first matching the URL against regexps defined in
@code{dnd-protocol-alist}, and then against @code{browse-url-handlers}
and @code{browse-url-default-handlers}, and failing that, inserting
the URL as plain text.
of the mouse pointer where the drop happened, or saved in the kill
ring if insertion failed, which could happen if the buffer was
read-only. If a URL was dropped instead, then Emacs will first try to
call an appropriate handler function by matching the URL against
regexps defined in the variable @code{dnd-protocol-alist}, and then
against those defined in the variables @code{browse-url-handlers} and
@code{browse-url-default-handlers}. Should no suitable handler be
located, Emacs will fall back to inserting the URL as plain text.
@defvar dnd-protocol-alist
This variable is a list of cons cells of the form
@w{@code{(@var{pattern} . @var{action})}}. @var{pattern} is a regexp
that URLs are matched against after being dropped. @var{action} is a
function that is called with two arguments should a URL being dropped
function that is called with two arguments, should a URL being dropped
match @var{pattern}: the URL being dropped, and the action being
performed for the drop (one of the symbols @code{copy}, @code{move},
@code{link}, @code{private} or @code{ask}).
performed for the drop, which is one of the symbols @code{copy},
@code{move}, @code{link}, @code{private} or @code{ask}.
If @var{action} is @var{private}, then it means the program that
initiated the drop wants Emacs to perform an unspecified action with
the URL; a reasonable action to perform that case is to open the URL
or copy its contents into the current buffer. Otherwise, @var{action}
has the same meaning as the @var{action} argument to
@code{dnd-begin-file-drag}.
@end defvar
@cindex drag and drop, X
@cindex drag and drop, other formats
Emacs implements drag-and-drop for text and URLs individually for
each window system, and does not by default support the dropping of
anything else. Code that wishes to support the dropping of content
types not supported by Emacs can utilize the X-specific interface
described below:
Emacs implements receiving text and URLs individually for each
window system, and does not by default support receiving other kinds
of data as drops. To support receiving other kinds of data, use the
X-specific interface described below:
@vindex x-dnd-test-function
@vindex x-dnd-known-types
When a user drags something from another application over Emacs on
the X Window System, that other application expects Emacs to tell it
if Emacs can handle the data that was dragged. The variable
@code{x-dnd-test-function} is used by Emacs to determine what to
reply. The default value is @code{x-dnd-default-test-function} which
accepts drops if the type of the data to be dropped is present in
@code{x-dnd-known-types}. You can customize
@code{x-dnd-test-function} and/or @code{x-dnd-known-types} if you want
Emacs to accept or reject drops based on some other criteria.
When a user drags something from another application over Emacs
under the X Window System, that other application expects Emacs to
tell it if Emacs understands the data being dragged. The function in
the variable @code{x-dnd-test-function} is called by Emacs to
determine what to reply to any such inquiry. The default value is
@code{x-dnd-default-test-function}, which accepts drops if the type of
the data to be dropped is present in @code{x-dnd-known-types}.
Changing the the variables @code{x-dnd-test-function} and
@code{x-dnd-known-types} can make Emacs accept or reject drops based
on some other criteria.
@vindex x-dnd-types-alist
If you want to change the way Emacs handles drop of different types
or add a new type, customize @code{x-dnd-types-alist}. This requires
detailed knowledge of what types other applications use for drag and
drop.
If you want to change the way Emacs receives drops of different data
types, or enable it to understand a new type, change the variable
@code{x-dnd-types-alist}. Doing so correctly requires detailed
knowledge of what data types other applications use for drag and drop.
Those data types are typically implemented as special data types an
X selection provided by the other application can be converted to.
They can either be the same data types that are typically accepted by
@code{gui-set-selection}, or they can be MIME types, depending on the
specific drag-n-drop protocol being used. Plain text may be
@code{"STRING"} or @code{"text/plain"}, for example.
These data types are typically implemented as special data types
that can be obtained from an X selection provided by the other
application. In most cases, they are either the same data types that
are typically accepted by @code{gui-set-selection}, or MIME types,
depending on the specific drag-and-drop protocol being used. For
example, the data type used for plain text may be either
@code{"STRING"} or @code{"text/plain"}.
@vindex x-dnd-direct-save-function
However, @code{x-dnd-types-alist} does not handle a special kind of
drop sent by a program which wants Emacs to save a file in a location
Emacs must determine by itself. These drops are handled via the
variable @code{x-dnd-direct-save-function}, which should be a function
that accepts two arguments. If the first argument is non-@code{nil},
then the second argument is a string describing the name (with no
leading directory) that the other program recommends the file be saved
under, and the function should return the complete file name under
which it will be saved. Otherwise, the file has already been saved,
and the second argument is the complete name of the file. The
function should then perform whatever action is appropriate (i.e.,
open the file or refresh the directory listing.)
drop sent by a program that wants Emacs to tell it where to save a
file in a specific location determined by the user. These drops are
instead handled by a function set as the value of the variable
@code{x-dnd-direct-save-function}, which should accept two arguments.
If the first argument is non-@code{nil}, then the second argument is a
string describing the name (with no directory name) that the other
program recommends that the file should be saved under, and the
function should return the full file name under which it should be
saved. After the function completes, Emacs will ask the other program
to save the file under the name that was returned, and if the file was
successfully saved, call the function again with the first argument
set to a non-@code{nil} value and the second argument set to the file
name that was returned. The function should then perform whatever
action is appropriate (i.e., opening the file or refreshing a
directory listing.)
@cindex initiating drag-and-drop
On capable window systems, Emacs also supports dragging contents