; Auto-commit of ChangeLog files.
[emacs.git] / lisp / help-at-pt.el
blob82ca09daa079fdbe07c52b7bc4a8df4b2b793f55
1 ;;; help-at-pt.el --- local help through the keyboard
3 ;; Copyright (C) 2003-2015 Free Software Foundation, Inc.
5 ;; Author: Luc Teirlinck <teirllm@auburn.edu>
6 ;; Keywords: help
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This file contains functionality to make the help provided by the
26 ;; help-echo text or overlay property available to the keyboard user.
27 ;; It also supports a more keyboard oriented alternative to
28 ;; `help-echo', namely a new text or overlay property `kbd-help'.
30 ;; It provides facilities to access the local help available at point
31 ;; either on demand, using the command `display-local-help', or
32 ;; automatically after a suitable idle time, through the customizable
33 ;; variable `help-at-pt-display-when-idle'.
35 ;; You can get a more global overview of the local help available in
36 ;; the buffer, using the commands `scan-buf-next-region' and
37 ;; `scan-buf-previous-region', which move to the start of the next or
38 ;; previous region with available local help and print the help found
39 ;; there.
41 ;; Suggested key bindings:
43 ;; (global-set-key [C-tab] 'scan-buf-next-region)
44 ;; (global-set-key [C-M-tab] 'scan-buf-previous-region)
46 ;; You do not have to do anything special to use the functionality
47 ;; provided by this file, because all important functions autoload.
49 ;;; Code:
51 (defgroup help-at-pt nil
52 "Features for displaying local help."
53 :group 'help
54 :version "22.1")
56 ;;;###autoload
57 (defun help-at-pt-string (&optional kbd)
58 "Return the help-echo string at point.
59 Normally, the string produced by the `help-echo' text or overlay
60 property, or nil, is returned.
61 If KBD is non-nil, `kbd-help' is used instead, and any
62 `help-echo' property is ignored. In this case, the return value
63 can also be t, if that is the value of the `kbd-help' property."
64 (save-excursion
65 (let* ((prop (if kbd 'kbd-help 'help-echo))
66 (pair (get-char-property-and-overlay (point) prop))
67 (pair (if (car pair) pair
68 (unless (bobp)
69 (backward-char)
70 (get-char-property-and-overlay (point) prop))))
71 (val (car pair))
72 (ov (cdr pair)))
73 (if (functionp val)
74 (funcall val (selected-window) (if ov ov (current-buffer)) (point))
75 (eval val)))))
77 ;;;###autoload
78 (defun help-at-pt-kbd-string ()
79 "Return the keyboard help string at point.
80 If the `kbd-help' text or overlay property at point produces a
81 string, return it. Otherwise, use the `help-echo' property.
82 If this produces no string either, return nil."
83 (let ((kbd (help-at-pt-string t))
84 (echo (help-at-pt-string)))
85 (if (and kbd (not (eq kbd t))) kbd echo)))
87 ;;;###autoload
88 (defun display-local-help (&optional arg)
89 "Display local help in the echo area.
90 This displays a short help message, namely the string produced by
91 the `kbd-help' property at point. If `kbd-help' does not produce
92 a string, but the `help-echo' property does, then that string is
93 printed instead.
95 A numeric argument ARG prevents display of a message in case
96 there is no help. While ARG can be used interactively, it is
97 mainly meant for use from Lisp."
98 (interactive "P")
99 (let ((help (help-at-pt-kbd-string)))
100 (if help
101 (message "%s" help)
102 (if (not arg) (message "No local help at point")))))
104 (defvar help-at-pt-timer nil
105 "Non-nil means that a timer is set that checks for local help.
106 If non-nil, this is the value returned by the call of
107 `run-with-idle-timer' that set that timer. This variable is used
108 internally to enable `help-at-pt-display-when-idle'. Do not set it
109 yourself.")
111 (defcustom help-at-pt-timer-delay 1
112 "Delay before displaying local help.
113 This is used if `help-at-pt-display-when-idle' is enabled.
114 The value may be an integer or floating point number.
116 If a timer is already active, there are two ways to make the new
117 value take effect immediately. After setting the value, you can
118 first call `help-at-pt-cancel-timer' and then set a new timer
119 with `help-at-pt-set-timer'. Alternatively, you can set this
120 variable through Custom. This will not set a timer if none is
121 active, but if one is already active, Custom will make it use the
122 new value."
123 :group 'help-at-pt
124 :type 'number
125 :initialize 'custom-initialize-default
126 :set (lambda (variable value)
127 (set-default variable value)
128 (and (boundp 'help-at-pt-timer)
129 help-at-pt-timer
130 (timer-set-idle-time help-at-pt-timer value t))))
132 ;;;###autoload
133 (defun help-at-pt-cancel-timer ()
134 "Cancel any timer set by `help-at-pt-set-timer'.
135 This disables `help-at-pt-display-when-idle'."
136 (interactive)
137 (let ((inhibit-quit t))
138 (when help-at-pt-timer
139 (cancel-timer help-at-pt-timer)
140 (setq help-at-pt-timer nil))))
142 ;;;###autoload
143 (defun help-at-pt-set-timer ()
144 "Enable `help-at-pt-display-when-idle'.
145 This is done by setting a timer, if none is currently active."
146 (interactive)
147 (unless help-at-pt-timer
148 (setq help-at-pt-timer
149 (run-with-idle-timer
150 help-at-pt-timer-delay t #'help-at-pt-maybe-display))))
152 ;;;###autoload
153 (defcustom help-at-pt-display-when-idle 'never
154 "Automatically show local help on point-over.
155 If the value is t, the string obtained from any `kbd-help' or
156 `help-echo' property at point is automatically printed in the
157 echo area, if nothing else is already displayed there, or after a
158 quit. If both `kbd-help' and `help-echo' produce help strings,
159 `kbd-help' is used. If the value is a list, the help only gets
160 printed if there is a text or overlay property at point that is
161 included in this list. Suggested properties are `keymap',
162 `local-map', `button' and `kbd-help'. Any value other than t or
163 a non-empty list disables the feature.
165 This variable only takes effect after a call to
166 `help-at-pt-set-timer'. The help gets printed after Emacs has
167 been idle for `help-at-pt-timer-delay' seconds. You can call
168 `help-at-pt-cancel-timer' to cancel the timer set by, and the
169 effect of, `help-at-pt-set-timer'.
171 When this variable is set through Custom, `help-at-pt-set-timer'
172 is called automatically, unless the value is `never', in which
173 case `help-at-pt-cancel-timer' is called. Specifying an empty
174 list of properties through Custom will set the timer, thus
175 enabling buffer local values. It sets the actual value to nil.
176 Thus, Custom distinguishes between a nil value and other values
177 that disable the feature, which Custom identifies with `never'.
178 The default is `never'."
179 :group 'help-at-pt
180 :type '(choice (const :tag "Always"
181 :format "%t\n%h"
182 :doc
183 "This choice can get noisy.
184 The text printed from the `help-echo' property is often only
185 relevant when using the mouse. If you mind about too many
186 messages getting printed in the echo area, use \"In certain
187 situations\". See the documentation there for more information."
189 (repeat :tag "In certain situations"
190 ;; unless we specify 0 offset the doc string
191 ;; for this choice gets indented very
192 ;; differently than for the other two
193 ;; choices, when "More" is selected.
194 :offset 0
195 :format "%{%t%}:\n%v%i\n%h"
196 :doc
197 "This choice lets you specify a list of \
198 text properties.
199 Presence of any of these properties will trigger display of
200 available local help on point-over.
201 If you use this alternative through Custom without listing any
202 properties, a timer will be set anyway. This will enable buffer
203 local values. Use \"Never\" if you do not want a timer to be set.
205 Suggested properties:
206 The `keymap' and `local-map' properties change keybindings in
207 parts of the buffer. Some of these keymaps are mode independent
208 and are not mentioned in the mode documentation. Hence, the help
209 text is likely to be useful.
210 Specifying `button' is relevant in Custom and similar buffers.
211 In these buffers, most, but not all, of the text shown this way is
212 available by default when using tab, but not on regular point-over.
213 The presence of a `kbd-help' property guarantees that non mouse
214 specific help is available."
215 :value (keymap local-map button kbd-help)
216 symbol)
217 (other :tag "Never"
218 :format "%t\n%h"
219 :doc
220 "This choice normally disables buffer local values.
221 If you choose this value through Custom and a timer checking for
222 local help is currently active, it will be canceled. No new
223 timer will be set. Call `help-at-pt-set-timer' after choosing
224 this option, or use \"In certain situations\" and specify no text
225 properties, to enable buffer local values."
226 never))
227 :initialize 'custom-initialize-default
228 :set #'(lambda (variable value)
229 (set-default variable value)
230 (if (eq value 'never)
231 (help-at-pt-cancel-timer)
232 (help-at-pt-set-timer)))
233 :set-after '(help-at-pt-timer-delay)
234 :require 'help-at-pt)
236 ;; Function for use in `help-at-pt-set-timer'.
237 (defun help-at-pt-maybe-display ()
238 (and (or (eq help-at-pt-display-when-idle t)
239 (and (consp help-at-pt-display-when-idle)
240 (catch 'found
241 (dolist (prop help-at-pt-display-when-idle)
242 (if (get-char-property (point) prop)
243 (throw 'found t)))
244 (unless (bobp)
245 (save-excursion
246 (backward-char)
247 (dolist (prop help-at-pt-display-when-idle)
248 (if (get-char-property (point) prop)
249 (throw 'found t))))))))
250 (or (not (current-message))
251 (string= (current-message) "Quit"))
252 (display-local-help t)))
254 ;;;###autoload
255 (defun scan-buf-move-to-region (prop &optional arg hook)
256 "Go to the start of the next region with non-nil PROP property.
257 Then run HOOK, which should be a quoted symbol that is a normal
258 hook variable, or an expression evaluating to such a symbol.
259 Adjacent areas with different non-nil PROP properties are
260 considered different regions.
262 With numeric argument ARG, move to the start of the ARGth next
263 such region, then run HOOK. If ARG is negative, move backward.
264 If point is already in a region, then that region does not count
265 toward ARG. If ARG is 0 and point is inside a region, move to
266 the start of that region. If ARG is 0 and point is not in a
267 region, print a message to that effect, but do not move point and
268 do not run HOOK. If there are not enough regions to move over,
269 an error results and the number of available regions is mentioned
270 in the error message. Point is not moved and HOOK is not run."
271 (cond ((> arg 0)
272 (if (= (point) (point-max))
273 (error "No further `%s' regions" prop))
274 (let ((pos (point)))
275 (dotimes (x arg)
276 (setq pos (next-single-char-property-change pos prop))
277 (unless (get-char-property pos prop)
278 (setq pos (next-single-char-property-change pos prop))
279 (unless (get-char-property pos prop)
280 (cond ((= x 0)
281 (error "No further `%s' regions" prop))
282 ((= x 1)
283 (error "There is only one further `%s' region" prop))
285 (error
286 "There are only %d further `%s' regions"
287 x prop))))))
288 (goto-char pos)
289 (run-hooks hook)))
290 ((= arg 0)
291 (let ((val (get-char-property (point) prop)))
292 (cond ((not val)
293 (message "Point is not in a `%s' region" prop))
294 ((eq val (get-char-property (1- (point)) prop))
295 (goto-char
296 (previous-single-char-property-change (point) prop))
297 (run-hooks hook))
298 (t (run-hooks hook)))))
299 ((< arg 0)
300 (let ((pos (point)) (val (get-char-property (point) prop)))
301 (and val
302 (eq val (get-char-property (1- pos) prop))
303 (setq pos
304 (previous-single-char-property-change pos prop)))
305 (if (= pos (point-min))
306 (error "No prior `%s' regions" prop))
307 (dotimes (x (- arg))
308 (setq pos (previous-single-char-property-change pos prop))
309 (unless (get-char-property pos prop)
310 (setq pos (previous-single-char-property-change pos prop))
311 (unless (get-char-property pos prop)
312 (cond ((= x 0)
313 (error "No prior `%s' regions" prop))
314 ((= x 1)
315 (error "There is only one prior `%s' region" prop))
317 (error "There are only %d prior `%s' regions"
318 x prop))))))
319 (goto-char pos)
320 (run-hooks hook)))))
322 ;; To be moved to a different file and replaced by a defcustom in a
323 ;; future version.
324 (defvar scan-buf-move-hook '(display-local-help)
325 "Normal hook run by `scan-buf-next-region'.
326 Also used by `scan-buf-previous-region'. The hook is run after
327 positioning point.")
329 ;;;###autoload
330 (defun scan-buf-next-region (&optional arg)
331 "Go to the start of the next region with non-nil help-echo.
332 Print the help found there using `display-local-help'. Adjacent
333 areas with different non-nil help-echo properties are considered
334 different regions.
336 With numeric argument ARG, move to the start of the ARGth next
337 help-echo region. If ARG is negative, move backward. If point
338 is already in a help-echo region, then that region does not count
339 toward ARG. If ARG is 0 and point is inside a help-echo region,
340 move to the start of that region. If ARG is 0 and point is not
341 in such a region, just print a message to that effect. If there
342 are not enough regions to move over, an error results and the
343 number of available regions is mentioned in the error message.
345 A potentially confusing subtlety is that point can be in a
346 help-echo region without any local help being available. This is
347 because `help-echo' can be a function evaluating to nil. This
348 rarely happens in practice."
349 (interactive "p")
350 (scan-buf-move-to-region 'help-echo arg 'scan-buf-move-hook))
352 ;;;###autoload
353 (defun scan-buf-previous-region (&optional arg)
354 "Go to the start of the previous region with non-nil help-echo.
355 Print the help found there using `display-local-help'. Adjacent
356 areas with different non-nil help-echo properties are considered
357 different regions. With numeric argument ARG, behaves like
358 `scan-buf-next-region' with argument -ARG."
359 (interactive "p")
360 (scan-buf-move-to-region 'help-echo (- arg) 'scan-buf-move-hook))
362 (provide 'help-at-pt)
364 ;;; help-at-pt.el ends here