1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Display, Search, Registers, Top
5 @chapter Controlling the Display
7 Since only part of a large buffer fits in the window, Emacs tries to
8 show a part that is likely to be interesting. Display-control commands
9 allow you to specify which part of the text you want to see, and how to
13 * Scrolling:: Moving text up and down in a window.
14 * Horizontal Scrolling:: Moving text left and right in a window.
15 * Follow Mode:: Follow mode lets two windows scroll as one.
16 * Selective Display:: Hiding lines with lots of indentation.
17 * Optional Mode Line:: Optional mode line display features.
18 * Text Display:: How text characters are normally displayed.
19 * Display Vars:: Information on variables for customizing display.
25 If a buffer contains text that is too large to fit entirely within a
26 window that is displaying the buffer, Emacs shows a contiguous portion of
27 the text. The portion shown always contains point.
30 @dfn{Scrolling} means moving text up or down in the window so that
31 different parts of the text are visible. Scrolling forward means that text
32 moves up, and new text appears at the bottom. Scrolling backward moves
33 text down and new text appears at the top.
35 Scrolling happens automatically if you move point past the bottom or top
36 of the window. You can also explicitly request scrolling with the commands
41 Clear screen and redisplay, scrolling the selected window to center
42 point vertically within it (@code{recenter}).
44 Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
46 Likewise, scroll forward.
48 Scroll backward (@code{scroll-down}).
50 Likewise, scroll backward.
52 Scroll so point is on line @var{arg} (@code{recenter}).
54 Scroll heuristically to bring useful information onto the screen
55 (@code{reposition-window}).
60 The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
61 no argument. It clears the entire screen and redisplays all windows.
62 In addition, it scrolls the selected window so that point is halfway
63 down from the top of the window.
71 The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text
72 in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an
73 argument shows you that many more lines at the bottom of the window, moving
74 the text and point up together as @kbd{C-l} might. @kbd{C-v} with a
75 negative argument shows you more lines at the top of the window.
76 @kbd{M-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
77 opposite direction. The function keys @key{NEXT} and @key{PRIOR} are
78 equivalent to @kbd{C-v} and @kbd{M-v}.
80 The names of scroll commands are based on the direction that the text
81 moves in the window. Thus, the command to scroll forward is called
82 @code{scroll-up} because it moves the text upward on the screen.
84 @vindex next-screen-context-lines
85 To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
86 It takes the last two lines at the bottom of the window and puts them at
87 the top, followed by nearly a whole windowful of lines not previously
88 visible. If point was in the text scrolled off the top, it moves to the
89 new top of the window. @kbd{M-v} with no argument moves backward with
90 overlap similarly. The number of lines of overlap across a @kbd{C-v} or
91 @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
94 @vindex scroll-preserve-screen-position
95 Some users like the full-screen scroll commands to keep point at the
96 same screen line. To enable this behavior, set the variable
97 @code{scroll-preserve-screen-position} to a non-@code{nil} value. This
98 mode is convenient for browsing through a file by scrolling by
99 screenfuls; if you come back to the screen where you started, point goes
100 back to the line where it started. However, this mode is inconvenient
101 when you move to the next screen in order to move point to the text
104 Another way to do scrolling is with @kbd{C-l} with a numeric argument.
105 @kbd{C-l} does not clear the screen when given an argument; it only scrolls
106 the selected window. With a positive argument @var{n}, it repositions text
107 to put point @var{n} lines down from the top. An argument of zero puts
108 point on the very top line. Point does not move with respect to the text;
109 rather, the text and point move rigidly on the screen. @kbd{C-l} with a
110 negative argument puts point that many lines from the bottom of the window.
111 For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
112 - 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument,
113 as in @kbd{C-u C-l}, scrolls point to the center of the selected window.
116 @findex reposition-window
117 The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
118 window heuristically in a way designed to get useful information onto
119 the screen. For example, in a Lisp file, this command tries to get the
120 entire current defun onto the screen if possible.
122 @vindex scroll-conservatively
123 Scrolling happens automatically if point has moved out of the visible
124 portion of the text when it is time to display. Normally, automatic
125 scrolling centers point vertically within the window. However, if you
126 set @code{scroll-conservatively} to a small number @var{n}, then if you
127 move point just a little off the screen---less than @var{n} lines---then
128 Emacs scrolls the text just far enough to bring point back on screen.
129 By default, @code{scroll-conservatively} is 0.
131 @cindex aggressive scrolling
132 @vindex scroll-up-aggressively
133 @vindex scroll-down-aggressively
134 If you prefer a more aggressive scrolling, customize the values of the
135 variables @code{scroll-up-aggressively} and
136 @code{scroll-down-aggressively}. The value of
137 @code{scroll-up-aggressively} should be either nil or a fraction @var{f}
138 between 0 and 1. If it is a fraction, that specifies where on the
139 screen to put point when scrolling upward. More precisely, when a
140 window scrolls up because point is above the window start, the new start
141 position is chosen to put point @var{f} part of the window height from
142 the top. The larger @var{f}, the more aggressive the scrolling.
144 A value of @code{nil} is equivalent to .5, since its effect is to center
147 Likewise, @code{scroll-down-aggressively} is used for scrolling down.
148 The value, @var{f}, specifies how far point should be placed from the
149 bottom of the window; thus, as with @code{scroll-up-aggressively}, a
150 larger value scrolls more aggressively.
152 @vindex scroll-margin
153 The variable @code{scroll-margin} restricts how close point can come
154 to the top or bottom of a window. Its value is a number of screen
155 lines; if point comes within that many lines of the top or bottom of the
156 window, Emacs recenters the window. By default, @code{scroll-margin} is
159 @node Horizontal Scrolling
160 @section Horizontal Scrolling
161 @cindex horizontal scrolling
163 @dfn{Horizontal scrolling} means shifting all the lines sideways
164 within a window---so that some of the text near the left margin
165 is not displayed at all.
169 Scroll text in current window to the left (@code{scroll-left}).
171 Scroll to the right (@code{scroll-right}).
174 When a window has been scrolled horizontally, text lines are truncated
175 rather than continued (@pxref{Continuation Lines}), with a @samp{$}
176 appearing in the first column when there is text truncated to the left,
177 and in the last column when there is text truncated to the right.
183 The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
184 window to the left by @var{n} columns with argument @var{n}. This moves
185 part of the beginning of each line off the left edge of the window.
186 With no argument, it scrolls by almost the full width of the window (two
187 columns less, to be precise).
189 @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The
190 window cannot be scrolled any farther to the right once it is displayed
191 normally (with each line starting at the window's left margin);
192 attempting to do so has no effect. This means that you don't have to
193 calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
194 argument will restore the normal display.
196 @cindex horizontal scrolling
197 @vindex automatic-hscrolling
198 Emacs automatically scrolls a window horizontally whenever that is
199 necessary to keep point visible and not too far from the left or right
200 edge. If you don't want this, customize the variable
201 @code{automatic-hscrolling} and set it to nil.
203 If a window is scrolled horizontally by means of @code{scroll-left}, the
204 chosen column serves as a lower bound for automatic horizontal
205 scrolling. Automatic scrolling will continue to scroll the window to
206 the left, if necessary, but won't scroll it more to the right than the
207 column set by @code{scroll-left}.
214 @dfn{Follow mode} is a minor mode that makes two windows showing the
215 same buffer scroll as one tall ``virtual window.'' To use Follow mode,
216 go to a frame with just one window, split it into two side-by-side
217 windows using @kbd{C-x 3}, and then type @kbd{M-x follow-mode}. From
218 then on, you can edit the buffer in either of the two windows, or scroll
219 either one; the other window follows it.
221 To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
223 @node Selective Display
224 @section Selective Display
225 @findex set-selective-display
228 Emacs has the ability to hide lines indented more than a certain number
229 of columns (you specify how many columns). You can use this to get an
230 overview of a part of a program.
232 To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
233 numeric argument @var{n}. Then lines with at least @var{n} columns of
234 indentation disappear from the screen. The only indication of their
235 presence is that three dots (@samp{@dots{}}) appear at the end of each
236 visible line that is followed by one or more hidden ones.
238 The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
239 if they were not there.
241 The hidden lines are still present in the buffer, and most editing
242 commands see them as usual, so you may find point in the middle of the
243 hidden text. When this happens, the cursor appears at the end of the
244 previous line, after the three dots. If point is at the end of the
245 visible line, before the newline that ends it, the cursor appears before
248 To make all lines visible again, type @kbd{C-x $} with no argument.
250 @vindex selective-display-ellipses
251 If you set the variable @code{selective-display-ellipses} to
252 @code{nil}, the three dots do not appear at the end of a line that
253 precedes hidden lines. Then there is no visible indication of the
254 hidden lines. This variable becomes local automatically when set.
256 @node Optional Mode Line
257 @section Optional Mode Line Features
259 @cindex Line Number mode
260 @cindex mode, Line Number
261 @findex line-number-mode
262 The current line number of point appears in the mode line when Line
263 Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
264 turn this mode on and off; normally it is on. The line number appears
265 before the buffer percentage @var{pos}, with the letter @samp{L} to
266 indicate what it is. @xref{Minor Modes}, for more information about
267 minor modes and about how to use this command.
269 @vindex line-number-display-limit
270 @cindex line number display, removing the limit
271 If the buffer is very large (larger than the value of
272 @code{line-number-display-limit}), then the line number doesn't appear.
273 Emacs doesn't compute the line number when the buffer is large, because
274 that would be too slow. Set it to @code{nil} to remove the limit. If
275 you have narrowed the buffer (@pxref{Narrowing}), the displayed line
276 number is relative to the accessible portion of the buffer.
278 @cindex Column Number mode
279 @cindex mode, Column Number
280 @findex column-number-mode
281 You can also display the current column number by turning on Column
282 Number mode. It displays the current column number preceded by the
283 letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode.
286 @cindex time (on mode line)
287 Emacs can optionally display the time and system load in all mode
288 lines. To enable this feature, type @kbd{M-x display-time} or customize
289 the option @code{display-time-mode}. The information added to the mode
290 line usually appears after the buffer name, before the mode names and
291 their parentheses. It looks like this:
294 @var{hh}:@var{mm}pm @var{l.ll}
298 @vindex display-time-24hr-format
299 Here @var{hh} and @var{mm} are the hour and minute, followed always by
300 @samp{am} or @samp{pm}. @var{l.ll} is the average number of running
301 processes in the whole system recently. (Some fields may be missing if
302 your operating system cannot support them.) If you prefer time display
303 in 24-hour format, set the variable @code{display-time-24hr-format}
306 @cindex mail (on mode line)
307 @vindex display-time-use-mail-icon
308 @vindex display-time-mail-face
309 The word @samp{Mail} appears after the load level if there is mail
310 for you that you have not read yet. On a graphical display you can use
311 an icon instead of @samp{Mail} by customizing
312 @code{display-time-use-mail-icon}; this may save some space on the mode
313 line. You can customize @code{display-time-mail-face} to make the mail
317 @section How Text Is Displayed
318 @cindex characters (in text)
320 ASCII printing characters (octal codes 040 through 0176) in Emacs
321 buffers are displayed with their graphics. So are non-ASCII multibyte
322 printing characters (octal codes above 0400).
324 Some ASCII control characters are displayed in special ways. The
325 newline character (octal code 012) is displayed by starting a new line.
326 The tab character (octal code 011) is displayed by moving to the next
327 tab stop column (normally every 8 columns).
329 Other ASCII control characters are normally displayed as a caret
330 (@samp{^}) followed by the non-control version of the character; thus,
331 control-A is displayed as @samp{^A}.
333 Non-ASCII characters 0200 through 0237 (octal) are displayed with
334 octal escape sequences; thus, character code 0230 (octal) is displayed
335 as @samp{\230}. The display of character codes 0240 through 0377
336 (octal) may be either as escape sequences or as graphics. They do not
337 normally occur in multibyte buffers but if they do, they are displayed
338 as Latin-1 graphics. In unibyte mode, if you enable European display
339 they are displayed using their graphics (assuming your terminal supports
340 them), otherwise as escape sequences. @xref{Single-Byte Character
344 @section Variables Controlling Display
346 This section contains information for customization only. Beginning
347 users should skip it.
349 @vindex mode-line-inverse-video
350 The variable @code{mode-line-inverse-video} is an obsolete way of
351 controlling whether the mode line is displayed in inverse video; the
352 preferred way of doing this is to change the @code{mode-line} face.
353 @xref{Mode Line}. If you specify the foreground color for the
354 @code{mode-line} face, and @code{mode-line-inverse-video} is
355 non-@code{nil}, then the default background color for that face is the
356 usual foreground color. @xref{Faces}.
358 @vindex inverse-video
359 If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
360 to invert all the lines of the display from what they normally are.
363 If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
364 to make the whole screen blink when it would normally make an audible bell
365 sound. This variable has no effect if your terminal does not have a way
366 to make the screen blink.@refill
368 @vindex no-redraw-on-reenter
369 When you reenter Emacs after suspending, Emacs normally clears the
370 screen and redraws the entire display. On some terminals with more than
371 one page of memory, it is possible to arrange the termcap entry so that
372 the @samp{ti} and @samp{te} strings (output to the terminal when Emacs
373 is entered and exited, respectively) switch between pages of memory so
374 as to use one page for Emacs and another page for other output. Then
375 you might want to set the variable @code{no-redraw-on-reenter}
376 non-@code{nil}; this tells Emacs to assume, when resumed, that the
377 screen page it is using still contains what Emacs last wrote there.
379 @vindex echo-keystrokes
380 The variable @code{echo-keystrokes} controls the echoing of multi-character
381 keys; its value is the number of seconds of pause required to cause echoing
382 to start, or zero meaning don't echo at all. @xref{Echo Area}.
385 If the variable @code{ctl-arrow} is @code{nil}, control characters in
386 the buffer are displayed with octal escape sequences, except for newline
387 and tab. Altering the value of @code{ctl-arrow} makes it local to the
388 current buffer; until that time, the default value is in effect. The
389 default is initially @code{t}. @xref{Display Tables,, Display Tables,
390 elisp, The Emacs Lisp Reference Manual}.
393 Normally, a tab character in the buffer is displayed as whitespace which
394 extends to the next display tab stop position, and display tab stops come
395 at intervals equal to eight spaces. The number of spaces per tab is
396 controlled by the variable @code{tab-width}, which is made local by
397 changing it, just like @code{ctl-arrow}. Note that how the tab character
398 in the buffer is displayed has nothing to do with the definition of
399 @key{TAB} as a command. The variable @code{tab-width} must have an
400 integer value between 1 and 1000, inclusive.
402 @c @vindex truncate-lines @c No index entry here, because we have one
403 @c in the continuation section.
404 If the variable @code{truncate-lines} is non-@code{nil}, then each
405 line of text gets just one screen line for display; if the text line is
406 too long, display shows only the part that fits. If
407 @code{truncate-lines} is @code{nil}, then long text lines display as
408 more than one screen line, enough to show the whole text of the line.
409 @xref{Continuation Lines}. Altering the value of @code{truncate-lines}
410 makes it local to the current buffer; until that time, the default value
411 is in effect. The default is initially @code{nil}.
413 @c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
414 If the variable @code{truncate-partial-width-windows} is
415 non-@code{nil}, it forces truncation rather than continuation in any
416 window less than the full width of the screen or frame, regardless of
417 the value of @code{truncate-lines}. For information about side-by-side
418 windows, see @ref{Split Window}. See also @ref{Display,, Display,
419 elisp, The Emacs Lisp Reference Manual}.
422 The variable @code{baud-rate} holds the output speed of the terminal,
423 as far as Emacs knows. Setting this variable does not change the speed
424 of actual data transmission, but the value is used for calculations such
425 as padding. On terminals, it also affects decisions about whether to
426 scroll part of the screen or redraw it instead.
428 On window-systems, @code{baud-rate} is only used to determine how
429 frequently to look for pending input during display updating. A higher
430 value of @code{baud-rate} means that check for pending input will be
431 done less frequently.
433 You can customize the way any particular character code is displayed
434 by means of a display table. @xref{Display Tables,, Display Tables,
435 elisp, The Emacs Lisp Reference Manual}.