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.

Using Multiple Typefaces
========================

When using Emacs with a window system, you can set up multiple styles of displaying characters.  Some of the aspects of style that you can control are the type font, the foreground color, the background color, and whether or not to underline text, and in which color.

Features which rely on text in multiple faces (such as Font Lock mode) will also work on non-windowed terminals that can display more than one face, whether by colors or underlining and emboldening.  This includes the console on GNU/Linux, an xterm which supports colors, the MS-DOS display (see MS-DOS), and the MS-Windows version invoked with the -nw option.  Emacs determines automatically whether the terminal has this capability.

The way you control display style is by defining named faces. Each face can specify various attributes, like the type font's height, weight and slant, foreground and background color, and underlining, but it does not have to specify all of them.  By specifying the face or faces to use for a given part of the text in the buffer, you control how that text appears.

The style of display used for a given character in the text is determined by combining several faces.  Any aspect of the display style that isn't specified by overlays or text properties comes from a default face which inherits its settings from the frame itself.

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

To alter the appearance of a face, use the customization buffer. See Face Customization.  You can also use X resources to specify attributes of particular faces (see Resources X).

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.

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.  Here's a list of the standardly defined faces:

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

mode-line
     This face is used for mode lines.  By default, it's drawn with shadows for a ``raised'' effect on window systems, and drawn as the inverse of the default face on non-windowed terminals.  See Display Custom.

header-line
     Similar to mode-line for a window's header line.  Most modes don't use the header line, but the Info mode does.

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 Isearch matches.

isearch-lazy-highlight-face
     This face is used for lazy highlighting of Isearch 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 Secondary Selection).

bold
     This face uses a bold variant of the default font, if it has 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
     The basic fixed-pitch face.

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.)

scroll-bar
     This face determines the visual appearance of the scroll bar.

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 is the basic tool-bar face.  No text appears in the tool bar, but the colors of this face affect the appearance of tool bar icons.

tooltip
     This face is used for tooltips.

menu
     This face determines the colors and font of Emacs's menus.  Setting the font of LessTif/Motif menus is currently not supported; attempts to set the font are ignored in this case.

trailing-whitespace
     The face for highlighting trailing whitespace when show-trailing-whitespace is non-nil.

variable-pitch
     The basic variable-pitch face.

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 Face Customization).  See Transient Mark, for more information about Transient Mark mode and activation and deactivation of the mark.

One easy way to use faces is to turn on Font Lock mode.  This minor mode, which is always local to a particular buffer, arranges to choose faces according to the syntax of the text you are editing.  It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs.  See Font Lock, for more information about Font Lock mode and syntactic highlighting.

You can print out the buffer with the highlighting that appears on your screen using the command ps-print-buffer-with-faces. See PostScript.

Font Lock mode
==============

Font Lock mode is a minor mode, always local to a particular buffer, which highlights (or ``fontifies'') using various faces according to the syntax of the text you are editing.  It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs---for example, names of functions being defined or reserved keywords.

The command M-x font-lock-mode turns Font Lock mode on or off according to the argument, and toggles the mode when it has no argument. The function turn-on-font-lock unconditionally enables Font Lock mode.  This is useful in mode-hook functions.  For example, to enable Font Lock mode whenever you edit a C file, you can do this:

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

To turn on Font Lock mode automatically in all modes which support it, customize the user option global-font-lock-mode or use the function global-font-lock-mode in your .emacs file, like this:

     (global-font-lock-mode 1)

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 completion on the face name in set-face-foreground.

To change the colors or the fonts used by Font Lock mode to fontify different parts of text, just change these faces.  There are two ways to do it:

  * Invoke M-x set-face-foreground or M-x set-face-background to change the colors of a particular face used by Font Lock. See Faces.  The command M-x list-faces-display displays all the faces currently known to Emacs, including those used by Font Lock.

  * Customize the faces interactively with M-x customize-face, as described in Face Customization.

To get the full benefit of Font Lock mode, you need to choose a default font which has bold, italic, and bold-italic variants; or else you need to have a color or gray-scale screen.

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.  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 purposes of speed, some modes including C mode and Lisp mode rely on a special convention: an open-parenthesis in the leftmost column always defines the beginning of a defun, and is thus always outside any string or comment.  (see Defuns.)  If you don't follow this convention, then Font Lock mode can misfontify the text after an open-parenthesis in the leftmost column that is inside a string or comment.

The variable 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)))

Highlight Changes Mode
======================

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

Interactive Highlighting by Matching
====================================

It is sometimes useful to highlight the strings that match a certain regular expression.  For example, you might wish to see all the references to a certain variable in a program source file, or highlight certain parts in a voluminous output of some program, or make certain cliches stand out in an article.

Use the M-x hi-lock-mode command to turn on a minor mode that allows you to specify regular expressions of the text to be highlighted.  Hi-lock mode works like Font Lock (see Font Lock), except that it lets you specify explicitly what parts of text to highlight.  You control Hi-lock mode with these commands:

C-x w h REGEXP RET FACE RET
     Highlight text that matches REGEXP using face FACE (highlight-regexp). By using this command more than once, you can highlight various parts of the text in different ways.

C-x w r REGEXP RET
     Unhighlight REGEXP (unhighlight-regexp).  You must enter one of the regular expressions currently specified for highlighting. (You can use completion, or a menu, to enter one of them conveniently.)

C-x w l REGEXP RET FACE RET
     Highlight 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 will be read the next time you visit the file while Hi-lock mode is enabled, or whenever you use the M-x hi-lock-find-patterns command.

C-x w i
     Re-read regexp/face pairs in the current buffer (hi-lock-write-interactive-patterns).  The list of pairs is found no matter where in the buffer it may be.

     This command does nothing if the major mode is a member of the list hi-lock-exclude-modes.

Trailing Whitespace
===================

It is easy to leave unnecessary spaces at the end of a line without realizing it.  In most cases, this trailing whitespace has no effect, but there are special circumstances where it matters.

You can make trailing whitespace visible on the screen by setting the variable show-trailing-whitespace to t.  Then Emacs displays trailing whitespace in the face trailing-whitespace.

Trailing whitespace is defined as spaces or tabs at the end of a line.  But trailing whitespace is not displayed specially if point is at the end of the line containing the whitespace.  (Doing that looks ugly while you are typing in new text, and the location of point is enough in that case to show you that the spaces are present.)

Emacs can indicate empty lines at the end of the buffer with a special bitmap on the left fringe of the window.  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.

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 means that text moves up, and new text appears at the bottom.  Scrolling backward 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 explicitly request scrolling 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
     Likewise, scroll forward.

M-v
     Scroll backward (scroll-down).

PRIOR
     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 clears the entire screen and redisplays all windows. In addition, it scrolls the selected window so that point is halfway down from the top of the window.

The scrolling commands C-v and M-v let you move all the text in the window up or down a few lines.  C-v (scroll-up) with an argument shows you that many more lines at the bottom of the window, moving the text and point up together as C-l might.  C-v with a negative argument shows you more lines at the top of the window. M-v (scroll-down) is like C-v, but moves in the opposite direction.  The function keys NEXT and PRIOR are equivalent to C-v and M-v.

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.

To read the buffer a windowful at a time, use C-v with no argument. It takes the last two lines at the bottom of the window and puts them at the top, followed by nearly a whole windowful of lines not previously visible.  If point was in the text scrolled off the top, it moves to the new top of the window.  M-v with no argument moves backward with overlap similarly.  The number of lines of overlap across a C-v or M-v is controlled by the variable next-screen-context-lines; by default, it is 2.

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.  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.  Just C-u as argument, as in C-u C-l, scrolls point to the center 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.

Scrolling happens automatically if point has moved out of the visible portion of the text when it is time to display.  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 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.

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.  Emacs does this automatically, in any window that uses line truncation rather than continuation: whenever point moves off the left or right edge of the screen, Emacs scrolls the buffer horizontally to make point visible.

When a window has been scrolled horizontally, text lines are truncated rather than continued (see Continuation Lines), with a $ appearing 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.

You can 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 scroll a window horizontally by hand, 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.

To disable automatic horizontal scrolling, set the variable automatic-hscrolling to nil.

Follow Mode
===========

Follow mode is a minor mode that makes two windows showing the same buffer scroll as one 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.

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, 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.

Optional Mode Line Features
===========================

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 before the buffer percentage POS, with the letter L to indicate what it is.  See Minor Modes, for more information about minor modes and about how to use this command.

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.  If you have narrowed the buffer (see Narrowing), the displayed line number is relative to the accessible portion of the buffer.

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.

By default, the mode line is drawn on graphics displays as a 3D released button.  Depending on the font used for the mode line's text, this might make the mode line use more space than a text line in a window, and cause the last line of the window be partially obscured. That is, the window displays a non-integral number of text lines.  If you don't like this effect, you can disable the 3D appearence of the mode line by customizing the attributes of the mode-line face in your .emacs init file, like this:

      (set-face-attribute 'mode-line nil :box nil)

Alternatively, you could turn off the box attribute in your .Xdefaults file:

      Emacs.mode-line.AttributeBox: off

How Text Is Displayed
=====================

ASCII printing characters (octal codes 040 through 0176) in Emacs buffers are displayed with their graphics.  So 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.

Non-ASCII characters 0200 through 0237 (octal) are displayed with octal escape sequences; thus, character code 0230 (octal) is displayed as \230.  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 Single-Byte Character Support.

Customization of Display
========================

This section contains information for customization only.  Beginning users should skip it.

The variable mode-line-inverse-video is an obsolete way of controlling whether the mode line is displayed in inverse video; the preferred way of doing this is to change the mode-line face. See Mode Line.  If you specify the foreground color for the mode-line face, and mode-line-inverse-video is non-nil, then the default background color for that face is the usual foreground color.  See Faces.

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.

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.  Then 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.

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.  See Echo Area.

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.  See Display Tables (The Emacs Lisp Reference Manual).

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, just like ctl-arrow.  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.

If the variable truncate-lines is non-nil, then each line of text gets just one screen line for display; if the text line is too long, display shows only the part that fits.  If truncate-lines is nil, then long text lines display as more than one screen line, enough to show the whole text of the line. See Continuation Lines.  Altering the value of truncate-lines makes it local to the current buffer; until that time, the default value is in effect.  The default is initially 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 Split Window.  See also Display (The Emacs Lisp Reference Manual).

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 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 window-systems, 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.

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

On a window system, 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.

Displaying the Cursor
=====================

There are a number of ways to customize the display of the cursor. M-x hl-line-mode enables or disables a global minor mode which highlights the line containing point.  On window systems, the command M-x blink-cursor-mode turns on or off the blinking of the cursor.  (On terminals, the terminal itself blinks the cursor, and Emacs has no control over it.)

You can customize the cursor's color, and whether it blinks, using the cursor Custom group (see Easy Customization).

When displaying on a window system, 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.

Normally, the cursor in non-selected windows is shown as a hollow box. To turn off cursor display in non-selected windows, customize the option cursor-in-non-selected-windows to assign it a nil value.