lisp/hl-line.el

   1 ;;; hl-line.el --- highlight the current line  -*- lexical-binding:t -*-
   2
   3 ;; Copyright (C) 1998, 2000-2017 Free Software Foundation, Inc.
   4
   5 ;; Author:  Dave Love <fx@gnu.org>
   6 ;; Maintainer: emacs-devel@gnu.org
   7 ;; Created: 1998-09-13
   8 ;; Keywords: faces, frames, emulations
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26
  27 ;; Provides a local minor mode (toggled by M-x hl-line-mode) and
  28 ;; a global minor mode (toggled by M-x global-hl-line-mode) to
  29 ;; highlight, on a suitable terminal, the line on which point is.  The
  30 ;; global mode highlights the current line in the selected window only
  31 ;; (except when the minibuffer window is selected).  This was
  32 ;; implemented to satisfy a request for a feature of Lesser Editors.
  33 ;; The local mode is sticky: it highlights the line about the buffer's
  34 ;; point even if the buffer's window is not selected.  Caveat: the
  35 ;; buffer's point might be different from the point of a non-selected
  36 ;; window.  Set the variable `hl-line-sticky-flag' to nil to make the
  37 ;; local mode behave like the global mode.
  38
  39 ;; You probably don't really want to use the global mode; if the
  40 ;; cursor is difficult to spot, try changing its color, relying on
  41 ;; `blink-cursor-mode' or both.  The hookery used might affect
  42 ;; response noticeably on a slow machine.  The local mode may be
  43 ;; useful in non-editing buffers such as Gnus or PCL-CVS though.
  44
  45 ;; An overlay is used.  In the non-sticky cases, this overlay is
  46 ;; active only on the selected window.  A hook is added to
  47 ;; `post-command-hook' to activate the overlay and move it to the line
  48 ;; about point.  To get the non-sticky behavior, `hl-line-unhighlight'
  49 ;; is added to `pre-command-hook' as well.  This function deactivates
  50 ;; the overlay unconditionally in case the command changes the
  51 ;; selected window.  (It does so rather than keeping track of changes
  52 ;; in the selected window).
  53
  54 ;; You could make variable `global-hl-line-mode' buffer-local and set
  55 ;; it to nil to avoid highlighting specific buffers, when the global
  56 ;; mode is used.
  57
  58 ;; By default the whole line is highlighted.  The range of highlighting
  59 ;; can be changed by defining an appropriate function as the
  60 ;; buffer-local value of `hl-line-range-function'.
  61
  62 ;;; Code:
  63
  64 (defvar-local hl-line-overlay nil
  65   "Overlay used by Hl-Line mode to highlight the current line.")
  66
  67 (defvar-local global-hl-line-overlay nil
  68   "Overlay used by Global-Hl-Line mode to highlight the current line.")
  69
  70 (defvar global-hl-line-overlays nil
  71   "Overlays used by Global-Hl-Line mode in various buffers.
  72 Global-Hl-Line keeps displaying one overlay in each buffer
  73 when `global-hl-line-sticky-flag' is non-nil.")
  74
  75 (defgroup hl-line nil
  76   "Highlight the current line."
  77   :version "21.1"
  78   :group 'convenience)
  79
  80 (defface hl-line
  81   '((t :inherit highlight))
  82   "Default face for highlighting the current line in Hl-Line mode."
  83   :version "22.1"
  84   :group 'hl-line)
  85
  86 (defcustom hl-line-face 'hl-line
  87   "Face with which to highlight the current line in Hl-Line mode."
  88   :type 'face
  89   :group 'hl-line
  90   :set (lambda (symbol value)
  91          (set symbol value)
  92          (dolist (buffer (buffer-list))
  93            (with-current-buffer buffer
  94              (when hl-line-overlay
  95                (overlay-put hl-line-overlay 'face hl-line-face))))
  96          (when global-hl-line-overlay
  97            (overlay-put global-hl-line-overlay 'face hl-line-face))))
  98
  99 (defcustom hl-line-sticky-flag t
 100   "Non-nil means the HL-Line mode highlight appears in all windows.
 101 Otherwise Hl-Line mode will highlight only in the selected
 102 window.  Setting this variable takes effect the next time you use
 103 the command `hl-line-mode' to turn Hl-Line mode on.
 104
 105 This variable has no effect in Global Highlight Line mode.
 106 For that, use `global-hl-line-sticky-flag'."
 107   :type 'boolean
 108   :version "22.1"
 109   :group 'hl-line)
 110
 111 (defcustom global-hl-line-sticky-flag nil
 112   "Non-nil means the Global HL-Line mode highlight appears in all windows.
 113 Otherwise Global Hl-Line mode will highlight only in the selected
 114 window.  Setting this variable takes effect the next time you use
 115 the command `global-hl-line-mode' to turn Global Hl-Line mode on."
 116   :type 'boolean
 117   :version "24.1"
 118   :group 'hl-line)
 119
 120 (defvar hl-line-range-function nil
 121   "If non-nil, function to call to return highlight range.
 122 The function of no args should return a cons cell; its car value
 123 is the beginning position of highlight and its cdr value is the
 124 end position of highlight in the buffer.
 125 It should return nil if there's no region to be highlighted.
 126
 127 This variable is expected to be made buffer-local by modes.")
 128
 129 (defvar hl-line-overlay-buffer nil
 130   "Most recently visited buffer in which Hl-Line mode is enabled.")
 131
 132 ;;;###autoload
 133 (define-minor-mode hl-line-mode
 134   "Toggle highlighting of the current line (Hl-Line mode).
 135 With a prefix argument ARG, enable Hl-Line mode if ARG is
 136 positive, and disable it otherwise.  If called from Lisp, enable
 137 the mode if ARG is omitted or nil.
 138
 139 Hl-Line mode is a buffer-local minor mode.  If
 140 `hl-line-sticky-flag' is non-nil, Hl-Line mode highlights the
 141 line about the buffer's point in all windows.  Caveat: the
 142 buffer's point might be different from the point of a
 143 non-selected window.  Hl-Line mode uses the function
 144 `hl-line-highlight' on `post-command-hook' in this case.
 145
 146 When `hl-line-sticky-flag' is nil, Hl-Line mode highlights the
 147 line about point in the selected window only.  In this case, it
 148 uses the function `hl-line-maybe-unhighlight' in
 149 addition to `hl-line-highlight' on `post-command-hook'."
 150   :group 'hl-line
 151   (if hl-line-mode
 152       (progn
 153         ;; In case `kill-all-local-variables' is called.
 154         (add-hook 'change-major-mode-hook #'hl-line-unhighlight nil t)
 155         (hl-line-highlight)
 156         (setq hl-line-overlay-buffer (current-buffer))
 157         (add-hook 'post-command-hook #'hl-line-highlight nil t)
 158         (add-hook 'post-command-hook #'hl-line-maybe-unhighlight nil t))
 159     (remove-hook 'post-command-hook #'hl-line-highlight t)
 160     (hl-line-unhighlight)
 161     (remove-hook 'change-major-mode-hook #'hl-line-unhighlight t)
 162     (remove-hook 'post-command-hook #'hl-line-maybe-unhighlight t)))
 163
 164 (defun hl-line-make-overlay ()
 165   (let ((ol (make-overlay (point) (point))))
 166     (overlay-put ol 'priority -50)           ;(bug#16192)
 167     (overlay-put ol 'face hl-line-face)
 168     ol))
 169
 170 (defun hl-line-highlight ()
 171   "Activate the Hl-Line overlay on the current line."
 172   (if hl-line-mode      ; Might be changed outside the mode function.
 173       (progn
 174         (unless hl-line-overlay
 175           (setq hl-line-overlay (hl-line-make-overlay))) ; To be moved.
 176         (overlay-put hl-line-overlay
 177                      'window (unless hl-line-sticky-flag (selected-window)))
 178         (hl-line-move hl-line-overlay))
 179     (hl-line-unhighlight)))
 180
 181 (defun hl-line-unhighlight ()
 182   "Deactivate the Hl-Line overlay on the current line."
 183   (when hl-line-overlay
 184     (delete-overlay hl-line-overlay)))
 185
 186 (defun hl-line-maybe-unhighlight ()
 187   "Maybe deactivate the Hl-Line overlay on the current line.
 188 Specifically, when `hl-line-sticky-flag' is nil deactivate all
 189 such overlays in all buffers except the current one."
 190   (let ((hlob hl-line-overlay-buffer)
 191         (curbuf (current-buffer)))
 192     (when (and (buffer-live-p hlob)
 193                (not hl-line-sticky-flag)
 194                (not (eq curbuf hlob))
 195                (not (minibufferp)))
 196       (with-current-buffer hlob
 197         (when (overlayp hl-line-overlay)
 198           (delete-overlay hl-line-overlay))))
 199     (when (and (overlayp hl-line-overlay)
 200                (eq (overlay-buffer hl-line-overlay) curbuf))
 201       (setq hl-line-overlay-buffer curbuf))))
 202
 203 ;;;###autoload
 204 (define-minor-mode global-hl-line-mode
 205   "Toggle line highlighting in all buffers (Global Hl-Line mode).
 206 With a prefix argument ARG, enable Global Hl-Line mode if ARG is
 207 positive, and disable it otherwise.  If called from Lisp, enable
 208 the mode if ARG is omitted or nil.
 209
 210 If `global-hl-line-sticky-flag' is non-nil, Global Hl-Line mode
 211 highlights the line about the current buffer's point in all live
 212 windows.
 213
 214 Global-Hl-Line mode uses the functions `global-hl-line-highlight'
 215 and `global-hl-line-maybe-unhighlight' on `post-command-hook'."
 216   :global t
 217   :group 'hl-line
 218   (if global-hl-line-mode
 219       (progn
 220         ;; In case `kill-all-local-variables' is called.
 221         (add-hook 'change-major-mode-hook #'global-hl-line-unhighlight)
 222         (global-hl-line-highlight-all)
 223         (add-hook 'post-command-hook #'global-hl-line-highlight)
 224         (add-hook 'post-command-hook #'global-hl-line-maybe-unhighlight))
 225     (global-hl-line-unhighlight-all)
 226     (remove-hook 'post-command-hook #'global-hl-line-highlight)
 227     (remove-hook 'change-major-mode-hook #'global-hl-line-unhighlight)
 228     (remove-hook 'post-command-hook #'global-hl-line-maybe-unhighlight)))
 229
 230 (defun global-hl-line-highlight ()
 231   "Highlight the current line in the current window."
 232   (when global-hl-line-mode     ; Might be changed outside the mode function.
 233     (unless (window-minibuffer-p)
 234       (unless global-hl-line-overlay
 235         (setq global-hl-line-overlay (hl-line-make-overlay))) ; To be moved.
 236       (unless (member global-hl-line-overlay global-hl-line-overlays)
 237         (push global-hl-line-overlay global-hl-line-overlays))
 238       (overlay-put global-hl-line-overlay 'window
 239                    (unless global-hl-line-sticky-flag
 240                      (selected-window)))
 241       (hl-line-move global-hl-line-overlay))))
 242
 243 (defun global-hl-line-highlight-all ()
 244   "Highlight the current line in all live windows."
 245   (walk-windows (lambda (w)
 246                   (with-current-buffer (window-buffer w)
 247                     (global-hl-line-highlight)))
 248                 nil t))
 249
 250 (defun global-hl-line-unhighlight ()
 251   "Deactivate the Global-Hl-Line overlay on the current line."
 252   (when global-hl-line-overlay
 253     (delete-overlay global-hl-line-overlay)))
 254
 255 (defun global-hl-line-maybe-unhighlight ()
 256   "Maybe deactivate the Global-Hl-Line overlay on the current line.
 257 Specifically, when `global-hl-line-sticky-flag' is nil deactivate
 258 all such overlays in all buffers except the current one."
 259   (mapc (lambda (ov)
 260           (let ((ovb (overlay-buffer ov)))
 261             (when (and (not global-hl-line-sticky-flag)
 262                        (bufferp ovb)
 263                        (not (eq ovb (current-buffer)))
 264                        (not (minibufferp)))
 265                 (with-current-buffer ovb
 266                   (when (overlayp global-hl-line-overlay)
 267                     (delete-overlay global-hl-line-overlay))))))
 268         global-hl-line-overlays))
 269
 270 (defun global-hl-line-unhighlight-all ()
 271   "Deactivate all Global-Hl-Line overlays."
 272   (mapc (lambda (ov)
 273           (let ((ovb (overlay-buffer ov)))
 274             (when (bufferp ovb)
 275                 (with-current-buffer ovb
 276                   (global-hl-line-unhighlight)))))
 277         global-hl-line-overlays)
 278   (setq global-hl-line-overlays nil))
 279
 280 (defun hl-line-move (overlay)
 281   "Move the Hl-Line overlay.
 282 If `hl-line-range-function' is non-nil, move the OVERLAY to the position
 283 where the function returns.  If `hl-line-range-function' is nil, fill
 284 the line including the point by OVERLAY."
 285   (let (tmp b e)
 286     (if hl-line-range-function
 287         (setq tmp (funcall hl-line-range-function)
 288               b   (car tmp)
 289               e   (cdr tmp))
 290       (setq tmp t
 291             b (line-beginning-position)
 292             e (line-beginning-position 2)))
 293     (if tmp
 294         (move-overlay overlay b e)
 295       (move-overlay overlay 1 1))))
 296
 297 (defun hl-line-unload-function ()
 298   "Unload the Hl-Line library."
 299   (global-hl-line-mode -1)
 300   (save-current-buffer
 301     (dolist (buffer (buffer-list))
 302       (set-buffer buffer)
 303       (when hl-line-mode (hl-line-mode -1))))
 304   ;; continue standard unloading
 305   nil)
 306
 307 (provide 'hl-line)
 308
 309 ;;; hl-line.el ends here