@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Display, Search, Registers, Top
@chapter 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.
+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.
@menu
-* Scrolling:: Moving text up and down in a window.
+* Scrolling:: Commands to move text up and down in a window.
+* Auto Scrolling:: Redisplay scrolls text automatically when needed.
* Horizontal Scrolling:: Moving text left and right in a window.
* Follow Mode:: Follow mode lets two windows scroll as one.
* Faces:: How to change the display style using faces.
* Font Lock:: Minor mode for syntactic highlighting using faces.
* Highlight Interactively:: Tell Emacs what text to highlight.
* Fringes:: Enabling or disabling window fringes.
+* Displaying Boundaries:: Displaying top and bottom of the buffer.
* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
* Text Display:: How text characters are normally displayed.
* Cursor Display:: Features for displaying the cursor.
+* Line Truncation:: Truncating lines to fit the screen width instead
+ of continuing them to multiple screen lines.
* Display Custom:: Information on variables for customizing display.
@end menu
@kindex PAGEUP
@findex scroll-up
@findex scroll-down
-@vindex next-screen-context-lines
To read the buffer a windowful at a time, use @kbd{C-v}
(@code{scroll-up}) with no argument. This scrolls forward by nearly
the whole window height. The effect is to take the two lines at the
was in the text that scrolled off the top, it ends up at the new top
of the window.
+@vindex next-screen-context-lines
@kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in
-a similar way, also with overlap. The number of lines of overlap
-across a @kbd{C-v} or @kbd{M-v} is controlled by the variable
-@code{next-screen-context-lines}; by default, it is 2. The function
-keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP},
-are equivalent to @kbd{C-v} and @kbd{M-v}.
+a similar way, also with overlap. The number of lines of overlap that
+the @kbd{C-v} or @kbd{M-v} commands leave is controlled by the
+variable @code{next-screen-context-lines}; by default, it is 2. The
+function keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and
+@key{PAGEUP}, are equivalent to @kbd{C-v} and @kbd{M-v}.
The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll
the text in the selected window up or down a few lines. @kbd{C-v}
Some users like the full-screen scroll commands to keep point at the
same screen line. To enable this behavior, set the variable
@code{scroll-preserve-screen-position} to a non-@code{nil} value. In
-this mode, when scrolling shifts point off the screen, or into the
-scrolling margins, Emacs moves 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.
+this mode, when these commands would scroll the text around point off
+the screen, or within @code{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 @kbd{C-l} with a numeric argument.
@kbd{C-l} does not clear the screen when given an argument; it only scrolls
the screen. For example, in a Lisp file, this command tries to get the
entire current defun onto the screen if possible.
+@node Auto Scrolling
+@section Automatic Scrolling
+
@vindex scroll-conservatively
- Scrolling happens automatically when point moves out of the visible
-portion of the text. Normally, automatic scrolling centers point
-vertically within the window. However, if you set
-@code{scroll-conservatively} to a small number @var{n}, then if you
-move point just a little off the screen---less than @var{n}
-lines---then Emacs scrolls the text just far enough to bring point
-back on screen. By default, @code{scroll-conservatively} is 0.
+ 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 @code{scroll-conservatively} to a small
+number @var{n}, then if you move point just a little off the
+screen---less than @var{n} lines---then Emacs scrolls the text just
+far enough to bring point back on screen. By default,
+@code{scroll-conservatively} is@tie{}0.
@cindex aggressive scrolling
@vindex scroll-up-aggressively
@dfn{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 (@pxref{Display
-Custom}). Whenever a window shows truncated lines, Emacs
+text lines are truncated rather than continued (@pxref{Line
+Truncation}). 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.
background colors for the current frame only; see @ref{Frame
Parameters}.)
+ If you want to alter the appearance of all Emacs frames, you need to
+customize the frame parameters in the variable
+@code{default-frame-alist}; see @ref{Creating Frames,
+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
To see what faces are currently defined, and what they look like,
type @kbd{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.
+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.
when @code{show-trailing-whitespace} is non-@code{nil}; see
@ref{Useless Whitespace}.
@item nobreak-space
-The face for displaying the character ``nobreak space''.
+The face for displaying the character ``nobreak space.''
@item escape-glyph
The face for highlighting the @samp{\} or @samp{^} that indicates
a control character. It's also used when @samp{\} indicates a
This face is used for the prompt strings displayed in the minibuffer.
By default, Emacs automatically adds this face to the value of
@code{minibuffer-prompt-properties}, which is a list of text
-properties used to display the prompt text.
+properties used to display the prompt text. (This variable takes
+effect when you enter the minibuffer.)
@item fringe
@cindex @code{fringe} face
The face for the fringes to the left and right of windows on graphic
(global-font-lock-mode 0)
@end example
+@noindent
+This variable, like all the variables that control Font Lock mode,
+take effect whenever fontification is done; that is, potentially at
+any time.
+
@findex turn-on-font-lock
If you have disabled Global Font Lock mode, you can still enable Font
Lock for specific major modes by adding the function
@cindex Hi Lock mode
@findex hi-lock-mode
- Hi Lock mode is another minor mode, which highlights text that
-matches your specified regular expressions. 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
-@kbd{M-x hi-lock-mode} command to enable (or disable) Hi Lock mode.
-To enable Hi Lock mode for all buffers, use @kbd{M-x
-global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)} in your
-@file{.emacs} file.
+ 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 @kbd{M-x hi-lock-mode} command to enable (or
+disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use
+@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)}
+in your @file{.emacs} file.
Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except
that you specify explicitly the regular expressions to highlight. You
program. (This key binding runs the
@code{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 @kbd{M-x
-hi-lock-find-patterns} command.
+These patterns are extracted from the comments, if appropriate, if you
+invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
+Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).
@item C-x w i
@kindex C-x w i
@findex hi-lock-find-patterns
-@vindex hi-lock-exclude-modes
-Re-read regexp/face pairs in the current buffer
-(@code{hi-lock-write-interactive-patterns}). Users familiar with Font
-Lock keywords might interactively enter patterns
-(@code{highlight-regexp}), write them into the file
-(@code{hi-lock-write-interactive-patterns}), edit them, perhaps
+Extract regexp/face pairs from comments in the current buffer
+(@code{hi-lock-find-patterns}). Thus, you can enter patterns
+interactively with @code{highlight-regexp}, store them into the file
+with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
including different faces for different parenthesized parts of the
-match, and finally use this command
-(@code{hi-lock-write-interactive-patterns}) to have Hi Lock highlight
-them.
+match), and finally use this command (@code{hi-lock-find-patterns}) to
+have Hi Lock highlight the edited patterns.
+
+@vindex hi-lock-file-patterns-policy
+The variable @code{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 @code{nil} (never
+highlight), @code{t} (highlight the patterns), @code{ask} (query the
+user), or a function. If it is a function,
+@code{hi-lock-find-patterns} calls it with the patterns as argument;
+if the function returns non-@code{nil}, the patterns are used. The
+default is @code{nil}. Note that patterns are always highlighted if
+you call @code{hi-lock-find-patterns} directly, regardless of the
+value of this variable.
-This command does nothing if the major mode is a member of the list
-@code{hi-lock-exclude-modes}.
+@vindex hi-lock-exclude-modes
+Also, @code{hi-lock-find-patterns} does nothing if the current major
+mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
@end table
@node Fringes
@kbd{M-x fringe-mode}. To enable and disable the fringes
for the selected frame, use @kbd{M-x set-fringe-style}.
+@node Displaying Boundaries
+@section Displaying Boundaries
+
+@vindex indicate-buffer-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 @code{indicate-buffer-boundaries} controls
+how the buffer boundaries and window scrolling is indicated in the
+fringes. If the value is @code{left} or @code{right}, both angle and
+arrow bitmaps are displayed in the left or right fringe, respectively.
+
+ If value is an alist, each element @code{(@var{indicator} .
+@var{position})} specifies the position of one of the indicators.
+The @var{indicator} must be one of @code{top}, @code{bottom},
+@code{up}, @code{down}, or @code{t} which specifies the default
+position for the indicators not present in the alist.
+The @var{position} is one of @code{left}, @code{right}, or @code{nil}
+which specifies not to show this indicator.
+
+ For example, @code{((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 @code{((top . left)
+(bottom . left))}.
+
+@vindex default-indicate-buffer-boundaries
+ The value of the variable @code{default-indicate-buffer-boundaries}
+is the default value for @code{indicate-buffer-boundaries} in buffers
+that do not override it.
+
@node Useless Whitespace
@section Useless Whitespace
Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
turn this mode on and off; normally it is on. The line number appears
after the buffer percentage @var{pos}, with the letter @samp{L} to
-indicate what it is. @xref{Minor Modes}, for more information about
-minor modes and about how to use this command.
+indicate what it is.
+
+@cindex Column Number mode
+@cindex mode, Column Number
+@findex column-number-mode
+ Similarly, you can display the current column number by turning on
+Column number mode with @kbd{M-x column-number-mode}. The column
+number is indicated by the letter @samp{C}. However, when both of
+these modes are enabled, the line and column numbers are displayed in
+parentheses, the line number first, rather than with @samp{L} and
+@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more
+information about minor modes and about how to use these commands.
@cindex narrowing, and line number display
If you have narrowed the buffer (@pxref{Narrowing}), the displayed
@code{line-number-display-limit-width}. The default value is 200
characters.
-@cindex Column Number mode
-@cindex mode, Column Number
-@findex column-number-mode
- You can also display the current column number by turning on Column
-Number mode. It displays the current column number preceded by the
-letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode.
-
@findex display-time
@cindex time (on mode line)
Emacs can optionally display the time and system load in all mode
@vindex visible-cursor
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. Setting the
-variable @code{visible-cursor} to @code{nil} makes it use the
-normal cursor.
+blinking. By default Emacs uses the very visible cursor, and switches
+to it when you start or resume Emacs. If the variable
+@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it
+doesn't switch, so it uses the normal cursor.
@cindex cursor in non-selected windows
@vindex cursor-in-non-selected-windows
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,
+``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 @code{cursor-in-non-selected-windows} and assign
it a @code{nil} value.
hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x
global-hl-line-mode} enables or disables the same mode globally.
-@node Display Custom
-@section Customization of Display
-
- This section describes variables (@pxref{Variables}) that you can
-change to customize how Emacs displays. Beginning users can skip
-it.
-@c the reason for that pxref is because an xref early in the
-@c ``echo area'' section leads here.
-
-@vindex inverse-video
- If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
-to invert all the lines of the display from what they normally are.
-
-@vindex visible-bell
- If the variable @code{visible-bell} is non-@code{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.
-
-@vindex echo-keystrokes
- The variable @code{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. @xref{Echo Area}.
+@node Line Truncation
+@section Truncation of Lines
@cindex truncation
@cindex line truncation, and fringes
newline overflows into the right fringe, and the cursor appears in the
fringe when positioned on that newline.
-@vindex indicate-buffer-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.
+@node Display Custom
+@section Customization of Display
- The buffer-local variable @code{indicate-buffer-boundaries} controls
-how the buffer boundaries and window scrolling is indicated in the
-fringes. If the value is @code{left} or @code{right}, both angle and
-arrow bitmaps are displayed in the left or right fringe, respectively.
+ This section describes variables (@pxref{Variables}) that you can
+change to customize how Emacs displays. Beginning users can skip
+it.
+@c the reason for that pxref is because an xref early in the
+@c ``echo area'' section leads here.
- If value is an alist, each element @code{(@var{indicator} .
-@var{position})} specifies the position of one of the indicators.
-The @var{indicator} must be one of @code{top}, @code{bottom},
-@code{up}, @code{down}, or @code{t} which specifies the default
-position for the indicators not present in the alist.
-The @var{position} is one of @code{left}, @code{right}, or @code{nil}
-which specifies not to show this indicator.
+@vindex inverse-video
+ If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
+to invert all the lines of the display from what they normally are.
- For example, @code{((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 @code{((top . left)
-(bottom . left))}.
+@vindex visible-bell
+ If the variable @code{visible-bell} is non-@code{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.
-@vindex default-indicate-buffer-boundaries
- The value of the variable @code{default-indicate-buffer-boundaries}
-is the default value for @code{indicate-buffer-boundaries} in buffers
-that do not override it.
+@vindex echo-keystrokes
+ The variable @code{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. @xref{Echo Area}.
@vindex baud-rate
The variable @anchor{baud-rate}@code{baud-rate} holds the output
amount of time Emacs must remain busy before the busy indicator is
displayed, by setting the variable @code{hourglass-delay}.
+@vindex overline-margin
+ 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.
+
+@vindex x-underline-at-descent-line
+ On graphical display, Emacs normally draws an underline at the
+baseline level of the font. If @code{x-underline-at-descent-line} is
+non-@code{nil}, Emacs draws the underline at the same height as the
+font's descent line.
+
@findex tty-suppress-bold-inverse-default-colors
On some text-only terminals, bold face and inverse video together
result in text that is hard to read. Call the function
the termcap entry so that the @samp{ti} and @samp{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
+page for other output. On such terminals, you might want to set the variable
@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
assume, when resumed, that the screen page it is using still contains
what Emacs last wrote there.
HCoop / bpt / emacs.git / blobdiff