face-remapping-alist is used for buffer-local or
global changes in the appearance of a face. For instance, it is used
to implement the
text-scale-adjust command (see Text
Scale in The GNU Emacs Manual).
The value of this variable is an alist whose elements have the form
(face . remapping). This causes Emacs to display
any text having the face face with remapping, rather than
the ordinary definition of face.
remapping may be any face spec suitable for a
property: either a face (i.e., a face name or a property list of
attribute/value pairs), or a list of faces. For details, see the
description of the
face text property in Properties with Special Meanings. remapping serves as the complete specification for
the remapped face—it replaces the normal definition of face,
instead of modifying it.
face-remapping-alist is buffer-local, its local value takes
effect only within that buffer. If
includes faces applicable only to certain windows, by using the
(:filtered (:window param val) spec),
that face takes effect only in windows that match the filter
conditions (see Properties with Special Meanings). To turn off face filtering
face-filters-always-match to a non-
value, then all face filters will match any window.
Note: face remapping is non-recursive. If remapping references
the same face name face, either directly or via the
:inherit attribute of some other face in remapping, that
reference uses the normal definition of face. For instance, if
mode-line face is remapped using this entry in
(mode-line italic mode-line)
then the new definition of the
mode-line face inherits from the
italic face, and the normal (non-remapped) definition of
The following functions implement a higher-level interface to
face-remapping-alist. Most Lisp code should use these
functions instead of setting
face-remapping-alist directly, to
avoid trampling on remappings applied elsewhere. These functions are
intended for buffer-local remappings, so they all make
face-remapping-alist buffer-local as a side-effect. They manage
face-remapping-alist entries of the form
(face relative-spec-1 relative-spec-2 ... base-spec)
where, as explained above, each of the relative-spec-N and
base-spec is either a face name, or a property list of
attribute/value pairs. Each of the relative remapping entries,
relative-spec-N, is managed by the
functions; these are intended for simple modifications like changing
the text size. The base remapping entry, base-spec, has
the lowest priority and is managed by the
face-remap-reset-base functions; it is intended for major
modes to remap faces in the buffers they control.
This function adds specs as relative remappings for face face in the current buffer. specs should be a list where each element is either a face name, or a property list of attribute/value pairs.
The return value is a Lisp object that serves as a cookie; you can
pass this object as an argument to
if you need to remove the remapping later.
;; Remap the 'escape-glyph' face into a combination ;; of the 'highlight' and 'italic' faces: (face-remap-add-relative 'escape-glyph 'highlight 'italic) ;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5)
Note that buffer-local face remapping does not work reliably for
parent faces of basic faces (see Basic Faces). (These are the
faces that are used in mode lines, header lines, and other basic
decorations of windows and frames.) For instance,
mode-line-inactive inherits from
mode-line won’t normally have the desired effect on
mode-line-inactive, especially if done locally for some
buffers. Instead you have to remap
This function removes a relative remapping previously added by
face-remap-add-relative. cookie should be the Lisp
object returned by
face-remap-add-relative when the remapping
This function sets the base remapping of face in the current
buffer to specs. If specs is empty, the default base
remapping is restored, similar to calling
(see below); note that this is different from specs containing a
nil, which has the opposite result (the global
definition of face is ignored).
This overwrites the default base-spec, which inherits the global face definition, so it is up to the caller to add such inheritance if so desired.
This function sets the base remapping of face to its default value, which inherits from face’s global definition.