[elpa] externals/pulsar b469abdd94 17/28: Abstract pulse effect; add pulsar-highlight-line

[ELPA Syncer]

branch: externals/pulsar
commit b469abdd948e9d1e26f9dffc567af12ca760e0eb
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Abstract pulse effect; add pulsar-highlight-line
    
    Thanks to Mark Barton for the feedback in the disccussion around issue
    1: <https://gitlab.com/protesilaos/pulsar/-/issues/1>.
---
 README.org | 17 ++++++++++++++++-
 pulsar.el  | 33 ++++++++++++++++++++++++++++-----
 2 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/README.org b/README.org
index 872d2e1a33..a5098487f7 100644
--- a/README.org
+++ b/README.org
@@ -92,8 +92,12 @@ The current line will remain highlighted until another 
command is
 invoked.
 
 #+findex: pulsar-pulse-line
+#+findex: pulsar-highlight-line
 To highlight the current line on demand, use the ~pulsar-pulse-line~
-command.
+command.  When ~pulsar-pulse~ is non-nil (the default), its highlight
+will pulse before fading away.  Whereas the ~pulsar-highlight-line~
+command never pulses the line: the highlight stays in place as if
+~pulsar-pulse~ is nil.
 
 Pulsar depends on the built-in ~pulse.el~ library.
 
@@ -189,6 +193,17 @@ Remember to read the doc string of each of these variables.
 (setq pulsar-delay 0.055)
 (setq pulsar-iterations 10)
 (setq pulsar-face 'pulsar-magenta)
+
+;; pulsar does not define any key bindings.  This is just a sample that
+;; respects the key binding conventions.  Evaluate:
+;;
+;;     (info "(elisp) Key Binding Conventions")
+;;
+;; The author uses C-x l for `pulsar-pulse-line' and C-x L for
+;; `pulsar-highlight-line'.
+(let ((map global-map))
+  (define-key map (kbd "C-c h p") #'pulsar-pulse-line)
+  (define-key map (kbd "C-c h h") #'pulsar-highlight-line))
 #+end_src
 
 * Integration with other packages
diff --git a/pulsar.el b/pulsar.el
index 94ccbd7643..328f0bf336 100644
--- a/pulsar.el
+++ b/pulsar.el
@@ -234,14 +234,37 @@ command is invoked."
       (line-beginning-position 1)
     (line-beginning-position 2)))
 
+(defun pulsar--pulse (&optional no-pulse face)
+  "Highlight the current line.
+With optional NO-PULSE keep the highlight until another command
+is invoked.  Otherwise use whatever `pulsar-pulse' entails.
+
+With optiona FACE, use it instead of `pulsar-face'."
+  (let ((pulse-flag (if no-pulse nil pulsar-pulse))
+        (pulse-delay pulsar-delay)
+        (pulse-iterations pulsar-iterations)
+        (f (if (facep face) face pulsar-face)))
+    (pulse-momentary-highlight-region (pulsar--start) (pulsar--end) f)))
+
 ;;;###autoload
 (defun pulsar-pulse-line ()
-  "Temporarily highlight the current line with optional FACE."
+  "Temporarily highlight the current line.
+When `pulsar-pulse' is non-nil (the default) make the highlight
+pulse before fading away.  The pulse effect is controlled by
+`pulsar-delay' and `pulsar-iterations'.
+
+Also see `pulsar-highlight-line' for a highlight without the
+pulse effect."
   (interactive)
-  (let ((pulse-flag pulsar-pulse)
-        (pulse-delay pulsar-delay)
-        (pulse-iterations pulsar-iterations))
-    (pulse-momentary-highlight-region (pulsar--start) (pulsar--end) 
pulsar-face)))
+  (pulsar--pulse))
+
+;;;###autoload
+(defun pulsar-highlight-line ()
+  "Temporarily highlight the current line.
+Unlike `pulsar-pulse-line', never pulse the current line.  Keep
+the highlight in place until another command is invoked."
+  (interactive)
+  (pulsar--pulse :no-pulse))
 
 ;;;; Advice setup