1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001, 2002, 2005
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Display, Search, Registers, Top
6 @chapter Controlling the Display
8 Since only part of a large buffer fits in the window, Emacs tries to
9 show a part that is likely to be interesting. Display-control commands
10 allow you to specify which part of the text you want to see, and how to
14 * Faces:: How to change the display style using faces.
15 * Standard Faces:: Emacs' predefined faces.
16 * Font Lock:: Minor mode for syntactic highlighting using faces.
17 * Highlight Changes:: Using colors to show where you changed the buffer.
18 * Highlight Interactively:: Tell Emacs what text to highlight.
19 * Scrolling:: Moving text up and down in a window.
20 * Horizontal Scrolling:: Moving text left and right in a window.
21 * Fringes:: Enabling or disabling window fringes.
22 * Useless Whitespace:: Showing possibly-spurious trailing whitespace.
23 * Follow Mode:: Follow mode lets two windows scroll as one.
24 * Selective Display:: Hiding lines with lots of indentation.
25 * Optional Mode Line:: Optional mode line display features.
26 * Text Display:: How text characters are normally displayed.
27 * Cursor Display:: Features for displaying the cursor.
28 * Display Custom:: Information on variables for customizing display.
32 @section Using Multiple Typefaces
35 You can specify various styles for displaying text using
36 @dfn{faces}. Each face can specify various @dfn{face attributes},
37 such as the font family, the height, weight and slant of the
38 characters, the foreground and background color, and underlining or
39 overlining. A face does not have to specify all of these attributes;
40 often it inherits most of them from another face.
42 On a window system, all the Emacs face attributes are meaningful.
43 On a character terminal, only some of them work. Some character
44 terminals support inverse video, bold, and underline attributes; some
45 support colors. Character terminals generally do not support changing
46 the height and width or the font family.
48 The easiest way to use faces is to turn on Font Lock mode.
49 @xref{Font Lock}, for more information about Font Lock mode and
50 syntactic highlighting. You can print out the buffer with the
51 highlighting that appears on your screen using the command
52 @code{ps-print-buffer-with-faces}. @xref{PostScript}.
54 Features which rely on text in multiple faces (such as Font Lock mode)
55 will also work on non-windowed terminals that can display more than one
56 face, whether by colors or underlining and emboldening. This includes
57 the console on GNU/Linux, an @code{xterm} which supports colors, the
58 MS-DOS display (@pxref{MS-DOS}), and the MS-Windows version invoked with
59 the @option{-nw} option. Emacs determines automatically whether the
60 terminal has this capability.
62 You control the appearance of a part of the text in the buffer by
63 specifying the face or faces to use for it. The style of display used
64 for any given character is determined by combining the attributes of
65 all the applicable faces specified for that character. Any attribute
66 that isn't specified by these faces is taken from the @code{default} face,
67 whose attributes reflect the default settings of the frame itself.
69 Enriched mode, the mode for editing formatted text, includes several
70 commands and menus for specifying faces for text in the buffer.
71 @xref{Format Faces}, for how to specify the font for text in the
72 buffer. @xref{Format Colors}, for how to specify the foreground and
75 @cindex face colors, setting
76 @findex set-face-foreground
77 @findex set-face-background
78 To alter the appearance of a face, use the customization buffer.
79 @xref{Face Customization}. You can also use X resources to specify
80 attributes of particular faces (@pxref{Resources}). Alternatively,
81 you can change the foreground and background colors of a specific face
82 with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
83 These commands prompt in the minibuffer for a face name and a color
84 name, with completion, and then set that face to use the specified
85 color. Changing the colors of the @code{default} face also changes
86 the foreground and background colors on all frames, both existing and
87 those to be created in the future. (You can also set foreground and
88 background colors for the current frame only; see @ref{Frame
91 Emacs can correctly display variable-width fonts, but Emacs commands
92 that calculate width and indentation do not know how to calculate
93 variable widths. This can sometimes lead to incorrect results when
94 you use variable-width fonts. In particular, indentation commands can
95 give inconsistent results, so we recommend you avoid variable-width
96 fonts for editing program source code. Filling will sometimes make
97 lines too long or too short. We plan to address these issues in
98 future Emacs versions.
101 @section Standard Faces
103 @findex list-faces-display
104 To see what faces are currently defined, and what they look like,
105 type @kbd{M-x list-faces-display}. It's possible for a given face to
106 look different in different frames; this command shows the appearance
107 in the frame in which you type it. Here are the standard faces
108 for specifying text appearance:
112 This face is used for ordinary text that doesn't specify any other face.
114 This face uses a bold variant of the default font, if it has one.
116 This face uses an italic variant of the default font, if it has one.
118 This face uses a bold italic variant of the default font, if it has one.
120 This face underlines text.
122 The basic fixed-pitch face.
124 The basic variable-pitch face.
127 Here's an incomplete list of faces used to highlight parts of the
128 text temporarily for specific purposes. (Many other modes define
129 their own faces for this purpose.)
133 This face is used for highlighting portions of text, in various modes.
134 For example, mouse-sensitive text is highlighted using this face.
135 @item mode-line-highlight
136 Like @code{highlight}, but used for portions of text on mode lines.
138 This face is used for highlighting Isearch matches.
140 This face is used for lazy highlighting of Isearch and Query Replace
141 matches other than the current one.
143 This face is used for displaying a selected region (when Transient Mark
144 mode is enabled---see below).
145 @item secondary-selection
146 This face is used for displaying a secondary X selection (@pxref{Secondary
148 @item trailing-whitespace
149 The face for highlighting trailing whitespace when
150 @code{show-trailing-whitespace} is non-@code{nil}; see @ref{Useless
153 The face for displaying the character ``nobreak space''.
155 The face for highlighting the @samp{\} or @samp{^} that indicates
156 a control character. It's also used when @samp{\} indicates a
157 nobreak space or nobreak (soft) hyphen.
159 The basic face for making the text less noticeable than the surrounding
160 ordinary text. Usually this is achieved by using shades of grey in
161 contrast with either black or white default foreground color.
164 @cindex @code{region} face
165 When Transient Mark mode is enabled, the text of the region is
166 highlighted when the mark is active. This uses the face named
167 @code{region}; you can control the style of highlighting by changing the
168 style of this face (@pxref{Face Customization}). @xref{Transient Mark},
169 for more information about Transient Mark mode and activation and
170 deactivation of the mark.
172 These faces control the appearance of parts of the Emacs frame.
173 They exist as faces to provide a consistent way to customize the
174 appearance of these parts of the frame.
178 This face is used for the mode line of the currently selected window.
179 By default, it's drawn with shadows for a ``raised'' effect on window
180 systems, and drawn as the inverse of the default face on non-windowed
182 @item mode-line-inactive
183 Like @code{mode-line}, but used for mode lines of the windows other
184 than the selected one (if @code{mode-line-in-non-selected-windows} is
185 non-@code{nil}). This face inherits from @code{mode-line}, so changes
186 in that face affect mode lines in all windows.
188 Similar to @code{mode-line} for a window's header line. Most modes
189 don't use the header line, but the Info mode does.
190 @item vertical-border
191 This face is used for the vertical divider between windows on
192 character terminals. By default this face inherits from the
193 @code{mode-line-inactive} face.
194 @item minibuffer-prompt
195 This face is used for the prompt strings displayed in the minibuffer.
198 The face for the fringes to the left and right of windows on graphic
199 displays. (The fringes are the narrow portions of the Emacs frame
200 between the text area and the window's right and left borders.)
203 This face determines the visual appearance of the scroll bar.
206 This face determines the color of the frame border.
208 This face determines the color of the cursor.
210 This face determines the color of the mouse pointer.
212 This is the basic tool-bar face. No text appears in the tool bar, but the
213 colors of this face affect the appearance of tool bar icons. @xref{Tool Bars}.
215 This face is used for tooltips. @xref{Tooltips}.
217 This face determines the colors and font of Emacs's menus. Setting the
218 font of LessTif/Motif menus is currently not supported; attempts to set
219 the font are ignored in this case. @xref{Menu Bars}.
223 @section Font Lock mode
224 @cindex Font Lock mode
225 @cindex mode, Font Lock
226 @cindex syntax highlighting and coloring
228 Font Lock mode is a minor mode, always local to a particular buffer,
229 which highlights (or ``fontifies'') the buffer contents according to
230 the syntax of the text you are editing. It can recognize comments and
231 strings in most languages; in several languages, it can also recognize
232 and properly highlight various other important constructs---for
233 example, names of functions being defined or reserved keywords.
234 Some special modes, such as Occur mode and Info mode, have completely
235 specialized ways of assigning fonts for Font Lock mode.
237 @findex font-lock-mode
238 @findex turn-on-font-lock
239 The command @kbd{M-x font-lock-mode} turns Font Lock mode on with
240 positive argument, off with negative or zero argument, and toggles the
241 mode when it has no argument. The function @code{turn-on-font-lock}
242 unconditionally enables Font Lock mode. This is useful in mode-hook
243 functions. For example, to enable Font Lock mode whenever you edit a
244 C file, you can do this:
247 (add-hook 'c-mode-hook 'turn-on-font-lock)
250 @findex global-font-lock-mode
251 @vindex global-font-lock-mode
252 To turn on Font Lock mode automatically in all modes which support
253 it, customize the variable @code{global-font-lock-mode} using the
254 Customize interface (@pxref{Easy Customization}) or use the function
255 @code{global-font-lock-mode} in your @file{.emacs} file, like this:
258 (global-font-lock-mode 1)
262 You can also specify this using the menu bar Options menu, specifying
263 first Syntax Highlighting and then Save Options.
265 Font Lock mode uses several specifically named faces to do its job,
266 including @code{font-lock-string-face}, @code{font-lock-comment-face},
267 and others. The easiest way to find them all is to use completion
268 on the face name in @code{set-face-foreground}.
270 To change the colors or the fonts used by Font Lock mode to fontify
271 different parts of text, just change these faces. There are
276 Invoke @kbd{M-x set-face-foreground} or @kbd{M-x set-face-background}
277 to change the colors of a particular face used by Font Lock.
278 @xref{Faces}. The command @kbd{M-x list-faces-display} displays all
279 the faces currently known to Emacs, including those used by Font Lock.
282 Customize the faces interactively with @kbd{M-x customize-face}, as
283 described in @ref{Face Customization}.
286 @vindex font-lock-maximum-decoration
287 The variable @code{font-lock-maximum-decoration} specifies the
288 preferred level of fontification, for modes that provide multiple
289 levels. Level 1 is the least amount of fontification; some modes
290 support levels as high as 3. The normal default is ``as high as
291 possible.'' You can specify an integer, which applies to all modes, or
292 you can specify different numbers for particular major modes; for
293 example, to use level 1 for C/C++ modes, and the default level
297 (setq font-lock-maximum-decoration
298 '((c-mode . 1) (c++-mode . 1)))
301 @vindex font-lock-maximum-size
302 Fontification can be too slow for large buffers, so you can suppress
303 it. The variable @code{font-lock-maximum-size} specifies a buffer size,
304 beyond which buffer fontification is suppressed.
306 @c @w is used below to prevent a bad page-break.
307 @vindex font-lock-beginning-of-syntax-function
308 @cindex incorrect fontification
309 @cindex parenthesis in column zero and fontification
310 @cindex brace in column zero and fontification
311 Comment and string fontification (or ``syntactic'' fontification)
312 relies on analysis of the syntactic structure of the buffer text. For
313 the sake of speed, some modes, including C mode and Lisp mode,
314 rely on a special convention: an open-parenthesis or open-brace in the
315 leftmost column always defines the @w{beginning} of a defun, and is
316 thus always outside any string or comment. (@xref{Left Margin
317 Paren}.) If you don't follow this convention, Font Lock mode can
318 misfontify the text that follows an open-parenthesis or open-brace in
319 the leftmost column that is inside a string or comment.
321 @cindex slow display during scrolling
322 The variable @code{font-lock-beginning-of-syntax-function} (always
323 buffer-local) specifies how Font Lock mode can find a position
324 guaranteed to be outside any comment or string. In modes which use the
325 leftmost column parenthesis convention, the default value of the variable
326 is @code{beginning-of-defun}---that tells Font Lock mode to use the
327 convention. If you set this variable to @code{nil}, Font Lock no longer
328 relies on the convention. This avoids incorrect results, but the price
329 is that, in some cases, fontification for a changed text must rescan
330 buffer text from the beginning of the buffer. This can considerably
331 slow down redisplay while scrolling, particularly if you are close to
332 the end of a large buffer.
334 @findex font-lock-add-keywords
335 Font Lock highlighting patterns already exist for many modes, but you
336 may want to fontify additional patterns. You can use the function
337 @code{font-lock-add-keywords}, to add your own highlighting patterns for
338 a particular mode. For example, to highlight @samp{FIXME:} words in C
342 (font-lock-add-keywords
344 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
347 @findex font-lock-remove-keywords
348 To remove keywords from the font-lock highlighting patterns, use the
349 function @code{font-lock-remove-keywords}. @xref{Search-based
350 Fontification,,, elisp, The Emacs Lisp Reference Manual}, for
351 documentation of the format of this list.
353 @cindex just-in-time (JIT) font-lock
354 @cindex background syntax highlighting
355 Fontifying large buffers can take a long time. To avoid large
356 delays when a file is visited, Emacs fontifies only the visible
357 portion of a buffer. As you scroll through the buffer, each portion
358 that becomes visible is fontified as soon as it is displayed. The
359 parts of the buffer that are not displayed are fontified
360 ``stealthily,'' in the background, i.e.@: when Emacs is idle. You can
361 control this background fontification, also called @dfn{Just-In-Time}
362 (or @dfn{JIT}) Lock, by customizing variables in the customization
363 group @samp{jit-lock}. @xref{Specific Customization}.
365 @node Highlight Changes
366 @section Highlight Changes Mode
368 @findex highlight-changes-mode
369 Use @kbd{M-x highlight-changes-mode} to enable a minor mode
370 that uses faces (colors, typically) to indicate which parts of
371 the buffer were changed most recently.
373 @node Highlight Interactively
374 @section Interactive Highlighting by Matching
375 @cindex highlighting by matching
376 @cindex interactive highlighting
378 It is sometimes useful to highlight the strings that match a certain
379 regular expression. For example, you might wish to see all the
380 references to a certain variable in a program source file, or highlight
381 certain parts in a voluminous output of some program, or make certain
382 cliches stand out in an article.
385 Use the @kbd{M-x hi-lock-mode} command to turn on a minor mode that
386 allows you to specify regular expressions of the text to be
387 highlighted. Hi-lock mode works like Font Lock (@pxref{Font Lock}),
388 except that it lets you specify explicitly what parts of text to
389 highlight. You control Hi-lock mode with these commands:
392 @item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
394 @findex highlight-regexp
395 Highlight text that matches
396 @var{regexp} using face @var{face} (@code{highlight-regexp}).
397 By using this command more than once, you can highlight various
398 parts of the text in different ways.
400 @item C-x w r @var{regexp} @key{RET}
402 @findex unhighlight-regexp
403 Unhighlight @var{regexp} (@code{unhighlight-regexp}). You must enter
404 one of the regular expressions currently specified for highlighting.
405 (You can use completion, or choose from a menu, to enter one of them
408 @item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
410 @findex highlight-lines-matching-regexp
411 @cindex lines, highlighting
412 @cindex highlighting lines of text
413 Highlight entire lines containing a match for @var{regexp}, using face
414 @var{face} (@code{highlight-lines-matching-regexp}).
418 @findex hi-lock-write-interactive-patterns
419 Insert all the current highlighting regexp/face pairs into the buffer
420 at point, with comment delimiters to prevent them from changing your
421 program. This key binding runs the
422 @code{hi-lock-write-interactive-patterns} command.
424 These patterns will be read the next time you visit the file while
425 Hi-lock mode is enabled, or whenever you use the @kbd{M-x
426 hi-lock-find-patterns} command.
430 @findex hi-lock-find-patterns
431 @vindex hi-lock-exclude-modes
432 Re-read regexp/face pairs in the current buffer
433 (@code{hi-lock-write-interactive-patterns}). The list of pairs is
434 found no matter where in the buffer it may be.
436 This command does nothing if the major mode is a member of the list
437 @code{hi-lock-exclude-modes}.
443 If a buffer contains text that is too large to fit entirely within a
444 window that is displaying the buffer, Emacs shows a contiguous portion of
445 the text. The portion shown always contains point.
448 @dfn{Scrolling} means moving text up or down in the window so that
449 different parts of the text are visible. Scrolling forward means that text
450 moves up, and new text appears at the bottom. Scrolling backward moves
451 text down and new text appears at the top.
453 Scrolling happens automatically if you move point past the bottom or top
454 of the window. You can also explicitly request scrolling with the commands
459 Clear screen and redisplay, scrolling the selected window to center
460 point vertically within it (@code{recenter}).
462 Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
464 @itemx @key{PAGEDOWN}
465 Likewise, scroll forward.
467 Scroll backward (@code{scroll-down}).
470 Likewise, scroll backward.
472 Scroll so point is on line @var{arg} (@code{recenter}).
474 Scroll heuristically to bring useful information onto the screen
475 (@code{reposition-window}).
480 The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
481 no argument. It scrolls the selected window so that point is halfway
482 down from the top of the window. On a text terminal, it also clears
483 the screen and redisplays all windows. That is useful in case the
484 screen is garbled (@pxref{Screen Garbled}).
494 @vindex next-screen-context-lines
495 To read the buffer a windowful at a time, use @kbd{C-v}
496 (@code{scroll-up}) with no argument. This scrolls forward by nearly
497 the whole window height. The effect is to take the two lines at the
498 bottom of the window and put them at the top, followed by nearly a
499 whole windowful of lines that were not previously visible. If point
500 was in the text that scrolled off the top, it ends up at the new top
503 @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in
504 a similar way, also with overlap. The number of lines of overlap
505 across a @kbd{C-v} or @kbd{M-v} is controlled by the variable
506 @code{next-screen-context-lines}; by default, it is 2. The function
507 keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP},
508 are equivalent to @kbd{C-v} and @kbd{M-v}.
510 The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll
511 the text in the selected window up or down a few lines. @kbd{C-v}
512 with an argument moves the text and point up, together, that many
513 lines; it brings the same number of new lines into view at the bottom
514 of the window. @kbd{M-v} with numeric argument scrolls the text
515 downward, bringing that many new lines into view at the top of the
516 window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice
519 The names of scroll commands are based on the direction that the
520 text moves in the window. Thus, the command to scroll forward is
521 called @code{scroll-up} because it moves the text upward on the
522 screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names
523 and customary meanings from a different convention that developed
524 elsewhere; hence the strange result that @key{PAGEDOWN} runs
527 @vindex scroll-preserve-screen-position
528 Some users like the full-screen scroll commands to keep point at the
529 same screen line. To enable this behavior, set the variable
530 @code{scroll-preserve-screen-position} to a non-@code{nil} value. In
531 this mode, when scrolling shifts point off the screen, or into the
532 scrolling margins, Emacs moves point to keep the same vertical
533 position within the window. This mode is convenient for browsing
534 through a file by scrolling by screenfuls; if you come back to the
535 screen where you started, point goes back to the line where it
536 started. However, this mode is inconvenient when you move to the next
537 screen in order to move point to the text there.
539 Another way to do scrolling is with @kbd{C-l} with a numeric argument.
540 @kbd{C-l} does not clear the screen when given an argument; it only scrolls
541 the selected window. With a positive argument @var{n}, it repositions text
542 to put point @var{n} lines down from the top. An argument of zero puts
543 point on the very top line. Point does not move with respect to the text;
544 rather, the text and point move rigidly on the screen. @kbd{C-l} with a
545 negative argument puts point that many lines from the bottom of the window.
546 For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
547 - 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put
548 point at the center (vertically) of the selected window.
551 @findex reposition-window
552 The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
553 window heuristically in a way designed to get useful information onto
554 the screen. For example, in a Lisp file, this command tries to get the
555 entire current defun onto the screen if possible.
557 @vindex scroll-conservatively
558 Scrolling happens automatically when point moves out of the visible
559 portion of the text. Normally, automatic scrolling centers point
560 vertically within the window. However, if you set
561 @code{scroll-conservatively} to a small number @var{n}, then if you
562 move point just a little off the screen---less than @var{n}
563 lines---then Emacs scrolls the text just far enough to bring point
564 back on screen. By default, @code{scroll-conservatively} is 0.
566 @cindex aggressive scrolling
567 @vindex scroll-up-aggressively
568 @vindex scroll-down-aggressively
569 When the window does scroll by a longer distance, you can control
570 how aggressively it scrolls, by setting the variables
571 @code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
572 The value of @code{scroll-up-aggressively} should be either
573 @code{nil}, or a fraction @var{f} between 0 and 1. A fraction
574 specifies where on the screen to put point when scrolling upward.
575 More precisely, when a window scrolls up because point is above the
576 window start, the new start position is chosen to put point @var{f}
577 part of the window height from the top. The larger @var{f}, the more
578 aggressive the scrolling.
580 @code{nil}, which is the default, scrolls to put point at the center.
581 So it is equivalent to .5.
583 Likewise, @code{scroll-down-aggressively} is used for scrolling
584 down. The value, @var{f}, specifies how far point should be placed
585 from the bottom of the window; thus, as with
586 @code{scroll-up-aggressively}, a larger value is more aggressive.
588 @vindex scroll-margin
589 The variable @code{scroll-margin} restricts how close point can come
590 to the top or bottom of a window. Its value is a number of screen
591 lines; if point comes within that many lines of the top or bottom of the
592 window, Emacs recenters the window. By default, @code{scroll-margin} is
595 @node Horizontal Scrolling
596 @section Horizontal Scrolling
597 @cindex horizontal scrolling
599 @dfn{Horizontal scrolling} means shifting all the lines sideways
600 within a window---so that some of the text near the left margin is not
601 displayed at all. When the text in a window is scrolled horizontally,
602 text lines are truncated rather than continued (@pxref{Display
603 Custom}). Whenever a window shows truncated lines, Emacs
604 automatically updates its horizontal scrolling whenever point moves
605 off the left or right edge of the screen. You can also use these
606 commands to do explicit horizontal scrolling.
610 Scroll text in current window to the left (@code{scroll-left}).
612 Scroll to the right (@code{scroll-right}).
619 The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
620 window to the left by @var{n} columns with argument @var{n}. This moves
621 part of the beginning of each line off the left edge of the window.
622 With no argument, it scrolls by almost the full width of the window (two
623 columns less, to be precise).
625 @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The
626 window cannot be scrolled any farther to the right once it is displayed
627 normally (with each line starting at the window's left margin);
628 attempting to do so has no effect. This means that you don't have to
629 calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
630 argument will restore the normal display.
632 If you use those commands to scroll a window horizontally, that sets
633 a lower bound for automatic horizontal scrolling. Automatic scrolling
634 will continue to scroll the window, but never farther to the right
635 than the amount you previously set by @code{scroll-left}.
637 @vindex hscroll-margin
638 The value of the variable @code{hscroll-margin} controls how close
639 to the window's edges point is allowed to get before the window will
640 be automatically scrolled. It is measured in columns. If the value
641 is 5, then moving point within 5 columns of the edge causes horizontal
642 scrolling away from that edge.
645 The variable @code{hscroll-step} determines how many columns to
646 scroll the window when point gets too close to the edge. If it's
647 zero, horizontal scrolling centers point horizontally within the
648 window. If it's a positive integer, it specifies the number of
649 columns to scroll by. If it's a floating-point number, it specifies
650 the fraction of the window's width to scroll by. The default is zero.
652 @vindex auto-hscroll-mode
653 To disable automatic horizontal scrolling, set the variable
654 @code{auto-hscroll-mode} to @code{nil}.
657 @section Window Fringes
660 On a graphical display, each Emacs window normally has narrow
661 @dfn{fringes} on the left and right edges. The fringes display
662 indications about the text in the window.
664 The most common use of the fringes is to indicate a continuation
665 line, when one line of text is split into multiple lines on the
666 screen. The left fringe shows a curving arrow for each screen line
667 except the first, indicating that ``this is not the real beginning.''
668 The right fringe shows a curving arrow for each screen line except the
669 last, indicating that ``this is not the real end.''
671 The fringes indicate line truncation with short horizontal arrows
672 meaning ``there's more text on this line which is scrolled
673 horizontally out of view;'' clicking the mouse on one of the arrows
674 scrolls the display horizontally in the direction of the arrow. The
675 fringes can also indicate other things, such as empty lines, or where a
676 program you are debugging is executing (@pxref{Debuggers}).
678 @findex set-fringe-style
680 You can enable and disable the fringes for all frames using
681 @kbd{M-x fringe-mode}. To enable and disable the fringes
682 for the selected frame, use @kbd{M-x set-fringe-style}.
684 @node Useless Whitespace
685 @section Useless Whitespace
687 @cindex trailing whitespace
688 @cindex whitespace, trailing
689 @vindex show-trailing-whitespace
690 It is easy to leave unnecessary spaces at the end of a line, or
691 empty lines at the end of a file, without realizing it. In most
692 cases, this @dfn{trailing whitespace} has no effect, but there are
693 special circumstances where it matters.
695 You can make trailing whitespace at the end of a line visible on the
696 screen by setting the buffer-local variable
697 @code{show-trailing-whitespace} to @code{t}. Then Emacs displays
698 trailing whitespace in the face @code{trailing-whitespace}.
700 This feature does not apply when point is at the end of the line
701 containing the whitespace. Strictly speaking, that is ``trailing
702 whitespace'' nonetheless, but displaying it specially in that case
703 looks ugly while you are typing in new text. In this special case,
704 the location of point is enough to show you that the spaces are
707 @findex delete-trailing-whitespace
708 To delete all trailing whitespace within the current buffer's
709 accessible portion (@pxref{Narrowing}), type @kbd{M-x
710 delete-trailing-whitespace @key{RET}}. (This command does not remove
711 the form-feed characters.)
713 @vindex indicate-empty-lines
714 @vindex default-indicate-empty-lines
716 @cindex fringes, and unused line indication
717 Emacs can indicate unused lines at the end of the window with a
718 small image in the left fringe (@pxref{Fringes}). The image appears
719 for window lines that do not correspond to any buffer text. Blank
720 lines at the end of the buffer then stand out because they do not have
721 this image in the fringe.
723 To enable this feature, set the buffer-local variable
724 @code{indicate-empty-lines} to a non-@code{nil} value. The default
725 value of this variable is controlled by the variable
726 @code{default-indicate-empty-lines}; by setting that variable, you
727 can enable or disable this feature for all new buffers. (This feature
728 currently doesn't work on character terminals.)
735 @cindex windows, synchronizing
736 @cindex synchronizing windows
738 @dfn{Follow mode} is a minor mode that makes two windows, both
739 showing the same buffer, scroll as a single tall ``virtual window.''
740 To use Follow mode, go to a frame with just one window, split it into
741 two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
742 follow-mode}. From then on, you can edit the buffer in either of the
743 two windows, or scroll either one; the other window follows it.
745 In Follow mode, if you move point outside the portion visible in one
746 window and into the portion visible in the other window, that selects
747 the other window---again, treating the two as if they were parts of
750 To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
752 @node Selective Display
753 @section Selective Display
754 @cindex selective display
755 @findex set-selective-display
758 Emacs has the ability to hide lines indented more than a certain number
759 of columns (you specify how many columns). You can use this to get an
760 overview of a part of a program.
762 To hide lines in the current buffer, type @kbd{C-x $}
763 (@code{set-selective-display}) with a numeric argument @var{n}. Then
764 lines with at least @var{n} columns of indentation disappear from the
765 screen. The only indication of their presence is that three dots
766 (@samp{@dots{}}) appear at the end of each visible line that is
767 followed by one or more hidden ones.
769 The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
770 if they were not there.
772 The hidden lines are still present in the buffer, and most editing
773 commands see them as usual, so you may find point in the middle of the
774 hidden text. When this happens, the cursor appears at the end of the
775 previous line, after the three dots. If point is at the end of the
776 visible line, before the newline that ends it, the cursor appears before
779 To make all lines visible again, type @kbd{C-x $} with no argument.
781 @vindex selective-display-ellipses
782 If you set the variable @code{selective-display-ellipses} to
783 @code{nil}, the three dots do not appear at the end of a line that
784 precedes hidden lines. Then there is no visible indication of the
785 hidden lines. This variable becomes local automatically when set.
787 See also @ref{Outline Mode} for another way to hide part of
788 the text in a buffer.
790 @node Optional Mode Line
791 @section Optional Mode Line Features
793 @cindex buffer size display
794 @cindex display of buffer size
795 @findex size-indication-mode
796 The buffer percentage @var{pos} indicates the percentage of the
797 buffer above the top of the window. You can additionally display the
798 size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
799 Size Indication mode. The size will be displayed immediately
800 following the buffer percentage like this:
803 @var{POS} of @var{SIZE}
807 Here @var{SIZE} is the human readable representation of the number of
808 characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
809 for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
811 @cindex narrowing, and buffer size display
812 If you have narrowed the buffer (@pxref{Narrowing}), the size of the
813 accessible part of the buffer is shown.
815 @cindex line number display
816 @cindex display of line number
817 @findex line-number-mode
818 The current line number of point appears in the mode line when Line
819 Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
820 turn this mode on and off; normally it is on. The line number appears
821 after the buffer percentage @var{pos}, with the letter @samp{L} to
822 indicate what it is. @xref{Minor Modes}, for more information about
823 minor modes and about how to use this command.
825 @cindex narrowing, and line number display
826 If you have narrowed the buffer (@pxref{Narrowing}), the displayed
827 line number is relative to the accessible portion of the buffer.
829 @vindex line-number-display-limit
830 If the buffer is very large (larger than the value of
831 @code{line-number-display-limit}), then the line number doesn't appear.
832 Emacs doesn't compute the line number when the buffer is large, because
833 that would be too slow. Set it to @code{nil} to remove the limit.
835 @vindex line-number-display-limit-width
836 Line-number computation can also be slow if the lines in the buffer
837 are too long. For this reason, Emacs normally doesn't display line
838 numbers if the average width, in characters, of lines near point is
839 larger than the value of the variable
840 @code{line-number-display-limit-width}. The default value is 200
843 @cindex Column Number mode
844 @cindex mode, Column Number
845 @findex column-number-mode
846 You can also display the current column number by turning on Column
847 Number mode. It displays the current column number preceded by the
848 letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode.
851 @cindex time (on mode line)
852 Emacs can optionally display the time and system load in all mode
853 lines. To enable this feature, type @kbd{M-x display-time} or customize
854 the option @code{display-time-mode}. The information added to the mode
855 line usually appears after the buffer name, before the mode names and
856 their parentheses. It looks like this:
859 @var{hh}:@var{mm}pm @var{l.ll}
863 @vindex display-time-24hr-format
864 Here @var{hh} and @var{mm} are the hour and minute, followed always by
865 @samp{am} or @samp{pm}. @var{l.ll} is the average number of running
866 processes in the whole system recently. (Some fields may be missing if
867 your operating system cannot support them.) If you prefer time display
868 in 24-hour format, set the variable @code{display-time-24hr-format}
871 @cindex mail (on mode line)
872 @vindex display-time-use-mail-icon
873 @vindex display-time-mail-face
874 @vindex display-time-mail-file
875 @vindex display-time-mail-directory
876 The word @samp{Mail} appears after the load level if there is mail
877 for you that you have not read yet. On a graphical display you can use
878 an icon instead of @samp{Mail} by customizing
879 @code{display-time-use-mail-icon}; this may save some space on the mode
880 line. You can customize @code{display-time-mail-face} to make the mail
881 indicator prominent. Use @code{display-time-mail-file} to specify
882 the mail file to check, or set @code{display-time-mail-directory}
883 to specify the directory to check for incoming mail (any nonempty regular
884 file in the directory is considered as ``newly arrived mail'').
886 @cindex mode line, 3D appearance
887 @cindex attributes of mode line, changing
888 @cindex non-integral number of lines in a window
889 By default, the mode line is drawn on graphics displays with
890 3D-style highlighting, like that of a button when it is not being
891 pressed. If you don't like this effect, you can disable the 3D
892 highlighting of the mode line, by customizing the attributes of the
893 @code{mode-line} face in your @file{.emacs} init file, like this:
896 (set-face-attribute 'mode-line nil :box nil)
900 Alternatively, you can turn off the box attribute in your
901 @file{.Xdefaults} file:
904 Emacs.mode-line.AttributeBox: off
907 @cindex non-selected windows, mode line appearance
908 By default, the mode line of nonselected windows is displayed in a
909 different face, called @code{mode-line-inactive}. Only the selected
910 window is displayed in the @code{mode-line} face. This helps show
911 which window is selected. When the minibuffer is selected, since
912 it has no mode line, the window from which you activated the minibuffer
913 has its mode line displayed using @code{mode-line}; as a result,
914 ordinary entry to the minibuffer does not change any mode lines.
916 @vindex mode-line-in-non-selected-windows
917 You can disable use of @code{mode-line-inactive} by setting variable
918 @code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
919 lines are displayed in the @code{mode-line} face.
922 @section How Text Is Displayed
923 @cindex characters (in text)
925 @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
926 buffers are displayed with their graphics, as are non-ASCII multibyte
927 printing characters (octal codes above 0400).
929 Some @acronym{ASCII} control characters are displayed in special ways. The
930 newline character (octal code 012) is displayed by starting a new line.
931 The tab character (octal code 011) is displayed by moving to the next
932 tab stop column (normally every 8 columns).
934 Other @acronym{ASCII} control characters are normally displayed as a caret
935 (@samp{^}) followed by the non-control version of the character; thus,
936 control-A is displayed as @samp{^A}.
938 Non-@acronym{ASCII} characters 0200 through 0237 (octal) are displayed with
939 octal escape sequences; thus, character code 0230 (octal) is displayed
940 as @samp{\230}. The display of character codes 0240 through 0377
941 (octal) may be either as escape sequences or as graphics. They do not
942 normally occur in multibyte buffers, but if they do, they are displayed
943 as Latin-1 graphics. In unibyte mode, if you enable European display
944 they are displayed using their graphics (assuming your terminal supports
945 them), otherwise as escape sequences. @xref{Single-Byte Character
948 @vindex nobreak-char-display
949 @cindex no-break space, display
950 @cindex no-break hyphen, display
951 @cindex soft hyphen, display
952 Some character sets define ``no-break'' versions of the space and
953 hyphen characters, which are used where a line should not be broken.
954 Emacs normally displays these characters with special faces
955 (respectively, @code{nobreak-space} and @code{escape-glyph}) to
956 distinguish them from ordinary spaces and hyphens. You can turn off
957 this feature by setting the variable @code{nobreak-char-display} to
958 @code{nil}. If you set the variable to any other value, that means to
959 prefix these characters with an escape character.
962 @section Displaying the Cursor
964 @findex blink-cursor-mode
965 @vindex blink-cursor-alist
966 @cindex cursor, locating visually
967 @cindex cursor, blinking
968 You can customize the cursor's color, and whether it blinks, using
969 the @code{cursor} Custom group (@pxref{Easy Customization}). On
970 graphical terminals, the command @kbd{M-x blink-cursor-mode} enables
971 or disables the blinking of the cursor. (On text terminals, the
972 terminal itself blinks the cursor, and Emacs has no control over it.)
973 You can control how the cursor appears when it blinks off by setting
974 the variable @code{blink-cursor-alist}.
976 @cindex cursor in non-selected windows
977 @vindex cursor-in-non-selected-windows
978 Normally, the cursor appears in non-selected windows in the ``off''
979 state, with the same appearance as when the blinking cursor blinks
980 ``off''. For a box cursor, this is a hollow box; for a bar cursor,
981 this is a thinner bar. To turn off cursors in non-selected windows,
982 customize the variable @code{cursor-in-non-selected-windows} and assign
983 it a @code{nil} value.
985 @vindex x-stretch-cursor
986 @cindex wide block cursor
987 On graphical terminals, Emacs can optionally draw the block cursor
988 as wide as the character under the cursor---for example, if the cursor
989 is on a tab character, it would cover the full width occupied by that
990 tab character. To enable this feature, set the variable
991 @code{x-stretch-cursor} to a non-@code{nil} value.
994 @findex global-hl-line-mode
995 @cindex highlight current line
996 If you find it hard to see the cursor, you might like HL Line mode,
997 a minor mode that highlights the line containing point. Use @kbd{M-x
998 hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x
999 global-hl-line-mode} enables or disables the same mode globally.
1001 @node Display Custom
1002 @section Customization of Display
1004 This section contains information for customization only. Beginning
1005 users should skip it.
1007 @vindex mode-line-inverse-video
1008 The variable @code{mode-line-inverse-video} is an obsolete way of
1009 controlling whether the mode line is displayed in inverse video; the
1010 preferred way of doing this is to change the @code{mode-line} face.
1011 @xref{Mode Line}. However, if @code{mode-line-inverse-video} has a
1012 value of @code{nil}, then the @code{mode-line} face will be ignored,
1013 and mode-lines will be drawn using the default text face.
1016 @vindex inverse-video
1017 If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
1018 to invert all the lines of the display from what they normally are.
1020 @vindex visible-bell
1021 If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
1022 to make the whole screen blink when it would normally make an audible bell
1023 sound. This variable has no effect if your terminal does not have a way
1024 to make the screen blink.
1026 @vindex no-redraw-on-reenter
1027 On a text terminal, when you reenter Emacs after suspending, Emacs
1028 normally clears the screen and redraws the entire display. On some
1029 terminals with more than one page of memory, it is possible to arrange
1030 the termcap entry so that the @samp{ti} and @samp{te} strings (output
1031 to the terminal when Emacs is entered and exited, respectively) switch
1032 between pages of memory so as to use one page for Emacs and another
1033 page for other output. Then you might want to set the variable
1034 @code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
1035 assume, when resumed, that the screen page it is using still contains
1036 what Emacs last wrote there.
1038 @vindex echo-keystrokes
1039 The variable @code{echo-keystrokes} controls the echoing of multi-character
1040 keys; its value is the number of seconds of pause required to cause echoing
1041 to start, or zero meaning don't echo at all. @xref{Echo Area}.
1044 If the variable @code{ctl-arrow} is @code{nil}, all control characters in
1045 the buffer are displayed with octal escape sequences, except for newline
1046 and tab. Altering the value of @code{ctl-arrow} makes it local to the
1047 current buffer; until that time, the default value is in effect. The
1048 default is initially @code{t}. @xref{Display Tables,, Display Tables,
1049 elisp, The Emacs Lisp Reference Manual}.
1052 @vindex default-tab-width
1053 Normally, a tab character in the buffer is displayed as whitespace which
1054 extends to the next display tab stop position, and display tab stops come
1055 at intervals equal to eight spaces. The number of spaces per tab is
1056 controlled by the variable @code{tab-width}, which is made local by
1057 changing it, just like @code{ctl-arrow}. Note that how the tab character
1058 in the buffer is displayed has nothing to do with the definition of
1059 @key{TAB} as a command. The variable @code{tab-width} must have an
1060 integer value between 1 and 1000, inclusive. The variable
1061 @code{default-tab-width} controls the default value of this variable
1062 for buffers where you have not set it locally.
1065 @cindex line truncation, and fringes
1066 As an alternative to continuation, Emacs can display long lines by
1067 @dfn{truncation}. This means that all the characters that do not fit
1068 in the width of the screen or window do not appear at all. On
1069 graphical terminals, a small straight arrow in the fringe indicates
1070 truncation at either end of the line. On text terminals, @samp{$}
1071 appears in the first column when there is text truncated to the left,
1072 and in the last column when there is text truncated to the right.
1074 @vindex truncate-lines
1075 @findex toggle-truncate-lines
1076 Horizontal scrolling automatically causes line truncation
1077 (@pxref{Horizontal Scrolling}). You can explicitly enable line
1078 truncation for a particular buffer with the command @kbd{M-x
1079 toggle-truncate-lines}. This works by locally changing the variable
1080 @code{truncate-lines}. If that variable is non-@code{nil}, long lines
1081 are truncated; if it is @code{nil}, they are continued onto multiple
1082 screen lines. Setting the variable @code{truncate-lines} in any way
1083 makes it local to the current buffer; until that time, the default
1084 value is in effect. The default value is normally @code{nil}.
1086 @c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
1087 If the variable @code{truncate-partial-width-windows} is
1088 non-@code{nil}, it forces truncation rather than continuation in any
1089 window less than the full width of the screen or frame, regardless of
1090 the value of @code{truncate-lines}. For information about side-by-side
1091 windows, see @ref{Split Window}. See also @ref{Display,, Display,
1092 elisp, The Emacs Lisp Reference Manual}.
1094 @vindex overflow-newline-into-fringe
1095 If the variable @code{overflow-newline-into-fringe} is
1096 non-@code{nil} on a window system, it specifies that lines which are
1097 exactly as wide as the window (not counting the final newline
1098 character) shall not be broken into two lines on the display (with
1099 just the newline on the second line). Instead, the newline
1100 overflows into the right fringe, and the cursor will be displayed in
1101 the fringe when positioned on that newline.
1103 @vindex indicate-buffer-boundaries
1104 On a window system, Emacs may indicate the buffer boundaries in the
1105 fringes. The buffer boundaries, i.e. first and last line in the
1106 buffer, can be marked with angle bitmaps in the left or right fringe.
1107 This can be combined with up and down arrow bitmaps shown at the top
1108 and bottom of the left or right fringe if the window can be scrolled
1109 in either direction.
1111 The buffer-local variable @code{indicate-buffer-boundaries} controls
1112 how the buffer boundaries and window scrolling is indicated in the
1115 If the value is @code{left} or @code{right}, both angle and arrow
1116 bitmaps are displayed in the left or right fringe, respectively.
1118 If value is an alist, each element @code{(@var{indicator} .
1119 @var{position})} specifies the position of one of the indicators.
1120 The @var{indicator} must be one of @code{top}, @code{bottom},
1121 @code{up}, @code{down}, or @code{t} which specifies the default
1122 position for the indicators not present in the alist.
1123 The @var{position} is one of @code{left}, @code{right}, or @code{nil}
1124 which specifies not to show this indicator.
1126 For example, @code{((top . left) (t . right))} places the top angle
1127 bitmap in left fringe, the bottom angle bitmap in right fringe, and
1128 both arrow bitmaps in right fringe. To show just the angle bitmaps in
1129 the left fringe, but no arrow bitmaps, use @code{((top . left)
1132 @vindex default-indicate-buffer-boundaries
1133 The value of the variable @code{default-indicate-buffer-boundaries}
1134 is the default value for @code{indicate-buffer-boundaries} in buffers
1135 that do not override it.
1138 The variable @anchor{baud-rate}@code{baud-rate} holds the output speed of the
1139 terminal, as far as Emacs knows. Setting this variable does not
1140 change the speed of actual data transmission, but the value is used
1141 for calculations. On terminals, it affects padding, and decisions
1142 about whether to scroll part of the screen or redraw it instead.
1143 It also affects the behavior of incremental search.
1145 On window-systems, @code{baud-rate} is only used to determine how
1146 frequently to look for pending input during display updating. A
1147 higher value of @code{baud-rate} means that check for pending input
1148 will be done less frequently.
1150 You can customize the way any particular character code is displayed
1151 by means of a display table. @xref{Display Tables,, Display Tables,
1152 elisp, The Emacs Lisp Reference Manual}.
1154 @cindex hourglass pointer display
1155 @vindex hourglass-delay
1156 On a window system, Emacs can optionally display the mouse pointer
1157 in a special shape to say that Emacs is busy. To turn this feature on
1158 or off, customize the group @code{cursor}. You can also control the
1159 amount of time Emacs must remain busy before the busy indicator is
1160 displayed, by setting the variable @code{hourglass-delay}.
1162 @findex tty-suppress-bold-inverse-default-colors
1163 On some text-only terminals, bold face and inverse video together
1164 result in text that is hard to read. Call the function
1165 @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
1166 argument to suppress the effect of bold-face in this case.
1169 arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4