--- lispref.texi.orig Sat Apr 1 17:42:47 2000 +++ lispref.texi Sat Nov 18 15:50:25 2000 @@ -823,7 +823,8 @@ position stored in a register. * Transposition:: Swapping two portions of a buffer. * Change Hooks:: Supplying functions to be run when text is changed. - +* Selections:: Window-system selections. + The Kill Ring * Kill Ring Concepts:: What text looks like in the kill ring. --- text.texi.orig Thu Dec 23 02:50:37 1999 +++ text.texi Sat Nov 18 15:50:01 2000 @@ -54,6 +54,7 @@ * Transposition:: Swapping two portions of a buffer. * Change Hooks:: Supplying functions to be run when text is changed. * Transformations:: MD5 and base64 support. +* Selections:: Window-system selections. @end menu @node Near Point @@ -862,9 +863,10 @@ then that value is used as the ``most recent kill''. If it returns @code{nil}, then the first element of @code{kill-ring} is used. -The normal use of this hook is to get the X server's primary selection -as the most recent kill, even if the selection belongs to another X -client. @xref{X Selections}. +The normal use of this hook is to get the window system's default selection +(which could be the @b{Primary} selection, but might also be the @b{Clipboard} +selection on some window systems) as the most recent kill, even if that +selection belongs to another window system client. @xref{Selections}. @end defvar @defvar interprogram-cut-function @@ -2721,7 +2723,7 @@ that was previously in the unmodified state. @end defvar -@node Transformations +@node Transformations, Selections, Change Hooks, Text @section Textual transformations---MD5 and base64 support @cindex MD5 digests @cindex base64 @@ -2855,4 +2857,193 @@ @result{} nil @end group @end example +@end defun + +@node Selections, , Transformations, Text +@subsection Selections +@cindex selection +@cindex selections +@cindex clipboard + +XEmacs has unified support for window-system selection models; this support +functions on systems that natively support the X-style selection concept, +as well as those (perhaps the majority of non-X systems) that support the +clipboard model. The XEmacs selection model is not, however, dependent +on the presence of a window-system, and in fact only a few special selections +are used by the window-system. + +A selection is identified by a Lisp symbol; three symbols are currently +treated specially by window-system code: + +@itemize @bullet +@item +@code{PRIMARY} represents the window-system's primary selection (on +window-systems that have native selection support - e.g. X). + +@item +@code{SECONDARY} represents the window-system's secondary selection (again, +on window-systems that have native support for the selection concept - e.g. X). + +@item +@code{CLIPBOARD} represents the window-system clipboard. +@end itemize + +Users are free to create their own new selections and set them as they +see fit (though it should be understood that user-defined selections will +not be visible to other applications). + +Each selection has a set of @code{} pairs associated with it; +@code{type} is a symbol representing the type of data stored, and @code{data} +can be any valid Lisp object that is meaningful for the specified @code{type}. +The three most common data types currently are: + +@itemize @bullet +@item +@code{TEXT} specifies that @code{data} is a string, an extent or a +cons of two markers. @code{COMPOUND_TEXT} is a synonym for @code{TEXT}; +XEmacs automatically uses the compound text selection data format on the +X window system. + +@item +@code{STRING} specifies that @code{data} is an ordinary string. + +@item +@code{CF_TEXT} specifies that @code{data} is a Microsoft Windows format +string (i.e. with CR-LF line endings and a NUL terminator). On Win32 platforms, +all clipboard formats described in the Microsoft Platform SDK have predefined +symbols beginning @code{CF_}. +@end itemize + +@menu +* Manipulating Selections:: Commands that manipulate window-system selections +* Selection Data Types:: Support for selections of different data types +@end menu + +@node Manipulating Selections, Selection Data Types, Selections, Selections +@subsection Manipulating Selections +@cindex selection commands +@cindex manipulating selections + +Three core functions provide the XEmacs selection functionality: + +@defun own-selection data &optional type how-to-add data-type +Make a selection of type @var{type} and value @var{data}. +The argument @var{type} (default @code{PRIMARY}) says which selection, +and @var{data} specifies the contents. @var{data} may be any lisp data type +that can be converted using the function corresponding to @var{data-type} +in `select-convert-out-alist'---strings are the usual choice, but +other types may be permissible depending on the @var{data-type} parameter +(if @var{data-type} is not supplied, the default behaviour is window +system specific, but strings are always accepted). + +@var{how-to-add} may be any of the following: + +@itemize @bullet +@item +@code{replace-all} or @code{nil}---replace all data in the selection. + +@item +@code{replace-existing}---replace data for specified DATA-TYPE only. + +@item +@code{append} or @code{t}---append data to existing DATA-TYPE data. +@end itemize + +@var{data-type} is the window-system specific data type identifier, +most commonly @code{TEXT} or @code{STRING}; the +@code{register-selection-data-type} function may be used to register +new system-wide data types if your window-system supports it (currently +this is only the case on Microsoft Windows platforms). +@xref{Selection Data Types} + +The selection may also be a cons of two markers pointing to the same buffer, +or an overlay. In these cases, the selection is considered to be the text +between the markers @emph{at whatever time the selection is examined} (note +that the window system clipboard does not necessarily duplicate this +behaviour - it doesn't on Microsoft Windows for example). +Thus, editing done in the buffer after you specify the selection +can alter the effective value of the selection. + +The data may also be a vector of valid non-vector selection values. +@end defun + +@defun get-selection &optional type data-type +This function accesses selections set up by XEmacs or by other X +clients. It returns the value of the selection specified by @code{type}; +the @code{data-type} argument allows the caller to request a specific +data format (the default is @code{STRING}, or @code{COMPOUND_TEXT} under +Mule). If there is no selection, the function returns @code{nil}. +@end defun + +@defun disown-selection &optional secondary-p +Assuming we own the selection, this function disowns it. If +@var{secondary-p} is non-@code{nil}, the @code{SECONDARY} selection instead of +the @code{PRIMARY} selection is discarded. +@end defun + +@node Selection Data Types, , Selections, Selections +@subsection Selection Data Types +@cindex selection data types + +If your window-system supports it, XEmacs can register data types with it +and transfer them via the three special window-system selections. This is +achieved by using the @code{register-selection-data-type} function: + +@defun register-selection-data-type data-type &optional device +Register a new selection data type with the name @code{data-type} (a string), +optionally on the specified @code{device}. Returns a device-specific data +type identifier that may be used as the @code{data-type} parameter in +the @code{own-selection} or @code{get-selection} functions. +@end defun + +Support for selection data-types is dependent on six variables that specify +how the selection code should handle data of a particular type. + +@defvar selection-coercible-types +A list of @code{data-type} values that specifies data types from which +XEmacs should attempt automatic coercion; if data of the specified type is not +available to XEmacs when the user calls @code{get-selection}, it may search +the selection to find one of the types in this list. Upon finding data in +one of these types, XEmacs will then search @code{selection-coercion-alist} +for a function that can convert it to the target type. +@end defvar + +@defvar selection-coercion-alist +See @code{selection-coercible-types}. +@end defvar + +@defvar selection-appender-alist +A list of @code{(data-type . handler-function)} cons pairs that provide XEmacs +with a way of finding a function suitable for appending data onto data of +a specified type that is already in a selection. Functions in this list take +four parameters---@code{selection}, @code{data-type}, @code{value1} and +@code{value2}. +@end defvar + +@defvar selection-converter-out-alist +A list of @code{(data-type . handler-function)} cons pairs that give XEmacs +a mapping between @code{data-type} and handler functions that can convert +from a suitable Lisp data format (e.g. a string, an integer or a list) to a +suitable external data format for the data type in question. (X users please +note, there is some grotty code in @file{select-x.c} that restricts the +utility of this arrangement.) +@end defvar + +@defvar selection-converter-in-alist +A list of @code{(data-type . handler-function)} cons pairs that give XEmacs +a mapping between @code{data-type} and handler functions that can convert +from the external data format to a suitable Lisp data format (e.g. a string, +an integer or a list) to a for the data type in question. (X users please +note, there is some grotty code in @file{select-x.c} that restricts the +utility of this arrangement.) +@end defvar + +Handler functions in these alists take three values as follows, unless otherwise +noted: + +@defun selection-handler-function selection-type data-type value +@code{selection-type} is the selection in question (e.g. @code{PRIMARY}), +@code{data-type} is the specified data-type (this allows a single handler +function to handle conversions to several different data types), and +@code{value} is the value to convert. @end defun --- x-windows.texi.orig Fri Jan 28 11:27:32 2000 +++ x-windows.texi Sat Nov 18 15:50:22 2000 @@ -34,32 +34,8 @@ symbols. X clients including XEmacs can read or set the selection for any given type. -@defun x-own-selection data &optional type -This function sets a ``selection'' in the X server. It takes two -arguments: a value, @var{data}, and the selection type @var{type} to -assign it to. @var{data} may be a string, a cons of two markers, or an -extent. In the latter cases, the selection is considered to be the text -between the markers, or between the extent's endpoints. - -Each possible @var{type} has its own selection value, which changes -independently. The usual values of @var{type} are @code{PRIMARY} and -@code{SECONDARY}; these are symbols with upper-case names, in accord -with X Windows conventions. The default is @code{PRIMARY}. - -(In FSF Emacs, this function is called @code{x-set-selection} and -takes different arguments.) -@end defun - -@defun x-get-selection -This function accesses selections set up by XEmacs or by other X -clients. It returns the value of the current primary selection. -@end defun - -@defun x-disown-selection &optional secondary-p -Assuming we own the selection, this function disowns it. If -@var{secondary-p} is non-@code{nil}, the secondary selection instead of -the primary selection is discarded. -@end defun +XEmacs now has unified support for selections that works in a window-system +independent way. @xref{Selections}. @cindex cut buffer The X server also has a set of numbered @dfn{cut buffers} which can