From 12e5171882afb2bb31e3505cb077953b342920af Mon Sep 17 00:00:00 2001 From: Po Lu Date: Fri, 1 Jul 2022 18:10:39 +0800 Subject: [PATCH] Document XDS stuff * doc/emacs/frames.texi (Drag and Drop): * doc/lispref/frames.texi (Drag and Drop): Add documentation about XDS features. * etc/NEWS: Tag entry. --- doc/emacs/frames.texi | 7 +++++++ doc/lispref/frames.texi | 14 ++++++++++++++ etc/NEWS | 1 + 3 files changed, 22 insertions(+) diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index d90a6ac6729..d78cbffaa71 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1249,6 +1249,13 @@ To drag text from Emacs to other programs, set the option @code{mouse-drag-and-drop-region-cross-program} to a non-@code{nil} value. + On the X window system, some programs can drop files on Emacs, +expecting Emacs to save them. Normally, Emacs will prompt for a file +name under which the file will be saved, and then open the file, but +that behavior can be changed by changing the variable +@code{x-dnd-direct-save-function}. @xref{Drag and Drop,,, elisp, The +Emacs Lisp Reference Manual}. + @node Menu Bars @section Menu Bars @cindex menu bar mode diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index f7491502f4c..f655ccdfa73 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -4090,6 +4090,20 @@ They can either be the same data types that are typically accepted by specific drag-n-drop protocol being used. Plain text may be @code{"STRING"} or @code{"text/plain"}, for example. +@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.) + @cindex initiating drag-and-drop On capable window systems, Emacs also supports dragging contents from its frames to windows of other applications. diff --git a/etc/NEWS b/etc/NEWS index b0a5cd4f1db..3127e734261 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -423,6 +423,7 @@ This inhibits putting empty strings onto the kill ring. These options allow adjusting point and scrolling a window when dragging items from another program. ++++ ** The X Direct Save (XDS) protocol is now supported. This means dropping an image or file link from programs such as Firefox will no longer create a temporary file in a random directory, -- 2.39.5