Function: face-remap-add-relative

face-remap-add-relative is an autoloaded and byte-compiled function defined in face-remap.el.gz.

Signature

(face-remap-add-relative FACE &rest SPECS)

Documentation

Add a face remapping entry of FACE to SPECS in the current buffer.

Return a cookie which can be used to delete this remapping with face-remap-remove-relative.

The remaining arguments, SPECS, should form a list of faces. Each list element should be either a face name or a property list of face attribute/value pairs. If more than one face is listed, that specifies an aggregate face, in the same way as in a face text property, except for possible priority changes noted below.

The face remapping specified by SPECS takes effect alongside the remappings from other calls to face-remap-add-relative for the same FACE, as well as the normal definition of FACE (at lowest priority). This function tries to sort multiple remappings for the same face, so that remappings specifying relative face attributes are applied after remappings specifying absolute face attributes.

The base (lowest priority) remapping may be set to something other than the normal definition of FACE via face-remap-set-base.

View in manual

Probably introduced at or before Emacs version 23.1.

Source Code

;; Defined in /usr/src/emacs/lisp/face-remap.el.gz
;;;###autoload
(defun face-remap-add-relative (face &rest specs)
  "Add a face remapping entry of FACE to SPECS in the current buffer.
Return a cookie which can be used to delete this remapping with
`face-remap-remove-relative'.

The remaining arguments, SPECS, should form a list of faces.
Each list element should be either a face name or a property list
of face attribute/value pairs.  If more than one face is listed,
that specifies an aggregate face, in the same way as in a `face'
text property, except for possible priority changes noted below.

The face remapping specified by SPECS takes effect alongside the
remappings from other calls to `face-remap-add-relative' for the
same FACE, as well as the normal definition of FACE (at lowest
priority).  This function tries to sort multiple remappings for
the same face, so that remappings specifying relative face
attributes are applied after remappings specifying absolute face
attributes.

The base (lowest priority) remapping may be set to something
other than the normal definition of FACE via `face-remap-set-base'."
  (while (and (consp specs) (null (cdr specs)))
    (setq specs (car specs)))
  (make-local-variable 'face-remapping-alist)
  (let ((entry (assq face face-remapping-alist)))
    (when (null entry)
      (setq entry (list face face))	; explicitly merge with global def
      (push entry face-remapping-alist))
    (let ((faces (cdr entry)))
      (if (symbolp faces)
	  (setq faces (list faces)))
      (setcdr entry (face-remap-order (cons specs faces)))
      ;; Force redisplay of this buffer.
      (force-mode-line-update))
    (cons face specs)))