Variable: face-remapping-alist

face-remapping-alist is a variable defined in xfaces.c.

Value

nil

Documentation

Alist of face remappings.

Each element is of the form:

   (FACE . REPLACEMENT),

which causes display of the face FACE to use REPLACEMENT instead. REPLACEMENT is a face specification, i.e. one of the following:

  (1) a face name
  (2) a property list of attribute/value pairs, or
  (3) a list in which each element has one of the above forms.

List values for REPLACEMENT are merged to form the final face specification, with earlier entries taking precedence, in the same way as with the face text property.

Face-name remapping cycles are suppressed; recursive references use the underlying face instead of the remapped face. So a remapping of the form:

   (FACE EXTRA-FACE... FACE)

or:

   (FACE (FACE-ATTR VAL ...) FACE)

causes EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the existing definition of FACE. Note that this isn't necessary for the default face, since every face inherits from the default face.

An entry in the list can also be a filtered face expression of the form:

  (:filtered FILTER FACE-SPECIFICATION)

This construct applies FACE-SPECIFICATION (which can have any of the forms allowed for face specifications generally) only if FILTER matches at the moment Emacs wants to draw text with the combined face.

The only filters currently defined are NIL (which always matches) and
(:window PARAMETER VALUE), which matches only in the context of a
window with a parameter EQ-equal to VALUE.

An entry in the face list can also be nil, which does nothing.

If face-remapping-alist is made buffer-local, the face remapping takes effect only in that buffer. For instance, the mode my-mode could define a face my-mode-default, and then in the mode setup function, do:

   (set (make-local-variable 'face-remapping-alist)
        (copy-tree '((default my-mode-default)))).

You probably want to use the face-remap package included in Emacs instead of manipulating face-remapping-alist directly. Note that many of the functions in that package modify the list destructively, so make sure you set it to a fresh value (for instance, use copy-tree as in the example above) before modifying.

Because Emacs normally only redraws screen areas when the underlying buffer contents change, you may need to call redraw-display after changing this variable for it to take effect.

View in manual

Probably introduced at or before Emacs version 23.1.

Source Code

// Defined in /usr/src/emacs/src/xfaces.c
  DEFVAR_LISP ("face-remapping-alist", Vface_remapping_alist,
	       doc: /* Alist of face remappings.
Each element is of the form:

   (FACE . REPLACEMENT),

which causes display of the face FACE to use REPLACEMENT instead.
REPLACEMENT is a face specification, i.e. one of the following:

  (1) a face name
  (2) a property list of attribute/value pairs, or
  (3) a list in which each element has one of the above forms.

List values for REPLACEMENT are merged to form the final face
specification, with earlier entries taking precedence, in the same way
as with the `face' text property.

Face-name remapping cycles are suppressed; recursive references use
the underlying face instead of the remapped face.  So a remapping of
the form:

   (FACE EXTRA-FACE... FACE)

or:

   (FACE (FACE-ATTR VAL ...) FACE)

causes EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
existing definition of FACE.  Note that this isn't necessary for the
default face, since every face inherits from the default face.

An entry in the list can also be a filtered face expression of the
form:

  (:filtered FILTER FACE-SPECIFICATION)

This construct applies FACE-SPECIFICATION (which can have any of the
forms allowed for face specifications generally) only if FILTER
matches at the moment Emacs wants to draw text with the combined face.

The only filters currently defined are NIL (which always matches) and
(:window PARAMETER VALUE), which matches only in the context of a
window with a parameter EQ-equal to VALUE.

An entry in the face list can also be nil, which does nothing.

If `face-remapping-alist' is made buffer-local, the face remapping
takes effect only in that buffer.  For instance, the mode my-mode
could define a face `my-mode-default', and then in the mode setup
function, do:

   (set (make-local-variable \\='face-remapping-alist)
        (copy-tree \\='((default my-mode-default)))).

You probably want to use the face-remap package included in Emacs
instead of manipulating face-remapping-alist directly.  Note that many
of the functions in that package modify the list destructively, so make
sure you set it to a fresh value (for instance, use `copy-tree' as in
the example above) before modifying.

Because Emacs normally only redraws screen areas when the underlying
buffer contents change, you may need to call `redraw-display' after
changing this variable for it to take effect.  */);