elisp: Defining Faces
37.12.2 Defining Faces
----------------------
The usual way to define a face is through the ‘defface’ macro. This
macro associates a face name (a symbol) with a default “face spec”. A
face spec is a construct which specifies what attributes a face should
have on any given terminal; for example, a face spec might specify one
foreground color on high-color terminals, and a different foreground
color on low-color terminals.
People are sometimes tempted to create a variable whose value is a
face name. In the vast majority of cases, this is not necessary; the
usual procedure is to define a face with ‘defface’, and then use its
name directly.
-- Macro: defface face spec doc [keyword value]...
This macro declares FACE as a named face whose default face spec is
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 ‘defgroup’ and ‘defcustom’
(
Common Keywords).
If FACE already has a default face spec, this macro does nothing.
The default face spec determines FACE’s appearance when no
customizations are in effect (Customization). If FACE has
already been customized (via Custom themes or via customizations
read from the init file), its appearance is determined by the
custom face spec(s), which override the default face spec SPEC.
However, if the customizations are subsequently removed, the
appearance of FACE will again be determined by its default face
spec.
As an exception, if you evaluate a ‘defface’ form with ‘C-M-x’ in
Emacs Lisp mode (‘eval-defun’), a special feature of ‘eval-defun’
overrides any custom face specs on the face, causing the face to
reflect exactly what the ‘defface’ says.
The SPEC argument is a “face spec”, which states how the face
should appear on different kinds of terminals. It should be an
alist whose elements each have the form
(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 ‘(DISPLAY PLIST)’.
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:
‘default’
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.
‘t’
This element of SPEC matches all terminals. Therefore, any
subsequent elements of SPEC are never used. Normally ‘t’ is
used in the last (or only) element of SPEC.
a list
If DISPLAY is a list, each element should have the form
‘(CHARACTERISTIC VALUE...)’. 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:
‘type’
The kind of window system the terminal uses—either
‘graphic’ (any graphics-capable display), ‘x’, ‘pc’ (for
the MS-DOS console), ‘w32’ (for MS Windows 9X/NT/2K/XP),
or ‘tty’ (a non-graphics-capable display).
window-system Window Systems.
‘class’
What kinds of colors the terminal supports—either
‘color’, ‘grayscale’, or ‘mono’.
‘background’
The kind of background—either ‘light’ or ‘dark’.
‘min-colors’
An integer that represents the minimum number of colors
the terminal should support. This matches a terminal if
its ‘display-color-cells’ value is at least the specified
integer.
‘supports’
Whether or not the terminal can display the face
attributes given in VALUE... (Face Attributes).
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.
For example, here’s the definition of the standard face ‘highlight’:
(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 each face’s default spec in its
‘face-defface-spec’ symbol property (Symbol Properties). The
‘saved-face’ property stores any face spec saved by the user using the
customization buffer; the ‘customized-face’ property stores the face
spec 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 the face specs for that
face. The face’s documentation string is stored in the
‘face-documentation’ property.
Normally, a face is declared just once, using ‘defface’, and any
further changes to its appearance are applied using the Customize
framework (e.g., via the Customize user interface or via the
‘custom-set-faces’ function; Applying Customizations), or by
face remapping (Face Remapping). In the rare event that you
need to change a face spec directly from Lisp, you can use the
‘face-spec-set’ function.
-- Function: face-spec-set face spec &optional spec-type
This function applies SPEC as a face spec for ‘face’. SPEC should
be a face spec, as described in the above documentation for
‘defface’.
This function also defines FACE as a valid face name if it is not
already one, and (re)calculates its attributes on existing frames.
The argument SPEC-TYPE determines which spec to set. If it is
‘nil’ or ‘face-override-spec’, this function sets the “override
spec”, which overrides over all other face specs on FACE. If it is
‘customized-face’ or ‘saved-face’, this function sets the
customized spec or the saved custom spec. If it is
‘face-defface-spec’, this function sets the default face spec (the
same one set by ‘defface’). If it is ‘reset’, this function clears
out all customization specs and override specs from FACE (in this
case, the value of SPEC is ignored). Any other value of SPEC-TYPE
is reserved for internal use.
Info Catalog
elisp: Face Attributes
elisp: Faces
elisp: Attribute Functions