1 ;;; select.el --- lisp portion of standard selection support
3 ;; Copyright (C) 1993-1994, 2001-2014 Free Software Foundation, Inc.
5 ;; Maintainer: emacs-devel@gnu.org
8 ;; This file is part of GNU Emacs.
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.
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.
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/>.
25 ;; Based partially on earlier release by Lucid.
29 (defcustom selection-coding-system nil
30 "Coding system for communicating with other programs.
32 For MS-Windows and MS-DOS:
33 When sending or receiving text via selection and clipboard, the text
34 is encoded or decoded by this coding system. The default value is
35 the current system default encoding on 9x/Me, `utf-16le-dos'
36 \(Unicode) on NT/W2K/XP, and `iso-latin-1-dos' on MS-DOS.
39 When sending text via selection and clipboard, if the target
40 data-type matches with the type of this coding system, it is used
41 for encoding the text. Otherwise (including the case that this
42 variable is nil), a proper coding system is used as below:
44 data-type coding system
45 --------- -------------
47 COMPOUND_TEXT compound-text-with-extensions
49 C_STRING no-conversion
51 When receiving text, if this coding system is non-nil, it is used
52 for decoding regardless of the data-type. If this is nil, a
53 proper coding system is used according to the data-type as above.
55 See also the documentation of the variable `x-select-request-type' how
56 to control which data-type to request for receiving text.
58 The default value is nil."
61 ;; Default was compound-text-with-extensions in 22.x (pre-unicode).
63 :set (lambda (symbol value)
64 (set-selection-coding-system value)
67 (defvar next-selection-coding-system nil
68 "Coding system for the next communication with other programs.
69 Usually, `selection-coding-system' is used for communicating with
70 other programs (X Windows clients or MS Windows programs). But, if this
71 variable is set, it is used for the next communication only.
72 After the communication, this variable is set to nil.")
74 ;; Only declared obsolete in 23.3.
75 (define-obsolete-function-alias 'x-selection 'x-get-selection "at least 19.34")
77 (defcustom gui-select-enable-clipboard t
78 "Non-nil means cutting and pasting uses the clipboard.
79 This can be in addition to, but in preference to, the primary selection,
80 if applicable (i.e. under X11)."
83 ;; The GNU/Linux version changed in 24.1, the MS-Windows version did not.
85 (define-obsolete-variable-alias 'x-select-enable-clipboard
86 'gui-select-enable-clipboard "25.1")
88 (gui-method-declare gui-select-text #'ignore
89 "Method used to pass the current selection to the system.
90 Called with one argument (the text selected).
91 Should obey `gui-select-enable-clipboard' where applicable.")
93 (gui-method-declare gui-get-selection #'ignore
94 "Return selected text.
95 Called with 2 arguments: (SELECTION-SYMBOL TARGET-TYPE)
96 SELECTION-SYMBOL is typically `PRIMARY', `SECONDARY', or `CLIPBOARD'.
97 \(Those are literal upper-case symbol names, since that's what X expects.)
98 TARGET-TYPE is the type of data desired, typically `STRING'.")
100 (defvar gui-last-selected-text nil
101 "Last text passed to `gui-select-text'.")
103 (defun gui-select-text (text)
104 "Select TEXT, a string, according to the window system.
105 if `gui-select-enable-clipboard' is non-nil, copy TEXT to the system's clipboard.
107 On X, if `x-select-enable-primary' is non-nil, put TEXT in
108 the primary selection.
110 On MS-Windows, make TEXT the current selection."
111 ;; FIXME: We should test gui-select-enable-clipboard here!
112 ;; But that would break the independence between x-select-enable-primary
113 ;; and x-select-enable-clipboard!
114 ;;(when gui-select-enable-clipboard
115 (gui-call gui-select-text text) ;;)
116 (setq gui-last-selected-text text))
117 (define-obsolete-function-alias 'x-select-text 'gui-select-text "25.1")
119 (defun gui-get-selection (&optional type data-type)
120 "Return the value of an X Windows selection.
121 The argument TYPE (default `PRIMARY') says which selection,
122 and the argument DATA-TYPE (default `STRING') says
123 how to convert the data.
125 TYPE may be any symbol \(but nil stands for `PRIMARY'). However,
126 only a few symbols are commonly used. They conventionally have
127 all upper-case names. The most often used ones, in addition to
128 `PRIMARY', are `SECONDARY' and `CLIPBOARD'.
130 DATA-TYPE is usually `STRING', but can also be one of the symbols
131 in `selection-converter-alist', which see. This argument is
132 ignored on MS-Windows and MS-DOS."
133 (let ((data (gui-call gui-get-selection (or type 'PRIMARY)
134 (or data-type 'STRING))))
135 (when (and (stringp data)
136 (setq data-type (get-text-property 0 'foreign-selection data)))
137 (let ((coding (or next-selection-coding-system
138 selection-coding-system
140 ('UTF8_STRING 'utf-8)
141 ('COMPOUND_TEXT 'compound-text-with-extensions)
143 ('STRING 'iso-8859-1)
144 (_ (error "Unknown selection data type: %S"
146 (setq data (if coding (decode-coding-string data coding)
147 (string-to-multibyte data))))
148 (setq next-selection-coding-system nil)
149 (put-text-property 0 (length data) 'foreign-selection data-type data))
151 (define-obsolete-function-alias 'x-get-selection 'gui-get-selection "25.1")
153 (defun x-get-clipboard ()
154 "Return text pasted to the clipboard."
155 (declare (obsolete gui-get-selection "25.1"))
156 (gui-call gui-get-selection 'CLIPBOARD 'STRING))
158 (defun gui-get-primary-selection ()
159 "Return the PRIMARY selection, or the best emulation thereof."
160 (or (gui-get-selection 'PRIMARY)
161 (and (fboundp 'w32-get-selection-value)
162 (eq (framep (selected-frame)) 'w32)
163 ;; MS-Windows emulates PRIMARY in x-get-selection, but only
164 ;; within the Emacs session, so consult the clipboard if
165 ;; primary is not found.
166 (w32-get-selection-value))
167 (error "No selection is available")))
168 (define-obsolete-function-alias 'x-get-selection-value
169 'gui-get-primary-selection "25.1")
171 (gui-method-declare gui-own-selection nil
172 "Method to assert a selection of type SELECTION and value VALUE.
173 SELECTION is a symbol, typically `PRIMARY', `SECONDARY', or `CLIPBOARD'.
174 (Those are literal upper-case symbol names, since that's what X expects.)
175 VALUE is typically a string, or a cons of two markers, but may be
176 anything that the functions on `selection-converter-alist' know about.
178 Called with 2 args: (SELECTION VALUE).")
180 (gui-method-declare gui-disown-selection nil
181 "If we own the selection SELECTION, disown it.
182 Disowning it means there is no such selection.
184 Called with one argument: (SELECTION)")
186 (gui-method-declare gui-selection-owner-p #'ignore
187 "Whether the current Emacs process owns the given X Selection.
188 Called with one argument: (SELECTION).
189 The arg should be the name of the selection in question, typically one of
190 the symbols `PRIMARY', `SECONDARY', or `CLIPBOARD'.
191 (Those are literal upper-case symbol names, since that's what X expects.)
192 For convenience, the symbol nil is the same as `PRIMARY',
193 and t is the same as `SECONDARY'.")
195 (defun gui-set-selection (type data)
196 "Make an X selection of type TYPE and value DATA.
197 The argument TYPE (nil means `PRIMARY') says which selection, and
198 DATA specifies the contents. TYPE must be a symbol. \(It can also
199 be a string, which stands for the symbol with that name, but this
200 is considered obsolete.) DATA may be a string, a symbol, an
201 integer (or a cons of two integers or list of two integers).
203 The selection may also be a cons of two markers pointing to the same buffer,
204 or an overlay. In these cases, the selection is considered to be the text
205 between the markers *at whatever time the selection is examined*.
206 Thus, editing done in the buffer after you specify the selection
207 can alter the effective value of the selection.
209 The data may also be a vector of valid non-vector selection values.
211 The return value is DATA.
213 Interactively, this command sets the primary selection. Without
214 prefix argument, it reads the selection in the minibuffer. With
215 prefix argument, it uses the text of the region as the selection value.
217 Note that on MS-Windows, primary and secondary selections set by Emacs
218 are not available to other programs."
219 (interactive (if (not current-prefix-arg)
220 (list 'PRIMARY (read-string "Set text for pasting: "))
221 (list 'PRIMARY (buffer-substring (region-beginning) (region-end)))))
222 (if (stringp type) (setq type (intern type)))
223 (or (gui--valid-simple-selection-p data)
226 (i (1- (length data))))
228 (or (gui--valid-simple-selection-p (aref data i))
232 (signal 'error (list "invalid selection" data)))
233 (or type (setq type 'PRIMARY))
235 (gui-call gui-own-selection type data)
236 (gui-call gui-disown-selection type))
238 (define-obsolete-function-alias 'x-set-selection 'gui-set-selection "25.1")
240 (defun gui--valid-simple-selection-p (data)
245 (marker-buffer (car data))
246 (buffer-name (marker-buffer (car data)))
247 (eq (marker-buffer (car data))
248 (marker-buffer (cdr data))))
251 (overlay-buffer data)
252 (buffer-name (overlay-buffer data)))
256 ;; Functions to convert the selection into various other selection types.
257 ;; Every selection type that Emacs handles is implemented this way, except
258 ;; for TIMESTAMP, which is a special case.
260 (defun xselect--selection-bounds (value)
261 "Return bounds of X selection value VALUE.
262 The return value is a list (BEG END BUF) if VALUE is a cons of
263 two markers or an overlay. Otherwise, it is nil."
264 (cond ((bufferp value)
265 (with-current-buffer value
267 (list (mark t) (point) value))))
269 (markerp (car value))
270 (markerp (cdr value)))
271 (when (and (marker-buffer (car value))
272 (buffer-name (marker-buffer (car value)))
273 (eq (marker-buffer (car value))
274 (marker-buffer (cdr value))))
275 (list (marker-position (car value))
276 (marker-position (cdr value))
277 (marker-buffer (car value)))))
279 (when (overlay-buffer value)
280 (list (overlay-start value)
282 (overlay-buffer value))))))
284 (defun xselect--int-to-cons (n)
285 (cons (ash n -16) (logand n 65535)))
287 (defun xselect--encode-string (type str &optional can-modify)
289 ;; If TYPE is nil, this is a local request; return STR as-is.
292 ;; Otherwise, encode STR.
293 (let ((coding (or next-selection-coding-system
294 selection-coding-system)))
296 (setq coding (coding-system-base coding)))
297 (let ((inhibit-read-only t))
298 ;; Suppress producing escape sequences for compositions.
299 ;; But avoid modifying the string if it's a buffer name etc.
300 (unless can-modify (setq str (substring str 0)))
301 (remove-text-properties 0 (length str) '(composition nil) str)
302 ;; For X selections, TEXT is a polymorphic target; choose
303 ;; the actual type from `UTF8_STRING', `COMPOUND_TEXT',
304 ;; `STRING', and `C_STRING'. On Nextstep, always use UTF-8
305 ;; (see ns_string_to_pasteboard_internal in nsselect.m).
306 (when (eq type 'TEXT)
309 (setq type 'UTF8_STRING))
310 ((not (multibyte-string-p str))
311 (setq type 'C_STRING))
313 (let (non-latin-1 non-unicode eight-bit)
320 (setq eight-bit t)))))
322 (setq type (if (or non-unicode
325 ;; If a coding is specified for
326 ;; selection, and that is
327 ;; compatible with COMPOUND_TEXT,
330 (eq (coding-system-get coding :mime-charset)
333 (if non-latin-1 'UTF8_STRING
334 (if eight-bit 'C_STRING
337 ((eq type 'UTF8_STRING)
339 (not (eq (coding-system-type coding) 'utf-8)))
340 (setq coding 'utf-8))
341 (setq str (encode-coding-string str coding)))
345 (not (eq (coding-system-type coding) 'charset)))
346 (setq coding 'iso-8859-1))
347 (setq str (encode-coding-string str coding)))
349 ((eq type 'COMPOUND_TEXT)
351 (not (eq (coding-system-type coding) 'iso-2022)))
352 (setq coding 'compound-text-with-extensions))
353 (setq str (encode-coding-string str coding)))
356 (setq str (string-make-unibyte str)))
359 (error "Unknown selection type: %S" type)))))
361 (setq next-selection-coding-system nil)
364 (defun xselect-convert-to-string (_selection type value)
365 (let ((str (cond ((stringp value) value)
366 ((setq value (xselect--selection-bounds value))
367 (with-current-buffer (nth 2 value)
368 (buffer-substring (nth 0 value)
370 (xselect--encode-string type str t)))
372 (defun xselect-convert-to-length (_selection _type value)
373 (let ((len (cond ((stringp value)
375 ((setq value (xselect--selection-bounds value))
376 (abs (- (nth 0 value) (nth 1 value)))))))
378 (xselect--int-to-cons len))))
380 (defun xselect-convert-to-targets (_selection _type _value)
381 ;; return a vector of atoms, but remove duplicates first.
382 (let* ((all (cons 'TIMESTAMP
384 (mapcar 'car selection-converter-alist))))
387 (cond ((memq (car rest) (cdr rest))
388 (setcdr rest (delq (car rest) (cdr rest))))
389 ((eq (car (cdr rest)) '_EMACS_INTERNAL) ; shh, it's a secret
390 (setcdr rest (cdr (cdr rest))))
392 (setq rest (cdr rest)))))
393 (apply 'vector all)))
395 (defun xselect-convert-to-delete (selection _type _value)
396 (gui-call gui-disown-selection selection)
397 ;; A return value of nil means that we do not know how to do this conversion,
398 ;; and replies with an "error". A return value of NULL means that we have
399 ;; done the conversion (and any side-effects) but have no value to return.
402 (defun xselect-convert-to-filename (_selection _type value)
403 (when (setq value (xselect--selection-bounds value))
404 (xselect--encode-string 'TEXT (buffer-file-name (nth 2 value)))))
406 (defun xselect-convert-to-charpos (_selection _type value)
407 (when (setq value (xselect--selection-bounds value))
408 (let ((beg (1- (nth 0 value))) ; zero-based
409 (end (1- (nth 1 value))))
410 (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
411 (xselect--int-to-cons (max beg end)))))))
413 (defun xselect-convert-to-lineno (_selection _type value)
414 (when (setq value (xselect--selection-bounds value))
415 (with-current-buffer (nth 2 value)
416 (let ((beg (line-number-at-pos (nth 0 value)))
417 (end (line-number-at-pos (nth 1 value))))
418 (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
419 (xselect--int-to-cons (max beg end))))))))
421 (defun xselect-convert-to-colno (_selection _type value)
422 (when (setq value (xselect--selection-bounds value))
423 (with-current-buffer (nth 2 value)
424 (let ((beg (progn (goto-char (nth 0 value)) (current-column)))
425 (end (progn (goto-char (nth 1 value)) (current-column))))
426 (cons 'SPAN (vector (xselect--int-to-cons (min beg end))
427 (xselect--int-to-cons (max beg end))))))))
429 (defun xselect-convert-to-os (_selection _type _size)
430 (xselect--encode-string 'TEXT (symbol-name system-type)))
432 (defun xselect-convert-to-host (_selection _type _size)
433 (xselect--encode-string 'TEXT (system-name)))
435 (defun xselect-convert-to-user (_selection _type _size)
436 (xselect--encode-string 'TEXT (user-full-name)))
438 (defun xselect-convert-to-class (_selection _type _size)
439 "Convert selection to class.
440 This function returns the string \"Emacs\"."
443 ;; We do not try to determine the name Emacs was invoked with,
444 ;; because it is not clean for a program's behavior to depend on that.
445 (defun xselect-convert-to-name (_selection _type _size)
446 "Convert selection to name.
447 This function returns the string \"emacs\"."
450 (defun xselect-convert-to-integer (_selection _type value)
451 (and (integerp value)
452 (xselect--int-to-cons value)))
454 (defun xselect-convert-to-atom (_selection _type value)
455 (and (symbolp value) value))
457 (defun xselect-convert-to-identity (_selection _type value) ; used internally
460 ;; Null target that tells clipboard managers we support SAVE_TARGETS
461 ;; (see freedesktop.org Clipboard Manager spec).
462 (defun xselect-convert-to-save-targets (selection _type _value)
463 (when (eq selection 'CLIPBOARD)
466 (setq selection-converter-alist
467 '((TEXT . xselect-convert-to-string)
468 (COMPOUND_TEXT . xselect-convert-to-string)
469 (STRING . xselect-convert-to-string)
470 (UTF8_STRING . xselect-convert-to-string)
471 (TARGETS . xselect-convert-to-targets)
472 (LENGTH . xselect-convert-to-length)
473 (DELETE . xselect-convert-to-delete)
474 (FILE_NAME . xselect-convert-to-filename)
475 (CHARACTER_POSITION . xselect-convert-to-charpos)
476 (LINE_NUMBER . xselect-convert-to-lineno)
477 (COLUMN_NUMBER . xselect-convert-to-colno)
478 (OWNER_OS . xselect-convert-to-os)
479 (HOST_NAME . xselect-convert-to-host)
480 (USER . xselect-convert-to-user)
481 (CLASS . xselect-convert-to-class)
482 (NAME . xselect-convert-to-name)
483 (ATOM . xselect-convert-to-atom)
484 (INTEGER . xselect-convert-to-integer)
485 (SAVE_TARGETS . xselect-convert-to-save-targets)
486 (_EMACS_INTERNAL . xselect-convert-to-identity)))
490 ;;; select.el ends here