1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001
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 * Font Lock:: Minor mode for syntactic highlighting using faces.
16 * Highlight Changes:: Using colors to show where you changed the buffer.
17 * Highlight Interactively:: Tell Emacs what text to highlight.
18 * Trailing Whitespace:: Showing possibly-spurious trailing whitespace.
19 * Scrolling:: Moving text up and down in a window.
20 * Horizontal Scrolling:: Moving text left and right in a window.
21 * Follow Mode:: Follow mode lets two windows scroll as one.
22 * Selective Display:: Hiding lines with lots of indentation.
23 * Optional Mode Line:: Optional mode line display features.
24 * Text Display:: How text characters are normally displayed.
25 * Display Custom:: Information on variables for customizing display.
26 * Cursor Display:: Features for displaying the cursor.
30 @section Using Multiple Typefaces
33 When using Emacs with a window system, you can set up multiple
34 styles of displaying characters. Each style is called a @dfn{face}.
35 Each face can specify various attributes, such as the height, weight
36 and slant of the characters, the foreground and background color, and
37 underlining. But it does not have to specify all of them.
39 Features which rely on text in multiple faces (such as Font Lock mode)
40 will also work on non-windowed terminals that can display more than one
41 face, whether by colors or underlining and emboldening. This includes
42 the console on GNU/Linux, an @code{xterm} which supports colors, the
43 MS-DOS display (@pxref{MS-DOS}), and the MS-Windows version invoked with
44 the @option{-nw} option. Emacs determines automatically whether the
45 terminal has this capability.
47 You control the appearance of a part of the text in the buffer by
48 specifying the face or faces to use for it. The style of display used
49 for any given character is determined by combining the attributes of
50 all the applicable faces specified for that character. Any attribute
51 that isn't specified by these faces is taken from the default face,
52 whose attributes reflect the default settings of the frame itself.
54 Enriched mode, the mode for editing formatted text, includes several
55 commands and menus for specifying faces for text in the buffer.
56 @xref{Format Faces}, for how to specify the font for text in the
57 buffer. @xref{Format Colors}, for how to specify the foreground and
60 @cindex face colors, setting
61 @findex set-face-foreground
62 @findex set-face-background
63 To alter the appearance of a face, use the customization buffer.
64 @xref{Face Customization}. You can also use X resources to specify
65 attributes of particular faces (@pxref{Resources X}). Alternatively,
66 you can change the foreground and background colors of a specific face
67 with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
68 These commands prompt in the minibuffer for a face name and a color
69 name, with completion, and then set that face to use the specified
70 color. Changing the colors of the @code{default} face also changes
71 the foreground and background colors on all frames, both existing and
72 those to be created in the future. (You can also set foreground and
73 background colors for the current frame only; see @ref{Frame
76 Emacs 21 can correctly display variable-width fonts, but Emacs
77 commands that calculate width and indentation do not know how to
78 calculate variable widths. This can sometimes lead to incorrect
79 results when you use variable-width fonts. In particular, indentation
80 commands can give inconsistent results, so we recommend you avoid
81 variable-width fonts for editing program source code. Filling will
82 sometimes make lines too long or too short. We plan to address these
83 issues in future Emacs versions.
85 @findex list-faces-display
86 To see what faces are currently defined, and what they look like, type
87 @kbd{M-x list-faces-display}. It's possible for a given face to look
88 different in different frames; this command shows the appearance in the
89 frame in which you type it. Here's a list of the standard defined
94 This face is used for ordinary text that doesn't specify any other face.
96 This face is used for mode lines. By default, it's drawn with shadows
97 for a ``raised'' effect on window systems, and drawn as the inverse of
98 the default face on non-windowed terminals. @xref{Display Custom}.
100 Similar to @code{mode-line} for a window's header line. Most modes
101 don't use the header line, but the Info mode does.
103 This face is used for highlighting portions of text, in various modes.
104 For example, mouse-sensitive text is highlighted using this face.
106 This face is used for highlighting Isearch matches.
107 @item isearch-lazy-highlight-face
108 This face is used for lazy highlighting of Isearch matches other than
111 This face is used for displaying a selected region (when Transient Mark
112 mode is enabled---see below).
113 @item secondary-selection
114 This face is used for displaying a secondary X selection (@pxref{Secondary
117 This face uses a bold variant of the default font, if it has one.
119 This face uses an italic variant of the default font, if it has one.
121 This face uses a bold italic variant of the default font, if it has one.
123 This face underlines text.
125 The basic fixed-pitch face.
128 The face for the fringes to the left and right of windows on graphic
129 displays. (The fringes are the narrow portions of the Emacs frame
130 between the text area and the window's right and left borders.)
132 This face determines the visual appearance of the scroll bar.
134 This face determines the color of the frame border.
136 This face determines the color of the cursor.
138 This face determines the color of the mouse pointer.
140 This is the basic tool-bar face. No text appears in the tool bar, but the
141 colors of this face affect the appearance of tool bar icons.
143 This face is used for tooltips.
145 This face determines the colors and font of Emacs's menus. Setting the
146 font of LessTif/Motif menus is currently not supported; attempts to set
147 the font are ignored in this case.
148 @item trailing-whitespace
149 The face for highlighting trailing whitespace when
150 @code{show-trailing-whitespace} is non-nil.
152 The basic variable-pitch face.
155 @cindex @code{region} face
156 When Transient Mark mode is enabled, the text of the region is
157 highlighted when the mark is active. This uses the face named
158 @code{region}; you can control the style of highlighting by changing the
159 style of this face (@pxref{Face Customization}). @xref{Transient Mark},
160 for more information about Transient Mark mode and activation and
161 deactivation of the mark.
163 One easy way to use faces is to turn on Font Lock mode. This minor
164 mode, which is always local to a particular buffer, arranges to
165 choose faces according to the syntax of the text you are editing. It
166 can recognize comments and strings in most languages; in several
167 languages, it can also recognize and properly highlight various other
168 important constructs. @xref{Font Lock}, for more information about
169 Font Lock mode and syntactic highlighting.
171 You can print out the buffer with the highlighting that appears
172 on your screen using the command @code{ps-print-buffer-with-faces}.
176 @section Font Lock mode
177 @cindex Font Lock mode
178 @cindex mode, Font Lock
179 @cindex syntax highlighting and coloring
181 Font Lock mode is a minor mode, always local to a particular
182 buffer, which highlights (or ``fontifies'') using various faces
183 according to the syntax of the text you are editing. It can
184 recognize comments and strings in most languages; in several
185 languages, it can also recognize and properly highlight various other
186 important constructs---for example, names of functions being defined
187 or reserved keywords.
189 @findex font-lock-mode
190 @findex turn-on-font-lock
191 The command @kbd{M-x font-lock-mode} turns Font Lock mode on or off
192 according to the argument, and toggles the mode when it has no argument.
193 The function @code{turn-on-font-lock} unconditionally enables Font Lock
194 mode. This is useful in mode-hook functions. For example, to enable
195 Font Lock mode whenever you edit a C file, you can do this:
198 (add-hook 'c-mode-hook 'turn-on-font-lock)
201 @findex global-font-lock-mode
202 @vindex global-font-lock-mode
203 To turn on Font Lock mode automatically in all modes which support
204 it, customize the user option @code{global-font-lock-mode} or use the
205 function @code{global-font-lock-mode} in your @file{.emacs} file, like
209 (global-font-lock-mode 1)
212 Font Lock mode uses several specifically named faces to do its job,
213 including @code{font-lock-string-face}, @code{font-lock-comment-face},
214 and others. The easiest way to find them all is to use completion
215 on the face name in @code{set-face-foreground}.
217 To change the colors or the fonts used by Font Lock mode to fontify
218 different parts of text, just change these faces. There are
223 Invoke @kbd{M-x set-face-foreground} or @kbd{M-x set-face-background}
224 to change the colors of a particular face used by Font Lock.
225 @xref{Faces}. The command @kbd{M-x list-faces-display} displays all
226 the faces currently known to Emacs, including those used by Font Lock.
229 Customize the faces interactively with @kbd{M-x customize-face}, as
230 described in @ref{Face Customization}.
233 To get the full benefit of Font Lock mode, you need to choose a
234 default font which has bold, italic, and bold-italic variants; or else
235 you need to have a color or gray-scale screen.
237 @vindex font-lock-maximum-decoration
238 The variable @code{font-lock-maximum-decoration} specifies the
239 preferred level of fontification, for modes that provide multiple
240 levels. Level 1 is the least amount of fontification; some modes
241 support levels as high as 3. The normal default is ``as high as
242 possible.'' You can specify an integer, which applies to all modes, or
243 you can specify different numbers for particular major modes; for
244 example, to use level 1 for C/C++ modes, and the default level
248 (setq font-lock-maximum-decoration
249 '((c-mode . 1) (c++-mode . 1)))
252 @vindex font-lock-maximum-size
253 Fontification can be too slow for large buffers, so you can suppress
254 it. The variable @code{font-lock-maximum-size} specifies a buffer size,
255 beyond which buffer fontification is suppressed.
257 @c @w is used below to prevent a bad page-break.
258 @vindex font-lock-beginning-of-syntax-function
259 Comment and string fontification (or ``syntactic'' fontification)
260 relies on analysis of the syntactic structure of the buffer text. For
261 the purposes of speed, some modes, including C mode and Lisp mode,
262 rely on a special convention: an open-parenthesis or open-brace in the
263 leftmost column always defines the @w{beginning} of a defun, and is
264 thus always outside any string or comment. (@xref{Left Margin
265 Paren}.) If you don't follow this convention, Font Lock mode can
266 misfontify the text that follows an open-parenthesis or open-brace in
267 the leftmost column that is inside a string or comment.
269 @cindex slow display during scrolling
270 The variable @code{font-lock-beginning-of-syntax-function} (always
271 buffer-local) specifies how Font Lock mode can find a position
272 guaranteed to be outside any comment or string. In modes which use the
273 leftmost column parenthesis convention, the default value of the variable
274 is @code{beginning-of-defun}---that tells Font Lock mode to use the
275 convention. If you set this variable to @code{nil}, Font Lock no longer
276 relies on the convention. This avoids incorrect results, but the price
277 is that, in some cases, fontification for a changed text must rescan
278 buffer text from the beginning of the buffer. This can considerably
279 slow down redisplay while scrolling, particularly if you are close to
280 the end of a large buffer.
282 @findex font-lock-add-keywords
283 Font Lock highlighting patterns already exist for many modes, but you
284 may want to fontify additional patterns. You can use the function
285 @code{font-lock-add-keywords}, to add your own highlighting patterns for
286 a particular mode. For example, to highlight @samp{FIXME:} words in C
290 (font-lock-add-keywords
292 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
295 @node Highlight Changes
296 @section Highlight Changes Mode
298 @findex highlight-changes-mode
299 Use @kbd{M-x highlight-changes-mode} to enable a minor mode
300 that uses faces (colors, typically) to indicate which parts of
301 the buffer were changed most recently.
303 @node Highlight Interactively
304 @section Interactive Highlighting by Matching
305 @cindex highlighting by matching
306 @cindex interactive highlighting
308 It is sometimes useful to highlight the strings that match a certain
309 regular expression. For example, you might wish to see all the
310 references to a certain variable in a program source file, or highlight
311 certain parts in a voluminous output of some program, or make certain
312 cliches stand out in an article.
315 Use the @kbd{M-x hi-lock-mode} command to turn on a minor mode that
316 allows you to specify regular expressions of the text to be
317 highlighted. Hi-lock mode works like Font Lock (@pxref{Font Lock}),
318 except that it lets you specify explicitly what parts of text to
319 highlight. You control Hi-lock mode with these commands:
322 @item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
324 @findex highlight-regexp
325 Highlight text that matches
326 @var{regexp} using face @var{face} (@code{highlight-regexp}).
327 By using this command more than once, you can highlight various
328 parts of the text in different ways.
330 @item C-x w r @var{regexp} @key{RET}
332 @findex unhighlight-regexp
333 Unhighlight @var{regexp} (@code{unhighlight-regexp}). You must enter
334 one of the regular expressions currently specified for highlighting.
335 (You can use completion, or choose from a menu, to enter one of them
338 @item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
340 @findex highlight-lines-matching-regexp
341 @cindex lines, highlighting
342 @cindex highlighting lines of text
343 Highlight entire lines containing a match for @var{regexp}, using face
344 @var{face} (@code{highlight-lines-matching-regexp}).
348 @findex hi-lock-write-interactive-patterns
349 Insert all the current highlighting regexp/face pairs into the buffer
350 at point, with comment delimiters to prevent them from changing your
351 program. This key binding runs the
352 @code{hi-lock-write-interactive-patterns} command.
354 These patterns will be read the next time you visit the file while
355 Hi-lock mode is enabled, or whenever you use the @kbd{M-x
356 hi-lock-find-patterns} command.
360 @findex hi-lock-find-patterns
361 @vindex hi-lock-exclude-modes
362 Re-read regexp/face pairs in the current buffer
363 (@code{hi-lock-write-interactive-patterns}). The list of pairs is
364 found no matter where in the buffer it may be.
366 This command does nothing if the major mode is a member of the list
367 @code{hi-lock-exclude-modes}.
370 @node Trailing Whitespace
371 @section Trailing Whitespace
373 @cindex trailing whitespace
374 @cindex whitespace, trailing
375 @vindex show-trailing-whitespace
376 It is easy to leave unnecessary spaces at the end of a line without
377 realizing it. In most cases, this @dfn{trailing whitespace} has no
378 effect, but there are special circumstances where it matters.
380 You can make trailing whitespace visible on the screen by setting
381 the variable @code{show-trailing-whitespace} to @code{t}. Then Emacs
382 displays trailing whitespace in the face @code{trailing-whitespace}.
384 Trailing whitespace is defined as spaces or tabs at the end of a
385 line. But trailing whitespace is not displayed specially if point is
386 at the end of the line containing the whitespace. (Doing that looks
387 ugly while you are typing in new text, and the location of point is
388 enough in that case to show you that the spaces are present.)
390 @vindex indicate-empty-lines
391 @vindex default-indicate-empty-lines
393 Emacs can indicate empty lines at the end of the buffer with a
394 special bitmap on the left fringe of the window. To enable this
395 feature, set the buffer-local variable @code{indicate-empty-lines} to
396 a non-@code{nil} value. The default value of this variable is
397 controlled by the variable @code{default-indicate-empty-lines};
398 by setting that variable, you can enable or disable this feature
404 If a buffer contains text that is too large to fit entirely within a
405 window that is displaying the buffer, Emacs shows a contiguous portion of
406 the text. The portion shown always contains point.
409 @dfn{Scrolling} means moving text up or down in the window so that
410 different parts of the text are visible. Scrolling forward means that text
411 moves up, and new text appears at the bottom. Scrolling backward moves
412 text down and new text appears at the top.
414 Scrolling happens automatically if you move point past the bottom or top
415 of the window. You can also explicitly request scrolling with the commands
420 Clear screen and redisplay, scrolling the selected window to center
421 point vertically within it (@code{recenter}).
423 Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
425 @itemx @key{PAGEDOWN}
426 Likewise, scroll forward.
428 Scroll backward (@code{scroll-down}).
431 Likewise, scroll backward.
433 Scroll so point is on line @var{arg} (@code{recenter}).
435 Scroll heuristically to bring useful information onto the screen
436 (@code{reposition-window}).
441 The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
442 no argument. It clears the entire screen and redisplays all windows.
443 In addition, it scrolls the selected window so that point is halfway
444 down from the top of the window.
454 @vindex next-screen-context-lines
455 To read the buffer a windowful at a time, use @kbd{C-v}
456 (@code{scroll-up}) with no argument. This scrolls forward by nearly
457 the whole window height. The effect is to take the two lines at the
458 bottom of the window and put them at the top, followed by nearly a
459 whole windowful of lines that were not previously visible. If point
460 was in the text that scrolled off the top, it ends up at the new top
463 @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward
464 similarly with overlap. The number of lines of overlap across a
465 @kbd{C-v} or @kbd{M-v} is controlled by the variable
466 @code{next-screen-context-lines}; by default, it is 2. The function
467 keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP},
468 are equivalent to @kbd{C-v} and @kbd{M-v}.
470 The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll
471 the text in the selected window up or down a few lines. @kbd{C-v}
472 with an argument moves the text and point up, together, that many
473 lines; it brings the same number of new lines into view at the bottom
474 of the window. @kbd{M-v} with numeric argument scrolls the text
475 downward, bringing that many new lines into view at the top of the
476 window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice
479 The names of scroll commands are based on the direction that the
480 text moves in the window. Thus, the command to scroll forward is
481 called @code{scroll-up} because it moves the text upward on the
482 screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names
483 and customary meanings from a different convention that developed
484 elsewhere; hence the strange result that @key{PAGEDOWN} runs
487 @vindex scroll-preserve-screen-position
488 Some users like the full-screen scroll commands to keep point at the
489 same screen line. To enable this behavior, set the variable
490 @code{scroll-preserve-screen-position} to a non-@code{nil} value. This
491 mode is convenient for browsing through a file by scrolling by
492 screenfuls; if you come back to the screen where you started, point goes
493 back to the line where it started. However, this mode is inconvenient
494 when you move to the next screen in order to move point to the text
497 Another way to do scrolling is with @kbd{C-l} with a numeric argument.
498 @kbd{C-l} does not clear the screen when given an argument; it only scrolls
499 the selected window. With a positive argument @var{n}, it repositions text
500 to put point @var{n} lines down from the top. An argument of zero puts
501 point on the very top line. Point does not move with respect to the text;
502 rather, the text and point move rigidly on the screen. @kbd{C-l} with a
503 negative argument puts point that many lines from the bottom of the window.
504 For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
505 - 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put
506 point at the center (vertically) of the selected window.
509 @findex reposition-window
510 The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
511 window heuristically in a way designed to get useful information onto
512 the screen. For example, in a Lisp file, this command tries to get the
513 entire current defun onto the screen if possible.
515 @vindex scroll-conservatively
516 Scrolling happens automatically when point moves out of the visible
517 portion of the text. Normally, automatic scrolling centers point
518 vertically within the window. However, if you set
519 @code{scroll-conservatively} to a small number @var{n}, then if you
520 move point just a little off the screen---less than @var{n}
521 lines---then Emacs scrolls the text just far enough to bring point
522 back on screen. By default, @code{scroll-conservatively} is 0.
524 @cindex aggressive scrolling
525 @vindex scroll-up-aggressively
526 @vindex scroll-down-aggressively
527 When the window does scroll by a longer distance, you can control
528 how aggressively it scrolls, by setting the variables
529 @code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
530 The value of @code{scroll-up-aggressively} should be either
531 @code{nil}, or a fraction @var{f} between 0 and 1. A fraction
532 specifies where on the screen to put point when scrolling upward.
533 More precisely, when a window scrolls up because point is above the
534 window start, the new start position is chosen to put point @var{f}
535 part of the window height from the top. The larger @var{f}, the more
536 aggressive the scrolling.
538 @code{nil}, which is the default, scrolls to put point at the center.
539 So it is equivalent to .5.
541 Likewise, @code{scroll-down-aggressively} is used for scrolling
542 down. The value, @var{f}, specifies how far point should be placed
543 from the bottom of the window; thus, as with
544 @code{scroll-up-aggressively}, a larger value is more aggressive.
546 @vindex scroll-margin
547 The variable @code{scroll-margin} restricts how close point can come
548 to the top or bottom of a window. Its value is a number of screen
549 lines; if point comes within that many lines of the top or bottom of the
550 window, Emacs recenters the window. By default, @code{scroll-margin} is
553 @node Horizontal Scrolling
554 @section Horizontal Scrolling
555 @cindex horizontal scrolling
557 @dfn{Horizontal scrolling} means shifting all the lines sideways
558 within a window---so that some of the text near the left margin is not
559 displayed at all. Emacs does this automatically in any window that
560 uses line truncation rather than continuation: whenever point moves
561 off the left or right edge of the screen, Emacs scrolls the buffer
562 horizontally to make point visible.
564 When a window has been scrolled horizontally, text lines are truncated
565 rather than continued (@pxref{Continuation Lines}), with a @samp{$}
566 appearing in the first column when there is text truncated to the left,
567 and in the last column when there is text truncated to the right.
569 You can use these commands to do explicit horizontal scrolling.
573 Scroll text in current window to the left (@code{scroll-left}).
575 Scroll to the right (@code{scroll-right}).
582 The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
583 window to the left by @var{n} columns with argument @var{n}. This moves
584 part of the beginning of each line off the left edge of the window.
585 With no argument, it scrolls by almost the full width of the window (two
586 columns less, to be precise).
588 @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The
589 window cannot be scrolled any farther to the right once it is displayed
590 normally (with each line starting at the window's left margin);
591 attempting to do so has no effect. This means that you don't have to
592 calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
593 argument will restore the normal display.
595 If you scroll a window horizontally by hand, that sets a lower bound
596 for automatic horizontal scrolling. Automatic scrolling will continue
597 to scroll the window, but never farther to the right than the amount
598 you previously set by @code{scroll-left}.
600 @vindex automatic-hscrolling
601 To disable automatic horizontal scrolling, set the variable
602 @code{automatic-hscrolling} to @code{nil}.
609 @cindex windows, synchronizing
610 @cindex synchronizing windows
612 @dfn{Follow mode} is a minor mode that makes two windows showing the
613 same buffer scroll as one tall ``virtual window.'' To use Follow mode,
614 go to a frame with just one window, split it into two side-by-side
615 windows using @kbd{C-x 3}, and then type @kbd{M-x follow-mode}. From
616 then on, you can edit the buffer in either of the two windows, or scroll
617 either one; the other window follows it.
619 In Follow mode, if you move point outside the portion visible in one
620 window and into the portion visible in the other window, that selects
621 the other window---again, treating the two as if they were parts of
624 To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
626 @node Selective Display
627 @section Selective Display
628 @cindex selective display
629 @findex set-selective-display
632 Emacs has the ability to hide lines indented more than a certain number
633 of columns (you specify how many columns). You can use this to get an
634 overview of a part of a program.
636 To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
637 numeric argument @var{n}. Then lines with at least @var{n} columns of
638 indentation disappear from the screen. The only indication of their
639 presence is that three dots (@samp{@dots{}}) appear at the end of each
640 visible line that is followed by one or more hidden ones.
642 The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
643 if they were not there.
645 The hidden lines are still present in the buffer, and most editing
646 commands see them as usual, so you may find point in the middle of the
647 hidden text. When this happens, the cursor appears at the end of the
648 previous line, after the three dots. If point is at the end of the
649 visible line, before the newline that ends it, the cursor appears before
652 To make all lines visible again, type @kbd{C-x $} with no argument.
654 @vindex selective-display-ellipses
655 If you set the variable @code{selective-display-ellipses} to
656 @code{nil}, the three dots do not appear at the end of a line that
657 precedes hidden lines. Then there is no visible indication of the
658 hidden lines. This variable becomes local automatically when set.
660 @node Optional Mode Line
661 @section Optional Mode Line Features
663 @cindex line number display
664 @cindex display of line number
665 @findex line-number-mode
666 The current line number of point appears in the mode line when Line
667 Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
668 turn this mode on and off; normally it is on. The line number appears
669 before the buffer percentage @var{pos}, with the letter @samp{L} to
670 indicate what it is. @xref{Minor Modes}, for more information about
671 minor modes and about how to use this command.
673 @cindex narrowing, and line number display
674 If you have narrowed the buffer (@pxref{Narrowing}), the displayed
675 line number is relative to the accessible portion of the buffer.
677 @vindex line-number-display-limit
678 If the buffer is very large (larger than the value of
679 @code{line-number-display-limit}), then the line number doesn't appear.
680 Emacs doesn't compute the line number when the buffer is large, because
681 that would be too slow. Set it to @code{nil} to remove the limit.
683 @vindex line-number-display-limit-width
684 Line-number computation can also be slow if the lines in the buffer
685 are too long. For this reason, Emacs normally doesn't display line
686 numbers if the average width, in characters, of lines near point is
687 larger than the value of the variable
688 @code{line-number-display-limit-width}. The default value is 200
691 @cindex Column Number mode
692 @cindex mode, Column Number
693 @findex column-number-mode
694 You can also display the current column number by turning on Column
695 Number mode. It displays the current column number preceded by the
696 letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode.
699 @cindex time (on mode line)
700 Emacs can optionally display the time and system load in all mode
701 lines. To enable this feature, type @kbd{M-x display-time} or customize
702 the option @code{display-time-mode}. The information added to the mode
703 line usually appears after the buffer name, before the mode names and
704 their parentheses. It looks like this:
707 @var{hh}:@var{mm}pm @var{l.ll}
711 @vindex display-time-24hr-format
712 Here @var{hh} and @var{mm} are the hour and minute, followed always by
713 @samp{am} or @samp{pm}. @var{l.ll} is the average number of running
714 processes in the whole system recently. (Some fields may be missing if
715 your operating system cannot support them.) If you prefer time display
716 in 24-hour format, set the variable @code{display-time-24hr-format}
719 @cindex mail (on mode line)
720 @vindex display-time-use-mail-icon
721 @vindex display-time-mail-face
722 The word @samp{Mail} appears after the load level if there is mail
723 for you that you have not read yet. On a graphical display you can use
724 an icon instead of @samp{Mail} by customizing
725 @code{display-time-use-mail-icon}; this may save some space on the mode
726 line. You can customize @code{display-time-mail-face} to make the mail
729 @cindex mode line, 3D appearence
730 @cindex attributes of mode line, changing
731 @cindex non-integral number of lines in a window
732 By default, the mode line is drawn on graphics displays with
733 3D-style highlighting, like that of a button when it is not being
734 pressed. If you don't like this effect, you can disable the 3D
735 highlighting of the mode line, by customizing the attributes of the
736 @code{mode-line} face in your @file{.emacs} init file, like this:
739 (set-face-attribute 'mode-line nil :box nil)
743 Alternatively, you can turn off the box attribute in your
744 @file{.Xdefaults} file:
747 Emacs.mode-line.AttributeBox: off
751 @section How Text Is Displayed
752 @cindex characters (in text)
754 ASCII printing characters (octal codes 040 through 0176) in Emacs
755 buffers are displayed with their graphics, as are non-ASCII multibyte
756 printing characters (octal codes above 0400).
758 Some ASCII control characters are displayed in special ways. The
759 newline character (octal code 012) is displayed by starting a new line.
760 The tab character (octal code 011) is displayed by moving to the next
761 tab stop column (normally every 8 columns).
763 Other ASCII control characters are normally displayed as a caret
764 (@samp{^}) followed by the non-control version of the character; thus,
765 control-A is displayed as @samp{^A}.
767 Non-ASCII characters 0200 through 0237 (octal) are displayed with
768 octal escape sequences; thus, character code 0230 (octal) is displayed
769 as @samp{\230}. The display of character codes 0240 through 0377
770 (octal) may be either as escape sequences or as graphics. They do not
771 normally occur in multibyte buffers, but if they do, they are displayed
772 as Latin-1 graphics. In unibyte mode, if you enable European display
773 they are displayed using their graphics (assuming your terminal supports
774 them), otherwise as escape sequences. @xref{Single-Byte Character
778 @section Customization of Display
780 This section contains information for customization only. Beginning
781 users should skip it.
783 @vindex mode-line-inverse-video
784 The variable @code{mode-line-inverse-video} is an obsolete way of
785 controlling whether the mode line is displayed in inverse video; the
786 preferred way of doing this is to change the @code{mode-line} face.
787 @xref{Mode Line}. If you specify the foreground color for the
788 @code{mode-line} face, and @code{mode-line-inverse-video} is
789 non-@code{nil}, then the default background color for that face is the
790 usual foreground color. @xref{Faces}.
792 @vindex inverse-video
793 If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
794 to invert all the lines of the display from what they normally are.
797 If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
798 to make the whole screen blink when it would normally make an audible bell
799 sound. This variable has no effect if your terminal does not have a way
800 to make the screen blink.@refill
802 @vindex no-redraw-on-reenter
803 When you reenter Emacs after suspending, Emacs normally clears the
804 screen and redraws the entire display. On some terminals with more than
805 one page of memory, it is possible to arrange the termcap entry so that
806 the @samp{ti} and @samp{te} strings (output to the terminal when Emacs
807 is entered and exited, respectively) switch between pages of memory so
808 as to use one page for Emacs and another page for other output. Then
809 you might want to set the variable @code{no-redraw-on-reenter}
810 non-@code{nil}; this tells Emacs to assume, when resumed, that the
811 screen page it is using still contains what Emacs last wrote there.
813 @vindex echo-keystrokes
814 The variable @code{echo-keystrokes} controls the echoing of multi-character
815 keys; its value is the number of seconds of pause required to cause echoing
816 to start, or zero meaning don't echo at all. @xref{Echo Area}.
819 If the variable @code{ctl-arrow} is @code{nil}, all control characters in
820 the buffer are displayed with octal escape sequences, except for newline
821 and tab. Altering the value of @code{ctl-arrow} makes it local to the
822 current buffer; until that time, the default value is in effect. The
823 default is initially @code{t}. @xref{Display Tables,, Display Tables,
824 elisp, The Emacs Lisp Reference Manual}.
827 Normally, a tab character in the buffer is displayed as whitespace which
828 extends to the next display tab stop position, and display tab stops come
829 at intervals equal to eight spaces. The number of spaces per tab is
830 controlled by the variable @code{tab-width}, which is made local by
831 changing it, just like @code{ctl-arrow}. Note that how the tab character
832 in the buffer is displayed has nothing to do with the definition of
833 @key{TAB} as a command. The variable @code{tab-width} must have an
834 integer value between 1 and 1000, inclusive.
836 @c @vindex truncate-lines @c No index entry here, because we have one
837 @c in the continuation section.
838 If the variable @code{truncate-lines} is non-@code{nil}, then each
839 line of text gets just one screen line for display; if the text line is
840 too long, display shows only the part that fits. If
841 @code{truncate-lines} is @code{nil}, then long text lines display as
842 more than one screen line, enough to show the whole text of the line.
843 @xref{Continuation Lines}. Altering the value of @code{truncate-lines}
844 makes it local to the current buffer; until that time, the default value
845 is in effect. The default is initially @code{nil}.
847 @c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
848 If the variable @code{truncate-partial-width-windows} is
849 non-@code{nil}, it forces truncation rather than continuation in any
850 window less than the full width of the screen or frame, regardless of
851 the value of @code{truncate-lines}. For information about side-by-side
852 windows, see @ref{Split Window}. See also @ref{Display,, Display,
853 elisp, The Emacs Lisp Reference Manual}.
856 The variable @code{baud-rate} holds the output speed of the
857 terminal, as far as Emacs knows. Setting this variable does not
858 change the speed of actual data transmission, but the value is used
859 for calculations. On terminals, it affects padding, and decisions
860 about whether to scroll part of the screen or redraw it instead.
861 It also affects the behavior of incremental search.
863 On window-systems, @code{baud-rate} is only used to determine how
864 frequently to look for pending input during display updating. A
865 higher value of @code{baud-rate} means that check for pending input
866 will be done less frequently.
868 You can customize the way any particular character code is displayed
869 by means of a display table. @xref{Display Tables,, Display Tables,
870 elisp, The Emacs Lisp Reference Manual}.
872 @cindex hourglass pointer display
873 @vindex hourglass-delay
874 On a window system, Emacs can optionally display the mouse pointer
875 in a special shape to say that Emacs is busy. To turn this feature on
876 or off, customize the group @code{cursor}. You can also control the
877 amount of time Emacs must remain busy before the busy indicator is
878 displayed, by setting the variable @code{hourglass-delay}.
881 @section Displaying the Cursor
884 @cindex highlight current line
885 @findex blink-cursor-mode
886 @cindex cursor, locating visually
887 @cindex cursor, blinking
888 There are a number of ways to customize the display of the cursor.
889 @kbd{M-x hl-line-mode} enables or disables a global minor mode which
890 highlights the line containing point. On window systems, the command
891 @kbd{M-x blink-cursor-mode} turns on or off the blinking of the
892 cursor. (On terminals, the terminal itself blinks the cursor, and
893 Emacs has no control over it.)
895 You can customize the cursor's color, and whether it blinks, using
896 the @code{cursor} Custom group (@pxref{Easy Customization}).
898 @vindex x-stretch-cursor
899 @cindex wide block cursor
900 When displaying on a window system, Emacs can optionally draw the
901 block cursor as wide as the character under the cursor---for example,
902 if the cursor is on a tab character, it would cover the full width
903 occupied by that tab character. To enable this feature, set the
904 variable @code{x-stretch-cursor} to a non-@code{nil} value.
906 @cindex cursor in non-selected windows
907 @vindex cursor-in-non-selected-windows
908 Normally, the cursor in non-selected windows is shown as a hollow box.
909 To turn off cursor display in non-selected windows, customize the option
910 @code{cursor-in-non-selected-windows} to assign it a @code{nil} value.