@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997, 2000, 2001, 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Display, Search, Registers, Top
@chapter Controlling the Display
@menu
* Faces:: How to change the display style using faces.
+* Standard Faces:: Emacs' predefined faces.
* Font Lock:: Minor mode for syntactic highlighting using faces.
-* Highlight Changes:: Using colors to show where you changed the buffer.
* Highlight Interactively:: Tell Emacs what text to highlight.
+* Highlight Changes:: Using colors to show where you changed the buffer.
* Scrolling:: Moving text up and down in a window.
* Horizontal Scrolling:: Moving text left and right in a window.
* Fringes:: Enabling or disabling window fringes.
support colors. Character terminals generally do not support changing
the height and width or the font family.
+ The easiest way to use faces is to turn on Font Lock mode.
+@xref{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
+@code{ps-print-buffer-with-faces}. @xref{PostScript}.
+
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
lines too long or too short. We plan to address these issues in
future Emacs versions.
+@node Standard Faces
+@section Standard Faces
+
@findex list-faces-display
- 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. Here's a list of the standard defined
-faces:
+ 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.
+
+Here are the standard faces for specifying text appearance. You can
+use them on specific text, when you want the effects they produce.
@table @code
@item default
This face is used for ordinary text that doesn't specify any other face.
-@item mode-line
-This face is used for the mode line of the currently selected window.
-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. @xref{Display Custom}.
-@item mode-line-inactive
-Like @code{mode-line}, but used for mode lines of the windows other
-than the selected one (if @code{mode-line-in-non-selected-windows} is
-non-@code{nil}). This face inherits from @code{mode-line}, so changes
-in that face affect mode lines in all windows.
-@item header-line
-Similar to @code{mode-line} for a window's header line. Most modes
-don't use the header line, but the Info mode does.
-@item minibuffer-prompt
-This face is used for the prompt strings displayed in the minibuffer.
+@item 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.
+@item italic
+This face uses an italic variant of the default font, if it has one.
+@item bold-italic
+This face uses a bold italic variant of the default font, if it has one.
+@item underline
+This face underlines text.
+@item fixed-pitch
+This face forces use of a particular fixed-width font.
+@item variable-pitch
+This face forces use of a particular variable-width font. It's
+reasonable to customize this to use a different variable-width font,
+if you like, but you should not make it a fixed-width font.
+@item 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.
+@end table
+
+ 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.)
+
+@table @code
@item highlight
This face is used for highlighting portions of text, in various modes.
For example, mouse-sensitive text is highlighted using this face.
+@item mode-line-highlight
+Like @code{highlight}, but used for portions of text on mode lines.
@item isearch
This face is used for highlighting Isearch matches.
@item lazy-highlight
@item secondary-selection
This face is used for displaying a secondary X selection (@pxref{Secondary
Selection}).
-@item bold
-This face uses a bold variant of the default font, if it has one.
-@item italic
-This face uses an italic variant of the default font, if it has one.
-@item bold-italic
-This face uses a bold italic variant of the default font, if it has one.
-@item underline
-This face underlines text.
-@item fixed-pitch
-The basic fixed-pitch face.
+@item trailing-whitespace
+The face for highlighting excess spaces and tabs at the end of a line
+when @code{show-trailing-whitespace} is non-@code{nil}; see
+@ref{Useless Whitespace}.
+@item 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
+nobreak space or nobreak (soft) hyphen.
+@end table
+
+@cindex @code{region} face
+ When Transient Mark mode is enabled, the text of the region is
+highlighted when the mark is active. This uses the face named
+@code{region}; you can control the style of highlighting by changing the
+style of this face (@pxref{Face Customization}). @xref{Transient Mark},
+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.
+
+@table @code
+@item mode-line
+@itemx 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 window systems, and
+drawn as the inverse of the default face on non-windowed terminals.
+@code{modeline} is an alias for the @code{mode-line} face, for
+compatibility with old Emacs versions.
+@item mode-line-inactive
+Like @code{mode-line}, but used for mode lines of the windows other
+than the selected one (if @code{mode-line-in-non-selected-windows} is
+non-@code{nil}). This face inherits from @code{mode-line}, so changes
+in that face affect mode lines in all windows.
+@item header-line
+Similar to @code{mode-line} for a window's header line. Most modes
+don't use the header line, but some special modes, such the Info mode, do.
+@item vertical-border
+This face is used for the vertical divider between windows.
+By default this face inherits from the @code{mode-line-inactive} face
+on character terminals. On window systems the foreground color of
+this face is used for the vertical line between windows without
+scrollbars.
+@item minibuffer-prompt
+@cindex @code{minibuffer-prompt} face
+@vindex minibuffer-prompt-properties
+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.
@item fringe
-@cindex fringe
+@cindex @code{fringe} face
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.)
+@xref{Fringes}.
@item scroll-bar
This face determines the visual appearance of the scroll bar.
+@xref{Scroll Bars}.
@item border
This face determines the color of the frame border.
@item cursor
This face determines the color of the mouse pointer.
@item 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.
+colors of this face affect the appearance of tool bar icons. @xref{Tool Bars}.
@item tooltip
-This face is used for tooltips.
+This face is used for tooltips. @xref{Tooltips}.
@item 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.
-@item trailing-whitespace
-The face for highlighting trailing whitespace when
-@code{show-trailing-whitespace} is non-@code{nil}; see @ref{Useless
-Whitespace}.
-@item variable-pitch
-The basic variable-pitch face.
+@cindex menu bar appearance
+@cindex @code{menu} face, no effect if customized
+@cindex customization of @code{menu} face
+This face determines the colors and font of Emacs's menus. @xref{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 port are ignored by the respective GUI toolkits;
+you need to use system-wide styles and options to change the
+appearance of the menus.
@end table
-@cindex @code{region} face
- When Transient Mark mode is enabled, the text of the region is
-highlighted when the mark is active. This uses the face named
-@code{region}; you can control the style of highlighting by changing the
-style of this face (@pxref{Face Customization}). @xref{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. @xref{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 @code{ps-print-buffer-with-faces}.
-@xref{PostScript}.
-
@node Font Lock
@section Font Lock mode
@cindex Font Lock mode
specialized ways of assigning fonts for Font Lock mode.
@findex font-lock-mode
-@findex turn-on-font-lock
- The command @kbd{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 @code{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:
-
-@example
-(add-hook 'c-mode-hook 'turn-on-font-lock)
-@end example
+ 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 @kbd{M-x
+font-lock-mode}. Using a positive argument unconditionally turns Font
+Lock mode on, and a negative or zero argument turns it off.
@findex global-font-lock-mode
@vindex global-font-lock-mode
- To turn on Font Lock mode automatically in all modes which support
-it, customize the variable @code{global-font-lock-mode} or use the
-function @code{global-font-lock-mode} in your @file{.emacs} file, like
-this:
+ If you do not wish Font Lock mode to be turned on by default,
+customize the variable @code{global-font-lock-mode} using the Customize
+interface (@pxref{Easy Customization}), or use the function
+@code{global-font-lock-mode} in your @file{.emacs} file, like this:
@example
-(global-font-lock-mode 1)
+(global-font-lock-mode 0)
@end example
-@noindent
-You can also specify this using the menu bar Options menu, specifying
-first Syntax Highlighting and then Save Options.
+@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
+@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For
+example, to enable Font Lock mode for editing C files, you can do this:
+
+@example
+(add-hook 'c-mode-hook 'turn-on-font-lock)
+@end example
Font Lock mode uses several specifically named faces to do its job,
including @code{font-lock-string-face}, @code{font-lock-comment-face},
-and others. The easiest way to find them all is to use completion
-on the face name in @code{set-face-foreground}.
+and others. The easiest way to find them all is to use
+@kbd{M-x customize-group @key{RET} font-lock-faces @key{RET}}.
To change the colors or the fonts used by Font Lock mode to fontify
different parts of text, just change these faces. There are
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
+``stealthily,'' in the background, i.e.@: when Emacs is idle. You can
control this background fontification, also called @dfn{Just-In-Time}
(or @dfn{JIT}) Lock, by customizing variables in the customization
group @samp{jit-lock}. @xref{Specific Customization}.
-@node Highlight Changes
-@section Highlight Changes Mode
-
-@findex highlight-changes-mode
- Use @kbd{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.
-
@node Highlight Interactively
@section Interactive Highlighting by Matching
@cindex highlighting by matching
@cindex interactive highlighting
- 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.
+ It is sometimes useful to temporarily highlight text that
+matches a certain regular expression. 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.
@findex hi-lock-mode
Use the @kbd{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 (@pxref{Font Lock}),
-except that it lets you specify explicitly what parts of text to
-highlight. You control Hi-lock mode with these commands:
+allows you to interactively add and remove regular expressions
+specifying text to be highlighted. Hi Lock mode works like Font Lock
+mode (@pxref{Font Lock}), except that it lets you easily add and
+remove regular expressions while you are editing a buffer. 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.
+
+You control Hi Lock mode with these commands:
@table @kbd
@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w h
@findex highlight-regexp
-Highlight text that matches
-@var{regexp} using face @var{face} (@code{highlight-regexp}).
-By using this command more than once, you can highlight various
-parts of the text in different ways.
+Highlight text that matches @var{regexp} using face @var{face}
+(@code{highlight-regexp}). By using this command more than once, you
+can highlight various parts of the text in different ways. 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) @kbd{C-x w h whim @key{RET}
+@key{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 @kbd{M-p} and @kbd{M-n} to cycle through
+them.
@item C-x w r @var{regexp} @key{RET}
@kindex C-x w r
@findex unhighlight-regexp
-Unhighlight @var{regexp} (@code{unhighlight-regexp}). You must enter
-one of the regular expressions currently specified for highlighting.
-(You can use completion, or choose from a menu, to enter one of them
-conveniently.)
+Unhighlight @var{regexp} (@code{unhighlight-regexp}).
+When activated from the menu select the expression to unhighlight from
+a list. When activated from the keyboard the most recently added
+expression will be shown. Use @kbd{M-p} to show the next older
+expression and @kbd{M-n} to select the next newer expression. When
+the expression to unhighlight appears press @kbd{@key{RET}} to unhighlight
+it. The expression can also be typed and completion is available.
@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w l
@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 mode is enabled, or whenever you use the @kbd{M-x
hi-lock-find-patterns} command.
@item 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}). The list of pairs is
-found no matter where in the buffer it may be.
+(@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
+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.
This command does nothing if the major mode is a member of the list
@code{hi-lock-exclude-modes}.
@end table
+@node Highlight Changes
+@section Highlight Changes Mode
+
+@findex highlight-changes-mode
+ Use @kbd{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.
+
@node Scrolling
@section Scrolling
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 also indicate other things such as empty lines, or where a
+fringes can also indicate other things, such as empty lines, or where a
program you are debugging is executing (@pxref{Debuggers}).
@findex set-fringe-style
delete-trailing-whitespace @key{RET}}. (This command does not remove
the form-feed characters.)
-@vindex indicate-unused-lines
+@vindex indicate-empty-lines
@vindex default-indicate-empty-lines
@cindex unused lines
@cindex fringes, and unused line indication
this image in the fringe.
To enable this feature, set the buffer-local variable
-@code{indicate-unused-lines} to a non-@code{nil} value. The default
+@code{indicate-empty-lines} to a non-@code{nil} value. The default
value of this variable is controlled by the variable
-@code{default-indicate-unused-lines}; by setting that variable, you
+@code{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 character terminals.)
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 @kbd{C-x $} (@code{set-selective-display}) with a
-numeric argument @var{n}. Then lines with at least @var{n} columns of
-indentation disappear from the screen. The only indication of their
-presence is that three dots (@samp{@dots{}}) appear at the end of each
-visible line that is followed by one or more hidden ones.
+ To hide lines in the current buffer, type @kbd{C-x $}
+(@code{set-selective-display}) with a numeric argument @var{n}. Then
+lines with at least @var{n} columns of indentation disappear from the
+screen. The only indication of their presence is that three dots
+(@samp{@dots{}}) appear at the end of each visible line that is
+followed by one or more hidden ones.
The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
if they were not there.
them), otherwise as escape sequences. @xref{Single-Byte Character
Support}.
+@vindex nobreak-char-display
+@cindex no-break space, display
+@cindex no-break hyphen, display
+@cindex soft hyphen, display
+ 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, @code{nobreak-space} and @code{escape-glyph}) to
+distinguish them from ordinary spaces and hyphens. You can turn off
+this feature by setting the variable @code{nobreak-char-display} to
+@code{nil}. If you set the variable to any other value, that means to
+prefix these characters with an escape character.
+
@node Cursor Display
@section Displaying the Cursor
This section contains information for customization only. Beginning
users should skip it.
-@vindex mode-line-inverse-video
- The variable @code{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 @code{mode-line} face.
-@xref{Mode Line}. However, if @code{mode-line-inverse-video} has a
-value of @code{nil}, then the @code{mode-line} face will be ignored,
-and mode-lines will be drawn using the default text face.
-@xref{Faces}.
-
@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.
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{ni}
+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
that do not override it.
@vindex baud-rate
- The variable @code{baud-rate} holds the output speed of the
+ The variable @anchor{baud-rate}@code{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