The usual way to define a face is through the
This macro defines a face name, and associates that name with a set of
face attributes. It also sets up the face so that the user can
customize it via the Customize interface (see Customization).
This macro 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 is a documentation string for the face. The additional keyword arguments have the same meanings 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
deffacesays.(display . plist)
display specifies a class of terminals (see below). plist is a property list of face attributes and their values, specifying how the face appears on such terminals. For backward compatibility, you can also write an element as
The display part of an element of spec determines which terminals the element matches. If more than one element of spec matches a given terminal, the first element that matches is the one used for that terminal. There are three possibilities for display:
- This element of spec doesn't match any terminal; instead, it specifies defaults that apply to all terminals. This 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 terminals. 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 terminals, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:
- The kind of window system the terminal 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 terminal supports—either
- The kind of background—either
- An integer that represents the minimum number of colors the terminal should support. This matches a terminal if its
display-color-cellsvalue is at least the specified integer.
- Whether or not the terminal 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 terminal must match one of the values specified for it in display.
Here's how the standard face
highlight is defined:
(defface highlight '((((class color) (min-colors 88) (background light)) :background "darkseagreen2") (((class color) (min-colors 88) (background dark)) :background "darkolivegreen") (((class color) (min-colors 16) (background light)) :background "darkseagreen2") (((class color) (min-colors 16) (background dark)) :background "darkolivegreen") (((class color) (min-colors 8)) :background "green" :foreground "black") (t :inverse-video t)) "Basic face for highlighting." :group 'basic-faces)
Internally, Emacs stores the face's default specification in its
face-defface-spec symbol property (see Symbol Properties).
saved-face property stores the face specification saved by
the user, using the customization buffer; the
property stores the face specification customized for the current
session, but not saved; and the
theme-face property stores an
alist associating the active customization settings and Custom themes
with their specifications for that face. The face's documentation
string is stored in the
face-documentation property. But
normally you should not try to set any of these properties directly.
See Applying Customizations, for the
function, which is used to apply customized face settings.
People are sometimes tempted to create variables whose values specify a face to use. In the vast majority of cases, this is not necessary; it is preferable to simply use faces directly.