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).
The value of this variable is an alist whose elements have the form
). 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
facetext 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
facetext property in Special Properties. remapping serves as the complete specification for the remapped face—it replaces the normal definition of face, instead of modifying it.
face-remapping-alistis buffer-local, its local value takes effect only within that buffer.
Note: face remapping is non-recursive. If remapping references the same face name face, either directly or via the
:inheritattribute of some other face in remapping, that reference uses the normal definition of face. For instance, if the
mode-lineface is remapped using this entry in
face-remapping-alist:(mode-line italic mode-line)
then the new definition of the
mode-lineface inherits from the
italicface, 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 the face spec in specs as relative remappings for face face in the current buffer. The remaining arguments, specs, should form either a list of face names, 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
face-remap-remove-relativeif 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)
This function removes a relative remapping previously added by
face-remap-add-relative. cookie should be the Lisp object returned by
face-remap-add-relativewhen the remapping was added.
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
face-remap-reset-base(see below); note that this is different from specs containing a single value
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.