-;;; beacon.el --- Highlight the cursor whenever it moves long distances -*- lexical-binding: t; -*-
+;;; beacon.el --- Highlight the cursor whenever the window scrolls -*- lexical-binding: t; -*-
-;; Copyright (C) 2015 Artur Malabarba
+;; Copyright (C) 2015 Free Software Foundation, Inc.
;; Author: Artur Malabarba <emacs@endlessparentheses.com>
;; URL: https://github.com/Malabarba/beacon
;;; Commentary:
-;; This is a global minor-mode. Turn it on everywhere with
-;; (beacon-mode 1)
+;; This is a global minor-mode. Turn it on everywhere with:
+;; ┌────
+;; │ (beacon-mode 1)
+;; └────
+;;
+;; Whenever the window scrolls a light will shine on top of your cursor so
+;; you know where it is.
+;;
+;; 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-window-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'.
;;; Code:
"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-duration 0.3
"Time, in seconds, that the blink should last."
:type 'number)
e.g. \"#666600\"."
:type '(choice number color))
+(defcustom 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
+non-nil, the beacon will not blink."
+ :type 'hook)
+
+(add-hook 'beacon-dont-blink-predicates (lambda () (bound-and-true-p hl-line-mode)))
+(add-hook 'beacon-dont-blink-predicates #'window-minibuffer-p)
+
+(defcustom beacon-dont-blink-major-modes '(magit-status-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))
+
\f
;;; Overlays
(defvar beacon--ovs nil)
-(defun beacon--colored-overlay (color)
+(defconst beacon-overlay-priority (/ most-positive-fixnum 2)
+ "Priotiy used on all of our overlays.")
+
+(defun beacon--make-overlay (length &rest properties)
"Put an overlay at point with background COLOR."
- (let ((ov (make-overlay (point) (1+ (point)))))
- (overlay-put ov 'face (list :background color))
+ (let ((ov (make-overlay (point) (+ length (point)))))
(overlay-put ov 'beacon t)
- (push ov beacon--ovs)))
+ ;; 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)
+ ov))
+
+(defun beacon--colored-overlay (color)
+ "Put an overlay at point with background COLOR."
+ (beacon--make-overlay 1 'face (list :background color)))
(defun beacon--ov-put-after-string (overlay colors)
"Add an after-string property to OVERLAY.
The property's value is a string of spaces with background
-COLORS applied to each one."
+COLORS applied to each one.
+If COLORS is nil, OVERLAY is deleted!"
(if (not colors)
- (delete-overlay overlay)
+ (when (overlayp overlay)
+ (delete-overlay overlay))
(overlay-put overlay 'beacon-colors colors)
(overlay-put overlay 'after-string
(propertize
"Put an overlay at point with an after-string property.
The property's value is a string of spaces with background
COLORS applied to each one."
- (let ((ov (make-overlay (point) (point)))
- ;; The after-string must not be longer than the remaining columns from
- ;; point to right window-end else it will be wrapped around (assuming
- ;; truncate-lines is nil) introducing an ugly wrap-around for a
- ;; fraction of a second.
- (colors (seq-take colors (- (window-width) (current-column)))))
- (beacon--ov-put-after-string ov colors)
- (overlay-put ov 'beacon t)
- (push ov beacon--ovs)))
+ ;; The after-string must not be longer than the remaining columns
+ ;; from point to right window-end else it will be wrapped around.
+ (let ((colors (seq-take colors (- (window-width) (current-column)))))
+ (beacon--ov-put-after-string (beacon--make-overlay 0) colors)))
(defun beacon--ov-at-point ()
(car (or (seq-filter (lambda (o) (overlay-get o 'beacon))
"Blink the beacon at the position of the cursor."
(interactive)
(beacon--vanish)
- (beacon--shine)
- (setq beacon--timer
- (run-at-time beacon-blink-delay
- (/ beacon-blink-duration 1.0 beacon-size)
- #'beacon--dec)))
+ (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))
+ (beacon--shine)
+ (setq beacon--timer
+ (run-at-time beacon-blink-delay
+ (/ beacon-blink-duration 1.0 beacon-size)
+ #'beacon--dec))))
\f
;;; Movement detection
+(defvar beacon--window-scrolled nil)
(defvar beacon--previous-place nil)
-(defvar beacon--previous-window-start nil)
(defvar beacon--previous-mark-head nil)
+(defvar beacon--previous-window nil)
(defun beacon--movement-> (delta)
"Return non-nil if latest point movement is > DELTA.
(cond
((not (markerp beacon--previous-place))
(beacon--vanish))
- ;; Blink because we changed buffer.
- ((not (equal (marker-buffer beacon--previous-place)
- (current-buffer)))
- (when beacon-blink-when-buffer-changes
- (unless (window-minibuffer-p)
- (beacon-blink))))
+ ;; 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
- (progn (redisplay)
- (not (equal beacon--previous-window-start (window-start)))))
+ beacon--window-scrolled
+ (equal beacon--window-scrolled (selected-window)))
(beacon-blink))
;; Blink for movement
((beacon--movement-> beacon-blink-when-point-moves)
;; 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-window-start (window-start))
(setq beacon--previous-mark-head (car mark-ring))
- (setq beacon--previous-place (point-marker))))
+ (setq beacon--previous-place (point-marker))
+ (setq beacon--previous-window (selected-window))))
+
+(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
+scrolled window might not be active, but we only know that at
+`post-command-hook'.
+
+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)
+ (beacon-blink)))
\f
;;; Minor-mode
-(defcustom beacon-lighter (cond
- ((char-displayable-p ?💡) " 💡")
- ((char-displayable-p ?Λ) " Λ")
- (t " *"))
+(defcustom beacon-lighter
+ (cond
+ ((char-displayable-p ?💡) " 💡")
+ ((char-displayable-p ?Λ) " Λ")
+ (t " *"))
"Lighter string used on the mode-line."
:type 'string)
nil nil beacon-lighter nil
:global t
(if beacon-mode
- (add-hook 'post-command-hook #'beacon--post-command)
- (remove-hook 'post-command-hook #'beacon--post-command)))
+ (progn
+ (add-hook 'window-scroll-functions #'beacon--window-scroll-function)
+ (add-hook 'post-command-hook #'beacon--post-command)
+ (add-hook 'pre-command-hook #'beacon--vanish))
+ (remove-hook 'window-scroll-functions #'beacon--window-scroll-function)
+ (remove-hook 'post-command-hook #'beacon--post-command)
+ (remove-hook 'pre-command-hook #'beacon--vanish)))
(provide 'beacon)
;;; beacon.el ends here