Mercurial > emacs
annotate lisp/help-at-pt.el @ 104232:23230e6cbc19
*** empty log message ***
author | Dmitry Dzhus <dima@sphinx.net.ru> |
---|---|
date | Tue, 11 Aug 2009 10:48:56 +0000 |
parents | 9446d1875bbd |
children | 1d1d5d9bd884 |
rev | line source |
---|---|
53203 | 1 ;;; help-at-pt.el --- local help through the keyboard |
2 | |
100908 | 3 ;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
53203 | 4 |
5 ;; Author: Luc Teirlinck <teirllm@auburn.edu> | |
6 ;; Keywords: help | |
7 | |
8 ;; This file is part of GNU Emacs. | |
9 | |
94678
ee5932bf781d
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
93975
diff
changeset
|
10 ;; GNU Emacs is free software: you can redistribute it and/or modify |
53203 | 11 ;; it under the terms of the GNU General Public License as published by |
94678
ee5932bf781d
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
93975
diff
changeset
|
12 ;; the Free Software Foundation, either version 3 of the License, or |
ee5932bf781d
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
93975
diff
changeset
|
13 ;; (at your option) any later version. |
53203 | 14 |
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. | |
19 | |
20 ;; You should have received a copy of the GNU General Public License | |
94678
ee5932bf781d
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
93975
diff
changeset
|
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
53203 | 22 |
23 ;;; Commentary: | |
24 | |
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'. | |
29 ;; | |
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'. | |
34 ;; | |
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. | |
40 ;; | |
54524
d3e10b0b1a2e
Move suggestions for key bindings to Commentary.
Juri Linkov <juri@jurta.org>
parents:
54283
diff
changeset
|
41 ;; Suggested key bindings: |
d3e10b0b1a2e
Move suggestions for key bindings to Commentary.
Juri Linkov <juri@jurta.org>
parents:
54283
diff
changeset
|
42 ;; |
d3e10b0b1a2e
Move suggestions for key bindings to Commentary.
Juri Linkov <juri@jurta.org>
parents:
54283
diff
changeset
|
43 ;; (global-set-key [C-tab] 'scan-buf-next-region) |
d3e10b0b1a2e
Move suggestions for key bindings to Commentary.
Juri Linkov <juri@jurta.org>
parents:
54283
diff
changeset
|
44 ;; (global-set-key [C-M-tab] 'scan-buf-previous-region) |
d3e10b0b1a2e
Move suggestions for key bindings to Commentary.
Juri Linkov <juri@jurta.org>
parents:
54283
diff
changeset
|
45 ;; |
53203 | 46 ;; You do not have to do anything special to use the functionality |
47 ;; provided by this file, because all important functions autoload. | |
48 | |
49 ;;; Code: | |
50 | |
51 (defgroup help-at-pt nil | |
52 "Features for displaying local help." | |
53 :group 'help | |
59996
aac0a33f5772
Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents:
59727
diff
changeset
|
54 :version "22.1") |
53203 | 55 |
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 (let* ((prop (if kbd 'kbd-help 'help-echo)) | |
65 (pair (get-char-property-and-overlay (point) prop)) | |
66 (val (car pair)) | |
67 (ov (cdr pair))) | |
68 (if (functionp val) | |
69 (funcall val (selected-window) (if ov ov (current-buffer)) (point)) | |
70 (eval val)))) | |
71 | |
72 ;;;###autoload | |
73 (defun help-at-pt-kbd-string () | |
74 "Return the keyboard help string at point. | |
75 If the `kbd-help' text or overlay property at point produces a | |
102972
9446d1875bbd
* help-at-pt.el (help-at-pt-kbd-string): Reflow docstring.
Juanma Barranquero <lekktu@gmail.com>
parents:
100908
diff
changeset
|
76 string, return it. Otherwise, use the `help-echo' property. |
9446d1875bbd
* help-at-pt.el (help-at-pt-kbd-string): Reflow docstring.
Juanma Barranquero <lekktu@gmail.com>
parents:
100908
diff
changeset
|
77 If this produces no string either, return nil." |
53203 | 78 (let ((kbd (help-at-pt-string t)) |
79 (echo (help-at-pt-string))) | |
80 (if (and kbd (not (eq kbd t))) kbd echo))) | |
81 | |
82 ;;;###autoload | |
83 (defun display-local-help (&optional arg) | |
84 "Display local help in the echo area. | |
85 This displays a short help message, namely the string produced by | |
86 the `kbd-help' property at point. If `kbd-help' does not produce | |
87 a string, but the `help-echo' property does, then that string is | |
88 printed instead. | |
89 | |
90 A numeric argument ARG prevents display of a message in case | |
91 there is no help. While ARG can be used interactively, it is | |
92 mainly meant for use from Lisp." | |
93 (interactive "P") | |
94 (let ((help (help-at-pt-kbd-string))) | |
95 (if help | |
96 (message "%s" help) | |
97 (if (not arg) (message "No local help at point"))))) | |
98 | |
57798
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
99 (defvar help-at-pt-timer nil |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
100 "Non-nil means that a timer is set that checks for local help. |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
101 If non-nil, this is the value returned by the call of |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
102 `run-with-idle-timer' that set that timer. This variable is used |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
103 internally to enable `help-at-pt-display-when-idle'. Do not set it |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
104 yourself.") |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
105 |
53203 | 106 (defcustom help-at-pt-timer-delay 1 |
100171 | 107 "Delay before displaying local help. |
53203 | 108 This is used if `help-at-pt-display-when-idle' is enabled. |
109 The value may be an integer or floating point number. | |
110 | |
111 If a timer is already active, there are two ways to make the new | |
112 value take effect immediately. After setting the value, you can | |
113 first call `help-at-pt-cancel-timer' and then set a new timer | |
54283
d0c3cadb7e21
(help-at-pt-timer-delay): Minor doc fix (remove stray space).
Luc Teirlinck <teirllm@auburn.edu>
parents:
53208
diff
changeset
|
114 with `help-at-pt-set-timer'. Alternatively, you can set this |
53203 | 115 variable through Custom. This will not set a timer if none is |
116 active, but if one is already active, Custom will make it use the | |
117 new value." | |
118 :group 'help-at-pt | |
119 :type 'number | |
57798
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
120 :initialize 'custom-initialize-default |
53203 | 121 :set (lambda (variable value) |
122 (set-default variable value) | |
57798
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
123 (and (boundp 'help-at-pt-timer) |
bb24af8f5452
(help-at-pt-timer): Move defvar up to avoid compiler warning.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57542
diff
changeset
|
124 help-at-pt-timer |
57802
edb9ccd02dbf
(help-at-pt-timer-delay, help-at-pt-display-when-idle): Remove
Luc Teirlinck <teirllm@auburn.edu>
parents:
57798
diff
changeset
|
125 (timer-set-idle-time help-at-pt-timer value t)))) |
53203 | 126 |
127 ;;;###autoload | |
128 (defun help-at-pt-cancel-timer () | |
129 "Cancel any timer set by `help-at-pt-set-timer'. | |
130 This disables `help-at-pt-display-when-idle'." | |
131 (interactive) | |
132 (let ((inhibit-quit t)) | |
133 (when help-at-pt-timer | |
134 (cancel-timer help-at-pt-timer) | |
135 (setq help-at-pt-timer nil)))) | |
136 | |
137 ;;;###autoload | |
138 (defun help-at-pt-set-timer () | |
139 "Enable `help-at-pt-display-when-idle'. | |
140 This is done by setting a timer, if none is currently active." | |
141 (interactive) | |
142 (unless help-at-pt-timer | |
143 (setq help-at-pt-timer | |
144 (run-with-idle-timer | |
145 help-at-pt-timer-delay t #'help-at-pt-maybe-display)))) | |
146 | |
59727
86b02098f260
(help-at-pt-display-when-idle): Add autoload cookie.
Luc Teirlinck <teirllm@auburn.edu>
parents:
57802
diff
changeset
|
147 ;;;###autoload |
53203 | 148 (defcustom help-at-pt-display-when-idle 'never |
100171 | 149 "Automatically show local help on point-over. |
53203 | 150 If the value is t, the string obtained from any `kbd-help' or |
151 `help-echo' property at point is automatically printed in the | |
152 echo area, if nothing else is already displayed there, or after a | |
153 quit. If both `kbd-help' and `help-echo' produce help strings, | |
154 `kbd-help' is used. If the value is a list, the help only gets | |
155 printed if there is a text or overlay property at point that is | |
156 included in this list. Suggested properties are `keymap', | |
157 `local-map', `button' and `kbd-help'. Any value other than t or | |
158 a non-empty list disables the feature. | |
159 | |
160 This variable only takes effect after a call to | |
161 `help-at-pt-set-timer'. The help gets printed after Emacs has | |
162 been idle for `help-at-pt-timer-delay' seconds. You can call | |
163 `help-at-pt-cancel-timer' to cancel the timer set by, and the | |
164 effect of, `help-at-pt-set-timer'. | |
165 | |
166 When this variable is set through Custom, `help-at-pt-set-timer' | |
167 is called automatically, unless the value is `never', in which | |
168 case `help-at-pt-cancel-timer' is called. Specifying an empty | |
169 list of properties through Custom will set the timer, thus | |
170 enabling buffer local values. It sets the actual value to nil. | |
171 Thus, Custom distinguishes between a nil value and other values | |
172 that disable the feature, which Custom identifies with `never'. | |
173 The default is `never'." | |
174 :group 'help-at-pt | |
175 :type '(choice (const :tag "Always" | |
176 :format "%t\n%h" | |
177 :doc | |
178 "This choice can get noisy. | |
179 The text printed from the `help-echo' property is often only | |
180 relevant when using the mouse. If you mind about too many | |
181 messages getting printed in the echo area, use \"In certain | |
182 situations\". See the documentation there for more information." | |
183 t) | |
184 (repeat :tag "In certain situations" | |
185 ;; unless we specify 0 offset the doc string | |
186 ;; for this choice gets indented very | |
187 ;; differently than for the other two | |
188 ;; choices, when "More" is selected. | |
189 :offset 0 | |
190 :format "%{%t%}:\n%v%i\n%h" | |
191 :doc | |
192 "This choice lets you specify a list of \ | |
193 text properties. | |
194 Presence of any of these properties will trigger display of | |
195 available local help on point-over. | |
196 If you use this alternative through Custom without listing any | |
197 properties, a timer will be set anyway. This will enable buffer | |
198 local values. Use \"Never\" if you do not want a timer to be set. | |
199 | |
200 Suggested properties: | |
201 The `keymap' and `local-map' properties change keybindings in | |
202 parts of the buffer. Some of these keymaps are mode independent | |
203 and are not mentioned in the mode documentation. Hence, the help | |
204 text is likely to be useful. | |
205 Specifying `button' is relevant in Custom and similar buffers. | |
206 In these buffers, most, but not all, of the text shown this way is | |
207 available by default when using tab, but not on regular point-over. | |
208 The presence of a `kbd-help' property guarantees that non mouse | |
209 specific help is available." | |
210 :value (keymap local-map button kbd-help) | |
211 symbol) | |
212 (other :tag "Never" | |
213 :format "%t\n%h" | |
214 :doc | |
215 "This choice normally disables buffer local values. | |
216 If you choose this value through Custom and a timer checking for | |
217 local help is currently active, it will be canceled. No new | |
218 timer will be set. Call `help-at-pt-set-timer' after choosing | |
219 this option, or use \"In certain situations\" and specify no text | |
220 properties, to enable buffer local values." | |
221 never)) | |
222 :initialize 'custom-initialize-default | |
223 :set #'(lambda (variable value) | |
224 (set-default variable value) | |
225 (if (eq value 'never) | |
226 (help-at-pt-cancel-timer) | |
227 (help-at-pt-set-timer))) | |
228 :set-after '(help-at-pt-timer-delay) | |
57802
edb9ccd02dbf
(help-at-pt-timer-delay, help-at-pt-display-when-idle): Remove
Luc Teirlinck <teirllm@auburn.edu>
parents:
57798
diff
changeset
|
229 :require 'help-at-pt) |
53203 | 230 |
231 ;; Function for use in `help-at-pt-set-timer'. | |
232 (defun help-at-pt-maybe-display () | |
233 (and (or (eq help-at-pt-display-when-idle t) | |
234 (and (consp help-at-pt-display-when-idle) | |
235 (catch 'found | |
236 (dolist (prop help-at-pt-display-when-idle) | |
237 (if (get-char-property (point) prop) | |
238 (throw 'found t)))))) | |
239 (or (not (current-message)) | |
240 (string= (current-message) "Quit")) | |
241 (display-local-help t))) | |
242 | |
243 ;;;###autoload | |
244 (defun scan-buf-move-to-region (prop &optional arg hook) | |
245 "Go to the start of the next region with non-nil PROP property. | |
246 Then run HOOK, which should be a quoted symbol that is a normal | |
73330
400487787181
* dnd.el (dnd-handle-one-url): Fix typo in doc-string.
Jan Djärv <jan.h.d@swipnet.se>
parents:
68651
diff
changeset
|
247 hook variable, or an expression evaluating to such a symbol. |
53203 | 248 Adjacent areas with different non-nil PROP properties are |
249 considered different regions. | |
250 | |
251 With numeric argument ARG, move to the start of the ARGth next | |
252 such region, then run HOOK. If ARG is negative, move backward. | |
253 If point is already in a region, then that region does not count | |
254 toward ARG. If ARG is 0 and point is inside a region, move to | |
255 the start of that region. If ARG is 0 and point is not in a | |
256 region, print a message to that effect, but do not move point and | |
257 do not run HOOK. If there are not enough regions to move over, | |
258 an error results and the number of available regions is mentioned | |
259 in the error message. Point is not moved and HOOK is not run." | |
260 (cond ((> arg 0) | |
261 (if (= (point) (point-max)) | |
262 (error "No further `%s' regions" prop)) | |
263 (let ((pos (point))) | |
264 (dotimes (x arg) | |
265 (setq pos (next-single-char-property-change pos prop)) | |
266 (unless (get-char-property pos prop) | |
267 (setq pos (next-single-char-property-change pos prop)) | |
268 (unless (get-char-property pos prop) | |
269 (cond ((= x 0) | |
270 (error "No further `%s' regions" prop)) | |
271 ((= x 1) | |
272 (error "There is only one further `%s' region" prop)) | |
273 (t | |
274 (error | |
275 "There are only %d further `%s' regions" | |
276 x prop)))))) | |
277 (goto-char pos) | |
278 (run-hooks hook))) | |
279 ((= arg 0) | |
280 (let ((val (get-char-property (point) prop))) | |
281 (cond ((not val) | |
282 (message "Point is not in a `%s' region" prop)) | |
283 ((eq val (get-char-property (1- (point)) prop)) | |
284 (goto-char | |
285 (previous-single-char-property-change (point) prop)) | |
286 (run-hooks hook)) | |
287 (t (run-hooks hook))))) | |
288 ((< arg 0) | |
289 (let ((pos (point)) (val (get-char-property (point) prop))) | |
290 (and val | |
291 (eq val (get-char-property (1- pos) prop)) | |
292 (setq pos | |
293 (previous-single-char-property-change pos prop))) | |
294 (if (= pos (point-min)) | |
295 (error "No prior `%s' regions" prop)) | |
296 (dotimes (x (- arg)) | |
297 (setq pos (previous-single-char-property-change pos prop)) | |
298 (unless (get-char-property pos prop) | |
299 (setq pos (previous-single-char-property-change pos prop)) | |
300 (unless (get-char-property pos prop) | |
301 (cond ((= x 0) | |
302 (error "No prior `%s' regions" prop)) | |
303 ((= x 1) | |
304 (error "There is only one prior `%s' region" prop)) | |
305 (t | |
306 (error "There are only %d prior `%s' regions" | |
307 x prop)))))) | |
308 (goto-char pos) | |
309 (run-hooks hook))))) | |
310 | |
311 ;; To be moved to a different file and replaced by a defcustom in a | |
312 ;; future version. | |
313 (defvar scan-buf-move-hook '(display-local-help) | |
314 "Normal hook run by `scan-buf-next-region'. | |
315 Also used by `scan-buf-previous-region'. The hook is run after | |
316 positioning point.") | |
317 | |
318 ;;;###autoload | |
319 (defun scan-buf-next-region (&optional arg) | |
320 "Go to the start of the next region with non-nil help-echo. | |
321 Print the help found there using `display-local-help'. Adjacent | |
322 areas with different non-nil help-echo properties are considered | |
323 different regions. | |
324 | |
325 With numeric argument ARG, move to the start of the ARGth next | |
326 help-echo region. If ARG is negative, move backward. If point | |
327 is already in a help-echo region, then that region does not count | |
328 toward ARG. If ARG is 0 and point is inside a help-echo region, | |
329 move to the start of that region. If ARG is 0 and point is not | |
330 in such a region, just print a message to that effect. If there | |
331 are not enough regions to move over, an error results and the | |
332 number of available regions is mentioned in the error message. | |
333 | |
334 A potentially confusing subtlety is that point can be in a | |
335 help-echo region without any local help being available. This is | |
336 because `help-echo' can be a function evaluating to nil. This | |
337 rarely happens in practice." | |
338 (interactive "p") | |
339 (scan-buf-move-to-region 'help-echo arg 'scan-buf-move-hook)) | |
340 | |
341 ;;;###autoload | |
342 (defun scan-buf-previous-region (&optional arg) | |
343 "Go to the start of the previous region with non-nil help-echo. | |
344 Print the help found there using `display-local-help'. Adjacent | |
345 areas with different non-nil help-echo properties are considered | |
346 different regions. With numeric argument ARG, behaves like | |
102972
9446d1875bbd
* help-at-pt.el (help-at-pt-kbd-string): Reflow docstring.
Juanma Barranquero <lekktu@gmail.com>
parents:
100908
diff
changeset
|
347 `scan-buf-next-region' with argument -ARG." |
53203 | 348 (interactive "p") |
349 (scan-buf-move-to-region 'help-echo (- arg) 'scan-buf-move-hook)) | |
350 | |
351 (provide 'help-at-pt) | |
352 | |
93975
1e3a407766b9
Fix up comment convention on the arch-tag lines.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
87649
diff
changeset
|
353 ;; arch-tag: d0b8b86d-d23f-45d0-a82d-208d6205a583 |
53203 | 354 ;;; help-at-pt.el ends here |