lisp/select.el

   1 ;;; select.el --- lisp portion of standard selection support
   2
   3 ;; Copyright (C) 1993-1994, 2001-2014 Free Software Foundation, Inc.
   4
   5 ;; Maintainer: emacs-devel@gnu.org
   6 ;; Keywords: internal
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; Based partially on earlier release by Lucid.
  26
  27 ;; The functionality here is pretty messy, because there are different
  28 ;; functions that claim to get or set the "selection", with no clear
  29 ;; distinction between them.  Here's my best understanding of it:
  30 ;; - gui-select-text and gui-selection-value go together to access the general
  31 ;;   notion of "GUI selection" for interoperation with other applications.
  32 ;;   This can use either the clipboard or the primary selection, or both or
  33 ;;   none according to gui-select-enable-clipboard and x-select-enable-primary.
  34 ;;   These are the default values of interprogram-cut/paste-function.
  35 ;; - gui-get-primary-selection is used to get the PRIMARY selection,
  36 ;;   specifically for mouse-yank-primary.
  37 ;; - gui-get-selection and gui-set-selection are lower-level functions meant to
  38 ;;   access various kinds of selections (CLIPBOARD, PRIMARY, SECONDARY).
  39
  40 ;; Currently gui-select-text and gui-selection-value provide gui-methods so the
  41 ;; actual backend can do it whichever way it wants.  This means for example
  42 ;; that gui-select-enable-clipboard is defined here but implemented in each and
  43 ;; every backend.
  44 ;; Maybe a better structure would be to make gui-select-text and
  45 ;; gui-selection-value have no associated gui-method, and implement
  46 ;; gui-select-enable-clipboard (and x-select-enable-clipboard) themselves.
  47 ;; This would instead rely on gui-get/set-selection being implemented well
  48 ;; (e.g. currently w32's implementation thereof sucks, for example,
  49 ;; since it doesn't access the system's clipboard when setting/getting the
  50 ;; CLIPBOARD selection).
  51
  52 ;;; Code:
  53
  54 (defcustom selection-coding-system nil
  55   "Coding system for communicating with other programs.
  56
  57 For MS-Windows and MS-DOS:
  58 When sending or receiving text via selection and clipboard, the text
  59 is encoded or decoded by this coding system.  The default value is
  60 the current system default encoding on 9x/Me, `utf-16le-dos'
  61 \(Unicode) on NT/W2K/XP, and `iso-latin-1-dos' on MS-DOS.
  62
  63 For X Windows:
  64 When sending text via selection and clipboard, if the target
  65 data-type matches with the type of this coding system, it is used
  66 for encoding the text.  Otherwise (including the case that this
  67 variable is nil), a proper coding system is used as below:
  68
  69 data-type       coding system
  70 ---------       -------------
  71 UTF8_STRING     utf-8
  72 COMPOUND_TEXT   compound-text-with-extensions
  73 STRING          iso-latin-1
  74 C_STRING        no-conversion
  75
  76 When receiving text, if this coding system is non-nil, it is used
  77 for decoding regardless of the data-type.  If this is nil, a
  78 proper coding system is used according to the data-type as above.
  79
  80 See also the documentation of the variable `x-select-request-type' how
  81 to control which data-type to request for receiving text.
  82
  83 The default value is nil."
  84   :type 'coding-system
  85   :group 'mule
  86   ;; Default was compound-text-with-extensions in 22.x (pre-unicode).
  87   :version "23.1"
  88   :set (lambda (symbol value)
  89          (set-selection-coding-system value)
  90          (set symbol value)))
  91
  92 (defvar next-selection-coding-system nil
  93   "Coding system for the next communication with other programs.
  94 Usually, `selection-coding-system' is used for communicating with
  95 other programs (X Windows clients or MS Windows programs).  But, if this
  96 variable is set, it is used for the next communication only.
  97 After the communication, this variable is set to nil.")
  98
  99 ;; Only declared obsolete in 23.3.
 100 (define-obsolete-function-alias 'x-selection 'x-get-selection "at least 19.34")
 101
 102 (defcustom gui-select-enable-clipboard t
 103   "Non-nil means cutting and pasting uses the clipboard.
 104 This can be in addition to, but in preference to, the primary selection,
 105 if applicable (i.e. under X11)."
 106   :type 'boolean
 107   :group 'killing
 108   ;; The GNU/Linux version changed in 24.1, the MS-Windows version did not.
 109   :version "24.1")
 110 (define-obsolete-variable-alias 'x-select-enable-clipboard
 111   'gui-select-enable-clipboard "25.1")
 112
 113 (gui-method-declare gui-select-text #'ignore
 114   "Method used to pass the current selection to the system.
 115 Called with one argument (the text selected).
 116 Should obey `gui-select-enable-clipboard' where applicable.")
 117
 118 (gui-method-declare gui-get-selection #'ignore
 119   "Return selected text.
 120 Called with 2 arguments: (SELECTION-SYMBOL TARGET-TYPE)
 121 SELECTION-SYMBOL is typically `PRIMARY', `SECONDARY', or `CLIPBOARD'.
 122 \(Those are literal upper-case symbol names, since that's what X expects.)
 123 TARGET-TYPE is the type of data desired, typically `STRING'.")
 124
 125 (defvar gui-last-selected-text nil
 126   ;; We keep track of the last text selected here, so we can check the
 127   ;; current selection against it, and avoid passing back our own text
 128   ;; from gui-selection-value.
 129   "Last text passed to `gui-select-text'.")
 130
 131 (defun gui-select-text (text)
 132   "Select TEXT, a string, according to the window system.
 133 if `gui-select-enable-clipboard' is non-nil, copy TEXT to the system's clipboard.
 134
 135 On X, if `x-select-enable-primary' is non-nil, put TEXT in
 136 the primary selection.
 137
 138 On MS-Windows, make TEXT the current selection."
 139   ;; FIXME: We should test gui-select-enable-clipboard here!
 140   ;; But that would break the independence between x-select-enable-primary
 141   ;; and x-select-enable-clipboard!
 142   ;;(when gui-select-enable-clipboard
 143     (gui-call gui-select-text text) ;;)
 144   (setq gui-last-selected-text text))
 145 (define-obsolete-function-alias 'x-select-text 'gui-select-text "25.1")
 146
 147 (gui-method-declare gui-selection-value #'ignore
 148   "Method to return the GUI's selection.
 149 Takes no argument, and returns a string.
 150 Should obey `gui-select-enable-clipboard'.")
 151
 152 (defun gui-selection-value ()
 153   (let ((text (gui-call gui-selection-value)))
 154     (if (string= text "") (setq text nil))
 155     (cond
 156      ((not text) nil)
 157      ((eq text gui-last-selected-text) nil)
 158      ((string= text gui-last-selected-text)
 159       ;; Record the newer string, so subsequent calls can use the `eq' test.
 160       (setq gui-last-selected-text text)
 161       nil)
 162      (t
 163       (setq gui-last-selected-text text)))))
 164 (define-obsolete-function-alias 'x-selection-value 'gui-selection-value "25.1")
 165
 166 (defun gui-get-selection (&optional type data-type)
 167   "Return the value of an X Windows selection.
 168 The argument TYPE (default `PRIMARY') says which selection,
 169 and the argument DATA-TYPE (default `STRING') says
 170 how to convert the data.
 171
 172 TYPE may be any symbol \(but nil stands for `PRIMARY').  However,
 173 only a few symbols are commonly used.  They conventionally have
 174 all upper-case names.  The most often used ones, in addition to
 175 `PRIMARY', are `SECONDARY' and `CLIPBOARD'.
 176
 177 DATA-TYPE is usually `STRING', but can also be one of the symbols
 178 in `selection-converter-alist', which see.  This argument is
 179 ignored on MS-Windows and MS-DOS."
 180   (let ((data (gui-call gui-get-selection (or type 'PRIMARY)
 181                         (or data-type 'STRING))))
 182     (when (and (stringp data)
 183                (setq data-type (get-text-property 0 'foreign-selection data)))
 184       (let ((coding (or next-selection-coding-system
 185                         selection-coding-system
 186                         (pcase data-type
 187                           ('UTF8_STRING 'utf-8)
 188                           ('COMPOUND_TEXT 'compound-text-with-extensions)
 189                           ('C_STRING nil)
 190                           ('STRING 'iso-8859-1)
 191                           (_ (error "Unknown selection data type: %S"
 192                                     type))))))
 193         (setq data (if coding (decode-coding-string data coding)
 194                      (string-to-multibyte data))))
 195       (setq next-selection-coding-system nil)
 196       (put-text-property 0 (length data) 'foreign-selection data-type data))
 197     data))
 198 (define-obsolete-function-alias 'x-get-selection 'gui-get-selection "25.1")
 199
 200 (defun x-get-clipboard ()
 201   "Return text pasted to the clipboard."
 202   (declare (obsolete gui-get-selection "25.1"))
 203   (gui-call gui-get-selection 'CLIPBOARD 'STRING))
 204
 205 (defun gui-get-primary-selection ()
 206   "Return the PRIMARY selection, or the best emulation thereof."
 207   (or (gui-get-selection 'PRIMARY)
 208       (and (fboundp 'w32-get-selection-value)
 209            (eq (framep (selected-frame)) 'w32)
 210            ;; MS-Windows emulates PRIMARY in x-get-selection, but only
 211            ;; within the Emacs session, so consult the clipboard if
 212            ;; primary is not found.
 213            (w32-get-selection-value))
 214       (error "No selection is available")))
 215 (define-obsolete-function-alias 'x-get-selection-value
 216   'gui-get-primary-selection "25.1")
 217
 218 (gui-method-declare gui-own-selection nil
 219   "Method to assert a selection of type SELECTION and value VALUE.
 220 SELECTION is a symbol, typically `PRIMARY', `SECONDARY', or `CLIPBOARD'.
 221 (Those are literal upper-case symbol names, since that's what X expects.)
 222 VALUE is typically a string, or a cons of two markers, but may be
 223 anything that the functions on `selection-converter-alist' know about.
 224
 225 Called with 2 args: (SELECTION VALUE).")
 226
 227 (gui-method-declare gui-disown-selection nil
 228   "If we own the selection SELECTION, disown it.
 229 Disowning it means there is no such selection.
 230
 231 Called with one argument: (SELECTION)")
 232
 233 (gui-method-declare gui-selection-owner-p #'ignore
 234   "Whether the current Emacs process owns the given X Selection.
 235 Called with one argument: (SELECTION).
 236 The arg should be the name of the selection in question, typically one of
 237 the symbols `PRIMARY', `SECONDARY', or `CLIPBOARD'.
 238 (Those are literal upper-case symbol names, since that's what X expects.)")
 239
 240 (gui-method-declare gui-selection-exists-p #'ignore
 241   "Whether there is an owner for the given X Selection.
 242 Called with one argument: (SELECTION).
 243 The arg should be the name of the selection in question, typically one of
 244 the symbols `PRIMARY', `SECONDARY', or `CLIPBOARD'.
 245 (Those are literal upper-case symbol names, since that's what X expects.)")
 246
 247 (defun gui-set-selection (type data)
 248   "Make an X selection of type TYPE and value DATA.
 249 The argument TYPE (nil means `PRIMARY') says which selection, and
 250 DATA specifies the contents.  TYPE must be a symbol.  \(It can also
 251 be a string, which stands for the symbol with that name, but this
 252 is considered obsolete.)  DATA may be a string, a symbol, an
 253 integer (or a cons of two integers or list of two integers).
 254
 255 The selection may also be a cons of two markers pointing to the same buffer,
 256 or an overlay.  In these cases, the selection is considered to be the text
 257 between the markers *at whatever time the selection is examined*.
 258 Thus, editing done in the buffer after you specify the selection
 259 can alter the effective value of the selection.
 260
 261 The data may also be a vector of valid non-vector selection values.
 262
 263 The return value is DATA.
 264
 265 Interactively, this command sets the primary selection.  Without
 266 prefix argument, it reads the selection in the minibuffer.  With
 267 prefix argument, it uses the text of the region as the selection value.
 268
 269 Note that on MS-Windows, primary and secondary selections set by Emacs
 270 are not available to other programs."
 271   (interactive (if (not current-prefix-arg)
 272                    (list 'PRIMARY (read-string "Set text for pasting: "))
 273                  (list 'PRIMARY (buffer-substring (region-beginning) (region-end)))))
 274   (if (stringp type) (setq type (intern type)))
 275   (or (gui--valid-simple-selection-p data)
 276       (and (vectorp data)
 277            (let ((valid t)
 278                  (i (1- (length data))))
 279              (while (>= i 0)
 280                (or (gui--valid-simple-selection-p (aref data i))
 281                    (setq valid nil))
 282                (setq i (1- i)))
 283              valid))
 284       (signal 'error (list "invalid selection" data)))
 285   (or type (setq type 'PRIMARY))
 286   (if data
 287       (gui-call gui-own-selection type data)
 288     (gui-call gui-disown-selection type))
 289   data)
 290 (define-obsolete-function-alias 'x-set-selection 'gui-set-selection "25.1")
 291
 292 (defun gui--valid-simple-selection-p (data)
 293   (or (bufferp data)
 294       (and (consp data)
 295            (markerp (car data))
 296            (markerp (cdr data))
 297            (marker-buffer (car data))
 298            (buffer-name (marker-buffer (car data)))
 299            (eq (marker-buffer (car data))
 300                (marker-buffer (cdr data))))
 301       (stringp data)
 302       (and (overlayp data)
 303            (overlay-buffer data)
 304            (buffer-name (overlay-buffer data)))
 305       (symbolp data)
 306       (integerp data)))
 307 \f
 308 ;; Functions to convert the selection into various other selection types.
 309 ;; Every selection type that Emacs handles is implemented this way, except
 310 ;; for TIMESTAMP, which is a special case.
 311
 312 (defun xselect--selection-bounds (value)
 313   "Return bounds of X selection value VALUE.
 314 The return value is a list (BEG END BUF) if VALUE is a cons of
 315 two markers or an overlay.  Otherwise, it is nil."
 316   (cond ((bufferp value)
 317          (with-current-buffer value
 318            (when (mark t)
 319              (list (mark t) (point) value))))
 320         ((and (consp value)
 321               (markerp (car value))
 322               (markerp (cdr value)))
 323          (when (and (marker-buffer (car value))
 324                     (buffer-name (marker-buffer (car value)))
 325                     (eq (marker-buffer (car value))
 326                         (marker-buffer (cdr value))))
 327            (list (marker-position (car value))
 328                  (marker-position (cdr value))
 329                  (marker-buffer (car value)))))
 330         ((overlayp value)
 331          (when (overlay-buffer value)
 332            (list (overlay-start value)
 333                  (overlay-end value)
 334                  (overlay-buffer value))))))
 335
 336 (defun xselect--int-to-cons (n)
 337   (cons (ash n -16) (logand n 65535)))
 338
 339 (defun xselect--encode-string (type str &optional can-modify)
 340   (when str
 341     ;; If TYPE is nil, this is a local request; return STR as-is.
 342     (if (null type)
 343         str
 344       ;; Otherwise, encode STR.
 345       (let ((coding (or next-selection-coding-system
 346                         selection-coding-system)))
 347         (if coding
 348             (setq coding (coding-system-base coding)))
 349         (let ((inhibit-read-only t))
 350           ;; Suppress producing escape sequences for compositions.
 351           ;; But avoid modifying the string if it's a buffer name etc.
 352           (unless can-modify (setq str (substring str 0)))
 353           (remove-text-properties 0 (length str) '(composition nil) str)
 354           ;; For X selections, TEXT is a polymorphic target; choose
 355           ;; the actual type from `UTF8_STRING', `COMPOUND_TEXT',
 356           ;; `STRING', and `C_STRING'.  On Nextstep, always use UTF-8
 357           ;; (see ns_string_to_pasteboard_internal in nsselect.m).
 358           (when (eq type 'TEXT)
 359             (cond
 360              ((featurep 'ns)
 361               (setq type 'UTF8_STRING))
 362              ((not (multibyte-string-p str))
 363               (setq type 'C_STRING))
 364              (t
 365               (let (non-latin-1 non-unicode eight-bit)
 366                 (mapc #'(lambda (x)
 367                           (if (>= x #x100)
 368                               (if (< x #x110000)
 369                                   (setq non-latin-1 t)
 370                                 (if (< x #x3FFF80)
 371                                     (setq non-unicode t)
 372                                   (setq eight-bit t)))))
 373                       str)
 374                 (setq type (if (or non-unicode
 375                                    (and
 376                                     non-latin-1
 377                                     ;; If a coding is specified for
 378                                     ;; selection, and that is
 379                                     ;; compatible with COMPOUND_TEXT,
 380                                     ;; use it.
 381                                     coding
 382                                     (eq (coding-system-get coding :mime-charset)
 383                                         'x-ctext)))
 384                                'COMPOUND_TEXT
 385                              (if non-latin-1 'UTF8_STRING
 386                                (if eight-bit 'C_STRING
 387                                  'STRING))))))))
 388           (cond
 389            ((eq type 'UTF8_STRING)
 390             (if (or (not coding)
 391                     (not (eq (coding-system-type coding) 'utf-8)))
 392                 (setq coding 'utf-8))
 393             (setq str (encode-coding-string str coding)))
 394
 395            ((eq type 'STRING)
 396             (if (or (not coding)
 397                     (not (eq (coding-system-type coding) 'charset)))
 398                 (setq coding 'iso-8859-1))
 399             (setq str (encode-coding-string str coding)))
 400
 401            ((eq type 'COMPOUND_TEXT)
 402             (if (or (not coding)
 403                     (not (eq (coding-system-type coding) 'iso-2022)))
 404                 (setq coding 'compound-text-with-extensions))
 405             (setq str (encode-coding-string str coding)))
 406
 407            ((eq type 'C_STRING)
 408             (setq str (string-make-unibyte str)))
 409
 410            (t
 411             (error "Unknown selection type: %S" type)))))
 412
 413       (setq next-selection-coding-system nil)
 414       (cons type str))))
 415
 416 (defun xselect-convert-to-string (_selection type value)
 417   (let ((str (cond ((stringp value) value)
 418                    ((setq value (xselect--selection-bounds value))
 419                     (with-current-buffer (nth 2 value)
 420                       (buffer-substring (nth 0 value)
 421                                         (nth 1 value)))))))
 422     (xselect--encode-string type str t)))
 423
 424 (defun xselect-convert-to-length (_selection _type value)
 425   (let ((len (cond ((stringp value)
 426                     (length value))
 427                    ((setq value (xselect--selection-bounds value))
 428                     (abs (- (nth 0 value) (nth 1 value)))))))
 429     (if len
 430         (xselect--int-to-cons len))))
 431
 432 (defun xselect-convert-to-targets (_selection _type _value)
 433   ;; return a vector of atoms, but remove duplicates first.
 434   (let* ((all (cons 'TIMESTAMP
 435                     (cons 'MULTIPLE
 436                           (mapcar 'car selection-converter-alist))))
 437          (rest all))
 438     (while rest
 439       (cond ((memq (car rest) (cdr rest))
 440              (setcdr rest (delq (car rest) (cdr rest))))
 441             ((eq (car (cdr rest)) '_EMACS_INTERNAL)  ; shh, it's a secret
 442              (setcdr rest (cdr (cdr rest))))
 443             (t
 444              (setq rest (cdr rest)))))
 445     (apply 'vector all)))
 446
 447 (defun xselect-convert-to-delete (selection _type _value)
 448   (gui-call gui-disown-selection selection)
 449   ;; A return value of nil means that we do not know how to do this conversion,
 450   ;; and replies with an "error".  A return value of NULL means that we have
 451   ;; done the conversion (and any side-effects) but have no value to return.
 452   'NULL)
 453
 454 (defun xselect-convert-to-filename (_selection _type value)
 455   (when (setq value (xselect--selection-bounds value))
 456     (xselect--encode-string 'TEXT (buffer-file-name (nth 2 value)))))
 457
 458 (defun xselect-convert-to-charpos (_selection _type value)
 459   (when (setq value (xselect--selection-bounds value))
 460     (let ((beg (1- (nth 0 value))) ; zero-based
 461           (end (1- (nth 1 value))))
 462       (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
 463                           (xselect--int-to-cons (max beg end)))))))
 464
 465 (defun xselect-convert-to-lineno (_selection _type value)
 466   (when (setq value (xselect--selection-bounds value))
 467     (with-current-buffer (nth 2 value)
 468       (let ((beg (line-number-at-pos (nth 0 value)))
 469             (end (line-number-at-pos (nth 1 value))))
 470         (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
 471                             (xselect--int-to-cons (max beg end))))))))
 472
 473 (defun xselect-convert-to-colno (_selection _type value)
 474   (when (setq value (xselect--selection-bounds value))
 475     (with-current-buffer (nth 2 value)
 476       (let ((beg (progn (goto-char (nth 0 value)) (current-column)))
 477             (end (progn (goto-char (nth 1 value)) (current-column))))
 478         (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
 479                             (xselect--int-to-cons (max beg end))))))))
 480
 481 (defun xselect-convert-to-os (_selection _type _size)
 482   (xselect--encode-string 'TEXT (symbol-name system-type)))
 483
 484 (defun xselect-convert-to-host (_selection _type _size)
 485   (xselect--encode-string 'TEXT (system-name)))
 486
 487 (defun xselect-convert-to-user (_selection _type _size)
 488   (xselect--encode-string 'TEXT (user-full-name)))
 489
 490 (defun xselect-convert-to-class (_selection _type _size)
 491   "Convert selection to class.
 492 This function returns the string \"Emacs\"."
 493   "Emacs")
 494
 495 ;; We do not try to determine the name Emacs was invoked with,
 496 ;; because it is not clean for a program's behavior to depend on that.
 497 (defun xselect-convert-to-name (_selection _type _size)
 498   "Convert selection to name.
 499 This function returns the string \"emacs\"."
 500   "emacs")
 501
 502 (defun xselect-convert-to-integer (_selection _type value)
 503   (and (integerp value)
 504        (xselect--int-to-cons value)))
 505
 506 (defun xselect-convert-to-atom (_selection _type value)
 507   (and (symbolp value) value))
 508
 509 (defun xselect-convert-to-identity (_selection _type value) ; used internally
 510   (vector value))
 511
 512 ;; Null target that tells clipboard managers we support SAVE_TARGETS
 513 ;; (see freedesktop.org Clipboard Manager spec).
 514 (defun xselect-convert-to-save-targets (selection _type _value)
 515   (when (eq selection 'CLIPBOARD)
 516     'NULL))
 517
 518 (setq selection-converter-alist
 519       '((TEXT . xselect-convert-to-string)
 520         (COMPOUND_TEXT . xselect-convert-to-string)
 521         (STRING . xselect-convert-to-string)
 522         (UTF8_STRING . xselect-convert-to-string)
 523         (TARGETS . xselect-convert-to-targets)
 524         (LENGTH . xselect-convert-to-length)
 525         (DELETE . xselect-convert-to-delete)
 526         (FILE_NAME . xselect-convert-to-filename)
 527         (CHARACTER_POSITION . xselect-convert-to-charpos)
 528         (LINE_NUMBER . xselect-convert-to-lineno)
 529         (COLUMN_NUMBER . xselect-convert-to-colno)
 530         (OWNER_OS . xselect-convert-to-os)
 531         (HOST_NAME . xselect-convert-to-host)
 532         (USER . xselect-convert-to-user)
 533         (CLASS . xselect-convert-to-class)
 534         (NAME . xselect-convert-to-name)
 535         (ATOM . xselect-convert-to-atom)
 536         (INTEGER . xselect-convert-to-integer)
 537         (SAVE_TARGETS . xselect-convert-to-save-targets)
 538         (_EMACS_INTERNAL . xselect-convert-to-identity)))
 539
 540 (provide 'select)
 541
 542 ;;; select.el ends here