@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
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:
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)}
@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
The way to define a new face is with @code{defface}. This creates a
kind of customization item (@pxref{Customization}) which the user can
customize using the Customization buffer (@pxref{Easy Customization,,,
-emacs, The GNU Emacs Manual}).
+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
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
insert images into text, and also control other aspects of how text
displays. 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
+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
Don't use both @code{:height} and @code{:relative-height} together.
- The @code{:height} and @code{:align-to} properties are supported on
+ The @code{:width} and @code{:align-to} properties are supported on
non-graphic terminals, but the other space properties in this section
are not.
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 display specification is an image descriptor (@pxref{Images}).
When used as a display specification, it means to display the image