30.21 Window System Selections

In window systems, such as X, data can be transferred between different applications by means of selections. Each window system defines an arbitrary number of selection types, all storing their own data; however, only three are commonly used: the clipboard, primary selection, and secondary selection. See Cut and Paste in The GNU Emacs Manual, for Emacs commands that make use of these selections. This section documents the low-level functions for reading and setting window-system selections; See Accessing Selections, for documentation concerning selection types and data formats under particular window systems.

Command: gui-set-selection type data ¶

This function sets a window-system selection. It takes two arguments: a selection type type, and the value to assign to it, data.

type should be a symbol; it is usually one of PRIMARY, SECONDARY or CLIPBOARD. These are generally symbols with upper-case names, in accord with X Window System conventions. If type is nil, that stands for PRIMARY.

If data is nil, it means to clear out the selection. Otherwise, data may be a string, a symbol, an integer, an overlay, or a cons of two markers pointing to the same buffer. An overlay or a pair of markers stands for text in the overlay or between the markers. The argument data may also be a vector of valid non-vector selection values.

If data is a string, then its text properties can specify values used for individual data types. For example, if data has a property named text/uri-list, then a call to gui-get-selection with the data type text/uri-list will result in the value of that property being used instead of data itself.

This function returns data.

Function: gui-get-selection &optional type data-type ¶

This function accesses selections set up by Emacs or by other programs. It takes two optional arguments, type and data-type. The default for type, the selection type, is PRIMARY.

The data-type argument specifies the form of data conversion to use, to convert the raw data obtained from another program into Lisp data. See X Selections, for an enumeration of data types valid under X, and see Other Selections for those elsewhere.

User Option: selection-coding-system ¶

This variable provides a coding system (see Coding Systems) which is used to encode selection data, and takes effect on MS-Windows and X. It is also used in the MS-DOS port when it runs on MS-Windows and can access the Windows clipboard text.

On X, the value of this variable provides the coding system which gui-get-selection will use to decode selection data for a subset of text data types, and also forces replies to selection requests for the polymorphic TEXT data type to be encoded by the compound-text-with-extensions coding system rather than Unicode.

On MS-Windows, this variable is generally ignored, as the MS-Windows clipboard provides the information about decoding as part of the clipboard data, and uses either UTF-16 or locale-specific encoding automatically as appropriate. We recommend to set the value of this variable only on the older Windows 9X, as it is otherwise used only in the very rare cases when the information provided by the clipboard data is unusable for some reason.

The default value of this variable is the system code page under MS-Windows 98 or Me, utf-16le-dos on Windows NT/W2K/XP/Vista/7/8/10/11, iso-latin-1-dos on MS-DOS, and nil elsewhere.

For backward compatibility, there are obsolete aliases x-get-selection and x-set-selection, which were the names of gui-get-selection and gui-set-selection before Emacs 25.1.