The way to define a new face is with
defface. This creates a
kind of customization item (see Customization) which the user can
customize using the Customization buffer (see Easy Customization).
People are sometimes tempted to create variables whose values specify which faces to use (for example, Font-Lock does this). In the vast majority of cases, this is not necessary, and simply using faces directly is preferable.
This declares face as a customizable face whose default attributes are given by spec. You should not quote the symbol face, and it should not end in ‘-face’ (that would be redundant). The argument doc specifies the face documentation. The keywords you can use in
deffaceare the same as in
defcustom(see Common Keywords).
deffaceexecutes, it defines the face according to spec, then uses any customizations that were read from the init file (see Init File) to override that specification.
When you evaluate a
deffaceform with C-M-x in Emacs Lisp mode (
eval-defun), a special feature of
eval-defunoverrides any customizations of the face. This way, the face reflects exactly what the
The purpose of spec is to specify how the face should appear on different kinds of terminals. It should be an alist whose elements have the form
). Each element's car, display, specifies a class of terminals. (The first element, if its car is
default, is special—it specifies defaults for the remaining elements). The element's cadr, atts, is a list of face attributes and their values; it specifies what the face should look like on that kind of terminal. The possible attributes are defined in the value of
The display part of an element of spec determines which frames the element matches. If more than one element of spec matches a given frame, the first element that matches is the one used for that frame. There are three possibilities for display:
- This element of spec doesn't match any frames; instead, it specifies defaults that apply to all frames. This kind of element, if used, must be the first element of spec. Each of the following elements can override any or all of these defaults.
- This element of spec matches all frames. Therefore, any subsequent elements of spec are never used. Normally
tis used in the last (or only) element of spec.
- a list
- If display is a list, each element should have the form
...). Here characteristic specifies a way of classifying frames, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:
- The kind of window system the frame uses—either
graphic(any graphics-capable display),
pc(for the MS-DOS console),
w32(for MS Windows 9X/NT/2K/XP), or
tty(a non-graphics-capable display). See window-system.
- What kinds of colors the frame supports—either
- The kind of background—either
- An integer that represents the minimum number of colors the frame should support. This matches a frame if its
display-color-cellsvalue is at least the specified integer.
- Whether or not the frame can display the face attributes given in value… (see Face Attributes). See Display Face Attribute Testing, for more information on exactly how this testing is done.
If an element of display specifies more than one value for a given characteristic, any of those values is acceptable. If display has more than one element, each element should specify a different characteristic; then each characteristic of the frame must match one of the values specified for it in display.
Here's how the standard face
region is defined:
(defface region '((((class color) (min-colors 88) (background dark)) :background "blue3") (((class color) (min-colors 88) (background light)) :background "lightgoldenrod2") (((class color) (min-colors 16) (background dark)) :background "blue3") (((class color) (min-colors 16) (background light)) :background "lightgoldenrod2") (((class color) (min-colors 8)) :background "blue" :foreground "white") (((type tty) (class mono)) :inverse-video t) (t :background "gray")) "Basic face for highlighting the region." :group 'basic-faces)
defface uses the symbol property
face-defface-spec to record the specified face attributes. The
attributes saved by the user with the customization buffer are
recorded in the symbol property
saved-face; the attributes
customized by the user for the current session, but not saved, are
recorded in the symbol property
documentation string is recorded in the symbol property
This option, if non-
nil, specifies the background type to use for interpreting face definitions. If it is
dark, then Emacs treats all frames as if they had a dark background, regardless of their actual background colors. If it is
light, then Emacs treats all frames as if they had a light background.