@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
@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.
@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
@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 nil, it means to delete all overlays in
+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
-nil, that means the beginning and end of the buffer respectively.
+@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
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.
@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)}
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
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
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
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
@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.