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:}
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)}
The kind of background---either @code{light} or @code{dark}.
@item supports
-Whether or not the frame can display the face attributes (@pxref{Face
-Attributes}) given in @var{value}@dots{}. See the documentation for
-the function @code{display-supports-face-attributes-p} (@pxref{Display
-Face Attribute Testing}) for more information on exactly how this testing
-is done.
+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
(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
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
@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
You should use one and only one of the above properties. You can
@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
@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. 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