Improve documentation

[gnu-emacs-elpa] / beacon.el

diff --git a/beacon.el b/beacon.el
index b6aa776aaed2be455962683f3bac549924326b6c..ffdbcbc3b63821ea841747b9edafeff02b2c6575 100644 (file)
--- a/beacon.el
+++ b/beacon.el
@@ -5,7 +5,7 @@
 ;; Author: Artur Malabarba <emacs@endlessparentheses.com>
 ;; URL: https://github.com/Malabarba/beacon
 ;; Keywords: convenience
 ;; Author: Artur Malabarba <emacs@endlessparentheses.com>
 ;; URL: https://github.com/Malabarba/beacon
 ;; Keywords: convenience

-;; Version: 0.1
+;; Version: 0.3

 ;; Package-Requires: ((seq "1.9"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; Package-Requires: ((seq "1.9"))
 
 ;; This program is free software; you can redistribute it and/or modify


@@ -28,33 +28,12 @@
 ;; │ (beacon-mode 1)
 ;; └────
 ;;
 ;; │ (beacon-mode 1)
 ;; └────
 ;;

-;; Whenever the window scrolls or you switch buffer a light will shine on
-;; top of your cursor so you know where it is.
+;; Whenever the window scrolls a light will shine on top of your cursor so
+;; you know where it is.

 ;;
 ;; That’s it.
 ;;
 ;;
 ;; That’s it.
 ;;

-;;
-;; 1 Customizations
-;; ════════════════
-;;
-;;   • The appearance of the beacon is configured by `beacon-size' and
-;;     `beacon-color'.
-;;
-;;   • The duration is configured by `beacon-blink-duration' and
-;;     `beacon-blink-delay'.
-;;
-;;   • To customize /when/ the beacon should blink at all, configure
-;;     `beacon-blink-when-window-scrolls',
-;;     `beacon-blink-when-buffer-changes', and
-;;     `beacon-blink-when-point-moves'.
-;;
-;;   • To prevent the beacon from blinking only on some major-modes,
-;;     configure `beacon-dont-blink-major-modes'. For specific buffers, you
-;;     can do `(setq-local beacon-mode nil)'. For even more refined
-;;     control, configure `beacon-dont-blink-predicates'
-;;
-;;   • Beacon can also push the mark for you whenever point moves a long
-;;     distance. For this, configure `beacon-push-mark'.
+;; See the accompanying Readme.org for configuration details.

 
 ;;; Code:
 
 
 ;;; Code:
 


@@ -67,7 +46,7 @@
 
 (defvar beacon--timer nil)
 
 
 (defvar beacon--timer nil)
 

-(defcustom beacon-push-mark nil
+(defcustom beacon-push-mark 35

   "Should the mark be pushed before long movements?
 If nil, `beacon' will not push the mark.
 Otherwise this should be a number, and `beacon' will push the
   "Should the mark be pushed before long movements?
 If nil, `beacon' will not push the mark.
 Otherwise this should be a number, and `beacon' will push the


@@ -89,6 +68,17 @@ movement distance (in lines) that triggers a beacon blink."
   "Should the beacon blink when the window scrolls?"
   :type 'boolean)
 
   "Should the beacon blink when the window scrolls?"
   :type 'boolean)
 

+(defcustom beacon-blink-when-window-changes t
+  "Should the beacon blink when the window changes?"
+  :type 'boolean)
+
+(defcustom beacon-blink-when-focused nil
+  "Should the beacon blink when Emacs gains focus?
+Note that, due to a limitation of `focus-in-hook', this might
+trigger false positives on some systems."
+  :type 'boolean
+  :package-version '(beacon . "0.2"))
+

 (defcustom beacon-blink-duration 0.3
   "Time, in seconds, that the blink should last."
   :type 'number)
 (defcustom beacon-blink-duration 0.3
   "Time, in seconds, that the blink should last."
   :type 'number)


@@ -113,23 +103,56 @@ If it is a string, it is a color name or specification,
 e.g. \"#666600\"."
   :type '(choice number color))
 
 e.g. \"#666600\"."
   :type '(choice number color))
 

-(defcustom beacon-dont-blink-predicates nil
+(defface beacon-fallback-background
+  '((((class color) (background light)) (:background "black"))
+    (((class color) (background dark)) (:background "white")))
+  "Fallback beacon background color.
+Used in cases where the color can't be determined by Emacs.
+Only the background of this face is used.")
+
+(defvar beacon-dont-blink-predicates nil

   "A list of predicates that prevent the beacon blink.
 These predicate functions are called in order, with no
 arguments, before blinking the beacon.  If any returns
   "A list of predicates that prevent the beacon blink.
 These predicate functions are called in order, with no
 arguments, before blinking the beacon.  If any returns

-non-nil, the beacon will not blink."
-  :type 'hook)
+non-nil, the beacon will not blink.
+
+For instance, if you want to disable beacon on buffers where
+`hl-line-mode' is on, you can do:
+
+    (add-hook \\='beacon-dont-blink-predicates
+              (lambda () (bound-and-true-p hl-line-mode)))")

 
 

-(add-hook 'beacon-dont-blink-predicates (lambda () (bound-and-true-p hl-line-mode)))

 (add-hook 'beacon-dont-blink-predicates #'window-minibuffer-p)
 
 (add-hook 'beacon-dont-blink-predicates #'window-minibuffer-p)
 

-(defcustom beacon-dont-blink-major-modes nil
+(defcustom beacon-dont-blink-major-modes '(magit-status-mode magit-popup-mode)

   "A list of major-modes where the beacon won't blink.
 Whenever the current buffer satisfies `derived-mode-p' for
 one of the major-modes on this list, the beacon will not
 blink."
   :type '(repeat symbol))
 
   "A list of major-modes where the beacon won't blink.
 Whenever the current buffer satisfies `derived-mode-p' for
 one of the major-modes on this list, the beacon will not
 blink."
   :type '(repeat symbol))
 

+(defcustom beacon-dont-blink-commands '(recenter-top-bottom)
+  "A list of commands that should not make the beacon blink.
+Use this for commands that scroll the window in very
+predictable ways, when the blink would be more distracting
+than helpful.."
+  :type '(repeat symbol))
+
+\f
+;;; Internal variables
+(defvar beacon--window-scrolled nil)
+(defvar beacon--previous-place nil)
+(defvar beacon--previous-mark-head nil)
+(defvar beacon--previous-window nil)
+(defvar beacon--previous-window-start 0)
+
+(defun beacon--record-vars ()
+  (unless (window-minibuffer-p)
+    (setq beacon--previous-mark-head (car mark-ring))
+    (setq beacon--previous-place (point-marker))
+    (setq beacon--previous-window (selected-window))
+    (setq beacon--previous-window-start (window-start))))
+

 \f
 ;;; Overlays
 (defvar beacon--ovs nil)
 \f
 ;;; Overlays
 (defvar beacon--ovs nil)


@@ -144,6 +167,7 @@ blink."
     ;; Our overlay is very temporary, so we take the liberty of giving
     ;; it a high priority.
     (overlay-put ov 'priority beacon-overlay-priority)
     ;; Our overlay is very temporary, so we take the liberty of giving
     ;; it a high priority.
     (overlay-put ov 'priority beacon-overlay-priority)

+    (overlay-put ov 'window (selected-window))

     (while properties
       (overlay-put ov (pop properties) (pop properties)))
     (push ov beacon--ovs)
     (while properties
       (overlay-put ov (pop properties) (pop properties)))
     (push ov beacon--ovs)


@@ -204,7 +228,10 @@ Only returns `beacon-size' elements."
 
 (defun beacon--color-range ()
   "Return a list of background colors for the beacon."
 
 (defun beacon--color-range ()
   "Return a list of background colors for the beacon."

-  (let* ((bg (color-values (face-attribute 'default :background)))
+  (let* ((default-bg (face-attribute 'default :background))
+         (bg (color-values (if (string-match "\\`unspecified-" default-bg)
+                               (face-attribute 'beacon-fallback-background :background)
+                             default-bg)))

          (fg (cond
               ((stringp beacon-color) (color-values beacon-color))
               ((< (color-distance "black" bg)
          (fg (cond
               ((stringp beacon-color) (color-values beacon-color))
               ((< (color-distance "black" bg)


@@ -252,9 +279,13 @@ Only returns `beacon-size' elements."
   "Blink the beacon at the position of the cursor."
   (interactive)
   (beacon--vanish)
   "Blink the beacon at the position of the cursor."
   (interactive)
   (beacon--vanish)

+  ;; Record vars here in case something is blinking outside the
+  ;; command loop.
+  (beacon--record-vars)

   (unless (or (not beacon-mode)
               (run-hook-with-args-until-success 'beacon-dont-blink-predicates)
   (unless (or (not beacon-mode)
               (run-hook-with-args-until-success 'beacon-dont-blink-predicates)

-              (seq-find #'derived-mode-p beacon-dont-blink-major-modes))
+              (seq-find #'derived-mode-p beacon-dont-blink-major-modes)
+              (memq (or this-command last-command) beacon-dont-blink-commands))

     (beacon--shine)
     (setq beacon--timer
           (run-at-time beacon-blink-delay
     (beacon--shine)
     (setq beacon--timer
           (run-at-time beacon-blink-delay


@@ -263,10 +294,6 @@ Only returns `beacon-size' elements."
 
 \f
 ;;; Movement detection
 
 \f
 ;;; Movement detection

-(defvar beacon--window-scrolled nil)
-(defvar beacon--previous-place nil)
-(defvar beacon--previous-mark-head nil)
-

 (defun beacon--movement-> (delta)
   "Return non-nil if latest point movement is > DELTA.
 If DELTA is nil, return nil."
 (defun beacon--movement-> (delta)
   "Return non-nil if latest point movement is > DELTA.
 If DELTA is nil, return nil."


@@ -274,11 +301,19 @@ If DELTA is nil, return nil."
        (markerp beacon--previous-place)
        (equal (marker-buffer beacon--previous-place)
               (current-buffer))
        (markerp beacon--previous-place)
        (equal (marker-buffer beacon--previous-place)
               (current-buffer))

+       ;; Quick check that prevents running the code below in very
+       ;; short movements (like typing).

        (> (abs (- (point) beacon--previous-place))
           delta)
        (> (abs (- (point) beacon--previous-place))
           delta)

-       (> (count-screen-lines (min (point) beacon--previous-place)
-                              (max (point) beacon--previous-place))
-          delta)))
+       ;; Check if the movement was >= DELTA lines by moving DELTA
+       ;; lines. `count-screen-lines' is too slow if the movement had
+       ;; thousands of lines.
+       (save-excursion
+         (let ((p (point)))
+           (goto-char (min beacon--previous-place p))
+           (vertical-motion delta)
+           (> (max p beacon--previous-place)
+              (line-beginning-position))))))

 
 (defun beacon--maybe-push-mark ()
   "Push mark if it seems to be safe."
 
 (defun beacon--maybe-push-mark ()
   "Push mark if it seems to be safe."


@@ -294,6 +329,10 @@ If DELTA is nil, return nil."
   (cond
    ((not (markerp beacon--previous-place))
     (beacon--vanish))
   (cond
    ((not (markerp beacon--previous-place))
     (beacon--vanish))

+   ;; Blink for switching windows.
+   ((and beacon-blink-when-window-changes
+         (not (eq beacon--previous-window (selected-window))))
+    (beacon-blink))

    ;; Blink for scrolling.
    ((and beacon-blink-when-window-scrolls
          beacon--window-scrolled
    ;; Blink for scrolling.
    ((and beacon-blink-when-window-scrolls
          beacon--window-scrolled


@@ -305,12 +344,9 @@ If DELTA is nil, return nil."
    ;; Even if we don't blink, vanish any previous beacon.
    (t (beacon--vanish)))
   (beacon--maybe-push-mark)
    ;; Even if we don't blink, vanish any previous beacon.
    (t (beacon--vanish)))
   (beacon--maybe-push-mark)

-  (setq beacon--window-scrolled nil)
-  (unless (window-minibuffer-p)
-    (setq beacon--previous-mark-head (car mark-ring))
-    (setq beacon--previous-place (point-marker))))
+  (setq beacon--window-scrolled nil))

 
 

-(defun beacon--window-scroll-function (win _start-pos)
+(defun beacon--window-scroll-function (win start-pos)

   "Blink the beacon or record that window has been scrolled.
 If invoked during the command loop, record the current window so
 that it may be blinked on post-command.  This is because the
   "Blink the beacon or record that window has been scrolled.
 If invoked during the command loop, record the current window so
 that it may be blinked on post-command.  This is because the


@@ -319,18 +355,25 @@ scrolled window might not be active, but we only know that at
 
 If invoked outside the command loop, `post-command-hook' would be
 unreliable, so just blink immediately."
 
 If invoked outside the command loop, `post-command-hook' would be
 unreliable, so just blink immediately."

-  (if this-command
-      (setq beacon--window-scrolled win)
-    (setq beacon--window-scrolled nil)
+  (unless (and (equal beacon--previous-window-start start-pos)
+               (equal beacon--previous-window win))
+    (if this-command
+        (setq beacon--window-scrolled win)
+      (setq beacon--window-scrolled nil)
+      (beacon-blink))))
+
+(defun beacon--blink-on-focus ()
+  "Blink if `beacon-blink-when-focused' is non-nil"
+  (when beacon-blink-when-focused

     (beacon-blink)))
 
 \f
 ;;; Minor-mode
 (defcustom beacon-lighter
   (cond
     (beacon-blink)))
 
 \f
 ;;; Minor-mode
 (defcustom beacon-lighter
   (cond

-   ((char-displayable-p ?💡) " 💡")
-   ((char-displayable-p ?Λ) " Λ")
-   (t " *"))
+   ;; ((char-displayable-p ?💡) " 💡")
+   ;; ((char-displayable-p ?Λ) " Λ")
+   (t " (*)"))

   "Lighter string used on the mode-line."
   :type 'string)
 
   "Lighter string used on the mode-line."
   :type 'string)
 


@@ -341,11 +384,19 @@ unreliable, so just blink immediately."
   (if beacon-mode
       (progn
         (add-hook 'window-scroll-functions #'beacon--window-scroll-function)
   (if beacon-mode
       (progn
         (add-hook 'window-scroll-functions #'beacon--window-scroll-function)

+        (add-hook 'focus-in-hook #'beacon--blink-on-focus)

         (add-hook 'post-command-hook #'beacon--post-command)
         (add-hook 'post-command-hook #'beacon--post-command)

+        (add-hook 'pre-command-hook #'beacon--record-vars)

         (add-hook 'pre-command-hook #'beacon--vanish))
         (add-hook 'pre-command-hook #'beacon--vanish))

+    (remove-hook 'focus-in-hook #'beacon--blink-on-focus)

     (remove-hook 'window-scroll-functions #'beacon--window-scroll-function)
     (remove-hook 'post-command-hook #'beacon--post-command)
     (remove-hook 'window-scroll-functions #'beacon--window-scroll-function)
     (remove-hook 'post-command-hook #'beacon--post-command)

+    (remove-hook 'pre-command-hook #'beacon--record-vars)

     (remove-hook 'pre-command-hook #'beacon--vanish)))
 
 (provide 'beacon)
 ;;; beacon.el ends here
     (remove-hook 'pre-command-hook #'beacon--vanish)))
 
 (provide 'beacon)
 ;;; beacon.el ends here

+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; End: