nav-flash: Added new layer variable and other changes

- Added a new layer variable `nav-flash-exclude-modes` which tells
`nav-flash/blink-cursor-maybe` not to trigger when the major mode matches one of
its elements.
- Expanded the documentation.
- Tidying up.

layers/+misc/nav-flash/README.org

@@ -5,7 +5,10 @@
 * Table of Contents                     :TOC_5_gh:noexport:
 - [[#description][Description]]
   - [[#features][Features:]]
-- [[#install][Install]]
+- [[#installation][Installation]]
+- [[#customization][Customization]]
+  - [[#custom-trigger-of-nav-flash][Custom Trigger of =nav-flash=]]
+  - [[#exclusion-rules][Exclusion Rules]]
 
 * Description
 This layer adds [[https://github.com/rolandwalker/nav-flash][nav-flash]] package which temporarily highlights the line
@@ -15,7 +18,50 @@ navigation command.
 ** Features:
 - Fancy flashing line on navigation.
 
-* Install
-To use this configuration layer, add it to your =~/.spacemacs=. You will need to
-add =nav-flash= to the existing =dotspacemacs-configuration-layers= list in this
-file.
+* Installation
+To use this configuration layer, add =nav-flash= to the existing
+=dotspacemacs-configuration-layers= list in your =~/.spacemacs=.
+
+#+BEGIN_SRC emacs-lisp
+  (setq-default dotspacemacs-configuration-layers
+                '(nav-flash))
+#+END_SRC
+
+* Customization
+** Custom Trigger of =nav-flash=
+=nav-flash= layer works around the following functions:
+
+- =nav-flash/blink-cursor-maybe= blinks the line containing the point unless
+  current major mode or current command is excluded, or if =so-long-minor-mode=
+  is on.
+- =nav-flash/delayed-blink-cursor-h= blinks after a short pause, which is useful
+  to wait for the point moving to the correct window.
+
+They are added to [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Hooks.html][hooks]] or [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Advising-Functions.html][after advices]] of various functions. You can trigger
+=nav-flash= in more context viaa =dotspacemacs/user-config=, for example:
+
+#+BEGIN_SRC emacs-lisp
+;; blink after triggering evil-window-left/right/up/down
+(advice-add #'evil-window-left  :after #'nav-flash/blink-cursor-maybe)
+(advice-add #'evil-window-right :after #'nav-flash/blink-cursor-maybe)
+(advice-add #'evil-window-up    :after #'nav-flash/blink-cursor-maybe)
+(advice-add #'evil-window-down  :after #'nav-flash/blink-cursor-maybe)
+
+;; blink after a delay in after projectile-switch-project
+(spacemacs/add-to-hooks #'nav-flash/delayed-blink-cursor-h
+                        '(projectile-after-switch-project-hook)
+                        t)
+#+END_SRC
+
+** Exclusion Rules
+=nav-flash/blink-cursor-maybe= is configured not to flash the line when either
+the command or the major mode is excluded, which can be customized via variables
+=nav-flash-exclude-commands= and =nav-flash-exlude-modes= in your
+=dotspacemacs/user-config=. For example,
+
+#+BEGIN_SRC emacs-lisp
+;; don't trigger in dired-mode
+(add-to-list 'nav-flash-exclude-modes 'dired-mode )
+;; don't trigger for spacemacs/alternate-buffer (SPC TAB)
+(add-to-list 'nav-flash-exclude-commands 'spacemacs/alternate-buffer)
+#+END_SRC

layers/+misc/nav-flash/config.el

@@ -20,10 +20,16 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-(defvar nav-flash-exclude-commands
+(spacemacs|defc nav-flash-exclude-modes
+  '(special-mode term-mode vterm-mode so-long-mode)
+  "A list of major mode that should not trigger `nav-flash'."
+  '(repeat symbol))
+
+(spacemacs|defc nav-flash-exclude-commands
   '(mouse-set-point mouse-drag-region evil-mouse-drag-region +org/dwim-at-point
                     org-find-file org-find-file-at-mouse)
-  "A list of commands that should not trigger nav-flash.")
+  "A list of commands that should not trigger `nav-flash'."
+  '(repeat symbol))
 
 (defvar nav-flash--last-point nil
-  "internal variable for nav-flash.")
+  "Internal variable to store the last point and windoow before blinking.")

layers/+misc/nav-flash/funcs.el

@@ -21,29 +21,30 @@
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 (defun nav-flash//blink-cursor (&rest _)
-  "Blinks the current line in the current window, to make it clear where the
-cursor has landed (typically after a large motion, like switching windows or
-jumping to another part of the file)."
+  "Blink the line containing hte point.
+This makes it clear where the cursor has landed (typically after a large motion,
+like switching windows or jumping to another part of the file)."
   (unless (minibufferp)
     (nav-flash-show)
     ;; only show in the current window
     (overlay-put compilation-highlight-overlay 'window (selected-window))))
 
 (defun nav-flash/blink-cursor-maybe (&rest _)
-  "Like `nav-flash//blink-cursor', but no-ops if in special-mode, term-mode,
-vterm-mode, or triggered from one of `nav-flash-exclude-commands'."
+  "Like `nav-flash//blink-cursor', but no-ops if any following condition is met.
+- If it's trigger by one of `nav-flash-exclude-commands'.
+- If current major mode is one of `nav-flash-exclude-modes'.
+- If `so-long-minor-mode' is on."
   (unless (or (memq this-command nav-flash-exclude-commands)
               (bound-and-true-p so-long-minor-mode)
-              (derived-mode-p 'so-long-mode 'special-mode 'term-mode
-                              'vterm-mode)
+              (apply #'derived-mode-p nav-flash-exclude-modes)
               (and (equal (point-marker) (car nav-flash--last-point))
                    (equal (selected-window) (cdr nav-flash--last-point))))
     (nav-flash//blink-cursor)
     (setq nav-flash--last-point (cons (point-marker) (selected-window)))))
 
 (defun nav-flash/delayed-blink-cursor-h (&rest _)
-  "Like `nav-flash//blink-cursor', but links after a tiny pause, in case it
-isn't clear at run-time if the point will be in the correct window/buffer (like
+  "Like `nav-flash//blink-cursor', but blinks after a tiny pause.
+Useful at run-time to ensure the point be in the correct window/buffer (like
 for `org-follow-link-hook')."
   (run-at-time 0.1 nil #'nav-flash//blink-cursor))
 

layers/+misc/nav-flash/packages.el

@@ -40,8 +40,6 @@
   ;; `org'
   (add-hook 'org-follow-link-hook #'nav-flash/delayed-blink-cursor-h)
 
-  ;; (add-hook 'persp-activated-functions #'nav-flash/delayed-blink-cursor-h)
-
   ;; `saveplace'
   (advice-add #'save-place-find-file-hook :after #'nav-flash/blink-cursor-maybe)
 
@@ -71,7 +69,5 @@
   (advice-add 'persp-switch :after #'nav-flash/delayed-blink-cursor-h)
 
   :config
-  ;; emacs 27 extend face
-  (when (fboundp 'set-face-extend)
   (with-eval-after-load "nav-flash"
-      (set-face-extend 'nav-flash-face t))))
+    (set-face-extend 'nav-flash-face t)))