Function: defface

defface is a macro defined in custom.el.gz.

Signature

(defface FACE SPEC DOC &rest ARGS)

Documentation

Declare FACE as a customizable face that defaults to SPEC.

FACE does not need to be quoted.

Third argument DOC is the face documentation.

If FACE has been set with custom-theme-set-faces, set the face attributes as specified by that function, otherwise set the face attributes according to SPEC.

The remaining arguments should have the form [KEYWORD VALUE]... For a list of valid keywords, see the common keywords listed in defcustom.

SPEC should be a "face spec", i.e., an alist of the form

   ((DISPLAY . ATTS)...)

where DISPLAY is a form specifying conditions to match certain terminals and ATTS is a property list (ATTR VALUE ATTR VALUE...) specifying face attributes and values for frames on those terminals. On each terminal, the first element with a matching DISPLAY specification takes effect, and the remaining elements in SPEC are disregarded.

As a special exception, in the first element of SPEC, DISPLAY can be the special value default. Then the ATTS in that element act as defaults for all the following elements.

For backward compatibility, elements of SPEC can be written as (DISPLAY ATTS) instead of (DISPLAY . ATTS).

Each DISPLAY can have the following values:
 - default (only in the first element).
 - The symbol t, which matches all terminals.
 - An alist of conditions. Each alist element must have the form
   (REQ ITEM...). A matching terminal must satisfy each
   specified condition by matching one of its ITEMs. Each REQ
   must be one of the following:
   - type (the terminal type).
     Each ITEM must be one of the values returned by
     window-system. Under X, additional allowed values are
     motif, lucid, gtk and x-toolkit.
   - class (the terminal's color support).
     Each ITEM should be one of color, grayscale, or mono.
   - background (what color is used for the background text)
     Each ITEM should be one of light or dark.
   - min-colors (the minimum number of supported colors)
     Each ITEM should be an integer, which is compared with the
     result of display-color-cells.
   - supports (match terminals supporting certain attributes).
     Each ITEM should be a list of face attributes. See
     display-supports-face-attributes-p for more information on
     exactly how testing is done.

In the ATTS property list, possible attributes are :family, :font,
:foundry, :width, :height, :weight, :slant, :underline,
:overline, :strike-through, :box, :foreground, :distant-foreground,
:background, :stipple, :inverse-video, :extend, and :inherit.

See Info node (elisp) Faces in the Emacs Lisp manual for more information.

View in manual

Probably introduced at or before Emacs version 20.3.

Source Code

;; Defined in /usr/src/emacs/lisp/custom.el.gz
;;; The `defface' Macro.

(defmacro defface (face spec doc &rest args)
  "Declare FACE as a customizable face that defaults to SPEC.
FACE does not need to be quoted.

Third argument DOC is the face documentation.

If FACE has been set with `custom-theme-set-faces', set the face
attributes as specified by that function, otherwise set the face
attributes according to SPEC.

The remaining arguments should have the form [KEYWORD VALUE]...
For a list of valid keywords, see the common keywords listed in
`defcustom'.

SPEC should be a \"face spec\", i.e., an alist of the form

   ((DISPLAY . ATTS)...)

where DISPLAY is a form specifying conditions to match certain
terminals and ATTS is a property list (ATTR VALUE ATTR VALUE...)
specifying face attributes and values for frames on those
terminals.  On each terminal, the first element with a matching
DISPLAY specification takes effect, and the remaining elements in
SPEC are disregarded.

As a special exception, in the first element of SPEC, DISPLAY can
be the special value `default'.  Then the ATTS in that element
act as defaults for all the following elements.

For backward compatibility, elements of SPEC can be written
as (DISPLAY ATTS) instead of (DISPLAY . ATTS).

Each DISPLAY can have the following values:
 - `default' (only in the first element).
 - The symbol t, which matches all terminals.
 - An alist of conditions.  Each alist element must have the form
   (REQ ITEM...).  A matching terminal must satisfy each
   specified condition by matching one of its ITEMs.  Each REQ
   must be one of the following:
   - `type' (the terminal type).
     Each ITEM must be one of the values returned by
     `window-system'.  Under X, additional allowed values are
     `motif', `lucid', `gtk' and `x-toolkit'.
   - `class' (the terminal's color support).
     Each ITEM should be one of `color', `grayscale', or `mono'.
   - `background' (what color is used for the background text)
     Each ITEM should be one of `light' or `dark'.
   - `min-colors' (the minimum number of supported colors)
     Each ITEM should be an integer, which is compared with the
     result of `display-color-cells'.
   - `supports' (match terminals supporting certain attributes).
     Each ITEM should be a list of face attributes.  See
     `display-supports-face-attributes-p' for more information on
     exactly how testing is done.

In the ATTS property list, possible attributes are `:family', `:font',
`:foundry', `:width', `:height', `:weight', `:slant', `:underline',
`:overline', `:strike-through', `:box', `:foreground', `:distant-foreground',
`:background', `:stipple', `:inverse-video', `:extend', and `:inherit'.

See Info node `(elisp) Faces' in the Emacs Lisp manual for more
information."
  (declare (doc-string 3) (indent defun))
  ;; It is better not to use backquote in this file,
  ;; because that makes a bootstrapping problem
  ;; if you need to recompile all the Lisp files using interpreted code.
  (nconc (list 'custom-declare-face (list 'quote face) spec doc) args))