diff options
author | Dave Love <[email protected]> | 1999-09-29 15:17:24 +0000 |
---|---|---|
committer | Dave Love <[email protected]> | 1999-09-29 15:17:24 +0000 |
commit | 6bf7aab68402fd010eae5d280350bd399014406a (patch) | |
tree | 625ed090fc4abe8605e63f152740733c70314c4a /man/frames.texi | |
parent | f58395f66db524e38e011f95f292d7abcc1fe2d1 (diff) |
#
Diffstat (limited to 'man/frames.texi')
-rw-r--r-- | man/frames.texi | 1076 |
1 files changed, 1076 insertions, 0 deletions
diff --git a/man/frames.texi b/man/frames.texi new file mode 100644 index 0000000000..392e890c50 --- /dev/null +++ b/man/frames.texi @@ -0,0 +1,1076 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Frames, International, Windows, Top +@chapter Frames and X Windows +@cindex frames + + When using the X Window System, you can create multiple windows at the +X level in a single Emacs session. Each X 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. + + Editing you do in one frame also 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}. + + To avoid confusion, we reserve the word ``window'' for the +subdivisions that Emacs implements, and never use it to refer to a +frame. + + Emacs compiled for MS-DOS emulates some aspects of the window system +so that you can use many of the features described in this chapter. +@xref{MS-DOS Input}, for more information. + +@menu +* Mouse Commands:: Moving, cutting, and pasting, with the mouse. +* Secondary Selection:: Cutting without altering point and mark. +* 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. +* Speedbar:: How to make and use a speedbar frame. +* Creating Frames:: Creating additional Emacs frames with various contents. +* 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. +* Menu Bars:: Enabling and disabling the menu bar. +* Faces:: How to change the display style using faces. +* Font Lock:: Minor mode for syntactic highlighting using faces. +* Support Modes:: Font Lock support modes make Font Lock faster. +* Highlight Changes:: Using colors to show where you changed the buffer. +* Misc X:: Iconifying and deleting frames. Region highlighting. +* Non-Window Terminals:: Multiple frames on terminals that show only one. +@end menu + +@node Mouse Commands +@section 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 X client programs. + +@kindex DELETE + 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 +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. + +@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. + +@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. + +@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 (sexp) +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 + + 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 cutting and X +@cindex pasting and X +@cindex X cutting and pasting + To copy text to another X window, kill it or save it in the kill ring. +Under X, this also sets the @dfn{primary selection}. Then use the +``paste'' or ``yank'' command of the program operating the other window +to insert the text from the selection. + + To copy text from another X window, use the ``cut'' or ``copy'' command +of the program operating the other window, to select the text you want. +Then yank it in Emacs with @kbd{C-y} or @kbd{Mouse-2}. + + These cutting and pasting commands also work on MS-Windows. + +@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 X server. +This is how other X clients can access the text. Emacs also stores the +text in the cut buffer, but only if the text is short enough +(@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. + +@node Secondary Selection +@section Secondary Selection +@cindex secondary selection + + The @dfn{secondary selection} is another way of selecting text using +X. 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. + +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. + +@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}). 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; all +that matters is which window you click on. @xref{Mouse Commands}. + +@node Mouse References +@section Following References with the Mouse +@kindex Mouse-2 @r{(selection)} + + Some Emacs buffers display lists of various sorts. These include +lists of files, of buffers, of possible completions, of matches for +a pattern, and so on. + + Since yanking text into these buffers is not very useful, most of them +define @kbd{Mouse-2} specially, as a command to use or view the item you +click on. + + 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. + + You can usually tell when @kbd{Mouse-2} has this special sort of +meaning because the sensitive text highlights when you move the mouse +over it. + +@node Menu Mouse Clicks +@section Mouse Clicks for Menus + + Mouse clicks modified with the @key{CTRL} and @key{SHIFT} keys +bring up menus. + +@kindex C-Mouse-3 +@table @kbd +@item C-Mouse-1 +This menu is for selecting a buffer. + +@item C-Mouse-2 +This menu is for specifying faces and other text properties +for editing formatted text. @xref{Formatted Text}. + +@item C-Mouse-3 +This menu is mode-specific. For most modes, 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.} + +@item S-mouse-1 +This menu is for specifying the frame's principal font. +@end table + +@node Mode Line Mouse +@section Mode Line Mouse Commands + + You can use mouse clicks on window mode lines to select and manipulate +windows. + +@table @kbd +@item Mouse-1 +@kbd{Mouse-1} on a mode line selects the window above. By dragging +@kbd{Mouse-1} on the mode line, you can move it, thus changing the +height of the windows above and below. + +@item Mouse-2 +@kbd{Mouse-2} on a mode line expands that window to fill its frame. + +@item Mouse-3 +@kbd{Mouse-3} on a mode line deletes the window above. + +@item C-Mouse-2 +@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 + + @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 + 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 + +@node Speedbar +@section Making and Using a Speedbar Frame +@cindex speedbar + + An Emacs frame can have a @dfn{speedbar}, which is a vertical window +that serves as a scrollable menu of files you could visit and tags +within those files. To create a speedbar, type @kbd{M-x speedbar}; this +creates a speedbar window for the selected frame. From then on, you can +click on a file name in the speedbar to visit that file in the +corresponding Emacs frame, or click on a tag name to jump to that tag in +the Emacs frame. + + Initially the speedbar lists the immediate contents of the current +directory, one file per line. Each line also has a box, @samp{[+]} or +@samp{<+>}, that you can click on with @kbd{Mouse-2} to ``open up'' the +contents of that item. If the line names a directory, opening it adds +the contents of that directory to the speedbar display, underneath the +directory's own line. If the line lists an ordinary file, opening it up +adds a list of the tags in that file to the speedbar display. When a +file is opened up, the @samp{[+]} changes to @samp{[-]}; you can click +on that box to ``close up'' that file (hide its contents). + + 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{<M>} box. + + A speedbar belongs to one Emacs frame, and always operates on that +frame. If you use multiple frames, you can make a speedbar for some or +all of the frames; type @kbd{M-x speedbar} in any given frame to make a +speedbar for it. + +@node Multiple Displays +@section Multiple Displays +@cindex multiple displays + + A single Emacs can talk to more than one X Windows display. +Initially, Emacs uses just one display---the one specified with the +@code{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, for which Emacs normally creates +a second window when you have just one 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 a separate 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}. Alternatively, it 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 colors +@cindex Auto-Raise mode +@cindex Auto-Lower mode + + This section describes commands for altering the display style and +window management behavior of the selected frame. + +@findex set-foreground-color +@findex set-background-color +@findex set-cursor-color +@findex set-mouse-color +@findex set-border-color +@findex auto-raise-mode +@findex auto-lower-mode +@table @kbd +@item M-x set-foreground-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the foreground of the selected frame. +(This also changes the foreground color of the default face.) + +@item M-x set-background-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the background of the selected frame. +(This also changes the background color of the default face.) + +@item M-x set-cursor-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the cursor of the selected frame. + +@item M-x set-mouse-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the mouse cursor when it is over the +selected frame. + +@item M-x set-border-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the border of the selected frame. + +@item M-x list-colors-display +Display the defined color names and show what the colors look like. +This command is somewhat slow. + +@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. + +Note that this auto-raise feature is implemented by Emacs itself. Some +window managers also implement auto-raise. If you enable auto-raise for +Emacs frames in your X window manager, it should work, but it is beyond +Emacs's control and therefore @code{auto-raise-mode} has no effect on +it. + +@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 of X windows. + +The command @code{auto-lower-mode} has no effect on auto-lower +implemented by the X window manager. To control that, you must use +the appropriate window manager features. + +@findex set-frame-font +@item M-x set-frame-font @key{RET} @var{font} @key{RET} +@cindex font (principal) +Specify font @var{font} as the principal font for the selected frame. +The principal font controls several face attributes of the +@code{default} face (@pxref{Faces}). For example, if the principal font +has a height of 12 pt, all text will be drawn in 12 pt fonts, unless you +use another face that specifies a different height. @xref{Font X}, for +ways to list the available fonts on your system. + +@kindex S-Mouse-1 +You can also set a frame's principal font through a pop-up menu. +Press @kbd{S-Mouse-1} to activate this menu. +@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 X}). +@xref{Colors X}, regarding colors. @xref{Font X}, regarding choice of +font. + + For information on 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 + + When using X, Emacs normally makes a @dfn{scroll bar} at the left of +each Emacs window. 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. + + Aside from scrolling, 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 + 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. You can use the X resource +@samp{verticalScrollBars} to control the initial setting of Scroll Bar +mode. @xref{Resources X}. + +@findex toggle-scroll-bar + To enable or disable scroll bars for just the selected frame, use the +@kbd{M-x toggle-scroll-bar} command. + +@node Menu Bars +@section Menu Bars +@cindex Menu Bar mode +@cindex mode, Menu Bar + + You can turn display of menu bars on or off with @kbd{M-x +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 X}. Expert users often turn off the +menu bar, especially on text-only terminals, where this makes one +additional line available for text. + + @xref{Menu Bar}, for information on how to invoke commands with the +menu bar. + +@node Faces +@section Using Multiple Typefaces +@cindex faces + + When using Emacs with X, you can set up multiple styles of displaying +characters. The aspects of style that you can control are the type +font, the foreground color, the background color, and whether to +underline. Emacs on MS-DOS supports faces partially by letting you +control the foreground and background colors of each face +(@pxref{MS-DOS}). + + The way you control display style is by defining named @dfn{faces}. +Each face can specify a type font, a foreground color, a background +color, and an underline flag; but it does not have to specify all of +them. Then by specifying the face or faces to use for a given part +of the text in the buffer, you control how that text appears. + + The style of display used for a given character in the text is +determined by combining several faces. Any aspect of the display style +that isn't specified by overlays or text properties comes from the frame +itself. + + Enriched mode, the mode for editing formatted text, includes several +commands and menus for specifying faces. @xref{Format Faces}, for how +to specify the font for text in the buffer. @xref{Format Colors}, for +how to specify the foreground and background color. + + To alter the appearance of a face, use the customization buffer. +@xref{Face Customization}. You can also use X resources to specify +attributes of particular faces (@pxref{Resources X}). + +@findex list-faces-display + To see what faces are currently defined, and what they look like, type +@kbd{M-x list-faces-display}. It's possible for a given face to look +different in different frames; this command shows the appearance in the +frame in which you type it. Here's a list of the standardly defined +faces: + +@table @code +@item default +This face is used for ordinary text that doesn't specify any other face. +@item modeline +This face is used for mode lines. By default, it's set up as the +inverse of the default face. @xref{Display Vars}. +@item highlight +This face is used for highlighting portions of text, in various modes. +@item region +This face is used for displaying a selected region (when Transient Mark +mode is enabled---see below). +@item secondary-selection +This face is used for displaying a secondary selection (@pxref{Secondary +Selection}). +@item bold +This face uses a bold variant of the default font, if it has one. +@item italic +This face uses an italic variant of the default font, if it has one. +@item bold-italic +This face uses a bold italic variant of the default font, if it has one. +@item underline +This face underlines text. +@end table + +@cindex @code{region} face + When Transient Mark mode is enabled, the text of the region is +highlighted when the mark is active. This uses the face named +@code{region}; you can control the style of highlighting by changing the +style of this face (@pxref{Face Customization}). @xref{Transient Mark}, +for more information about Transient Mark mode and activation and +deactivation of the mark. + + One easy way to use faces is to turn on Font Lock mode. This minor +mode, which is always local to a particular buffer, arranges to +choose faces according to the syntax of the text you are editing. It +can recognize comments and strings in most languages; in several +languages, it can also recognize and properly highlight various other +important constructs. @xref{Font Lock}, for more information about +Font Lock mode and syntactic highlighting. + + You can print out the buffer with the highlighting that appears +on your screen using the command @code{ps-print-buffer-with-faces}. +@xref{Postscript}. + +@node Font Lock +@section Font Lock mode +@cindex Font Lock mode +@cindex mode, Font Lock +@cindex syntax highlighting + + Font Lock mode is a minor mode, always local to a particular +buffer, which highlights (or ``fontifies'') using various faces +according to the syntax of the text you are editing. It can +recognize comments and strings in most languages; in several +languages, it can also recognize and properly highlight various other +important constructs---for example, names of functions being defined +or reserved keywords. + +@findex font-lock-mode +@findex turn-on-font-lock + The command @kbd{M-x font-lock-mode} turns Font Lock mode on or off +according to the argument, and toggles the mode when it has no argument. +The function @code{turn-on-font-lock} unconditionally enables Font Lock +mode. This is useful in mode-hook functions. For example, to enable +Font Lock mode whenever you edit a C file, you can do this: + +@example +(add-hook 'c-mode-hook 'turn-on-font-lock) +@end example + +@findex global-font-lock-mode + To turn on Font Lock mode automatically in all modes which support it, +use the function @code{global-font-lock-mode}, like this: + +@example +(global-font-lock-mode 1) +@end example + +@kindex M-g M-g +@findex font-lock-fontify-block + In Font Lock mode, when you edit the text, the highlighting updates +automatically in the line that you changed. Most changes don't affect +the highlighting of subsequent lines, but occasionally they do. To +rehighlight a range of lines, use the command @kbd{M-g M-g} +(@code{font-lock-fontify-block}). + +@vindex font-lock-mark-block-function + In certain major modes, @kbd{M-g M-g} refontifies the entire current +function. (The variable @code{font-lock-mark-block-function} controls +how to find the current function.) In other major modes, @kbd{M-g M-g} +refontifies 16 lines above and below point. + + With a prefix argument @var{n}, @kbd{M-g M-g} refontifies @var{n} +lines above and below point, regardless of the mode. + + To get the full benefit of Font Lock mode, you need to choose a +default font which has bold, italic, and bold-italic variants; or else +you need to have a color or gray-scale screen. + +@vindex font-lock-maximum-decoration + The variable @code{font-lock-maximum-decoration} specifies the +preferred level of fontification, for modes that provide multiple +levels. Level 1 is the least amount of fontification; some modes +support levels as high as 3. The normal default is ``as high as +possible.'' You can specify an integer, which applies to all modes, or +you can specify different numbers for particular major modes; for +example, to use level 1 for C/C++ modes, and the default level +otherwise, use this: + +@example +(setq font-lock-maximum-decoration + '((c-mode . 1) (c++-mode . 1))) +@end example + +@vindex font-lock-maximum-size + Fontification can be too slow for large buffers, so you can suppress +it. The variable @code{font-lock-maximum-size} specifies a buffer size, +beyond which buffer fontification is suppressed. + +@c @w is used below to prevent a bad page-break. +@vindex font-lock-beginning-of-syntax-function + Comment and string fontification (or ``syntactic'' fontification) +relies on analysis of the syntactic structure of the buffer text. For +the purposes of speed, some modes including C mode and Lisp mode rely on +a special convention: an open-parenthesis in the leftmost column always +defines the @w{beginning} of a defun, and is thus always outside any string +or comment. (@xref{Defuns}.) If you don't follow this convention, +then Font Lock mode can misfontify the text after an open-parenthesis in +the leftmost column that is inside a string or comment. + + The variable @code{font-lock-beginning-of-syntax-function} (always +buffer-local) specifies how Font Lock mode can find a position +guaranteed to be outside any comment or string. In modes which use the +leftmost column parenthesis convention, the default value of the variable +is @code{beginning-of-defun}---that tells Font Lock mode to use the +convention. If you set this variable to @code{nil}, Font Lock no longer +relies on the convention. This avoids incorrect results, but the price +is that, in some cases, fontification for a changed text must rescan +buffer text from the beginning of the buffer. + +@findex font-lock-add-keywords + Font Lock highlighting patterns already exist for many modes, but you +may want to fontify additional patterns. You can use the function +@code{font-lock-add-keywords}, to add your own highlighting patterns for +a particular mode. For example, to highlight @samp{FIXME:} words in C +comments, use this: + +@example +(font-lock-add-keywords + 'c-mode + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))) +@end example + +@node Support Modes +@section Font Lock Support Modes + + Font Lock support modes make Font Lock mode faster for large buffers. +There are two support modes: Fast Lock mode and Lazy Lock mode. They +use two different methods of speeding up Font Lock mode. + +@menu +* Fast Lock Mode:: Saving font information in files. +* Lazy Lock Mode:: Fontifying only text that is actually displayed. +* Fast or Lazy:: Which support mode is best for you? +@end menu + +@node Fast Lock Mode +@subsection Fast Lock Mode + +@cindex Fast Lock mode +@cindex mode, Fast Lock + To make Font Lock mode faster for buffers visiting large files, you +can use Fast Lock mode. Fast Lock mode saves the font information for +each file in a separate cache file; each time you visit the file, it +rereads the font information from the cache file instead of refontifying +the text from scratch. + +@findex fast-lock-mode + The command @kbd{M-x fast-lock-mode} turns Fast Lock mode on or off, +according to the argument (with no argument, it toggles). You can also +arrange to enable Fast Lock mode whenever you use Font Lock mode, like +this: + +@example +(setq font-lock-support-mode 'fast-lock-mode) +@end example + +@vindex fast-lock-minimum-size + It is not worth writing a cache file for small buffers. Therefore, +the variable @code{fast-lock-minimum-size} specifies a minimum file size +for caching font information. + +@vindex fast-lock-cache-directories + The variable @code{fast-lock-cache-directories} specifies where to put +the cache files. Its value is a list of directories to try; @code{"."} +means the same directory as the file being edited. The default value is +@w{@code{("." "~/.emacs-flc")}}, which means to use the same directory if +possible, and otherwise the directory @file{~/.emacs-flc}. + +@vindex fast-lock-save-others + The variable @code{fast-lock-save-others} specifies whether Fast Lock +mode should save cache files for files that you do not own. A +non-@code{nil} value means yes (and that is the default). + +@node Lazy Lock Mode +@subsection Lazy Lock Mode +@cindex Lazy Lock mode +@cindex mode, Lazy Lock + + To make Font Lock mode faster for large buffers, you can use Lazy Lock +mode to reduce the amount of text that is fontified. In Lazy Lock mode, +buffer fontification is demand-driven; it happens to portions of the +buffer that are about to be displayed. And fontification of your +changes is deferred; it happens only when Emacs has been idle for a +certain short period of time. + +@findex lazy-lock-mode + The command @kbd{M-x lazy-lock-mode} turns Lazy Lock mode on or off, +according to the argument (with no argument, it toggles). You can also +arrange to enable Lazy Lock mode whenever you use Font Lock mode, like +this: + +@example +(setq font-lock-support-mode 'lazy-lock-mode) +@end example + +@vindex lazy-lock-minimum-size + It is not worth avoiding buffer fontification for small buffers. +Therefore, the variable @code{lazy-lock-minimum-size} specifies a +minimum buffer size for demand-driven buffer fontification. Buffers +smaller than that are fontified all at once, as in plain Font Lock mode. + +@vindex lazy-lock-defer-time + When you alter the buffer, Lazy Lock mode defers fontification of the +text you changed. The variable @code{lazy-lock-defer-time} specifies +how many seconds Emacs must be idle before it starts fontifying your +changes. If the value is 0, then changes are fontified immediately, as +in plain Font Lock mode. + +@vindex lazy-lock-defer-on-scrolling + Lazy Lock mode normally fontifies newly visible portions of the buffer +before they are first displayed. However, if the value of +@code{lazy-lock-defer-on-scrolling} is non-@code{nil}, newly visible +text is fontified only when Emacs is idle for +@code{lazy-lock-defer-time} seconds. + +@vindex lazy-lock-defer-contextually + In some modes, including C mode and Emacs Lisp mode, changes in one +line's contents can alter the context for subsequent lines, and thus +change how they ought to be fontified. Ordinarily, you must type +@kbd{M-g M-g} to refontify the subsequent lines. However, if you set +the variable @code{lazy-lock-defer-contextually} to non-@code{nil}, Lazy +Lock mode does this automatically, after @code{lazy-lock-defer-time} +seconds. + +@cindex stealth fontification + When Emacs is idle for a long time, Lazy Lock fontifies additional +portions of the buffer, not yet displayed, in case you will display them +later. This is called @dfn{stealth fontification}. + +@vindex lazy-lock-stealth-time +@vindex lazy-lock-stealth-lines +@vindex lazy-lock-stealth-verbose + The variable @code{lazy-lock-stealth-time} specifies how many seconds +Emacs has to be idle before stealth fontification starts. A value of +@code{nil} means no stealth fontification. The variables +@code{lazy-lock-stealth-lines} and @code{lazy-lock-stealth-verbose} +specify the granularity and verbosity of stealth fontification. + +@node Fast or Lazy +@subsection Fast Lock or Lazy Lock? + + Here is a simple guide to help you choose one of the Font Lock support +modes. + +@itemize @bullet +@item +Fast Lock mode intervenes only during file visiting and buffer +killing (and related events); therefore buffer editing and window +scrolling are no faster or slower than in plain Font Lock mode. + +@item +Fast Lock mode is slower at reading a cache file than Lazy Lock +mode is at fontifying a window; therefore Fast Lock mode is slower at +visiting a file than Lazy Lock mode. + +@item +Lazy Lock mode intervenes during window scrolling to fontify text that +scrolls onto the screen; therefore, scrolling is slower than in plain +Font Lock mode. + +@item +Lazy Lock mode doesn't fontify during buffer editing (it defers +fontification of changes); therefore, editing is faster than in plain +Font Lock mode. + +@item +Fast Lock mode can be fooled by a file that is kept under version +control software; therefore buffer fontification may occur even when +a cache file exists for the file. + +@item +Fast Lock mode only works with a buffer visiting a file; Lazy Lock +mode works with any buffer. + +@item +Fast Lock mode generates cache files; Lazy Lock mode does not. +@end itemize + +@vindex font-lock-support-mode + The variable @code{font-lock-support-mode} specifies which of these +support modes to use; for example, to specify that Fast Lock mode is +used for C/C++ modes, and Lazy Lock mode otherwise, set the variable +like this: + +@example +(setq font-lock-support-mode + '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode) + (t . lazy-lock-mode))) +@end example + +@node Highlight Changes +@section Highlight Changes Mode + +@findex highlight-changes-mode + Use @kbd{M-x highlight-changes-mode} to enable a minor mode +that uses faces (colors, typically) to indicate which parts of +the buffer were changed most recently. + +@node Misc X +@section Miscellaneous X Window Features + + 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}). +The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under a +window system, so it has a different binding in that case. + +If you type this command on an Emacs frame's icon, it deiconifies the frame. + +@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. +@end table + +@node Non-Window Terminals +@section Non-Window Terminals +@cindex non-window terminals +@cindex single-frame terminals + + If your terminal does not have a window system that Emacs supports, +then it 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 actually the frame's name. You can also specify a +different name 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. + |