Info Catalog elisp: Displaying Faces elisp: Faces elisp: Face Functions

elisp: Face Remapping

 
 37.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 is used to
 implement the ‘text-scale-adjust’ command ((emacs)Text Scale).
 
  -- Variable: face-remapping-alist
      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 ‘face’ text 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 Special
      Properties.  REMAPPING serves as the complete specification for
      the remapped face—it replaces the normal definition of FACE,
      instead of modifying it.
 
      If ‘face-remapping-alist’ is 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 ‘:inherit’
      attribute of some other face in REMAPPING, that reference uses the
      normal definition of FACE.  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.
 
    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
 ‘face-remap-add-relative’ and ‘face-remap-remove-relative’ 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-set-base’ and ‘face-remap-reset-base’
 functions; it is intended for major modes to remap faces in the buffers
 they control.
 
  -- Function: face-remap-add-relative face &rest specs
      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-relative’ 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)
 
  -- Function: face-remap-remove-relative cookie
      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 was added.
 
  -- 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, 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.
 
  -- 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.
 

Info Catalog elisp: Displaying Faces elisp: Faces elisp: Face Functions