@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
-@node Display, Calendar, Processes, Top
+@node Display, System Interface, Processes, Top
@chapter Emacs Display
This chapter describes a number of features related to the display
* Refresh Screen:: Clearing the screen and redrawing everything on it.
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
-* The Echo Area:: Where messages are displayed.
+* The Echo Area:: Displaying messages at the bottom of the screen.
* Warnings:: Displaying warning messages for the user.
-* Progress:: Informing user about progress of a long operation.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
-* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
-* Fringe Bitmaps:: Displaying bitmaps in the window fringes.
-* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
* Scroll Bars:: Controlling vertical scroll bars.
* Pointer Shape:: Controlling the mouse pointer shape.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Inverse Video:: Specifying how the screen looks.
* Usual Display:: The usual conventions for displaying nonprinting chars.
* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
@node Refresh Screen
@section Refreshing the Screen
-The function @code{redraw-frame} redisplays the entire contents of a
-given frame (@pxref{Frames}).
+ The function @code{redraw-frame} clears and redisplays the entire
+contents of a given frame (@pxref{Frames}). This is useful if the
+screen is corrupted.
@c Emacs 19 feature
@defun redraw-frame frame
This function clears and redisplays frame @var{frame}.
@end defun
-Even more powerful is @code{redraw-display}:
+ Even more powerful is @code{redraw-display}:
@deffn Command redraw-display
This function clears and redisplays all visible frames.
@end deffn
- This function forces certain windows to be redisplayed
-but does not clear them.
+ This function calls for redisplay of certain windows, the next time
+redisplay is done, but does not clear them first.
-@defun force-window-update object
+@defun force-window-update &optional object
This function forces redisplay of some or all windows. If
@var{object} is a window, it forces redisplay of that window. If
@var{object} is a buffer or buffer name, it forces redisplay of all
-windows displaying that buffer. If @var{object} is @code{nil}, it
-forces redisplay of all windows.
+windows displaying that buffer. If @var{object} is @code{nil} (or
+omitted), it forces redisplay of all windows.
@end defun
Processing user input takes absolute priority over redisplay. If you
@defvar redisplay-dont-pause
If this variable is non-@code{nil}, pending input does not
prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available. This feature is available
-as of Emacs 21.
+regardless of whether input is available.
@end defvar
You can request a display update, but only if no input is pending,
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
- On a windowed display, the @samp{$} and @samp{\} indicators are
-replaced with graphics bitmaps displayed in the window fringes
+ On a graphical display, the @samp{$} and @samp{\} indicators are
+replaced with arrow images displayed in the window fringes
(@pxref{Fringes}).
Note that continuation is different from filling; continuation happens
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
- You can override the glyphs that indicate continuation or truncation
-using the display table; see @ref{Display Tables}.
-
If your buffer contains @emph{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
redisplay slow. The column computation and indentation functions also
@cindex error display
@cindex echo area
-The @dfn{echo area} is used for displaying messages made with the
-@code{message} primitive, and for echoing keystrokes. It is not the
-same as the minibuffer, despite the fact that the minibuffer appears
-(when active) in the same place on the screen as the echo area. The
-@cite{GNU Emacs Manual} specifies the rules for resolving conflicts
-between the echo area and the minibuffer for use of that screen space
-(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
-Error messages appear in the echo area; see @ref{Errors}.
-
-You can write output in the echo area by using the Lisp printing
-functions with @code{t} as the stream (@pxref{Output Functions}), or as
-follows:
-
-@defun message string &rest arguments
-This function displays a message in the echo area. The
-argument @var{string} is similar to a C language @code{printf} control
-string. See @code{format} in @ref{String Conversion}, for the details
+ The @dfn{echo area} is used for displaying error messages
+(@pxref{Errors}), for messages made with the @code{message} primitive,
+and for echoing keystrokes. It is not the same as the minibuffer,
+despite the fact that the minibuffer appears (when active) in the same
+place on the screen as the echo area. The @cite{GNU Emacs Manual}
+specifies the rules for resolving conflicts between the echo area and
+the minibuffer for use of that screen space (@pxref{Minibuffer,, The
+Minibuffer, emacs, The GNU Emacs Manual}).
+
+ You can write output in the echo area by using the Lisp printing
+functions with @code{t} as the stream (@pxref{Output Functions}), or
+explicitly.
+
+@menu
+* Displaying Messages:: Explicitly displaying text in the echo area.
+* Progress:: Informing user about progress of a long operation.
+* Logging Messages:: Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+@end menu
+
+@node Displaying Messages
+@subsection Displaying Messages in the Echo Area
+
+ This section describes the functions for explicitly producing echo
+area messages. Many other Emacs features display messages there, too.
+
+@defun message format-string &rest arguments
+This function displays a message in the echo area. The argument
+@var{format-string} is similar to a C language @code{printf} format
+string. See @code{format} in @ref{Formatting Strings}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.
-If @var{string}, or strings among the @var{arguments}, have @code{face}
-text properties, these affect the way the message is displayed.
+If @var{format-string}, or strings among the @var{arguments}, have
+@code{face} text properties, these affect the way the message is displayed.
@c Emacs 19 feature
-If @var{string} is @code{nil}, @code{message} clears the echo area; if
-the echo area has been expanded automatically, this brings it back to
-its normal size. If the minibuffer is active, this brings the
-minibuffer contents back onto the screen immediately.
-
-@vindex message-truncate-lines
-Normally, displaying a long message resizes the echo area to display
-the entire message. But if the variable @code{message-truncate-lines}
-is non-@code{nil}, the echo area does not resize, and the message is
-truncated to fit it, as in Emacs 20 and before.
+If @var{format-string} is @code{nil} or the empty string,
+@code{message} clears the echo area; if the echo area has been
+expanded automatically, this brings it back to its normal size.
+If the minibuffer is active, this brings the minibuffer contents back
+onto the screen immediately.
@example
@group
@end example
To automatically display a message in the echo area or in a pop-buffer,
-depending on its size, use @code{display-message-or-buffer}.
+depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
@tindex with-temp-message
the previous echo area contents.
@end defmac
-@defun message-or-box string &rest arguments
+@defun message-or-box format-string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse---more precisely, if
@code{last-nonmenu-event} to a suitable value around the call.
@end defun
-@defun message-box string &rest arguments
+@defun message-box format-string &rest arguments
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
echo area, or @code{nil} if there is none.
@end defun
-@defvar cursor-in-echo-area
-This variable controls where the cursor appears when a message is
-displayed in the echo area. If it is non-@code{nil}, then the cursor
-appears at the end of the message. Otherwise, the cursor appears at
-point---not in the echo area at all.
+@node Progress
+@subsection Reporting Operation Progress
+@cindex progress reporting
-The value is normally @code{nil}; Lisp programs bind it to @code{t}
-for brief periods of time.
-@end defvar
+ When an operation can take a while to finish, you should inform the
+user about the progress it makes. This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
-@defvar echo-area-clear-hook
-This normal hook is run whenever the echo area is cleared---either by
-@code{(message nil)} or for any other reason.
-@end defvar
+ Functions listed in this section provide simple and efficient way of
+reporting operation progress. Here is a working example that does
+nothing useful:
+
+@smallexample
+(let ((progress-reporter
+ (make-progress-reporter "Collecting mana for Emacs..."
+ 0 500)))
+ (dotimes (k 500)
+ (sit-for 0.01)
+ (progress-reporter-update progress-reporter k))
+ (progress-reporter-done progress-reporter))
+@end smallexample
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates and returns a @dfn{progress reporter}---an
+object you will use as an argument for all other functions listed
+here. The idea is to precompute as much data as possible to make
+progress reporting very fast.
+
+When this progress reporter is subsequently used, it will display
+@var{message} in the echo area, followed by progress percentage.
+@var{message} is treated as a simple string. If you need it to depend
+on a filename, for instance, use @code{format} before calling this
+function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation. For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly. It is required that @var{max-value} is greater than
+@var{min-value}. If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument. But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates. Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints. It can be fractional. Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision. Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
-Almost all the messages displayed in the echo area are also recorded
-in the @samp{*Messages*} buffer.
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation. It displays the message of @var{reporter}, followed by
+progress percentage determined by @var{value}. If percentage is zero,
+or close enough according to the @var{min-change} and @var{min-time}
+arguments, then it is omitted from the output.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}. @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}. For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation. It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}. Optional @var{new-message} allows
+you to change the message of the @var{reporter}. Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished. It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
+@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above. It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+ (k 500)
+ "Collecting some mana for Emacs..."
+ (sit-for 0.01))
+@end example
+@end defmac
+
+@node Logging Messages
+@subsection Logging Messages in @samp{*Messages*}
+@cindex logging echo-area messages
+
+ Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer so that the user can refer back to
+them. This includes all the messages that are output with
+@code{message}.
@defopt message-log-max
This variable specifies how many lines to keep in the @samp{*Messages*}
@end example
@end defopt
+ To make @samp{*Messages*} more convenient for the user, the logging
+facility combines successive identical messages. It also combines
+successive related messages for the sake of two cases: question
+followed by answer, and a series of progress messages.
+
+ A ``question followed by an answer'' means two messages like the
+ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
+and the second is @samp{@var{question}...@var{answer}}. The first
+message conveys no additional information beyond what's in the second,
+so logging the second message discards the first from the log.
+
+ A ``series of progress messages'' means successive messages like
+those produced by @code{make-progress-reporter}. They have the form
+@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
+time, while @var{how-far} varies. Logging each message in the series
+discards the previous one, provided they are consecutive.
+
+ The functions @code{make-progress-reporter} and @code{y-or-n-p}
+don't have to do anything special to activate the message log
+combination feature. It operates whenever two consecutive messages
+are logged that share a common prefix ending in @samp{...}.
+
+@node Echo Area Customization
+@subsection Echo Area Customization
+
+ These variables control details of how the echo area works.
+
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area. If it is non-@code{nil}, then the cursor
+appears at the end of the message. Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
+@defvar echo-area-clear-hook
+This normal hook is run whenever the echo area is cleared---either by
+@code{(message nil)} or for any other reason.
+@end defvar
+
@defvar echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
If the value is zero, then command input is not echoed.
@end defvar
+@defvar message-truncate-lines
+Normally, displaying a long message resizes the echo area to display
+the entire message. But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
+@end defvar
+
+ The variable @code{max-mini-window-height}, which specifies the
+maximum height for resizing minibuffer windows, also applies to the
+echo area (which is really a special use of the minibuffer window.
+@xref{Minibuffer Misc}.
+
@node Warnings
@section Reporting Warnings
@cindex warnings
that warning is not logged.
@end defopt
-@node Progress
-@section Reporting Operation Progress
-@cindex progress reporting
-
-When an operation can take a while to finish, you should inform the
-user about the progress it makes. This way the user can estimate
-remaining time and clearly see that Emacs is busy working, not hung.
-
-Functions listed in this section provide simple and efficient way of
-reporting operation progress. Here is a working example that does
-nothing useful:
-
-@example
-(let ((progress-reporter
- (make-progress-reporter "Collecting some mana for Emacs..."
- 0 500)))
- (dotimes (k 500)
- (sit-for 0.01)
- (progress-reporter-update progress-reporter k))
- (progress-reporter-done progress-reporter))
-@end example
-
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates a progress reporter---the object you will use as
-an argument for all other functions listed here. The idea is to
-precompute as much data as possible to make progress reporting very
-fast.
-
-The @var{message} will be displayed in the echo area, followed by
-progress percentage. @var{message} is treated as a simple string. If
-you need it to depend on a filename, for instance, use @code{format}
-before calling this function.
-
-@var{min-value} and @var{max-value} arguments stand for starting and
-final states of your operation. For instance, if you scan a buffer,
-they should be the results of @code{point-min} and @code{point-max}
-correspondingly. It is required that @var{max-value} is greater than
-@var{min-value}. If you create progress reporter when some part of
-the operation has already been completed, then specify
-@var{current-value} argument. But normally you should omit it or set
-it to @code{nil}---it will default to @var{min-value} then.
-
-Remaining arguments control the rate of echo area updates. Progress
-reporter will wait for at least @var{min-change} more percents of the
-operation to be completed before printing next message.
-@var{min-time} specifies the minimum time in seconds to pass between
-successive prints. It can be fractional. Depending on Emacs and
-system capabilities, progress reporter may or may not respect this
-last argument or do it with varying precision. Default value for
-@var{min-change} is 1 (one percent), for @var{min-time}---0.2
-(seconds.)
-
-This function calls @code{progress-reporter-update}, so the first
-message is printed immediately.
-@end defun
-
-@defun progress-reporter-update reporter value
-This function does the main work of reporting progress of your
-operation. It print the message of @var{reporter} followed by
-progress percentage determined by @var{value}. If percentage is zero,
-then it is not printed at all.
-
-@var{reporter} must be the result of a call to
-@code{make-progress-reporter}. @var{value} specifies the current
-state of your operation and must be between @var{min-value} and
-@var{max-value} (inclusive) as passed to
-@code{make-progress-reporter}. For instance, if you scan a buffer,
-then @var{value} should be the result of a call to @code{point}.
-
-This function respects @var{min-change} and @var{min-time} as passed
-to @code{make-progress-reporter} and so does not output new messages
-on every invocation. It is thus very fast and normally you should not
-try to reduce the number of calls to it: resulting overhead will most
-likely negate your effort.
-@end defun
-
-@defun progress-reporter-force-update reporter value &optional new-message
-This function is similar to @code{progress-reporter-update} except
-that it prints a message in the echo area unconditionally.
-
-The first two arguments have the same meaning as for
-@code{progress-reporter-update}. Optional @var{new-message} allows
-you to change the message of the @var{reporter}. Since this functions
-always updates the echo area, such a change will be immediately
-presented to the user.
-@end defun
-
-@defun progress-reporter-done reporter
-This function should be called when the operation is finished. It
-prints the message of @var{reporter} followed by word ``done'' in the
-echo area.
-
-You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%.'' Firstly, it may
-never print it, there are many good reasons for this not to happen.
-Secondly, ``done'' is more explicit.
-@end defun
-
-@defmac dotimes-with-progress-reporter (var count [result]) message body...
-This is a convenience macro that works the same way as @code{dotimes}
-does, but also reports loop progress using the functions described
-above. It allows you to save some typing.
-
-You can rewrite the example in the beginning of this node using
-this macro this way:
-
-@example
-(dotimes-with-progress-reporter
- (k 500)
- "Collecting some mana for Emacs..."
- (sit-for 0.01))
-@end example
-@end defmac
-
@node Invisible Text
@section Invisible Text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
text property (@pxref{Text Properties}) or a property of an overlay
-(@pxref{Overlays}).
+(@pxref{Overlays}). Cursor motion also partly ignores these
+characters; if the command loop finds point within them, it moves
+point to the other side of them.
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
@defun add-to-invisibility-spec element
This function adds the element @var{element} to
-@code{buffer-invisibility-spec} (if it is not already present in that
-list). If @code{buffer-invisibility-spec} was @code{t}, it changes to
-a list, @code{(t)}, so that text whose @code{invisible} property
-is @code{t} remains invisible.
+@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
+was @code{t}, it changes to a list, @code{(t)}, so that text whose
+@code{invisible} property is @code{t} remains invisible.
@end defun
@defun remove-from-invisibility-spec element
Ordinarily, functions that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
explicitly ignore invisible newlines if
-@code{line-move-ignore-invisible} is non-@code{nil}, but only because
-they are explicitly programmed to do so.
+@code{line-move-ignore-invisible} is non-@code{nil} (the default), but
+only because they are explicitly programmed to do so.
- However, if a command ends with point inside or immediately after
+ However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
further backward (in the same direction that the command already moved
it) until that condition is no longer true. Thus, if the command
moved point back into an invisible range, Emacs moves point back to
-the beginning of that range, following the previous visible character.
-If the command moved point forward into an invisible range, Emacs
-moves point forward past the first visible character that follows the
-invisible text.
+the beginning of that range, and then back one more character. If the
+command moved point forward into an invisible range, Emacs moves point
+forward up to the first visible character that follows the invisible
+text.
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
- The first variant, explicit selective display, is designed for use in
-a Lisp program: it controls which lines are hidden by altering the text.
-The invisible text feature (@pxref{Invisible Text}) has partially
-replaced this feature.
+ The first variant, explicit selective display, is designed for use
+in a Lisp program: it controls which lines are hidden by altering the
+text. This kind of hiding in some ways resembles the effect of the
+@code{invisible} property (@pxref{Invisible Text}), but the two
+features are different and do not work the same way.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m). The text that
-was formerly a line following that newline is now invisible. Strictly
-speaking, it is temporarily no longer a line at all, since only newlines
-can separate lines; it is now part of the previous line.
+was formerly a line following that newline is now hidden. Strictly
+speaking, it is temporarily no longer a line at all, since only
+newlines can separate lines; it is now part of the previous line.
Selective display does not directly affect editing commands. For
-example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-@code{next-line} skips invisible lines, since it searches only for
-newlines. Modes that use selective display can also define commands
-that take account of the newlines, or that make parts of the text
-visible or invisible.
+example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
+into hidden text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For
+example, @code{next-line} skips hidden lines, since it searches only
+for newlines. Modes that use selective display can also define
+commands that take account of the newlines, or that control which
+parts of the text are hidden.
When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines. This means that when you next read
-in the file, it looks OK, with nothing invisible. The selective display
+in the file, it looks OK, with nothing hidden. The selective display
effect is seen only within Emacs.
@defvar selective-display
This buffer-local variable enables selective display. This means that
-lines, or portions of lines, may be made invisible.
+lines, or portions of lines, may be made hidden.
@itemize @bullet
@item
If the value of @code{selective-display} is @code{t}, then the character
-control-m marks the start of invisible text; the control-m, and the rest
+control-m marks the start of hidden text; the control-m, and the rest
of the line following it, are not displayed. This is explicit selective
display.
displayed.
@end itemize
-When some portion of a buffer is invisible, the vertical movement
+When some portion of a buffer is hidden, the vertical movement
commands operate as if that portion did not exist, allowing a single
-@code{next-line} command to skip any number of invisible lines.
+@code{next-line} command to skip any number of hidden lines.
However, character movement commands (such as @code{forward-char}) do
-not skip the invisible portion, and it is possible (if tricky) to insert
-or delete text in an invisible portion.
+not skip the hidden portion, and it is possible (if tricky) to insert
+or delete text in an hidden portion.
In the examples below, we show the @emph{display appearance} of the
buffer @code{foo}, which changes with the value of
@defvar selective-display-ellipses
If this buffer-local variable is non-@code{nil}, then Emacs displays
-@samp{@dots{}} at the end of a line that is followed by invisible text.
+@samp{@dots{}} at the end of a line that is followed by hidden text.
This example is a continuation of the previous one.
@example
(@samp{@dots{}}). @xref{Display Tables}.
@end defvar
-@node Overlay Arrow
-@section The Overlay Arrow
-@cindex overlay arrow
-
- The @dfn{overlay arrow} is useful for directing the user's attention
-to a particular line in a buffer. For example, in the modes used for
-interface to debuggers, the overlay arrow indicates the line of code
-about to be executed.
-
-@defvar overlay-arrow-string
-This variable holds the string to display to call attention to a
-particular line, or @code{nil} if the arrow feature is not in use.
-On a graphical display the contents of the string are ignored; instead a
-glyph is displayed in the fringe area to the left of the display area.
-@end defvar
-
-@defvar overlay-arrow-position
-This variable holds a marker that indicates where to display the overlay
-arrow. It should point at the beginning of a line. On a non-graphical
-display the arrow text
-appears at the beginning of that line, overlaying any text that would
-otherwise appear. Since the arrow is usually short, and the line
-usually begins with indentation, normally nothing significant is
-overwritten.
-
-The overlay string is displayed only in the buffer that this marker
-points into. Thus, only one buffer can have an overlay arrow at any
-given time.
-@c !!! overlay-arrow-position: but the overlay string may remain in the display
-@c of some other buffer until an update is required. This should be fixed
-@c now. Is it?
-@end defvar
-
- You can do a similar job by creating an overlay with a
-@code{before-string} property. @xref{Overlay Properties}.
-
@node Temporary Displays
@section Temporary Displays
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
-An overlays uses markers to record its beginning and end; thus,
+An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text. When you create the overlay,
you can specify whether text inserted at the beginning should be
inside the overlay or outside, and likewise for the end of the overlay.
@menu
+* Managing Overlays:: Creating and moving overlays.
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
-* Managing Overlays:: Creating and moving overlays.
* Finding Overlays:: Searching for overlays.
@end menu
+@node Managing Overlays
+@subsection Managing Overlays
+
+ This section describes the functions to create, delete and move
+overlays, and to examine their contents. Overlay changes are not
+recorded in the buffer's undo list, since the overlays are not
+part of the buffer's contents.
+
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
+@defun make-overlay start end &optional buffer front-advance rear-advance
+This function creates and returns an overlay that belongs to
+@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
+and @var{end} must specify buffer positions; they may be integers or
+markers. If @var{buffer} is omitted, the overlay is created in the
+current buffer.
+
+The arguments @var{front-advance} and @var{rear-advance} specify the
+marker insertion type for the start of the overlay and for the end of
+the overlay, respectively. @xref{Marker Insertion Types}. If they
+are both @code{nil}, the default, then the overlay extends to include
+any text inserted at the beginning, but not text inserted at the end.
+If @var{front-advance} is non-@code{nil}, text inserted at the
+beginning of the overlay is excluded from the overlay. If
+@var{rear-advance} is non-@code{nil}, text inserted at the end of the
+overlay is included in the overlay.
+@end defun
+
+@defun overlay-start overlay
+This function returns the position at which @var{overlay} starts,
+as an integer.
+@end defun
+
+@defun overlay-end overlay
+This function returns the position at which @var{overlay} ends,
+as an integer.
+@end defun
+
+@defun overlay-buffer overlay
+This function returns the buffer that @var{overlay} belongs to. It
+returns @code{nil} if @var{overlay} has been deleted.
+@end defun
+
+@defun delete-overlay overlay
+This function deletes @var{overlay}. The overlay continues to exist as
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
+
+A deleted overlay is not permanently disconnected. You can give it a
+position in a buffer again by calling @code{move-overlay}.
+@end defun
+
+@defun move-overlay overlay start end &optional buffer
+This function moves @var{overlay} to @var{buffer}, and places its bounds
+at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
+
+The return value is @var{overlay}.
+
+This is the only valid way to change the endpoints of an overlay. Do
+not try modifying the markers in the overlay by hand, as that fails to
+update other vital data structures and can cause some overlays to be
+``lost''.
+@end defun
+
+@defun remove-overlays &optional start end name value
+This function removes all the overlays between @var{start} and
+@var{end} whose property @var{name} has the value @var{value}. It can
+move the endpoints of the overlays in the region, or split them.
+
+If @var{name} is omitted or @code{nil}, it means to delete all overlays in
+the specified region. If @var{start} and/or @var{end} are omitted or
+@code{nil}, that means the beginning and end of the buffer respectively.
+Therefore, @code{(remove-overlays)} removes all the overlays in the
+current buffer.
+@end defun
+
+ Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+ @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 10
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+ @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+ @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+ @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+ @result{} 5
+(overlay-end foo)
+ @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+ @result{} nil
+;; @r{Verify it is deleted.}
+foo
+ @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+ @result{} nil
+(overlay-end foo)
+ @result{} nil
+(overlay-buffer foo)
+ @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+ @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 20
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay does not change its properties.}
+(overlay-get foo 'happy)
+ @result{} t
+@end example
+
@node Overlay Properties
@subsection Overlay Properties
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
-most respects they are different. Text properties are considered a part
-of the text; overlays are specifically considered not to be part of the
-text. Thus, copying text between various buffers and strings preserves
-text properties, but does not try to preserve overlays. Changing a
-buffer's text properties marks the buffer as modified, while moving an
-overlay or changing its properties does not. Unlike text property
-changes, overlay changes are not recorded in the buffer's undo list.
-@xref{Text Properties}, for comparison.
-
- These functions are used for reading and writing the properties of an
-overlay:
+most respects they are different. @xref{Text Properties}, for comparison.
+
+ Text properties are considered a part of the text; overlays and
+their properties are specifically considered not to be part of the
+text. Thus, copying text between various buffers and strings
+preserves text properties, but does not try to preserve overlays.
+Changing a buffer's text properties marks the buffer as modified,
+while moving an overlay or changing its properties does not. Unlike
+text property changes, overlay property changes are not recorded in
+the buffer's undo list.
+
+ These functions read and set the properties of an overlay:
@defun overlay-get overlay prop
This function returns the value of property @var{prop} recorded in
A face name (a symbol or string).
@item
-Starting in Emacs 21, a property list of face attributes. This has the
-form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
-face attribute name and @var{value} is a meaningful value for that
-attribute. With this feature, you do not need to create a face each
-time you want to specify a particular attribute for certain text.
-@xref{Face Attributes}.
+A property list of face attributes. This has the form (@var{keyword}
+@var{value} @dots{}), where each @var{keyword} is a face attribute
+name and @var{value} is a meaningful value for that attribute. With
+this feature, you do not need to create a face each time you want to
+specify a particular attribute for certain text. @xref{Face
+Attributes}.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
-@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+@code{(foreground-color . @var{color-name})} has the same effect as
+@code{(:foreground @var{color-name})}; likewise for the background.
@end itemize
@item mouse-face
@xref{Display Property}.
@item help-echo
-@kindex help-echo @r{(text property)}
+@kindex help-echo @r{(overlay property)}
If an overlay has a @code{help-echo} property, then when you move the
mouse onto the text in the overlay, Emacs displays a help string in the
echo area, or in the tooltip window. For details see @ref{Text
length is the number of characters deleted, and the post-change
beginning and end are equal.)
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called before and
property) rather than replacing it.
@end table
-@node Managing Overlays
-@subsection Managing Overlays
-
- This section describes the functions to create, delete and move
-overlays, and to examine their contents.
-
-@defun overlayp object
-This function returns @code{t} if @var{object} is an overlay.
-@end defun
-
-@defun make-overlay start end &optional buffer front-advance rear-advance
-This function creates and returns an overlay that belongs to
-@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
-and @var{end} must specify buffer positions; they may be integers or
-markers. If @var{buffer} is omitted, the overlay is created in the
-current buffer.
-
-The arguments @var{front-advance} and @var{rear-advance} specify the
-insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}. If
-@var{front-advance} is non-@code{nil}, text inserted at the beginning
-of the overlay is excluded from the overlay. If @var{read-advance} is
-non-@code{nil}, text inserted at the beginning of the overlay is
-included in the overlay.
-@end defun
-
-@defun overlay-start overlay
-This function returns the position at which @var{overlay} starts,
-as an integer.
-@end defun
-
-@defun overlay-end overlay
-This function returns the position at which @var{overlay} ends,
-as an integer.
-@end defun
-
-@defun overlay-buffer overlay
-This function returns the buffer that @var{overlay} belongs to.
-@end defun
-
-@defun delete-overlay overlay
-This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, and its property list is unchanged, but it ceases to be
-attached to the buffer it belonged to, and ceases to have any effect on
-display.
-
-A deleted overlay is not permanently disconnected. You can give it a
-position in a buffer again by calling @code{move-overlay}.
-@end defun
-
-@defun move-overlay overlay start end &optional buffer
-This function moves @var{overlay} to @var{buffer}, and places its bounds
-at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
-must specify buffer positions; they may be integers or markers.
-
-If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
-was already associated with; if @var{overlay} was deleted, it goes into
-the current buffer.
-
-The return value is @var{overlay}.
-
-This is the only valid way to change the endpoints of an overlay. Do
-not try modifying the markers in the overlay by hand, as that fails to
-update other vital data structures and can cause some overlays to be
-``lost''.
-@end defun
-
- Here are some examples:
-
-@example
-;; @r{Create an overlay.}
-(setq foo (make-overlay 1 10))
- @result{} #<overlay from 1 to 10 in display.texi>
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 10
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @r{Give it a property we can check later.}
-(overlay-put foo 'happy t)
- @result{} t
-;; @r{Verify the property is present.}
-(overlay-get foo 'happy)
- @result{} t
-;; @r{Move the overlay.}
-(move-overlay foo 5 20)
- @result{} #<overlay from 5 to 20 in display.texi>
-(overlay-start foo)
- @result{} 5
-(overlay-end foo)
- @result{} 20
-;; @r{Delete the overlay.}
-(delete-overlay foo)
- @result{} nil
-;; @r{Verify it is deleted.}
-foo
- @result{} #<overlay in no buffer>
-;; @r{A deleted overlay has no position.}
-(overlay-start foo)
- @result{} nil
-(overlay-end foo)
- @result{} nil
-(overlay-buffer foo)
- @result{} nil
-;; @r{Undelete the overlay.}
-(move-overlay foo 1 20)
- @result{} #<overlay from 1 to 20 in display.texi>
-;; @r{Verify the results.}
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 20
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @r{Moving and deleting the overlay does not change its properties.}
-(overlay-get foo 'happy)
- @result{} t
-@end example
-
@node Finding Overlays
@subsection Searching for Overlays
@defun next-overlay-change pos
This function returns the buffer position of the next beginning or end
-of an overlay, after @var{pos}.
+of an overlay, after @var{pos}. If there is none, it returns
+@code{(point-max)}.
@end defun
@defun previous-overlay-change pos
This function returns the buffer position of the previous beginning or
-end of an overlay, before @var{pos}.
+end of an overlay, before @var{pos}. If there is none, it returns
+@code{(point-min)}.
@end defun
- Here's an easy way to use @code{next-overlay-change} to search for the
-next character which gets a non-@code{nil} @code{happy} property from
+ Here's a function which uses @code{next-overlay-change} to search
+for the next character which gets a given property @code{prop} from
either its overlays or its text properties (@pxref{Property Search}):
@smallexample
(defun find-overlay-prop (prop)
(save-excursion
(while (and (not (eobp))
- (not (get-char-property (point) 'happy)))
+ (not (get-char-property (point) prop)))
(goto-char (min (next-overlay-change (point))
- (next-single-property-change (point) 'happy))))
+ (next-single-property-change (point) prop))))
(point)))
@end smallexample
+ Now you can search for a @code{happy} property like this:
+
+@smallexample
+(find-overlay-prop 'happy)
+@end smallexample
+
@node Width
@section Width
if it were displayed in the current buffer and the selected window.
@end defun
-@defun truncate-string-to-width string width &optional start-column padding
+@defun truncate-string-to-width string width &optional start-column padding ellipsis
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
+If @var{ellipsis} is non-@code{nil}, it should be a string which will
+replace the end of @var{str} (including any padding) if it extends
+beyond @var{end-column}, unless the display width of @var{str} is
+equal to or less than the display width of @var{ellipsis}. If
+@var{ellipsis} is non-@code{nil} and not a string, it stands for
+@code{"..."}.
+
@example
(truncate-string-to-width "\tab\t" 12 4)
@result{} "ab"
adding blank areas between the images.
If the property value is not @code{t}, it is a height spec. A height
-spec stands for a numeric height value; this heigh spec specifies the
+spec stands for a numeric height value; this height spec specifies the
actual line height, @var{line-height}. There are several ways to
write a height spec; here's how each of them translates into a numeric
height:
is @var{ratio} times the height of face @var{face}. @var{ratio} can
be any type of number, or @code{nil} which means a ratio of 1.
If @var{face} is @code{t}, it refers to the current face.
-@item (@code{nil} . @var{ratio})
+@item (nil . @var{ratio})
If the height spec is a cons of the format shown, the numeric height
is @var{ratio} times the height of the contents of the line.
@end table
the line to achieve the total height @var{line-height}. Otherwise,
@var{line-height} has no effect.
- If you don't specify the @code{line-height} propery, the line's
+ If you don't specify the @code{line-height} property, the line's
height consists of the contents' height plus the line spacing.
There are several ways to specify the line spacing for different
parts of Emacs text.
@vindex default-line-spacing
You can specify the line spacing for all lines in a frame with the
-@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
However, if the variable @code{default-line-spacing} is
non-@code{nil}, it overrides the frame's @code{line-spacing}
parameter. An integer value specifies the number of pixels put below
-lines on window systems. A floating point number specifies the
+lines on graphical displays. A floating point number specifies the
spacing relative to the frame's default line height.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines on window systems. A floating
+the number of pixels put below lines on graphical displays. A floating
point number specifies the spacing relative to the default frame line
height. This overrides line spacings specified for the frame.
A @dfn{face} is a named collection of graphical attributes: font
family, foreground color, background color, optional underlining, and
many others. Faces are used in Emacs to control the style of display of
-particular parts of the text or the frame.
+particular parts of the text or the frame. @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
+comes with.
@cindex face id
Each face has its own @dfn{face number}, which distinguishes faces at
low levels within Emacs. However, for most purposes, you refer to
-faces in Lisp programs by their names.
+faces in Lisp programs by the symbols that name them.
@defun facep object
-This function returns @code{t} if @var{object} is a face name symbol (or
-if it is a vector of the kind used internally to record face data). It
-returns @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a face name string
+or symbol (or if it is a vector of the kind used internally to record
+face data). It returns @code{nil} otherwise.
@end defun
Each face name is meaningful for all frames, and by default it has the
face name a special meaning in one frame if you wish.
@menu
-* Standard Faces:: The faces Emacs normally comes with.
* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
that handle a range of character sets.
@end menu
-@node Standard Faces
-@subsection Standard Faces
-
- This table lists all the standard faces and their uses. Most of them
-are used for displaying certain parts of the frames or certain kinds of
-text; you can control how those places look by customizing these faces.
-
-@table @code
-@item default
-@kindex default @r{(face name)}
-This face is used for ordinary text.
-
-@item mode-line
-@kindex mode-line @r{(face name)}
-This face is used for the mode line of the selected window, and for
-menu bars when toolkit menus are not used---but only if
-@code{mode-line-inverse-video} is non-@code{nil}.
-
-@item modeline
-@kindex modeline @r{(face name)}
-This is an alias for the @code{mode-line} face, for compatibility with
-old Emacs versions.
-
-@item mode-line-inactive
-@kindex mode-line-inactive @r{(face name)}
-This face is used for mode lines of non-selected windows.
-This face inherits from @code{mode-line}, so changes
-in that face affect all windows.
-
-@item header-line
-@kindex header-line @r{(face name)}
-This face is used for the header lines of windows that have them.
-
-@item menu
-This face controls the display of menus, both their colors and their
-font. (This works only on certain systems.)
-
-@item fringe
-@kindex fringe @r{(face name)}
-This face controls the default colors of window fringes, the thin areas on
-either side that are used to display continuation and truncation glyphs.
-
-@item minibuffer-prompt
-@kindex minibuffer-prompt @r{(face name)}
-@vindex minibuffer-prompt-properties
-This face is used for the text of minibuffer prompts. 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 scroll-bar
-@kindex scroll-bar @r{(face name)}
-This face controls the colors for display of scroll bars.
-
-@item tool-bar
-@kindex tool-bar @r{(face name)}
-This face is used for display of the tool bar, if any.
-
-@item region
-@kindex region @r{(face name)}
-This face is used for highlighting the region in Transient Mark mode.
-
-@item secondary-selection
-@kindex secondary-selection @r{(face name)}
-This face is used to show any secondary selection you have made.
-
-@item highlight
-@kindex highlight @r{(face name)}
-This face is meant to be used for highlighting for various purposes.
-
-@item trailing-whitespace
-@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line,
-if @code{show-trailing-whitespace} is non-@code{nil}.
-@end table
-
- In contrast, these faces are provided to change the appearance of text
-in specific ways. You can use them on specific text, when you want
-the effects they produce.
-
-@table @code
-@item bold
-@kindex bold @r{(face name)}
-This face uses a bold font, if possible. It uses the bold variant of
-the frame's 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
-@kindex italic @r{(face name)}
-This face uses the italic variant of the frame's font, if it has one.
-
-@item bold-italic
-@kindex bold-italic @r{(face name)}
-This face uses the bold italic variant of the frame's font, if it has
-one.
-
-@item underline
-@kindex underline @r{(face name)}
-This face underlines text.
-
-@item fixed-pitch
-@kindex fixed-pitch @r{(face name)}
-This face forces use of a particular fixed-width font.
-
-@item variable-pitch
-@kindex variable-pitch @r{(face name)}
-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.
-@end table
-
-@defvar show-trailing-whitespace
-@tindex show-trailing-whitespace
-If this variable is non-@code{nil}, Emacs uses the
-@code{trailing-whitespace} face to display any spaces and tabs at the
-end of a line.
-@end defvar
-
@node Defining Faces
@subsection Defining Faces
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
-@defmac defface face spec doc [keyword value]...
-This declares @var{face} as a customizable face that defaults according
-to @var{spec}. You should not quote the symbol @var{face}. The
+@defmac defface face spec doc [keyword value]@dots{}
+This declares @var{face} as a customizable face that defaults
+according to @var{spec}. You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant). The
argument @var{doc} specifies the face documentation. The keywords you
-can use in @code{defface} are the same ones that are meaningful in both
-@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+can use in @code{defface} are the same as in @code{defgroup} and
+@code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
-different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
-@var{display}, specifies a class of terminals. The element's second element,
-@var{atts}, is a list of face attributes and their values; it specifies
-what the face should look like on that kind of terminal. The possible
-attributes are defined in the value of @code{custom-face-attributes}.
+different kinds of terminals. It should be an alist whose elements
+have the form @code{(@var{display} @var{atts})}. Each element's
+@sc{car}, @var{display}, specifies a class of terminals. (The first
+element, if its @sc{car} is @code{default}, is special---it specifies
+defaults for the remaining elements). The element's @sc{cadr},
+@var{atts}, is a list of face attributes and their values; it
+specifies what the face should look like on that kind of terminal.
+The possible attributes are defined in the value of
+@code{custom-face-attributes}.
The @var{display} part of an element of @var{spec} determines which
-frames the element applies to. If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame. There are two possibilities for @var{display}:
+frames the element matches. If more than one element of @var{spec}
+matches a given frame, the first element that matches is the one used
+for that frame. There are three possibilities for @var{display}:
@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any frames; instead, it
+specifies defaults that apply to all frames. This kind of element, if
+used, must be the first element of @var{spec}. Each of the following
+elements can override any or all of these defaults.
+
@item @code{t}
This element of @var{spec} matches all frames. Therefore, any
subsequent elements of @var{spec} are never used. Normally
The kind of background---either @code{light} or @code{dark}.
@item min-colors
-An integer that represents the minimum number of colors the frame should
-support, it is compared with the result of @code{display-color-cells}.
+An integer that represents the minimum number of colors the frame
+should support. This matches a frame if its
+@code{display-color-cells} value is at least the specified integer.
@item supports
Whether or not the frame can display the face attributes given in
Internally, @code{defface} uses the symbol property
@code{face-defface-spec} to record the face attributes specified in
@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
+with the customization buffer, @code{customized-face} for the
+attributes customized by the user for the current session, but not
+saved, and @code{face-documentation} for the documentation string.
@defopt frame-background-mode
This option, if non-@code{nil}, specifies the background type to use for
given piece of text; when that happens, the attributes of all the faces
are merged to specify how to display the text. @xref{Displaying Faces}.
- In Emacs 21, any attribute in a face can have the value
-@code{unspecified}. This means the face doesn't specify that attribute.
-In face merging, when the first face fails to specify a particular
-attribute, that means the next face gets a chance. However, the
-@code{default} face must specify all attributes.
+ Any attribute in a face can have the value @code{unspecified}. This
+means the face doesn't specify that attribute. In face merging, when
+the first face fails to specify a particular attribute, that means the
+next face gets a chance. However, the @code{default} face must
+specify all attributes.
Some of these font attributes are meaningful only on certain kinds of
displays---if your display cannot handle a certain attribute, the
The name of a face from which to inherit attributes, or a list of face
names. Attributes from inherited faces are merged into the face like an
underlying face would be, with higher priority than underlying faces.
+If a list of faces is used, attributes from faces earlier in the list
+override those from later faces.
@item :box
Whether or not a box should be drawn around characters, its color, the
is used.
@end table
- The attributes @code{:overline}, @code{:strike-through} and
-@code{:box} are new in Emacs 21. The attributes @code{:family},
-@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
-new; previous versions used the following attributes, now semi-obsolete,
-to specify some of the same information:
+ In older versions of Emacs, before @code{:family}, @code{:height},
+@code{:width}, @code{:weight}, and @code{:slant} existed, these
+attributes were used to specify the type face. They are now
+semi-obsolete, but they still work:
@table @code
@item :font
A non-@code{nil} value specifies an italic font.
@end table
- For compatibility, you can still set these ``attributes'' in Emacs 21,
-even though they are not real face attributes. Here is what that does:
+ For compatibility, you can still set these ``attributes'', even
+though they are not real face attributes. Here is what that does:
@table @code
@item :font
@end defun
@defun set-face-font face font &optional frame
-This function sets the font of face @var{face}.
-
-In Emacs 21, this actually sets the attributes @code{:family},
-@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
-according to the font name @var{font}.
-
-In Emacs 20, this sets the font attribute. Once you set the font
-explicitly, the bold and italic attributes cease to have any effect,
-because the precise font that you specified is used.
+This function sets the font of face @var{face}. This actually sets
+the attributes @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} according to the font name
+@var{font}.
@end defun
@defun set-face-bold-p face bold-p &optional frame
This function specifies whether @var{face} should be bold. If
@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
-
-In Emacs 21, this sets the @code{:weight} attribute.
-In Emacs 20, it sets the @code{:bold} attribute.
+This actually sets the @code{:weight} attribute.
@end defun
@defun set-face-italic-p face italic-p &optional frame
This function specifies whether @var{face} should be italic. If
@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
-
-In Emacs 21, this sets the @code{:slant} attribute.
-In Emacs 20, it sets the @code{:italic} attribute.
+This actually sets the @code{:slant} attribute.
@end defun
@defun set-face-underline-p face underline-p &optional frame
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
+@defun set-face-inverse-video-p face inverse-video-p &optional frame
+This function sets the @code{:inverse-video} attribute of face
+@var{face}.
+@end defun
+
@defun invert-face face &optional frame
-This function inverts the @code{:inverse-video} attribute of face
-@var{face}. If the attribute is @code{nil}, this function sets it to
-@code{t}, and vice versa.
+This function swaps the foreground and background colors of face
+@var{face}.
@end defun
These functions examine the attributes of a face. If you don't
value for that attribute.
@defun face-foreground face &optional frame inherit
-@defunx face-background face &optional frame
+@defunx face-background face &optional frame inherit
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
default for all text. (In Emacs 19 and 20, the @code{default}
face is used only when no other face is specified.)
-For a mode line or header line, the face @code{modeline} or
-@code{header-line} is used just before @code{default}.
+@item
+For a mode line or header line, the face @code{mode-line} or
+@code{mode-line-inactive}, or @code{header-line}, is merged in just
+before @code{default}.
@item
With text properties. A character can have a @code{face} property; if
@item
With a region that is active. In Transient Mark mode, the region is
-highlighted with the face @code{region} (@pxref{Standard Faces}).
+highlighted with the face @code{region} (@pxref{Standard Faces,,,
+emacs, The GNU Emacs Manual}).
@item
With special glyphs. Each glyph can specify a particular face
If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
-specified. The attributes of the faces of special glyphs come first;
-then comes the face for region highlighting, if appropriate;
-then come attributes of faces from overlays, followed by those from text
-properties, and last the default face.
+specified. For each attribute, Emacs tries first the face of any
+special glyph; then the face for region highlighting, if appropriate;
+then the faces specified by overlays, followed by those specified by
+text properties, then the @code{mode-line} or
+@code{mode-line-inactive} or @code{header-line} face (if in a mode
+line or a header line), and last the @code{default} face.
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
- In Emacs 20, if an attribute such as the font or a color is not
-specified in any of the above ways, the frame's own font or color is
-used. In newer Emacs versions, this cannot happen, because the
-@code{default} face specifies all attributes---in fact, the frame's own
-font and colors are synonymous with those of the default face.
-
@node Font Selection
@subsection Font Selection
@end defun
@defun copy-face old-face new-name &optional frame new-frame
-This function defines the face @var{new-name} as a copy of the existing
+This function defines a face named @var{new-name} as a copy of the existing
face named @var{old-face}. It creates the face @var{new-name} if that
doesn't already exist.
differently from the default face.
@end defun
+@cindex face alias
+A @dfn{face alias} provides an equivalent name for a face. You can
+define a face alias by giving the alias symbol the @code{face-alias}
+property, with a value of the target face name. The following example
+makes @code{modeline} an alias for the @code{mode-line} face.
+
+@example
+(put 'modeline 'face-alias 'mode-line)
+@end example
+
+
@node Auto Faces
@subsection Automatic Face Assignment
@cindex automatic face assignment
@cindex faces, automatic choice
@cindex Font-Lock mode
- Starting with Emacs 21, a hook is available for automatically
-assigning faces to text in the buffer. This hook is used for part of
-the implementation of Font-Lock mode.
+ This hook is used for automatically assigning faces to text in the
+buffer. It is part of the implementation of Font-Lock mode.
@tindex fontification-functions
@defvar fontification-functions
many fonts match the pattern.
@end defun
- These additional functions are available starting in Emacs 21.
-
@defun x-family-fonts &optional family frame
@tindex x-family-fonts
This function returns a list describing the available fonts for family
registry name is @samp{JISX0208.1983} for all characters belonging to
the charset @code{japanese-jisx0208}.
-@example
-(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
-@end example
+@smallexample
+(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+@end smallexample
+@end defun
+
+@defun char-displayable-p char
+This function returns @code{t} if Emacs ought to be able to display
+@var{char}. More precisely, if the selected frame's fontset has a
+font to display the character set that @var{char} belongs to.
+
+Fontsets can specify a font on a per-character basis; when the fontset
+does that, this function's value may not be accurate.
+@end defun
+
+@node Fringes
+@section Fringes
+@cindex Fringes
+
+ The @dfn{fringes} of a window are thin vertical strips down the
+sides that are used for displaying bitmaps that indicate truncation,
+continuation, horizontal scrolling, and the overlay arrow.
+
+@menu
+* Fringe Size/Pos:: Specifying where to put the window fringes.
+* Fringe Indicators:: Displaying indicator icons in the window fringes.
+* Fringe Cursors:: Displaying cursors in the right fringe.
+* Fringe Bitmaps:: Specifying bitmaps for fringe indicators.
+* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
+* Overlay Arrow:: Display of an arrow to indicate position.
+@end menu
+
+@node Fringe Size/Pos
+@subsection Fringe Size and Position
+
+ The following buffer-local variables control the position and width
+of the window fringes.
+
+@defvar fringes-outside-margins
+The fringes normally appear between the display margins and the window
+text. If the value is non-@code{nil}, they appear outside the display
+margins. @xref{Display Margins}.
+@end defvar
+
+@defvar left-fringe-width
+This variable, if non-@code{nil}, specifies the width of the left
+fringe in pixels. A value of @code{nil} means to use the left fringe
+width from the window's frame.
+@end defvar
+
+@defvar right-fringe-width
+This variable, if non-@code{nil}, specifies the width of the right
+fringe in pixels. A value of @code{nil} means to use the right fringe
+width from the window's frame.
+@end defvar
+
+ The values of these variables take effect when you display the
+buffer in a window. If you change them while the buffer is visible,
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
+
+@defun set-window-fringes window left &optional right outside-margins
+This function sets the fringe widths of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
+
+The argument @var{left} specifies the width in pixels of the left
+fringe, and likewise @var{right} for the right fringe. A value of
+@code{nil} for either one stands for the default width. If
+@var{outside-margins} is non-@code{nil}, that specifies that fringes
+should appear outside of the display margins.
+@end defun
+
+@defun window-fringes &optional window
+This function returns information about the fringes of a window
+@var{window}. If @var{window} is omitted or @code{nil}, the selected
+window is used. The value has the form @code{(@var{left-width}
+@var{right-width} @var{outside-margins})}.
+@end defun
+
+
+@node Fringe Indicators
+@subsection Fringe Indicators
+@cindex fringe indicators
+@cindex indicators, fringe
+
+ The @dfn{fringe indicators} are tiny icons Emacs displays in the
+window fringe (on a graphic display) to indicate truncated or
+continued lines, buffer boundaries, overlay arrow, etc.
+
+@defopt indicate-empty-lines
+@tindex indicate-empty-lines
+@cindex fringes, and empty line indication
+When this is non-@code{nil}, Emacs displays a special glyph in the
+fringe of each empty line at the end of the buffer, on graphical
+displays. @xref{Fringes}. This variable is automatically
+buffer-local in every buffer.
+@end defopt
+
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling are indicated in the window fringes.
+
+Emacs can indicate the buffer boundaries---that is, the first and last
+line in the buffer---with angle icons when they appear on the screen.
+In addition, Emacs can display an up-arrow in the fringe to show
+that there is text above the screen, and a down-arrow to show
+there is text below the screen.
+
+There are four kinds of basic values:
+
+@table @asis
+@item @code{nil}
+Don't display the icons.
+@item @code{left}
+Display them in the left fringe.
+@item @code{right}
+Display them in the right fringe.
+@item @var{anything-else}
+Display the icon at the top of the window top in the left fringe, and other
+in the right fringe.
+@end table
+
+If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
+controls the angle icons, and @var{arrows} controls the arrows. Both
+@var{angles} and @var{arrows} work according to the table above.
+Thus, @code{(t . right)} places the top angle icon in the left
+fringe, the bottom angle icon in the right fringe, and both arrows in
+the right fringe.
+@end defvar
+
+@defvar default-indicate-buffer-boundaries
+The value of this variable is the default value for
+@code{indicate-buffer-boundaries} in buffers that do not override it.
+@end defvar
+
+@defvar fringe-indicator-alist
+This buffer-local variable specifies the mapping from logical fringe
+indicators to the actual bitmaps displayed in the window fringes.
+
+These symbols identify the logical fringe indicators:
+
+@table @asis
+@item Truncation and continuation line indicators:
+@code{truncation}, @code{continuation}.
+
+@item Buffer position indicators:
+@code{up}, @code{down},
+@code{top}, @code{bottom},
+@code{top-bottom}.
+
+@item Empty line indicator:
+@code{empty-line}.
-@end defun
+@item Overlay arrow indicator:
+@code{overlay-arrow}.
-@defun char-displayable-p char
-This function returns @code{t} if Emacs ought to be able to display
-@var{char}. More precisely, if the selected frame's fontset has a
-font to display the character set that @var{char} belongs to.
+@item Unknown bitmap indicator:
+@code{unknown}.
+@end table
-Fontsets can specify a font on a per-character basis; when the fontset
-does that, this function's value may not be accurate.
-@end defun
+ The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
+specifies the fringe bitmaps used to display a specific logical
+fringe indicator.
-@node Fringes
-@section Fringes
-@cindex Fringes
+Here, @var{indicator} specifies the logical indicator type, and
+@var{bitmaps} is list of symbols @code{(@var{left} @var{right}
+[@var{left1} @var{right1}])} which specifies the actual bitmap shown
+in the left or right fringe for the logical indicator.
- The @dfn{fringes} of a window are thin vertical strips down the
-sides that are used for displaying bitmaps that indicate truncation,
-continuation, horizontal scrolling, and the overlay arrow. The
-fringes normally appear between the display margins and the window
-text, but you can put them outside the display margins for a specific
-buffer by setting @code{fringes-outside-margins} buffer-locally to a
-non-@code{nil} value.
+The @var{left} and @var{right} symbols specify the bitmaps shown in
+the left and/or right fringe for the specific indicator. The
+@var{left1} or @var{right1} bitmaps are used only for the `bottom' and
+`top-bottom indicators when the last (only) line in has no final
+newline. Alternatively, @var{bitmaps} may be a single symbol which is
+used in both left and right fringes.
-@defvar fringes-outside-margins
-If the value is non-@code{nil}, the frames appear outside
-the display margins.
-@end defvar
+When @code{fringe-indicator-alist} has a buffer-local value, and there
+is no bitmap defined for a logical indicator, or the bitmap is
+@code{t}, the corresponding value from the (non-local)
+@code{default-fringe-indicator-alist} is used.
-@defvar left-fringe-width
-This variable, if non-@code{nil}, specifies the width of the left
-fringe in pixels.
+To completely hide a specific indicator, set the bitmap to @code{nil}.
@end defvar
-@defvar right-fringe-width
-This variable, if non-@code{nil}, specifies the width of the right
-fringe in pixels.
+@defvar default-fringe-indicator-alist
+The value of this variable is the default value for
+@code{fringe-indicator-alist} in buffers that do not override it.
@end defvar
- The values of these variables take effect when you display the
-buffer in a window. If you change them while the buffer is visible,
-you can call @code{set-window-buffer} to display it once again in the
-same window, to make the changes take effect.
+@table @asis
+@item Standard fringe bitmaps for indicators:
+@code{left-arrow}, @code{right-arrow}, @code{up-arrow}, @code{down-arrow},
+@code{left-curly-arrow}, @code{right-curly-arrow},
+@code{left-triangle}, @code{right-triangle},
+@code{top-left-angle}, @code{top-right-angle},
+@code{bottom-left-angle}, @code{bottom-right-angle},
+@code{left-bracket}, @code{right-bracket},
+@code{filled-rectangle}, @code{hollow-rectangle},
+@code{filled-square}, @code{hollow-square},
+@code{vertical-bar}, @code{horizontal-bar},
+@code{empty-line},
+@code{question-mark}.
+@end table
-@defun set-window-fringes window left &optional right outside-margins
-This function sets the fringe widths of window @var{window}.
-If @var{window} is @code{nil}, the selected window is used.
+@node Fringe Cursors
+@subsection Fringe Cursors
+@cindex fringe cursors
+@cindex cursor, fringe
-The argument @var{left} specifies the width in pixels of the left
-fringe, and likewise @var{right} for the right fringe. A value of
-@code{nil} for either one stands for the default width. If
-@var{outside-margins} is non-@code{nil}, that specifies that fringes
-should appear outside of the display margins.
-@end defun
+ When a line is exactly as wide as the window, Emacs displays the
+cursor in the right fringe instead of using two lines. Different
+bitmaps are used to represent the cursor in the fringe depending on
+the current buffer's cursor type.
-@defun window-fringes &optional window
-This function returns information about the fringes of a window
-@var{window}. If @var{window} is omitted or @code{nil}, the selected
-window is used. The value has the form @code{(@var{left-width}
-@var{right-width} @var{frames-outside-margins})}.
-@end defun
+@table @asis
+@item Logical cursor types:
+@code{box} , @code{hollow}, @code{bar},
+@code{hbar}, @code{hollow-small}.
+@end table
+
+The @code{hollow-small} type is used instead of @code{hollow} when the
+normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
+display line.
@defvar overflow-newline-into-fringe
If this is non-@code{nil}, lines exactly as wide as the window (not
fringe.
@end defvar
+@defvar fringe-cursor-alist
+This variable specifies the mapping from logical cursor type to the
+actual fringe bitmaps displayed in the right fringe. The value is an
+alist where each element @code{(@var{cursor}. @var{bitmap})} specifies
+the fringe bitmaps used to display a specific logical cursor type in
+the fringe. Here, @var{cursor} specifies the logical cursor type and
+@var{bitmap} is a symbol specifying the fringe bitmap to be displayed
+for that logical cursor type.
+
+When @code{fringe-cursor-alist} has a buffer-local value, and there is
+no bitmap defined for a cursor type, the corresponding value from the
+(non-local) @code{default-fringes-indicator-alist} is used.
+@end defvar
+
+@defvar default-fringes-cursor-alist
+The value of this variable is the default value for
+@code{fringe-cursor-alist} in buffers that do not override it.
+@end defvar
+
+@table @asis
+@item Standard bitmaps for displaying the cursor in right fringe:
+@code{filled-rectangle}, @code{hollow-rectangle},
+@code{filled-square}, @code{hollow-square},
+@code{vertical-bar}, @code{horizontal-bar}.
+@end table
+
+
@node Fringe Bitmaps
-@section Fringe Bitmaps
+@subsection Fringe Bitmaps
@cindex fringe bitmaps
@cindex bitmaps, fringe
- The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
-fringe (on a graphic display) to indicate truncated or continued
-lines, buffer boundaries, overlay arrow, etc. The fringe bitmaps are
-shared by all frames and windows. You can redefine the built-in
-fringe bitmaps, and you can define new fringe bitmaps.
+ The @dfn{fringe bitmaps} are the actual bitmaps which represent the
+logical fringe indicators for truncated or continued lines, buffer
+boundaries, overlay arrow, etc. Fringe bitmap symbols have their own
+name space. The fringe bitmaps are shared by all frames and windows.
+You can redefine the built-in fringe bitmaps, and you can define new
+fringe bitmaps.
The way to display a bitmap in the left or right fringes for a given
line in a window is by specifying the @code{display} property for one
of the characters that appears in it. Use a display specification of
the form @code{(left-fringe @var{bitmap} [@var{face}])} or
@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
-Property}). Here, @var{bitmap} is a symbol identifying the bitmap
-you want, and @var{face} (which is optional) is the name of the face
-whose colors should be used for displaying the bitmap.
-
- These are the symbols identify the standard fringe bitmaps.
-Evaluate @code{(require 'fringe)} to define them. Fringe bitmap
-symbols have their own name space.
-
-@table @asis
-@item Truncation and continuation line bitmaps:
-@code{left-truncation}, @code{right-truncation},
-@code{continued-line}, @code{continuation-line}.
-
-@item Buffer indication bitmaps:
-@code{up-arrow}, @code{down-arrow},
-@code{top-left-angle}, @code{top-right-angle},
-@code{bottom-left-angle}, @code{bottom-right-angle},
-@code{left-bracket}, @code{right-bracket}.
-
-@item Empty line indication bitmap:
-@code{empty-line}.
-
-@item Overlay arrow bitmap:
-@code{overlay-arrow}.
-
-@item Bitmaps for displaying the cursor in right fringe:
-@code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
-@code{bar-cursor}, @code{hbar-cursor}.
-@end table
+Property}). Here, @var{bitmap} is a symbol identifying the bitmap you
+want, and @var{face} (which is optional) is the name of the face whose
+colors should be used for displaying the bitmap, instead of the
+default @code{fringe} face. @var{face} is automatically merged with
+the @code{fringe} face, so normally @var{face} need only specify the
+foreground color for the bitmap.
@defun fringe-bitmaps-at-pos &optional pos window
This function returns the fringe bitmaps of the display line
@end defun
@node Customizing Bitmaps
-@section Customizing Fringe Bitmaps
+@subsection Customizing Fringe Bitmaps
@defun define-fringe-bitmap bitmap bits &optional height width align
This function defines the symbol @var{bitmap} as a new fringe bitmap,
If @var{face} is @code{nil}, it selects the @code{fringe} face. The
bitmap's face controls the color to draw it in.
-The face you use here should be derived from @code{fringe}, and should
-specify only the foreground color.
+@var{face} is merged with the @code{fringe} face, so normally
+@var{face} should specify only the foreground color.
@end defun
+@node Overlay Arrow
+@subsection The Overlay Arrow
+@cindex overlay arrow
+
+ The @dfn{overlay arrow} is useful for directing the user's attention
+to a particular line in a buffer. For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed. This feature has nothing to do with
+@dfn{overlays} (@pxref{Overlays}).
+
+@defvar overlay-arrow-string
+This variable holds the string to display to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
+On a graphical display the contents of the string are ignored; instead a
+glyph is displayed in the fringe area to the left of the display area.
+@end defvar
+
+@defvar overlay-arrow-position
+This variable holds a marker that indicates where to display the overlay
+arrow. It should point at the beginning of a line. On a non-graphical
+display the arrow text
+appears at the beginning of that line, overlaying any text that would
+otherwise appear. Since the arrow is usually short, and the line
+usually begins with indentation, normally nothing significant is
+overwritten.
+
+The overlay-arrow string is displayed in any given buffer if the value
+of @code{overlay-arrow-position} in that buffer points into that
+buffer. Thus, it works to can display multiple overlay arrow strings
+by creating buffer-local bindings of @code{overlay-arrow-position}.
+However, it is usually cleaner to use
+@code{overlay-arrow-variable-list} to achieve this result.
+@c !!! overlay-arrow-position: but the overlay string may remain in the display
+@c of some other buffer until an update is required. This should be fixed
+@c now. Is it?
+@end defvar
+
+ You can do a similar job by creating an overlay with a
+@code{before-string} property. @xref{Overlay Properties}.
+
+ You can define multiple overlay arrows via the variable
+@code{overlay-arrow-variable-list}.
+
+@defvar overlay-arrow-variable-list
+This variable's value is a list of variables, each of which specifies
+the position of an overlay arrow. The variable
+@code{overlay-arrow-position} has its normal meaning because it is on
+this list.
+@end defvar
+
+Each variable on this list can have properties
+@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
+specify an overlay arrow string (for text-only terminals) or fringe
+bitmap (for graphical terminals) to display at the corresponding
+overlay arrow position. If either property is not set, the default
+(@code{overlay-arrow-string} or @code{overlay-arrow-fringe-bitmap}) is
+used.
+
@node Scroll Bars
@section Scroll Bars
Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars. A
-non-@code{nil} parameter value means they do. The frame parameter
+whether the windows in the frame have vertical scroll bars, and
+whether they are on the left or right. The frame parameter
@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default). @xref{Window Frame Parameters}.
+meaning the default). @xref{Layout Parameters}.
+
+@defun frame-current-scroll-bars &optional frame
+This function reports the scroll bar type settings for frame
+@var{frame}. The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
+@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
+(which means no scroll bar.) @var{horizontal-type} is meant to
+specify the horizontal scroll bar type, but since they are not
+implemented, it is always @code{nil}.
+@end defun
@vindex vertical-scroll-bar
You can enable or disable scroll bars for a particular buffer,
the left, and @code{right} to put a scroll bar on the right.
@end defvar
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
+@code{window-scroll-bars}, this reports the scroll bar type actually
+used, once frame defaults and @code{scroll-bar-mode} are taken into
+account.
+@end defun
+
@defvar scroll-bar-width
This variable, always local in all buffers, specifies the width of the
buffer's scroll bars, measured in pixels. A value of @code{nil} means
The @code{display} text property (or overlay property) is used to
insert images into text, and also control other aspects of how text
-displays. These features are available starting in Emacs 21. The value
-of the @code{display} property should be a display specification, or a
-list or vector containing several display specifications. The rest of
-this section describes several kinds of display specifications and what
-they mean.
+displays. The value of the @code{display} property should be a
+display specification, or a list or vector containing several display
+specifications.
+
+ Some kinds of @code{display} properties specify something to display
+instead of the text that has the property. In this case, ``the text''
+means all the consecutive characters that have the same Lisp object as
+their @code{display} property; these characters are replaced as a
+single unit. By contrast, characters that have similar but distinct
+Lisp objects as their @code{display} properties are handled
+separately. Here's a function that illustrates this point:
+
+@smallexample
+(defun foo ()
+ (goto-char (point-min))
+ (dotimes (i 5)
+ (let ((string (concat "A")))
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 1)
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 1))))
+@end smallexample
+
+@noindent
+It gives each of the first ten characters in the buffer string
+@code{"A"} as the @code{display} property, but they don't all get the
+same string. The first two characters get the same string, so they
+together are replaced with one @samp{A}. The next two characters get
+a second string, so they together are replaced with one @samp{A}.
+Likewise for each following pair of characters. Thus, the ten
+characters appear as five A's. This function would have the same
+results:
+
+@smallexample
+(defun foo ()
+ (goto-char (point-min))
+ (dotimes (i 5)
+ (let ((string (concat "A")))
+ (put-text-property (point) (2+ (point)) 'display string)
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 2))))
+@end smallexample
+
+@noindent
+This illustrates that what matters is the property value for
+each character. If two consecutive characters have the same
+object as the @code{display} property value, it's irrelevant
+whether they got this property from a single call to
+@code{put-text-property} or from two different calls.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
@menu
* Specified Space:: Displaying one space with a specified width.
up or down on the page; adjusting the width
of spaces within text.
* Display Margins:: Displaying text or images to the side of the main text.
-* Conditional Display:: Making any of the above features conditional
- depending on some Lisp expression.
@end menu
@node Specified Space
Don't use both @code{:height} and @code{:relative-height} together.
- The @code{:height} and @code{:align-to} properties are supported on
+ The @code{:width} and @code{:align-to} properties are supported on
non-graphic terminals, but the other space properties in this section
are not.
The following expressions are supported:
-@example
+@smallexample
@group
@var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
@var{num} ::= @var{integer} | @var{float} | @var{symbol}
@var{unit} ::= in | mm | cm | width | height
+@end group
+@group
@var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
| scroll-bar | text
@var{pos} ::= left | center | right
@var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
@var{op} ::= + | -
@end group
-@end example
+@end smallexample
The form @var{num} specifies a fraction of the default frame font
height or width. The form @code{(@var{num})} specifies an absolute
to the left edge of the text area. For example, @samp{:align-to 0} in a
header-line aligns with the first text column in the text area.
- A value of the form @code{(@var{num} . @var{expr})} stands
-multiplying the values of @var{num} and @var{expr}. For example,
+ A value of the form @code{(@var{num} . @var{expr})} stands for the
+product of the values of @var{num} and @var{expr}. For example,
@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
-@var{image})} specifies half the width (or height) of the specified image.
+@var{image})} specifies half the width (or height) of the specified
+image.
The form @code{(+ @var{expr} ...)} adds up the value of the
expressions. The form @code{(- @var{expr} ...)} negates or subtracts
in the @code{display} text property.
@table @code
+@item @var{string}
+Display @var{string} instead of the text that has this property.
+
+Recursive display specifications are not supported---@var{string}'s
+@code{display} properties, if any, are not used.
+
@item (image . @var{image-props})
-This is in fact an image descriptor (@pxref{Images}). When used as a
-display specification, it means to display the image instead of the text
-that has the display specification.
+This kind of display specification is an image descriptor (@pxref{Images}).
+When used as a display specification, it means to display the image
+instead of the text that has the display specification.
@item (slice @var{x} @var{y} @var{width} @var{height})
This specification together with @code{image} specifies a @dfn{slice}
of the entire image.
@item ((margin nil) @var{string})
-@itemx @var{string}
A display specification of this form means to display @var{string}
instead of the text that has the display specification, at the same
-position as that text. This is a special case of marginal display
-(@pxref{Display Margins}).
-
-Recursive display specifications are not supported---string display
-specifications must not have @code{display} properties themselves.
+position as that text. It is equivalent to using just @var{string},
+but it is done as a special case of marginal display (@pxref{Display
+Margins}).
@item (space-width @var{factor})
This display specification affects all the space characters within the
faces used for the text.
@end table
+@c We put all the `@code{(when ...)}' on one line to encourage
+@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
+@c was at eol; the info file ended up w/ two spaces rendered after it.
+ You can make any display specification conditional. To do that,
+package it in another list of the form
+@code{(when @var{condition} . @var{spec})}.
+Then the specification @var{spec} applies only when
+@var{condition} evaluates to a non-@code{nil} value. During the
+evaluation, @code{object} is bound to the string or buffer having the
+conditional @code{display} property. @code{position} and
+@code{buffer-position} are bound to the position within @code{object}
+and the buffer position where the @code{display} property was found,
+respectively. Both positions can be different when @code{object} is a
+string.
+
@node Display Margins
@subsection Displaying in the Margins
@cindex display margins
If @var{window} is @code{nil}, the selected window is used.
@end defun
-@node Conditional Display
-@subsection Conditional Display Specifications
-@cindex conditional display specifications
-
- You can make any display specification conditional. To do that,
-package it in another list of the form @code{(when @var{condition} .
-@var{spec})}. Then the specification @var{spec} applies only when
-@var{condition} evaluates to a non-@code{nil} value. During the
-evaluation, @code{object} is bound to the string or buffer having the
-conditional @code{display} property. @code{position} and
-@code{buffer-position} are bound to the position within @code{object}
-and the buffer position where the @code{display} property was found,
-respectively. Both positions can be different when @code{object} is a
-string.
-
@node Images
@section Images
@cindex images in buffers
To display an image in an Emacs buffer, you must first create an image
descriptor, then use it as a display specifier in the @code{display}
-property of text that is displayed (@pxref{Display Property}). Like the
-@code{display} property, this feature is available starting in Emacs 21.
+property of text that is displayed (@pxref{Display Property}).
Emacs can display a number of different image formats; some of them
are supported only if particular support libraries are installed on
-your machine. In some environments, Emacs allows loading image
+your machine. In some environments, Emacs can load image
libraries on demand; if so, the variable @code{image-library-alist}
can be used to modify the set of known names for these dynamic
libraries (though it is not possible to add new image formats).
- The supported image formats include XBM, XPM (needing the
-libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
-@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
-@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
-and PNG (needing @code{libpng} 1.0.2).
+ The supported image formats include XBM, XPM (this requires the
+libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
+@code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
+@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
+v3.4), and PNG (requiring @code{libpng} 1.0.2).
You specify one of these formats with an image type symbol. The image
type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
@subsection Image Descriptors
@cindex image descriptor
- An image description is a list of the form @code{(image
-. @var{props})}, where @var{props} is a property list containing
-alternating keyword symbols (symbols whose names start with a colon) and
-their values. You can use any Lisp object as a property, but the only
-properties that have any special meaning are certain symbols, all of
-them keywords.
+ An image description is a list of the form @code{(image . @var{props})},
+where @var{props} is a property list containing alternating keyword
+symbols (symbols whose names start with a colon) and their values.
+You can use any Lisp object as a property, but the only properties
+that have any special meaning are certain symbols, all of them keywords.
Every image descriptor must contain the property @code{:type
@var{type}} to specify the format of the image. The value of @var{type}
@table @code
@item :file @var{file}
-The @code{:file} property specifies to load the image from file
+The @code{:file} property says to load the image from file
@var{file}. If @var{file} is not an absolute file name, it is expanded
in @code{data-directory}.
@item :data @var{data}
-The @code{:data} property specifies the actual contents of the image.
+The @code{:data} property says the actual contents of the image.
Each image must use either @code{:data} or @code{:file}, but not both.
For most image types, the value of the @code{:data} property should be a
string containing the image data; we recommend using a unibyte string.
@subsection GIF Images
@cindex GIF
- For GIF images, specify image type @code{gif}. Because of the patents
-in the US covering the LZW algorithm, the continued use of GIF format is
-a problem for the whole Internet; to end this problem, it is a good idea
-for everyone, even outside the US, to stop using GIFs right away
-(@uref{http://www.burnallgifs.org/}). But if you still want to use
-them, Emacs can display them.
+ For GIF images, specify image type @code{gif}.
@table @code
@item :index @var{index}
@var{file} exists, is used to construct the image specification to be
returned. If no specification is satisfied, @code{nil} is returned.
-The image is looked for first on @code{load-path} and then in
-@code{data-directory}.
+The image is looked for in @code{image-load-path}.
+@end defun
+
+@defvar image-load-path
+@tindex image-load-path
+This variable's value is a list of locations in which to search for
+image files. If an element is a string or a variable symbol whose
+value is a string, the string is taken to be the name of a directory
+to search. If an element is a variable symbol whose value is a list,
+that is taken to be a list of directory names to search.
+
+The default is to search in the @file{images} subdirectory of the
+directory specified by @code{data-directory}, then the directory
+specified by @code{data-directory}, and finally in the directories in
+@code{load-path}. Subdirectories are not automatically included in
+the search, so if you put an image file in a subdirectory, you have to
+supply the subdirectory name explicitly. For example, to find the
+image @file{images/foo/bar.xpm} within @code{data-directory}, you
+should specify the image as follows:
+
+@example
+(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
+@end example
+@end defvar
+
+@defun image-load-path-for-library library image &optional path no-error
+@tindex image-load-path-for-library
+This function returns a suitable search path for images used by the
+Lisp package @var{library}.
+
+It searches for @var{image} in @code{image-load-path} (excluding
+@file{@code{data-directory}/images}) and @code{load-path}, followed by
+a path suitable for @var{library}, which includes
+@file{../../etc/images} and @file{../etc/images} relative to the
+library file itself, and then in @file{@code{data-directory}/images}.
+
+Then this function returns a list of directories which contains first
+the directory in which @var{image} was found, followed by the value of
+@code{load-path}. If @var{path} is given, it is used instead of
+@code{load-path}.
+
+If @var{no-error} is non-@code{nil} and a suitable path can't be
+found, don't signal an error. Instead, return a list of directories as
+before, except that @code{nil} appears in place of the image directory.
+
+Here is an example that uses a common idiom to provide compatibility
+with versions of Emacs that lack the variable @code{image-load-path}:
+
+@example
+;; Shush compiler.
+(defvar image-load-path)
+
+(let* ((load-path (image-load-path-for-library "mh-e" "mh-logo.xpm"))
+ (image-load-path (cons (car load-path)
+ (when (boundp 'image-load-path)
+ image-load-path))))
+ (mh-tool-bar-folder-buttons-init))
+@end example
@end defun
@node Showing Images
This function inserts @var{image} in the current buffer at point. The
value @var{image} should be an image descriptor; it could be a value
returned by @code{create-image}, or the value of a symbol defined with
-@code{defimage}. The argument @var{string} specifies the text to put in
-the buffer to hold the image.
+@code{defimage}. The argument @var{string} specifies the text to put
+in the buffer to hold the image. If it is omitted or @code{nil},
+@code{insert-image} uses @code{" "} by default.
The argument @var{area} specifies whether to put the image in a margin.
If it is @code{left-margin}, the image appears in the left margin;
Focus}).
@end defun
+@defvar max-image-size
+@tindex max-image-size
+This variable is used to define the maximum size of image that Emacs
+will load. Emacs will refuse to load (and display) any image that is
+larger than this limit.
+
+If the value is an integer, it directly specifies the maximum
+image height and width, measured in pixels. If it is a floating
+point number, it specifies the maximum image height and width
+as a ratio to the frame height and width. If the value is
+non-numeric, there is no explicit limit on the size of images.
+
+The purpose of this variable is to prevent unreasonably large images
+from accidentally being loaded into Emacs. It only takes effect the
+first time an image is loaded. Once an image is placed in the image
+cache, it can always be displayed, even if the value of
+@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@end defvar
+
@node Image Cache
@subsection Image Cache
buttons in Emacs buffers, such as might be used for help hyper-links,
etc. Emacs uses buttons for the hyper-links in help text and the like.
-A button is essentially a set of properties attached (via text
-properties or overlays) to a region of text in an Emacs buffer, which
-are called its button properties. @xref{Button Properties}.
+ A button is essentially a set of properties attached (via text
+properties or overlays) to a region of text in an Emacs buffer. These
+properties are called @dfn{button properties}.
-One of the these properties (@code{action}) is a function, which will
+ One of the these properties (@code{action}) is a function, which will
be called when the user invokes it using the keyboard or the mouse.
The invoked function may then examine the button and use its other
properties as desired.
-In some ways the Emacs button package duplicates functionality offered
+ In some ways the Emacs button package duplicates functionality offered
by the widget package (@pxref{Top, , Introduction, widget, The Emacs
Widget Library}), but the button package has the advantage that it is
much faster, much smaller, and much simpler to use (for elisp
* Making Buttons:: Adding buttons to Emacs buffers.
* Manipulating Buttons:: Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
-* Manipulating Button Types::
@end menu
@node Button Properties
Buttons have an associated list of properties defining their
appearance and behavior, and other arbitrary properties may be used
-for application specific purposes.
-
-Some properties that have special meaning to the button package
-include:
+for application specific purposes. Some properties that have special
+meaning to the button package include:
@table @code
-
@item action
@kindex action @r{(button property)}
The function to call when the user invokes the button, which is passed
standard button functions do).
@end table
-There are other properties defined for the regions of text in a
+ There are other properties defined for the regions of text in a
button, but these are not generally interesting for typical uses.
@node Button Types
reflected in its subtypes.
@end defun
-Using @code{define-button-type} to define default properties for
+ Using @code{define-button-type} to define default properties for
buttons is not necessary---buttons without any specified type use the
-built-in button-type @code{button}---but it is is encouraged, since
+built-in button-type @code{button}---but it is encouraged, since
doing so usually makes the resulting code clearer and more efficient.
@node Making Buttons
@cindex making buttons
Buttons are associated with a region of text, using an overlay or
-text-properties to hold button-specific information, all of which are
+text properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
button type @code{button}). Like all Emacs text, the appearance of
the button is governed by the @code{face} property; by default (via
the @code{face} property inherited from the @code{button} button-type)
this is a simple underline, like a typical web-page link.
-For convenience, there are two sorts of button-creation functions,
+ For convenience, there are two sorts of button-creation functions,
those that add button properties to an existing region of a buffer,
-called @code{make-...button}, and those also insert the button text,
-called @code{insert-...button}.
+called @code{make-...button}, and those that also insert the button
+text, called @code{insert-...button}.
-The button-creation functions all take the @code{&rest} argument
+ The button-creation functions all take the @code{&rest} argument
@var{properties}, which should be a sequence of @var{property value}
pairs, specifying properties to add to the button; see @ref{Button
Properties}. In addition, the keyword argument @code{:type} may be
during creation will be inherited from the button's type (if the type
defines such a property).
-The following functions add a button using an overlay
+ The following functions add a button using an overlay
(@pxref{Overlays}) to hold the button properties:
@defun make-button beg end &rest properties
@tindex make-button
-Make a button from @var{beg} to @var{end} in the current buffer.
+This makes a button from @var{beg} to @var{end} in the
+current buffer, and returns it.
@end defun
@defun insert-button label &rest properties
@tindex insert-button
-Insert a button with the label @var{label}.
+This insert a button with the label @var{label} at point,
+and returns it.
@end defun
-The following functions are similar, but use Emacs text-properties
+ The following functions are similar, but use Emacs text properties
(@pxref{Text Properties}) to hold the button properties, making the
button actually part of the text instead of being a property of the
-buffer (using text-properties is usually faster than using overlays,
-so this may be preferable when creating large numbers of buttons):
+buffer. Buttons using text properties do not create markers into the
+buffer, which is important for speed when you use extremely large
+numbers of buttons. Both functions return the position of the start
+of the new button:
@defun make-text-button beg end &rest properties
@tindex make-text-button
-Make a button from @var{beg} to @var{end} in the current buffer, using
-text-properties.
+This makes a button from @var{beg} to @var{end} in the current buffer, using
+text properties.
@end defun
@defun insert-text-button label &rest properties
@tindex insert-text-button
-Insert a button with the label @var{label}, using text-properties.
+This inserts a button with the label @var{label} at point, using text
+properties.
@end defun
-Buttons using text-properties retain no markers into the buffer are
-retained, which is important for speed in cases where there are
-extremely large numbers of buttons.
-
@node Manipulating Buttons
@subsection Manipulating Buttons
@cindex manipulating buttons
Return the button at position @var{pos} in the current buffer, or @code{nil}.
@end defun
+@defun button-type-put type prop val
+@tindex button-type-put
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+@tindex button-type-get
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+@tindex button-type-subtype-p
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
@node Button Buffer Commands
@subsection Button Buffer Commands
@cindex button buffer commands
parent keymap for its keymap.
If the button has a non-@code{nil} @code{follow-link} property, and
-@var{mouse-1-click-follows-link} is set, a @key{Mouse-1} click will
-also activate the @code{push-button} command.
+@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
+will also activate the @code{push-button} command.
+@xref{Links and Mouse-1}.
@deffn Command push-button &optional pos use-mouse-action
@tindex push-button
@var{pos} in the search, instead of starting at the next button.
@end defun
-@node Manipulating Button Types
-@subsection Manipulating Button Types
-@cindex manipulating button types
-
-@defun button-type-put type prop val
-@tindex button-type-put
-Set the button-type @var{type}'s @var{prop} property to @var{val}.
-@end defun
-
-@defun button-type-get type prop
-@tindex button-type-get
-Get the property of button-type @var{type} named @var{prop}.
-@end defun
-
-@defun button-type-subtype-p type supertype
-@tindex button-type-subtype-p
-Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
-@end defun
-
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
@end smallexample
@end deffn
-@node Inverse Video
-@section Inverse Video
-@cindex Inverse Video
-
-@defopt inverse-video
-@cindex highlighting
-This variable controls whether Emacs uses inverse video for all text
-on the screen. Non-@code{nil} means yes, @code{nil} means no. The
-default is @code{nil}.
-@end defopt
-
-@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines and menu
-bars. If it is non-@code{nil}, then these lines are displayed in
-inverse video. Otherwise, these lines are displayed normally, just like
-other text. The default is @code{t}.
-
-For window frames, this feature actually applies the face named
-@code{mode-line}; that face is normally set up as the inverse of the
-default face, unless you change it.
-@end defopt
-
@node Usual Display
@section Usual Display Conventions
@end defvar
@defopt tab-width
-The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers. The value is in units of
-columns, and the default is 8. Note that this feature is completely
-independent of the user-settable tab stops used by the command
-@code{tab-to-tab-stop}. @xref{Indent Tabs}.
+The value of this buffer-local variable is the spacing between tab
+stops used for displaying tab characters in Emacs buffers. The value
+is in units of columns, and the default is 8. Note that this feature
+is completely independent of the user-settable tab stops used by the
+command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
-@defopt indicate-empty-lines
-@tindex indicate-empty-lines
-@cindex fringes, and empty line indication
-When this is non-@code{nil}, Emacs displays a special glyph in the
-fringe of each empty line at the end of the buffer, on terminals that
-support it (window systems). @xref{Fringes}.
-@end defopt
-
-@defvar indicate-buffer-boundaries
-This buffer-local variable controls how the buffer boundaries and
-window scrolling are indicated in the window fringes.
-
-Emacs can indicate the buffer boundaries---that is, the first and last
-line in the buffer---with angle icons when they appear on the screen.
-In addition, Emacs can display an up-arrow in the fringe to show
-that there is text above the screen, and a down-arrow to show
-there is text below the screen.
-
-There are four kinds of basic values:
-
-@table @asis
-@item @code{nil}
-Don't display the icons.
-@item @code{left}
-Display them in the left fringe.
-@item @code{right}
-Display them in the right fringe.
-@item @var{anything-else}
-Display the icon at the top of the window top in the left fringe, and other
-in the right fringe.
-@end table
-
-If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
-controls the angle icons, and @var{arrows} controls the arrows. Both
-@var{angles} and @var{arrows} work according to the table above.
-Thus, @code{(t . right)} places the top angle icon in the left
-fringe, the bottom angle icon in the right fringe, and both arrows in
-the right fringe.
-@end defvar
-
-@defvar default-indicate-buffer-boundaries
-The value of this variable is the default value for
-@code{indicate-buffer-boundaries} in buffers that do not override it.
-@end defvar
-
@node Display Tables
@section Display Tables
@table @asis
@item 0
The glyph for the end of a truncated screen line (the default for this
-is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
-display arrows to indicate truncation---the display table has no effect
-in these situations.
+is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
+arrows in the fringes to indicate truncation, so the display table has
+no effect.
+
@item 1
The glyph for the end of a continued line (the default is @samp{\}).
-Newer Emacs versions, on some platforms, display curved arrows to
-indicate continuation---the display table has no effect in these
-situations.
+On graphical terminals, Emacs uses curved arrows in the fringes to
+indicate continuation, so the display table has no effect.
+
@item 2
The glyph for indicating a character displayed as an octal character
code (the default is @samp{\}).
+
@item 3
The glyph for indicating a control character (the default is @samp{^}).
+
@item 4
A vector of glyphs for indicating the presence of invisible lines (the
default is @samp{...}). @xref{Selective Display}.
+
@item 5
The glyph used to draw the border between side-by-side windows (the
default is @samp{|}). @xref{Splitting Windows}. This takes effect only
table if any. The display table chosen is called the @dfn{active}
display table.
-@defun window-display-table window
+@defun window-display-table &optional window
This function returns @var{window}'s display table, or @code{nil}
-if @var{window} does not have an assigned display table.
+if @var{window} does not have an assigned display table. The default
+for @var{window} is the selected window.
@end defun
@defun set-window-display-table window table
@item @var{string}
Send the characters in @var{string} to the terminal to output
this glyph. This alternative is available on character terminals,
-but not under a window system.
+but not on graphical displays.
@item @var{integer}
Define this glyph code as an alias for glyph code @var{integer}. You
@defopt visible-bell
This variable determines whether Emacs should flash the screen to
represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
-is effective on a window system, and on a character-only terminal
+is effective on graphical displays, and on text-only terminals
provided the terminal's Termcap entry defines the visible bell
capability (@samp{vb}).
@end defopt