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:
gui-get-selection.
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:
INTEGER16-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.
ATOM32-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_TEXTUTF8_STRINGSTRINGA 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_FORMATThis target returns data in Adobe System’s “Portable Document Format” format, as a string.
APPLE_PICTThis target returns data in the “PICT” image format used on Macintosh computers, as a string.
BACKGROUNDBITMAPCOLORMAPFOREGROUNDTogether, 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_POSITIONThis 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_TEXTThis target returns a string of type COMPOUND_TEXT in the X
Consortium’s multi-byte text encoding system.
DELETEThis target returns nothing, but as a side-effect deletes the selection contents from any text field containing them.
DRAWABLEPIXMAPThis target returns a list of unsigned 32-bit integers, each of which corresponds to an X server drawable or pixmap.
ENCAPSULATED_POSTSCRIPT_ADOBE_EPSThis target returns a string containing encapsulated Postscript code.
FILE_NAMEThis target returns a string containing one or more file names, separated by NULL characters.
HOST_NAMEThis target returns a string containing the fully-qualified domain name of the machine on which the selection owner is running.
USERThis target returns a string containing the user name of the machine on which the selection owner is running.
LENGTHThis target returns an unsigned 32-bit or 16-bit integer containing the length of the selection data.
LINE_NUMBERThis 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.
MODULEThis target returns the name of any function containing the selection data. It is principally requested by text editors.
STRINGThis target returns the selection data as a string of type
STRING, encoded in ISO Latin-1 format, with Unix newline
characters.
C_STRINGThis 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_STRINGThis returns the selection data as a string of type
UTF8_STRING, encoded in UTF-8, with unspecified EOL format.
TIMESTAMPThis 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.
TEXTThis 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:
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.
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:
TEXTThis selection converter returns selection data as:
C_STRING, if the selection contents contain no
multibyte characters, or contain “raw 8-bit bytes” (see Text Representations).
STRING, if the selection contents can be
represented as ISO-Latin-1 text.
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.
UTF8_STRING otherwise.
COMPOUND_TEXTThis selection converter returns selection data as a string of type
COMPOUND_TEXT.
STRINGThis selection converter returns selection data as a string of type
STRING, encoded in ISO-Latin-1 format.
UTF8_STRINGThis selection converter returns selection data in UTF-8 format.
text/plaintext/plain;charset=utf-8text/uri-listtext/x-xdnd-usernameXmTRANSFER_SUCCESSXmTRANSFER_FAILUREFILE_DT_NETFILEThese selection converters are used for internal purposes during
drag-and-drop operations and are not available for selections other
than XdndSelection.
TARGETSThis selection converter returns a list of atoms, one for each selection target understood by Emacs.
MULTIPLEThis 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.
LENGTHThis selection converter returns the length of the selection data, in bytes.
DELETEThis selection converter is used for internal purposes during drag-and-drop operations.
FILE_NAMEThis selection converter returns the file name of the buffer containing the selection data.
CHARACTER_POSITIONThis selection converter returns the character positions of each end of the selection in the buffer containing the selection data.
LINE_NUMBERCOLUMN_NUMBERThis selection converter returns the line and column numbers of each end of the selection in the buffer containing the selection data.
OWNER_OSThis selection converter returns the name of the operating system on which Emacs is running.
HOST_NAMEThis selection converter returns the fully-qualified domain name of the machine on which Emacs is running.
USERThis selection converter returns the username of the user account under which Emacs is running.
CLASSNAMEThese selection converters return the resource class and name used by Emacs.
INTEGERThis selection converter returns an integer value verbatim.
SAVE_TARGETS_EMACS_INTERNALThese 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:
(beg end buf), where
beg and end are two markers or overlays describing the
bounds of the selection data in the buffer buf.