Function: face-background

face-background is a byte-compiled function defined in faces.el.gz.

Signature

(face-background FACE &optional FRAME INHERIT)

Documentation

Return the background color name of FACE, or nil if unspecified.

On TTY frames, the returned color name can be "unspecified-bg", which stands for the unknown default background color of the display where the frame is displayed. If the optional argument FRAME is given, report on face FACE in that frame. If FRAME is t, report on the defaults for face FACE (for new frames). If FRAME is omitted or nil, use the selected frame.

If INHERIT is nil, only a background color directly defined by FACE is
  considered, so the return value may be nil.
If INHERIT is t, and FACE doesn't define a background color, then any
  background color that FACE inherits through its :inherit attribute
  is considered as well; however the return value may still be nil.
If INHERIT is a face or a list of faces, then it is used to try to
  resolve an unspecified background color, in addition to using any
inherited color.

To ensure that a valid color is always returned, use a value of default for INHERIT; this will resolve any unspecified values by merging with the default face (which is always completely specified).

View in manual

Probably introduced at or before Emacs version 22.1.

Aliases

mh-face-background (obsolete since 29.1)

Source Code

;; Defined in /usr/src/emacs/lisp/faces.el.gz
(defun face-background (face &optional frame inherit)
  "Return the background color name of FACE, or nil if unspecified.
On TTY frames, the returned color name can be \"unspecified-bg\",
which stands for the unknown default background color of the display
where the frame is displayed.
If the optional argument FRAME is given, report on face FACE in that frame.
If FRAME is t, report on the defaults for face FACE (for new frames).
If FRAME is omitted or nil, use the selected frame.

If INHERIT is nil, only a background color directly defined by FACE is
  considered, so the return value may be nil.
If INHERIT is t, and FACE doesn't define a background color, then any
  background color that FACE inherits through its `:inherit' attribute
  is considered as well; however the return value may still be nil.
If INHERIT is a face or a list of faces, then it is used to try to
  resolve an unspecified background color, in addition to using any
inherited color.

To ensure that a valid color is always returned, use a value of
`default' for INHERIT; this will resolve any unspecified values by
merging with the `default' face (which is always completely specified)."
  (face-attribute-specified-or (face-attribute face :background frame inherit)
			       nil))