diff options
Diffstat (limited to 'doc/emacs/frames.texi')
| -rw-r--r-- | doc/emacs/frames.texi | 619 |
1 files changed, 526 insertions, 93 deletions
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index b168effb3a0..8a255fa40fb 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2017 Free Software +@c Copyright (C) 1985--1987, 1993--1995, 1997, 1999--2022 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Frames @@ -58,6 +58,7 @@ for doing so on MS-DOS). Menus are supported on all text terminals. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. +* Tab Bars:: Enabling and disabling the tab bar. * Dialog Boxes:: Controlling use of dialog boxes. * Tooltips:: Displaying information at the current mouse position. * Mouse Avoidance:: Preventing the mouse pointer from obscuring text. @@ -90,6 +91,10 @@ If the region is active, move the nearer end of the region to the click position; otherwise, set mark at the current value of point and point at the click position. Save the resulting region in the kill ring; on a second click, kill it (@code{mouse-save-then-kill}). + +@item C-M-mouse-1 +Activate a rectangular region around the text selected by dragging. +@xref{Rectangles}. @end table @findex mouse-set-point @@ -98,7 +103,7 @@ invoked by clicking with the left mouse button, @kbd{mouse-1}, in the text area of a window. This moves point to the position where you clicked. If that window was not the selected window, it becomes the selected window. You can also activate a region by double-clicking -mouse-1 (@pxref{Word and Line Mouse}). +@kbd{mouse-1} (@pxref{Word and Line Mouse}). @vindex x-mouse-click-focus-ignore-position Normally, if the frame you clicked in was not the selected frame, it @@ -123,6 +128,12 @@ In addition, the text in the region becomes the primary selection non-@code{nil} value, dragging the mouse over a stretch of text also adds the text to the kill ring. The default is @code{nil}. + If this variable is @code{non-empty}, only copy to the kill ring if +the region is non-empty. For instance, if you mouse drag an area that +is less than a half a character, you'd normally get the empty string +in your kill ring, but with @code{non-empty}, this short mouse drag +won't affect the kill ring. + @vindex mouse-scroll-min-lines If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse @@ -131,6 +142,12 @@ entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable @code{mouse-scroll-min-lines} specifies a minimum step size. +@vindex mouse-drag-mode-line-buffer + If you enable the option @code{mouse-drag-mode-line-buffer} and +dragging files is supported by the window system, then dragging the +mouse on the buffer name portion of the mode line will drag that +buffer's file to another program or frame. + @findex mouse-yank-primary @findex mouse-yank-at-click Clicking with the middle mouse button, @kbd{mouse-2}, moves point to @@ -198,6 +215,10 @@ deactivating the mark. @xref{Shift Selection}. @vindex mouse-wheel-follow-mouse @vindex mouse-wheel-scroll-amount @vindex mouse-wheel-progressive-speed +@cindex wheel-up, a mouse event +@cindex wheel-down, a mouse event +@cindex wheel-left, a mouse event +@cindex wheel-right, a mouse event Some mice have a ``wheel'' which can be used for scrolling. Emacs supports scrolling windows with the mouse wheel, by default, on most graphical displays. To toggle this feature, use @kbd{M-x @@ -205,15 +226,36 @@ mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and @code{mouse-wheel-scroll-amount} determine where and by how much buffers are scrolled. The variable @code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - -@vindex mwheel-tilt-scroll-p -@vindex mwheel-flip-direction -Emacs can also support horizontal scrolling if your mouse's wheel can -be tilted. This feature is off by default; the variable -@code{mwheel-tilt-scroll-p} turns it on. If you'd like to reverse the +speed is linked to how fast you move the wheel. This mode also +supports increasing or decreasing the font size, by default bound to +scrolling with the @key{Ctrl} modifier. When this mode is enabled, +mouse wheel produces special events like @code{wheel-up} and +@code{wheel-down}. (Some older systems report them as @code{mouse-4} +and @code{mouse-5}.) If the mouse has a horizontal scroll wheel, it +produces @code{wheel-left} and @code{wheel-right} events as well. + +@vindex mouse-wheel-scroll-amount-horizontal +Emacs also supports horizontal scrolling with the @key{Shift} +modifier. Typing a numeric prefix arg (e.g., @kbd{M-5}) before +starting horizontal scrolling changes its step value defined +by the user option @code{mouse-wheel-scroll-amount-horizontal}. + +@vindex mouse-wheel-tilt-scroll +@vindex mouse-wheel-flip-direction +If your mouse's wheel can be tilted, or if your touchpad supports it, +then you can also enable horizontal scrolling by customizing the +variable @code{mouse-wheel-tilt-scroll} to a non-@code{nil} value. +By default, tilting the mouse wheel scrolls the window's view +horizontally in the direction of the tilt: e.g., tilting to the right +scrolls the window to the right, so that the text displayed in the +window moves horizontally to the left. If you'd like to reverse the direction of horizontal scrolling, customize the variable -@code{mwheel-flip-direction} to a non-@code{nil} value. +@code{mouse-wheel-flip-direction} to a non-@code{nil} value. + +When the mouse pointer is over an image in Image mode, @pxref{Image Mode}, +scrolling the mouse wheel with the @key{Ctrl} modifier scales the image +under the mouse pointer, and scrolling the mouse wheel with the +@key{Shift} modifier scrolls the image horizontally. @node Word and Line Mouse @@ -243,18 +285,18 @@ location of point. Double-clicking on the end of a parenthetical grouping or end string-delimiter keeps point at the end of the region by default, so the beginning of the region will not be visible if it is above the top of the window; setting the user option -@code{mouse-select-region-move-to-beginning} to non-nil changes this -to move point to the beginning of the region, scrolling the display -backward if necessary. +@code{mouse-select-region-move-to-beginning} to non-@code{nil} changes +this to move point to the beginning of the region, scrolling the +display backward if necessary. @item Double-Drag-mouse-1 -Select the text you drag across, in the form of whole words. +Select the text you drag across, in units of whole words. @item Triple-mouse-1 Select the line you click on. @item Triple-Drag-mouse-1 -Select the text you drag across, in the form of whole lines. +Select the text you drag across, in units of whole lines. @end table @node Mouse References @@ -312,7 +354,7 @@ button. @node Menu Mouse Clicks @section Mouse Clicks for Menus - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers + Several mouse clicks with the @key{Ctrl} and @key{SHIFT} modifiers bring up menus. @table @kbd @@ -344,16 +386,24 @@ This menu is for changing the default face within the window's buffer. @xref{Text Scale}. @end table - Some graphical applications use @kbd{mouse-3} for a mode-specific -menu. If you prefer @kbd{mouse-3} in Emacs to bring up such a menu -instead of running the @code{mouse-save-then-kill} command, rebind -@kbd{mouse-3} by adding the following line to your init file -(@pxref{Init Rebinding}): - -@c FIXME: `mouse-popup-menubar-stuff' is obsolete since 23.1. -@smallexample -(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) -@end smallexample +@cindex context menu +@findex context-menu-mode +@vindex context-menu-functions +@kindex Down-mouse-3 +@kindex S-F10 + Many GUI applications use @kbd{mouse-3} to display @dfn{context +menus}: menus that provide access to various pertinent settings and +actions for the location and context of the mouse click. If you +prefer this in Emacs over the default function of @kbd{mouse-3}, which +is bound to the @code{mouse-save-then-kill} command (@pxref{Mouse +Commands}), you can enable the minor mode @code{context-menu-mode}. +Then Emacs will show context menus when you click @kbd{mouse-3}. The +exact contents of these context menus depends on the current major +mode and the buffer contents around the place where you click the +mouse. To customize the contents of the context menu, you can use the +variable @code{context-menu-functions} (@pxref{Major Mode +Conventions,,, elisp, The Emacs Lisp Reference Manual}). +You can also invoke the context menu by pressing @kbd{S-@key{F10}}. @node Mode Line Mouse @section Mode Line Mouse Commands @@ -388,7 +438,6 @@ make any window smaller than the minimum height. frame has only one window, it does nothing. @item C-mouse-2 -@kindex C-mouse-2 @r{(mode line)} @kbd{C-mouse-2} on a mode line splits that window, producing two side-by-side windows with the boundary running through the click position (@pxref{Split Window}). @@ -410,10 +459,11 @@ boundary to the left or right. The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas each @kbd{C-x 4} command pops up a buffer in a different window in the selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a -different frame. If an existing visible or iconified (a.k.a.@: ``minimized'') -frame already displays the requested buffer, that frame is raised and -deiconified (``un-minimized''); otherwise, a new frame is created on -the current display terminal. +different frame. If an existing visible or iconified (a.k.a.@: +``minimized'', @pxref{Visibility of Frames,,, elisp, The Emacs Lisp +Reference Manual}) frame already displays the requested buffer, that +frame is raised and deiconified (``un-minimized''); otherwise, a new +frame is created on the current display terminal. The various @kbd{C-x 5} commands differ in how they find or create the buffer to select: @@ -422,30 +472,49 @@ buffer to select: @item C-x 5 2 @kindex C-x 5 2 @findex make-frame-command -Create a new frame (@code{make-frame-command}). +Create a new frame using the default frame parameters +(@code{make-frame-command}). + +@item C-x 5 c +@kindex C-x 5 c +@findex clone-frame +Create a new frame using the window configuration and frame parameters +of the current frame (@code{clone-frame}). + @item C-x 5 b @var{bufname} @key{RET} Select buffer @var{bufname} in another frame. This runs @code{switch-to-buffer-other-frame}. + @item C-x 5 f @var{filename} @key{RET} Visit file @var{filename} and select its buffer in another frame. This runs @code{find-file-other-frame}. @xref{Visiting}. + @item C-x 5 d @var{directory} @key{RET} Select a Dired buffer for directory @var{directory} in another frame. This runs @code{dired-other-frame}. @xref{Dired}. + @item C-x 5 m Start composing a mail message in another frame. This runs @code{compose-mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. @xref{Sending Mail}. + @item C-x 5 . Find the definition of an identifier in another frame. This runs @code{xref-find-definitions-other-frame}, the multiple-frame variant of @kbd{M-.}. @xref{Xref}. + @item C-x 5 r @var{filename} @key{RET} @kindex C-x 5 r @findex find-file-read-only-other-frame Visit file @var{filename} read-only, and select its buffer in another frame. This runs @code{find-file-read-only-other-frame}. @xref{Visiting}. + +@item C-x 5 5 +A more general prefix command that affects the buffer displayed by the +next command invoked immediately after this prefix command +(@code{other-frame-prefix}). It requests the buffer of the next +command to be displayed in another frame. @end table You can control the appearance and behavior of the newly-created @@ -463,9 +532,18 @@ frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. Delete the selected frame (@code{delete-frame}). This signals an error if there is only one frame. +@item C-x 5 u +@kindex C-x 5 u +@findex undelete-frame +@findex undelete-frame-mode +When @code{undelete-frame-mode} is enabled, undelete one of the 16 +most recently deleted frames. Without a prefix argument, undelete the +most recently deleted frame. With a numerical prefix argument between +1 and 16, where 1 is the most recently deleted frame, undelete the +corresponding deleted frame. + @item C-z @kindex C-z @r{(X windows)} -@findex suspend-frame Minimize (or iconify) the selected Emacs frame (@code{suspend-frame}). @xref{Exiting}. @@ -480,14 +558,14 @@ cycles through all the frames on your terminal. @findex delete-other-frames Delete all frames on the current terminal, except the selected one. -@item M-<F10> -@kindex M-<F10> +@item M-@key{F10} +@kindex M-F10 @findex toggle-frame-maximized Toggle the maximization state of the current frame. When a frame is maximized, it fills the screen. -@item <F11> -@kindex <F11> +@item @key{F11} +@kindex F11 @findex toggle-frame-fullscreen Toggle full-screen mode for the current frame. (The difference between full-screen and maximized is normally that the former @@ -532,8 +610,10 @@ the mouse cursor to the chosen frame. @cindex fonts By default, Emacs displays text on graphical displays using a -10-point monospace font. There are several different ways to specify -a different font: +10-point monospace font, and the font size can be changed +interactively (@pxref{Text Scale}). + + There are several different ways to specify a different font: @itemize @item @@ -576,7 +656,10 @@ If you are running Emacs on the GNOME desktop, you can tell Emacs to use the default system font by setting the variable @code{font-use-system-font} to @code{t} (the default is @code{nil}). For this to work, Emacs must have been compiled with support for -Gsettings (or the older Gconf). +Gsettings (or the older Gconf). (To be specific, the Gsettings +configuration names used are +@samp{org.gnome.desktop.interface monospace-font-name} and +@samp{org.gnome.desktop.interface font-name}.) @item Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font @@ -588,9 +671,9 @@ command can be helpful. It describes the character at point, and names the font that it's rendered in. @cindex fontconfig - On X, there are four different ways to express a font name. The -first is to use a @dfn{Fontconfig pattern}. Fontconfig patterns have -the following form: + There are four different ways to express a font name. The first is +to use a @dfn{Fontconfig pattern}. Fontconfig patterns have the +following form: @example @var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... @@ -644,7 +727,11 @@ Monospace-12:weight=bold:slant=italic For a more detailed description of Fontconfig patterns, see the Fontconfig manual, which is distributed with Fontconfig and available -online at @url{http://fontconfig.org/fontconfig-user.html}. +online at @url{https://fontconfig.org/fontconfig-user.html}. + +On MS-Windows, only the subset of the form +@var{fontname}[-@var{fontsize}] is supported for all fonts; the full +Fontconfig pattern might not work for all of them. @cindex GTK font pattern The second way to specify a font is to use a @dfn{GTK font pattern}. @@ -681,12 +768,15 @@ Monospace 12 Monospace Bold Italic 12 @end example +On MS-Windows, only the subset @var{fontname} is supported. + @cindex XLFD @cindex X Logical Font Description The third way to specify a font is to use an @dfn{XLFD} (@dfn{X Logical Font Description}). This is the traditional method for -specifying fonts under X@. Each XLFD consists of fourteen words or -numbers, separated by dashes, like this: +specifying fonts under X, and is also supported on MS-Windows. Each +XLFD consists of fourteen words or numbers, separated by dashes, like +this: @example -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 @@ -770,6 +860,8 @@ equivalent to -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 @end example +This form is not supported on MS-Windows. + @cindex client-side fonts @cindex server-side fonts On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts, @@ -877,6 +969,7 @@ Speedbar,,speedbar, Speedbar Manual}. @node Multiple Displays @section Multiple Displays @cindex multiple displays +@cindex display server A single Emacs can talk to more than one X display. Initially, Emacs uses just one display---the one specified with the @env{DISPLAY} @@ -900,9 +993,19 @@ input stream for each server. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame. + On multi-monitor displays it is possible to use the command +@code{make-frame-on-monitor}: + +@findex make-frame-on-monitor +@table @kbd +@item M-x make-frame-on-monitor @key{RET} @var{monitor} @key{RET} +Create a new frame on monitor @var{monitor} whose screen area is +a part of the current display. +@end table + @node Frame Parameters @section Frame Parameters -@cindex default-frame-alist +@vindex default-frame-alist You can control the default appearance and behavior of all frames by specifying a default list of @dfn{frame parameters} in the variable @@ -926,7 +1029,7 @@ default font to @samp{Monospace-10}: For a list of frame parameters and their effects, see @ref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}. -@cindex initial-frame-alist +@vindex initial-frame-alist You can also specify a list of frame parameters which apply to just the initial frame, by customizing the variable @code{initial-frame-alist}. @@ -935,6 +1038,10 @@ the initial frame, by customizing the variable specify colors and fonts don't affect menus and the menu bar, since those are drawn by the toolkit and not directly by Emacs. + Frame appearance and behavior can also be customized through X +resources (@pxref{X Resources}); these override the parameters of the +initial frame specified in your init file. + Note that if you are using the desktop library to save and restore your sessions, the frames to be restored are recorded in the desktop file, together with their parameters. When these frames are restored, @@ -951,11 +1058,13 @@ that. On graphical displays, there is a @dfn{vertical scroll bar} on the side of each Emacs window. Clicking @kbd{mouse-1} on the scroll bar's -up and down buttons scrolls the window by one line at a time. Clicking -@kbd{mouse-1} above or below the scroll bar's inner box scrolls the -window by nearly the entire height of the window, like @kbd{M-v} and -@kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box -scrolls continuously. +up and down buttons scrolls the window by one line at a time (but some +toolkits allow you to customize the scroll bars to not have those +buttons). Clicking @kbd{mouse-1} above or below the scroll bar's +inner box scrolls the window by nearly the entire height of the +window, like @kbd{M-v} and @kbd{C-v} respectively (@pxref{Moving +Point}). (This, too, can behave differently with some toolkits.) +Dragging the inner box scrolls continuously. If Emacs is compiled on the X Window System without X toolkit support, the scroll bar behaves differently. Clicking @kbd{mouse-1} @@ -972,13 +1081,14 @@ frame, use the command @kbd{M-x toggle-scroll-bar}. @vindex scroll-bar-mode To control the use of vertical scroll bars at startup, customize the -variable @code{scroll-bar-mode}. Its value should be either -@code{right} (put scroll bars on the right side of windows), @code{left} -(put them on the left), or @code{nil} (disable vertical scroll bars). -By default, Emacs puts scroll bars on the right if it was compiled with -GTK+ support on the X Window System, and on MS-Windows or Mac OS; Emacs -puts scroll bars on the left if compiled on the X Window System without -GTK+ support (following the old convention for X applications). +variable @code{scroll-bar-mode} (@pxref{Customization}). Its value +should be either @code{right} (put scroll bars on the right side of +windows), @code{left} (put them on the left), or @code{nil} (disable +vertical scroll bars). By default, Emacs puts scroll bars on the +right if it was compiled with GTK+ support on the X Window System, and +on MS-Windows or macOS; Emacs puts scroll bars on the left if compiled +on the X Window System without GTK+ support (following the old +convention for X applications). @vindex scroll-bar-width @cindex width of the vertical scroll bar @@ -995,21 +1105,39 @@ variable @code{scroll-bar-adjust-thumb-portion} to control when the end of the buffer is visible. If its value is non-@code{nil}, the scroll bar can be dragged downwards even if the end of the buffer is shown; if @code{nil}, the thumb will be at the -bottom when the end of the buffer is shown. You can not over-scroll +bottom when the end of the buffer is shown. You cannot over-scroll when the entire buffer is visible. -@cindex scroll-bar face +@cindex @code{scroll-bar} face The visual appearance of the scroll bars is controlled by the -@code{scroll-bar} face. +@code{scroll-bar} face. (Some toolkits, such as GTK+ and MS-Windows, +ignore this face; the scroll-bar appearance there can only be +customized system-wide, for GTK+ @pxref{GTK resources}). + +@cindex vertical border + On graphical frames, vertical scroll bars implicitly serve to separate +side-by-side windows visually. When vertical scroll bars are disabled, +Emacs by default separates such windows with the help of a one-pixel +wide @dfn{vertical border}. That border occupies the first pixel column +of the window on the right and may thus overdraw the leftmost pixels of +any glyph displayed there. If these pixels convey important +information, you can make them visible by enabling window dividers, see +@ref{Window Dividers}. To replicate the look of vertical borders, set +the @code{right-divider-width} parameter of frames to one and have the +@code{window-divider} face inherit from that of @code{vertical-border}, +@ref{Window Dividers,, Window Dividers, elisp, The Emacs Lisp Reference +Manual}. @cindex Horizontal Scroll Bar @cindex Horizontal Scroll Bar mode On graphical displays with toolkit support, Emacs may also supply a @dfn{horizontal scroll bar} on the bottom of each window. Clicking -@kbd{mouse-1} on the that scroll bar's left and right buttons scrolls -the window horizontally by one column at a time. Clicking @kbd{mouse-1} -on the left or right of the scroll bar's inner box scrolls the window by -four columns. Dragging the inner box scrolls the window continuously. +@kbd{mouse-1} on that scroll bar's left and right buttons scrolls the +window horizontally by one column at a time. (Note that some toolkits +allow customizations of the scroll bar that cause these buttons not to +be shown.) Clicking @kbd{mouse-1} on the left or right of the scroll +bar's inner box scrolls the window by four columns. Dragging the +inner box scrolls the window continuously. Note that such horizontal scrolling can make the window's position of point disappear on the left or the right. Typing a character to insert @@ -1060,7 +1188,12 @@ window-divider-mode}. customize the options @code{window-divider-default-bottom-width} and @code{window-divider-default-right-width}. - For more details about window dividers see @ref{Window Dividers,, + When vertical scroll bars are disabled, dividers can be also useful to +make the first pixel column of a window visible, which would be otherwise +covered by the vertical border used to separate side-by-side windows +(@pxref{Scroll Bars}). + +For more details about window dividers see @ref{Window Dividers,, Window Dividers, elisp, The Emacs Lisp Reference Manual}. @node Drag and Drop @@ -1075,18 +1208,6 @@ file on a Dired buffer moves or copies the file (according to the conventions of the application it came from) into the directory displayed in that buffer. -@vindex mouse-drag-and-drop-region - Emacs can also optionally drag the region of text by mouse into -another portion of this or another buffer. To enable that, customize -the variable @code{mouse-drag-and-drop-region} to a non-nil value. -Normally, the text is moved, i.e. cut and pasted, when the destination -is the same buffer as the origin; dropping the region on another -buffer copies the text instead. If the value of this variable names a -modifier key, such as @samp{shift} or @samp{control} or @samp{alt}, -then pressing that modifier key when dropping the text will copy it -instead of cutting it, even if you drop on the same buffer as the one -from which the text came. - @vindex dnd-open-file-other-window Dropping a file normally visits it in the window you drop it on. If you prefer to visit the file in a new window in such cases, customize @@ -1095,9 +1216,57 @@ the variable @code{dnd-open-file-other-window}. The XDND and Motif drag and drop protocols, and the old KDE 1.x protocol, are currently supported. +@vindex dnd-indicate-insertion-point +@vindex dnd-scroll-margin + + It can be difficult to scroll a window or determine where dropped +text will be inserted while dragging text onto an Emacs window. +Setting the option @code{dnd-indicate-insertion-point} to a +non-@code{nil} value makes point move to the location any dropped text +will be inserted when the mouse moves in a window during drag, and +setting @code{dnd-scroll-margin} to an integer value causes a window +to be scrolled if the mouse moves within that many lines of the top +or bottom of the window during drag. + +@vindex mouse-drag-and-drop-region + Emacs can also optionally drag the region with the mouse into +another portion of this or another buffer. To enable that, customize +the variable @code{mouse-drag-and-drop-region} to a non-@code{nil} +value. Normally, the text is moved, i.e. cut and pasted, when the +destination is the same buffer as the origin; dropping the region on +another buffer copies the text instead. If the value of this variable +names a modifier key, such as @samp{shift}, @samp{control} or +@samp{alt}, then pressing that modifier key when dropping the text +will copy it instead of cutting it, even if you drop on the same +buffer as the one from which the text came. + +@vindex mouse-drag-and-drop-region-cut-when-buffers-differ +@vindex mouse-drag-and-drop-region-show-tooltip +@vindex mouse-drag-and-drop-region-show-cursor +In order to cut text even when source and destination buffers differ, +set the option +@code{mouse-drag-and-drop-region-cut-when-buffers-differ} to a +non-@code{nil} value. By default, on a graphic display the selected +text is shown in a tooltip and point moves together with the mouse +cursor during dragging. To suppress such behavior, set the options +@code{mouse-drag-and-drop-region-show-tooltip} and/or +@code{mouse-drag-and-drop-region-show-cursor} to @code{nil}. + +@vindex mouse-drag-and-drop-region-cross-program +To drag text from Emacs to other programs, set the option +@code{mouse-drag-and-drop-region-cross-program} to a non-@code{nil} +value. + + On the X window system, some programs can drop files on Emacs, +expecting Emacs to save them. Normally, Emacs will prompt for a file +name under which the file will be saved, and then open the file, but +that behavior can be changed by changing the variable +@code{x-dnd-direct-save-function}. @xref{Drag and Drop,,, elisp, The +Emacs Lisp Reference Manual}. + @node Menu Bars @section Menu Bars -@cindex Menu Bar mode +@cindex menu bar mode @cindex mode, Menu Bar @findex menu-bar-mode @vindex menu-bar-mode @@ -1114,7 +1283,9 @@ the use of menu bars at startup, customize the variable terminals, where this makes one additional line available for text. If the menu bar is off, you can still pop up a menu of its contents with @kbd{C-mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. +Or you can enable @code{context-menu-mode} and customize the variable +@code{context-menu-functions} to pop up a context menu with +@kbd{mouse-3}. @xref{Menu Mouse Clicks}. @xref{Menu Bar}, for information on how to invoke commands with the menu bar. @xref{X Resources}, for how to customize the menu bar @@ -1122,7 +1293,7 @@ menus' visual appearance. @node Tool Bars @section Tool Bars -@cindex Tool Bar mode +@cindex tool bar mode @cindex mode, Tool Bar @cindex icons, toolbar @@ -1160,6 +1331,263 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}. On macOS the tool bar is hidden when the frame is put into fullscreen, but can be displayed by moving the mouse pointer to the top of the screen. +@node Tab Bars +@section Tab Bars +@cindex tab bar mode +@cindex mode, Tab Bar +@cindex tabs, on the Tab Bar + + On graphical displays and on text terminals, Emacs can optionally +display a @dfn{Tab Bar} at the top of each frame, just below the menu +bar (@pxref{Menu Bars}) and above or below the tool bar (@pxref{Tool +Bars}) depending on the variable @code{tab-bar-position}. +The Tab Bar is a row of @dfn{tabs}---buttons that you can click to +switch between window configurations. + + Each tab on the Tab Bar represents a named persistent window +configuration of its frame, i.e., how that frame is partitioned into +windows and which buffer is displayed in each window. The tab's name +is composed from the list of names of buffers shown in windows of that +window configuration. Clicking on the tab switches to the window +configuration recorded by the tab; it is a configuration of windows +and buffers which was previously used in the frame when that tab was +the current tab. + + If you are using the desktop library to save and restore your +sessions (@pxref{Saving Emacs Sessions}), the tabs from the Tab Bar are +recorded in the desktop file, together with their associated window +configurations, and will be available after restoring the session. + +Note that the Tab Bar is different from the Tab Line (@pxref{Tab Line}). +Whereas tabs on the Tab Line at the top of each window are used to +switch between buffers in the window, tabs on the Tab Bar at the top +of each frame are used to switch between window configurations +containing several windows showing one or more buffers. + +@findex tab-bar-mode + To toggle the use of Tab Bars, type @kbd{M-x tab-bar-mode}. This +command applies to all frames, including frames yet to be created. To +control the use of tab bars at startup, customize the variable +@code{tab-bar-mode} and save your customization. + +@vindex tab-bar-show + The variable @code{tab-bar-show} controls whether the Tab Bar mode +is turned on automatically. If the value is @code{t}, then +@code{tab-bar-mode} is enabled when using the commands that create new +tabs. The value @code{1} hides the tab bar when it has only one tab, +and shows it again when more tabs are created. More generally, a +value that is a non-negative integer causes the Tab Bar to be +displayed only if the number of tabs is greater than that integer. +The value @code{nil} always keeps the Tab Bar hidden; in this case +it's still possible to switch between named window configurations +without displaying the Tab Bar by using @kbd{M-x tab-next}, @kbd{M-x +tab-switcher}, and other commands that provide completion on tab +names. Also it's possible to create and close tabs without the Tab +Bar by using commands @kbd{M-x tab-new}, @kbd{M-x tab-close}, etc. + + Note that a numerical value of @code{tab-bar-show} can cause the Tab +Bar to be displayed on some frames, but not on others, depending on +the number of tabs created on each frame. + +@findex toggle-frame-tab-bar + To toggle the use of the Tab Bar only on the selected frame, type +@kbd{M-x toggle-frame-tab-bar}. This command allows to enable the +display of the Tab Bar on some frames and disable it on others, +regardless of the values of @code{tab-bar-mode} and @code{tab-bar-show}. + +@kindex C-x t + The prefix key @kbd{C-x t} is analogous to @kbd{C-x 5}. +Whereas each @kbd{C-x 5} command pops up a buffer in a different frame +(@pxref{Creating Frames}), the @kbd{C-x t} commands use a different +tab with a different window configuration in the selected frame. + + The various @kbd{C-x t} commands differ in how they find or create the +buffer to select. The following commands can be used to select a buffer +in a new tab: + +@table @kbd +@kindex C-x t 2 +@findex tab-new +@vindex tab-bar-tab-name-function +@item C-x t 2 +Add a new tab (@code{tab-new}). You can control the choice of the +buffer displayed in a new tab by customizing the variable +@code{tab-bar-new-tab-choice}. You can control the names given by +default to new tabs by customizing the variable +@code{tab-bar-tab-name-function}. + +@kindex C-x t b +@findex switch-to-buffer-other-tab +@item C-x t b @var{bufname} @key{RET} +Select buffer @var{bufname} in another tab. This runs +@code{switch-to-buffer-other-tab}. + +@kindex C-x t f +@findex find-file-other-tab +@item C-x t f @var{filename} @key{RET} +Visit the file @var{filename} (@pxref{Visiting}) and select its buffer +in another tab. This runs @code{find-file-other-tab}. + +@kindex C-x t d +@findex dired-other-tab +@item C-x t d @var{directory} @key{RET} +Edit the specified @var{directory} (@pxref{Dired}) in another tab. +This runs @code{dired-other-tab}. + +@kindex C-x t t +@findex other-tab-prefix +@item C-x t t +This is a prefix command (@code{other-tab-prefix}) that affects the +next command invoked immediately after this prefix command. It +requests the buffer displayed by the next command to be shown in +another tab. +@end table + +@vindex tab-bar-new-tab-choice + By default, a new tab starts with the buffer that was +current before calling the command that adds a new tab. +To start a new tab with other buffers, customize the variable +@code{tab-bar-new-tab-choice}. + +@vindex tab-bar-new-tab-to + The variable @code{tab-bar-new-tab-to} defines where to place a new tab. +By default, a new tab is added on the right side of the current tab. + + The following commands can be used to delete tabs: + +@table @kbd +@kindex C-x t 0 +@findex tab-close +@vindex tab-bar-close-last-tab-choice +@item C-x t 0 +Close the selected tab (@code{tab-close}). This has no effect if there +is only one tab, unless the variable @code{tab-bar-close-last-tab-choice} +is customized to a non-default value. + +@kindex C-x t 1 +@findex tab-close-other +@item C-x t 1 +Close all tabs, except the selected tab, on the selected frame. +@end table + +@vindex tab-bar-close-tab-select + The variable @code{tab-bar-close-tab-select} defines what tab to +select after closing the current tab. By default, it selects +a recently used tab. + +@findex tab-undo + The command @code{tab-undo} restores the last closed tab. + + The following commands can be used to switch between tabs: + +@table @kbd +@kindex C-x t o +@kindex C-TAB +@findex tab-next +@item C-x t o +@itemx C-@key{TAB} +Switch to the next tab (@code{tab-next}). If you repeat this command, +it cycles through all the tabs on the selected frame. With a positive +numeric argument @var{n}, it switches to the @var{n}th next tab; with +a negative argument @minus{}@var{n}, it switches back to the @var{n}th +previous tab. + +@kindex S-C-TAB +@findex tab-previous +@item S-C-@key{TAB} +Switch to the previous tab (@code{tab-previous}). With a positive +numeric argument @var{n}, it switches to the @var{n}th previous tab; +with a negative argument @minus{}@var{n}, it switches to the +@var{n}th next tab. + +@kindex C-x t @key{RET} +@findex tab-switch +@item C-x t @key{RET} @var{tabname} @key{RET} +Switch to the tab by its name (@code{tab-switch}), with completion on +all tab names. The default value and the ``future history'' of tab +names is sorted by recency, so you can use @kbd{M-n} +(@code{next-history-element}) to get the name of the last visited tab, +the second last, and so on. + +@kindex C-1, tab bar +@kindex M-1, tab bar +@findex tab-select +@vindex tab-bar-select-tab-modifiers +@vindex tab-bar-tab-hints +@item @var{modifier}-@var{tab-number} +Switch to the tab by its number @var{tab-number} (@code{tab-select}). +After customizing the variable @code{tab-bar-select-tab-modifiers} to +specify one or more @var{modifier} keys, you can select a tab by its +ordinal number using one of the specified modifiers in combination +with the tab number to select. The number 9 can be used to select the +last tab. You can select any modifiers supported by Emacs, +@pxref{Modifier Keys}. To display the tab number alongside the tab +name, you can customize another variable @code{tab-bar-tab-hints}. +This will help you decide which numerical key to press to select the +tab by its number. + +@kindex C-9, tab bar +@kindex M-9, tab bar +@findex tab-last +@item @var{modifier}-@kbd{9} +Switch to the last tab (@code{tab-last}). The key combination is +the modifier key defined by @code{tab-bar-select-tab-modifiers} and +the key @kbd{9}. With a numeric argument @var{n}, switch to the +@var{n}th last tab. + +@kindex C-0, tab bar +@kindex M-0, tab bar +@findex tab-recent +@item @var{modifier}-@kbd{0} +Switch to the recent tab (@code{tab-recent}). The key combination is +the modifier key defined by @code{tab-bar-select-tab-modifiers} and +the key @kbd{0}. With a numeric argument @var{n}, switch to the +@var{n}th recent tab. +@end table + + The following commands can be used to operate on tabs: + +@table @kbd +@kindex C-x t r +@findex tab-rename +@item C-x t r @var{tabname} @key{RET} +Rename the current tab to @var{tabname} (@code{tab-rename}). + +@kindex C-x t m +@findex tab-move +@item C-x t m +Move the current tab one position to the right (@code{tab-move}). +With a positive numeric argument @var{n}, move it that many positions +to the right; with a negative argument @minus{}@var{n}, move it +@var{n} positions to the left. +@end table + + You can use the mouse to operate on tabs. Clicking @kbd{mouse-2} +closes the tab. Clicking @kbd{mouse-3} pops up the context menu with +the items that operate on the clicked tab. Dragging the tab with +@kbd{mouse-1} moves it to another position on the tab bar. Mouse +wheel scrolling switches to the next or previous tab. Holding down +the @key{SHIFT} key during scrolling moves the tab to the left or right. + +@findex tab-bar-history-mode + You can enable @code{tab-bar-history-mode} to remember window +configurations used in every tab, and later restore them. + +@table @kbd +@findex tab-bar-history-back +@item M-x tab-bar-history-back +Restore a previous window configuration used in the current tab. +This navigates back in the history of window configurations. + +@findex tab-bar-history-forward +@item M-x tab-bar-history-forward +Cancel restoration of the previous window configuration. +This moves forward in the history of window configurations. +@end table + + It's possible to customize the items displayed on the tab bar +by the user option @code{tab-bar-format}. + @node Dialog Boxes @section Using Dialog Boxes @cindex dialog boxes @@ -1249,13 +1677,18 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also For additional customization options for displaying tooltips, use @kbd{M-x customize-group @key{RET} tooltip @key{RET}}. -@vindex x-gtk-use-system-tooltips - If Emacs is built with GTK+ support, it displays tooltips via GTK+, -using the default appearance of GTK+ tooltips. To disable this, -change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. -If you do this, or if Emacs is built without GTK+ support, most -attributes of the tooltip text are specified by the @code{tooltip} -face, and by X resources (@pxref{X Resources}). +@vindex use-system-tooltips + If Emacs is built with the GTK+ toolkit, Nextstep windowing, or +Haiku windowing support, it displays tooltips via the toolkit, using +the default appearance of the toolkit's tooltips.@footnote{The +foreground and background colors of toolkit-created tooltips on +Nextstep can also be customized by setting the @code{foreground} and +@code{background} frame parameters that are part of +@code{tooltip-frame-parameters}.} To disable this, change the variable +@code{use-system-tooltips} to @code{nil}. If you do this, or if Emacs +is built without the appropriate windowing support, most attributes of +the tooltip text are specified by the @code{tooltip} face, and by X +resources (@pxref{X Resources}). @dfn{GUD tooltips} are special tooltips that show the values of variables when debugging a program with GUD@. @xref{Debugger @@ -1269,11 +1702,11 @@ Operation}. On graphical terminals, the mouse pointer may obscure the text in the Emacs frame. Emacs provides two methods to avoid this problem. -@vindex make-pointer-invisible Firstly, Emacs hides the mouse pointer each time you type a self-inserting character, if the pointer lies inside an Emacs frame; moving the mouse pointer makes it visible again. To disable this feature, set the variable @code{make-pointer-invisible} to @code{nil}. +@xref{Display Custom}. @vindex mouse-avoidance-mode Secondly, you can use Mouse Avoidance mode, a minor mode, to keep @@ -1346,7 +1779,7 @@ can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple uses of the mouse---basically, only non-modified single clicks are supported. Newer versions of @command{xterm} also support mouse-tracking. The normal @command{xterm} mouse functionality for -such clicks is still available by holding down the @kbd{SHIFT} key +such clicks is still available by holding down the @key{SHIFT} key when you press the mouse button. Xterm Mouse mode is a global minor mode (@pxref{Minor Modes}). Repeating the command turns the mode off again. @@ -1356,7 +1789,7 @@ again. enable mouse support. You must have the gpm server installed and running on your system in order for this to work. Note that when this mode is enabled, you cannot use the mouse to transfer text -between Emacs and other programs which use GPM. This is due to +between Emacs and other programs which use GPM@. This is due to limitations in GPM and the Linux kernel. @iftex |