@cindex secondary selection
In window systems, such as X, data can be transferred between
-different applications by means of @dfn{selections}. X defines an
-arbitrary number of @dfn{selection types}, each of which can store its
-own data; however, only three are commonly used: the @dfn{clipboard},
-@dfn{primary selection}, and @dfn{secondary selection}. Other window
-systems support only the clipboard. @xref{Cut and Paste,, Cut and
-Paste, emacs, 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.
+different applications by means of @dfn{selections}. Each window
+system defines an arbitrary number of @dfn{selection types}, all
+storing their own data; however, only three are commonly used: the
+@dfn{clipboard}, @dfn{primary selection}, and @dfn{secondary
+selection}. @xref{Cut and Paste,, Cut and Paste, emacs, 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; @xref{Accessing Selections} for
+documentation concerning selection types and data formats under
+particular window systems.
@deffn Command gui-set-selection type data
This function sets a window-system selection. It takes two arguments:
a selection type @var{type}, and the value to assign to it, @var{data}.
@var{type} should be a symbol; it is usually one of @code{PRIMARY},
-@code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
-upper-case names, in accord with X Window System conventions. If
+@code{SECONDARY} or @code{CLIPBOARD}. These are generally symbols
+with upper-case names, in accord with X Window System conventions. If
@var{type} is @code{nil}, that stands for @code{PRIMARY}.
If @var{data} is @code{nil}, it means to clear out the selection.
The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another program into Lisp
-data. Meaningful values include @code{TEXT}, @code{STRING},
-@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
-@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
-@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
-@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
-@code{INTEGER}. (These are symbols with upper-case names in accord
-with X conventions.) The default for @var{data-type} is
-@code{STRING}. Window systems other than X usually support only a
-small subset of these types, in addition to @code{STRING}.
+data. @xref{X Selections} for an enumeration of data types valid
+under X, and @xref{Other Selections} for those elsewhere.
@end defun
@defopt selection-coding-system
converts to the text representation that X11 normally uses.
@end defopt
-@cindex clipboard support (for MS-Windows)
-When Emacs runs on MS-Windows, it does not implement X selections in
-general, but it does support the clipboard. @code{gui-get-selection}
-and @code{gui-set-selection} on MS-Windows support the text data type
-only; if the clipboard holds other types of data, Emacs treats the
-clipboard as empty. The supported data type is @code{STRING}.
-
For backward compatibility, there are obsolete aliases
@code{x-get-selection} and @code{x-set-selection}, which were the
names of @code{gui-get-selection} and @code{gui-set-selection} before
@node Accessing Selections
@section Accessing Selections
- @code{gui-get-selection} is able to retrieve multiple different
-kinds of selection data from any number of selections. However, the
-data types and selections that Emacs understands is not precisely
-specified and differs depending on the window system on which Emacs is
-running.
-
- At the same time, @code{gui-set-selection} hides a great deal of
-complexity behind its back, at least on some systems: its @var{data}
-argument need not be a string, but is actually given verbatim to
-system specific code.
-
- Emacs's implementation of selections is most complete on the X
-Window System. This is both an artifact of history (X was the first
-window system supported by Emacs) and one of technical reasons:
-instead of using selections only to transfer text and multimedia
-content between clients, X uses selections as a general inter-client
-communication system, leading to a great proliferation of selection
-data types.
-
- Even more confusingly, X also supports another inter-client
-communication mechanism: the Inter-Client Exchange. However, ICE is
+ The data types and selections that @code{gui-get-selection} and
+@code{gui-set-selection} understand are not precisely specified and
+differ subject to the window system on which Emacs is running.
+
+ At the same time, @code{gui-set-selection} abstracts over plenty of
+complexity: its @var{data} argument is given verbatim to
+system-specific code to be rendered suitable for transfer to the
+window system or requesting clients.
+
+ The most comprehensive implementation of selections is that under
+the X Window System. This is both an artifact of history (X was the
+first window system supported by Emacs) and one occasioned by
+technical considerations: X selections are not merely an expedient for
+the transfer of text and multimedia content between clients, but a
+general inter-client communication system, a design that has yielded a
+proliferation of selection and data types.
+
+ Compounding this confusion, there is another inter-client
+communication mechanism under X: the Inter-Client Exchange. ICE is
only used by Emacs to communicate with session managers, and is a
separate topic.
@node X Selections
@subsection X Selections
- X refrains from defining fixed data types for selection data, or a
-fixed number of selections. Selections are instead identified by X
-``atoms'', which are unique 29-bit identifiers issued by the X server
-for a corresponding name. In Emacs, you can simply write a symbol
-with the name of the atom, and Emacs will transparently request these
-identifiers where necessary.
+ 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
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 took ownership over the selection, which then
-replies with the requested data.
+the window which last asserted ownership over the selection, which
+which is expected to respond with the requested data.
- Each selection request contains three parameters:
+ Each selection request incorporates three parameters:
@itemize @bullet
@item
-The window which requested the selection; this is used to identify the
+The window which requested the selection, which identifies the
@c Not a typo: X spells ``requestor'' with an o.
requesting program, otherwise known as the @dfn{requestor}.
@item
-An atom identifying the ``target'' to which the owner should convert
+An atom identifying the @dfn{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 @dfn{type} argument to
+Emacs, the target is determined by the @var{type} argument to
@code{gui-get-selection}.
@item
-A 32-bit timestamp containing the X server time at which the requestor
-last obtained input.
+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.
@end itemize
The selection owner responds by tranferring to the requestor a
returns.
By default, Emacs converts selection data consisting of any series
-of bytes to a unibyte string containing those bytes, selection data
-consisting of a single 16-bit or 32-bit word as an unsigned number,
-and selection data consisting of multiple such words as a vector of
-unsigned numbers. However, Emacs applies special treatment for
-several selection data types:
+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.
+However, Emacs applies special treatment for data from the following
+conversion targets:
@table @code
@item INTEGER
-16-bit or 32-bit words of this type are treated as signed integers,
-instead of unsigned ones. If there are multiple words in the
-selection data, a vector is returned; otherwise, the integer is
-returned by itself.
+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.
@item ATOM
32-bit words of this type are treated as X atoms, and returned (either
-alone or as vectors) as Lisp symbols containing the names they
-identify. Invalid atoms are returned as @code{nil}.
+alone or as vectors) as Lisp symbols by the names they identify.
+Invalid atoms are replaced by @code{nil}.
@item COMPOUND_TEXT
@item UTF8_STRING
@item STRING
-Unibyte strings returned for these data types will have a single
-@code{foreign-selection} text property set to a symbol with the type
-of the selection data.
+A single @code{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.
@end table
Each selection owner must return at least two selection targets:
Consortium's
@url{http://x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html,
Inter-Client Communication Conventions Manual}, while others, such as
-@code{UTF8_STRING}, were supposed to be standardized by the XFree86
-Project, which unfortunately did not happen.
+@code{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 @dfn{polymorphic target}.
-A selection target may also return no data at all: by convention, the
-selection owner performs some action a side effect upon responding to
-a selection request with that target, and as such these targets are
-referred to as @dfn{side-effect targets}.
+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 @dfn{side-effect
+targets}.
- Here are some selection targets which behave in a reasonably
-standard manner when used with the @code{CLIPBOARD}, @code{PRIMARY},
-or @code{SECONDARY} selections.
+ Here are some selection targets whose behavior is generally
+consistent with a standard when requested from the @code{CLIPBOARD},
+@code{PRIMARY}, or @code{SECONDARY} selections.
@table @code
@item ADOBE_PORTABLE_DOCUMENT_FORMAT
@item MODULE
This target returns the name of any function containing the selection
-data. It is mainly used by text editors.
+data. It is principally requested by text editors.
@item STRING
This target returns the selection data as a string of type
When a request for the targets @code{STRING}, @code{COMPOUND_TEXT},
or @code{UTF8_STRING} is made using the function
@code{gui-get-selection}, and neither @code{selection-coding-system}
-nor @code{next-selection-coding-system} are set, the returned strings
-are additionally decoded using the appropriate coding system for those
-data types: @code{iso-8859-1}, @code{compound-text-with-extensions}
-and @code{utf-8} respectively.
+nor @code{next-selection-coding-system} is set, the resultant strings
+are decoded by the proper coding systems for those targets:
+@code{iso-8859-1}, @code{compound-text-with-extensions} and
+@code{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 decided to define selection data types of
-their own, without consulting the appropriate X standards bodies.
-These targets are usually named after MIME types, such as
-@code{text/html} or @code{image/jpeg}, and have been known to contain:
+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 @code{text/html} or
+@code{image/jpeg}; they have been witnessed returning the following
+forms of data:
@itemize @bullet
@item
Image or text data in the appropriate format.
@item
-@code{file://} URIs (or possibly newline or NUL terminated lists of
-URIs) leading to files in the appropriate format.
+@code{file://} URIs (or conceivably newline or NUL terminated lists of
+URIs) identifying files in the appropriate format.
@end itemize
These selection targets were first used by Netscape, but are now
-found in all kinds of programs, especially those based on recent
+proffered by all kinds of programs, especially those based on recent
versions of the GTK+ or Qt toolkits.
- Emacs is also capable of acting as a selection owner. When
-@code{gui-set-selection} is called, the selection data specified is
-not transferred to the X server; instead, Emacs records it internally
-and obtains ownership of the selection.
+ Emacs is also capable of serving as a selection owner. When
+@code{gui-set-selection} is called, the selection data provided is
+recorded internally and Emacs obtains ownership of the selection being
+set.
@defvar selection-converter-alist
- Alist of selection targets to ``selection converter'' functions.
-When a selection request is received, Emacs looks up the selection
-converter associated with the requested selection target.
+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.
- The selection converter is called with three arguments: the symbol
+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
-@code{gui-set-selection}. The value which it returns is either a cons
-of a symbol specifying the data type and a number, symbol, or a vector
-of numbers or symbols, or its cdr by itself.
+@code{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 the value is the special symbol @code{NULL}, the data type is set
-to @code{NULL}, and no data is returned to the requestor.
+If a selection converter's value is the special symbol @code{NULL},
+the data type returned to its requestor is set to @code{NULL}, and no
+data is sent in response.
- If the value is a string, it must be a unibyte string; should no
-data type be explicitly specified, the data is transferred to the
+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 @code{STRING}.
- If the value is a symbol, its ``atom'' is retrieved, and it is
-transferred to the requestor as a 32-bit value---if no data type was
-specified, its type is @code{ATOM}.
+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 @code{ATOM}.
- If the value is a number between @code{-32769} and @code{32768}, it
-is transferred to the requestor as a 16 bit value---if no data type
-was specified, its type is @code{INTEGER}.
+If it is a number between @code{-32769} and @code{32768}, it is
+transferred to its requestor as a 16 bit value---if no data type is
+specified, its type is @code{INTEGER}.
- If the value is any other number, it is returned as a 32 bit value.
-Even if the number returned is unsigned, the requestor will treat
-words of type @code{INTEGER} as signed. To return an unsigned value,
-specify the type @code{CARDINAL} instead.
+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 @code{INTEGER} as signed. To return an unsigned value, specify
+the type @code{CARDINAL} in its place.
- If the value is a vector of symbols or numbers, it is returned as a
-list of multiple atoms or numbers. The data type returned by default
-is determined by that of its first element.
+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.
@end defvar
By default, Emacs is configured with selection converters for the
@end table
With the exception of @code{INTEGER}, all selection converters
-expect the value given to @code{gui-set-selection} to be one of the
+expect the data provided to @code{gui-set-selection} to be one of the
following:
@itemize @bullet
projects / emacs.git / commitdiff