@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
* Refresh Screen:: Clearing the screen and redrawing everything on it.
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
-* The Echo Area:: Where messages are displayed.
+* The Echo Area:: Displaying messages at the bottom of the screen.
* Warnings:: Displaying warning messages for the user.
-* Progress:: Informing user about progress of a long operation.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
@cindex error display
@cindex echo area
-The @dfn{echo area} is used for displaying error messages
+ The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes. It is not the same as the minibuffer,
despite the fact that the minibuffer appears (when active) in the same
the minibuffer for use of that screen space (@pxref{Minibuffer,, The
Minibuffer, emacs, The GNU Emacs Manual}).
-You can write output in the echo area by using the Lisp printing
-functions with @code{t} as the stream (@pxref{Output Functions}), or as
-follows:
+ You can write output in the echo area by using the Lisp printing
+functions with @code{t} as the stream (@pxref{Output Functions}), or
+explicitly.
+
+@menu
+* Displaying Messages:: Explicitly displaying text in the echo area.
+* Progress:: Informing user about progress of a long operation.
+* Logging Messages:: Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+@end menu
+
+@node Displaying Messages
+@subsection Displaying Messages in the Echo Area
+
+ This section describes the functions for explicitly producing echo
+area messages. Many other Emacs features display messages there, too.
@defun message string &rest arguments
This function displays a message in the echo area. The
argument @var{string} is similar to a C language @code{printf} control
-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."
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
echo area, or @code{nil} if there is none.
@end defun
-@defvar cursor-in-echo-area
-This variable controls where the cursor appears when a message is
-displayed in the echo area. If it is non-@code{nil}, then the cursor
-appears at the end of the message. Otherwise, the cursor appears at
-point---not in the echo area at all.
+@node Progress
+@subsection Reporting Operation Progress
+@cindex progress reporting
-The value is normally @code{nil}; Lisp programs bind it to @code{t}
-for brief periods of time.
-@end defvar
+ When an operation can take a while to finish, you should inform the
+user about the progress it makes. This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
-@defvar echo-area-clear-hook
-This normal hook is run whenever the echo area is cleared---either by
-@code{(message nil)} or for any other reason.
-@end defvar
+ Functions listed in this section provide simple and efficient way of
+reporting operation progress. Here is a working example that does
+nothing useful:
-Almost all the messages displayed in the echo area are also recorded
-in the @samp{*Messages*} buffer.
+@smallexample
+(let ((progress-reporter
+ (make-progress-reporter "Collecting mana for Emacs..."
+ 0 500)))
+ (dotimes (k 500)
+ (sit-for 0.01)
+ (progress-reporter-update progress-reporter k))
+ (progress-reporter-done progress-reporter))
+@end smallexample
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates and returns a @dfn{progress reporter}---an
+object you will use as an argument for all other functions listed
+here. The idea is to precompute as much data as possible to make
+progress reporting very fast.
+
+When this progress reporter is subsequently used, it will display
+@var{message} in the echo area, followed by progress percentage.
+@var{message} is treated as a simple string. If you need it to depend
+on a filename, for instance, use @code{format} before calling this
+function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation. For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly. It is required that @var{max-value} is greater than
+@var{min-value}. If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument. But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates. Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints. It can be fractional. Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision. Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation. It displays the message of @var{reporter}, followed by
+progress percentage determined by @var{value}. If percentage is zero,
+or close enough according to the @var{min-change} and @var{min-time}
+arguments, then it is omitted from the output.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}. @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}. For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation. It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}. Optional @var{new-message} allows
+you to change the message of the @var{reporter}. Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished. It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
+@defmac dotimes-with-progress-reporter (var count [result]) message body...
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above. It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+ (k 500)
+ "Collecting some mana for Emacs..."
+ (sit-for 0.01))
+@end example
+@end defmac
+
+@node Logging Messages
+@subsection Logging Messages in @samp{*Messages*}
+@cindex logging echo-area messages
+
+ Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer so that the user can refer back to
+them. This includes all the messages that are output with
+@code{message}.
@defopt message-log-max
This variable specifies how many lines to keep in the @samp{*Messages*}
@end example
@end defopt
+ To make @samp{*Messages*} more convenient for the user, the logging
+facility combines successive identical messages. It also combines
+successive related messages for the sake of two cases: question
+followed by answer, and a series of progress messages.
+
+ A ``question followed by an answer'' means two messages like the
+ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
+and the second is @samp{@var{question}...@var{answer}}. The first
+message conveys no additional information beyond what's in the second,
+so logging the second message discards the first from the log.
+
+ A ``series of progress messages'' means successive messages like
+those produced by @code{make-progress-reporter}. They have the form
+@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
+time, while @var{how-far} varies. Logging each message in the series
+discards the previous one, provided they are consecutive.
+
+ The functions @code{make-progress-reporter} and @code{y-or-n-p}
+don't have to do anything special to activate the message log
+combination feature. It operates whenever two consecutive messages
+are logged that share a common prefix ending in @samp{...}.
+
+@node Echo Area Customization
+@subsection Echo Area Customization
+
+ These variables control details of how the echo area works.
+
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area. If it is non-@code{nil}, then the cursor
+appears at the end of the message. Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
+@defvar echo-area-clear-hook
+This normal hook is run whenever the echo area is cleared---either by
+@code{(message nil)} or for any other reason.
+@end defvar
+
@defvar echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
If the value is zero, then command input is not echoed.
@end defvar
+@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
+
+@defvar message-truncate-lines
+Normally, displaying a long message resizes the echo area to display
+the entire message. But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
+@end defvar
+
@node Warnings
@section Reporting Warnings
@cindex warnings
that warning is not logged.
@end defopt
-@node Progress
-@section Reporting Operation Progress
-@cindex progress reporting
-
- When an operation can take a while to finish, you should inform the
-user about the progress it makes. This way the user can estimate
-remaining time and clearly see that Emacs is busy working, not hung.
-
- Functions listed in this section provide simple and efficient way of
-reporting operation progress. Here is a working example that does
-nothing useful:
-
-@example
-(let ((progress-reporter
- (make-progress-reporter "Collecting some mana for Emacs..."
- 0 500)))
- (dotimes (k 500)
- (sit-for 0.01)
- (progress-reporter-update progress-reporter k))
- (progress-reporter-done progress-reporter))
-@end example
-
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates 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
@defun add-to-invisibility-spec element
This function adds the element @var{element} to
-@code{buffer-invisibility-spec} (if it is not already present in that
-list). If @code{buffer-invisibility-spec} was @code{t}, it changes to
-a list, @code{(t)}, so that text whose @code{invisible} property
-is @code{t} remains invisible.
+@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
+was @code{t}, it changes to a list, @code{(t)}, so that text whose
+@code{invisible} property is @code{t} remains invisible.
@end defun
@defun remove-from-invisibility-spec element
Ordinarily, functions that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
explicitly ignore invisible newlines if
-@code{line-move-ignore-invisible} is non-@code{nil}, but only because
-they are explicitly programmed to do so.
+@code{line-move-ignore-invisible} is non-@code{nil} (the default), but
+only because they are explicitly programmed to do so.
However, if a command ends with point inside or immediately after
invisible text, the main editing loop moves point further forward or
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:
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
-@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+@code{(foreground-color . @var{color-name})} has the same effect as
+@code{(:foreground @var{color-name})}; likewise for the background.
@end itemize
@item mouse-face
length is the number of characters deleted, and the post-change
beginning and end are equal.)
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called before and
adding blank areas between the images.
If the property value is not @code{t}, it is a height spec. A height
-spec stands for a numeric height value; this heigh spec specifies the
+spec stands for a numeric height value; this height spec specifies the
actual line height, @var{line-height}. There are several ways to
write a height spec; here's how each of them translates into a numeric
height:
is @var{ratio} times the height of face @var{face}. @var{ratio} can
be any type of number, or @code{nil} which means a ratio of 1.
If @var{face} is @code{t}, it refers to the current face.
-@item (@code{nil} . @var{ratio})
+@item (nil . @var{ratio})
If the height spec is a cons of the format shown, the numeric height
is @var{ratio} times the height of the contents of the line.
@end table
the line to achieve the total height @var{line-height}. Otherwise,
@var{line-height} has no effect.
- If you don't specify the @code{line-height} propery, the line's
+ If you don't specify the @code{line-height} property, the line's
height consists of the contents' height plus the line spacing.
There are several ways to specify the line spacing for different
parts of Emacs text.
@cindex face id
Each face has its own @dfn{face number}, which distinguishes faces at
low levels within Emacs. However, for most purposes, you refer to
-faces in Lisp programs by their names.
+faces in Lisp programs by the symbols that name them.
@defun facep object
-This function returns @code{t} if @var{object} is a face name symbol (or
-if it is a vector of the kind used internally to record face data). It
-returns @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a face name string
+or symbol (or if it is a vector of the kind used internally to record
+face data). It returns @code{nil} otherwise.
@end defun
Each face name is meaningful for all frames, and by default it has the
@item mode-line
@kindex mode-line @r{(face name)}
This face is used for the mode line of the selected window, and for
-menu bars when toolkit menus are not used---but only if
-@code{mode-line-inverse-video} is non-@code{nil}.
+menu bars when toolkit menus are not used.
@item modeline
@kindex modeline @r{(face name)}
@item fringe
@kindex fringe @r{(face name)}
-This face controls the default colors of window fringes, the thin areas on
-either side that are used to display continuation and truncation glyphs.
+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)}
@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
This face forces use of a particular variable-width font. It's
reasonable to customize this to use a different variable-width font, if
you like, but you should not make it a fixed-width font.
+
+@item shadow
+@kindex shadow @r{(face name)}
+This face is used for making the text less noticeable than the
+surrounding ordinary text.
@end table
@defvar show-trailing-whitespace
emacs, The GNU Emacs Manual}).
@defmac defface face spec doc [keyword value]...
-This declares @var{face} as a customizable face that defaults according
-to @var{spec}. You should not quote the symbol @var{face}. The
+This declares @var{face} as a customizable face that defaults
+according to @var{spec}. You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant). The
argument @var{doc} specifies the face documentation. The keywords you
-can use in @code{defface} are the same ones that are meaningful in both
-@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+can use in @code{defface} are the same as in @code{defgroup} and
+@code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
-different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
-@var{display}, specifies a class of terminals. The element's second element,
-@var{atts}, is a list of face attributes and their values; it specifies
-what the face should look like on that kind of terminal. The possible
-attributes are defined in the value of @code{custom-face-attributes}.
+different kinds of terminals. It should be an alist whose elements
+have the form @code{(@var{display} @var{atts})}. Each element's
+@sc{car}, @var{display}, specifies a class of terminals. (The first
+element, if 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
The kind of background---either @code{light} or @code{dark}.
@item min-colors
-An integer that represents the minimum number of colors the frame should
-support, it is compared with the result of @code{display-color-cells}.
+An integer that represents the minimum number of colors the frame
+should support. This matches a frame if its
+@code{display-color-cells} value is at least the specified integer.
@item supports
Whether or not the frame can display the face attributes given in
Internally, @code{defface} uses the symbol property
@code{face-defface-spec} to record the face attributes specified in
@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
+with the customization buffer, @code{customized-face} for the
+attributes customized by the user for the current session, but not
+saved, and @code{face-documentation} for the documentation string.
@defopt frame-background-mode
This option, if non-@code{nil}, specifies the background type to use for
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
differently from the default face.
@end defun
+@cindex face alias
+A @dfn{face alias} provides an equivalent name for a face. You can
+define a face alias by giving the alias symbol the @code{face-alias}
+property, with a value of the target face name. The following example
+makes @code{modeline} an alias for the @code{mode-line} face.
+
+@example
+(put 'modeline 'face-alias 'mode-line)
+@end example
+
+
@node Auto Faces
@subsection Automatic Face Assignment
@cindex automatic face assignment
registry name is @samp{JISX0208.1983} for all characters belonging to
the charset @code{japanese-jisx0208}.
-@example
+@smallexample
(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
-@end example
-
+@end smallexample
@end defun
@defun char-displayable-p char
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.
+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.
+ These symbols identify the standard fringe bitmaps. Evaluate
+@code{(require 'fringe)} to define them. Fringe bitmap symbols have
+their own name space.
@table @asis
@item Truncation and continuation line bitmaps:
If @var{face} is @code{nil}, it selects the @code{fringe} face. The
bitmap's face controls the color to draw it in.
-The face you use here should be derived from @code{fringe}, and should
-specify only the foreground color.
+@var{face} is merged with the @code{fringe} face, so normally
+@var{face} should specify only the foreground color.
@end defun
@node Overlay Arrow
@code{overlay-arrow-variable-list}.
@defvar overlay-arrow-variable-list
-This variable's value is a list of varibles, each of which specifies
+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.
@section Scroll Bars
Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars. A
-non-@code{nil} parameter value means they do. The frame parameter
+whether the windows in the frame have vertical scroll bars, and
+whether they are on the left or right. The frame parameter
@code{scroll-bar-width} specifies how wide they are (@code{nil}
meaning the default). @xref{Window Frame Parameters}.
+@defun frame-current-scroll-bars &optional frame
+This function reports the scroll bar type settings for frame
+@var{frame}. The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
+@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
+(which means no scroll bar.) @var{horizontal-type} is meant to
+specify the horizontal scroll bar type, but since they are not
+implemented, it is always @code{nil}.
+@end defun
+
@vindex vertical-scroll-bar
You can enable or disable scroll bars for a particular buffer,
by setting the variable @code{vertical-scroll-bar}. This variable
the left, and @code{right} to put a scroll bar on the right.
@end defvar
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a cons cell
+@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
+@code{window-scroll-bars}, this reports the scroll bar type actually
+used, once frame defaults and @code{scroll-bar-mode} are taken into
+account.
+@end defun
+
@defvar scroll-bar-width
This variable, always local in all buffers, specifies the width of the
buffer's scroll bars, measured in pixels. A value of @code{nil} means
Lisp objects as their @code{display} properties are handled
separately. Here's a function that illustrates this point:
-@example
+@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(forward-char 1)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 1))))
-@end example
+@end smallexample
@noindent
It gives each of the first ten characters in the buffer string
characters appear as five A's. This function would have the same
results:
-@example
+@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(put-text-property (point) (2+ (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
-@end example
+@end smallexample
@noindent
This illustrates that what matters is the property value for
each character. If two consecutive characters have the same
-object as the @code{display} property value, it's irrelevent
+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 following expressions are supported:
-@example
+@smallexample
@group
@var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
@var{num} ::= @var{integer} | @var{float} | @var{symbol}
@var{unit} ::= in | mm | cm | width | height
+@end group
+@group
@var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
| scroll-bar | text
@var{pos} ::= left | center | right
@var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
@var{op} ::= + | -
@end group
-@end example
+@end smallexample
The form @var{num} specifies a fraction of the default frame font
height or width. The form @code{(@var{num})} specifies an absolute
Display @var{string} instead of the text that has this property.
@item (image . @var{image-props})
-This display specification is an image descriptor (@pxref{Images}).
+This kind of display specification is an image descriptor (@pxref{Images}).
When used as a display specification, it means to display the image
instead of the text that has the display specification.
default is @code{nil}.
@end defopt
-@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines and
-menu bars. If it is non-@code{nil}, then these lines are displayed in
-the face @code{mode-line}. Otherwise, these lines are displayed
-normally, just like other text. The default is @code{t}.
-@end defopt
-
@node Usual Display
@section Usual Display Conventions