# HG changeset patch # User Glenn Morris # Date 1189053968 0 # Node ID dd1e0f7439230abef393f377e0f0bbedda1c4e0a # Parent f144b998e85fb4a7053004880a96cc7e0c2714c1 Move here from ../../man diff -r f144b998e85f -r dd1e0f743923 doc/emacs/frames.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/frames.texi Thu Sep 06 04:46:08 2007 +0000 @@ -0,0 +1,1113 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Frames, International, Windows, Top +@chapter Frames and Graphical Displays +@cindex frames + + When using a graphical display, you can create multiple windows at +the system in a single Emacs session. Each system-level window that +belongs to Emacs displays a @dfn{frame} which can contain one or +several Emacs windows. A frame initially contains a single +general-purpose Emacs window which you can subdivide vertically or +horizontally into smaller windows. A frame normally contains its own +echo area and minibuffer, but you can make frames that don't have +these---they use the echo area and minibuffer of another frame. + + To avoid confusion, we reserve the word ``window'' for the +subdivisions that Emacs implements, and never use it to refer to a +frame. + + Editing you do in one frame affects the other frames. For +instance, if you put text in the kill ring in one frame, you can yank it +in another frame. If you exit Emacs through @kbd{C-x C-c} in one frame, +it terminates all the frames. To delete just one frame, use @kbd{C-x 5 +0} (that is zero, not @kbd{o}). + + Emacs compiled for MS-DOS emulates some windowing functionality, +so that you can use many of the features described in this chapter. +@iftex +@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{MS-DOS Mouse}. +@end ifnottex + +@menu +* Cut and Paste:: Mouse commands for cut and paste. +* Mouse References:: Using the mouse to select an item from a list. +* Menu Mouse Clicks:: Mouse clicks that bring up menus. +* Mode Line Mouse:: Mouse clicks on the mode line. +* Creating Frames:: Creating additional Emacs frames with various contents. +* Frame Commands:: Iconifying, deleting, and switching frames. +* Speedbar:: How to make and use a speedbar frame. +* Multiple Displays:: How one Emacs job can talk to several displays. +* Special Buffer Frames:: You can make certain buffers have their own frames. +* Frame Parameters:: Changing the colors and other modes of frames. +* Scroll Bars:: How to enable and disable scroll bars; how to use them. +* Wheeled Mice:: Using mouse wheels for scrolling. +* 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. +* Dialog Boxes:: Controlling use of dialog boxes. +* Tooltips:: Displaying information at the current mouse position. +* Mouse Avoidance:: Moving the mouse pointer out of the way. +* Non-Window Terminals:: Multiple frames on terminals that show only one. +* Text-Only Mouse:: Using the mouse in text-only terminals. +@end menu + +@node Cut and Paste +@section Killing and Yanking on Graphical Displays + + This section describes facilities for selecting a region, killing, +and yanking using the mouse. + +@menu +* Mouse Commands:: Moving, cutting, and pasting, with the mouse. +* Cut/Paste Other App:: Transfering text between Emacs and other apps. +* Word and Line Mouse:: Mouse commands for selecting whole words or lines. +* Secondary Selection:: Cutting without altering point and mark. +* Clipboard:: Using the clipboard for selections. +@end menu + +@node Mouse Commands +@subsection Mouse Commands for Editing +@cindex mouse buttons (what they do) + + The mouse commands for selecting and copying a region are mostly +compatible with the @code{xterm} program. You can use the same mouse +commands for copying between Emacs and other window-based programs. +Most of these commands also work in Emacs when you run it under an +@code{xterm} terminal. + +@kindex DELETE @r{(and mouse selection)} + If you select a region with any of these mouse commands, and then +immediately afterward type the @key{DELETE} function key, it deletes the +region that you selected. The @key{BACKSPACE} function key and the +@acronym{ASCII} character @key{DEL} do not do this; if you type any other key +in between the mouse command and @key{DELETE}, it does not do this. + +@findex mouse-set-region +@findex mouse-set-point +@findex mouse-yank-at-click +@findex mouse-save-then-click +@kindex Mouse-1 +@kindex Mouse-2 +@kindex Mouse-3 +@table @kbd +@item Mouse-1 +Move point to where you click (@code{mouse-set-point}). +This is normally the left button. + +@vindex x-mouse-click-focus-ignore-position +Normally, Emacs does not distinguish between ordinary mouse clicks and +clicks that select a frame. When you click on a frame to select it, +that also changes the selected window and cursor position according to +the mouse click position. On the X window system, you can change this +behavior by setting the variable +@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the +first click selects the frame, but does not affect the selected window +or cursor position. If you click again in the same place, since that +click will be in the selected frame, it will change the window or +cursor position. + +@item Drag-Mouse-1 +Set the region to the text you select by dragging, and copy it to the +kill ring (@code{mouse-set-region}). You can specify both ends of the +region with this single command. + +@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 +back into the window. This way, you can select regions that don't fit +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-copy-region +If the variable @code{mouse-drag-copy-region} is @code{nil}, this +mouse command does not copy the selected region into the kill ring. + +@item Mouse-2 +Yank the last killed text, where you click (@code{mouse-yank-at-click}). +This is normally the middle button. + +@item Mouse-3 +This command, @code{mouse-save-then-kill}, has several functions +depending on where you click and the status of the region. + +The most basic case is when you click @kbd{Mouse-1} in one place and +then @kbd{Mouse-3} in another. This selects the text between those two +positions as the region. It also copies the new region to the kill +ring, so that you can copy it to someplace else. + +If you click @kbd{Mouse-1} in the text, scroll with the scroll bar, and +then click @kbd{Mouse-3}, it remembers where point was before scrolling +(where you put it with @kbd{Mouse-1}), and uses that position as the +other end of the region. This is so that you can select a region that +doesn't fit entirely on the screen. + +More generally, if you do not have a highlighted region, @kbd{Mouse-3} +selects the text between point and the click position as the region. It +does this by setting the mark where point was, and moving point to where +you click. + +If you have a highlighted region, or if the region was set just before +by dragging button 1, @kbd{Mouse-3} adjusts the nearer end of the region +by moving it to where you click. The adjusted region's text also +replaces the old region's text in the kill ring. + +If you originally specified the region using a double or triple +@kbd{Mouse-1}, so that the region is defined to consist of entire words +or lines, then adjusting the region with @kbd{Mouse-3} also proceeds by +entire words or lines. + +If you use @kbd{Mouse-3} a second time consecutively, at the same place, +that kills the region already selected. +@end table + + The simplest way to kill text with the mouse is to press @kbd{Mouse-1} +at one end, then press @kbd{Mouse-3} twice at the other end. +@xref{Killing}. To copy the text into the kill ring without deleting it +from the buffer, press @kbd{Mouse-3} just once---or just drag across the +text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it. + +@vindex mouse-yank-at-point + To yank the killed or copied text somewhere else, move the mouse there +and press @kbd{Mouse-2}. @xref{Yanking}. However, if +@code{mouse-yank-at-point} is non-@code{nil}, @kbd{Mouse-2} yanks at +point. Then it does not matter where you click, or even which of the +frame's windows you click on. The default value is @code{nil}. This +variable also affects yanking the secondary selection. + +@cindex Delete Selection mode +@cindex mode, Delete Selection +@findex delete-selection-mode + Many graphical applications follow the convention that insertion while text +is selected deletes the selected text. You can make Emacs behave this +way by enabling Delete Selection mode---with @kbd{M-x +delete-selection-mode} or using Custom. Another effect of this mode +is that @key{DEL}, @kbd{C-d} and some other keys, when a selection +exists, will kill the whole selection. It also enables Transient Mark +mode (@pxref{Transient Mark}). + +@node Cut/Paste Other App +@subsection Cut and Paste with Other Window Applications + +@cindex cutting +@cindex pasting +@cindex X cutting and pasting + To copy text to another windowing application, kill it or save it in +the kill ring. Then use the ``paste'' or ``yank'' command of the +other application to insert the text. + + To copy text from another windowing application, use its ``cut'' or +``copy'' command to select the text you want. Then yank it in Emacs +with @kbd{C-y} or @kbd{Mouse-2}. + +@cindex primary selection +@cindex cut buffer +@cindex selection, primary +@vindex x-cut-buffer-max + When Emacs puts text into the kill ring, or rotates text to the +front of the kill ring, it sets the @dfn{primary selection} in the +window system. This is how other windowing applications can access +the text. On the X Window System, emacs also stores the text in the +cut buffer, but only if the text is short enough (the value of +@code{x-cut-buffer-max} specifies the maximum number of characters); +putting long strings in the cut buffer can be slow. + + The commands to yank the first entry in the kill ring actually check +first for a primary selection in another program; after that, they check +for text in the cut buffer. If neither of those sources provides text +to yank, the kill ring contents are used. + + The standard coding system for X Window System selections is +@code{compound-text-with-extensions}. To specify another coding +system for selections, use @kbd{C-x @key{RET} x} or @kbd{C-x @key{RET} +X}. @xref{Communication Coding}. + +@node Word and Line Mouse +@subsection Mouse Commands for Words and Lines + + These variants of @kbd{Mouse-1} select entire words or lines at a time. + +@table @kbd +@item Double-Mouse-1 +This key sets the region around the word which you click on. If you +click on a character with ``symbol'' syntax (such as underscore, in C +mode), it sets the region around the symbol surrounding that character. + +If you click on a character with open-parenthesis or close-parenthesis +syntax, it sets the region around the parenthetical grouping +which that character starts or ends. If you click on a character with +string-delimiter syntax (such as a singlequote or doublequote in C), it +sets the region around the string constant (using heuristics to figure +out whether that character is the beginning or the end of it). + +@item Double-Drag-Mouse-1 +This key selects a region made up of the words you drag across. + +@item Triple-Mouse-1 +This key sets the region around the line you click on. + +@item Triple-Drag-Mouse-1 +This key selects a region made up of the lines you drag across. +@end table + +@node Secondary Selection +@subsection Secondary Selection +@cindex secondary selection + + The @dfn{secondary selection} is another way of selecting text using +the X Window System. It does not use point or the mark, so you can +use it to kill text without setting point or the mark. + +@table @kbd +@findex mouse-set-secondary +@kindex M-Drag-Mouse-1 +@item M-Drag-Mouse-1 +Set the secondary selection, with one end at the place where you press +down the button, and the other end at the place where you release it +(@code{mouse-set-secondary}). The highlighting appears and changes as +you drag. You can control the appearance of the highlighting by +customizing the @code{secondary-selection} face (@pxref{Face +Customization}). + +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 +back into the window. This way, you can mark regions that don't fit +entirely on the screen. + +This way of setting the secondary selection does not alter the kill ring. + +@findex mouse-start-secondary +@kindex M-Mouse-1 +@item M-Mouse-1 +Set one endpoint for the @dfn{secondary selection} +(@code{mouse-start-secondary}). + +@findex mouse-secondary-save-then-kill +@kindex M-Mouse-3 +@item M-Mouse-3 +Make a secondary selection, using the place specified with @kbd{M-Mouse-1} +as the other end (@code{mouse-secondary-save-then-kill}). This also +puts the selected text in the kill ring. A second click at the same +place kills the secondary selection just made. + +@findex mouse-yank-secondary +@kindex M-Mouse-2 +@item M-Mouse-2 +Insert the secondary selection where you click +(@code{mouse-yank-secondary}). This places point at the end of the +yanked text. +@end table + +Double or triple clicking of @kbd{M-Mouse-1} operates on words and +lines, much like @kbd{Mouse-1}. + +If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks +at point. Then it does not matter precisely where you click, or even +which of the frame's windows you click on. @xref{Mouse Commands}. + +@node Clipboard +@subsection Using the Clipboard +@cindex clipboard +@vindex x-select-enable-clipboard +@findex menu-bar-enable-clipboard +@cindex OpenWindows +@cindex Gnome + + Apart from the primary and secondary selection types, Emacs can +handle the @dfn{clipboard} selection type which is used by some +applications, particularly under OpenWindows and Gnome. + + The command @kbd{M-x menu-bar-enable-clipboard} makes the @code{Cut}, +@code{Paste} and @code{Copy} menu items, as well as the keys of the same +names, all use the clipboard. + + You can customize the variable @code{x-select-enable-clipboard} to make +the Emacs yank functions consult the clipboard before the primary +selection, and to make the kill functions to store in the clipboard as +well as the primary selection. Otherwise they do not access the +clipboard at all. Using the clipboard is the default on MS-Windows and Mac, +but not on other systems. + +@node Mouse References +@section Following References with the Mouse +@kindex Mouse-1 @r{(selection)} +@kindex Mouse-2 @r{(selection)} + + Some read-only Emacs buffers include references you can follow, or +commands you can activate. These include names of files, of buffers, +of possible completions, of matches for a pattern, as well as the +buttons in Help buffers and customization buffers. You can follow the +reference or activate the command by moving point to it and typing +@key{RET}. You can also do this with the mouse, using either +@kbd{Mouse-1} or @kbd{Mouse-2}. + + Since yanking text into a read-only buffer is not allowed, these +buffers generally define @kbd{Mouse-2} to follow a reference or +activate a command. For example, if you click @kbd{Mouse-2} on a file +name in a Dired buffer, you visit that file. If you click +@kbd{Mouse-2} on an error message in the @samp{*Compilation*} buffer, +you go to the source code for that error message. If you click +@kbd{Mouse-2} on a completion in the @samp{*Completions*} buffer, you +choose that completion. + + However, most applications use @kbd{Mouse-1} to do this sort of +thing, so Emacs implements this too. If you click @kbd{Mouse-1} +quickly on a reference or button, it follows or activates. If you +click slowly, it moves point as usual. Dragging, meaning moving the +mouse while it is held down, also has its usual behavior of setting +the region. + +@vindex mouse-1-click-in-non-selected-windows + Normally, the @kbd{Mouse-1} click behavior is performed on links in +any window. The variable @code{mouse-1-click-in-non-selected-windows} +controls whether @kbd{Mouse-1} has this behavior even in non-selected +windows, or only in the selected window. + +@vindex mouse-highlight + You can usually tell when @kbd{Mouse-1} and @kbd{Mouse-2} have this +special sort of meaning because the sensitive text highlights when you +move the mouse over it. The variable @code{mouse-highlight} controls +whether to do this highlighting always (even when such text appears +where the mouse already is), never, or only immediately after you move +the mouse. + +@vindex mouse-1-click-follows-link + In Emacs versions before 22, only @kbd{Mouse-2} follows links and +@kbd{Mouse-1} always sets point. If you prefer this older behavior, +set the variable @code{mouse-1-click-follows-link} to @code{nil}. +This variable also lets you choose various other alternatives for +following links with the mouse. Type @kbd{C-h v +mouse-1-click-follows-link @key{RET}} for more details. + +@node Menu Mouse Clicks +@section Mouse Clicks for Menus + + Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers +bring up menus. + +@table @kbd +@item C-Mouse-1 +@kindex C-Mouse-1 +This menu is for selecting a buffer. + +The MSB (``mouse select buffer'') global minor mode makes this +menu smarter and more customizable. @xref{Buffer Menus}. + +@item C-Mouse-2 +@kindex C-Mouse-2 +This menu is for specifying faces and other text properties +for editing formatted text. @xref{Formatted Text}. + +@item C-Mouse-3 +@kindex C-Mouse-3 +This menu is mode-specific. For most modes if Menu-bar mode is on, +this menu has the same items as all the mode-specific menu-bar menus +put together. Some modes may specify a different menu for this +button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific +menu. We took a survey of users, and found they preferred to keep +@kbd{Mouse-3} for selecting and killing regions. Hence the decision +to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead, +do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If +Menu-bar mode is off, this menu contains all the items which would be +present in the menu bar---not just the mode-specific ones---so that +you can access them without having to display the menu bar. + +@item S-Mouse-1 +This menu is for specifying the frame's default font. +@end table + +@node Mode Line Mouse +@section Mode Line Mouse Commands +@cindex mode line, mouse +@cindex mouse on mode line + + You can use mouse clicks on window mode lines to select and manipulate +windows. + + Some areas of the mode line, such as the buffer name and the major +mode name, have their own special mouse bindings. These areas are +highlighted when you hold the mouse over them, and information about +the special bindings will be displayed (@pxref{Tooltips}). This +section's commands do not apply in those areas. + +@table @kbd +@item Mouse-1 +@kindex Mouse-1 @r{(mode line)} +@kbd{Mouse-1} on a mode line selects the window it belongs to. By +dragging @kbd{Mouse-1} on the mode line, you can move it, thus +changing the height of the windows above and below. Changing heights +with the mouse in this way never deletes windows, it just refuses to +make any window smaller than the minimum height. + +@item Mouse-2 +@kindex Mouse-2 @r{(mode line)} +@kbd{Mouse-2} on a mode line expands that window to fill its frame. + +@item Mouse-3 +@kindex Mouse-3 @r{(mode line)} +@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the +frame has only one window, it buries the current buffer instead, and +switches to another buffer. + +@item C-Mouse-2 +@kindex C-mouse-2 @r{(mode line)} +@kbd{C-Mouse-2} on a mode line splits the window above +horizontally, above the place in the mode line where you click. +@end table + +@kindex C-Mouse-2 @r{(scroll bar)} +@kindex Mouse-1 @r{(scroll bar)} + Using @kbd{Mouse-1} on the divider between two side-by-side mode +lines, you can move the vertical boundary left or right. Using +@kbd{C-Mouse-2} on a scroll bar splits the corresponding window +vertically. @xref{Split Window}. + +@node Creating Frames +@section Creating Frames +@cindex creating frames + +@kindex C-x 5 + The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel +subcommands. The difference is that @kbd{C-x 5} commands create a new +frame rather than just a new window in the selected frame (@pxref{Pop +Up Window}). If an existing visible or iconified frame already displays +the requested material, these commands use the existing frame, after +raising or deiconifying as necessary. + + The various @kbd{C-x 5} commands differ in how they find or create the +buffer to select: + +@table @kbd +@item C-x 5 2 +@kindex C-x 5 2 +@findex make-frame-command +Create a new frame (@code{make-frame-command}). +@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{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. +@xref{Sending Mail}. +@item C-x 5 . +Find a tag in the current tag table in another frame. This runs +@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. +@xref{Tags}. +@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}. +@end table + +@cindex default-frame-alist +@cindex initial-frame-alist +@cindex face customization, in @file{~/.emacs} +@cindex color customization, in @file{~/.emacs} + You can control the appearance of new frames you create by setting the +frame parameters in @code{default-frame-alist}. You can use the +variable @code{initial-frame-alist} to specify parameters that affect +only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs +Lisp Reference Manual}, for more information. + +@cindex font (default) + The easiest way to specify the principal font for all your Emacs +frames is with an X resource (@pxref{Font X}), but you can also do it by +modifying @code{default-frame-alist} to specify the @code{font} +parameter, as shown here: + +@example +(add-to-list 'default-frame-alist '(font . "10x20")) +@end example + +@noindent +Here's a similar example for specifying a foreground color: + +@example +(add-to-list 'default-frame-alist '(foreground-color . "blue")) +@end example + +@noindent +By putting such customizations in your @file{~/.emacs} init file, you +can control the appearance of all the frames Emacs creates, including +the initial one. + +@node Frame Commands +@section Frame Commands + + The following commands let you create, delete and operate on frames: + +@table @kbd +@item C-z +@kindex C-z @r{(X windows)} +@findex iconify-or-deiconify-frame +Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}). +When typed on an Emacs frame's icon, deiconify instead. + +The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under +a graphical display that allows multiple applications to operate +simultaneously in their own windows, so Emacs gives @kbd{C-z} a +different binding in that case. + +@item C-x 5 0 +@kindex C-x 5 0 +@findex delete-frame +Delete the selected frame (@code{delete-frame}). This is not allowed if +there is only one frame. + +@item C-x 5 o +@kindex C-x 5 o +@findex other-frame +Select another frame, raise it, and warp the mouse to it so that it +stays selected. If you repeat this command, it cycles through all the +frames on your terminal. + +@item C-x 5 1 +@kindex C-x 5 1 +@findex delete-other-frames +Delete all frames except the selected one. +@end table + +@vindex focus-follows-mouse + To make the command @kbd{C-x 5 o} work properly, you must tell Emacs +how the system (or the window manager) generally handles +focus-switching between windows. There are two possibilities: either +simply moving the mouse onto a window selects it (gives it focus), or +you have to click on it in a suitable way to do so. On X, this focus +policy also affects whether the focus is given to a frame that Emacs +raises. Unfortunately there is no way Emacs can find out +automatically which way the system handles this, so you have to +explicitly say, by setting the variable @code{focus-follows-mouse}. +If just moving the mouse onto a window selects it, that variable +should be @code{t}; if a click is necessary, the variable should be +@code{nil}. + +The window manager that is part of MS-Windows always gives focus to a +frame that raises, so this variable has no effect in the native +MS-Windows build of Emacs. + +@node Speedbar +@section Speedbar Frames +@cindex speedbar + +@cindex attached frame (of speedbar) + The @dfn{speedbar} is a special frame for conveniently navigating in +or operating on another frame. The speedbar, when it exists, is +always associated with a specific frame, called its @dfn{attached +frame}; all speedbar operations act on that frame. + + Type @kbd{M-x speedbar} to create the speedbar and associate it with +the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} +again, or select the speedbar and type @kbd{q}. (You can also delete +the speedbar frame like any other Emacs frame.) If you wish to +associate the speedbar with a different frame, dismiss it and call +@kbd{M-x speedbar} from that frame. + + The speedbar can operate in various modes. Its default mode is +@dfn{File Display} mode, which shows the files in the current +directory of the selected window of the attached frame, one file per +line. Clicking on a file name visits that file in the selected window +of the attached frame, and clicking on a directory name shows that +directory in the speedbar (@pxref{Mouse References}). Each line also +has a box, @samp{[+]} or @samp{<+>}, that you can click on to +@dfn{expand} the contents of that item. Expanding a directory adds +the contents of that directory to the speedbar display, underneath the +directory's own line. Expanding an ordinary file adds a list of the +tags in that file to the speedbar display; you can click on a tag name +to jump to that tag in the selected window of the attached frame. +When a file or directory is expanded, the @samp{[+]} changes to +@samp{[-]}; you can click on that box to @dfn{contract} the item, +hiding its contents. + + You navigate through the speedbar using the keyboard, too. Typing +@kbd{RET} while point is on a line in the speedbar is equivalent to +clicking the item on the current line, and @kbd{SPC} expands or +contracts the item. @kbd{U} displays the parent directory of the +current directory. To copy, delete, or rename the file on the current +line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a +new directory, type @kbd{M}. + + Another general-purpose speedbar mode is @dfn{Buffer Display} mode; +in this mode, the speedbar displays a list of Emacs buffers. To +switch to this mode, type @kbd{b} in the speedbar. To return to File +Display mode, type @kbd{f}. You can also change the display mode by +clicking @kbd{mouse-3} anywhere in the speedbar window (or +@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the +pop-up menu. + + Some major modes, including Rmail mode, Info, and GUD, have +specialized ways of putting useful items into the speedbar for you to +select. For example, in Rmail mode, the speedbar shows a list of Rmail +files, and lets you move the current message to another Rmail file by +clicking on its @samp{} box. + + For more details on using and programming the speedbar, @xref{Top, +Speedbar,,speedbar, Speedbar Manual}. + +@node Multiple Displays +@section Multiple Displays +@cindex multiple displays + + A single Emacs can talk to more than one X display. Initially, Emacs +uses just one display---the one specified with the @env{DISPLAY} +environment variable or with the @samp{--display} option (@pxref{Initial +Options}). To connect to another display, use the command +@code{make-frame-on-display}: + +@findex make-frame-on-display +@table @kbd +@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} +Create a new frame on display @var{display}. +@end table + + A single X server can handle more than one screen. When you open +frames on two screens belonging to one server, Emacs knows they share a +single keyboard, and it treats all the commands arriving from these +screens as a single stream of input. + + When you open frames on different X servers, Emacs makes a separate +input stream for each server. This way, two users can type +simultaneously on the two displays, and Emacs will not garble their +input. Each server also has its own selected frame. The commands you +enter with a particular X server apply to that server's selected frame. + + Despite these features, people using the same Emacs job from different +displays can still interfere with each other if they are not careful. +For example, if any one types @kbd{C-x C-c}, that exits the Emacs job +for all of them! + +@node Special Buffer Frames +@section Special Buffer Frames + +@vindex special-display-buffer-names + You can make certain chosen buffers, which Emacs normally displays +in ``another window,'' appear in special frames of their own. To do +this, set the variable @code{special-display-buffer-names} to a list +of buffer names; any buffer whose name is in that list automatically +gets a special frame, when an Emacs command wants to display it ``in +another window.'' + + For example, if you set the variable this way, + +@example +(setq special-display-buffer-names + '("*Completions*" "*grep*" "*tex-shell*")) +@end example + +@noindent +then completion lists, @code{grep} output and the @TeX{} mode shell +buffer get individual frames of their own. These frames, and the +windows in them, are never automatically split or reused for any other +buffers. They continue to show the buffers they were created for, +unless you alter them by hand. Killing the special buffer deletes its +frame automatically. + +@vindex special-display-regexps + More generally, you can set @code{special-display-regexps} to a list +of regular expressions; then a buffer gets its own frame if its name +matches any of those regular expressions. (Once again, this applies only +to buffers that normally get displayed for you in ``another window.'') + +@vindex special-display-frame-alist + The variable @code{special-display-frame-alist} specifies the frame +parameters for these frames. It has a default value, so you don't need +to set it. + + For those who know Lisp, an element of +@code{special-display-buffer-names} or @code{special-display-regexps} +can also be a list. Then the first element is the buffer name or +regular expression; the rest of the list specifies how to create the +frame. It can be an association list specifying frame parameter +values; these values take precedence over parameter values specified +in @code{special-display-frame-alist}. If you specify the symbol +@code{same-window} as a ``frame parameter'' in this list, with a +non-@code{nil} value, that means to use the selected window if +possible. If you use the symbol @code{same-frame} as a ``frame +parameter'' in this list, with a non-@code{nil} value, that means to +use the selected frame if possible. + + Alternatively, the value can have this form: + +@example +(@var{function} @var{args}...) +@end example + +@noindent +where @var{function} is a symbol. Then the frame is constructed by +calling @var{function}; its first argument is the buffer, and its +remaining arguments are @var{args}. + + An analogous feature lets you specify buffers which should be +displayed in the selected window. @xref{Force Same Window}. The +same-window feature takes precedence over the special-frame feature; +therefore, if you add a buffer name to +@code{special-display-buffer-names} and it has no effect, check to see +whether that feature is also in use for the same buffer name. + +@node Frame Parameters +@section Setting Frame Parameters +@cindex Auto-Raise mode +@cindex Auto-Lower mode + +@kindex S-Mouse-1 + You can specify the font and colors used for text display, and the +colors for the frame borders, the cursor, and the mouse cursor, by +customizing the faces @code{default}, @code{border}, @code{cursor} and +@code{mouse}. @xref{Face Customization}. You can also set a frame's +default font through a pop-up menu. Press @kbd{S-Mouse-1} to activate +this menu. + + These commands are available for controlling the window management +behavior of the selected frame. + +@table @kbd +@findex auto-raise-mode +@item M-x auto-raise-mode +Toggle whether or not the selected frame should auto-raise. Auto-raise +means that every time you move the mouse onto the frame, it raises the +frame. + +Some window managers also implement auto-raise. If you enable +auto-raise for Emacs frames in your window manager, it will work, but +it is beyond Emacs' control, so @code{auto-raise-mode} has no effect +on it. + +@findex auto-lower-mode +@item M-x auto-lower-mode +Toggle whether or not the selected frame should auto-lower. +Auto-lower means that every time you move the mouse off the frame, +the frame moves to the bottom of the stack on the screen. + +The command @code{auto-lower-mode} has no effect on auto-lower +implemented by the window manager. To control that, you must use the +appropriate window manager features. +@end table + + In Emacs versions that use an X toolkit, the color-setting and +font-setting functions don't affect menus and the menu bar, since they +are displayed by their own widget classes. To change the appearance of +the menus and menu bar, you must use X resources (@pxref{Resources}). +@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of +font. + + Colors, fonts, and other attributes of the frame's display can also +be customized by setting frame parameters in the variable +@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed +description of frame parameters and customization, see @ref{Frame +Parameters,,, elisp, The Emacs Lisp Reference Manual}. + +@node Scroll Bars +@section Scroll Bars +@cindex Scroll Bar mode +@cindex mode, Scroll Bar + + On graphical displays, Emacs normally makes a @dfn{scroll bar} at +the left of each Emacs window.@footnote{Placing it at the left is +usually more useful with overlapping frames with text starting at the +left margin.} The scroll bar runs the height of the window, and shows +a moving rectangular inner box which represents the portion of the +buffer currently displayed. The entire height of the scroll bar +represents the entire length of the buffer. + + You can use @kbd{Mouse-2} (normally, the middle button) in the scroll +bar to move or drag the inner box up and down. If you move it to the +top of the scroll bar, you see the top of the buffer. If you move it to +the bottom of the scroll bar, you see the bottom of the buffer. + + The left and right buttons in the scroll bar scroll by controlled +increments. @kbd{Mouse-1} (normally, the left button) moves the line at +the level where you click up to the top of the window. @kbd{Mouse-3} +(normally, the right button) moves the line at the top of the window +down to the level where you click. By clicking repeatedly in the same +place, you can scroll by the same distance over and over. + + You can also click @kbd{C-Mouse-2} in the scroll bar to split a +window vertically. The split occurs on the line where you click. + +@findex scroll-bar-mode +@vindex scroll-bar-mode + You can enable or disable Scroll Bar mode with the command @kbd{M-x +scroll-bar-mode}. With no argument, it toggles the use of scroll +bars. With an argument, it turns use of scroll bars on if and only if +the argument is positive. This command applies to all frames, +including frames yet to be created. Customize the variable +@code{scroll-bar-mode} to control the use of scroll bars at startup. +You can use it to specify that they are placed at the right of windows +if you prefer that. You have to set this variable through the +@samp{Customize} interface (@pxref{Easy Customization}), or it will +not work properly. + + You can also use the X resource @samp{verticalScrollBars} to control +the initial setting of Scroll Bar mode. @xref{Resources}. + +@findex toggle-scroll-bar + To enable or disable scroll bars for just the selected frame, use the +command @kbd{M-x toggle-scroll-bar}. + +@vindex scroll-bar-width +@cindex width of the scroll bar + You can control the scroll bar width by changing the value of the +@code{scroll-bar-width} frame parameter. + +@node Wheeled Mice +@section Scrolling With ``Wheeled'' Mice + +@cindex mouse wheel +@cindex wheel, mouse +@findex mouse-wheel-mode +@cindex Mouse Wheel minor mode +@cindex mode, Mouse Wheel + Some mice have a ``wheel'' instead of a third button. You can +usually click the wheel to act as either @kbd{Mouse-2} or +@kbd{Mouse-3}, depending on the setup. You can also use the wheel to +scroll windows instead of using the scroll bar or keyboard commands. +Mouse wheel support only works if the system generates appropriate +events; whenever possible, it is turned on by default. To toggle this +feature, use @kbd{M-x mouse-wheel-mode}. + +@vindex mouse-wheel-follow-mouse +@vindex mouse-wheel-scroll-amount +@vindex mouse-wheel-progressive-speed + The two 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. + +@node Drag and Drop +@section Drag and Drop +@cindex drag and drop + + Emacs supports @dfn{drag and drop} using the mouse. For instance, +dropping text onto an Emacs frame inserts the text where it is dropped. +Dropping a file onto an Emacs frame visits that file. As a special +case, dropping the 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 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 +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. + +@node Menu Bars +@section Menu Bars +@cindex Menu Bar mode +@cindex mode, Menu Bar +@findex menu-bar-mode +@vindex menu-bar-mode + + You can turn display of menu bars on or off with @kbd{M-x +menu-bar-mode} or by customizing the variable @code{menu-bar-mode}. +With no argument, this command toggles Menu Bar mode, a +minor mode. With an argument, the command turns Menu Bar mode on if the +argument is positive, off if the argument is not positive. You can use +the X resource @samp{menuBarLines} to control the initial setting of +Menu Bar mode. @xref{Resources}. + +@kindex C-Mouse-3 @r{(when menu bar is disabled)} + Expert users often turn off the menu bar, especially on text-only +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}. + + @xref{Menu Bar}, for information on how to invoke commands with the +menu bar. @xref{X Resources}, for how to customize the menu bar +menus' visual appearance. + +@node Tool Bars +@section Tool Bars +@cindex Tool Bar mode +@cindex mode, Tool Bar +@cindex icons, toolbar + + The @dfn{tool bar} is a line (or lines) of icons at the top of the +Emacs window, just below the menu bar. You can click on these icons +with the mouse to do various jobs. + + The global tool bar contains general commands. Some major modes +define their own tool bars to replace it. A few ``special'' modes +that are not designed for ordinary editing remove some items from the +global tool bar. + + Tool bars work only on a graphical display. The tool bar uses colored +XPM icons if Emacs was built with XPM support. Otherwise, the tool +bar uses monochrome icons (PBM or XBM format). + +@findex tool-bar-mode +@vindex tool-bar-mode + You can turn display of tool bars on or off with @kbd{M-x +tool-bar-mode} or by customizing the option @code{tool-bar-mode}. + +@node Dialog Boxes +@section Using Dialog Boxes +@cindex dialog boxes + +@vindex use-dialog-box + A dialog box is a special kind of menu for asking you a yes-or-no +question or some other special question. Many Emacs commands use a +dialog box to ask a yes-or-no question, if you used the mouse to +invoke the command to begin with. + + You can customize the variable @code{use-dialog-box} to suppress the +use of dialog boxes. This also controls whether to use file selection +windows (but those are not supported on all platforms). + +@vindex use-file-dialog + A file selection window is a special kind of dialog box for asking +for file names. You can customize the variable @code{use-file-dialog} +to suppress the use of file selection windows, even if you still want +other kinds of dialogs. This variable has no effect if you have +suppressed all dialog boxes with the variable @code{use-dialog-box}. + +@vindex x-gtk-show-hidden-files + For Gtk+ version 2.4 and newer, Emacs use the Gtk+ file chooser +dialog. Emacs adds a toggle button that enables and disables showing +of hidden files (files starting with a dot) in that dialog. The +variable @code{x-gtk-show-hidden-files} controls whether to show +hidden files by default. + +@vindex x-gtk-use-old-file-dialog + For Gtk+ versions 2.4 through 2.10, you can select the old file +dialog (@code{gtk-file-selector}) by setting the variable +@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If it is +@code{nil}, Emacs uses @code{gtk-file-chooser}. If Emacs is built +with a Gtk+ version that has only one file dialog, this variable has +no effect. + +@vindex x-gtk-file-dialog-help-text + Emacs adds help text to the Gtk+ file chooser dialog. The variable +@code{x-gtk-file-dialog-help-text} specifies the text to add; if it is +@code{nil}, that disables the added text. + +@node Tooltips +@section Tooltips +@cindex tooltips + + @dfn{Tooltips} are small windows that display text information at the +current mouse position. They activate when there is a pause in mouse +movement. There are two types of tooltip: help tooltips and GUD +tooltips. + + @dfn{Help tooltips} typically display over text---including the mode +line---but are also available for other parts of the Emacs frame, such +as the tool bar and menu items. + +@findex tooltip-mode + You can toggle display of help tooltips (Tooltip mode) with the +command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the +help text is displayed in the echo area instead. + + @dfn{GUD tooltips} show values of variables. They are useful when +you are debugging a program. @xref{Debugger Operation}. + +@vindex tooltip-delay + The variables @code{tooltip-delay} specifies how long Emacs should +wait before displaying a tooltip. For additional customization +options for displaying tooltips, use @kbd{M-x customize-group +@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on +customizing the windows that display tooltips. + +@node Mouse Avoidance +@section Mouse Avoidance +@cindex avoiding mouse in the way of your typing +@cindex mouse avoidance + +@vindex mouse-avoidance-mode +Mouse Avoidance mode keeps the mouse pointer away from point, to avoid +obscuring text you want to edit. Whenever it moves the mouse, it also +raises the frame. To use Mouse Avoidance mode, customize the variable +@code{mouse-avoidance-mode}. You can set this to various values to +move the mouse in several ways: + +@table @code +@item banish +Move the mouse to the upper-right corner on any key-press; +@item exile +Move the mouse to the corner only if the cursor gets too close, +and allow it to return once the cursor is out of the way; +@item jump +If the cursor gets too close to the mouse, displace the mouse +a random distance & direction; +@item animate +As @code{jump}, but shows steps along the way for illusion of motion; +@item cat-and-mouse +The same as @code{animate}; +@item proteus +As @code{animate}, but changes the shape of the mouse pointer too. +@end table + +@findex mouse-avoidance-mode +You can also use the command @kbd{M-x mouse-avoidance-mode} to enable +the mode. + +@node Non-Window Terminals +@section Non-Window Terminals +@cindex non-window terminals +@cindex single-frame terminals + + On a text-only terminal, Emacs can display only one Emacs frame at a +time. However, you can still create multiple Emacs frames, and switch +between them. Switching frames on these terminals is much like +switching between different window configurations. + + Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x +5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete +the current frame. + + Each frame has a number to distinguish it. If your terminal can +display only one frame at a time, the selected frame's number @var{n} +appears near the beginning of the mode line, in the form +@samp{F@var{n}}. + +@findex set-frame-name +@findex select-frame-by-name + @samp{F@var{n}} is in fact the frame's initial name. You can give +frames more meaningful names if you wish, and you can select a frame +by its name. Use the command @kbd{M-x set-frame-name @key{RET} +@var{name} @key{RET}} to specify a new name for the selected frame, +and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} +to select a frame according to its name. The name you specify appears +in the mode line when the frame is selected. + +@node Text-Only Mouse +@section Using a Mouse in Terminal Emulators +@cindex mouse support +@cindex terminal emulators, mouse support + +Some terminal emulators support mouse clicks in the terminal window. + +@cindex xterm +In a terminal emulator which is compatible with @code{xterm}, +you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over +simple use of the mouse---basically, only non-modified single clicks +are supported. The normal @code{xterm} mouse functionality for such +clicks is still available by holding down the @kbd{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. + +In the console on GNU/Linux, you can use @kbd{M-x t-mouse-mode}. You +need to have the gpm package installed and running on your system in +order for this to work. + +@ignore + arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49 +@end ignore