Function: dnd-begin-text-drag

dnd-begin-text-drag is a byte-compiled function defined in dnd.el.gz.

Signature

(dnd-begin-text-drag TEXT &optional FRAME ACTION ALLOW-SAME-FRAME)

Documentation

Begin dragging TEXT from FRAME.

Initiate a drag-and-drop operation allowing the user to drag text from Emacs to another program (the drop target), then block until the drop is completed or is canceled.

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.

  - move, which means TEXT was inserted, and the caller should
    additionally delete TEXT from its source (such as the buffer
    where it originated).

  - private, which means the drop target chose to perform an
    unspecified action.

Return nil if the drop was canceled.

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 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 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, 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 down-mouse-1 (or similar) event.

This function is only supported on X Windows, macOS/GNUstep, and Haiku; on all other platforms it will signal an error.

View in manual

Source Code

;; Defined in /usr/src/emacs/lisp/dnd.el.gz
(defun dnd-begin-text-drag (text &optional frame action allow-same-frame)
  "Begin dragging TEXT from FRAME.
Initiate a drag-and-drop operation allowing the user to drag text
from Emacs to another program (the drop target), then block until
the drop is completed or is canceled.

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.

  - `move', which means TEXT was inserted, and the caller should
    additionally delete TEXT from its source (such as the buffer
    where it originated).

  - `private', which means the drop target chose to perform an
    unspecified action.

Return nil if the drop was canceled.

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 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 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, 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
`down-mouse-1' (or similar) event.

This function is only supported on X Windows, macOS/GNUstep, and Haiku;
on all other platforms it will signal an error."
  (unless (fboundp 'x-begin-drag)
    (error "Dragging text from Emacs is not supported by this window system"))
  (gui-set-selection 'XdndSelection text)
  (unless action
    (setq action 'copy))
  (let ((return-value
         (x-begin-drag '(;; Traditional X selection targets used by GTK, the
                         ;; Motif drag-and-drop protocols, and programs like
                         ;; Xterm.  `STRING' is also used on NS and Haiku.
                         "STRING" "TEXT" "COMPOUND_TEXT" "UTF8_STRING"
                         ;; Used by Xdnd clients that strictly comply with
                         ;; the standard (i.e. Qt programs).
                         "text/plain" "text/plain;charset=utf-8")
                       (cl-ecase action
                         (copy 'XdndActionCopy)
                         (move 'XdndActionMove))
                       frame nil allow-same-frame)))
    (cond
     ((eq return-value 'XdndActionCopy) 'copy)
     ((eq return-value 'XdndActionMove) 'move)
     ((not return-value) nil)
     (t 'private))))