30.22.2 Other Selections

Selections under such window systems as MS-Windows, Nextstep, Haiku and Android are not aligned with those under X. Each of these window system improvises its own selection mechanism without employing the “selection converter” mechanism illustrated in the preceding node. Only the PRIMARY, CLIPBOARD, and SECONDARY selections are generally supported, with the XdndSelection selection that records drag-and-drop data also available under Nextstep and Haiku.

GTK seeks to emulate the X selection system, but its emulations are not altogether dependable, with the overall quality of each subject to the GDK backend being used. Therefore, Emacs built with PGTK will supply the same selection interface as Emacs built with X, but many selection targets will not be useful.

Although a clipboard exists, there is no concept of primary or secondary selections within the MS-Windows operating system. On this system, Emacs simulates the presence of a primary and secondary selection, while saving to and retrieving from the clipboard when so requested.

The simulation of the primary and secondary selections is conducted by saving values supplied to gui-set-selection within the x-selections property of the symbol designating the pertinent selection, namely the type argument to gui-get-selection. Each subsequent call to gui-get-selection in turn returns its value, which is not subject to further examination (such as type checks and the like). Under such circumstances, data-type argument is generally disregarded. (But see below for the qualification regarding TARGETS.)

Where the clipboard selection is concerned (whenever type is CLIPBOARD), gui-set-selection verifies that the value provided is a string and saves it within the system clipboard once it is encoded by the coding system configured in selection-coding-system. Callers of gui-get-selection are required to set data-type to either STRING or TARGETS.

When data-type is set to TARGETS in a call to gui-get-selection, a vector of symbols is returned when selection data exists, much as it is under X. It is impossible to request clipboard data in any format besides STRING, for the prerequisite data conversion routines are absent. Just as strings saved into the clipboard are encoded by the selection-coding-system, so those read from the clipboard are decoded by that same coding system; this variable and its cousin next-selection-coding-system merit particular scrutiny when difficulties are encountered with saving selection text into the clipboard.

All three selections standard in X exist in Nextstep as well, but Emacs is only capable of saving strings to such selections. Restrictions imposed upon calls to gui-set-selection there are much the same as those on MS-Windows, though text is uniformly encoded as utf-8-unix without regard to the value of selection-coding-system. gui-get-selection is more charitable, and accepts requests for the following selection targets:

• text/plain
• image/png
• text/html
• application/pdf
• application/rtf
• application/rtfd
• STRING
• text/plain
• image/tiff

The XdndSelection selection is also present under Nextstep, in the form of a repository that records values supplied to gui-set-selection. Its sole purpose is to save such values for the fundamental drag-and-drop function x-begin-drag (see Drag and Drop); no guarantees exist concerning its value when read by anything else.

Selections on Haiku systems comprise all three selections customary under X and the XdndSelection that records drag-and-drop data.

When gui-set-selection is called for the former three selections, the data supplied is converted into a window server “message” by a list of selection encoder functions, which is sent to the window server.

Variable: haiku-normal-selection-encoders ¶

List of selection encoder functions. When gui-set-selection is called, each function in this list is successively called with its selection and value arguments. If such a function returns non-nil, its return value must be a list of the form (key type value). In this list, key must be the name of the data being transferred, generally that of a MIME type, for example ‘"text/plain"’, and type is a symbol or a number designating the type of the data; thus also governing the interpretation of value; following is a list of valid data types and how each of them will cause value to be interpreted.

string

A unibyte string. The string is NULL-terminated after being placed in the message.

ref

A file name. The file is located and the inode identifying the file is placed in the message.

short

A 16-bit integer value.

long

A 32-bit integer value.

llong

A 64-bit integer value.

byte

char

An unsigned byte between 0 and 255.

size_t

A number between 0 and 1 minus two to the power of the word size of the computer Emacs is running on.

ssize_t

A number which fits in the C type ssize_t.

point

A cons of two floats, specifying a coordinate on-screen.

float

double

A single or double-precision floating point number in an unspecified format.

(haiku-numeric-enum MIME)

A unibyte string containing data in a certain MIME type.

A call to gui-get-selection generally returns the data named data-type within the selection message, albeit with data-type replaced by an alternative name should it be one of the following X selection targets:

STRING

This represents Latin-1 text under X: “text/plain;charset=iso-8859-1”

UTF8_STRING

This represents UTF-8 text: “text/plain”

If data-type is a text type such as STRING or a MIME type matching the pattern ‘`text/*’, the string data is decoded with the coding system apposite for it before being returned.

Furthermore, the two data types TIMESTAMP and TARGETS are afforded special treatment; the value returned for the first is the number of times the selection has been modified since system startup (not a timestamp), and that for the other is a vector of available selection data types, as elsewhere.

Much like MS-Windows, Android provides a clipboard but no primary or secondary selection; gui-set-selection simulates the primary and secondary selections by saving the value supplied into a variable subsequent calls to gui-get-selection return.

From the clipboard, gui-get-selection is capable of returning UTF-8 string data of the type STRING, the TARGETS data type, or image and application data of any MIME type. gui-set-selection sets only string data, much as under MS-Windows, although this data is not affected by the value of selection-coding-system. By contrast, only string data can be saved to and from the primary and secondary selections; but since this data is not communicated to programs besides Emacs, it is not subject to encoding or decoding by any coding system.