@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, 2002
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
+@cindex fringes, and line continuation/truncation indicators
+ On a windowed display, the @samp{$} and @samp{\} indicators are
+replaced with graphics bitmaps displayed on the thin areas right near
+the window edges, called the @dfn{fringes}.
+
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}.
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
@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 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.
@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 removeds 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:}
about to be executed.
@defvar overlay-arrow-string
+@cindex fringe, and overlay arrow display
This variable holds the string to display to call attention to a
particular line, or @code{nil} if the arrow feature is not in use.
On a graphical display the contents of the string are ignored; instead a
@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
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 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.
This face controls the colors of window fringes, the thin areas on
either side that are used to display continuation and truncation glyphs.
+@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)}
This face controls the colors for display of scroll bars.
@item background
The kind of background---either @code{light} or @code{dark}.
+
+@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
@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 (@pxref{Input Focus}).
If @var{frame} is @code{t}, the value is the default for
@var{face} for new frames.
+If @var{inherit} is nil, only attributes directly defined by
+@var{face} are considered, so the return value may be
+@code{unspecified}, or a relative value. If @var{inherit} is non-nil,
+@var{face}'s definition of @var{attribute} is merged with the faces
+specified by its @code{:inherit} attribute; however the return value
+may still be @code{unspecified} or relative. If @var{inherit} is a
+face or a list of faces, then the result is further merged with that
+face (or faces), until it becomes specified and absolute.
+
+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 a
+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 a 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.
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 nil, only a color directly defined by the face is
+returned. If @var{inherit} is non-nil, any faces specified by its
+@code{:inherit} attribute are considered as well, and if @var{inherit}
+is a face or a list of faces, then they are also considered, until a
+specified 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 nil, only a stipple directly defined by the face
+is returned. If @var{inherit} is non-nil, any faces specified by its
+@code{:inherit} attribute are considered as well, and if @var{inherit}
+is a face or a list of faces, then they are also considered, until a
+specified stipple is found. To ensure that the return value is always
+specified, use a value of @code{default} for @var{inherit}.
@end defun
@defun face-font face &optional frame
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}
@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.
+may be an integer or a floating point number.
@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 other properties:
@table @code
@item :height @var{height}
greater than 100.
@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.
@node Other Display Specs
@subsection Other Display Specifications
position as that text. This is a special case of marginal display
(@pxref{Display Margins}).
-Recursive display specifications are not supported, i.e.@: string
-display specifications that have a display specification property
-themselves.
+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
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
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
@defopt indicate-empty-lines
@tindex indicate-empty-lines
+@cindex fringes, and empty line indication
When this is non-@code{nil}, Emacs displays a special glyph in
each empty line at the end of the buffer, on terminals that
support it (window systems).
@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). The glyph table is not used on windowed displays.
+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