# HG changeset patch # User Glenn Morris # Date 1189053407 0 # Node ID e560eb704610bb727aa99e2ace6f89f8a3ca7ade # Parent 60fb8ba0c0bb89a734039ef69098fc64eee37cdc Move to ../doc/emacs/, misc/ diff -r 60fb8ba0c0bb -r e560eb704610 man/frames.texi --- a/man/frames.texi Thu Sep 06 04:36:42 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1113 +0,0 @@ -@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