diff options
Diffstat (limited to 'doc/lispref/frames.texi')
| -rw-r--r-- | doc/lispref/frames.texi | 1195 |
1 files changed, 945 insertions, 250 deletions
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index dc38f90ed74..cf7fc7721c5 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -60,8 +60,12 @@ The frame is displayed on a GNUstep or Macintosh Cocoa graphical terminal. @item pc The frame is displayed on an MS-DOS terminal. +@item haiku +The frame is displayed using the Haiku Application Kit. @item pgtk The frame is displayed using pure GTK facilities. +@item android +The frame is displayed on an Android device. @end table @end defun @@ -104,9 +108,11 @@ window of another Emacs frame. @xref{Child Frames}. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. +* On-Screen Keyboards:: Displaying the virtual keyboard. * 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. @@ -222,8 +228,8 @@ The terminal and keyboard coding systems used on the terminal. @item The kind of display associated with the terminal. This is the symbol returned by the function @code{terminal-live-p} (i.e., @code{x}, -@code{t}, @code{w32}, @code{ns}, @code{pc}, @code{haiku}, or @code{pgtk}). -@xref{Frames}. +@code{t}, @code{w32}, @code{ns}, @code{pc}, @code{haiku}, @code{pgtk}, +or @code{android}). @xref{Frames}. @item A list of terminal parameters. @xref{Terminal Parameters}. @@ -527,7 +533,8 @@ Height | | | Height | | | Height | | | |<--+--- Inner Frame Width ------->| | | | | | | | | | | | | | | | |___v______________________________| | | | - | | |___________ Internal Border __________| | v + | | |___________ Internal Border __________| | | + | | (4)__________ Bottom Tool Bar __________| | v v |___________ External/Outer Border __________| <-------- Native Frame Width --------> @@ -603,7 +610,7 @@ frames (@pxref{Child Frames}) and @code{undecorated} or Outer borders are never shown on text terminal frames and on frames generated by GTK+ routines. On MS-Windows, the outer border is emulated with the help of a one pixel wide external border. Non-toolkit builds -on X allow to change the color of the outer border by setting the +on X allow changing the color of the outer border by setting the @code{border-color} frame parameter (@pxref{Layout Parameters}). @item Title Bar @@ -699,7 +706,7 @@ The position of the top left corner of the native frame specifies the indicate that position for the various builds: @itemize @w{} -@item (1) non-toolkit, Haiku, and terminal frames +@item (1) non-toolkit, Android, Haiku, and terminal frames @item (2) Lucid, Motif, and MS-Windows frames @@ -711,6 +718,10 @@ tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or those of the menu bar and the tool bar (non-toolkit and text terminal frames). +If the native position would otherwise be (2), but the tool bar is +placed at the bottom of the frame as depicted in (4), the native +position of the frame becomes that of the tab bar. + The native position of a frame is the reference position for functions that set or return the current position of the mouse (@pxref{Mouse Position}) and for functions dealing with the position of windows like @@ -848,8 +859,11 @@ native frame of @var{frame}). @item tool-bar-position This tells on which side the tool bar on @var{frame} is and can be one -of @code{left}, @code{top}, @code{right} or @code{bottom}. The only -toolkit that currently supports a value other than @code{top} is GTK+. +of @code{left}, @code{top}, @code{right} or @code{bottom}. + +The values @code{left} and @code{right} are only supported on builds +using the GTK+ toolkit; @code{bottom} is supported on all builds other +than NS, and @code{top} is supported everywhere. @item tool-bar-size A cons of the width and height of the tool bar of @var{frame}. @@ -990,12 +1004,12 @@ Negative parameter values position the right edge of the outer frame by frame's native rectangle) and the bottom edge by @var{-y} pixels up from the bottom edge of the screen (or the parent frame's native rectangle). -Note that negative values do not permit to align the right or bottom +Note that negative values do not permit aligning the right or bottom edge of @var{frame} exactly at the right or bottom edge of its display -or parent frame. Neither do they allow to specify a position that does +or parent frame. Neither do they allow specifying a position that does not lie within the edges of the display or parent frame. The frame parameters @code{left} and @code{top} (@pxref{Position Parameters}) -allow to do that, but may still fail to provide good results for the +allow doing that, but may still fail to provide good results for the initial or a new frame. This function has no effect on text terminal frames. @@ -1732,7 +1746,7 @@ Geometry}) of the frame, in characters. Normally, the functions that establish a frame's initial width or resize a frame horizontally make sure that all the frame's windows, vertical scroll bars, fringes, margins and vertical dividers can be displayed. This parameter, if -non-@code{nil} allows to make a frame narrower than that with the +non-@code{nil} enables making a frame narrower than that with the consequence that any components that do not fit will be clipped by the window manager. @@ -1743,7 +1757,7 @@ Geometry}) of the frame, in characters. Normally, the functions that establish a frame's initial size or resize a frame make sure that all the frame's windows, horizontal scroll bars and dividers, mode and header lines, the echo area and the internal menu and tool bar can be -displayed. This parameter, if non-@code{nil} allows to make a frame +displayed. This parameter, if non-@code{nil} enables making a frame smaller than that with the consequence that any components that do not fit will be clipped by the window manager. @@ -1804,14 +1818,14 @@ the first time. @vindex fit-frame-to-buffer-margins@r{, a frame parameter} @item fit-frame-to-buffer-margins -This parameter allows to override the value of the option -@code{fit-frame-to-buffer-margins} when fitting this frame to the buffer -of its root window with @code{fit-frame-to-buffer} (@pxref{Resizing -Windows}). +This parameter enables overriding the value of the option +@code{fit-frame-to-buffer-margins} when fitting this frame to the +buffer of its root window with @code{fit-frame-to-buffer} +(@pxref{Resizing Windows}). @vindex fit-frame-to-buffer-sizes@r{, a frame parameter} @item fit-frame-to-buffer-sizes -This parameter allows to override the value of the option +This parameter enables overriding the value of the option @code{fit-frame-to-buffer-sizes} when fitting this frame to the buffer of its root window with @code{fit-frame-to-buffer} (@pxref{Resizing Windows}). @@ -1892,13 +1906,13 @@ to not draw bottom dividers. @vindex menu-bar-lines@r{, a frame parameter} @item menu-bar-lines The number of lines to allocate at the top of the frame for a menu bar -(@pxref{Menu Bar}). The default is one if Menu Bar mode is enabled and -zero otherwise. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. For an -external menu bar (@pxref{Frame Layout}), this value remains unchanged -even when the menu bar wraps to two or more lines. In that case, the -@code{menu-bar-size} value returned by @code{frame-geometry} -(@pxref{Frame Geometry}) allows to derive whether the menu bar actually -occupies one or more lines. +(@pxref{Menu Bar}). The default is one if Menu Bar mode is enabled +and zero otherwise. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. +For an external menu bar (@pxref{Frame Layout}), this value remains +unchanged even when the menu bar wraps to two or more lines. In that +case, the @code{menu-bar-size} value returned by @code{frame-geometry} +(@pxref{Frame Geometry}) enables you to establish whether the menu bar +actually occupies one or more lines. @vindex tool-bar-lines@r{, a frame parameter} @item tool-bar-lines @@ -1909,9 +1923,11 @@ whenever the tool bar wraps (@pxref{Frame Layout}). @vindex tool-bar-position@r{, a frame parameter} @item tool-bar-position -The position of the tool bar when Emacs was built with GTK+. Its value -can be one of @code{top}, @code{bottom} @code{left}, @code{right}. The -default is @code{top}. +The position of the tool bar. Its value can be one of @code{top}, +@code{bottom} @code{left}, @code{right}. The default is @code{top}. + +It can be set to @code{bottom} on Emacs built with any toolkit other +than Nextstep, and @code{left} or @code{right} on builds using GTK+. @vindex tab-bar-lines@r{, a frame parameter} @item tab-bar-lines @@ -2207,8 +2223,10 @@ resource must also be set to the string @code{"extended"}. @item inhibit-double-buffering If non-@code{nil}, the frame is drawn to the screen without double buffering. Emacs normally attempts to use double buffering, where -available, to reduce flicker. Set this property if you experience -display bugs or pine for that retro, flicker-y feeling. +available, to reduce flicker; nevertheless, this parameter is provided +for circumstances where double-buffering induces display corruption, +and for those eccentrics wistful for the immemorial flicker that once +beset Emacs. @vindex skip-taskbar@r{, a frame parameter} @item skip-taskbar @@ -2398,6 +2416,7 @@ engine), and @code{harfbuzz} (font driver for OTF and TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs, The GNU Emacs Manual}). The @code{harfbuzz} driver is similarly recommended. On Haiku, there can be several font drivers (@pxref{Haiku Fonts,,, emacs, +The GNU Emacs Manual}), as on Android (@pxref{Android Fonts,,, emacs, The GNU Emacs Manual}). On other systems, there is only one available font backend, so it does @@ -3420,15 +3439,15 @@ parameter indicates the number of pixels where the frame @dfn{snaps} at the respective edge or corner of its parent frame. There are two ways to drag an entire child frame with the mouse: The -@code{drag-with-mode-line} parameter, if non-@code{nil}, allows to drag -a frame without minibuffer window (@pxref{Minibuffer Windows}) via the -mode line area of its bottommost window. The -@code{drag-with-header-line} parameter, if non-@code{nil}, allows to -drag the frame via the header line area of its topmost window. +@code{drag-with-mode-line} parameter, if non-@code{nil}, enables +dragging a frame without minibuffer window (@pxref{Minibuffer +Windows}) via the mode line area of its bottommost window. The +@code{drag-with-header-line} parameter, if non-@code{nil}, enables +dragging the frame via the header line area of its topmost window. In order to give a child frame a draggable header or mode line, the window parameters @code{mode-line-format} and @code{header-line-format} -are handy (@pxref{Window Parameters}). These allow to remove an +are handy (@pxref{Window Parameters}). These allow removing an unwanted mode line (when @code{drag-with-header-line} is chosen) and to remove mouse-sensitive areas which might interfere with frame dragging. @@ -3743,9 +3762,9 @@ This function displays a pop-up menu and returns an indication of what selection the user makes. The argument @var{position} specifies where on the screen to put the -top left corner of the menu. It can be either a mouse button event -(which says to put the menu where the user actuated the button) or a -list of this form: +top left corner of the menu. It can be either a mouse button or +@code{touchscreen-begin} event (which says to put the menu where the +user actuated the button) or a list of this form: @example ((@var{xoffset} @var{yoffset}) @var{window}) @@ -3830,6 +3849,30 @@ keymap. It won't be called if @code{x-popup-menu} returns for some other reason without displaying a pop-up menu. @end defvar +@node On-Screen Keyboards +@section On-Screen Keyboards + + An on-screen keyboard is a special kind of pop up provided by the +system, with rows of clickable buttons that act as a real keyboard. + + On certain systems (@pxref{On-Screen Keyboards,,,emacs, The Emacs +Manual}), Emacs is supposed to display and hide the on screen keyboard +depending on whether or not the user is about to type something. + +@defun frame-toggle-on-screen-keyboard frame hide +This function displays or hides the on-screen keyboard on behalf of +the frame @var{frame}. If @var{hide} is non-@code{nil}, then the +on-screen keyboard is hidden; otherwise, it is displayed. + +It returns whether or not the on screen keyboard @strong{may} have +been displayed, which should be used to determine whether or not to +hide the on-screen keyboard later. + +This has no effect if the system automatically detects when to display +the on-screen keyboard, or when it does not provide any on-screen +keyboard. +@end defun + @node Dialog Boxes @section Dialog Boxes @cindex dialog boxes @@ -3964,22 +4007,24 @@ defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos @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. @@ -4007,157 +4052,823 @@ programs. It takes two optional arguments, @var{type} and 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 @pxref{Other Selections} for those elsewhere. @end defun @defopt selection-coding-system -This variable specifies the coding system to use when reading and -writing selections or the clipboard. @xref{Coding -Systems}. The default is @code{compound-text-with-extensions}, which -converts to the text representation that X11 normally uses. +This variable provides a coding system (@pxref{Coding Systems}) which +is used to encode selection data, and takes effect on MS-Windows and +X@. It is also used in the MS-DOS port when it runs on MS-Windows and +can access the Windows clipboard text. + +On X, the value of this variable provides the coding system which +@code{gui-get-selection} will use to decode selection data for a +subset of text data types, and also forces replies to selection +requests for the polymorphic @code{TEXT} data type to be encoded by +the @code{compound-text-with-extensions} coding system rather than +Unicode. + +On MS-Windows, this variable is generally ignored, as the MS-Windows +clipboard provides the information about decoding as part of the +clipboard data, and uses either UTF-16 or locale-specific encoding +automatically as appropriate. We recommend to set the value of this +variable only on the older Windows 9X, as it is otherwise used only in +the very rare cases when the information provided by the clipboard +data is unusable for some reason. + +The default value of this variable is the system code page under +MS-Windows 95, 98 or Me, @code{utf-16le-dos} on Windows +NT/W2K/XP/Vista/7/8/10/11, @code{iso-latin-1-dos} on MS-DOS, and +@code{nil} elsewhere. @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 Emacs 25.1. +@node Accessing Selections +@section Accessing Selections + + 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 exists 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. + +@menu +* X Selections:: Selection data types (and more) on X@. +* Other Selections:: How they work on other window systems. +@end menu + +@node X Selections +@subsection X Selections + + 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: + +@itemize @bullet +@item +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 @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 @var{type} argument to +@code{gui-get-selection}. + +@item +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 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 @code{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: + +@table @code +@item INTEGER +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 by the names they identify. +Invalid atoms are replaced by @code{nil}. + +@item COMPOUND_TEXT +@item UTF8_STRING +@item STRING +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: +@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 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}. +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 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 +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 principally requested 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} 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 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 +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 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 +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 +@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 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 +@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 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 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 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 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 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 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 +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 contain ``raw 8-bit bytes'' (@pxref{Text +Representations}). + +@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 data provided 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 +@subsection 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 @code{PRIMARY}, @code{CLIPBOARD}, and @code{SECONDARY} +selections are generally supported, with the @code{XdndSelection} +selection that records drag-and-drop data also available under +Nextstep and Haiku. + +@cindex PGTK selections + 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. + +@cindex MS-Windows selection emulation +@cindex MS-Windows primary and secondary selection + 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 @code{gui-set-selection} within the +@code{x-selections} property of the symbol designating the pertinent +selection, namely the @var{type} argument to @code{gui-get-selection}. +Each subsequent call to @code{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, @var{data-type} +argument is generally disregarded. (But see below for the +qualification regarding @code{TARGETS}.) + +@cindex MS-Windows clipboard + Where the clipboard selection is concerned (whenever @var{type} is +@code{CLIPBOARD}), @code{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 +@code{selection-coding-system}. Callers of @code{gui-get-selection} +are required to set @var{data-type} to either @code{STRING} or +@code{TARGETS}. + + When @var{data-type} is set to @code{TARGETS} in a call to +@code{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 @code{STRING}, for the +prerequisite data conversion routines are absent. Just as strings +saved into the clipboard are encoded by the +@code{selection-coding-system}, so those read from the clipboard are +decoded by that same coding system; this variable and its cousin +@code{next-selection-coding-system} merit particular scrutiny when +difficulties are encountered with saving selection text into the +clipboard. + +@cindex Nextstep selections + 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 @code{gui-set-selection} there are +much the same as those on MS-Windows, though text is uniformly encoded +as @code{utf-8-unix} without regard to the value of +@code{selection-coding-system}. @code{gui-get-selection} is more +charitable, and accepts requests for the following selection targets: + +@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 + + The @code{XdndSelection} selection is also present under Nextstep, +in the form of a repository that records values supplied to +@code{gui-set-selection}. Its sole purpose is to save such values for +the fundamental drag-and-drop function @code{x-begin-drag} +(@pxref{Drag and Drop}); no guarantees exist concerning its value when +read by anything else. + +@cindex Haiku selections + Selections on Haiku systems comprise all three selections customary +under X and the @code{XdndSelection} that records drag-and-drop data. + + When @code{gui-set-selection} is called for the former three +selections, the data supplied is converted into a window server +``message'' by a list of @dfn{selection encoder} functions, which is +sent to the window server. + +@defvar haiku-normal-selection-encoders +List of selection encoder functions. When @code{gui-set-selection} is +called, each function in this list is successively called with its +@var{selection} and @var{value} arguments. If such a function returns +non-@code{nil}, its return value must be a list of the form +@w{@code{(@var{key} @var{type} @var{value})}}. In this list, +@var{key} must be the name of the data being transferred, generally +that of a MIME type, for example @samp{"text/plain"}, and @var{type} +is a symbol or a number designating the type of the data; thus also +governing the interpretation of @var{value}; following is a list of +valid data types and how each of them will cause @var{value} to be +interpreted. + +@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 located and the inode 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 +@end defvar + + A call to @code{gui-get-selection} generally returns the the data +named @var{data-type} within the selection message, albeit with +@var{data-type} replaced by an alternative name should it be one of +the following X selection targets: + +@table @code +@item STRING +This represents Latin-1 text under X: ``text/plain;charset=iso-8859-1'' + +@item UTF8_STRING +This represents UTF-8 text: ``text/plain'' +@end table + + If @var{data-type} is a text type such as @code{STRING} or a MIME +type matching the pattern @samp{`text/*}, the string data is decoded +with the coding system apposite for it before being returned. + + Furthermore, the two data types @var{TIMESTAMP} and @code{TARGETS} +are afforded special treatment; the value returned for the first is +the number of times the selection has been modified since system +startup (@emph{not} a timestamp), and that for the other is a vector +of available selection data types, as elsewhere. + +@cindex Android selections + Much like MS-Windows, Android provides a clipboard but no primary or +secondary selection; @code{gui-set-selection} simulates the primary +and secondary selections by saving the value supplied into a variable +subsequent calls to @code{gui-get-selection} return. + + From the clipboard, @code{gui-get-selection} is capable of returning +UTF-8 string data of the type @code{STRING}, the @code{TAREGTS} data +type, or image and application data of any MIME type. +@code{gui-set-selection} sets only string data, much as under +MS-Windows, although this data is not affected by the value of +@code{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. + @node Yanking Media @section Yanking Media - If you choose, for instance, ``Copy Image'' in a web browser, that -image is put onto the clipboard, and Emacs can access it via -@code{gui-get-selection}. But in general, inserting image data into -an arbitrary buffer isn't very useful---you can't really do much with -it by default. - - So Emacs has a system to let modes register handlers for these -``complicated'' selections. + Data saved within window system selections is not restricted to +plain text. It is possible for selection data to encompass images or +other binary data of the like, as well as rich text content instanced +by HTML, and also PostScript. Since the selection data types incident +to this data are at variance with those for plain text, the insertion +of such data is facilitated by a set of functions dubbed +@dfn{yank-media handlers}, which are registered by each major mode +undertaking its insertion and called where warranted upon the +execution of the @code{yank-media} command. @defun yank-media-handler types handler -@var{types} can be a @acronym{MIME} media type symbol, a regexp to -match these, or a list of these symbols and regexps. For instance: +Register a yank-media handler which applies to the current buffer. + +@var{types} can be a symbol designating a selection data type +(@pxref{Accessing Selections}), a regexp against which such types are +matched, or a list of these symbols and regexps. For instance: @example (yank-media-handler 'text/html #'my-html-handler) (yank-media-handler "image/.*" #'my-image-handler) @end example -A mode can register as many handlers as required. - - The @var{handler} function is called with two parameters: The -@acronym{MIME} media type symbol and the data (as a string). The -handler should then insert the object into the buffer, or save it, or -do whatever is appropriate for the mode. +When a selection offers a data type matching @var{types}, the function +@var{handler} is called to insert its data, with the symbol +designating the matching selection data type, and the data returned by +@code{gui-get-selection}. @end defun - The @code{yank-media} command will consult the registered handlers in -the current buffer, compare that with the available media types on the -clipboard, and then pass on the matching selection to the handler (if -any). If there's more than one matching selection, the user is -queried first. - - The @code{yank-media-types} command can be used to explore the -clipboard/primary selection. It lists all the media types that are -currently available, and can be handy when creating handlers---to see -what data is actually available. Some applications put a surprising -amount of different data types on the clipboard. +The @code{yank-media-types} command presents a list of selection data +types that are currently available, which is useful when implementing +yank-media handlers; for programs generally offer an eclectic and +seldom consistent medley of data types. @node Drag and Drop @section Drag and Drop @cindex drag and drop - When the user drops something from another application over Emacs, -Emacs will try to insert any text and open any URL that was dropped. -If text was dropped, then it will always be inserted at the location -of the mouse pointer where the drop happened, or saved in the kill -ring if insertion failed, which could happen if the buffer was -read-only. If a URL was dropped instead, then Emacs will first try to -call an appropriate handler function by matching the URL against -regexps defined in the variable @code{dnd-protocol-alist}, and then -against those defined in the variables @code{browse-url-handlers} and -@code{browse-url-default-handlers}. Should no suitable handler be -located, Emacs will fall back to inserting the URL as plain text. + Data transferred by drag and drop is generally either plain text or +a list of URLs designating files or other resources. When text is +dropped, it is inserted at the location of the drop, with recourse to +saving it into the kill ring if that is not possible. + + URLs dropped are supplied to pertinent @dfn{DND handler functions} +in the variable @code{dnd-protocol-alist}, or alternatively ``URL +handlers'' as set forth by the variables @code{browse-url-handlers} +and @code{browse-url-default-handlers}; absent matching handlers of +either type, they are treated as plain text and inserted in the +buffer. @defvar dnd-protocol-alist - This variable is a list of cons cells of the form -@w{@code{(@var{pattern} . @var{action})}}. @var{pattern} is a regexp -that URLs are matched against after being dropped. @var{action} is a -function that is called with two arguments, should a URL being dropped -match @var{pattern}: the URL being dropped, and the action being -performed for the drop, which is one of the symbols @code{copy}, -@code{move}, @code{link}, @code{private} or @code{ask}. - -If @var{action} is @var{private}, then it means the program that -initiated the drop wants Emacs to perform an unspecified action with -the URL; a reasonable action to perform in that case is to open the URL -or copy its contents into the current buffer. Otherwise, @var{action} -has the same meaning as the @var{action} argument to +This variable is an alist between regexps against which URLs are +matched and DND handler functions called on the dropping of matching +URLs. + +@cindex dnd-multiple-handler, a symbol property +If a handler function is a symbol whose @code{dnd-multiple-handler} +property (@pxref{Symbol Properties}) is set, then upon a drop it is +given a list of every URL that matches its regexp; absent this +property, it is called once for each of those URLs. Following this +first argument is one of the symbols @code{copy}, @code{move}, +@code{link}, @code{private} or @code{ask} identifying the action to be +taken. + +If @var{action} is @code{private}, the program that initiated the drop +does not insist on any particular behavior on the part of its +recipient; a reasonable action to take in that case is to open the URL +or copy its contents into the current buffer. The other values of +@var{action} imply much the same as in the @var{action} argument to @code{dnd-begin-file-drag}. + +Once its work completes, a handler function must return a symbol +designating the action it took: either the action it was provided, or +the symbol @code{private}, which communicates to the source of the +drop that the action it prescribed has not been executed. + +When multiple handlers match an overlapping subset of items within a +drop, the handler matched against by the greatest number of items is +called to open that subset. The items it is supplied are subsequently +withheld from other handlers, even those they also match. @end defvar @cindex drag and drop, X @cindex drag and drop, other formats - Emacs implements receiving text and URLs individually for each -window system, and does not by default support receiving other kinds -of data as drops. To support receiving other kinds of data, use the -X-specific interface described below. - -@vindex x-dnd-test-function -@vindex x-dnd-known-types - When a user drags something from another application over Emacs -under the X Window System, that other application expects Emacs to -tell it if Emacs understands the data being dragged. The function in -the variable @code{x-dnd-test-function} is called by Emacs to -determine what to reply to any such inquiry. The default value is -@code{x-dnd-default-test-function}, which accepts drops if the type of -the data to be dropped is present in @code{x-dnd-known-types}. -Changing the variables @code{x-dnd-test-function} and -@code{x-dnd-known-types} can make Emacs accept or reject drops based -on some other criteria. - -@vindex x-dnd-types-alist - If you want to change the way Emacs receives drops of different data -types, or you want to enable it to understand a new type, change the variable -@code{x-dnd-types-alist}. Doing so correctly requires detailed -knowledge of what data types other applications use for drag and drop. - - These data types are typically implemented as special data types -that can be obtained from an X selection provided by the other -application. In most cases, they are either the same data types that -are typically accepted by @code{gui-set-selection}, or MIME types, -depending on the specific drag-and-drop protocol being used. For -example, the data type used for plain text may be either -@code{"STRING"} or @code{"text/plain"}. + Emacs does not take measures to accept data besides text and URLs, +for the window system interfaces which enable this are too far removed +from each other to abstract over consistently. Nor are DND handlers +accorded influence over the actions they are meant to take, as +particular drag-and-drop protocols deny recipients such control. The +X11 drag-and-drop implementation rests on several underlying protocols +that make use of selection transfer and share much in common, to which +low level access is provided through the following functions and +variables: + +@defvar x-dnd-test-function +This function is called to ascertain whether Emacs should accept a +drop. It is called with three arguments: + +@itemize @bullet +@item +The window under the item being dragged, which is to say the window +whose buffer is to receive the drop. If the item is situated over a +non-window component of a frame (such as scroll bars, tool bars and +things to that effect), the frame itself is provided in its place. + +@item +One of the symbols @code{move}, @code{copy}, @code{link} or +@code{ask}, representing an action to take on the item data suggested +by the drop source. These symbols carry the same implications as in +@code{x-begin-drag}. + +@item +A vector of selection data types (@pxref{X Selections}) the item +provides. +@end itemize + +This function must return @code{nil} to reject the drop or a cons of +the action that will be taken (such as through transfer to a DND +handler function) and the selection data type to be requested. The +action returned in that cons may also be the symbol @code{private}, +which intimates that the action taken is as yet indeterminate. +@end defvar + +@defvar x-dnd-known-types +Modifying @code{x-dnd-test-function} is generally unwarranted, for its +default set of criteria for accepting a drop can be adjusted by +changing this list of selection data types. Each element is a string, +which if found as the symbol name of an element within the list of +data types by the default ``test function'', will induce that function +to accept the drop. + +Introducing a new entry into this list is not useful unless a +counterpart handler function is appended to @code{x-dnd-types-alist}. +@end defvar + +@defvar x-dnd-types-alist +This variable is an alist between strings designating selection data +types and functions which are called when things of such types are +dropped. + +Each such function is supplied three arguments; the first is the +window or frame below the location of the drop, as in +@code{x-dnd-test-function}; the second is the action to be taken, +which may be any of the actions returned by test functions, and third +is the selection data itself (@pxref{Accessing Selections}). +@end defvar + + Selection data types as provided by X11 drag-and-drop protocols are +sometimes distinct from those provided by the ICCCM and conforming +clipboard or primary selection owners. Frequently, the name of a MIME +type, such as @code{"text/plain;charset=utf-8"} (with discrepant +capitalization of the ``utf-8''), is substituted for a standard X +selection name such as @code{UTF8_STRING}. @cindex XDS @cindex direct save protocol @vindex x-dnd-direct-save-function - When Emacs runs on X window system, it supports the X Direct Save -(@acronym{XDS}) protocol, which allows users to save a file by -dragging and dropping it onto an Emacs window, such as a Dired window. -To comply with the unique requirements of @acronym{XDS}, these -drag-and-drop requests are processed specially: instead of being -handled according to @code{x-dnd-types-alist}, they are handled by the -@dfn{direct-save function} that is the value of the variable -@code{x-dnd-direct-save-function}. The value should be a function of -two arguments, @var{need-name} and @var{filename}. The @acronym{XDS} -protocol uses a two-step procedure for dragging files: + The X Direct Save (@acronym{XDS}) protocol enables programs to +devolve responsibility for naming a dropped file upon the recipient. +When such a drop transpires, DND handlers and the foregoing X-specific +interface are largely circumvented, tasking a different function with +responding to the drop. + +@defvar x-dnd-direct-save-function +This variable should be set to a function that registers and names +files dropped using the @acronym{XDS} protocol in a two-step +procedure. It is provided two arguments, @var{need-name} and +@var{filename}. @enumerate 1 @item @@ -4185,8 +4896,9 @@ Dired should update the directory on display by showing the new file there. @end enumerate -The default value of @code{x-dnd-direct-save-function} is +Its default @code{x-dnd-direct-save-function} is @code{x-dnd-save-direct}. +@end defvar @defun x-dnd-save-direct need-name filename When called with the @var{need-name} argument non-@code{nil}, this @@ -4212,48 +4924,47 @@ default directory.) @end defun @cindex initiating drag-and-drop - On capable window systems, Emacs also supports dragging contents -from its frames to windows of other applications. + It is also possible to drag content from Emacs to other programs +when this is supported by the current window-system. The functions +which provide for this are as follows: @cindex drop target, in drag-and-drop operations @defun dnd-begin-text-drag text &optional frame action allow-same-frame -This function begins dragging text from @var{frame} to another program -(known as the @dfn{drop target}), and returns the result of -drag-and-drop operation when the text is dropped or the drag-and-drop -operation is canceled. @var{text} is the text that will be inserted -by the drop target. +This function starts a drag-and-drop operation from @var{frame} to +another program (dubbed the @dfn{drop target}), and returns when +@var{text} is dropped or the operation is canceled. @var{action} must be one of the symbols @code{copy} or @code{move}, where @code{copy} means that @var{text} should be inserted by the drop -target, and @code{move} means the same as @code{copy}, but in addition -the caller may have to delete @var{text} from its source as explained +target, and @code{move} means the same as @code{copy}, but the caller +must also delete @var{text} from its source as explained in the list below. @var{frame} is the frame where the mouse is currently held down, or -@code{nil}, which means to use the selected frame. This function may -return immediately if no mouse buttons are held down, so it should be -only called immediately after a @code{down-mouse-1} or similar event -(@pxref{Mouse Events}), with @var{frame} set to the frame where that -event was generated (@pxref{Click Events}). +@code{nil}, which means to use the selected frame. Since this +function might return promptly if no mouse buttons are held down, it +should be only called in response to a @code{down-mouse-1} or +analogous event (@pxref{Mouse Events}), with @var{frame} set to the +frame where that event was generated (@pxref{Click Events}). -@var{allow-same-frame} specifies whether or not drops on top of -@var{frame} itself are to be ignored. +If @var{allow-same-frame} is @code{nil}, drops on top of @var{frame} +will be ignored. -The return value specifies the action that the drop target actually -performed, and optionally what the caller should do. It can be one of -the following symbols: +The return value reflects the action that the drop target actually +performed, and thus also what action, if any, the caller should in +turn take. It is one of the following symbols: @table @code @item copy The drop target inserted the dropped text. @item move -The drop target inserted the dropped text, but in addition the caller -should delete @var{text} from wherever it originated, such as its -buffer. +The drop target inserted the dropped text, and the caller should +delete @var{text} from the buffer where it was extracted from, if +applicable. @item private -The drop target performed some other unspecified action. +The drop target took some other unspecified action. @item nil The drag-and-drop operation was canceled. @@ -4262,11 +4973,12 @@ The drag-and-drop operation was canceled. @end defun @defun dnd-begin-file-drag file &optional frame action allow-same-frame -This function begins dragging @var{file} from @var{frame} to another -program, and returns the result of the drag-and-drop operation when -the file is dropped or the drag-and-drop operation is canceled. +This function starts a drag-and-drop operation from @var{frame} to +another program (dubbed the @dfn{drop target}), and returns when +@var{file} is dropped or the operation is canceled. -If @var{file} is a remote file, then a temporary copy will be made. +If @var{file} is a remote file, then a temporary local copy will be +made. @var{action} must be one of the symbols @code{copy}, @code{move} or @code{link}, where @code{copy} means that @var{file} should be opened @@ -4275,11 +4987,11 @@ move the file to another location, and @code{link} means the drop target should create a symbolic link to @var{file}. It is an error to specify @code{link} as the action if @var{file} is a remote file. -@var{frame} and @var{allow-same-frame} have the same meaning as in -@code{dnd-begin-text-drag}. +@var{frame} and @var{allow-same-frame} mean the same as they do in +calls to @code{dnd-begin-text-drag}. The return value is the action that the drop target actually -performed, which can be one of the following symbols: +performed, which is one of the following symbols: @table @code @item copy @@ -4308,19 +5020,18 @@ dropping multiple files, then the first file will be used instead. @end defun @defun dnd-direct-save file name &optional frame allow-same-frame -This function is similar to @code{dnd-begin-file-drag} (with the -default action of copy), but instead of specifying the action you -specify the name of the copy created by the target program in -@code{name}. +The behavior of this function is akin to that of +@code{dnd-begin-file-drag} (when the default action @code{copy} is +used), except that it accepts a name under which the copy is meant to +be filed. @end defun @cindex initiating drag-and-drop, low-level The high-level interfaces described above are implemented on top of -a lower-level primitive. If you need to drag content other than files -or text, use the low-level interface @code{x-begin-drag} -instead. However, using it will require detailed knowledge of the -data types and actions used by the programs to transfer content via -drag-and-drop on each platform you want to support. +a lower-level primitive. The low-level interface @code{x-begin-drag} +is also available for dragging content besides text and files. It +demands detailed knowledge of the data types and actions understood by +programs on each platform its callers wish to support. @defun x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip This function begins a drag from @var{frame}, and returns when the @@ -4332,60 +5043,59 @@ non-@code{nil}. If no mouse buttons are held down when the drag-and-drop operation begins, this function may immediately return @code{nil}. -@var{targets} is a list of strings describing selection targets, much -like the @var{data-type} argument to @code{gui-get-selection}, that -the drop target can request from Emacs (@pxref{Window System +@var{targets} is a list of strings representing selection targets, +much like the @var{data-type} argument to @code{gui-get-selection}, +that the drop target can request from Emacs (@pxref{Window System Selections}). -@var{action} is a symbol describing the action recommended to the -target. It can either be @code{XdndActionCopy}, which -means to copy the contents of the selection @code{XdndSelection} to -the drop target; or @code{XdndActionMove}, which means copy as with -@code{XdndActionCopy}, and in addition the caller should delete -whatever was stored in that selection after copying it. +@var{action} is a symbol designating the action recommended to the +target. It can either be @code{XdndActionCopy} or +@code{XdndActionMove}; both imply copying the contents of the +selection @code{XdndSelection} to the drop target, but the latter +moreover conveys a promise to delete the contents of the selection +after the copying. @var{action} may also be an alist which associates between symbols -describing the available actions, and strings that the drop target is -expected to present to the user to choose between the available -actions. +representing available actions, and strings that the drop target +presents to the user for him to select between those actions. If @var{return-frame} is non-@code{nil} and the mouse moves over an Emacs frame after first moving out of @var{frame}, then the frame to which the mouse moves will be returned immediately. If -@var{return-frame} is the symbol @code{now}, then any frame underneath +@var{return-frame} is the symbol @code{now}, then any frame beneath the mouse pointer will be returned without waiting for the mouse to first move out of @var{frame}. @var{return-frame} is useful when you want to treat dragging content from one frame to another specially, -while also being able to drag content to other programs, but it is not -guaranteed to work on all systems and with all window managers. +while also dragging content to other programs, but it is not +guaranteed to function on all systems and with all window managers. If @var{follow-tooltip} is non-@code{nil}, the position of any tooltip -(such as one shown by @code{tooltip-show}) will follow the location of -the mouse pointer whenever it moves during the drag-and-drop +(such as one displayed by @code{tooltip-show}) will follow the +location of the mouse pointer as it moves during the drag-and-drop operation. The tooltip will be hidden once all mouse buttons are released. If the drop was rejected or no drop target was found, this function -returns @code{nil}. Otherwise, it returns a symbol describing the -action the target chose to perform, which can differ from @var{action} -if that isn't supported by the drop target. @code{XdndActionPrivate} -is also a valid return value in addition to @code{XdndActionCopy} and -@code{XdndActionMove}; it means that the drop target chose to perform -an unspecified action, and no further processing is required by the -caller. - -The caller must cooperate with the target to fully perform the action -chosen by the target. For example, callers should delete the buffer -text that was dragged if this function returns @code{XdndActionMove}. +returns @code{nil}. Otherwise, it returns a symbol representing the +action the target opted to take, which can differ from @var{action} if +that isn't supported by the drop target. @code{XdndActionPrivate} is +also a valid return value in addition to @code{XdndActionCopy} and +@code{XdndActionMove}; it suggests that the drop target opted for an +indeterminate action, and no further action is required of the caller. + +The caller must cooperate with the target to complete the action +selected by the target. For example, callers should delete any buffer +text that was dragged if this function returns @code{XdndActionMove}, +and likewise for other drag data where comparable criteria apply. @end defun @cindex drag and drop protocols, X - On X Windows, several different drag-and-drop protocols are -supported by @code{x-begin-drag}. When dragging content that is known -to not be supported by a specific drag-and-drop protocol, it might be -desirable to turn that protocol off, by changing the values of the -following variables: + The function @code{x-begin-drag} leverages several drag-and-drop +protocols ``behind the scenes''. When dragging content that is known +to not be supported by a specific drag-and-drop protocol, that +protocol can be disabled by changing the values of the following +variables: @defvar x-dnd-disable-motif-protocol When this is non-@code{nil}, the Motif drag and drop protocols are @@ -4409,8 +5119,8 @@ events and the primary selection to insert the text if the drop target doesn't support any drag-and-drop protocol at all. A side effect is that Emacs will become the owner of the primary -selection upon such a drop. If that is not desired, then the drop -emulation can be disabled by setting this variable to @code{nil}. +selection upon such a drop. Such emulation can be disabled by setting +this variable to @code{nil}. @end defvar @node Color Names @@ -4451,20 +5161,12 @@ really supports that color. When using X, you can ask for any defined color on any kind of display, and you will get some result---typically, the closest it can do. To determine whether a frame can really display a certain color, use @code{color-supported-p} (see below). - -@findex x-color-defined-p -This function used to be called @code{x-color-defined-p}, -and that name is still supported as an alias. @end defun @defun defined-colors &optional frame This function returns a list of the color names that are defined and supported on frame @var{frame} (default, the selected frame). If @var{frame} does not support colors, the value is @code{nil}. - -@findex x-defined-colors -This function used to be called @code{x-defined-colors}, -and that name is still supported as an alias. @end defun @defun color-supported-p color &optional frame background-p @@ -4516,10 +5218,6 @@ The color values are returned for @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the information is returned for the selected frame's display. If the frame cannot display colors, the value is @code{nil}. - -@findex x-color-values -This function used to be called @code{x-color-values}, -and that name is still supported as an alias. @end defun @defun color-name-to-rgb color &optional frame @@ -4704,10 +5402,7 @@ This function returns @code{t} if @var{display} has a mouse available, @end defun @defun display-color-p &optional display -@findex x-display-color-p This function returns @code{t} if the screen is a color screen. -It used to be called @code{x-display-color-p}, and that name -is still supported as an alias. @end defun @defun display-grayscale-p &optional display |