From eea7214113b14f5b34ed7cfae0365c7509e5d5ac Mon Sep 17 00:00:00 2001 From: Po Lu Date: Tue, 24 Oct 2023 03:04:51 +0000 Subject: [PATCH] Rewrite first two sections of the drag-and-drop documentation * doc/lispref/frames.texi (Accessing Selections): Refine wording. (Drag and Drop): Rewrite for clarity and enter into detail upon various function arguments. --- doc/lispref/frames.texi | 164 +++++++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 63 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index d840f281849..5e2fdf1231c 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -4076,12 +4076,12 @@ complexity: its @var{data} argument is given verbatim to system-specific code to be rendered suitable for transfer to the window system or requesting clients. - The most comprehensive implementation of selections is that under -the X Window System. This is both an artifact of history (X was the -first window system supported by Emacs) and one occasioned by -technical considerations: X selections are not merely an expedient for -the transfer of text and multimedia content between clients, but a -general inter-client communication system, a design that has yielded a + The most comprehensive implementation of selections exists under the +X Window System. This is both an artifact of history (X was the first +window system supported by Emacs) and one occasioned by technical +considerations: X selections are not merely an expedient for the +transfer of text and multimedia content between clients, but a general +inter-client communication system, a design that has yielded a proliferation of selection and data types. Compounding this confusion, there is another inter-client @@ -4705,74 +4705,112 @@ seldom consistent medley of data types. @section Drag and Drop @cindex drag and drop - 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 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. + Data transferred by drag and drop is generally either plain text or +a URL designating a file or another resource. When text is dropped, +it is inserted at the location of the drop, with recourse to saving it +into the kill ring if that is not possible. + + URLs dropped are supplied to pertinent @dfn{DND handler functions} +in the variable @code{dnd-protocol-alist}, or alternatively ``URL +handlers'' as set forth by the variables @code{browse-url-handlers} +and @code{browse-url-default-handlers}; absent matching handlers of +either type, they are treated as plain text and inserted in the +buffer. @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 -match @var{pattern}: the URL being dropped, and the action being -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 in 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 +This variable is an alist between regexps against which URLs are +matched and DND handler functions called on the dropping of matching +URLs. + +Each handler function is called with the URL that matched it and one +of the symbols @code{copy}, @code{move}, @code{link}, @code{private} +or @code{ask} identifying the action to be taken. + +If @var{action} is @code{private}, the program that initiated the drop +does not insist on any particular behavior on the part of its +recipient; a reasonable action to take in that case is to open the URL +or copy its contents into the current buffer. The other values of +@var{action} imply much the same as in 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 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 -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 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 receives drops of different data -types, or you want to 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. - - 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"}. + Emacs does not take measures to accept data besides text and URLs by +default, for the window system interfaces which enable this are too +far removed from each other to abstract over consistently. Nor are +DND handlers accorded the capacity to influence the action they are +meant to take, as particular drag-and-drop protocols deny recipients +such control. The X11 drag-and-drop implementation rests on several +underlying protocols that make use of selection transfer and share +much in common, to which low level access is provided through the +following functions and variables: + +@defvar x-dnd-test-function +This function is called to ascertain whether Emacs should accept a +drop. It is called with three arguments: + +@itemize @bullet +@item +The window under the item being dragged, which is to say the window +whose buffer is to receive the drop. If the item is situated over a +non-window component of a frame (such as scroll bars, tool bars and +things to that effect), the frame itself is provided in its place. + +@item +One of the symbols @code{move}, @code{copy}, @code{link} or +@code{ask}, representing an action to take on the item data suggested +by the drop source. These symbols carry the same implications as in +@code{x-begin-drag}. + +@item +A vector of selection data types (@pxref{X Selections}) the item +provides. +@end itemize + +This function must return @code{nil} to reject the drop or a cons of +the action that will be taken (such as through transfer to a DND +handler function) and the selection data type to be requested. The +action returned in that cons may also be the symbol @code{private}, +which intimates that the action taken is as yet indeterminate. +@end defvar + +@defvar x-dnd-known-types +Modifying @code{x-dnd-test-function} is generally unwarranted, for its +default set of criteria for accepting a drop can be adjusted by +changing this list of selection data types. Each element is a string, +which if found as the symbol name of an element within the list of +data types by the default ``test function'', will induce that function +to accept the drop. + +Introducing a new entry into this list is not useful unless a +counterpart handler function is appended to @code{x-dnd-types-alist}. +@end defvar + +@defvar x-dnd-types-alist +This variable is an alist between strings designating selection data +types and functions which are called when things of such types are +dropped. + +Each such function is supplied three arguments; the first is the +window or frame below the location of the drop, as in +@code{x-dnd-test-function}; the second is the action to be taken, +which may be any of the actions returned by test functions, and third +is the selection data itself (@pxref{Accessing Selections}). +@end defvar + + Selection data types as provided by X11 drag-and-drop protocols are +sometimes distinct from those provided by the ICCCM and conforming +clipboard or primary selection owners. Frequently, the name of a MIME +type, such as @code{"text/plain;charset=utf-8"} (with discrepant +capitalization of the ``utf-8''), is substitued for a standard X +selection name such as @code{UTF8_STRING}. @cindex XDS @cindex direct save protocol @vindex x-dnd-direct-save-function - When Emacs runs on X window system, it supports the X Direct Save -(@acronym{XDS}) protocol, which allows users to save a file by + 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 -- 2.39.2