Function: pulse-faces

pulse-faces is a byte-compiled function defined in pulse.el.gz.

Signature

(pulse-faces FACES &optional WITH-FACE)

Documentation

Briefly pulse FACES by using attributes of face WITH-FACE (if defined).

FACES should be a list of faces to pulse. WITH-FACE is optional, it can be a defined face or a list of face properties to apply. If nil or omitted, it defaults to pulse-highlight-face.

Probably introduced at or before Emacs version 31.1.

Source Code

;; Defined in /usr/src/emacs/lisp/pulse.el.gz
;; FIXME: The pulse's smooth effect cannot be achieved here because
;;        the face-remapping will not work well for that.
(defun pulse-faces (faces &optional with-face)
  "Briefly pulse FACES by using attributes of face WITH-FACE (if defined).
FACES should be a list of faces to pulse.
WITH-FACE is optional, it can be a defined face or a list
of face properties to apply.  If nil or omitted, it defaults
to `pulse-highlight-face'."
  (when-let* (((numberp pulse-face-duration)) ; Ensure time is a number
              (with-face (or with-face 'pulse-highlight-face))
              (in-buffer (current-buffer))
              (cookies (mapcar (lambda (f)
                                 (if (consp with-face)
                                     (apply #'face-remap-add-relative
                                            f with-face)
                                   (face-remap-add-relative f with-face)))
                               faces)))
    ;; Use run-with-timer if the duration is very long, so as to avoid
    ;; blocking emacs; otherwise fall back to 'sleep-for'.
    (if (> pulse-face-duration 0.1)
        (run-with-timer pulse-face-duration 0
                        (lambda ()
                          ;; Remove the face remapping in the buffer
                          ;; where `pulse-faces' was called.
                          (if (buffer-live-p in-buffer)
                              (with-current-buffer in-buffer
                                (mapc #'face-remap-remove-relative cookies)))))
      (unwind-protect
          (progn
            ;; Redisplay to apply the face remapping.
            (redisplay)
            (sleep-for pulse-face-duration))
        (mapc #'face-remap-remove-relative cookies)))))