@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, System Interface, Processes, Top
* 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).
* Temporary Displays:: Displays that go away automatically.
font, colors, etc.
* Fringes:: Controlling window 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.
+* Abstract Display:: Emacs' Widget for Object Collections.
* 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.
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
- On a window system display, the @samp{$} and @samp{\} indicators are
+ On a graphical display, the @samp{$} and @samp{\} indicators are
replaced with arrow images displayed in the window fringes
(@pxref{Fringes}).
@cindex error display
@cindex echo area
-The @dfn{echo area} is used for displaying error messages
+ 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
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 as
-follows:
+ 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 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
+@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
depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
-@defopt max-mini-window-height
-This variable specifies the maximum height for resizing minibuffer
-windows. If a float, it specifies a fraction of the height of the
-frame. If an integer, it specifies a number of lines.
-@end defopt
-
@tindex with-temp-message
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
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.)
+
+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.
+ 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:
-
-@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.)
-
-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...
-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
@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
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
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.
+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
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
@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
@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
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.
* Displaying Faces:: How Emacs combines the faces specified for a character.
* Font Selection:: Finding the best available font for a face.
* Face Functions:: How to define and examine faces.
-* Auto Faces:: Hook for automatic face assignment.
-* Font Lookup:: Looking up the names of available fonts
- and information about them.
-* Fontsets:: A fontset is a collection of fonts
- 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. Other faces used to display bitmaps in the fringe
-are implicitly merged with this face.
-
-@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 mode-line-highlight
-@kindex mode-line-highlight @r{(face name)}
-This face is used for highlighting something on @code{mode-line} or
-@code{header-line} 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}.
-
-@item escape-glyph
-@kindex escape-glyph @r{(face name)}
-This face is used to display control characters and escape glyphs.
-@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.
-
-@item shadow
-@kindex shadow @r{(face name)}
-This face is used for making the text less noticeable than the
-surrounding ordinary text.
-@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
+* Auto Faces:: Hook for automatic face assignment.
+* Font Lookup:: Looking up the names of available fonts
+ and information about them.
+* Fontsets:: A fontset is a collection of fonts
+ that handle a range of character sets.
+@end menu
@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]...
+@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
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 it s @sc{car} is @code{default}, is special---it specifies
+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.
@item type
The kind of window system the frame uses---either @code{graphic} (any
graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
-@code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
-display).
+@code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh
+display), or @code{tty} (a non-graphics-capable display).
+@xref{Window Systems, window-system}.
@item class
What kinds of colors the frame supports---either @code{color},
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.
@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
@menu
* Fringe Size/Pos:: Specifying where to put the window fringes.
-* Fringe Bitmaps:: Displaying bitmaps in 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
- Here's how to control the position and width of the window fringes.
+ The following buffer-local variables control the position and width
+of the window fringes.
@defvar fringes-outside-margins
-If the value is non-@code{nil}, the frames appear outside the display
-margins. The fringes normally appear between the display margins and
-the window text. It works to set @code{fringes-outside-margins}
-buffer-locally. @xref{Display 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.
+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.
+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
@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}.
+
+@item Overlay arrow indicator:
+@code{overlay-arrow}.
+
+@item Unknown bitmap indicator:
+@code{unknown}.
+@end table
+
+ 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.
+
+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 @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.
+
+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.
+
+To completely hide a specific indicator, set the bitmap to @code{nil}.
+@end defvar
+
+@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
+
+@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
+
+@node Fringe Cursors
+@subsection Fringe Cursors
+@cindex fringe cursors
+@cindex cursor, fringe
+
+ 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.
+
+@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
counting the final newline character) are not continued. Instead,
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
@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
the @code{fringe} face, so normally @var{face} need only specify the
foreground color for the bitmap.
- These 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
-
@defun fringe-bitmaps-at-pos &optional pos window
This function returns the fringe bitmaps of the display line
containing position @var{pos} in window @var{window}. The return
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.
+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?
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
to use the value specified by the frame.
@end defvar
-@node Pointer Shape
-@section Pointer Shape
-
- Normally, the mouse pointer has the @code{text} shape over text and
-the @code{arrow} shape over window areas which do not correspond to
-any buffer text. You can specify the mouse pointer shape over text or
-images via the @code{pointer} text property, and for images with the
-@code{:pointer} and @code{:map} image properties.
-
- The available pointer shapes are: @code{text} (or @code{nil}),
-@code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
-@code{modeline}, and @code{hourglass}.
-
-@defvar void-text-area-pointer
-@tindex void-text-area-pointer
-This variable specifies the mouse pointer shape in void text areas,
-i.e. the areas after the end of a line or below the last line in the
-buffer. The default is to use the @code{arrow} (non-text) pointer.
-@end defvar
-
@node Display Property
@section The @code{display} Property
@cindex display specification
@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 kind of display specification is an image descriptor (@pxref{Images}).
When used as a display specification, it means to display the image
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
+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
@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}
@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
where each pair in the vector describes one corner in the polygon.
-When the mouse pointer is above a hot-spot area of an image, the
+When the mouse pointer lies on a hot-spot area of an image, the
@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
-property it defines a tool-tip for the hot-spot, and if it contains
-a @code{pointer} property, it defines the shape of the mouse cursor when
-it is over the hot-spot.
+property, that defines a tool-tip for the hot-spot, and if it contains
+a @code{pointer} property, that defines the shape of the mouse cursor when
+it is on the hot-spot.
@xref{Pointer Shape}, for available pointer shapes.
When you click the mouse when the mouse pointer is over a hot-spot, an
@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
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
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
@var{properties}, which should be a sequence of @var{property value}
@var{pos} in the search, instead of starting at the next button.
@end defun
+@node Abstract Display
+@section Abstract Display
+@cindex ewoc
+@cindex display, abstract
+@cindex display, arbitrary objects
+@cindex model/view/controller
+@cindex view part, model/view/controller
+
+ The Ewoc package constructs buffer text that represents a structure
+of Lisp objects, and updates the text to follow changes in that
+structure. This is like the ``view'' component in the the
+``model/view/controller'' design paradigm.
+
+ An @dfn{ewoc} is a structure that organizes information required to
+construct buffer text that represents certain Lisp data. The buffer
+text of the ewoc has three parts, in order: first, fixed @dfn{header}
+text; next, textual descriptions of a series of data elements (Lisp
+objects that you specify); and last, fixed @dfn{footer} text.
+Specifically, an ewoc contains information on:
+
+@itemize @bullet
+@item
+The buffer which its text is generated in.
+
+@item
+The text's start position in the buffer.
+
+@item
+The header and footer strings.
+
+@item
+A doubly-linked chain of @dfn{nodes}, each of which contains:
+
+@itemize
+@item
+A @dfn{data element}, a single Lisp object.
+
+@item
+Links to the preceding and following nodes in the chain.
+@end itemize
+
+@item
+A @dfn{pretty-printer} function which is responsible for
+inserting the textual representation of a data
+element value into the current buffer.
+@end itemize
+
+ Typically, you define an ewoc with @code{ewoc-create}, and then pass
+the resulting ewoc structure to other functions in the Ewoc package to
+build nodes within it, and display it in the buffer. Once it is
+displayed in the buffer, other functions determine the correspondance
+between buffer positions and nodes, move point from one node's textual
+representation to another, and so forth. @xref{Abstract Display
+Functions}.
+
+ A node @dfn{encapsulates} a data element much the way a variable
+holds a value. Normally, encapsulation occurs as a part of adding a
+node to the ewoc. You can retrieve the data element value and place a
+new value in its place, like so:
+
+@lisp
+(ewoc-data @var{node})
+@result{} value
+
+(ewoc-set-data @var{node} @var{new-value})
+@result{} @var{new-value}
+@end lisp
+
+@noindent
+You can also use, as the data element value, a Lisp object (list or
+vector) that is a container for the ``real'' value, or an index into
+some other structure. The example (@pxref{Abstract Display Example})
+uses the latter approach.
+
+ When the data changes, you will want to update the text in the
+buffer. You can update all nodes by calling @code{ewoc-refresh}, or
+just specific nodes using @code{ewoc-invalidate}, or all nodes
+satisfying a predicate using @code{ewoc-map}. Alternatively, you can
+delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
+and add new nodes in their place. Deleting a node from an ewoc deletes
+its associated textual description from buffer, as well.
+
+@menu
+* Abstract Display Functions::
+* Abstract Display Example::
+@end menu
+
+@node Abstract Display Functions
+@subsection Abstract Display Functions
+
+ In this subsection, @var{ewoc} and @var{node} stand for the
+structures described above (@pxref{Abstract Display}), while
+@var{data} stands for an arbitrary Lisp object used as a data element.
+
+@defun ewoc-create pretty-printer &optional header footer nosep
+This constructs and returns a new ewoc, with no nodes (and thus no data
+elements). @var{pretty-printer} should be a function that takes one
+argument, a data element of the sort you plan to use in this ewoc, and
+inserts its textual description at point using @code{insert} (and never
+@code{insert-before-markers}, because that would interfere with the
+Ewoc package's internal mechanisms).
+
+Normally, a newline is automatically inserted after the header,
+the footer and every node's textual description. If @var{nosep}
+is non-@code{nil}, no newline is inserted. This may be useful for
+displaying an entire ewoc on a single line, for example, or for
+making nodes ``invisible'' by arranging for @var{pretty-printer}
+to do nothing for those nodes.
+
+An ewoc maintains its text in the buffer that is current when
+you create it, so switch to the intended buffer before calling
+@code{ewoc-create}.
+@end defun
+
+@defun ewoc-buffer ewoc
+This returns the buffer where @var{ewoc} maintains its text.
+@end defun
+
+@defun ewoc-get-hf ewoc
+This returns a cons cell @code{(@var{header} . @var{footer})}
+made from @var{ewoc}'s header and footer.
+@end defun
+
+@defun ewoc-set-hf ewoc header footer
+This sets the header and footer of @var{ewoc} to the strings
+@var{header} and @var{footer}, respectively.
+@end defun
+
+@defun ewoc-enter-first ewoc data
+@defunx ewoc-enter-last ewoc data
+These add a new node encapsulating @var{data}, putting it, respectively,
+at the beginning or end of @var{ewoc}'s chain of nodes.
+@end defun
+
+@defun ewoc-enter-before ewoc node data
+@defunx ewoc-enter-after ewoc node data
+These add a new node encapsulating @var{data}, adding it to
+@var{ewoc} before or after @var{node}, respectively.
+@end defun
+
+@defun ewoc-prev ewoc node
+@defunx ewoc-next ewoc node
+These return, respectively, the previous node and the next node of @var{node}
+in @var{ewoc}.
+@end defun
+
+@defun ewoc-nth ewoc n
+This returns the node in @var{ewoc} found at zero-based index @var{n}.
+A negative @var{n} means count from the end. @code{ewoc-nth} returns
+@code{nil} if @var{n} is out of range.
+@end defun
+
+@defun ewoc-data node
+This extracts the data encapsulated by @var{node} and returns it.
+@end defun
+
+@defun ewoc-set-data node data
+This sets the data encapsulated by @var{node} to @var{data}.
+@end defun
+
+@defun ewoc-locate ewoc &optional pos guess
+This determines the node in @var{ewoc} which contains point (or
+@var{pos} if specified), and returns that node. If @var{ewoc} has no
+nodes, it returns @code{nil}. If @var{pos} is before the first node,
+it returns the first node; if @var{pos} is after the last node, it returns
+the last node. The optional third arg @var{guess}
+should be a node that is likely to be near @var{pos}; this doesn't
+alter the result, but makes the function run faster.
+@end defun
+
+@defun ewoc-location node
+This returns the start position of @var{node}.
+@end defun
+
+@defun ewoc-goto-prev ewoc arg
+@defunx ewoc-goto-next ewoc arg
+These move point to the previous or next, respectively, @var{arg}th node
+in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
+the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
+moves past the last node, returning @code{nil}. Excepting this special
+case, these functions return the node moved to.
+@end defun
+
+@defun ewoc-goto-node ewoc node
+This moves point to the start of @var{node} in @var{ewoc}.
+@end defun
+
+@defun ewoc-refresh ewoc
+This function regenerates the text of @var{ewoc}. It works by
+deleting the text between the header and the footer, i.e., all the
+data elements' representations, and then calling the pretty-printer
+function for each node, one by one, in order.
+@end defun
+
+@defun ewoc-invalidate ewoc &rest nodes
+This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
+@var{ewoc} are updated instead of the entire set.
+@end defun
+
+@defun ewoc-delete ewoc &rest nodes
+This deletes each node in @var{nodes} from @var{ewoc}.
+@end defun
+
+@defun ewoc-filter ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc} and
+deletes those nodes for which @var{predicate} returns @code{nil}.
+Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-collect ewoc predicate &rest args
+This calls @var{predicate} for each data element in @var{ewoc}
+and returns a list of those elements for which @var{predicate}
+returns non-@code{nil}. The elements in the list are ordered
+as in the buffer. Any @var{args} are passed to @var{predicate}.
+@end defun
+
+@defun ewoc-map map-function ewoc &rest args
+This calls @var{map-function} for each data element in @var{ewoc} and
+updates those nodes for which @var{map-function} returns non-@code{nil}.
+Any @var{args} are passed to @var{map-function}.
+@end defun
+
+@node Abstract Display Example
+@subsection Abstract Display Example
+
+ Here is a simple example using functions of the ewoc package to
+implement a ``color components display'', an area in a buffer that
+represents a vector of three integers (itself representing a 24-bit RGB
+value) in various ways.
+
+@example
+(setq colorcomp-ewoc nil
+ colorcomp-data nil
+ colorcomp-mode-map nil
+ colorcomp-labels ["Red" "Green" "Blue"])
+
+(defun colorcomp-pp (data)
+ (if data
+ (let ((comp (aref colorcomp-data data)))
+ (insert (aref colorcomp-labels data) "\t: #x"
+ (format "%02X" comp) " "
+ (make-string (ash comp -2) ?#) "\n"))
+ (let ((cstr (format "#%02X%02X%02X"
+ (aref colorcomp-data 0)
+ (aref colorcomp-data 1)
+ (aref colorcomp-data 2)))
+ (samp " (sample text) "))
+ (insert "Color\t: "
+ (propertize samp 'face `(foreground-color . ,cstr))
+ (propertize samp 'face `(background-color . ,cstr))
+ "\n"))))
+
+(defun colorcomp (color)
+ "Allow fiddling with COLOR in a new buffer.
+The buffer is in Color Components mode."
+ (interactive "sColor (name or #RGB or #RRGGBB): ")
+ (when (string= "" color)
+ (setq color "green"))
+ (unless (color-values color)
+ (error "No such color: %S" color))
+ (switch-to-buffer
+ (generate-new-buffer (format "originally: %s" color)))
+ (kill-all-local-variables)
+ (setq major-mode 'colorcomp-mode
+ mode-name "Color Components")
+ (use-local-map colorcomp-mode-map)
+ (erase-buffer)
+ (buffer-disable-undo)
+ (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
+ (color-values color))))
+ (ewoc (ewoc-create 'colorcomp-pp
+ "\nColor Components\n\n"
+ (substitute-command-keys
+ "\n\\@{colorcomp-mode-map@}"))))
+ (set (make-local-variable 'colorcomp-data) data)
+ (set (make-local-variable 'colorcomp-ewoc) ewoc)
+ (ewoc-enter-last ewoc 0)
+ (ewoc-enter-last ewoc 1)
+ (ewoc-enter-last ewoc 2)
+ (ewoc-enter-last ewoc nil)))
+@end example
+
+@cindex controller part, model/view/controller
+ This example can be extended to be a ``color selection widget'' (in
+other words, the controller part of the ``model/view/controller''
+design paradigm) by defining commands to modify @code{colorcomp-data}
+and to ``finish'' the selection process, and a keymap to tie it all
+together conveniently.
+
+@example
+(defun colorcomp-mod (index limit delta)
+ (let ((cur (aref colorcomp-data index)))
+ (unless (= limit cur)
+ (aset colorcomp-data index (+ cur delta)))
+ (ewoc-invalidate
+ colorcomp-ewoc
+ (ewoc-nth colorcomp-ewoc index)
+ (ewoc-nth colorcomp-ewoc -1))))
+
+(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
+(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
+(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
+(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
+(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
+(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
+
+(defun colorcomp-copy-as-kill-and-exit ()
+ "Copy the color components into the kill ring and kill the buffer.
+The string is formatted #RRGGBB (hash followed by six hex digits)."
+ (interactive)
+ (kill-new (format "#%02X%02X%02X"
+ (aref colorcomp-data 0)
+ (aref colorcomp-data 1)
+ (aref colorcomp-data 2)))
+ (kill-buffer nil))
+
+(setq colorcomp-mode-map
+ (let ((m (make-sparse-keymap)))
+ (suppress-keymap m)
+ (define-key m "i" 'colorcomp-R-less)
+ (define-key m "o" 'colorcomp-R-more)
+ (define-key m "k" 'colorcomp-G-less)
+ (define-key m "l" 'colorcomp-G-more)
+ (define-key m "," 'colorcomp-B-less)
+ (define-key m "." 'colorcomp-B-more)
+ (define-key m " " 'colorcomp-copy-as-kill-and-exit)
+ m))
+@end example
+
+Note that we never modify the data in each node, which is fixed when the
+ewoc is created to be either @code{nil} or an index into the vector
+@code{colorcomp-data}, the actual color components.
+
@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
-the face @code{mode-line}. Otherwise, these lines are displayed
-normally, just like other text. The default is @code{t}.
-@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}.
-@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}.
+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
-@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
@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