Next: , Previous: Displaying Faces, Up: Faces

38.12.5 Face Remapping

The variable 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 particular buffer.

— Variable: face-remapping-alist

An alist whose elements have the form (face remapping...). 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 face text property: either a face name, or a property list of attribute/value pairs. See Special Properties.

If face-remapping-alist is buffer-local, its local value takes effect only within that buffer.

Two points bear emphasizing:

  1. 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.
  2. If remapping... recursively references the same face name face, either directly remapping entry, or via the :inherit attribute 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-line face is remapped using this entry in face-remapping-alist: 

                   (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 mode-line face.

A typical use of the face-remapping-alist is to change a buffer's default face; for example, the following changes a buffer's default face to use the variable-pitch face, 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 face-remapping-alist which 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 added by 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, e.g., of the default face.

— Function: face-remap-add-relative face &rest specs

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 face-remap-remove-relative.

specs can be any value suitable for the face text 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.

— Function: face-remap-remove-relative cookie

This function removes a face remapping previously added by face-remap-add-relative. cookie should be a return value from that function.

— Function: face-remap-set-base face &rest specs

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).

— Function: face-remap-reset-base face

This function sets the “base remapping” of face to its default value, which inherits from face's global definition.