From: Po Lu Date: Sat, 8 Apr 2023 01:35:19 +0000 (+0800) Subject: Document selections on Android more thoroughly X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=3695ae4d6359b12dddd1ca59a4f4d9f8a38fbd04;p=emacs.git Document selections on Android more thoroughly * doc/lispref/elisp.texi (Top): * doc/lispref/frames.texi (Frames): Add ``Accessing Selections'' to menu. (Accessing Selections, X Selections, Other Selections): New nodes. --- diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a1d7b51b609..72441c8d442 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1139,6 +1139,7 @@ Frames * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other X clients. +* Accessing Selections:: The multiple different kinds of selections. * Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 9083b4b01c9..7a752c1f6a9 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -108,6 +108,7 @@ window of another Emacs frame. @xref{Child Frames}. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. +* Accessing Selections:: The multiple different kinds of selections. * Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. @@ -4059,6 +4060,539 @@ For backward compatibility, there are obsolete aliases names of @code{gui-get-selection} and @code{gui-set-selection} before Emacs 25.1. +@node Accessing Selections +@section Accessing Selections + + @code{gui-get-selection} is able to retrieve multiple different +kinds of selection data. However, the exact data types which 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 implements selections most completely 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 +only used by Emacs to communicate with session managers, and is a +separate topic. + +@menu +* X Selections:: Selection data types (and more) on X. +* Other Selections:: How they work on other window systems. +@end menu + +@node X Selections +@section 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 name of the atom, and Emacs will transparently request these +identifiers where necessary. + + When a program ``sets'' a selection under X, it actually takes +ownership 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 took ownership over the selection. + + Each selection request contains three parameters: + +@itemize @bullet +@item +The window which requested the selection; this is used to identify 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 +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 +@code{gui-get-selection}. + +@item +A 32-bit timestamp containing the X server time at which the requestor +last obtained input. +@end itemize + + The selection owner responds by tranferring 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 @code{gui-get-selection} +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: + +@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. + +@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}. + +@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. +@end table + + Each selection owner must return at least two selection targets: +@code{TARGETS}, which returns a number of atoms describing the +selection targets that the owner supports, and @code{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 +@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. + + 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}. + + Here are some selection targets which behave in a reasonably +standard manner when used with the @code{CLIPBOARD}, @code{PRIMARY}, +or @code{SECONDARY} selections. + +@table @code +@item ADOBE_PORTABLE_DOCUMENT_FORMAT +This target returns data in Adobe System's ``Portable Document +Format'' format, as a string. + +@item APPLE_PICT +This target returns data in the ``PICT'' image format used on +Macintosh computers, as a string. + +@item BACKGROUND +@item BITMAP +@item COLORMAP +@item 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. + +@item CHARACTER_POSITION +This target returns two unsigned 32-bit integers of type @code{SPAN} +describing the start and end positions of the selection data in the +text field containing it, in bytes. + +@item COMPOUND_TEXT +This target returns a string of type @code{COMPOUND_TEXT} in the X +Consortium's multi-byte text encoding system. + +@item DELETE +This target returns nothing, but as a side-effect deletes the +selection contents from any text field containing them. + +@item DRAWABLE +@item PIXMAP +This target returns a list of unsigned 32-bit integers, each of which +corresponds to an X server drawable or pixmap. + +@item ENCAPSULATED_POSTSCRIPT +@item _ADOBE_EPS +This target returns a string containing encapsulated Postscript code. + +@item FILE_NAME +This target returns a string containing one or more file names, +separated by NULL characters. + +@item HOST_NAME +This target returns a string containing the fully-qualified domain +name of the machine on which the selection owner is running. + +@item USER +This target returns a string containing the user name of the machine +on which the selection owner is running. + +@item LENGTH +This target returns an unsigned 32-bit or 16-bit integer containing +the length of the selection data. + +@item LINE_NUMBER +This target returns two unsigned 32-bit integers of type @code{SPAN} +describing the line numbers corresponding to the start and end +positions of the selection data in the text field containing it. + +@item MODULE +This target returns the name of any function containing the selection +data. It is mainly used by text editors. + +@item STRING +This target returns the selection data as a string of type +@code{STRING}, encoded in ISO Latin-1 format, with Unix newline +characters. + +@item 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. + +@item UTF8_STRING +This returns the selection data as a string of type +@code{UTF8_STRING}, encoded in UTF-8, with unspecified EOL format. + +@item 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 +@code{CARDINAL}. + +@item TEXT +This polymorphic target returns selection data as a string, either +@code{COMPOUND_TEXT}, @code{STRING}, @code{C_STRING}, or +@code{UTF8_STRING}, whichever data type is convenient for the +selection owner. +@end table + + 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. + + 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: + +@itemize @bullet +@item +Unterminated, newline terminated, or NULL character terminated file +names of an image or text file. + +@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. +@end itemize + + These selection targets were first used by Netscape, but are now +found in 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. + +@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. + + The selection converter is 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. + + 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 the value is a string, it must be a unibyte string; should no +data type be explicitly specified, the data is transferred to the +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 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 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 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. +@end defvar + + By default, Emacs is configured with selection converters for the +following selection targets: + +@table @code +@item TEXT +This selection converter returns selection data as: + +@itemize @bullet +@item +A string of type @code{C_STRING}, if the selection contents contain no +multibyte characters, or contains 8-bit characters with all 8 bits +set. + +@item +A string of type @code{STRING}, if the selection contents can be +represented as ISO-Latin-1 text. + +@item +A string of type @code{COMPOUND_TEXT}, if the selection contents can +be encoded in the X Consortium's Compound Text Encoding, and +@code{selection-coding-system} or @code{next-selection-coding-system} +is set to a coding system whose @code{:mime-charset} property is +@code{x-ctext}. + +@item +A string of type @code{UTF8_STRING} otherwise. +@end itemize + +@item COMPOUND_TEXT +This selection converter returns selection data as a string of type +@code{COMPOUND_TEXT}. + +@item STRING +This selection converter returns selection data as a string of type +@code{STRING}, encoded in ISO-Latin-1 format. + +@item UTF8_STRING +This selection converter returns selection data in UTF-8 format. + +@item text/plain +@item text/plain;charset=utf-8 +@item text/uri-list +@item text/x-xdnd-username +@item XmTRANSFER_SUCCESS +@item XmTRANSFER_FAILURE +@item FILE +@item _DT_NETFILE +These selection converters are used for internal purposes during +drag-and-drop operations and are not available for selections other +than @code{XdndSelection}. + +@item TARGETS +This selection converter returns a list of atoms, one for each +selection target understood by Emacs. + +@item 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. + +@item LENGTH +This selection converter returns the length of the selection data, in +bytes. + +@item DELETE +This selection converter is used for internal purposes during +drag-and-drop operations. + +@item FILE_NAME +This selection converter returns the file name of the buffer +containing the selection data. + +@item CHARACTER_POSITION +This selection converter returns the character positions of each end +of the selection in the buffer containing the selection data. + +@item LINE_NUMBER +@item COLUMN_NUMBER +This selection converter returns the line and column numbers of each +end of the selection in the buffer containing the selection data. + +@item OWNER_OS +This selection converter returns the name of the operating system on +which Emacs is running. + +@item HOST_NAME +This selection converter returns the fully-qualified domain name of +the machine on which Emacs is running. + +@item USER +This selection converter returns the username of the user account +under which Emacs is running. + +@item CLASS +@item NAME +These selection converters return the resource class and name used by +Emacs. + +@item INTEGER +This selection converter returns an integer value verbatim. + +@item SAVE_TARGETS +@item _EMACS_INTERNAL +These selection converters are used for internal purposes. +@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 +following: + +@itemize @bullet +@item +A string. + +@item +A list of the form @w{@code{(@var{beg} @var{end} @var{buf})}}, where +@var{beg} and @var{end} are two markers or overlays describing the +bounds of the selection data in the buffer @var{buf}. +@end itemize + +@node Other Selections +@section Other Selections + + Window systems such as MS-Windows, Nextstep, Haiku and Android do +not provide selections corresponding to the X semantics. Each window +system provides its own ad-hoc emulation of selections, none of which +make use of the ``selection converter'' mechanism described above. In +addition, only the @code{PRIMARY}, @code{CLIPBOARD}, and +@code{SECONDARY} selections are typically supported, alongside the +@code{XdndSelection} used for drag-and-drop operations. + + GTK itself exposes emulations of X selections to applications, but +those emulations are of varying completeness. While Emacs built with +PGTK will use the same selection interface as Emacs built with X, many +selection targets will not be useful. + + On MS-Windows, @code{gui-get-selection} accepts a single target, +@code{STRING}. The value returned is the selection data decoded +using @code{selection-coding-system}. + + @code{gui-set-selection} also only accepts strings, encodes them +in the selection coding system, and saves them to the clipboard. + + On Nextstep, Emacs only supports saving strings to selections. +However, requests for the following targets are accepted: + +@c FIXME: how is the text coding system determined, and do image/* or +@c application/* return image data or file names? +@itemize @bullet +@item text/plain +@item image/png +@item text/html +@item application/pdf +@item application/rtf +@item application/rtfd +@item STRING +@item text/plain +@item image/tiff +@end itemize + + On Haiku, Emacs supports the same selection values as on X. In +addition, Emacs fully implements the primary and secondary selections. +However, instead of taking ownership over the selection data, Emacs +transfers the selection data to the window server when +@code{gui-set-selection} is called. The Haiku window server expects +selection data to be provided in the form of a ``message'', containing +associations between data types and selection data. + +@defvar haiku-normal-selection-encoders +List of functions which act as selection encoders. When +@code{gui-set-selection} is called, each function in this list is +successively called with its @var{selection} and @var{value} +arguments. If the function returns non-@code{nil}, it should return a +list of the form @w{@code{(@var{key} @var{type} @var{value})}}, where +@var{key} is the name of the data type being transferred, @var{type} +is either a number identifying a data type (in which case @var{value} +should be a unibyte string that is directly transferred to the window +server), or a symbol identifying both a data type and how @var{value} +should be interpreted. +@end defvar + + Here are the meaningful values of @var{type}, and what they will +cause Emacs to interpret @var{value} as: + +@table @code +@item string +A unibyte string. The string is NULL-terminated after being placed in +the message. + +@item ref +A file name. The file is looked up and file system information +identifying the file is placed in the message. + +@item short +A 16-bit integer value. + +@item long +A 32-bit integer value. + +@item llong +A 64-bit integer value. + +@item byte +@item char +An unsigned byte between 0 and 255. + +@item size_t +A number between 0 and 1 minus two to the power of the word size of +the computer Emacs is running on. + +@item ssize_t +A number which fits in the C type @code{ssize_t}. + +@item point +A cons of two floats, specifying a coordinate on-screen. + +@item float +@item double +A single or double-precision floating point number in an unspecified +format. + +@item (haiku-numeric-enum MIME) +A unibyte string containing data in a certain MIME type. +@end table + + Under Haiku, @code{gui-get-selection} accepts either the targets +@code{TARGETS} and @code{TIMESTAMP}, where the former returns a vector +containing supported data types (much like on X), and the latter +returns the number of times the selection has been set, the targets +@code{STRING} and @code{UTF8_STRING}, which return text in ISO-Latin-1 +and UTF-8 format, or a MIME type, in which the data is returned +undecoded as a unibyte string. + + Under Android, @code{gui-get-selection} is restricted to returning +UTF-8 string data of the type @code{STRING}, or image and application +data associated with a MIME type. @code{gui-set-selection} will only +set string data, as on MS-Windows. + @node Yanking Media @section Yanking Media