@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, 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, Processes, Top
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
+* 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.
+* 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:
+* Line Height:: Controlling the height of lines.
+* 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.
+* 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.
* Window Systems:: Which window system is being used.
@end menu
This function clears and redisplays all visible frames.
@end deffn
+ This function forces certain windows to be redisplayed
+but does not clear them.
+
+@defun force-window-update 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.
+@end defun
+
Processing user input takes absolute priority over redisplay. If you
call these functions when input is available, they do nothing
immediately, but a full redisplay does happen eventually---after all the
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
-@cindex fringes, and line continuation/truncation indicators
On a windowed display, the @samp{$} and @samp{\} indicators are
-replaced with graphics bitmaps displayed on the thin areas right near
-the window edges, called the @dfn{fringes}.
+replaced with graphics bitmaps displayed in the window fringes
+(@pxref{Fringes}).
Note that continuation is different from filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
If the value is zero, then command input is not echoed.
@end defvar
+@node Warnings
+@section Reporting Warnings
+@cindex warnings
+
+ @dfn{Warnings} are a facility for a program to inform the user of a
+possible problem, but continue running.
+
+@menu
+* Warning Basics:: Warnings concepts and functions to report them.
+* Warning Variables:: Variables programs bind to customize their warnings.
+* Warning Options:: Variables users set to control display of warnings.
+@end menu
+
+@node Warning Basics
+@subsection Warning Basics
+@cindex severity level
+
+ Every warning has a textual message, which explains the problem for
+the user, and a @dfn{severity level} which is a symbol. Here are the
+possible severity levels, in order of decreasing severity, and their
+meanings:
+
+@table @code
+@item :emergency
+A problem that will seriously impair Emacs operation soon
+if you do not attend to it promptly.
+@item :error
+A report of data or circumstances that are inherently wrong.
+@item :warning
+A report of data or circumstances that are not inherently wrong, but
+raise suspicion of a possible problem.
+@item :debug
+A report of information that may be useful if you are debugging.
+@end table
+
+ When your program encounters invalid input data, it can either
+signal a Lisp error by calling @code{error} or @code{signal} or report
+a warning with severity @code{:error}. Signaling a Lisp error is the
+easiest thing to do, but it means the program cannot continue
+processing. If you want to take the trouble to implement a way to
+continue processing despite the bad data, then reporting a warning of
+severity @code{:error} is the right way to inform the user of the
+problem. For instance, the Emacs Lisp byte compiler can report an
+error that way and continue compiling other functions. (If the
+program signals a Lisp error and then handles it with
+@code{condition-case}, the user won't see the error message; it could
+show the message to the user by reporting it as a warning.)
+
+@cindex warning type
+ Each warning has a @dfn{warning type} to classify it. The type is a
+list of symbols. The first symbol should be the custom group that you
+use for the program's user options. For example, byte compiler
+warnings use the warning type @code{(bytecomp)}. You can also
+subcategorize the warnings, if you wish, by using more symbols in the
+list.
+
+@defun display-warning type message &optional level buffer-name
+This function reports a warning, using @var{message} as the message
+and @var{type} as the warning type. @var{level} should be the
+severity level, with @code{:warning} being the default.
+
+@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
+for logging the warning. By default, it is @samp{*Warnings*}.
+@end defun
+
+@defun lwarn type level message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message. In other respects it is
+equivalent to @code{display-warning}.
+@end defun
+
+@defun warn message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message, @code{(emacs)} as the
+type, and @code{:warning} as the severity level. It exists for
+compatibility only; we recommend not using it, because you should
+specify a specific warning type.
+@end defun
+
+@node Warning Variables
+@subsection Warning Variables
+
+ Programs can customize how their warnings appear by binding
+the variables described in this section.
+
+@defvar warning-levels
+This list defines the meaning and severity order of the warning
+severity levels. Each element defines one severity level,
+and they are arranged in order of decreasing severity.
+
+Each element has the form @code{(@var{level} @var{string}
+@var{function})}, where @var{level} is the severity level it defines.
+@var{string} specifies the textual description of this level.
+@var{string} should use @samp{%s} to specify where to put the warning
+type information, or it can omit the @samp{%s} so as not to include
+that information.
+
+The optional @var{function}, if non-@code{nil}, is a function to call
+with no arguments, to get the user's attention.
+
+Normally you should not change the value of this variable.
+@end defvar
+
+@defvar warning-prefix-function
+If non-@code{nil}, the value is a function to generate prefix text for
+warnings. Programs can bind the variable to a suitable function.
+@code{display-warning} calls this function with the warnings buffer
+current, and the function can insert text in it. That text becomes
+the beginning of the warning message.
+
+The function is called with two arguments, the severity level and its
+entry in @code{warning-levels}. It should return a list to use as the
+entry (this value need not be an actual member of
+@code{warning-levels}). By constructing this value, the function can
+change the severity of the warning, or specify different handling for
+a given severity level.
+
+If the variable's value is @code{nil} then there is no function
+to call.
+@end defvar
+
+@defvar warning-series
+Programs can bind this variable to @code{t} to say that the next
+warning should begin a series. When several warnings form a series,
+that means to leave point on the first warning of the series, rather
+than keep moving it for each warning so that it appears on the last one.
+The series ends when the local binding is unbound and
+@code{warning-series} becomes @code{nil} again.
+
+The value can also be a symbol with a function definition. That is
+equivalent to @code{t}, except that the next warning will also call
+the function with no arguments with the warnings buffer current. The
+function can insert text which will serve as a header for the series
+of warnings.
+
+Once a series has begun, the value is a marker which points to the
+buffer position in the warnings buffer of the start of the series.
+
+The variable's normal value is @code{nil}, which means to handle
+each warning separately.
+@end defvar
+
+@defvar warning-fill-prefix
+When this variable is non-@code{nil}, it specifies a fill prefix to
+use for filling each warning's text.
+@end defvar
+
+@defvar warning-type-format
+This variable specifies the format for displaying the warning type
+in the warning message. The result of formatting the type this way
+gets included in the message under the control of the string in the
+entry in @code{warning-levels}. The default value is @code{" (%s)"}.
+If you bind it to @code{""} then the warning type won't appear at
+all.
+@end defvar
+
+@node Warning Options
+@subsection Warning Options
+
+ These variables are used by users to control what happens
+when a Lisp program reports a warning.
+
+@defopt warning-minimum-level
+This user option specifies the minimum severity level that should be
+shown immediately to the user. The default is @code{:warning}, which
+means to immediately display all warnings except @code{:debug}
+warnings.
+@end defopt
+
+@defopt warning-minimum-log-level
+This user option specifies the minimum severity level that should be
+logged in the warnings buffer. The default is @code{:warning}, which
+means to log all warnings except @code{:debug} warnings.
+@end defopt
+
+@defopt warning-suppress-types
+This list specifies which warning types should not be displayed
+immediately for the user. Each element of the list should be a list
+of symbols. If its elements match the first elements in a warning
+type, then that warning is not displayed immediately.
+@end defopt
+
+@defopt warning-suppress-log-types
+This list specifies which warning types should not be logged in the
+warnings buffer. Each element of the list should be a list of
+symbols. If it matches the first few elements in a warning type, then
+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
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
-actually make a character invisible.
+actually make a character invisible. Setting this variable makes it
+buffer-local.
@table @asis
@item @code{t}
@end defun
@defun remove-from-invisibility-spec element
-This removeds the element @var{element} from
+This removes the element @var{element} from
@code{buffer-invisibility-spec}. This does nothing if @var{element}
is not in the list.
@end defun
@example
;; @r{If you want to display an ellipsis:}
-(add-to-invisibility-spec '(my-symbol . t))
+(add-to-invisibility-spec '(my-symbol . t))
;; @r{If you don't want ellipsis:}
-(add-to-invisibility-spec 'my-symbol)
+(add-to-invisibility-spec 'my-symbol)
(overlay-put (make-overlay beginning end)
'invisible 'my-symbol)
@end example
@vindex line-move-ignore-invisible
- Ordinarily, commands that operate on text or move point do not care
+ 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.
+ However, if a command ends with point inside or immediately after
+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.
+
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
this, the overlay should have a non-@code{nil}
@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 invisible.
@itemize @bullet
@item
about to be executed.
@defvar overlay-arrow-string
-@cindex fringe, and overlay arrow display
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
created if necessary, and put into Help mode. Finally, the buffer is
displayed in some window, but not selected.
-If the @var{forms} do not change the major mode in the output buffer, so
-that it is still Help mode at the end of their execution, then
+If the @var{forms} do not change the major mode in the output buffer,
+so that it is still Help mode at the end of their execution, then
@code{with-output-to-temp-buffer} makes this buffer read-only at the
-end, and also scans it for function and variable names to make them into
-clickable cross-references.
+end, and also scans it for function and variable names to make them
+into clickable cross-references. @xref{Docstring hyperlinks, , Tips
+for Documentation Strings}, in particular the item on hyperlinks in
+documentation strings, for more details.
The string @var{buffer-name} specifies the temporary buffer, which
need not already exist. The argument must be a string, not a buffer.
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,
+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
-* Overlay Properties:: How to read and set properties.
+* 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.
@defun overlay-put overlay prop value
This function sets the value of property @var{prop} recorded in
@var{overlay} to @var{value}. It returns @var{value}.
+@end defun
+
+@defun overlay-properties overlay
+This returns a copy of the property list of @var{overlay}.
@end defun
See also the function @code{get-char-property} which checks both
@table @code
@item priority
@kindex priority @r{(overlay property)}
-This property's value (which should be a nonnegative number) determines
-the priority of the overlay. The priority matters when two or more
-overlays cover the same character and both specify a face for display;
-the one whose @code{priority} value is larger takes priority over the
-other, and its face attributes override the face attributes of the lower
-priority overlay.
+This property's value (which should be a nonnegative integer number)
+determines the priority of the overlay. The priority matters when two
+or more overlays cover the same character and both specify the same
+property; the one whose @code{priority} value is larger takes priority
+over the other. For the @code{face} property, the higher priority
+value does not completely replace the other; instead, its face
+attributes override the face attributes of the lower priority
+@code{face} property.
Currently, all overlays take priority over text properties. Please
avoid using negative priority values, as we have not yet decided just
@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
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
-if it ever becomes empty (i.e., if it spans no characters).
+if it becomes empty (i.e., if its length becomes zero). If you give
+an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
+it immediately.
@item local-map
@cindex keymap of character (and 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}
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}.
+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
@example
(truncate-string-to-width "\tab\t" 12 4)
@result{} "ab"
-(truncate-string-to-width "\tab\t" 12 4 ?\ )
+(truncate-string-to-width "\tab\t" 12 4 ?\s)
@result{} " ab "
@end example
@end defun
+@node Line Height
+@section Line Height
+@cindex line height
+
+ The total height of each display line consists of the height of the
+contents of the line, and additional vertical line spacing below the
+display row.
+
+ The height of the line contents is normally determined from the
+maximum height of any character or image on that display line,
+including the final newline if there is one. (A line that is
+continued doesn't include a final newline.) In the most common case,
+the line height equals the height of the default frame font.
+
+ There are several ways to explicitly control or change the line
+height, either by specifying an absolute height for the display line,
+or by adding additional vertical space below one or all lines.
+
+@kindex line-height @r{(text property)}
+ A newline can have a @code{line-height} text or overlay property
+that controls the total height of the display line ending in that
+newline.
+
+ If the property value is a list @code{(@var{height} @var{total})},
+then @var{height} is used as the actual property value for the
+@code{line-height}, and @var{total} specifies the total displayed
+height of the line, so the line spacing added below the line equals
+the @var{total} height minus the actual line height. In this case,
+the other ways to specify the line spacing are ignored.
+
+ If the property value is @code{t}, the displayed height of the
+line is exactly what its contents demand; no line-spacing is added.
+This case is useful for tiling small images or image slices without
+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
+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:
+
+@table @code
+@item @var{integer}
+If the height spec is a positive integer, the height value is that integer.
+@item @var{float}
+If the height spec is a float, @var{float}, the numeric height value
+is @var{float} times the frame's default line height.
+@item (@var{face} . @var{ratio})
+If the height spec is a cons of the format shown, the 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})
+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
+
+ Thus, any valid non-@code{t} property value specifies a height in pixels,
+@var{line-height}, one way or another. If the line contents' height
+is less than @var{line-height}, Emacs adds extra vertical space above
+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
+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}.
+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
+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
+point number specifies the spacing relative to the default frame line
+height. This overrides line spacings specified for the frame.
+
+@kindex line-spacing @r{(text property)}
+ Finally, a newline can have a @code{line-spacing} text or overlay
+property that controls the height of the display line ending with that
+newline. The property value overrides the default frame line spacing
+and the buffer local @code{line-spacing} variable.
+
+ One way or another, these mechanisms specify a Lisp value for the
+spacing of each line. The value is a height spec, and it translates
+into a Lisp value as described above. However, in this case the
+numeric height value specifies the line spacing, rather than the line
+height.
+
@node Faces
@section Faces
@cindex faces
* 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.
-* Merging Faces:: How Emacs combines the faces specified for a character.
+* 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.
+* 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.
@item fringe
@kindex fringe @r{(face name)}
-This face controls the colors of window fringes, the thin areas on
+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
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]...
This declares @var{face} as a customizable face that defaults according
to @var{spec}. You should not quote the symbol @var{face}. The
argument @var{doc} specifies the face documentation. The keywords you
@item background
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}.
+
@item supports
Whether or not the frame can display the face attributes given in
@var{value}@dots{} (@pxref{Face Attributes}). See the documentation
@example
@group
-(defface region
- `((((type tty) (class color))
- (:background "blue" :foreground "white"))
+ '((((class color) (min-colors 88) (background dark))
+ :background "blue3")
@end group
+ (((class color) (min-colors 88) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 16) (background dark))
+ :background "blue3")
+ (((class color) (min-colors 16) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 8))
+ :background "blue" :foreground "white")
(((type tty) (class mono))
- (:inverse-video t))
- (((class color) (background dark))
- (:background "blue"))
- (((class color) (background light))
- (:background "lightblue"))
- (t (:background "gray")))
+ :inverse-video t)
+ (t :background "gray"))
@group
"Basic face for highlighting the region."
:group 'basic-faces)
attributes}. This table lists all the face attributes, and what they
mean. Note that in general, more than one face can be specified for a
given piece of text; when that happens, the attributes of all the faces
-are merged to specify how to display the text. @xref{Merging 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.
@code{extra-condensed}, @code{condensed}, @code{semi-condensed},
@code{normal}, @code{semi-expanded}, @code{expanded},
@code{extra-expanded}, or @code{ultra-expanded}.
-
+
@item :height
Either the font height, an integer in units of 1/10 point, a floating
point number specifying the amount by which to scale the height of any
underlying face, or a function, which is called with the old height
(from the underlying face), and should return the new height.
-
+
@item :weight
Font weight---a symbol from this series (from most dense to most faint):
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
the terminal supports the feature.
@item :foreground
-Foreground color, a string.
-
+Foreground color, a string. The value can be a system-defined color
+name, or a hexadecimal color specification of the form
+@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
+@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
+blue, and @samp{#ffffff} is white.)
+
@item :background
-Background color, a string.
+Background color, a string, like the foreground color.
@item :inverse-video
Whether or not characters should be displayed in inverse video. The
If @var{frame} is @code{t}, the value is the default for
@var{face} for new frames.
-If @var{inherit} is nil, only attributes directly defined by
+If @var{inherit} is @code{nil}, only attributes directly defined by
@var{face} are considered, so the return value may be
-@code{unspecified}, or a relative value. If @var{inherit} is non-nil,
-@var{face}'s definition of @var{attribute} is merged with the faces
-specified by its @code{:inherit} attribute; however the return value
-may still be @code{unspecified} or relative. If @var{inherit} is a
-face or a list of faces, then the result is further merged with that
-face (or faces), until it becomes specified and absolute.
+@code{unspecified}, or a relative value. If @var{inherit} is
+non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
+with the faces specified by its @code{:inherit} attribute; however the
+return value may still be @code{unspecified} or relative. If
+@var{inherit} is a face or a list of faces, then the result is further
+merged with that face (or faces), until it becomes specified and
+absolute.
To ensure that the return value is always specified and absolute, use
a value of @code{default} for @var{inherit}; this will resolve any
@tindex face-attribute-relative-p
@defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as a
+This function returns non-@code{nil} if @var{value}, when used as
the value of the face attribute @var{attribute}, is relative (that is,
if it modifies an underlying or inherited value of @var{attribute}).
@end defun
If @var{value1} is a relative value for the face attribute
@var{attribute}, returns it merged with the underlying value
@var{value2}; otherwise, if @var{value1} is an absolute value for the
-face a attribute @var{attribute}, returns @var{value1} unchanged.
+face attribute @var{attribute}, returns @var{value1} unchanged.
@end defun
@defun set-face-foreground face color &optional frame
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
-If @var{inherit} is nil, only a color directly defined by the face is
-returned. If @var{inherit} is non-nil, any faces specified by its
+If @var{inherit} is @code{nil}, only a color directly defined by the face is
+returned. If @var{inherit} is non-@code{nil}, any faces specified by its
@code{:inherit} attribute are considered as well, and if @var{inherit}
is a face or a list of faces, then they are also considered, until a
specified color is found. To ensure that the return value is always
This function returns the name of the background stipple pattern of face
@var{face}, or @code{nil} if it doesn't have one.
-If @var{inherit} is nil, only a stipple directly defined by the face
-is returned. If @var{inherit} is non-nil, any faces specified by its
-@code{:inherit} attribute are considered as well, and if @var{inherit}
-is a face or a list of faces, then they are also considered, until a
-specified stipple is found. To ensure that the return value is always
-specified, use a value of @code{default} for @var{inherit}.
+If @var{inherit} is @code{nil}, only a stipple directly defined by the
+face is returned. If @var{inherit} is non-@code{nil}, any faces
+specified by its @code{:inherit} attribute are considered as well, and
+if @var{inherit} is a face or a list of faces, then they are also
+considered, until a specified stipple is found. To ensure that the
+return value is always specified, use a value of @code{default} for
+@var{inherit}.
@end defun
@defun face-font face &optional frame
This function returns the @code{:inverse-video} attribute of face @var{face}.
@end defun
-@node Merging Faces
-@subsection Merging Faces for Display
+@node Displaying Faces
+@subsection Displaying Faces
Here are the ways to specify which faces to use for display of text:
highlighted with the face @code{region} (@pxref{Standard Faces}).
@item
-With special glyphs. Each glyph can specify a particular face
+With special glyphs. Each glyph can specify a particular face
number. @xref{Glyphs}.
@end itemize
font choice, but not all. Part of the choice depends on what character
it is.
- For multibyte characters, typically each font covers only one
-character set. So each character set (@pxref{Character Sets}) specifies
-a registry and encoding to use, with the character set's
-@code{x-charset-registry} property. Its value is a string containing
-the registry and the encoding, with a dash between them:
-
-@example
-(plist-get (charset-plist 'latin-iso8859-1)
- 'x-charset-registry)
- @result{} "ISO8859-1"
-@end example
-
- Unibyte text does not have character sets, so displaying a unibyte
-character takes the registry and encoding from the variable
-@code{face-default-registry}.
-
-@defvar face-default-registry
-This variable specifies which registry and encoding to use in choosing
-fonts for unibyte characters. The value is initialized at Emacs startup
-time from the font the user specified for Emacs.
-@end defvar
-
If the face specifies a fontset name, that fontset determines a
pattern for fonts of the given charset. If the face specifies a font
family, a font pattern is constructed.
all unused fonts as well.
@end defun
+@defvar face-font-rescale-alist
+This variable specifies scaling for certain faces. Its value should
+be a list of elements of the form
+
+@example
+(@var{fontname-regexp} . @var{scale-factor})
+@end example
+
+If @var{fontname-regexp} matches the font name that is about to be
+used, this says to choose a larger similar font according to the
+factor @var{scale-factor}. You would use this feature to normalize
+the font size if certain fonts are bigger or smaller than their
+nominal heights and widths would suggest.
+@end defvar
+
@node Face Functions
@subsection Functions for Working with Faces
@end defun
@defun face-differs-from-default-p face &optional frame
-This returns @code{t} if the face @var{face} displays differently from
-the default face. A face is considered to be ``the same'' as the
-default face if each attribute is either the same as that of the default
-face, or unspecified (meaning to inherit from the default).
+This returns non-@code{nil} if the face @var{face} displays
+differently from the default face.
@end defun
@node Auto Faces
specify these attributes for a face, it will use this font.
The last three elements give additional information about the font.
-@var{fixed-p} is non-nil if the font is fixed-pitch. @var{full} is the
-full name of the font, and @var{registry-and-encoding} is a string
-giving the registry and encoding of the font.
+@var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
+@var{full} is the full name of the font, and
+@var{registry-and-encoding} is a string giving the registry and
+encoding of the font.
The result list is sorted according to the current face font sort order.
@end defun
For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
-For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
+For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.
In addition, when several consecutive fields are wildcards, Emacs
@end example
@noindent
-the font specification for @sc{ascii} characters would be this:
+the font specification for @acronym{ASCII} characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
+@defun set-fontset-font name character fontname &optional frame
+This function modifies the existing fontset @var{name} to
+use the font name @var{fontname} for the character @var{character}.
+
+If @var{name} is @code{nil}, this function modifies the default
+fontset, whose short name is @samp{fontset-default}.
+
+@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
+@var{from} and @var{to} are non-generic characters. In that case, use
+@var{fontname} for all characters in the range @var{from} and @var{to}
+(inclusive).
+
+@var{character} may be a charset. In that case, use
+@var{fontname} for all character in the charsets.
+
+@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+where @var{family} is a family name of a font (possibly including a
+foundry name at the head), @var{registry} is a registry name of a font
+(possibly including an encoding name at the tail).
+
+For instance, this changes the default fontset to use a font of which
+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
+
+@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. 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.
+
+@defvar fringes-outside-margins
+If the value is non-@code{nil}, the frames appear outside
+the display margins.
+@end defvar
+
+@defvar left-fringe-width
+This variable, if non-@code{nil}, specifies the width of the left
+fringe in pixels.
+@end defvar
+
+@defvar right-fringe-width
+This variable, if non-@code{nil}, specifies the width of the right
+fringe in pixels.
+@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{frames-outside-margins})}.
+@end defun
+
+@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,
+when point is at the end of the line, the cursor appears in the right
+fringe.
+@end defvar
+
+@node Fringe Bitmaps
+@section 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 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
+
+@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
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
+is the symbol for the fringe bitmap in the left fringe (or @code{nil}
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
+
+The value is @code{nil} if @var{pos} is not visible in @var{window}.
+If @var{window} is @code{nil}, that stands for the selected window.
+If @var{pos} is @code{nil}, that stands for the value of point in
+@var{window}.
+@end defun
+
+@node Customizing Bitmaps
+@section 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,
+or replaces an existing bitmap with that name.
+
+The argument @var{bits} specifies the image to use. It should be
+either a string or a vector of integers, where each element (an
+integer) corresponds to one row of the bitmap. Each bit of an integer
+corresponds to one pixel of the bitmap, where the low bit corresponds
+to the rightmost pixel of the bitmap.
+
+The height is normally the length of @var{bits}. However, you
+can specify a different height with non-@code{nil} @var{height}. The width
+is normally 8, but you can specify a different width with non-@code{nil}
+@var{width}. The width must be an integer between 1 and 16.
+
+The argument @var{align} specifies the positioning of the bitmap
+relative to the range of rows where it is used; the default is to
+center the bitmap. The allowed values are @code{top}, @code{center},
+or @code{bottom}.
+
+The @var{align} argument may also be a list @code{(@var{align}
+@var{periodic})} where @var{align} is interpreted as described above.
+If @var{periodic} is non-@code{nil}, it specifies that the rows in
+@code{bits} should be repeated enough times to reach the specified
+height.
+
+The return value on success is an integer identifying the new bitmap.
+You should save that integer in a variable so it can be used to select
+this bitmap.
+
+This function signals an error if there are no more free bitmap slots.
+@end defun
+
+@defun destroy-fringe-bitmap bitmap
+This function destroy the fringe bitmap identified by @var{bitmap}.
+If @var{bitmap} identifies a standard fringe bitmap, it actually
+restores the standard definition of that bitmap, instead of
+eliminating it entirely.
+@end defun
+
+@defun set-fringe-bitmap-face bitmap &optional face
+This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
+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.
+@end defun
+
+@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
+@code{scroll-bar-width} specifies how wide they are (@code{nil}
+meaning the default). @xref{Window Frame Parameters}.
+
+@vindex vertical-scroll-bar
+ You can enable or disable scroll bars for a particular buffer,
+by setting the variable @code{vertical-scroll-bar}. This variable
+automatically becomes buffer-local when set. The possible values are
+@code{left}, @code{right}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+
+ You can also control this for individual windows. Call the function
+@code{set-window-scroll-bars} to specify what to do for a specific window:
+
+@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
+This function sets the width and type of scroll bars for window
+@var{window}.
+
+@var{width} specifies the scroll bar width in pixels (@code{nil} means
+use the width specified for the frame). @var{vertical-type} specifies
+whether to have a vertical scroll bar and, if so, where. The possible
+values are @code{left}, @code{right} and @code{nil}, just like the
+values of the @code{vertical-scroll-bars} frame parameter.
+
+The argument @var{horizontal-type} is meant to specify whether and
+where to have horizontal scroll bars, but since they are not
+implemented, it has no effect. If @var{window} is @code{nil}, the
+selected window is used.
+@end defun
+
+@defun window-scroll-bars &optional window
+Report the width and type of scroll bars specified for @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
+@var{cols} @var{vertical-type} @var{horizontal-type})}. The value
+@var{width} is the value that was specified for the width (which may
+be @code{nil}); @var{cols} is the number of columns that the scroll
+bar actually occupies.
+
+@var{horizontal-type} is not actually meaningful.
+@end defun
+
+If you don't specify these values for a window with
+@code{set-window-scroll-bars}, the buffer-local variables
+@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
+displayed control the window's vertical scroll bars. The function
+@code{set-window-buffer} examines these variables. If you change them
+in a buffer that is already visible in a window, you can make the
+window take note of the new values by calling @code{set-window-buffer}
+specifying the same buffer that is already displayed.
+
+@defvar scroll-bar-mode
+This variable, always local in all buffers, controls whether and where
+to put scroll bars in windows displaying the buffer. The possible values
+are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
+the left, and @code{right} to put a scroll bar on the right.
+@end defvar
+
+@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
+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
they mean.
@menu
-* Specified Space:: Displaying one space with a specified width.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
- up or down on the page; adjusting the width
+* Specified Space:: Displaying one space with a specified width.
+* Pixel Specification:: Specifying space width or height in pixels.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ 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
+* Conditional Display:: Making any of the above features conditional
depending on some Lisp expression.
@end menu
@table @code
@item :width @var{width}
-Specifies that the space width should be @var{width} times the normal
-character width. @var{width} can be an integer or floating point
-number.
+If @var{width} is an integer or floating point number, it specifies
+that the space width should be @var{width} times the normal character
+width. @var{width} can also be a @dfn{pixel width} specification
+(@pxref{Pixel Specification}).
@item :relative-width @var{factor}
Specifies that the width of the stretch should be computed from the
character, multiplied by @var{factor}.
@item :align-to @var{hpos}
-Specifies that the space should be wide enough to reach @var{hpos}. The
-value @var{hpos} is measured in units of the normal character width. It
-may be an integer or a floating point number.
+Specifies that the space should be wide enough to reach @var{hpos}.
+If @var{hpos} is a number, it is measured in units of the normal
+character width. @var{hpos} can also be a @dfn{pixel width}
+specification (@pxref{Pixel Specification}).
@end table
You should use one and only one of the above properties. You can
-also specify the height of the space, with other properties:
+also specify the height of the space, with these properties:
@table @code
@item :height @var{height}
-Specifies the height of the space, as @var{height},
-measured in terms of the normal line height.
+Specifies the height of the space.
+If @var{height} is an integer or floating point number, it specifies
+that the space height should be @var{height} times the normal character
+height. The @var{height} may also be a @dfn{pixel height} specification
+(@pxref{Pixel Specification}).
@item :relative-height @var{factor}
Specifies the height of the space, multiplying the ordinary height
of the text having this display specification by @var{factor}.
@item :ascent @var{ascent}
-Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space---that is, the part above the
-baseline. The value of @var{ascent} must be a non-negative number no
-greater than 100.
+If the value of @var{ascent} is a non-negative number no greater than
+100, it specifies that @var{ascent} percent of the height of the space
+should be considered as the ascent of the space---that is, the part
+above the baseline. The ascent may also be specified in pixel units
+with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
+
@end table
Don't use both @code{:height} and @code{:relative-height} together.
+ The @code{:height} and @code{:align-to} properties are supported on
+non-graphic terminals, but the other space properties in this section
+are not.
+
+@node Pixel Specification
+@subsection Pixel Specification for Spaces
+@cindex spaces, pixel specification
+
+ The value of the @code{:width}, @code{:align-to}, @code{:height},
+and @code{:ascent} properties can be a special kind of expression that
+is evaluated during redisplay. The result of the evaluation is used
+as an absolute number of pixels.
+
+ The following expressions are supported:
+
+@example
+@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
+ @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
+
+ The form @var{num} specifies a fraction of the default frame font
+height or width. The form @code{(@var{num})} specifies an absolute
+number of pixels. If @var{num} is a symbol, @var{symbol}, its
+buffer-local variable binding is used.
+
+ The @code{in}, @code{mm}, and @code{cm} units specify the number of
+pixels per inch, millimeter, and centimeter, respectively. The
+@code{width} and @code{height} units correspond to the default width
+and height of the current face. An image specification @code{image}
+corresponds to the width or height of the image.
+
+ The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
+@code{right-margin}, @code{scroll-bar}, and @code{text} elements
+specify to the width of the corresponding area of the window.
+
+ The @code{left}, @code{center}, and @code{right} positions can be
+used with @code{:align-to} to specify a position relative to the left
+edge, center, or right edge of the text area.
+
+ Any of the above window elements (except @code{text}) can also be
+used with @code{:align-to} to specify that the position is relative to
+the left edge of the given area. Once the base offset for a relative
+position has been set (by the first occurrence of one of these
+symbols), further occurrences of these symbols are interpreted as the
+width of the specified area. For example, to align to the center of
+the left-margin, use
+
+@example
+:align-to (+ left-margin (0.5 . left-margin))
+@end example
+
+ If no specific base offset is set for alignment, it is always relative
+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,
+@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.
+
+ The form @code{(+ @var{expr} ...)} adds up the value of the
+expressions. The form @code{(- @var{expr} ...)} negates or subtracts
+the value of the expressions.
+
@node Other Display Specs
@subsection Other Display Specifications
+ Here are the other sorts of display specifications that you can use
+in the @code{display} text property.
+
@table @code
@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.
+@item (slice @var{x} @var{y} @var{width} @var{height})
+This specification together with @code{image} specifies a @dfn{slice}
+(a partial area) of the image to display. The elements @var{y} and
+@var{x} specify the top left corner of the slice, within the image;
+@var{width} and @var{height} specify the width and height of the
+slice. Integer values are numbers of pixels. A floating point number
+in the range 0.0--1.0 stands for that fraction of the width or height
+of the entire image.
+
@item ((margin nil) @var{string})
@itemx @var{string}
A display specification of this form means to display @var{string}
@defun set-window-margins window left &optional right
@tindex set-window-margins
This function specifies the margin widths for window @var{window}.
-The argument @var{left} controls the left margin and
+The argument @var{left} controls the left margin and
@var{right} controls the right margin (default @code{0}).
@end defun
@code{display} property, this feature is available starting in Emacs 21.
Emacs can display a number of different image formats; some of them
-are supported only if particular support libraries are installed on your
-machine. The supported image formats include XBM, XPM (needing the
+are supported only if particular support libraries are installed on
+your machine. In some environments, Emacs allows loading 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),
@defvar image-types
This variable contains a list of those image type symbols that are
-supported in the current configuration.
+potentially supported in the current configuration.
+@emph{Potentially} here means that Emacs knows about the image types,
+not necessarily that they can be loaded (they could depend on
+unavailable dynamic libraries, for example).
+
+To know which image types are really available, use
+@code{image-type-available-p}.
+@end defvar
+
+@defvar image-library-alist
+This in an alist of image types vs external libraries needed to
+display them.
+
+Each element is a list @code{(@var{image-type} @var{library}...)},
+where the car is a supported image format from @code{image-types}, and
+the rest are strings giving alternate filenames for the corresponding
+external libraries to load.
+
+Emacs tries to load the libraries in the order they appear on the
+list; if none is loaded, the running session of Emacs won't support
+the image type. @code{pbm} and @code{xbm} don't need to be listed;
+they're always supported.
+
+This variable is ignored if the image libraries are statically linked
+into Emacs.
@end defvar
+@defun image-type-available-p type
+@findex image-type-available-p
+
+This function returns non-@code{nil} if image type @var{type} is
+available, i.e., if images of this type can be loaded and displayed in
+Emacs. @var{type} should be one of the types contained in
+@code{image-types}.
+
+For image types whose support libraries are statically linked, this
+function always returns @code{t}; for other image types, it returns
+@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
+@end defun
+
@menu
* Image Descriptors:: How to specify an image for use in @code{:display}.
* XBM Images:: Special features for XBM format.
@item :margin @var{margin}
The @code{:margin} property specifies how many pixels to add as an
-extra margin around the image. The value, @var{margin}, must be a a
+extra margin around the image. The value, @var{margin}, must be a
non-negative number, or a pair @code{(@var{x} . @var{y})} of such
numbers. If it is a pair, @var{x} specifies how many pixels to add
horizontally, and @var{y} specifies how many pixels to add vertically.
@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
specifying the color to assume for the background of the image.
-If @var{mask} is nil, remove a mask from the image, if it has one. Images
-in some formats include a mask which can be removed by specifying
-@code{:mask nil}.
+If @var{mask} is @code{nil}, remove a mask from the image, if it has
+one. Images in some formats include a mask which can be removed by
+specifying @code{:mask nil}.
+
+@item :pointer @var{shape}
+This specifies the pointer shape when the mouse pointer is over this
+image. @xref{Pointer Shape}, for available pointer shapes.
+
+@item :map @var{map}
+This associates an image map of @dfn{hot spots} with this image.
+
+An image map is an alist where each element has the format
+@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
+as either a rectangle, a circle, or a polygon.
+
+A rectangle is a cons
+@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
+which specifies the pixel coordinates of the upper left and bottom right
+corners of the rectangle area.
+
+A circle is a cons
+@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
+which specifies the center and the radius of the circle; @var{r} may
+be a float or integer.
+
+A polygon is a cons
+@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
+@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.
+@xref{Pointer Shape}, for available pointer shapes.
+
+When you click the mouse when the mouse pointer is over a hot-spot, an
+event is composed by combining the @var{id} of the hot-spot with the
+mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
+@var{id} is @code{area4}.
@end table
@defun image-mask-p spec &optional frame
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
+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.
@item :index @var{index}
You can use @code{:index} to specify one image from a GIF file that
contains more than one image. This property specifies use of image
-number @var{index} from the file. An error is signaled if the GIF file
-doesn't contain an image with index @var{index}.
+number @var{index} from the file. If the GIF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
@end table
@ignore
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
-@defun create-image file &optional type &rest props
+@defun create-image file-or-data &optional type data-p &rest props
@tindex create-image
This function creates and returns an image descriptor which uses the
-data in @var{file}.
+data in @var{file-or-data}. @var{file-or-data} can be a file name or
+a string containing the image data; @var{data-p} should be @code{nil}
+for the former case, non-@code{nil} for the latter case.
The optional argument @var{type} is a symbol specifying the image type.
If @var{type} is omitted or @code{nil}, @code{create-image} tries to
properties---for example,
@example
-(create-image "foo.xpm" 'xpm :heuristic-mask t)
+(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
The function returns @code{nil} if images of this type are not
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image &optional string area
+@defun insert-image image &optional string area slice
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{nil} or omitted, the image is displayed at point within the
buffer's text.
+The argument @var{slice} specifies a slice of the image to insert. If
+@var{slice} is @code{nil} or omitted the whole image is inserted.
+Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
+@var{height})} which specifies the @var{x} and @var{y} positions and
+@var{width} and @var{height} of the image area to insert. Integer
+values are in units of pixels. A floating point number in the range
+0.0--1.0 stands for that fraction of the width or height of the entire
+image.
+
Internally, this function inserts @var{string} in the buffer, and gives
it a @code{display} property which specifies @var{image}. @xref{Display
Property}.
@end defun
+@defun insert-sliced-image image &optional string area rows cols
+This function inserts @var{image} in the current buffer at point, like
+@code{insert-image}, but splits the image into @var{rows}x@var{cols}
+equally sized slices.
+@end defun
+
@defun put-image image pos &optional string area
This function puts image @var{image} in front of @var{pos} in the
current buffer. The argument @var{pos} should be an integer or a
@tindex image-size
This function returns the size of an image as a pair
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
-specification. @var{pixels} non-nil means return sizes measured in
-pixels, otherwise return sizes measured in canonical character units
-(fractions of the width/height of the frame's default font).
-@var{frame} is the frame on which the image will be displayed.
+specification. @var{pixels} non-@code{nil} means return sizes
+measured in pixels, otherwise return sizes measured in canonical
+character units (fractions of the width/height of the frame's default
+font). @var{frame} is the frame on which the image will be displayed.
@var{frame} null or omitted means use the selected frame (@pxref{Input
Focus}).
@end defun
are cleared.
@end defun
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+ The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+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}.
+
+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
+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
+programmers---for users, the result is about the same). The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties:: Button properties with special meanings.
+* Button Types:: Defining common properties for classes of buttons.
+* 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
+@subsection Button Properties
+@cindex 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:
+
+@table @code
+
+@item action
+@kindex action @r{(button property)}
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}. By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+@kindex mouse-action @r{(button property)}
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}). If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+@kindex face @r{(button property)}
+This is an Emacs face controlling how buttons of this type are
+displayed; by default this is the @code{button} face.
+
+@item mouse-face
+@kindex mouse-face @r{(button property)}
+This is an additional face which controls appearance during
+mouse-overs (merged with the usual button face); by default this is
+the usual Emacs @code{highlight} face.
+
+@item keymap
+@kindex keymap @r{(button property)}
+The button's keymap, defining bindings active within the button
+region. By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET} and
+@key{mouse-2} to invoke the button.
+
+@item type
+@kindex type @r{(button property)}
+The button-type of the button. When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+@kindex help-index @r{(button property)}
+A string displayed by the Emacs tool-tip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item follow-link
+@kindex follow-link @r{(button property)}
+The follow-link property, defining how a @key{Mouse-1} click behaves
+on this button, @xref{Links and Mouse-1}.
+
+@item button
+@kindex button @r{(button property)}
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+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
+@subsection Button Types
+@cindex button types
+
+ Every button has a button @emph{type}, which defines default values
+for the button's properties. Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
+
+@defun define-button-type name &rest properties
+@tindex define-button-type
+Define a `button type' called @var{name}. The remaining arguments
+form a sequence of @var{property value} pairs, specifying default
+property values for buttons with this type (a button's type may be set
+by giving it a @code{type} property when creating the button, using
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values. Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+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
+doing so usually makes the resulting code clearer and more efficient.
+
+@node Making Buttons
+@subsection 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
+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,
+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}.
+
+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
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}. Any properties not explicitly specified
+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
+(@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.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+Insert a button with the label @var{label}.
+@end defun
+
+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):
+
+@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.
+@end defun
+
+@defun insert-text-button label &rest properties
+@tindex insert-text-button
+Insert a button with the label @var{label}, 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
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+invocation function when it is invoked.
+
+@defun button-start button
+@tindex button-start
+Return the position at which @var{button} starts.
+@end defun
+
+@defun button-end button
+@tindex button-end
+Return the position at which @var{button} ends.
+@end defun
+
+@defun button-get button prop
+@tindex button-get
+Get the property of button @var{button} named @var{prop}.
+@end defun
+
+@defun button-put button prop val
+@tindex button-put
+Set @var{button}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-activate button &optional use-mouse-action
+@tindex button-activate
+Call @var{button}'s @code{action} property (i.e., invoke it). If
+@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@end defun
+
+@defun button-label button
+@tindex button-label
+Return @var{button}'s text label.
+@end defun
+
+@defun button-type button
+@tindex button-type
+Return @var{button}'s button-type.
+@end defun
+
+@defun button-has-type-p button type
+@tindex button-has-type-p
+Return @code{t} if @var{button} has button-type @var{type}, or one of
+@var{type}'s subtypes.
+@end defun
+
+@defun button-at pos
+@tindex button-at
+Return the button at position @var{pos} in the current buffer, or @code{nil}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+buttons in an Emacs buffer.
+
+@code{push-button} is the command that a user uses to actually `push'
+a button, and is bound by default in the button itself to @key{RET}
+and to @key{mouse-2} using a region-specific keymap. Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+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.
+
+@deffn Command push-button &optional pos use-mouse-action
+@tindex push-button
+Perform the action specified by a button at location @var{pos}.
+@var{pos} may be either a buffer position or a mouse-event. If
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used. If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@end deffn
+
+@deffn Command forward-button n &optional wrap display-message
+@tindex forward-button
+Move to the @var{n}th next button, or @var{n}th previous button if
+@var{n} is negative. If @var{n} is zero, move to the start of any
+button at point. If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end. If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
+@end deffn
+
+@deffn Command backward-button n &optional wrap display-message
+@tindex backward-button
+Move to the @var{n}th previous button, or @var{n}th next button if
+@var{n} is negative. If @var{n} is zero, move to the start of any
+button at point. If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end. If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
+@end deffn
+
+@defun next-button pos &optional count-current
+@tindex next-button
+Return the next button after position @var{pos} in the current buffer.
+If @var{count-current} is non-@code{nil}, count any button at
+@var{pos} in the search, instead of starting at the next button.
+@end defun
+
+@defun previous-button pos &optional count-current
+@tindex previous-button
+Return the @var{n}th button before position @var{pos} in the current
+buffer. If @var{count-current} is non-@code{nil}, count any button at
+@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
All other codes in the range 0 through 31, and code 127, display in one
of two ways according to the value of @code{ctl-arrow}. If it is
non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @sc{ascii} code for @samp{^}. (A display table can
+first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
just like the codes in the range 128 to 255.
On MS-DOS terminals, Emacs arranges by default for the character code
127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon. This glyph is used to display non-@sc{ascii} characters
+empty polygon. This glyph is used to display non-@acronym{ASCII} characters
that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
emacs, The GNU Emacs Manual}.
@item
Character codes 128 through 255 map to sequences of four glyphs, where
-the first glyph is the @sc{ascii} code for @samp{\}, and the others are
+the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
digit characters representing the character code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
buffers that do not override it. @xref{Default Value}.
@end defvar
-@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
-each empty line at the end of the buffer, on terminals that
-support it (window systems).
-@end defopt
-
@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
@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
@cindex display table
You can use the @dfn{display table} feature to control how all possible
character codes display on the screen. This is useful for displaying
-European languages that have letters not in the @sc{ascii} character
+European languages that have letters not in the @acronym{ASCII} character
set.
The display table maps each character code into a sequence of
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@menu
-* Display Table Format:: What a display table consists of.
-* Active Display Table:: How Emacs selects a display table to use.
-* Glyphs:: How to define a glyph, and what glyphs mean.
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How Emacs selects a display table to use.
+* Glyphs:: How to define a glyph, and what glyphs mean.
@end menu
@node Display Table Format
@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 truncation---the display table has no effect in these
+indicate continuation---the display table has no effect in these
situations.
@item 2
The glyph for indicating a character displayed as an octal character
@defvar glyph-table
The value of this variable is the current glyph table. It should be a
-vector; the @var{g}th element defines glyph code @var{g}.
+vector; the @var{g}th element defines glyph code @var{g}.
If a glyph code is greater than or equal to the length of the glyph
table, that code is automatically simple. If the value of
the window system, and creating the initial window. Users should not
interfere with it.
@end defvar
+
+@ignore
+ arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6
+@end ignore