display-supports-face-attributes-p

etc/NEWS

@@ -1000,6 +1000,13 @@ removes the text properties in the `yank-excluded-properties' list.
 
 ** New function insert-buffer-substring-no-properties.
 
+** New function display-supports-face-attributes-p may be used to test
+whether a given set of face attributes is actually displayable.
+
+A new predicate `supports' has also been added to the `defface' face
+specification language, which can be used to do this test for faces
+defined with defface.
+
 ** Enhanced networking support.
 
 *** There is a new `make-network-process' function which supports

lispref/frames.texi

 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
 @c   Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/frames
@@ -1717,6 +1717,33 @@ This function returns @code{t} if the screen can display shades of gray.
 (All color displays can do this.)
 @end defun
 
+@anchor{Display Face Attribute Testing}
+@defun display-supports-face-attributes-p attributes &optional display
+@tindex display-supports-face-attributes-p
+This function returns non-@code{nil} if all the face attributes in
+@var{attributes} are supported (@pxref{Face Attributes}).
+
+The definition of `supported' is somewhat heuristic, but basically
+means that a face containing all the attributes in @var{attributes},
+when merged with the default face for display, can be represented in a
+way that's
+
+@enumerate
+@item
+different in appearance than the default face, and
+
+@item
+`close in spirit' to what the attributes specify, if not exact.
+@end enumerate
+
+Point (2) implies that a @code{:weight black} attribute will be
+satisfied by any display that can display bold, as will
+@code{:foreground "yellow"} as long as some yellowish color can be
+displayed, but @code{:slant italic} will @emph{not} be satisified by
+the tty display code's automatic substitution of a `dim' face for
+italic.
+@end defun
+
 @defun display-selections-p &optional display
 @tindex display-selections-p
 This function returns @code{t} if @var{display} supports selections.