New org capture template
[emacs.git] / .emacs.d / elisp / icicle / hl-line+.el
1 ;;; hl-line+.el --- Extensions to hl-line.el.
2 ;;
3 ;; Filename: hl-line+.el
4 ;; Description: Extensions to hl-line.el.
5 ;; Author: Drew Adams
6 ;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
7 ;; Copyright (C) 2006-2014, Drew Adams, all rights reserved.
8 ;; Created: Sat Aug 26 18:17:18 2006
9 ;; Version: 0
10 ;; Package-Requires: ()
11 ;; Last-Updated: Thu Dec 26 09:26:18 2013 (-0800)
12 ;; By: dradams
13 ;; Update #: 485
14 ;; URL: http://www.emacswiki.org/hl-line+.el
15 ;; Doc URL: http://www.emacswiki.org/HighlightCurrentLine
16 ;; Doc URL: http://www.emacswiki.org/CrosshairHighlighting
17 ;; Keywords: highlight, cursor, accessibility
18 ;; Compatibility: GNU Emacs: 22.x, 23.x, 24.x
19 ;;
20 ;; Features that might be required by this library:
21 ;;
22 ;; `hl-line'.
23 ;;
24 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
25 ;;
26 ;;; Commentary:
27 ;;
28 ;; This library extends standard library `hl-line.el' in these ways:
29 ;;
30 ;; 1. As an alternative to turning on `hl-line' highlighting at all
31 ;; times, you can turn it on only when Emacs is idle. To do that,
32 ;; use command `toggle-hl-line-when-idle' and customize
33 ;; `global-hl-line-mode' to nil.
34 ;;
35 ;; 2. As another alternative, you can turn it on for only a few
36 ;; seconds. To do that, use command `flash-line-highlight' and
37 ;; customize `global-hl-line-mode' to nil.
38 ;;
39 ;; 3. It provides a face, `hl-line', that you can customize, instead
40 ;; of using option `hl-line-face'.
41 ;;
42 ;; I suggested #3 to the Emacs developers, and it was added to
43 ;; Emacs 22, but with a different default value. If you use
44 ;; library `crosshairs.el', you might want to customize this to a
45 ;; value similar to what is used there, so that the horizontal and
46 ;; vertical highlights will be the same.
47 ;;
48 ;; 4. Option `hl-line-overlay-priority' is provided, so that you can
49 ;; make hl-line highlighting appear on top of other overlay
50 ;; highlighting that might exist.
51 ;;
52 ;; To use this library, put this in your Emacs init file (~/.emacs):
53 ;;
54 ;; (require 'hl-line+) ; Load this file (it will load `hl-line.el')
55 ;;
56 ;; To turn on `global-hl-line-mode' only when Emacs is idle, by
57 ;; default, add this line also to your init file:
58 ;;
59 ;; (toggle-hl-line-when-idle 1) ; Highlight only when idle
60 ;;
61 ;; You can use command `toggle-hl-line-when-idle' to turn idle
62 ;; highlighting on and off at any time. You can use command
63 ;; `hl-line-when-idle-interval' to change the number of idle seconds
64 ;; to wait before highlighting.
65 ;;
66 ;;
67 ;; See also these libraries:
68 ;;
69 ;; * `col-highlight.el', which highlights the current column.
70 ;;
71 ;; * `crosshairs.el', which highlights the current line and the
72 ;; current column, at the same time. It requires libraries
73 ;; `col-highlight.el' and `hl-line+.el'.
74 ;;
75 ;; * `hl-spotlight.el', which extends `hl-line.el' by spotlighting
76 ;; the lines around the cursor.
77 ;;
78 ;; * `cursor-chg.el' or library `oneonone.el', to change the cursor
79 ;; type when Emacs is idle.
80 ;;
81 ;;
82 ;; Faces defined here:
83 ;;
84 ;; `hl-line'.
85 ;;
86 ;; User options defined here:
87 ;;
88 ;; `hl-line-flash-show-period',
89 ;; `hl-line-inhibit-highlighting-for-modes',
90 ;; `hl-line-overlay-priority'.
91 ;;
92 ;; Commands defined here:
93 ;;
94 ;; `flash-line-highlight', `hl-line-flash',
95 ;; `hl-line-toggle-when-idle', `hl-line-when-idle-interval',
96 ;; `toggle-hl-line-when-idle'.
97 ;;
98 ;; Non-interactive functions defined here:
99 ;;
100 ;; `hl-line-highlight-now', `hl-line-unhighlight-now'.
101 ;;
102 ;; Internal variables defined here:
103 ;;
104 ;; `hl-line-idle-interval', `hl-line-idle-timer',
105 ;; `hl-line-when-idle-p'.
106 ;;
107 ;;
108 ;; ***** NOTE: The following non-interactive functions defined in
109 ;; `hl-line.el' have been ADVISED HERE (to respect option
110 ;; `hl-line-overlay-priority'):
111 ;;
112 ;; `global-hl-line-highlight', `hl-line-highlight'.
113 ;;
114 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
115 ;;
116 ;;; Change Log:
117 ;;
118 ;; 2013/06/08 dadams
119 ;; hl-line-inhibit-highlighting-for-modes: Corrected :type.
120 ;; global-hl-line-highlight defadvice: Respect in hl-line-inhibit-highlighting-for-modes.
121 ;; 2013/01/17 dadams
122 ;; toggle-hl-line-when-idle: Added optional MSGP arg.
123 ;; 2012/05/18 dadams
124 ;; Added: hl-line-overlay-priority, defadvice for (global-)hl-line-highlight.
125 ;; 2011/01/04 dadams
126 ;; Added autoload cookies for defcustom, defface and commands.
127 ;; 2010/10/03 dadams
128 ;; hl-line-flash:
129 ;; Set ARG in interactive spec and use it. Thx to Philip Weaver.
130 ;; 2009/12/18 dadams
131 ;; Added: hl-line-inhibit-highlighting-for-modes.
132 ;; hl-line-highlight-now: Respect hl-line-inhibit-for-modes. Thx to Sylecn.
133 ;; 2009/02/16 dadams
134 ;; Removed spotlight stuff - moved to new library hl-spotlight.el.
135 ;; 2009/02/15 dadams
136 ;; Added: hl-spotlight(-height|-old-state|widen|limits|mode),
137 ;; global-hl-spotlight-mode.
138 ;; 2008/01/28 dadams
139 ;; Fix from Yann Yodique: Moved adding/removing hl-line-unhighlight-now as
140 ;; pre-command-hook from hl-line-toggle-when-idle to hl-line-(un)highlight-now.
141 ;; 2008/01/20 dadams
142 ;; Renamed: line-show-period to hl-line-flash-show-period.
143 ;; 2007/10/11 dadams
144 ;; Commentary typo: toggle-cursor-type-when-idle -> toggle-hl-line-when-idle.
145 ;; 2007/01/10 dadams
146 ;; Update commentary to indicate that the face is now provided by default.
147 ;; 2006/09/08 dadams
148 ;; Added: flash-line-highlight, hl-line-flash.
149 ;; Renamed: hl-line-when-idle(-off) to hl-line-(un)highlight-now.
150 ;; 2006/09/04 dadams
151 ;; Added: hl-line-when-idle-p, hl-line-idle-interval, hl-line-idle-timer,
152 ;; hl-line-toggle-when-idle, hl-line-when-idle-interval,
153 ;; hl-line-when-idle(-off).
154 ;;
155 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
156 ;;
157 ;; This program is free software; you can redistribute it and/or
158 ;; modify it under the terms of the GNU General Public License as
159 ;; published by the Free Software Foundation; either version 3, or
160 ;; (at your option) any later version.
161 ;;
162 ;; This program is distributed in the hope that it will be useful,
163 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
164 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
165 ;; General Public License for more details.
166 ;;
167 ;; You should have received a copy of the GNU General Public License
168 ;; along with this program; see the file COPYING. If not, write to
169 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
170 ;; Floor, Boston, MA 02110-1301, USA.
171 ;;
172 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
173 ;;
174 ;;; Code:
175
176 (require 'hl-line)
177
178 (defvar hl-line-face) ; Quiet the byte-compiler.
179 (defvar global-hl-line-mode) ; Quiet the byte-compiler.
180
181 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
182
183 ;; This will be ignored, since this is now defined by default in Emacs 22.
184 ;; I include it here as a different face definition that you might want to try.
185 ;;;###autoload
186 (defface hl-line '((t (:background "SlateGray3"))) ; Try also (:underline "Yellow")
187 "*Face to use for `hl-line-face'." :group 'hl-line)
188 (setq hl-line-face 'hl-line)
189
190 ;;;###autoload
191 (defcustom hl-line-flash-show-period 1
192 "*Number of seconds for `hl-line-flash' to highlight the line."
193 :type 'integer :group 'cursor :group 'hl-line)
194
195 ;; Possible value: `(Info-mode help-mode view-mode Man-mode)'
196 ;;;###autoload
197 (defcustom hl-line-inhibit-highlighting-for-modes ()
198 "*Modes where highlighting is inhibited for `hl-line-highlight-now'.
199 A list of `major-mode' values (symbols)."
200 :type '(repeat (symbol :tag "Major mode where `hl-line' highlighting is inhibited"))
201 :group 'hl-line)
202
203 ;;;###autoload
204 (defcustom hl-line-overlay-priority 300
205 "*Priority to use for `hl-line-overlay' and `global-hl-line-overlay'.
206 A higher priority can make the hl-line highlighting appear on top of
207 other overlays that might exist."
208 :type '(choice
209 (const :tag "No priority (default priority)" nil)
210 (integer :tag "Priority" 300))
211 :group 'hl-line)
212
213 (defvar hl-line-idle-interval 5
214 "Number of seconds to wait before turning on `global-hl-line-mode'.
215 Do NOT change this yourself to change the wait period; instead, use
216 `\\[hl-line-when-idle-interval]'.")
217
218 (defvar hl-line-idle-timer
219 (progn ; Cancel to prevent duplication.
220 (when (boundp 'hl-line-idle-timer) (cancel-timer hl-line-idle-timer))
221 (run-with-idle-timer hl-line-idle-interval t 'hl-line-highlight-now))
222 "Timer used to turn on `global-hl-line-mode' whenever Emacs is idle.")
223
224 ;; Turn it off, by default. You must use `toggle-hl-line-when-idle' to turn it on.
225 (cancel-timer hl-line-idle-timer)
226
227 (defvar hl-line-when-idle-p nil
228 "Non-nil means to turn on `global-hl-line-mode' whenever Emacs is idle.
229 Do NOT change this yourself; instead, use `\\[toggle-hl-line-when-idle]'.")
230
231 (defadvice hl-line-highlight (after set-priority activate)
232 "Set the overlay priority to `hl-line-overlay-priority'."
233 (overlay-put hl-line-overlay 'priority hl-line-overlay-priority))
234
235 (defadvice global-hl-line-highlight (around set-priority-+respect-mode-inhibit activate)
236 "Set hl-line overlay priority and inhibit for specific modes.
237 Set the overlay to `hl-line-overlay-priority'.
238 Respect option `hl-line-inhibit-highlighting-for-modes'."
239 (unless (member major-mode hl-line-inhibit-highlighting-for-modes)
240 ad-do-it
241 (overlay-put global-hl-line-overlay 'priority hl-line-overlay-priority)))
242
243 ;;;###autoload
244 (defalias 'toggle-hl-line-when-idle 'hl-line-toggle-when-idle)
245 ;;;###autoload
246 (defun hl-line-toggle-when-idle (&optional arg msgp)
247 "Turn on or off using `global-hl-line-mode' when Emacs is idle.
248 When on, use `global-hl-line-mode' whenever Emacs is idle.
249 With prefix argument, turn on if ARG > 0; else turn off.
250
251 In Lisp code, non-nil optional second arg MSGP means display a message
252 showing the new value."
253 (interactive "P\np")
254 (setq hl-line-when-idle-p
255 (if arg (> (prefix-numeric-value arg) 0) (not hl-line-when-idle-p)))
256 (cond (hl-line-when-idle-p
257 (timer-activate-when-idle hl-line-idle-timer)
258 (when msgp (message "Turned ON using `global-hl-line-mode' when Emacs is idle.")))
259 (t
260 (cancel-timer hl-line-idle-timer)
261 (when msgp (message "Turned OFF using `global-hl-line-mode' when Emacs is idle.")))))
262
263 ;;;###autoload
264 (defun hl-line-when-idle-interval (secs)
265 "Set wait until using `global-hl-line-mode' when Emacs is idle.
266 Whenever Emacs is idle for this many seconds, `global-hl-line-mode'
267 will be turned on.
268
269 To turn on or off using `global-hl-line-mode' when idle,
270 use `\\[toggle-hl-line-when-idle]."
271 (interactive "nSeconds to idle, before using `global-hl-line-mode': ")
272 (timer-set-idle-time hl-line-idle-timer (setq hl-line-idle-interval secs) t))
273
274 (defun hl-line-highlight-now ()
275 "Turn on `global-hl-line-mode' and highlight current line now."
276 (unless (or global-hl-line-mode
277 (member major-mode hl-line-inhibit-highlighting-for-modes))
278 (global-hl-line-mode 1)
279 (global-hl-line-highlight)
280 (add-hook 'pre-command-hook 'hl-line-unhighlight-now)))
281
282 (defun hl-line-unhighlight-now ()
283 "Turn off `global-hl-line-mode' and unhighlight current line now."
284 (global-hl-line-mode -1)
285 (global-hl-line-unhighlight)
286 (remove-hook 'pre-command-hook 'hl-line-unhighlight-now))
287
288 ;;;###autoload
289 (defalias 'flash-line-highlight 'hl-line-flash)
290 ;;;###autoload
291 (defun hl-line-flash (&optional arg)
292 "Highlight the current line for `hl-line-flash-show-period' seconds.
293 With a prefix argument, highlight for that many seconds."
294 (interactive "P")
295 (hl-line-highlight-now)
296 (let ((line-period hl-line-flash-show-period))
297 (when arg (setq line-period (prefix-numeric-value arg)))
298 (run-at-time line-period nil #'hl-line-unhighlight-now)))
299
300 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
301
302 (provide 'hl-line+)
303
304 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
305 ;;; hl-line+.el ends here