diff options
Diffstat (limited to 'doc/lispref/frames.texi')
| -rw-r--r-- | doc/lispref/frames.texi | 144 |
1 files changed, 111 insertions, 33 deletions
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 25706befc8d..712c842a048 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -105,6 +105,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. +* 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. * Text Terminal Colors:: Defining colors for text terminals. @@ -151,7 +152,7 @@ the window (a.k.a.@: the @dfn{dominating} monitor). This function itself does not make the new frame the selected frame. @xref{Input Focus}. The previously selected frame remains selected. -On graphical terminals, however, the windowing system may select the +On graphical terminals, however, the window system may select the new frame for its own reasons. @end deffn @@ -170,7 +171,9 @@ usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (@pxref{Minibuffers and Frames}), the functions will be run for both, the minibuffer-less and -the minibuffer frame. +the minibuffer frame. Alternatively, you can add functions to these +hooks in your ``early init file'' (@pxref{Init File}), in which case +they will be in effect for the initial frame as well. @defvar frame-inherited-parameters This variable specifies the list of frame parameters that a newly @@ -213,7 +216,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}, or @code{pc}). @xref{Frames}. +@code{t}, @code{w32}, @code{ns}, @code{pc}, @code{haiku}, or @code{pgtk}). +@xref{Frames}. @item A list of terminal parameters. @xref{Terminal Parameters}. @@ -494,7 +498,8 @@ a graphical terminal: | | |_____________ Title Bar ______________| | | | (1)_____________ Menu Bar ______________| | ^ | | (2)_____________ Tool Bar ______________| | ^ - | | (3) _________ Internal Border ________ | | ^ + | | (3)_____________ Tab Bar _______________| | ^ + | | | _________ Internal Border ________ | | ^ | | | | ^ | | | | | | | | | | | | | Outer | | | Inner | | | Native @@ -640,6 +645,15 @@ GTK+, on the other hand, never wraps the tool bar but may automatically increase the outer width of a frame in order to accommodate an overlong tool bar. +@item Tab Bar +@cindex tab bar +The tab bar (@pxref{Tab Bars,,,emacs, The GNU Emacs Manual}) is always +drawn by Emacs itself. The tab bar appears above the tool bar in +Emacs built with an internal tool bar, and below the tool bar in +builds with an external tool bar. +Display of the tab bar can be suppressed by setting the +@code{tab-bar-lines} parameter (@pxref{Layout Parameters}) to zero. + @item Native Frame @cindex native frame @cindex native edges @@ -669,7 +683,7 @@ indicate that position for the various builds: @itemize @w{} @item (1) non-toolkit and terminal frames -@item (2) Lucid, Motif and MS-Windows frames +@item (2) Lucid, Motif, MS-Windows, and Haiku frames @item (3) GTK+ and NS frames @end itemize @@ -740,8 +754,8 @@ the internal border, one vertical scroll bar, and one left and one right fringe if they are specified for this frame, see @ref{Layout Parameters}. Its height can be obtained by removing from that of the native height the widths of the internal border and the heights of the -frame's internal menu and tool bars and one horizontal scroll bar if -specified for this frame. +frame's internal menu and tool bars, the tab bar and one horizontal +scroll bar if specified for this frame. @end table @cindex absolute position @@ -1208,10 +1222,10 @@ width of one scroll bar provided this option is @code{nil} and keep it unchanged if this option is @code{t} or a list containing @code{vertical-scroll-bars}. -The default value is @code{'(tab-bar-lines tool-bar-lines)} for Lucid, +The default value is @code{(tab-bar-lines tool-bar-lines)} for Lucid, Motif and MS-Windows (which means that adding/removing a tool or tab bar there does not change the outer frame height), -@code{'(tab-bar-lines)} on all other window systems including GTK+ +@code{(tab-bar-lines)} on all other window systems including GTK+ (which means that changing any of the parameters listed above with the exception of @code{tab-bar-lines} may change the size of the outer frame), and @code{t} otherwise (which means the outer frame size never @@ -1718,7 +1732,9 @@ fit will be clipped by the window manager. @item fullscreen This parameter specifies whether to maximize the frame's width, height or both. Its value can be @code{fullwidth}, @code{fullheight}, -@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as +@code{fullboth}, or @code{maximized}.@footnote{On Haiku, setting +@code{fullscreen} to @code{fullwidth} or @code{fullheight} has no +effect.} A @dfn{fullwidth} frame is as wide as possible, a @dfn{fullheight} frame is as tall as possible, and a @dfn{fullboth} frame is both as wide and as tall as possible. A @dfn{maximized} frame is like a ``fullboth'' frame, except that it usually @@ -1875,6 +1891,13 @@ 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}. +@vindex tab-bar-lines@r{, a frame parameter} +@item tab-bar-lines +The number of lines to use for the tab bar (@pxref{Tab Bars,,,emacs, The +GNU Emacs Manual}). The default is one if Tab Bar mode is enabled and +zero otherwise. This value may change whenever the tab bar wraps +(@pxref{Frame Layout}). + @vindex line-spacing@r{, a frame parameter} @item line-spacing Additional space to leave below each text line, in pixels (a positive @@ -2173,7 +2196,10 @@ either via @code{focus-follows-mouse} (@pxref{Input Focus}) or @code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor -this parameter. +this parameter. On Haiku, it also has the side-effect that the window +will not be able to receive any keyboard input from the user, not even +if the user switches to the frame using the key combination +@kbd{Alt-@key{TAB}}. @vindex undecorated@r{, a frame parameter} @item undecorated @@ -2334,7 +2360,10 @@ driver for OTF and TTF fonts with text shaping by the Uniscribe 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 -other systems, there is only one available font backend, so it does +Haiku, there can be several font drivers (@pxref{Haiku Fonts,,, emacs, +The GNU Emacs Manual}). + +On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter. @vindex background-mode@r{, a frame parameter} @@ -2692,18 +2721,19 @@ frame and defaults to the selected frame. It never returns a frame whose @code{no-other-frame} parameter (@pxref{Frame Interaction Parameters}) is non-@code{nil}. -The second argument, @var{minibuf}, says which frames to consider: +The second argument, @var{minibuf}, says which frames to consider when +deciding what the next frame should be: @table @asis @item @code{nil} -Exclude minibuffer-only frames. +Consider all frames except minibuffer-only frames. @item @code{visible} -Consider all visible frames. +Consider only visible frames. @item 0 -Consider all visible or iconified frames. +Consider only visible or iconified frames. @item a window Consider only the frames using that particular window as their -minibuffer. +minibuffer window. @item anything else Consider all frames. @end table @@ -2757,7 +2787,8 @@ Terminals}. @cindex selected frame At any time, one frame in Emacs is the @dfn{selected frame}. The -selected window always resides on the selected frame. +selected window (@pxref{Selecting Windows}) always resides on the +selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one @@ -2991,12 +3022,11 @@ Auto-selection}). Note that this option does not distinguish ``sloppy'' focus (where the frame that previously had focus retains focus as long as the mouse -pointer does not move into another window manager window) from -``strict'' focus (where a frame immediately loses focus when it's left -by the mouse pointer). Neither does it recognize whether your window -manager supports delayed focusing or auto-raising where you can -explicitly specify the time until a new frame gets focus or is -auto-raised. +pointer does not move into another window-system window) from ``strict'' +focus (where a frame immediately loses focus when it's left by the mouse +pointer). Neither does it recognize whether your window manager +supports delayed focusing or auto-raising where you can explicitly +specify the time until a new frame gets focus or is auto-raised. You can supply a ``focus follows mouse'' policy for individual Emacs windows by customizing the variable @code{mouse-autoselect-window} @@ -3122,8 +3152,10 @@ raises @var{frame} above all other child frames of its parent. @deffn Command lower-frame &optional frame This function lowers frame @var{frame} (default, the selected frame) below all other frames belonging to the same or a higher z-group as -@var{frame}. If @var{frame} is a child frame (@pxref{Child Frames}), -this lowers @var{frame} below all other child frames of its parent. +@var{frame}.@footnote{Lowering frames is not supported on Haiku, due +to limitations imposed by the system.} If @var{frame} is a child +frame (@pxref{Child Frames}), this lowers @var{frame} below all other +child frames of its parent. @end deffn @defun frame-restack frame1 frame2 &optional above @@ -3133,7 +3165,8 @@ that if both frames are visible and their display areas overlap, third argument @var{above} is non-@code{nil}, this function restacks @var{frame1} above @var{frame2}. This means that if both frames are visible and their display areas overlap, @var{frame1} will (partially) -obscure @var{frame2}. +obscure @var{frame2}.@footnote{Restacking frames is not supported on +Haiku, due to limitations imposed by the system.} Technically, this function may be thought of as an atomic action performed in two steps: The first step removes @var{frame1}'s @@ -3228,12 +3261,16 @@ parent frame's window-system window. @cindex reparent frame @cindex nest frame - The @code{parent-frame} parameter can be changed at any time. Setting -it to another frame @dfn{reparents} the child frame. Setting it to -another child frame makes the frame a @dfn{nested} child frame. Setting -it to @code{nil} restores the frame's status as a top-level frame---a -frame whose window-system window is a child of its display's root -window. + The @code{parent-frame} parameter can be changed at any time. +Setting it to another frame @dfn{reparents} the child frame. Setting +it to another child frame makes the frame a @dfn{nested} child frame. +Setting it to @code{nil} restores the frame's status as a top-level +frame---a frame whose window-system window is a child of its display's +root window.@footnote{On Haiku, child frames are only visible when a +parent frame is active, owing to a limitation of the Haiku windowing +system. Owing to the same limitation, child frames are only +guaranteed to appear above their top-level parent; that is to say, the +top-most frame in the hierarchy, which does not have a parent frame.} Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent @@ -3905,6 +3942,47 @@ For backward compatibility, there are obsolete aliases names of @code{gui-get-selection} and @code{gui-set-selection} before Emacs 25.1. +@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. + +@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: + +@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. +@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. + @node Drag and Drop @section Drag and Drop @cindex drag and drop |