face-remapping-alist is used for buffer-local or
global changes in the appearance of a face. For instance, it can be
used to make the
default face a variable-pitch face within a
An alist whose elements have the form
). This causes Emacs to display text using the face face using remapping... instead of face's ordinary definition. remapping... may be any face specification suitable for a
facetext property: either a face name, or a property list of attribute/value pairs. See Special Properties.
face-remapping-alistis buffer-local, its local value takes effect only within that buffer.
Two points bear emphasizing:
- The new definition remapping... is the complete specification of how to display face—it entirely replaces, rather than augmenting or modifying, the normal definition of that face.
- If remapping... recursively references the same face name face, either directly remapping entry, or via the
:inheritattribute of some other face in remapping..., then that reference uses the normal definition of face in the selected frame, instead of the “remapped” definition.
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
A typical use of the
face-remapping-alist is to change a
default face; for example, the following changes a
default face to use the
with the height doubled:
(set (make-local-variable 'face-remapping-alist) '((default variable-pitch :height 2.0)))
The following functions implement a higher-level interface to
face-remapping-alist, making it easier to use
“cooperatively”. They are mainly intended for buffer-local use, and
so all make
face-remapping-alist variable buffer-local as a
side-effect. They use entries in
have the general form:
(face relative_specs_1 relative_specs_2 ... base_specs)
Everything except face is a “face spec”: a list of face names or face attribute-value pairs. All face specs are merged together, with earlier values taking precedence.
The relative_specs_n values are “relative specs”, and are
face-remap-add-relative (and removed by
face-remap-remove-relative. These are intended for face
modifications (such as increasing the size). Typical users of these
relative specs would be minor modes.
base_specs is the lowest-priority value, and by default is just the face name, which causes the global definition of that face to be used.
A non-default value of base_specs may also be set using
face-remap-set-base. Because this overwrites the
default base-spec value (which inherits the global face definition),
it is up to the caller of
face-remap-set-base to add such
inheritance if it is desired. A typical use of
face-remap-set-base would be a major mode adding a face
remappings, ⁖, of the default face.
This functions adds a face remapping entry of face to specs in the current buffer.
It returns a “cookie” which can be used to later delete the remapping with
specs can be any value suitable for the
facetext property, including a face name, a list of face names, or a face-attribute property list. The attributes given by specs will be merged with any other currently active face remappings of face, and with the global definition of face (by default; this may be changed using
face-remap-set-base), with the most recently added relative remapping taking precedence.
This function removes a face remapping previously added by
face-remap-add-relative. cookie should be a return value from that function.
This function sets the “base remapping” of face in the current buffer to specs. If specs is empty, the default base remapping is restored, which inherits from the global definition of face; 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 function sets the “base remapping” of face to its default value, which inherits from face's global definition.