@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
-@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
+@node Display, System Interface, Processes, Top
@chapter Emacs Display
This chapter describes a number of features related to the display
* 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.
+* 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
@node Refresh Screen
@section Refreshing the Screen
-The function @code{redraw-frame} redisplays the entire contents of a
-given frame (@pxref{Frames}).
+ The function @code{redraw-frame} clears and redisplays the entire
+contents of a given frame (@pxref{Frames}). This is useful if the
+screen is corrupted.
@c Emacs 19 feature
@defun redraw-frame frame
This function clears and redisplays frame @var{frame}.
@end defun
-Even more powerful is @code{redraw-display}:
+ Even more powerful is @code{redraw-display}:
@deffn Command redraw-display
This function clears and redisplays all visible frames.
@end deffn
+ This function calls for redisplay of certain windows, the next time
+redisplay is done, but does not clear them first.
+
+@defun force-window-update &optional object
+This function forces redisplay of some or all windows. If
+@var{object} is a window, it forces redisplay of that window. If
+@var{object} is a buffer or buffer name, it forces redisplay of all
+windows displaying that buffer. If @var{object} is @code{nil} (or
+omitted), 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
@defvar redisplay-dont-pause
If this variable is non-@code{nil}, pending input does not
prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available. This feature is available
-as of Emacs 21.
+regardless of whether input is available.
@end defvar
You can request a display update, but only if no input is pending,
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
+ On a window system display, the @samp{$} and @samp{\} indicators are
+replaced with arrow images displayed in the window fringes
+(@pxref{Fringes}).
+
Note that continuation is different from filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
precisely at the right margin, not at a word boundary. @xref{Filling}.
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
- You can override the glyphs that indicate continuation or truncation
-using the display table; see @ref{Display Tables}.
-
If your buffer contains @emph{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
redisplay slow. The column computation and indentation functions also
@cindex error display
@cindex echo area
-The @dfn{echo area} is used for displaying messages made with the
-@code{message} primitive, and for echoing keystrokes. It is not the
-same as the minibuffer, despite the fact that the minibuffer appears
-(when active) in the same place on the screen as the echo area. The
-@cite{GNU Emacs Manual} specifies the rules for resolving conflicts
-between the echo area and the minibuffer for use of that screen space
-(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
-Error messages appear in the echo area; see @ref{Errors}.
+The @dfn{echo area} is used for displaying error messages
+(@pxref{Errors}), for messages made with the @code{message} primitive,
+and for echoing keystrokes. It is not the same as the minibuffer,
+despite the fact that the minibuffer appears (when active) in the same
+place on the screen as the echo area. The @cite{GNU Emacs Manual}
+specifies the rules for resolving conflicts between the echo area and
+the minibuffer for use of that screen space (@pxref{Minibuffer,, The
+Minibuffer, emacs, The GNU Emacs Manual}).
You can write output in the echo area by using the Lisp printing
functions with @code{t} as the stream (@pxref{Output Functions}), or as
follows:
@defun message string &rest arguments
-This function displays a one-line message in the echo area. The
+This function displays a message in the echo area. The
argument @var{string} is similar to a C language @code{printf} control
-string. See @code{format} in @ref{String Conversion}, for the details
+string. See @code{format} in @ref{Formatting Strings}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
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.
+
@example
@group
(message "Minibuffer depth is %d."
@end example
To automatically display a message in the echo area or in a pop-buffer,
-depending on its size, use @code{display-message-or-buffer}.
+depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
+@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
@end defun
@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+@tindex display-message-or-buffer
This function displays the message @var{message}, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
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 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
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
text property (@pxref{Text Properties}) or a property of an overlay
-(@pxref{Overlays}).
+(@pxref{Overlays}). Cursor motion also partly ignores these
+characters; if the command loop finds point within them, it moves
+point to the other side of them.
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
the default value of @code{buffer-invisibility-spec}, this is how the
-@code{invisible} property works.
+@code{invisible} property works. You should normally use @code{t}
+as the value of the @code{invisible} property if you don't plan
+to set @code{buffer-invisibility-spec} yourself.
More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make 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}
@code{buffer-invisibility-spec} and removing elements from it.
@defun add-to-invisibility-spec element
-Add the element @var{element} to @code{buffer-invisibility-spec}
-(if it is not already present in that list).
+This function adds the element @var{element} to
+@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
+was @code{t}, it changes to a list, @code{(t)}, so that text whose
+@code{invisible} property is @code{t} remains invisible.
@end defun
@defun remove-from-invisibility-spec element
-Remove the element @var{element} from @code{buffer-invisibility-spec}.
-This does nothing if @var{element} is not in the list.
+This removes the element @var{element} from
+@code{buffer-invisibility-spec}. This does nothing if @var{element}
+is not in the list.
@end defun
- One convention about the use of @code{buffer-invisibility-spec} is
-that a major mode should use the mode's own name as an element of
-@code{buffer-invisibility-spec} and as the value of the @code{invisible}
-property:
+ A convention for use of @code{buffer-invisibility-spec} is that a
+major mode should use the mode's own name as an element of
+@code{buffer-invisibility-spec} and as the value of the
+@code{invisible} property:
@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.
+@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
+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
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
- The first variant, explicit selective display, is designed for use in
-a Lisp program: it controls which lines are hidden by altering the text.
-The invisible text feature (@pxref{Invisible Text}) has partially
-replaced this feature.
+ The first variant, explicit selective display, is designed for use
+in a Lisp program: it controls which lines are hidden by altering the
+text. This kind of hiding in some ways resembles the effect of the
+@code{invisible} property (@pxref{Invisible Text}), but the two
+features are different and do not work the same way.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m). The text that
-was formerly a line following that newline is now invisible. Strictly
-speaking, it is temporarily no longer a line at all, since only newlines
-can separate lines; it is now part of the previous line.
+was formerly a line following that newline is now hidden. Strictly
+speaking, it is temporarily no longer a line at all, since only
+newlines can separate lines; it is now part of the previous line.
Selective display does not directly affect editing commands. For
-example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-@code{next-line} skips invisible lines, since it searches only for
-newlines. Modes that use selective display can also define commands
-that take account of the newlines, or that make parts of the text
-visible or invisible.
+example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
+into hidden text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For
+example, @code{next-line} skips hidden lines, since it searches only
+for newlines. Modes that use selective display can also define
+commands that take account of the newlines, or that control which
+parts of the text are hidden.
When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines. This means that when you next read
-in the file, it looks OK, with nothing invisible. The selective display
+in the file, it looks OK, with nothing hidden. The selective display
effect is seen only within Emacs.
@defvar selective-display
This buffer-local variable enables selective display. This means that
-lines, or portions of lines, may be made invisible.
+lines, or portions of lines, may be made hidden.
@itemize @bullet
@item
If the value of @code{selective-display} is @code{t}, then the character
-control-m marks the start of invisible text; the control-m, and the rest
+control-m marks the start of hidden text; the control-m, and the rest
of the line following it, are not displayed. This is explicit selective
display.
displayed.
@end itemize
-When some portion of a buffer is invisible, the vertical movement
+When some portion of a buffer is hidden, the vertical movement
commands operate as if that portion did not exist, allowing a single
-@code{next-line} command to skip any number of invisible lines.
+@code{next-line} command to skip any number of hidden lines.
However, character movement commands (such as @code{forward-char}) do
-not skip the invisible portion, and it is possible (if tricky) to insert
-or delete text in an invisible portion.
+not skip the hidden portion, and it is possible (if tricky) to insert
+or delete text in an hidden portion.
In the examples below, we show the @emph{display appearance} of the
buffer @code{foo}, which changes with the value of
@defvar selective-display-ellipses
If this buffer-local variable is non-@code{nil}, then Emacs displays
-@samp{@dots{}} at the end of a line that is followed by invisible text.
+@samp{@dots{}} at the end of a line that is followed by hidden text.
This example is a continuation of the previous one.
@example
(@samp{@dots{}}). @xref{Display Tables}.
@end defvar
-@node Overlay Arrow
-@section The Overlay Arrow
-@cindex overlay arrow
-
- The @dfn{overlay arrow} is useful for directing the user's attention
-to a particular line in a buffer. For example, in the modes used for
-interface to debuggers, the overlay arrow indicates the line of code
-about to be executed.
-
-@defvar overlay-arrow-string
-This variable holds the string to display to call attention to a
-particular line, or @code{nil} if the arrow feature is not in use.
-On a graphical display the contents of the string are ignored; instead a
-glyph is displayed in the fringe area to the left of the display area.
-@end defvar
-
-@defvar overlay-arrow-position
-This variable holds a marker that indicates where to display the overlay
-arrow. It should point at the beginning of a line. On a non-graphical
-display the arrow text
-appears at the beginning of that line, overlaying any text that would
-otherwise appear. Since the arrow is usually short, and the line
-usually begins with indentation, normally nothing significant is
-overwritten.
-
-The overlay string is displayed only in the buffer that this marker
-points into. Thus, only one buffer can have an overlay arrow at any
-given time.
-@c !!! overlay-arrow-position: but the overlay string may remain in the display
-@c of some other buffer until an update is required. This should be fixed
-@c now. Is it?
-@end defvar
-
- You can do a similar job by creating an overlay with a
-@code{before-string} property. @xref{Overlay Properties}.
-
@node Temporary Displays
@section Temporary Displays
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.
@defvar temp-buffer-setup-hook
@tindex temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
-evaluating @var{body}. When the hook runs, the help buffer is current.
-This hook is normally set up with a function to put the buffer in Help
-mode.
+evaluating @var{body}. When the hook runs, the temporary buffer is
+current. This hook is normally set up with a function to put the
+buffer in Help mode.
@end defvar
@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
-displaying the help buffer. When the hook runs, the help buffer is
-current, and the window it was displayed in is selected. This hook is
-normally set up with a function to make the buffer read only, and find
-function names and variable names in it, provided the major mode is
-still Help mode.
+displaying the temporary buffer. When the hook runs, the temporary buffer
+is current, and the window it was displayed in is selected. This hook
+is normally set up with a function to make the buffer read only, and
+find function names and variable names in it, provided the major mode
+is Help mode.
@end defvar
@defun momentary-string-display string position &optional char message
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.
- What properties do to the screen display.
* Managing Overlays:: Creating and moving overlays.
+* Overlay Properties:: How to read and set properties.
+ What properties do to the screen display.
* Finding Overlays:: Searching for overlays.
@end menu
+@node Managing Overlays
+@subsection Managing Overlays
+
+ This section describes the functions to create, delete and move
+overlays, and to examine their contents. Overlay changes are not
+recorded in the buffer's undo list, since the overlays are not
+part of the buffer's contents.
+
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
+@defun make-overlay start end &optional buffer front-advance rear-advance
+This function creates and returns an overlay that belongs to
+@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
+and @var{end} must specify buffer positions; they may be integers or
+markers. If @var{buffer} is omitted, the overlay is created in the
+current buffer.
+
+The arguments @var{front-advance} and @var{rear-advance} specify the
+insertion type for the start of the overlay and for the end of the
+overlay, respectively. @xref{Marker Insertion Types}. If
+@var{front-advance} is non-@code{nil}, text inserted at the beginning
+of the overlay is excluded from the overlay. If @var{read-advance} is
+non-@code{nil}, text inserted at the beginning of the overlay is
+included in the overlay.
+@end defun
+
+@defun overlay-start overlay
+This function returns the position at which @var{overlay} starts,
+as an integer.
+@end defun
+
+@defun overlay-end overlay
+This function returns the position at which @var{overlay} ends,
+as an integer.
+@end defun
+
+@defun overlay-buffer overlay
+This function returns the buffer that @var{overlay} belongs to. It
+returns @code{nil} if @var{overlay} has been deleted.
+@end defun
+
+@defun delete-overlay overlay
+This function deletes @var{overlay}. The overlay continues to exist as
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
+
+A deleted overlay is not permanently disconnected. You can give it a
+position in a buffer again by calling @code{move-overlay}.
+@end defun
+
+@defun move-overlay overlay start end &optional buffer
+This function moves @var{overlay} to @var{buffer}, and places its bounds
+at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
+
+The return value is @var{overlay}.
+
+This is the only valid way to change the endpoints of an overlay. Do
+not try modifying the markers in the overlay by hand, as that fails to
+update other vital data structures and can cause some overlays to be
+``lost''.
+@end defun
+
+@defun remove-overlays &optional start end name value
+This function removes all the overlays between @var{start} and
+@var{end} whose property @var{name} has the value @var{value}. It can
+move the endpoints of the overlays in the region, or split them.
+
+If @var{name} is omitted or @code{nil}, it means to delete all overlays in
+the specified region. If @var{start} and/or @var{end} are omitted or
+@code{nil}, that means the beginning and end of the buffer respectively.
+Therefore, @code{(remove-overlays)} removes all the overlays in the
+current buffer.
+@end defun
+
+ Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+ @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 10
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+ @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+ @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+ @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+ @result{} 5
+(overlay-end foo)
+ @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+ @result{} nil
+;; @r{Verify it is deleted.}
+foo
+ @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+ @result{} nil
+(overlay-end foo)
+ @result{} nil
+(overlay-buffer foo)
+ @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+ @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 20
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay does not change its properties.}
+(overlay-get foo 'happy)
+ @result{} t
+@end example
+
@node Overlay Properties
@subsection Overlay Properties
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
-most respects they are different. Text properties are considered a part
-of the text; overlays are specifically considered not to be part of the
-text. Thus, copying text between various buffers and strings preserves
-text properties, but does not try to preserve overlays. Changing a
-buffer's text properties marks the buffer as modified, while moving an
-overlay or changing its properties does not. Unlike text property
-changes, overlay changes are not recorded in the buffer's undo list.
-@xref{Text Properties}, for comparison.
-
- These functions are used for reading and writing the properties of an
-overlay:
+most respects they are different. @xref{Text Properties}, for comparison.
+
+ Text properties are considered a part of the text; overlays and
+their properties are specifically considered not to be part of the
+text. Thus, copying text between various buffers and strings
+preserves text properties, but does not try to preserve overlays.
+Changing a buffer's text properties marks the buffer as modified,
+while moving an overlay or changing its properties does not. Unlike
+text property changes, overlay property changes are not recorded in
+the buffer's undo list.
+
+ These functions read and set the properties of an overlay:
@defun overlay-get overlay prop
This function returns the value of property @var{prop} recorded in
@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
A face name (a symbol or string).
@item
-Starting in Emacs 21, a property list of face attributes. This has the
-form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
-face attribute name and @var{value} is a meaningful value for that
-attribute. With this feature, you do not need to create a face each
-time you want to specify a particular attribute for certain text.
-@xref{Face Attributes}.
+A property list of face attributes. This has the form (@var{keyword}
+@var{value} @dots{}), where each @var{keyword} is a face attribute
+name and @var{value} is a meaningful value for that attribute. With
+this feature, you do not need to create a face each time you want to
+specify a particular attribute for certain text. @xref{Face
+Attributes}.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})} or
@kindex display @r{(overlay property)}
This property activates various features that change the
way text is displayed. For example, it can make text appear taller
-or shorter, higher or lower, wider or narror, or replaced with an image.
+or shorter, higher or lower, wider or narrower, or replaced with an image.
@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
-help-echo}. This feature is available starting in Emacs 21.
+help-echo}.
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
@item after-string
@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
-the overlay. The string does not appear in the buffer in any
-sense---only on the screen.
-
-@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).
-
-@item local-map
-@cindex keymap of character (and overlays)
-@kindex local-map @r{(overlay property)}
-If this property is non-@code{nil}, it specifies a keymap for a portion
-of the text. The property's value replaces the buffer's local map, when
-the character after point is within the overlay. @xref{Active Keymaps}.
-@end table
-
-@node Managing Overlays
-@subsection Managing Overlays
-
- This section describes the functions to create, delete and move
-overlays, and to examine their contents.
-
-@defun make-overlay start end &optional buffer front-advance rear-advance
-This function creates and returns an overlay that belongs to
-@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
-and @var{end} must specify buffer positions; they may be integers or
-markers. If @var{buffer} is omitted, the overlay is created in the
-current buffer.
-
-The arguments @var{front-advance} and @var{rear-advance} specify the
-insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}.
-@end defun
-
-@defun overlay-start overlay
-This function returns the position at which @var{overlay} starts,
-as an integer.
-@end defun
-
-@defun overlay-end overlay
-This function returns the position at which @var{overlay} ends,
-as an integer.
-@end defun
-
-@defun overlay-buffer overlay
-This function returns the buffer that @var{overlay} belongs to.
-@end defun
-
-@defun delete-overlay overlay
-This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, and its property list is unchanged, but it ceases to be
-attached to the buffer it belonged to, and ceases to have any effect on
-display.
-
-A deleted overlay is not permanently disconnected. You can give it a
-position in a buffer again by calling @code{move-overlay}.
-@end defun
-
-@defun move-overlay overlay start end &optional buffer
-This function moves @var{overlay} to @var{buffer}, and places its bounds
-at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
-must specify buffer positions; they may be integers or markers.
-
-If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
-was already associated with; if @var{overlay} was deleted, it goes into
-the current buffer.
-
-The return value is @var{overlay}.
+the overlay. The string does not appear in the buffer in any
+sense---only on the screen.
-This is the only valid way to change the endpoints of an overlay. Do
-not try modifying the markers in the overlay by hand, as that fails to
-update other vital data structures and can cause some overlays to be
-``lost''.
-@end defun
+@item evaporate
+@kindex evaporate @r{(overlay property)}
+If this property is non-@code{nil}, the overlay is deleted automatically
+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.
- Here are some examples:
+@item local-map
+@cindex keymap of character (and overlays)
+@kindex local-map @r{(overlay property)}
+If this property is non-@code{nil}, it specifies a keymap for a portion
+of the text. The property's value replaces the buffer's local map, when
+the character after point is within the overlay. @xref{Active Keymaps}.
-@example
-;; @r{Create an overlay.}
-(setq foo (make-overlay 1 10))
- @result{} #<overlay from 1 to 10 in display.texi>
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 10
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @r{Give it a property we can check later.}
-(overlay-put foo 'happy t)
- @result{} t
-;; @r{Verify the property is present.}
-(overlay-get foo 'happy)
- @result{} t
-;; @r{Move the overlay.}
-(move-overlay foo 5 20)
- @result{} #<overlay from 5 to 20 in display.texi>
-(overlay-start foo)
- @result{} 5
-(overlay-end foo)
- @result{} 20
-;; @r{Delete the overlay.}
-(delete-overlay foo)
- @result{} nil
-;; @r{Verify it is deleted.}
-foo
- @result{} #<overlay in no buffer>
-;; @r{A deleted overlay has no position.}
-(overlay-start foo)
- @result{} nil
-(overlay-end foo)
- @result{} nil
-(overlay-buffer foo)
- @result{} nil
-;; @r{Undelete the overlay.}
-(move-overlay foo 1 20)
- @result{} #<overlay from 1 to 20 in display.texi>
-;; @r{Verify the results.}
-(overlay-start foo)
- @result{} 1
-(overlay-end foo)
- @result{} 20
-(overlay-buffer foo)
- @result{} #<buffer display.texi>
-;; @r{Moving and deleting the overlay does not change its properties.}
-(overlay-get foo 'happy)
- @result{} t
-@end example
+@item keymap
+@kindex keymap @r{(overlay property)}
+The @code{keymap} property is similar to @code{local-map} but overrides the
+buffer's local map (and the map specified by the @code{local-map}
+property) rather than replacing it.
+@end table
@node Finding Overlays
@subsection Searching for Overlays
(let ((overlays (overlays-at (point)))
found)
(while overlays
- (let ((overlay (cdr overlays)))
+ (let ((overlay (car overlays)))
(if (overlay-get overlay prop)
(setq found (cons overlay found))))
(setq overlays (cdr overlays)))
@defun next-overlay-change pos
This function returns the buffer position of the next beginning or end
-of an overlay, after @var{pos}.
+of an overlay, after @var{pos}. If there is none, it returns
+@code{(point-max)}.
@end defun
@defun previous-overlay-change pos
This function returns the buffer position of the previous beginning or
-end of an overlay, before @var{pos}.
+end of an overlay, before @var{pos}. If there is none, it returns
+@code{(point-min)}.
@end defun
Here's an easy way to use @code{next-overlay-change} to search for the
if it were displayed in the current buffer and the selected window.
@end defun
-@defun truncate-string-to-width string width &optional start-column padding
+@defun truncate-string-to-width string width &optional start-column padding ellipsis
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
+If @var{ellipsis} is non-@code{nil}, it should be a string which will
+replace the end of @var{str} (including any padding) if it extends
+beyond @var{end-column}, unless the display width of @var{str} is
+equal to or less than the display width of @var{ellipsis}. If
+@var{ellipsis} is non-@code{nil} and not a string, it stands for
+@code{"..."}.
+
@example
(truncate-string-to-width "\tab\t" 12 4)
@result{} "ab"
-(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 height spec specifies the
+actual line height, @var{line-height}. There are several ways to
+write a height spec; here's how each of them translates into a numeric
+height:
+
+@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 (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} property, the line's
+height consists of the contents' height plus the line spacing.
+There are several ways to specify the line spacing for different
+parts of Emacs text.
+
+@vindex default-line-spacing
+ You can specify the line spacing for all lines in a frame with the
+@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+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 face
+@cindex faces
A @dfn{face} is a named collection of graphical attributes: font
family, foreground color, background color, optional underlining, and
* 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 mode-line
@kindex mode-line @r{(face name)}
-This face is used for mode lines, and for menu bars when toolkit menus
-are not used---but only if @code{mode-line-inverse-video} is
-non-@code{nil}.
+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 fringe
@kindex fringe @r{(face name)}
-This face controls the colors of window fringes, the thin areas on
-either side that are used to display continuation and truncation glyphs.
+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)}
@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
@kindex underline @r{(face name)}
This face underlines text.
-@item fixed-patch
-@kindex fixed-patch @r{(face name)}
+@item fixed-pitch
+@kindex fixed-pitch @r{(face name)}
This face forces use of a particular fixed-width font.
-@item variable-patch
-@kindex variable-patch @r{(face name)}
+@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.
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
init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
-different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
-@var{display}, specifies a class of terminals. The element's second element,
-@var{atts}, is a list of face attributes and their values; it specifies
-what the face should look like on that kind of terminal. The possible
-attributes are defined in the value of @code{custom-face-attributes}.
+different kinds of terminals. It should be an alist whose elements
+have the form @code{(@var{display} @var{atts})}. Each element's
+@sc{car}, @var{display}, specifies a class of terminals. (The first
+element, if it s @sc{car} is @code{default}, is special---it specifies
+defaults for the remaining elements). The element's @sc{cadr},
+@var{atts}, is a list of face attributes and their values; it
+specifies what the face should look like on that kind of terminal.
+The possible attributes are defined in the value of
+@code{custom-face-attributes}.
The @var{display} part of an element of @var{spec} determines which
-frames the element applies to. If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame. There are two possibilities for @var{display}:
+frames the element matches. If more than one element of @var{spec}
+matches a given frame, the first element that matches is the one used
+for that frame. There are three possibilities for @var{display}:
@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any frames; instead, it
+specifies defaults that apply to all frames. This kind of element, if
+used, must be the first element of @var{spec}. Each of the following
+elements can override any or all of these defaults.
+
@item @code{t}
This element of @var{spec} matches all frames. Therefore, any
subsequent elements of @var{spec} are never used. Normally
@table @code
@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
+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).
@item class
What kinds of colors the frame supports---either @code{color},
@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. This matches a frame if its
+@code{display-color-cells} value is at least the specified integer.
+
+@item supports
+Whether or not the frame can display the face attributes given in
+@var{value}@dots{} (@pxref{Face Attributes}). See the documentation
+for the function @code{display-supports-face-attributes-p} for more
+information on exactly how this testing is done. @xref{Display Face
+Attribute Testing}.
@end table
If an element of @var{display} specifies more than one @var{value} for a
@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.
-In face merging, when the first face fails to specify a particular
-attribute, that means the next face gets a chance. However, the
-@code{default} face must specify all attributes.
+ Any attribute in a face can have the value @code{unspecified}. This
+means the face doesn't specify that attribute. In face merging, when
+the first face fails to specify a particular attribute, that means the
+next face gets a chance. However, the @code{default} face must
+specify all attributes.
Some of these font attributes are meaningful only on certain kinds of
displays---if your display cannot handle a certain attribute, the
@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
external-format X bitmap data. The file is found in the directories
listed in the variable @code{x-bitmap-file-path}.
-Alternatively, the value can specify the bitmap directly, with a list of
-the form @code{(@var{width} @var{height} @var{data})}. Here,
-@var{width} and @var{height} specify the size in pixels, and @var{data}
-is a string containing the raw bits of the bitmap, row by row. Each row
-occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
-(which should be a unibyte string for best results).
+Alternatively, the value can specify the bitmap directly, with a list
+of the form @code{(@var{width} @var{height} @var{data})}. Here,
+@var{width} and @var{height} specify the size in pixels, and
+@var{data} is a string containing the raw bits of the bitmap, row by
+row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
+in the string (which should be a unibyte string for best results).
+This means that each row always occupies at least one whole byte.
If the value is @code{nil}, that means use no stipple pattern.
The name of a face from which to inherit attributes, or a list of face
names. Attributes from inherited faces are merged into the face like an
underlying face would be, with higher priority than underlying faces.
+If a list of faces is used, attributes from faces earlier in the list
+override those from later faces.
@item :box
Whether or not a box should be drawn around characters, its color, the
is used.
@end table
- The attributes @code{:overline}, @code{:strike-through} and
-@code{:box} are new in Emacs 21. The attributes @code{:family},
-@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
-new; previous versions used the following attributes, now semi-obsolete,
-to specify some of the same information:
+ In older versions of Emacs, before @code{:family}, @code{:height},
+@code{:width}, @code{:weight}, and @code{:slant} existed, these
+attributes were used to specify the type face. They are now
+semi-obsolete, but they still work:
@table @code
@item :font
A non-@code{nil} value specifies an italic font.
@end table
- For compatibility, you can still set these ``attributes'' in Emacs 21,
-even though they are not real face attributes. Here is what that does:
+ For compatibility, you can still set these ``attributes'', even
+though they are not real face attributes. Here is what that does:
@table @code
@item :font
@end defvar
@defun bitmap-spec-p object
-This returns @code{t} if @var{object} is a valid bitmap
-specification, suitable for use with @code{:stipple}.
-It returns @code{nil} otherwise.
+This returns @code{t} if @var{object} is a valid bitmap specification,
+suitable for use with @code{:stipple} (see above). It returns
+@code{nil} otherwise.
@end defun
@node Attribute Functions
@example
(set-face-attribute 'foo nil
- :width :extended
- :weight :bold
+ :width 'extended
+ :weight 'bold
:underline "red")
@end example
@end defun
@tindex face-attribute
-@defun face-attribute face attribute &optional frame
+@defun face-attribute face attribute &optional frame inherit
This returns the value of the @var{attribute} attribute of face
@var{face} on @var{frame}. If @var{frame} is @code{nil},
-that means the selected frame.
+that means the selected frame (@pxref{Input Focus}).
If @var{frame} is @code{t}, the value is the default for
@var{face} for new frames.
+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-@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
+unspecified or relative values by merging with the @code{default} face
+(which is always completely specified).
+
For example,
@example
with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.
+@tindex face-attribute-relative-p
+@defun face-attribute-relative-p attribute value
+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
+
+@tindex merge-face-attribute
+@defun merge-face-attribute attribute value1 value2
+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 attribute @var{attribute}, returns @var{value1} unchanged.
+@end defun
+
@defun set-face-foreground face color &optional frame
@defunx set-face-background face color &optional frame
These functions set the foreground (or background, respectively) color
@end defun
@defun set-face-stipple face pattern &optional frame
-This function sets the background stipple pattern of face @var{face} to
-@var{pattern}. The argument @var{pattern} should be the name of a
-stipple pattern defined by the X server, or @code{nil} meaning don't use
-stipple.
+This function sets the background stipple pattern of face @var{face}
+to @var{pattern}. The argument @var{pattern} should be the name of a
+stipple pattern defined by the X server, or actual bitmap data
+(@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
Normally there is no need to pay attention to stipple patterns, because
they are used automatically to handle certain shades of gray.
@end defun
@defun set-face-font face font &optional frame
-This function sets the font of face @var{face}.
-
-In Emacs 21, this actually sets the attributes @code{:family},
-@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
-according to the font name @var{font}.
-
-In Emacs 20, this sets the font attribute. Once you set the font
-explicitly, the bold and italic attributes cease to have any effect,
-because the precise font that you specified is used.
+This function sets the font of face @var{face}. This actually sets
+the attributes @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} according to the font name
+@var{font}.
@end defun
@defun set-face-bold-p face bold-p &optional frame
This function specifies whether @var{face} should be bold. If
@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
-
-In Emacs 21, this sets the @code{:weight} attribute.
-In Emacs 20, it sets the @code{:bold} attribute.
+This actually sets the @code{:weight} attribute.
@end defun
@defun set-face-italic-p face italic-p &optional frame
This function specifies whether @var{face} should be italic. If
@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
-
-In Emacs 21, this sets the @code{:slant} attribute.
-In Emacs 20, it sets the @code{:italic} attribute.
+This actually sets the @code{:slant} attribute.
@end defun
@defun set-face-underline-p face underline-p &optional frame
They return the symbol @code{unspecified} if the face doesn't define any
value for that attribute.
-@defun face-foreground face &optional frame
+@defun face-foreground face &optional frame inherit
@defunx face-background face &optional frame
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
+
+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
+specified, use a value of @code{default} for @var{inherit}.
@end defun
-@defun face-stipple face &optional frame
+@defun face-stipple face &optional frame inherit
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 @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:
default for all text. (In Emacs 19 and 20, the @code{default}
face is used only when no other face is specified.)
-For a mode line or header line, the face @code{modeline} or
-@code{header-line} is used just before @code{default}.
+@item
+For a mode line or header line, the face @code{mode-line} or
+@code{mode-line-inactive}, or @code{header-line}, is merged in just
+before @code{default}.
@item
With text properties. A character can have a @code{face} property; if
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
If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
-specified. The attributes of the faces of special glyphs come first;
-then comes the face for region highlighting, if appropriate;
-then come attributes of faces from overlays, followed by those from text
-properties, and last the default face.
+specified. For each attribute, Emacs tries first the face of any
+special glyph; then the face for region highlighting, if appropriate;
+then the faces specified by overlays, followed by those specified by
+text properties, then the @code{mode-line} or
+@code{mode-line-inactive} or @code{header-line} face (if in a mode
+line or a header line), and last the @code{default} face.
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
- In Emacs 20, if an attribute such as the font or a color is not
-specified in any of the above ways, the frame's own font or color is
-used. In newer Emacs versions, this cannot happen, because the
-@code{default} face specifies all attributes---in fact, the frame's own
-font and colors are synonymous with those of the default face.
-
@node Font Selection
@subsection Font Selection
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.
quite right.
@end defvar
-@defvar face-alternative-font-family-alist
-@tindex face-alternative-font-family-alist
+@defvar face-font-family-alternatives
+@tindex face-font-family-alternatives
This variable lets you specify alternative font families to try, if a
given family is specified and doesn't exist. Each element should have
this form:
If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
+@end defvar
+
+@defvar face-font-registry-alternatives
+@tindex face-font-registry-alternatives
+This variable lets you specify alternative font registries to try, if a
+given registry is specified and doesn't exist. Each element should have
+this form:
+
+@example
+(@var{registry} @var{alternate-registries}@dots{})
+@end example
+
+If @var{registry} is specified but not available, Emacs will try the
+other registries given in @var{alternate-registries}, one by one,
+until it finds a registry that does exist.
@end defvar
Emacs can make use of scalable fonts, but by default it does not use
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 copy-face old-face new-name &optional frame new-frame
-This function defines the face @var{new-name} as a copy of the existing
+This function defines a face named @var{new-name} as a copy of the existing
face named @var{old-face}. It creates the face @var{new-name} if that
doesn't already exist.
@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
@cindex faces, automatic choice
@cindex Font-Lock mode
- Starting with Emacs 21, a hook is available for automatically
-assigning faces to text in the buffer. This hook is used for part of
-the implementation of Font-Lock mode.
+ This hook is used for automatically assigning faces to text in the
+buffer. It is part of the implementation of Font-Lock mode.
@tindex fontification-functions
@defvar fontification-functions
many fonts match the pattern.
@end defun
- These additional functions are available starting in Emacs 21.
-
@defun x-family-fonts &optional family frame
@tindex x-family-fonts
This function returns a list describing the available fonts for family
contain the wildcards @samp{?} and @samp{*}.
The list describes the display that @var{frame} is on; if @var{frame} is
-omitted or @code{nil}, it applies to the selected frame's display.
+omitted or @code{nil}, it applies to the selected frame's display
+(@pxref{Input Focus}).
The list contains a vector of the following form for each font:
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
@tindex x-font-family-list
This function returns a list of the font families available for
@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
-describes the selected frame's display.
+describes the selected frame's display (@pxref{Input Focus}).
The value is a list of elements of this form:
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
-collapses them into a single wildcard. This is to prevent use of
-auto-scaled fonts. Fonts made by scaling larger fonts are not usable
-for editing, and scaling a smaller font is not useful because it is
-better to use the smaller font in its own size, which Emacs does.
+ In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard. This is to prevent use of
+auto-scaled fonts. Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+ Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for @acronym{ASCII} characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+ You may not have any Chinese font matching the above font
+specification. Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+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.
+
+@menu
+* Fringe Size/Pos:: Specifying where to put the window fringes.
+* Fringe Bitmaps:: Displaying bitmaps in the window fringes.
+* 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.
+
+@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}.
+@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{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
+@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 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, instead of the
+default @code{fringe} face. @var{face} is automatically merged with
+the @code{fringe} face, so normally @var{face} need only specify the
+foreground color for the bitmap.
+
+ 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
+@subsection Customizing Fringe Bitmaps
+
+@defun define-fringe-bitmap bitmap bits &optional height width align
+This function defines the symbol @var{bitmap} as a new fringe bitmap,
+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.
+
+@var{face} is merged with the @code{fringe} face, so normally
+@var{face} should specify only the foreground color.
+@end defun
+
+@node Overlay Arrow
+@subsection The Overlay Arrow
+@cindex overlay arrow
+
+ The @dfn{overlay arrow} is useful for directing the user's attention
+to a particular line in a buffer. For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed. This feature has nothing to do with
+@dfn{overlays} (@pxref{Overlays}).
+
+@defvar overlay-arrow-string
+This variable holds the string to display to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
+On a graphical display the contents of the string are ignored; instead a
+glyph is displayed in the fringe area to the left of the display area.
+@end defvar
+
+@defvar overlay-arrow-position
+This variable holds a marker that indicates where to display the overlay
+arrow. It should point at the beginning of a line. On a non-graphical
+display the arrow text
+appears at the beginning of that line, overlaying any text that would
+otherwise appear. Since the arrow is usually short, and the line
+usually begins with indentation, normally nothing significant is
+overwritten.
+
+The overlay string is displayed only in the buffer that this marker
+points into. Thus, only one buffer can have an overlay arrow at any
+given time.
+@c !!! overlay-arrow-position: but the overlay string may remain in the display
+@c of some other buffer until an update is required. This should be fixed
+@c now. Is it?
+@end defvar
+
+ You can do a similar job by creating an overlay with a
+@code{before-string} property. @xref{Overlay Properties}.
+
+ You can define multiple overlay arrows via the variable
+@code{overlay-arrow-variable-list}.
+
+@defvar overlay-arrow-variable-list
+This variable's value is a list of variables, each of which specifies
+the position of an overlay arrow. The variable
+@code{overlay-arrow-position} has its normal meaning because it is on
+this list.
+@end defvar
+
+Each variable on this list can have properties
+@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
+specify an overlay arrow string (for text-only terminals) or fringe
+bitmap (for graphical terminals) to display at the corresponding
+overlay arrow position. If either property is not set, the default
+(@code{overlay-arrow-string} or @code{overlay-arrow-fringe-bitmap}) is
+used.
+
+@node Scroll Bars
+@section Scroll Bars
+
+Normally the frame parameter @code{vertical-scroll-bars} controls
+whether the windows in the frame have vertical scroll bars, 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}.
+
+@defun frame-current-scroll-bars &optional frame
+This function reports the scroll bar type settings for frame
+@var{frame}. The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
+@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
+(which means no scroll bar.) @var{horizontal-type} is meant to
+specify the horizontal scroll bar type, but since they are not
+implemented, it is always @code{nil}.
+@end defun
- Thus if @var{fontpattern} is this,
+@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
-@example
--*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
-@end example
+@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.
-@noindent
-the font specification for @sc{ascii} characters would be this:
+@var{horizontal-type} is not actually meaningful.
+@end defun
-@example
--*-fixed-medium-r-normal-*-24-*-ISO8859-1
-@end example
+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
-@noindent
-and the font specification for Chinese GB2312 characters would be this:
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
+@code{window-scroll-bars}, this reports the scroll bar type actually
+used, once frame defaults and @code{scroll-bar-mode} are taken into
+account.
+@end defun
-@example
--*-fixed-medium-r-normal-*-24-*-gb2312*-*
-@end example
+@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
- You may not have any Chinese font matching the above font
-specification. Most X distributions include only Chinese fonts that
-have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
-such a case, @samp{Fontset-@var{n}} can be specified as below:
+@node Pointer Shape
+@section Pointer Shape
-@smallexample
-Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
- chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
-@end smallexample
+ 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.
-@noindent
-Then, the font specifications for all but Chinese GB2312 characters have
-@samp{fixed} in the @var{family} field, and the font specification for
-Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
-field.
+ 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
The @code{display} text property (or overlay property) is used to
insert images into text, and also control other aspects of how text
-displays. These features are available starting in Emacs 21. The value
-of the @code{display} property should be a display specification, or a
-list or vector containing several display specifications. The rest of
-this section describes several kinds of display specifications and what
-they mean.
+displays. The value of the @code{display} property should be a
+display specification, or a list or vector containing several display
+specifications.
+
+ Some kinds of @code{display} properties specify something to display
+instead of the text that has the property. In this case, ``the text''
+means all the consecutive characters that have the same Lisp object as
+their @code{display} property; these characters are replaced as a
+single unit. By contrast, characters that have similar but distinct
+Lisp objects as their @code{display} properties are handled
+separately. Here's a function that illustrates this point:
+
+@example
+(defun foo ()
+ (goto-char (point-min))
+ (dotimes (i 5)
+ (let ((string (concat "A")))
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 1)
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 1))))
+@end example
+
+@noindent
+It gives each of the first ten characters in the buffer string
+@code{"A"} as the @code{display} property, but they don't all get the
+same string. The first two characters get the same string, so they
+together are replaced with one @samp{A}. The next two characters get
+a second string, so they together are replaced with one @samp{A}.
+Likewise for each following pair of characters. Thus, the ten
+characters appear as five A's. This function would have the same
+results:
+
+@example
+(defun foo ()
+ (goto-char (point-min))
+ (dotimes (i 5)
+ (let ((string (concat "A")))
+ (put-text-property (point) (2+ (point)) 'display string)
+ (put-text-property (point) (1+ (point)) 'display string)
+ (forward-char 2))))
+@end example
+
+@noindent
+This illustrates that what matters is the property value for
+each character. If two consecutive characters have the same
+object as the @code{display} property value, it's irrelevant
+whether they got this property from a single call to
+@code{put-text-property} or from two different calls.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
@menu
-* Specified Space:: Displaying one space with a specified width.
-* 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
- depending on some Lisp expression.
@end menu
@node Specified Space
values). You can put this property on one or more consecutive
characters; a space of the specified height and width is displayed in
place of @emph{all} of those characters. These are the properties you
-can use to specify the weight of the space:
+can use in @var{props} to specify the weight of the space:
@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 interer 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
- Exactly one of the above properties should be used. You can also
-specify the height of the space, with other properties:
+ You should use one and only one of the above properties. You can
+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
- You should not use both @code{:height} and @code{:relative-height}
-together.
+ Don't use both @code{:height} and @code{:relative-height} together.
+
+ The @code{:width} 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 for the
+product of the values of @var{num} and @var{expr}. For example,
+@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
+@var{image})} specifies half the width (or height) of the specified
+image.
+
+ 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 @var{string}
+Display @var{string} instead of the text that has this property.
+
@item (image . @var{image-props})
-This is in fact an image descriptor (@pxref{Images}). When used as a
-display specification, it means to display the image instead of the text
-that has the display specification.
+This display specification is an image descriptor (@pxref{Images}).
+When used as a display specification, it means to display the image
+instead of the text that has the display specification.
+
+@item (slice @var{x} @var{y} @var{width} @var{height})
+This specification together with @code{image} specifies a @dfn{slice}
+(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}
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.
+
@item (space-width @var{factor})
This display specification affects all the space characters within the
text that has the specification. It displays all of these spaces
faces used for the text.
@end table
+ You can make any display specification conditional. To do that,
+package it in another list of the form @code{(when @var{condition} .
+@var{spec})}. Then the specification @var{spec} applies only when
+@var{condition} evaluates to a non-@code{nil} value. During the
+evaluation, @code{object} is bound to the string or buffer having the
+conditional @code{display} property. @code{position} and
+@code{buffer-position} are bound to the position within @code{object}
+and the buffer position where the @code{display} property was found,
+respectively. Both positions can be different when @code{object} is a
+string.
+
@node Display Margins
@subsection Displaying in the Margins
@cindex display margins
display specification of the form @code{(margin right-margin)} or
@code{(margin left-margin)} on it. To put an image in a display margin,
use that display specification along with the display specification for
-the image.
+the image. Unfortunately, there is currently no way to make
+text or images in the margin mouse-sensitive.
+
+ If you put such a display specification directly on text in the
+buffer, the specified margin display appears @emph{instead of} that
+buffer text itself. To put something in the margin @emph{in
+association with} certain buffer text without preventing or altering
+the display of that text, put a @code{before-string} property on the
+text and put the display specification on the contents of the
+before-string.
Before the display margins can display anything, you must give
them a nonzero width. The usual way to do that is to set these
You can also set the margin widths immediately.
-@defun set-window-margins window left right
+@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
-@var{right} controls the right margin.
+The argument @var{left} controls the left margin and
+@var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
If @var{window} is @code{nil}, the selected window is used.
@end defun
-@node Conditional Display
-@subsection Conditional Display Specifications
-@cindex conditional display specifications
-
- You can make any display specification conditional. To do that,
-package it in another list of the form @code{(when @var{condition} .
-@var{spec})}. Then the specification @var{spec} applies only when
-@var{condition} evaluates to a non-@code{nil} value. During the
-evaluation, point is temporarily set at the end position of the text
-having this conditional display specification.
-
@node Images
@section Images
@cindex images in buffers
To display an image in an Emacs buffer, you must first create an image
descriptor, then use it as a display specifier in the @code{display}
-property of text that is displayed (@pxref{Display Property}). Like the
-@code{display} property, this feature is available starting in Emacs 21.
+property of text that is displayed (@pxref{Display Property}).
Emacs can display a number of different image formats; some of them
-are supported only if particular support libraries are installed on your
-machine. The supported image formats include XBM, XPM (needing the
-libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
-@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
-@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
-and PNG (needing @code{libpng} 1.0.2).
+are supported only if particular support libraries are installed on
+your machine. In some environments, Emacs can load image
+libraries on demand; if so, the variable @code{image-library-alist}
+can be used to modify the set of known names for these dynamic
+libraries (though it is not possible to add new image formats).
+
+ The supported image formats include XBM, XPM (this requires the
+libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
+@code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
+@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
+v3.4), and PNG (requiring @code{libpng} 1.0.2).
You specify one of these formats with an image type symbol. The image
type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
@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.
types:
@table @code
+@item :file @var{file}
+The @code{:file} property says to load the image from file
+@var{file}. If @var{file} is not an absolute file name, it is expanded
+in @code{data-directory}.
+
+@item :data @var{data}
+The @code{:data} property says the actual contents of the image.
+Each image must use either @code{:data} or @code{:file}, but not both.
+For most image types, the value of the @code{:data} property should be a
+string containing the image data; we recommend using a unibyte string.
+
+Before using @code{:data}, look for further information in the section
+below describing the specific image format. For some image types,
+@code{:data} may not be supported; for some, it allows other data types;
+for some, @code{:data} alone is not enough, so you need to use other
+image properties along with @code{:data}.
+
+@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
+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.
+If @code{:margin} is not specified, the default is zero.
+
@item :ascent @var{ascent}
The @code{:ascent} property specifies the amount of the image's
height to use for its ascent---that is, the part above the baseline.
If this property is omitted, it defaults to 50.
-@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
-non-negative number; if it is not specified, the default is zero.
-
@item :relief @var{relief}
The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
around the image. The value, @var{relief}, specifies the width of the
so that the image appears as a pressed button; otherwise, it appears as
an unpressed button.
-@item :algorithm @var{algorithm}
-The @code{:algorithm} property, if non-@code{nil}, specifies a
+@item :conversion @var{algorithm}
+The @code{:conversion} property, if non-@code{nil}, specifies a
conversion algorithm that should be applied to the image before it is
displayed; the value, @var{algorithm}, specifies which algorithm.
-Currently, the only meaningful value for @var{algorithm} (aside from
-@code{nil}) is @code{laplace}; this applies the Laplace edge detection
-algorithm, which blurs out small differences in color while highlighting
-larger differences. People sometimes consider this useful for
-displaying the image for a ``disabled'' button.
-
-@item :heuristic-mask @var{transparent-color}
-The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a
-certain color in the image should be transparent. Each pixel where this
-color appears will actually allow the frame's background to show
-through.
+@table @code
+@item laplace
+@itemx emboss
+Specifies the Laplace edge detection algorithm, which blurs out small
+differences in color while highlighting larger differences. People
+sometimes consider this useful for displaying the image for a
+``disabled'' button.
+
+@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+Specifies a general edge-detection algorithm. @var{matrix} must be
+either a nine-element list or a nine-element vector of numbers. A pixel
+at position @math{x/y} in the transformed image is computed from
+original pixels around that position. @var{matrix} specifies, for each
+pixel in the neighborhood of @math{x/y}, a factor with which that pixel
+will influence the transformed pixel; element @math{0} specifies the
+factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
+the pixel at @math{x/y-1} etc., as shown below:
+@iftex
+@tex
+$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
+ x-1/y & x/y & x+1/y \cr
+ x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ (x-1/y-1 x/y-1 x+1/y-1
+ x-1/y x/y x+1/y
+ x-1/y+1 x/y+1 x+1/y+1)
+@end display
+@end ifnottex
-If @var{transparent-color} is @code{t}, then determine the transparent
-color by looking at the four corners of the image. This uses the color
-that occurs most frequently near the corners as the transparent color.
+The resulting pixel is computed from the color intensity of the color
+resulting from summing up the RGB values of surrounding pixels,
+multiplied by the specified factors, and dividing that sum by the sum
+of the factors' absolute values.
-Otherwise, @var{heuristic-mask} should specify the transparent color
-directly, as a list of three integers in the form @code{(@var{red}
-@var{green} @var{blue})}.
+Laplace edge-detection currently uses a matrix of
+@iftex
+@tex
+$$\pmatrix{1 & 0 & 0 \cr
+ 0& 0 & 0 \cr
+ 9 & 9 & -1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ (1 0 0
+ 0 0 0
+ 9 9 -1)
+@end display
+@end ifnottex
-@item :file @var{file}
-The @code{:file} property specifies to load the image from file
-@var{file}. If @var{file} is not an absolute file name, it is expanded
-in @code{data-directory}.
+Emboss edge-detection uses a matrix of
+@iftex
+@tex
+$$\pmatrix{ 2 & -1 & 0 \cr
+ -1 & 0 & 1 \cr
+ 0 & 1 & -2 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ ( 2 -1 0
+ -1 0 1
+ 0 1 -2)
+@end display
+@end ifnottex
-@item :data @var{data}
-The @code{:data} property specifies the actual contents of the image.
-Each image must use either @code{:data} or @code{:file}, but not both.
-For most image types, the value of the @code{:data} property should be a
-string containing the image data; we recommend using a unibyte string.
+@item disabled
+Specifies transforming the image so that it looks ``disabled''.
+@end table
-Before using @code{:data}, look for further information in the section
-below describing the specific image format. For some image types,
-@code{:data} may not be supported; for some, it allows other data types;
-for some, @code{:data} alone is not enough, so you need to use other
-image properties along with @code{:data}.
+@item :mask @var{mask}
+If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
+a clipping mask for the image, so that the background of a frame is
+visible behind the image. If @var{bg} is not specified, or if @var{bg}
+is @code{t}, determine the background color of the image by looking at
+the four corners of the image, assuming the most frequently occurring
+color from the corners is the background color of the image. Otherwise,
+@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 @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
+@tindex image-mask-p
+This function returns @code{t} if image @var{spec} has a mask bitmap.
+@var{frame} is the frame on which the image will be displayed.
+@var{frame} @code{nil} or omitted means to use the selected frame
+(@pxref{Input Focus}).
+@end defun
+
@node XBM Images
@subsection XBM Images
@cindex XBM
@table @code
@item :foreground @var{foreground}
The value, @var{foreground}, should be a string specifying the image
-foreground color. This color is used for each pixel in the XBM that is
-1. The default is the frame's foreground color.
+foreground color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 1. The default is the frame's
+foreground color.
@item :background @var{background}
The value, @var{background}, should be a string specifying the image
-background color. This color is used for each pixel in the XBM that is
-0. The default is the frame's background color.
+background color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 0. The default is the frame's
+background color.
@end table
If you specify an XBM image using data within Emacs instead of an
@subsection GIF Images
@cindex GIF
- For GIF images, specify image type @code{gif}. Because of the patents
-in the US covering the LZW algorithm, the continued use of GIF format is
-a problem for the whole Internet; to end this problem, it is a good idea
-for everyone, even outside the US, to stop using GIFS right away
-(@uref{http://www.burnallgifs.org/}). But if you still want to use
-them, Emacs can display them.
+ For GIF images, specify image type @code{gif}.
@table @code
@item :index @var{index}
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
@table @code
@item :foreground @var{foreground}
The value, @var{foreground}, should be a string specifying the image
-foreground color. This color is used for each pixel in the XBM that is
-1. The default is the frame's foreground color.
+foreground color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 1. The default is the frame's
+foreground color.
@item :background @var{background}
The value, @var{background}, should be a string specifying the image
-background color. This color is used for each pixel in the XBM that is
-0. The default is the frame's background color.
+background color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 0. The default is the frame's
+background color.
@end table
For JPEG images, specify image type @code{jpeg}.
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
supported. Otherwise it returns an image descriptor.
@end defun
-@defmac defimage variable doc &rest specs
+@defmac defimage symbol specs &optional doc
@tindex defimage
-This macro defines @var{variable} as an image name. The second argument,
-@var{doc}, is an optional documentation string. The remaining
-arguments, @var{specs}, specify alternative ways to display the image.
+This macro defines @var{symbol} as an image name. The arguments
+@var{specs} is a list which specifies how to display the image.
+The third argument, @var{doc}, is an optional documentation string.
Each argument in @var{specs} has the form of a property list, and each
-one should specify at least the @code{:type} property and the
-@code{:file} property. Here is an example:
+one should specify at least the @code{:type} property and either the
+@code{:file} or the @code{:data} property. The value of @code{:type}
+should be a symbol specifying the image type, the value of
+@code{:file} is the file to load the image from, and the value of
+@code{:data} is a string containing the actual image data. Here is an
+example:
@example
(defimage test-image
- '((:type xpm :file "~/test1.xpm")
- (:type xbm :file "~/test1.xbm")))
+ ((:type xpm :file "~/test1.xpm")
+ (:type xbm :file "~/test1.xbm")))
@end example
@code{defimage} tests each argument, one by one, to see if it is
usable---that is, if the type is supported and the file exists. The
first usable argument is used to make an image descriptor which is
-stored in the variable @var{variable}.
+stored in @var{symbol}.
-If none of the alternatives will work, then @var{variable} is defined
+If none of the alternatives will work, then @var{symbol} is defined
as @code{nil}.
@end defmac
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{defimage}. The argument @var{string} specifies the text to put in
-the buffer to hold the image.
+@code{defimage}. The argument @var{string} specifies the text to put
+in the buffer to hold the image. If it is omitted or @code{nil},
+@code{insert-image} uses @code{" "} by default.
The argument @var{area} specifies whether to put the image in a margin.
If it is @code{left-margin}, the image appears in the left margin;
@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.
-@var{frame} null or omitted means use the selected frame.
+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
@node Image Cache
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. These
+properties are called @dfn{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.
+@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 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
+This makes a button from @var{beg} to @var{end} in the
+current buffer, and returns it.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+This insert a button with the label @var{label} at point,
+and returns it.
+@end defun
+
+ The following functions are similar, but use Emacs text properties
+(@pxref{Text Properties}) to hold the button properties, making the
+button actually part of the text instead of being a property of the
+buffer. Buttons using text properties do not create markers into the
+buffer, which is important for speed when you use extremely large
+numbers of buttons. Both functions return the position of the start
+of the new button:
+
+@defun make-text-button beg end &rest properties
+@tindex make-text-button
+This makes a button from @var{beg} to @var{end} in the current buffer, using
+text properties.
+@end defun
+
+@defun insert-text-button label &rest properties
+@tindex insert-text-button
+This inserts a button with the label @var{label} at point, using text
+properties.
+@end defun
+
+@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
+
+@defun button-type-put type prop val
+@tindex button-type-put
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+@tindex button-type-get
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+@tindex button-type-subtype-p
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+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 quick @key{Mouse-1} click
+will also activate the @code{push-button} command.
+@xref{Links and Mouse-1}.
+
+@deffn Command push-button &optional pos use-mouse-action
+@tindex push-button
+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 Blinking
@section Blinking Parentheses
@cindex parenthesis matching
@end defopt
@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines and menu
-bars. If it is non-@code{nil}, then these lines are displayed in
-inverse video. Otherwise, these lines are displayed normally, just like
-other text. The default is @code{t}.
-
-For window frames, this feature actually applies the face named
-@code{mode-line}; that face is normally set up as the inverse of the
-default face, unless you change it.
+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
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
-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
@table @asis
@item 0
The glyph for the end of a truncated screen line (the default for this
-is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
-display arrows to indicate truncation---the display table has no effect
-in these situations.
+is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
+arrows in the fringes to indicate truncation, so the display table has
+no effect.
+
@item 1
The glyph for the end of a continued line (the default is @samp{\}).
-Newer Emacs versions, on some platforms, display curved arrows to
-indicate truncation---the display table has no effect in these
-situations.
+On graphical terminals, Emacs uses curved arrows in the fringes to
+indicate continuation, so the display table has no effect.
+
@item 2
The glyph for indicating a character displayed as an octal character
code (the default is @samp{\}).
+
@item 3
The glyph for indicating a control character (the default is @samp{^}).
+
@item 4
A vector of glyphs for indicating the presence of invisible lines (the
default is @samp{...}). @xref{Selective Display}.
+
@item 5
The glyph used to draw the border between side-by-side windows (the
default is @samp{|}). @xref{Splitting Windows}. This takes effect only
table if any. The display table chosen is called the @dfn{active}
display table.
-@defun window-display-table window
+@defun window-display-table &optional window
This function returns @var{window}'s display table, or @code{nil}
-if @var{window} does not have an assigned display table.
+if @var{window} does not have an assigned display table. The default
+for @var{window} is the selected window.
@end defun
@defun set-window-display-table window table
@cindex glyph
A @dfn{glyph} is a generalization of a character; it stands for an
image that takes up a single character position on the screen. Glyphs
-are represented in Lisp as integers, just as characters are.
+are represented in Lisp as integers, just as characters are. Normally
+Emacs finds glyphs in the display table (@pxref{Display Tables}).
+
+ A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
+table}. A simple glyph is just a way of specifying a character and a
+face to output it in. The glyph code for a simple glyph, mod 524288,
+is the character to output, and the glyph code divided by 524288
+specifies the face number (@pxref{Face Functions}) to use while
+outputting it. (524288 is
+@ifnottex
+2**19.)
+@end ifnottex
+@tex
+$2^{19}$.)
+@end tex
+@xref{Faces}.
-@cindex glyph table
- The meaning of each integer, as a glyph, is defined by the glyph
-table, which is the value of the variable @code{glyph-table}.
+ On character terminals, you can set up a @dfn{glyph table} to define
+the meaning of glyph codes. The glyph codes is the value of the
+variable @code{glyph-table}.
@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}. If the value
-is @code{nil} instead of a vector, then all glyphs are simple (see
-below).
+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
+@code{glyph-table} is @code{nil} instead of a vector, then all glyphs
+are simple. The glyph table is not used on graphical displays, only
+on character terminals. On graphical displays, all glyphs are simple.
@end defvar
Here are the possible types of elements in the glyph table:
@item @var{integer}
Define this glyph code as an alias for glyph code @var{integer}. You
-can use an alias to specify a face code for the glyph; see below.
+can use an alias to specify a face code for the glyph and use a small
+number as its code.
@item @code{nil}
-This glyph is simple. On an ordinary terminal, the glyph code mod
-524288 is the character to output. In a window system, the glyph code
-mod 524288 is the character to output, and the glyph code divided by
-524288 specifies the face number (@pxref{Face Functions}) to use while
-outputting it. (524288 is
-@ifnottex
-2**19.)
-@end ifnottex
-@tex
-$2^{19}$.)
-@end tex
-@xref{Faces}.
+This glyph is simple.
@end table
- If a glyph code is greater than or equal to the length of the glyph
-table, that code is automatically simple.
-
@defun create-glyph string
@tindex create-glyph
This function returns a newly-allocated glyph code which is set up to
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
HCoop / bpt / emacs.git / blobdiff