Function: gui-get-selection

gui-get-selection is a byte-compiled function defined in select.el.gz.

Signature

(gui-get-selection &optional TYPE DATA-TYPE)

Documentation

Return the value of an X Windows selection.

The argument TYPE (default PRIMARY) says which selection, and the argument DATA-TYPE (default STRING) says how to convert the data.

TYPE may be any symbol (but nil stands for PRIMARY). However, only a few symbols are commonly used. They conventionally have all upper-case names. The most often used ones, in addition to PRIMARY, are SECONDARY and CLIPBOARD.

DATA-TYPE is usually STRING, but can also be one of the symbols in selection-converter-alist, which see. On X, we recommend to always use a specific DATA-TYPE expected from the selection owner. In particular, if the data is expected to be non-ASCII text, in many cases using 'UTF8_STRING is the most reasonable value for DATA-TYPE.

Window systems other than X usually support only a small subset of these symbols, in addition to STRING; MS-Windows supports TARGETS, which reports the formats available in the clipboard if TYPE is CLIPBOARD.

View in manual

Probably introduced at or before Emacs version 25.1.

Aliases

evil-get-selection x-get-selection (obsolete since 25.1)

Source Code

;; Defined in /usr/src/emacs/lisp/select.el.gz
(defun gui-get-selection (&optional type data-type)
  "Return the value of an X Windows selection.
The argument TYPE (default `PRIMARY') says which selection,
and the argument DATA-TYPE (default `STRING') says
how to convert the data.

TYPE may be any symbol \(but nil stands for `PRIMARY').  However,
only a few symbols are commonly used.  They conventionally have
all upper-case names.  The most often used ones, in addition to
`PRIMARY', are `SECONDARY' and `CLIPBOARD'.

DATA-TYPE is usually `STRING', but can also be one of the symbols
in `selection-converter-alist', which see.  On X, we recommend
to always use a specific DATA-TYPE expected from the selection
owner.  In particular, if the data is expected to be non-ASCII
text, in many cases using \\='UTF8_STRING is the most reasonable
value for DATA-TYPE.

Window systems other than X usually support only a small subset of
these symbols, in addition to `STRING'; MS-Windows supports `TARGETS',
which reports the formats available in the clipboard if TYPE is `CLIPBOARD'."
  (let ((data (gui-backend-get-selection (or type 'PRIMARY)
                                         (or data-type 'STRING))))
    (when (and (stringp data)
               ;; If this text property is set, then the data needs to
               ;; be decoded -- otherwise it has already been decoded
               ;; by the lower level functions.
               (get-text-property 0 'foreign-selection data))
      (let ((coding (or next-selection-coding-system
                        selection-coding-system
                        (pcase data-type
                          ('UTF8_STRING 'utf-8)
                          ('text/plain\;charset=utf-8 'utf-8)
                          ('COMPOUND_TEXT 'compound-text-with-extensions)
                          ('C_STRING nil)
                          ('STRING 'iso-8859-1)))))
        (setq data
              (cond (coding (decode-coding-string data coding))
                     ;; We want to convert each non-ASCII byte to the
                     ;; corresponding eight-bit character, which has
                     ;; a codepoint >= #x3FFF00.
                    ((eq data-type 'C_STRING)
                     (string-to-multibyte data))
                    ;; Guess at the charset for types like text/html
                    ;; -- it can be anything, and different
                    ;; applications use different encodings.
                    ((string-match-p "\\`text/" (symbol-name data-type))
                     (decode-coding-string
                      data (car (detect-coding-string data))))
                    ;; Do nothing.
                    (t data))))
      (setq next-selection-coding-system nil)
      (put-text-property 0 (length data) 'foreign-selection data-type data))
    data))