19. Controlling the Display

Since only part of a large buffer fits in the window, Emacs tries to show a part that is likely to be interesting. Display-control commands allow you to specify which part of the text you want to see, and how to display it. Many variables also affect the details of redisplay. Unless otherwise stated, the variables described in this chapter have their effect by customizing redisplay itself; therefore, their values only make a difference at the time of redisplay.

19.1 Scrolling

If a buffer contains text that is too large to fit entirely within a window that is displaying the buffer, Emacs shows a contiguous portion of the text. The portion shown always contains point.

Scrolling means moving text up or down in the window so that different parts of the text are visible. Scrolling "forward" or "up" means that text moves up, and new text appears at the bottom. Scrolling "backward" or "down" moves text down, and new text appears at the top.

Scrolling happens automatically if you move point past the bottom or top of the window. You can also scroll explicitly with the commands in this section.

C-l

Clear screen and redisplay, scrolling the selected window to center point vertically within it (recenter).

C-v

Scroll forward (a windowful or a specified number of lines) (scroll-up).

NEXT

PAGEDOWN

Likewise, scroll forward.

M-v

Scroll backward (scroll-down).

PRIOR

PAGEUP

Likewise, scroll backward.

arg C-l

Scroll so point is on line arg (recenter).

C-M-l

Scroll heuristically to bring useful information onto the screen (reposition-window).

The most basic scrolling command is C-l (recenter) with no argument. It scrolls the selected window so that point is halfway down from the top of the window. On a text terminal, it also clears the screen and redisplays all windows. That is useful in case the screen is garbled (see section Garbage on the Screen).

To read the buffer a windowful at a time, use C-v (scroll-up) with no argument. This scrolls forward by nearly the whole window height. The effect is to take the two lines at the bottom of the window and put them at the top, followed by nearly a whole windowful of lines that were not previously visible. If point was in the text that scrolled off the top, it ends up at the new top of the window.

M-v (scroll-down) with no argument scrolls backward in a similar way, also with overlap. The number of lines of overlap that the C-v or M-v commands leave is controlled by the variable next-screen-context-lines; by default, it is 2. The function keys NEXT and PRIOR, or PAGEDOWN and PAGEUP, are equivalent to C-v and M-v.

The commands C-v and M-v with a numeric argument scroll the text in the selected window up or down a few lines. C-v with an argument moves the text and point up, together, that many lines; it brings the same number of new lines into view at the bottom of the window. M-v with numeric argument scrolls the text downward, bringing that many new lines into view at the top of the window. C-v with a negative argument is like M-v and vice versa.

The names of scroll commands are based on the direction that the text moves in the window. Thus, the command to scroll forward is called scroll-up because it moves the text upward on the screen. The keys PAGEDOWN and PAGEUP derive their names and customary meanings from a different convention that developed elsewhere; hence the strange result that PAGEDOWN runs scroll-up.

Some users like the full-screen scroll commands to keep point at the same screen line. To enable this behavior, set the variable scroll-preserve-screen-position to a non-nil value. In this mode, when these commands would scroll the text around point off the screen, or within scroll-margin lines of the edge, they move point to keep the same vertical position within the window. This mode is convenient for browsing through a file by scrolling by screenfuls; if you come back to the screen where you started, point goes back to the line where it started. However, this mode is inconvenient when you move to the next screen in order to move point to the text there.

Another way to do scrolling is with C-l with a numeric argument. C-l does not clear the screen when given an argument; it only scrolls the selected window. With a positive argument n, it repositions text to put point n lines down from the top. An argument of zero puts point on the very top line. Point does not move with respect to the text; rather, the text and point move rigidly on the screen. C-l with a negative argument puts point that many lines from the bottom of the window. For example, C-u - 1 C-l puts point on the bottom line, and C-u - 5 C-l puts it five lines from the bottom. C-u C-l scrolls to put point at the center (vertically) of the selected window.

The C-M-l command (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.

19.2 Automatic Scrolling

Redisplay scrolls the buffer automatically when point moves out of the visible portion of the text. The purpose of automatic scrolling is to make point visible, but you can customize many aspects of how this is done.

Normally, automatic scrolling centers point vertically within the window. However, if you set scroll-conservatively to a small number n, then if you move point just a little off the screen--less than n lines--then Emacs scrolls the text just far enough to bring point back on screen. By default, scroll-conservatively is@tie{}0.

When the window does scroll by a longer distance, you can control how aggressively it scrolls, by setting the variables scroll-up-aggressively and scroll-down-aggressively. The value of scroll-up-aggressively should be either nil, or a fraction f between 0 and 1. A fraction specifies where on the screen to put point when scrolling upward. More precisely, when a window scrolls up because point is above the window start, the new start position is chosen to put point f part of the window height from the top. The larger f, the more aggressive the scrolling.

nil, which is the default, scrolls to put point at the center. So it is equivalent to .5.

Likewise, scroll-down-aggressively is used for scrolling down. The value, f, specifies how far point should be placed from the bottom of the window; thus, as with scroll-up-aggressively, a larger value is more aggressive.

The variable scroll-margin restricts how close point can come to the top or bottom of a window. Its value is a number of screen lines; if point comes within that many lines of the top or bottom of the window, Emacs recenters the window. By default, scroll-margin is 0.

19.3 Horizontal Scrolling

Horizontal scrolling means shifting all the lines sideways within a window--so that some of the text near the left margin is not displayed at all. When the text in a window is scrolled horizontally, text lines are truncated rather than continued (see section Truncation of Lines). Whenever a window shows truncated lines, Emacs automatically updates its horizontal scrolling whenever point moves off the left or right edge of the screen. You can also use these commands to do explicit horizontal scrolling.

C-x <

Scroll text in current window to the left (scroll-left).

C-x >

Scroll to the right (scroll-right).

The command C-x < (scroll-left) scrolls the selected window to the left by n columns with argument n. This moves part of the beginning of each line off the left edge of the window. With no argument, it scrolls by almost the full width of the window (two columns less, to be precise).

C-x > (scroll-right) scrolls similarly to the right. The window cannot be scrolled any farther to the right once it is displayed normally (with each line starting at the window's left margin); attempting to do so has no effect. This means that you don't have to calculate the argument precisely for C-x >; any sufficiently large argument will restore the normal display.

If you use those commands to scroll a window horizontally, that sets a lower bound for automatic horizontal scrolling. Automatic scrolling will continue to scroll the window, but never farther to the right than the amount you previously set by scroll-left.

The value of the variable hscroll-margin controls how close to the window's edges point is allowed to get before the window will be automatically scrolled. It is measured in columns. If the value is 5, then moving point within 5 columns of the edge causes horizontal scrolling away from that edge.

The variable hscroll-step determines how many columns to scroll the window when point gets too close to the edge. If it's zero, horizontal scrolling centers point horizontally within the window. If it's a positive integer, it specifies the number of columns to scroll by. If it's a floating-point number, it specifies the fraction of the window's width to scroll by. The default is zero.

To disable automatic horizontal scrolling, set the variable auto-hscroll-mode to nil.

19.4 Follow Mode

Follow mode is a minor mode that makes two windows, both showing the same buffer, scroll as a single tall "virtual window." To use Follow mode, go to a frame with just one window, split it into two side-by-side windows using C-x 3, and then type M-x follow-mode. From then on, you can edit the buffer in either of the two windows, or scroll either one; the other window follows it.

In Follow mode, if you move point outside the portion visible in one window and into the portion visible in the other window, that selects the other window--again, treating the two as if they were parts of one large window.

To turn off Follow mode, type M-x follow-mode a second time.

19.5 Using Multiple Typefaces

You can specify various styles for displaying text using faces. Each face can specify various face attributes, such as the font family, the height, weight and slant of the characters, the foreground and background color, and underlining or overlining. A face does not have to specify all of these attributes; often it inherits most of them from another face.

On graphical display, all the Emacs face attributes are meaningful. On a text-only terminal, only some of them work. Some text-only terminals support inverse video, bold, and underline attributes; some support colors. Text-only terminals generally do not support changing the height and width or the font family.

Emacs uses faces automatically for highlighting, through the work of Font Lock mode. See section Font Lock mode, for more information about Font Lock mode and syntactic highlighting. You can print out the buffer with the highlighting that appears on your screen using the command ps-print-buffer-with-faces. See section PostScript Hardcopy.

You control the appearance of a part of the text in the buffer by specifying the face or faces to use for it. The style of display used for any given character is determined by combining the attributes of all the applicable faces specified for that character. Any attribute that isn't specified by these faces is taken from the default face, whose attributes reflect the default settings of the frame itself.

Enriched mode, the mode for editing formatted text, includes several commands and menus for specifying faces for text in the buffer. See section Faces in Formatted Text, for how to specify the font for text in the buffer. See section Colors in Formatted Text, for how to specify the foreground and background color.

To alter the appearance of a face, use the customization buffer. See section Customizing Faces. You can also use X resources to specify attributes of particular faces (see section X Resources). Alternatively, you can change the foreground and background colors of a specific face with M-x set-face-foreground and M-x set-face-background. These commands prompt in the minibuffer for a face name and a color name, with completion, and then set that face to use the specified color. Changing the colors of the default face also changes the foreground and background colors on all frames, both existing and those to be created in the future. (You can also set foreground and background colors for the current frame only; see Setting Frame Parameters.)

If you want to alter the appearance of all Emacs frames, you need to customize the frame parameters in the variable default-frame-alist; see default-frame-alist.

Emacs can correctly display variable-width fonts, but Emacs commands that calculate width and indentation do not know how to calculate variable widths. This can sometimes lead to incorrect results when you use variable-width fonts. In particular, indentation commands can give inconsistent results, so we recommend you avoid variable-width fonts for editing program source code. Filling will sometimes make lines too long or too short. We plan to address these issues in future Emacs versions.

19.6 Standard Faces

To see what faces are currently defined, and what they look like, type M-x list-faces-display. It's possible for a given face to look different in different frames; this command shows the appearance in the frame in which you type it. With a prefix argument, this prompts for a regular expression, and displays only faces with names matching that regular expression.

Here are the standard faces for specifying text appearance. You can apply them to specific text when you want the effects they produce.

default

This face is used for ordinary text that doesn't specify any face.

bold

This face uses a bold variant of the default font, if it has one. It's up to you to choose a default font that has a bold variant, if you want to use one.

italic

This face uses an italic variant of the default font, if it has one.

bold-italic

This face uses a bold italic variant of the default font, if it has one.

underline

This face underlines text.

fixed-pitch

This face forces use of a particular fixed-width font.

variable-pitch

This face forces use of a particular variable-width font. It's reasonable to customize this face to use a different variable-width font, if you like, but you should not make it a fixed-width font.

shadow

This face is used for making the text less noticeable than the surrounding ordinary text. Usually this can be achieved by using shades of gray in contrast with either black or white default foreground color.

Here's an incomplete list of faces used to highlight parts of the text temporarily for specific purposes. (Many other modes define their own faces for this purpose.)

highlight

This face is used for highlighting portions of text, in various modes. For example, mouse-sensitive text is highlighted using this face.

isearch

This face is used for highlighting the current Isearch match.

query-replace

This face is used for highlighting the current Query Replace match.

lazy-highlight

This face is used for lazy highlighting of Isearch and Query Replace matches other than the current one.

region

This face is used for displaying a selected region (when Transient Mark mode is enabled--see below).

secondary-selection

This face is used for displaying a secondary X selection (see section Secondary Selection).

trailing-whitespace

The face for highlighting excess spaces and tabs at the end of a line when show-trailing-whitespace is non-nil; see Useless Whitespace.

nobreak-space

The face for displaying the character "nobreak space."

escape-glyph

The face for highlighting the `\' or `^' that indicates a control character. It's also used when `\' indicates a nobreak space or nobreak (soft) hyphen.

When Transient Mark mode is enabled, the text of the region is highlighted when the mark is active. This uses the face named region; you can control the style of highlighting by changing the style of this face (see section Customizing Faces). See section Transient Mark Mode, for more information about Transient Mark mode and activation and deactivation of the mark.

These faces control the appearance of parts of the Emacs frame. They exist as faces to provide a consistent way to customize the appearance of these parts of the frame.

mode-line

modeline

This face is used for the mode line of the currently selected window, and for menu bars when toolkit menus are not used. By default, it's drawn with shadows for a "raised" effect on graphical displays, and drawn as the inverse of the default face on non-windowed terminals. modeline is an alias for the mode-line face, for compatibility with old Emacs versions.

mode-line-inactive

Like mode-line, but used for mode lines of the windows other than the selected one (if mode-line-in-non-selected-windows is non-nil). This face inherits from mode-line, so changes in that face affect mode lines in all windows.

mode-line-highlight

Like highlight, but used for portions of text on mode lines.

mode-line-buffer-id

This face is used for buffer identification parts in the mode line.

header-line

Similar to mode-line for a window's header line, which appears at the top of a window just as the mode line appears at the bottom. Most windows do not have a header line--only some special modes, such Info mode, create one.

vertical-border

This face is used for the vertical divider between windows. By default this face inherits from the mode-line-inactive face on character terminals. On graphical displays the foreground color of this face is used for the vertical line between windows without scrollbars.

minibuffer-prompt

This face is used for the prompt strings displayed in the minibuffer. By default, Emacs automatically adds this face to the value of minibuffer-prompt-properties, which is a list of text properties used to display the prompt text. (This variable takes effect when you enter the minibuffer.)

fringe

The face for the fringes to the left and right of windows on graphic displays. (The fringes are the narrow portions of the Emacs frame between the text area and the window's right and left borders.) See section Window Fringes.

scroll-bar

This face determines the visual appearance of the scroll bar. See section Scroll Bars.

border

This face determines the color of the frame border.

cursor

This face determines the color of the cursor.

mouse

This face determines the color of the mouse pointer.

tool-bar

This face determines the color of tool bar icons. See section Tool Bars.

tooltip

This face is used for tooltips. See section Tooltips.

menu

This face determines the colors and font of Emacs's menus. See section Menu Bars. Setting the font of LessTif/Motif menus is currently not supported; attempts to set the font are ignored in this case. Likewise, attempts to customize this face in Emacs built with GTK and in the MS-Windows/Mac ports are ignored by the respective GUI toolkits; you need to use system-wide styles and options to change the appearance of the menus.

19.7 Font Lock mode

Font Lock mode is a minor mode, always local to a particular buffer, which highlights (or "fontifies") the buffer contents according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs--for example, names of functions being defined or reserved keywords. Some special modes, such as Occur mode and Info mode, have completely specialized ways of assigning fonts for Font Lock mode.

Font Lock mode is turned on by default in all modes which support it. You can toggle font-lock for each buffer with the command M-x font-lock-mode. Using a positive argument unconditionally turns Font Lock mode on, and a negative or zero argument turns it off.

If you do not wish Font Lock mode to be turned on by default, customize the variable global-font-lock-mode using the Customize interface (see section Easy Customization Interface), or use the function global-font-lock-mode in your `.emacs' file, like this:

(global-font-lock-mode 0)

This variable, like all the variables that control Font Lock mode, take effect whenever fontification is done; that is, potentially at any time.

If you have disabled Global Font Lock mode, you can still enable Font Lock for specific major modes by adding the function turn-on-font-lock to the mode hooks (see section Hooks). For example, to enable Font Lock mode for editing C files, you can do this:

(add-hook 'c-mode-hook 'turn-on-font-lock)

Font Lock mode uses several specifically named faces to do its job, including font-lock-string-face, font-lock-comment-face, and others. The easiest way to find them all is to use M-x customize-group RET font-lock-faces RET. You can then use that customization buffer to customize the appearance of these faces. See section Customizing Faces.

You can also customize these faces using M-x set-face-foreground or M-x set-face-background. See section Using Multiple Typefaces.

The variable font-lock-maximum-decoration specifies the preferred level of fontification, for modes that provide multiple levels. Level 1 is the least amount of fontification; some modes support levels as high as 3. The normal default is "as high as possible." You can specify an integer, which applies to all modes, or you can specify different numbers for particular major modes; for example, to use level 1 for C/C++ modes, and the default level otherwise, use this:

(setq font-lock-maximum-decoration
      '((c-mode . 1) (c++-mode . 1)))

Fontification can be too slow for large buffers, so you can suppress it for buffers above a certain size. The variable font-lock-maximum-size specifies a buffer size, beyond which buffer fontification is suppressed.

Comment and string fontification (or "syntactic" fontification) relies on analysis of the syntactic structure of the buffer text. For the sake of speed, some modes, including Lisp mode, rely on a special convention: an open-parenthesis or open-brace in the leftmost column always defines the beginning of a defun, and is thus always outside any string or comment. (See section Left Margin Convention.) If you don't follow this convention, Font Lock mode can misfontify the text that follows an open-parenthesis or open-brace in the leftmost column that is inside a string or comment.

The variable font-lock-beginning-of-syntax-function (always buffer-local) specifies how Font Lock mode can find a position guaranteed to be outside any comment or string. In modes which use the leftmost column parenthesis convention, the default value of the variable is beginning-of-defun--that tells Font Lock mode to use the convention. If you set this variable to nil, Font Lock no longer relies on the convention. This avoids incorrect results, but the price is that, in some cases, fontification for a changed text must rescan buffer text from the beginning of the buffer. This can considerably slow down redisplay while scrolling, particularly if you are close to the end of a large buffer.

Font Lock highlighting patterns already exist for many modes, but you may want to fontify additional patterns. You can use the function font-lock-add-keywords, to add your own highlighting patterns for a particular mode. For example, to highlight `FIXME:' words in C comments, use this:

(font-lock-add-keywords
 'c-mode
 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))

To remove keywords from the font-lock highlighting patterns, use the function font-lock-remove-keywords. See (elisp)Search-based Fontification section `Search-based Fontification' in The Emacs Lisp Reference Manual, for documentation of the format of this list.

Fontifying large buffers can take a long time. To avoid large delays when a file is visited, Emacs fontifies only the visible portion of a buffer. As you scroll through the buffer, each portion that becomes visible is fontified as soon as it is displayed. The parts of the buffer that are not displayed are fontified "stealthily," in the background, i.e. when Emacs is idle. You can control this background fontification, also called Just-In-Time (or JIT) Lock, by customizing variables in the customization group `jit-lock'. See section Customizing Specific Items.

19.8 Interactive Highlighting

Use M-x highlight-changes-mode to enable (or disable) Highlight Changes mode, a minor mode that uses faces (colors, typically) to indicate which parts of the buffer were changed most recently.

Hi Lock mode highlights text that matches regular expressions you specify. For example, you might wish to see all the references to a certain variable in a program source file, highlight certain parts in a voluminous output of some program, or make certain names stand out in an article. Use the M-x hi-lock-mode command to enable (or disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use M-x global-hi-lock-mode or place (global-hi-lock-mode 1) in your `.emacs' file.

Hi Lock mode works like Font Lock mode (see section Font Lock mode), except that you specify explicitly the regular expressions to highlight. You control them with these commands:

C-x w h regexp RET face RET

Highlight text that matches regexp using face face (highlight-regexp). The highlighting will remain as long as the buffer is loaded. For example, to highlight all occurrences of the word "whim" using the default face (a yellow background) C-x w h whim RET RET. Any face can be used for highlighting, Hi Lock provides several of its own and these are pre-loaded into a history list. While being prompted for a face use M-p and M-n to cycle through them.

You can use this command multiple times, specifying various regular expressions to highlight in different ways.

C-x w r regexp RET

Unhighlight regexp (unhighlight-regexp).

If you invoke this from the menu, you select the expression to unhighlight from a list. If you invoke this from the keyboard, you use the minibuffer. It will show the most recently added regular expression; use M-p to show the next older expression and M-n to select the next newer expression. (You can also type the expression by hand, with completion.) When the expression you want to unhighlight appears in the minibuffer, press RET to exit the minibuffer and unhighlight it.

C-x w l regexp RET face RET

Highlight entire lines containing a match for regexp, using face face (highlight-lines-matching-regexp).

C-x w b

Insert all the current highlighting regexp/face pairs into the buffer at point, with comment delimiters to prevent them from changing your program. (This key binding runs the hi-lock-write-interactive-patterns command.)

These patterns are extracted from the comments, if appropriate, if you invoke M-x hi-lock-find-patterns, or if you visit the file while Hi Lock mode is enabled (since that runs hi-lock-find-patterns).

C-x w i

Extract regexp/face pairs from comments in the current buffer (hi-lock-find-patterns). Thus, you can enter patterns interactively with highlight-regexp, store them into the file with hi-lock-write-interactive-patterns, edit them (perhaps including different faces for different parenthesized parts of the match), and finally use this command (hi-lock-find-patterns) to have Hi Lock highlight the edited patterns.

The variable hi-lock-file-patterns-policy controls whether Hi Lock mode should automatically extract and highlight patterns found in a file when it is visited. Its value can be nil (never highlight), t (highlight the patterns), ask (query the user), or a function. If it is a function, hi-lock-find-patterns calls it with the patterns as argument; if the function returns non-nil, the patterns are used. The default is nil. Note that patterns are always highlighted if you call hi-lock-find-patterns directly, regardless of the value of this variable.

Also, hi-lock-find-patterns does nothing if the current major mode's symbol is a member of the list hi-lock-exclude-modes.

19.9 Window Fringes

On a graphical display, each Emacs window normally has narrow fringes on the left and right edges. The fringes display indications about the text in the window.

The most common use of the fringes is to indicate a continuation line, when one line of text is split into multiple lines on the screen. The left fringe shows a curving arrow for each screen line except the first, indicating that "this is not the real beginning." The right fringe shows a curving arrow for each screen line except the last, indicating that "this is not the real end."

The fringes indicate line truncation with short horizontal arrows meaning "there's more text on this line which is scrolled horizontally out of view;" clicking the mouse on one of the arrows scrolls the display horizontally in the direction of the arrow. The fringes can also indicate other things, such as empty lines, or where a program you are debugging is executing (see section Running Debuggers Under Emacs).

You can enable and disable the fringes for all frames using M-x fringe-mode. To enable and disable the fringes for the selected frame, use M-x set-fringe-style.

19.10 Displaying Boundaries

On a graphical display, Emacs can indicate the buffer boundaries in the fringes. It indicates the first line and the last line with angle images in the fringes. This can be combined with up and down arrow images which say whether it is possible to scroll the window up and down.

The buffer-local variable indicate-buffer-boundaries controls how the buffer boundaries and window scrolling is indicated in the fringes. If the value is left or right, both angle and arrow bitmaps are displayed in the left or right fringe, respectively.

If value is an alist, each element (indicator . position) specifies the position of one of the indicators. The indicator must be one of top, bottom, up, down, or t which specifies the default position for the indicators not present in the alist. The position is one of left, right, or nil which specifies not to show this indicator.

For example, ((top . left) (t . right)) places the top angle bitmap in left fringe, the bottom angle bitmap in right fringe, and both arrow bitmaps in right fringe. To show just the angle bitmaps in the left fringe, but no arrow bitmaps, use ((top . left) (bottom . left)).

The value of the variable default-indicate-buffer-boundaries is the default value for indicate-buffer-boundaries in buffers that do not override it.

19.11 Useless Whitespace

It is easy to leave unnecessary spaces at the end of a line, or empty lines at the end of a file, without realizing it. In most cases, this trailing whitespace has no effect, but there are special circumstances where it matters. It can also be a nuisance that the line has "changed," when the change is just spaces added or removed at the end.

You can make trailing whitespace at the end of a line visible on the screen by setting the buffer-local variable show-trailing-whitespace to t. Then Emacs displays trailing whitespace in the face trailing-whitespace.

This feature does not apply when point is at the end of the line containing the whitespace. Strictly speaking, that is "trailing whitespace" nonetheless, but displaying it specially in that case looks ugly while you are typing in new text. In this special case, the location of point is enough to show you that the spaces are present.

To delete all trailing whitespace within the current buffer's accessible portion (see section Narrowing), type M-x delete-trailing-whitespace RET. (This command does not remove the form-feed characters.)

Emacs can indicate unused lines at the end of the window with a small image in the left fringe (see section Window Fringes). The image appears for window lines that do not correspond to any buffer text. Blank lines at the end of the buffer then stand out because they do not have this image in the fringe.

To enable this feature, set the buffer-local variable indicate-empty-lines to a non-nil value. The default value of this variable is controlled by the variable default-indicate-empty-lines; by setting that variable, you can enable or disable this feature for all new buffers. (This feature currently doesn't work on text-only terminals.)

19.12 Selective Display

Emacs has the ability to hide lines indented more than a certain number of columns (you specify how many columns). You can use this to get an overview of a part of a program.

To hide lines in the current buffer, type C-x $ (set-selective-display) with a numeric argument n. Then lines with at least n columns of indentation disappear from the screen. The only indication of their presence is that three dots (`…') appear at the end of each visible line that is followed by one or more hidden ones.

The commands C-n and C-p move across the hidden lines as if they were not there.

The hidden lines are still present in the buffer, and most editing commands see them as usual, so you may find point in the middle of the hidden text. When this happens, the cursor appears at the end of the previous line, after the three dots. If point is at the end of the visible line, before the newline that ends it, the cursor appears before the three dots.

To make all lines visible again, type C-x $ with no argument.

If you set the variable selective-display-ellipses to nil, the three dots do not appear at the end of a line that precedes hidden lines. Then there is no visible indication of the hidden lines. This variable becomes local automatically when set.

See also Outline Mode for another way to hide part of the text in a buffer.

19.13 Optional Mode Line Features

The buffer percentage pos indicates the percentage of the buffer above the top of the window. You can additionally display the size of the buffer by typing M-x size-indication-mode to turn on Size Indication mode. The size will be displayed immediately following the buffer percentage like this:

POS of SIZE

Here SIZE is the human readable representation of the number of characters in the buffer, which means that `k' for 10^3, `M' for 10^6, `G' for 10^9, etc., are used to abbreviate.

If you have narrowed the buffer (see section Narrowing), the size of the accessible part of the buffer is shown.

The current line number of point appears in the mode line when Line Number mode is enabled. Use the command M-x line-number-mode to turn this mode on and off; normally it is on. The line number appears after the buffer percentage pos, with the letter `L' to indicate what it is. See section Minor Modes, for more information about minor modes and about how to use this command.

If you have narrowed the buffer (see section Narrowing), the displayed line number is relative to the accessible portion of the buffer. Thus, it isn't suitable as an argument to goto-line. (Use what-line command to see the line number relative to the whole file.)

If the buffer is very large (larger than the value of line-number-display-limit), then the line number doesn't appear. Emacs doesn't compute the line number when the buffer is large, because that would be too slow. Set it to nil to remove the limit.

Line-number computation can also be slow if the lines in the buffer are too long. For this reason, Emacs normally doesn't display line numbers if the average width, in characters, of lines near point is larger than the value of the variable line-number-display-limit-width. The default value is 200 characters.

You can also display the current column number by turning on Column Number mode. It displays the current column number preceded by the letter `C'. Type M-x column-number-mode to toggle this mode.

Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time or customize the option display-time-mode. The information added to the mode line usually appears after the buffer name, before the mode names and their parentheses. It looks like this:

hh:mmpm l.ll

Here hh and mm are the hour and minute, followed always by `am' or `pm'. l.ll is the average number of running processes in the whole system recently. (Some fields may be missing if your operating system cannot support them.) If you prefer time display in 24-hour format, set the variable display-time-24hr-format to t.

The word `Mail' appears after the load level if there is mail for you that you have not read yet. On a graphical display you can use an icon instead of `Mail' by customizing display-time-use-mail-icon; this may save some space on the mode line. You can customize display-time-mail-face to make the mail indicator prominent. Use display-time-mail-file to specify the mail file to check, or set display-time-mail-directory to specify the directory to check for incoming mail (any nonempty regular file in the directory is considered as "newly arrived mail").

By default, the mode line is drawn on graphics displays with 3D-style highlighting, like that of a button when it is not being pressed. If you don't like this effect, you can disable the 3D highlighting of the mode line, by customizing the attributes of the mode-line face. See section Customizing Faces.

By default, the mode line of nonselected windows is displayed in a different face, called mode-line-inactive. Only the selected window is displayed in the mode-line face. This helps show which window is selected. When the minibuffer is selected, since it has no mode line, the window from which you activated the minibuffer has its mode line displayed using mode-line; as a result, ordinary entry to the minibuffer does not change any mode lines.

You can disable use of mode-line-inactive by setting variable mode-line-in-non-selected-windows to nil; then all mode lines are displayed in the mode-line face.

You can customize the mode line display for each of the end-of-line formats by setting each of the variables eol-mnemonic-unix, eol-mnemonic-dos, eol-mnemonic-mac, and eol-mnemonic-undecided to the strings you prefer.

19.14 How Text Is Displayed

ASCII printing characters (octal codes 040 through 0176) in Emacs buffers are displayed with their graphics, as are non-ASCII multibyte printing characters (octal codes above 0400).

Some ASCII control characters are displayed in special ways. The newline character (octal code 012) is displayed by starting a new line. The tab character (octal code 011) is displayed by moving to the next tab stop column (normally every 8 columns).

Other ASCII control characters are normally displayed as a caret (`^') followed by the non-control version of the character; thus, control-A is displayed as `^A'. The caret appears in face escape-glyph.

Non-ASCII characters 0200 through 0237 (octal) are displayed with octal escape sequences; thus, character code 0230 (octal) is displayed as `\230'. The backslash appears in face escape-glyph.

If the variable ctl-arrow is nil, control characters in the buffer are displayed with octal escape sequences, except for newline and tab. Altering the value of ctl-arrow makes it local to the current buffer; until that time, the default value is in effect. The default is initially t.

The display of character codes 0240 through 0377 (octal) may be either as escape sequences or as graphics. They do not normally occur in multibyte buffers, but if they do, they are displayed as Latin-1 graphics. In unibyte mode, if you enable European display they are displayed using their graphics (assuming your terminal supports them), otherwise as escape sequences. See section Unibyte Editing Mode.

Some character sets define "no-break" versions of the space and hyphen characters, which are used where a line should not be broken. Emacs normally displays these characters with special faces (respectively, nobreak-space and escape-glyph) to distinguish them from ordinary spaces and hyphens. You can turn off this feature by setting the variable nobreak-char-display to nil. If you set the variable to any other value, that means to prefix these characters with an escape character.

Normally, a tab character in the buffer is displayed as whitespace which extends to the next display tab stop position, and display tab stops come at intervals equal to eight spaces. The number of spaces per tab is controlled by the variable tab-width, which is made local by changing it. Note that how the tab character in the buffer is displayed has nothing to do with the definition of TAB as a command. The variable tab-width must have an integer value between 1 and 1000, inclusive. The variable default-tab-width controls the default value of this variable for buffers where you have not set it locally.

You can customize the way any particular character code is displayed by means of a display table. See (elisp)Display Tables section `Display Tables' in The Emacs Lisp Reference Manual.

19.15 Displaying the Cursor

You can customize the cursor's color, and whether it blinks, using the cursor Custom group (see section Easy Customization Interface). On a graphical display, the command M-x blink-cursor-mode enables or disables the blinking of the cursor. (On text terminals, the terminal itself blinks the cursor, and Emacs has no control over it.) You can control how the cursor appears when it blinks off by setting the variable blink-cursor-alist.

Some text terminals offer two different cursors: the normal cursor and the very visible cursor, where the latter may be e.g. bigger or blinking. By default Emacs uses the very visible cursor, and switches to it when you start or resume Emacs. If the variable visible-cursor is nil when Emacs starts or resumes, it doesn't switch, so it uses the normal cursor.

Normally, the cursor appears in non-selected windows in the "off" state, with the same appearance as when the blinking cursor blinks "off." For a box cursor, this is a hollow box; for a bar cursor, this is a thinner bar. To turn off cursors in non-selected windows, customize the variable cursor-in-non-selected-windows and assign it a nil value.

On graphical displays, Emacs can optionally draw the block cursor as wide as the character under the cursor--for example, if the cursor is on a tab character, it would cover the full width occupied by that tab character. To enable this feature, set the variable x-stretch-cursor to a non-nil value.

To make the cursor even more visible, you can use HL Line mode, a minor mode that highlights the line containing point. Use M-x hl-line-mode to enable or disable it in the current buffer. M-x global-hl-line-mode enables or disables the same mode globally.

19.16 Truncation of Lines

As an alternative to continuation, Emacs can display long lines by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. On graphical displays, a small straight arrow in the fringe indicates truncation at either end of the line. On text-only terminals, `$' appears in the first column when there is text truncated to the left, and in the last column when there is text truncated to the right.

Horizontal scrolling automatically causes line truncation (see section Horizontal Scrolling). You can explicitly enable line truncation for a particular buffer with the command M-x toggle-truncate-lines. This works by locally changing the variable truncate-lines. If that variable is non-nil, long lines are truncated; if it is nil, they are continued onto multiple screen lines. Setting the variable truncate-lines in any way makes it local to the current buffer; until that time, the default value is in effect. The default value is normally nil.

If the variable truncate-partial-width-windows is non-nil, it forces truncation rather than continuation in any window less than the full width of the screen or frame, regardless of the value of truncate-lines. For information about side-by-side windows, see Splitting Windows. See also (elisp)Display section `Display' in The Emacs Lisp Reference Manual.

If the variable overflow-newline-into-fringe is non-nil on a graphical display, then Emacs does not continue or truncate a line which is exactly as wide as the window. Instead, the newline overflows into the right fringe, and the cursor appears in the fringe when positioned on that newline.

19.17 Customization of Display

This section describes variables (see section Variables) that you can change to customize how Emacs displays. Beginning users can skip it.

If the variable inverse-video is non-nil, Emacs attempts to invert all the lines of the display from what they normally are.

If the variable visible-bell is non-nil, Emacs attempts to make the whole screen blink when it would normally make an audible bell sound. This variable has no effect if your terminal does not have a way to make the screen blink.

The variable echo-keystrokes controls the echoing of multi-character keys; its value is the number of seconds of pause required to cause echoing to start, or zero, meaning don't echo at all. The value takes effect when there is someting to echo. See section The Echo Area.

The variable baud-rate holds the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations. On text-only terminals, it affects padding, and decisions about whether to scroll part of the screen or redraw it instead. It also affects the behavior of incremental search.

On graphical displays, baud-rate is only used to determine how frequently to look for pending input during display updating. A higher value of baud-rate means that check for pending input will be done less frequently.

On graphical display, Emacs can optionally display the mouse pointer in a special shape to say that Emacs is busy. To turn this feature on or off, customize the group cursor. You can also control the amount of time Emacs must remain busy before the busy indicator is displayed, by setting the variable hourglass-delay.

On graphical display, this variables specifies the vertical position of an overline above the text, including the height of the overline itself (1 pixel). The default value is 2 pixels.

On graphical display, Emacs normally draws an underline at the baseline level of the font. If x-underline-at-descent-line is non-nil, Emacs draws the underline at the same height as the font's descent line.

On some text-only terminals, bold face and inverse video together result in text that is hard to read. Call the function tty-suppress-bold-inverse-default-colors with a non-nil argument to suppress the effect of bold-face in this case.

On a text-only terminal, when you reenter Emacs after suspending, Emacs normally clears the screen and redraws the entire display. On some terminals with more than one page of memory, it is possible to arrange the termcap entry so that the `ti' and `te' strings (output to the terminal when Emacs is entered and exited, respectively) switch between pages of memory so as to use one page for Emacs and another page for other output. On such terminals, you might want to set the variable no-redraw-on-reenter non-nil; this tells Emacs to assume, when resumed, that the screen page it is using still contains what Emacs last wrote there.

This document was generated by Mark Kaminski on July, 3 2008 using texi2html 1.70.