30.22.1 X Selections

X refrains from defining fixed data types for selection data or a fixed number of selections. Selections are identified by X “atoms”, which are unique 29-bit identifiers issued by the X server for string names. This complexity is hidden by Emacs: when Lisp provides a symbol whose name is that of the atom, Emacs will request these identifiers without further intervention.

When a program “sets” a selection under X, it actually makes itself the “owner” of the selection—the X server will then deliver selection requests to the program, which is obliged to respond to the requesting client with the selection data.

Similarly, a program does not “get” selection data from the X server. Instead, its selection requests are sent to the client with the window which last asserted ownership over the selection, which is expected to respond with the requested data.

Each selection request incorporates three parameters:

• The window which requested the selection, which identifies the requesting program, otherwise known as the requestor.
• An atom identifying the target to which the owner should convert the selection. It is easiest to think of the conversion target as the kind of data that the requestor wants: in selection requests made by Emacs, the target is determined by the type argument to gui-get-selection.
• A 32-bit timestamp representing the X server time at which the requestor last received input; this parameter is not relevant to Lisp code, for it’s only meant to abet synchronization between the X server, owner and requestor.

The selection owner responds by transferring to the requestor a series of bytes, 16 bit words, or 32 bit words, along with another atom identifying the type of those words. After requesting a selection, Emacs then applies its own interpretation of the data format and data type to convert the data transferred by the selection owner to a Lisp representation, which gui-get-selection returns.

Emacs converts selection data consisting of any series of bytes to a unibyte string holding those bytes, that consisting of a single 16-bit or 32-bit word as an unsigned number, and that consisting of multiple such words as a vector of unsigned numbers. The exceptions to this general pattern are that Emacs applies special treatment for data from the following conversion targets:

INTEGER

16-bit or 32-bit words of this type are treated as signed rather than unsigned integers. If there are multiple words in the selection data, a vector is returned; otherwise, the integer is returned by itself.

ATOM

32-bit words of this type are treated as X atoms, and returned (either alone or as vectors) as Lisp symbols by the names they identify. Invalid atoms are replaced by nil.

COMPOUND_TEXT

UTF8_STRING

STRING

A single foreign-selection text property set to the type of the selection data will be placed in unibyte strings derived from a request for these data types.

Each selection owner must return at least two selection targets: TARGETS, which returns a number of atoms describing the selection targets that the owner supports, and MULTIPLE, used for internal purposes by X clients. A selection owner may support any number of other targets, some of which may be standardized by the X Consortium’s Inter-Client Communication Conventions Manual, while others, such as UTF8_STRING, were meant to be standardized by the XFree86 Project, but their standardization was never completed.

Requests for a given selection target may, by convention, return data in a specific type, or it may return data in one of several types, whichever is most convenient for the selection owner; the latter type of selection target is dubbed a polymorphic target. In response to a request, a selection target may also return no data at all, whereafter the selection owner executes some action as a side effect. Targets that are thus replied to are termed side-effect targets.

Here are some selection targets whose behavior is generally consistent with a standard when requested from the CLIPBOARD, PRIMARY, or SECONDARY selections.

ADOBE_PORTABLE_DOCUMENT_FORMAT

This target returns data in Adobe System’s “Portable Document Format” format, as a string.

APPLE_PICT

This target returns data in the “PICT” image format used on Macintosh computers, as a string.

BACKGROUND

BITMAP

COLORMAP

FOREGROUND

Together, these four targets return integer data necessary to make use of a bitmap image stored on the X server: the pixel value of the bitmap’s background color, the X identifier of the bitmap, the colormap inside which the background and foreground are allocated, and the pixel value of the bitmap’s foreground color.

CHARACTER_POSITION

This target returns two unsigned 32-bit integers of type SPAN describing the start and end positions of the selection data in the text field containing it, in bytes.

COMPOUND_TEXT

This target returns a string of type COMPOUND_TEXT in the X Consortium’s multi-byte text encoding system.

DELETE

This target returns nothing, but as a side-effect deletes the selection contents from any text field containing them.

DRAWABLE

PIXMAP

This target returns a list of unsigned 32-bit integers, each of which corresponds to an X server drawable or pixmap.

ENCAPSULATED_POSTSCRIPT

_ADOBE_EPS

This target returns a string containing encapsulated Postscript code.

FILE_NAME

This target returns a string containing one or more file names, separated by NULL characters.

HOST_NAME

This target returns a string containing the fully-qualified domain name of the machine on which the selection owner is running.

USER

This target returns a string containing the user name of the machine on which the selection owner is running.

LENGTH

This target returns an unsigned 32-bit or 16-bit integer containing the length of the selection data.

LINE_NUMBER

This target returns two unsigned 32-bit integers of type SPAN describing the line numbers corresponding to the start and end positions of the selection data in the text field containing it.

MODULE

This target returns the name of any function containing the selection data. It is principally requested by text editors.

STRING

This target returns the selection data as a string of type STRING, encoded in ISO Latin-1 format, with Unix newline characters.

C_STRING

This target returns the selection data as a “C string”. This has been interpreted as meaning the raw selection data in whatever encoding used by the owner, either terminated with a NULL byte or not at all, or an ASCII string which may or may not be terminated.

UTF8_STRING

This returns the selection data as a string of type UTF8_STRING, encoded in UTF-8, with unspecified EOL format.

TIMESTAMP

This target returns the X server time at which the selection owner took ownership over the selection as a 16-bit or 32-bit word of type CARDINAL.

TEXT

This polymorphic target returns selection data as a string, either COMPOUND_TEXT, STRING, C_STRING, or UTF8_STRING, whichever data type is convenient for the selection owner.

When a request for the targets STRING, COMPOUND_TEXT, or UTF8_STRING is made using the function gui-get-selection, and neither selection-coding-system nor next-selection-coding-system is set, the resultant strings are decoded by the proper coding systems for those targets: iso-8859-1, compound-text-with-extensions and utf-8 respectively.

In addition to the targets specified above (and the many targets used by various programs for their own purposes), several popular programs and toolkits have defined selection data types of their own, without consulting the appropriate X standards bodies. These targets are generally named after such MIME types as text/html or image/jpeg; they have been witnessed returning the following forms of data:

• Unterminated, newline terminated, or NULL character terminated file names of an image or text file.
• Image or text data in the appropriate format.
• file:// URIs (or conceivably newline or NUL terminated lists of URIs) identifying files in the appropriate format.

These selection targets were first used by Netscape, but are now proffered by all kinds of programs, especially those based on recent versions of the GTK+ or Qt toolkits.

Emacs is also capable of serving as a selection owner. When gui-set-selection is called, the selection data provided is recorded internally and Emacs obtains ownership of the selection being set.

Variable: selection-converter-alist ¶

Alist of selection targets to “selection converter” functions. When a selection request is received, Emacs looks up the selection converter pertaining to the requested selection target.

Selection converters are called with three arguments: the symbol corresponding to the atom identifying the selection being requested, the selection target that is being requested, and the value set with gui-set-selection. The values which they must return are either conses of symbols designating the data type and numbers, symbols, vectors of numbers or symbols, or the cdrs of such conses by themselves.

If a selection converter’s value is the special symbol NULL, the data type returned to its requestor is set to NULL, and no data is sent in response.

If such a value is a string, it must be a unibyte string; should no data type be explicitly specified, the data is transferred to its requestor with the type STRING.

If it is a symbol, its “atom” is retrieved, and it is transferred to its requestor as a 32-bit value—if no data type is specified, its type is ATOM.

If it is a number between -32769 and 32768, it is transferred to its requestor as a 16 bit value—if no data type is specified, its type is INTEGER.

If it is any other number, it is accounted a 32 bit value. Even if the number returned is unsigned, its requestor will treat words of type INTEGER as signed. To return an unsigned value, specify the type CARDINAL in its place.

If it is a vector of symbols or numbers, the response to its requestor will be a list of multiple atoms or numbers. The data type returned when not expressly set is that of the list’s first element.

By default, Emacs is configured with selection converters for the following selection targets:

TEXT

This selection converter returns selection data as:

• A string of type C_STRING, if the selection contents contain no multibyte characters, or contain “raw 8-bit bytes” (see Text Representations).
• A string of type STRING, if the selection contents can be represented as ISO-Latin-1 text.
• A string of type COMPOUND_TEXT, if the selection contents can be encoded in the X Consortium’s Compound Text Encoding, and selection-coding-system or next-selection-coding-system is set to a coding system whose :mime-charset property is x-ctext.
• A string of type UTF8_STRING otherwise.

COMPOUND_TEXT

This selection converter returns selection data as a string of type COMPOUND_TEXT.

STRING

This selection converter returns selection data as a string of type STRING, encoded in ISO-Latin-1 format.

UTF8_STRING

This selection converter returns selection data in UTF-8 format.

text/plain

text/plain;charset=utf-8

text/uri-list

text/x-xdnd-username

XmTRANSFER_SUCCESS

XmTRANSFER_FAILURE

FILE

_DT_NETFILE

These selection converters are used for internal purposes during drag-and-drop operations and are not available for selections other than XdndSelection.

TARGETS

This selection converter returns a list of atoms, one for each selection target understood by Emacs.

MULTIPLE

This selection converter is implemented in C code and is used to implement efficient transfer of selection requests which specify multiple selection targets at the same time.

LENGTH

This selection converter returns the length of the selection data, in bytes.

DELETE

This selection converter is used for internal purposes during drag-and-drop operations.

FILE_NAME

This selection converter returns the file name of the buffer containing the selection data.

CHARACTER_POSITION

This selection converter returns the character positions of each end of the selection in the buffer containing the selection data.

LINE_NUMBER

COLUMN_NUMBER

This selection converter returns the line and column numbers of each end of the selection in the buffer containing the selection data.

OWNER_OS

This selection converter returns the name of the operating system on which Emacs is running.

HOST_NAME

This selection converter returns the fully-qualified domain name of the machine on which Emacs is running.

USER

This selection converter returns the username of the user account under which Emacs is running.

CLASS

NAME

These selection converters return the resource class and name used by Emacs.

INTEGER

This selection converter returns an integer value verbatim.

SAVE_TARGETS

_EMACS_INTERNAL

These selection converters are used for internal purposes.

With the exception of INTEGER, all selection converters expect the data provided to gui-set-selection to be one of the following:

• A string.
• A list of the form (beg end buf), where beg and end are two markers or overlays describing the bounds of the selection data in the buffer buf.