|
0
|
1 ;;; Balloon help for XEmacs (requires 19.12 or later)
|
|
22
|
2 ;;; Copyright (C) 1995, 1997 Kyle E. Jones
|
|
0
|
3 ;;;
|
|
|
4 ;;; This program is free software; you can redistribute it and/or modify
|
|
|
5 ;;; it under the terms of the GNU General Public License as published by
|
|
|
6 ;;; the Free Software Foundation; either version 1, or (at your option)
|
|
|
7 ;;; any later version.
|
|
|
8 ;;;
|
|
|
9 ;;; This program is distributed in the hope that it will be useful,
|
|
|
10 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
11 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
12 ;;; GNU General Public License for more details.
|
|
|
13 ;;;
|
|
|
14 ;;; A copy of the GNU General Public License can be obtained from this
|
|
|
15 ;;; program's author (send electronic mail to kyle@uunet.uu.net) or from
|
|
|
16 ;;; the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
|
|
|
17 ;;; 02139, USA.
|
|
|
18 ;;;
|
|
|
19 ;;; Send bug reports to kyle@wonderworks.com
|
|
|
20
|
|
|
21 ;; Balloon help pops up a small frame to display help text
|
|
|
22 ;; relating to objects that the mouse cursor passes over.
|
|
|
23 ;;
|
|
|
24 ;; Installation:
|
|
|
25 ;;
|
|
|
26 ;; Byte-compile the file balloon-help.el (with M-x byte-compile-file)
|
|
|
27 ;; and put the .elc file in a directory in your load-path. Add the
|
|
|
28 ;; following line to your .emacs:
|
|
|
29 ;;
|
|
|
30 ;; (require 'balloon-help)
|
|
|
31 ;;
|
|
|
32 ;; For 19.12 users:
|
|
|
33 ;; If you are using fvwm, [tv]twm or ol[v]wm, you can also add
|
|
|
34 ;; the following lines to various configuration file to use
|
|
|
35 ;; minimal decorations on the balloon help frames.
|
|
|
36 ;;
|
|
|
37 ;; In .emacs:
|
|
|
38 ;; (setq balloon-help-frame-name "balloon-help")
|
|
|
39 ;;
|
|
|
40 ;; For ol[v]wm use this in .Xdefaults:
|
|
|
41 ;; olvwm.NoDecor: balloon-help
|
|
|
42 ;; or
|
|
|
43 ;; olwm.MinimalDecor: balloon-help
|
|
|
44 ;;
|
|
|
45 ;; For fvvm use this in your .fvwmrc:
|
|
|
46 ;; NoTitle balloon-help
|
|
|
47 ;; or
|
|
|
48 ;; Style "balloon-help" NoTitle, NoHandles, BorderWidth 0
|
|
|
49 ;;
|
|
|
50 ;; For twm use this in your .twmrc:
|
|
|
51 ;; NoTitle { "balloon-help" }
|
|
|
52 ;;
|
|
|
53 ;; Under 19.13 and later versions the balloon-help frame uses a
|
|
|
54 ;; transient window that is not normally decorated by window
|
|
|
55 ;; managers. So the window manager directives should not be
|
|
|
56 ;; needed for XEmacs 19.13 and beyond.
|
|
|
57
|
|
|
58 (provide 'balloon-help)
|
|
|
59
|
|
26
|
60 (defvar balloon-help-version "1.04"
|
|
0
|
61 "Version string for Balloon Help.")
|
|
|
62
|
|
|
63 (defvar balloon-help-mode t
|
|
|
64 "*Non-nil means Balloon help mode is enabled.")
|
|
|
65
|
|
|
66 (defvar balloon-help-timeout 1500
|
|
|
67 "*Display help after this many milliseconds of mouse inactivity.")
|
|
|
68
|
|
|
69 (defvar balloon-help-foreground "black"
|
|
|
70 "*The foreground color for displaying balloon help text.")
|
|
|
71
|
|
|
72 (defvar balloon-help-background "rgb:c0/c0/c0"
|
|
|
73 "*The background color for the balloon help frame.")
|
|
|
74
|
|
|
75 (defvar balloon-help-background-pixmap ""
|
|
|
76 "*The background pixmap for the balloon help frame.")
|
|
|
77
|
|
|
78 (defvar balloon-help-font "fixed"
|
|
|
79 "*The font for displaying balloon help text.")
|
|
|
80
|
|
|
81 (defvar balloon-help-border-color "black"
|
|
|
82 "*The color for displaying balloon help frame's border.")
|
|
|
83
|
|
26
|
84 (defvar balloon-help-border-width 2
|
|
|
85 "*The width of the balloon help frame's border.")
|
|
|
86
|
|
0
|
87 (defvar balloon-help-use-sound nil
|
|
|
88 "*Non-nil value means play a sound to herald the appearance
|
|
|
89 and disappearance of the help frame.
|
|
|
90
|
|
|
91 `balloon-help-appears' will be played when the frame appears.
|
|
|
92 `balloon-help-disappears' will be played when the frame disappears.
|
|
|
93
|
|
|
94 See the documentation for the function load-sound-file to see how
|
|
|
95 define sounds.")
|
|
|
96
|
|
|
97 (defvar balloon-help-frame-name nil
|
|
|
98 "*The frame name to use for the frame to display the balloon help.")
|
|
|
99
|
|
22
|
100 (defvar balloon-help-aggressively-follow-mouse nil
|
|
|
101 "*Non-nil means the balloon should move with the mouse even if the mouse
|
|
|
102 is over the same object as the last mouse motion event.")
|
|
|
103
|
|
0
|
104 ;;;
|
|
|
105 ;;; End of user variables.
|
|
|
106 ;;;
|
|
|
107
|
|
|
108 (defvar mouse-motion-hook mouse-motion-handler
|
|
|
109 "Hooks to be run whenever the user moves the mouse.
|
|
|
110 Each hook is called with one argument, the mouse motion event.")
|
|
|
111
|
|
|
112 (defun mouse-motion-hook (event)
|
|
|
113 "Run the hooks attached to mouse-motion-hook."
|
|
|
114 (run-hook-with-args 'mouse-motion-hook event))
|
|
|
115
|
|
|
116 (setq mouse-motion-handler 'mouse-motion-hook)
|
|
|
117
|
|
|
118 (defvar balloon-help-frame nil
|
|
|
119 "Balloon help is displayed in this frame.")
|
|
|
120
|
|
|
121 (defvar balloon-help-help-object nil
|
|
|
122 "Object that the mouse is over that has a help property, nil otherwise.")
|
|
|
123
|
|
|
124 (defvar balloon-help-help-object-x nil
|
|
|
125 "Last horizontal mouse position over balloon-help-help-object.")
|
|
|
126
|
|
|
127 (defvar balloon-help-help-object-y nil
|
|
|
128 "Last vertical mouse position over balloon-help-help-object.")
|
|
|
129
|
|
|
130 (defvar balloon-help-buffer nil
|
|
|
131 "Buffer used to display balloon help.")
|
|
|
132
|
|
|
133 (defvar balloon-help-timeout-id nil
|
|
|
134 "Timeout id for the balloon help timeout.")
|
|
|
135
|
|
|
136 (defvar balloon-help-display-pending nil
|
|
|
137 "Non-nil value means the help frame will be visible as soon
|
|
|
138 as the X server gets around to displaying it. Nil means it
|
|
|
139 will be invisible as soon as the X server decides to hide it.")
|
|
|
140
|
|
|
141 (defvar balloon-help-bar-cursor nil)
|
|
|
142
|
|
|
143 (defun balloon-help-mode (&optional arg)
|
|
|
144 "Toggle Balloon Help mode.
|
|
|
145 With arg, turn Balloon Help mode on iff arg is positive.
|
|
|
146
|
|
|
147 With Balloon Help enabled, a small frame is displayed whenever
|
|
|
148 the mouse rests on an object that has a help property of some
|
|
|
149 kind. The text of that help property is displayed in the frame.
|
|
|
150
|
|
|
151 For extents, the 'balloon-help' property is
|
|
|
152 checked.
|
|
|
153
|
|
|
154 For toolbar buttons, the help-string slot of the toolbar button
|
|
|
155 is checked.
|
|
|
156
|
|
|
157 If the value is a string, it is used as the help message.
|
|
|
158
|
|
|
159 If the property's value is a symbol, it is assumed to be the name
|
|
|
160 of a function and it will be called with one argument, the object
|
|
|
161 under the mouse, and the return value of that function will be
|
|
|
162 used as the help message."
|
|
|
163 (interactive "P")
|
|
|
164 (setq balloon-help-mode (or (and arg (> (prefix-numeric-value arg) 0))
|
|
|
165 (and (null arg) (null balloon-help-mode))))
|
|
|
166 (if (null balloon-help-mode)
|
|
|
167 (balloon-help-undisplay-help)))
|
|
|
168
|
|
|
169 (defun balloon-help-displayed ()
|
|
|
170 (and (frame-live-p balloon-help-frame)
|
|
|
171 (frame-visible-p balloon-help-frame)))
|
|
|
172
|
|
|
173 (defun balloon-help-motion-hook (event)
|
|
|
174 (cond
|
|
|
175 ((null balloon-help-mode) t)
|
|
|
176 ((button-press-event-p event)
|
|
|
177 (setq balloon-help-help-object nil)
|
|
|
178 (if balloon-help-timeout-id
|
|
|
179 (disable-timeout balloon-help-timeout-id))
|
|
|
180 (if (balloon-help-displayed)
|
|
|
181 (balloon-help-undisplay-help)))
|
|
|
182 (t
|
|
|
183 (let* ((buffer (event-buffer event))
|
|
|
184 (frame (event-frame event))
|
|
|
185 (point (and buffer (event-point event)))
|
|
|
186 (glyph-extent (event-glyph-extent event))
|
|
|
187 (glyph-extent (if (and glyph-extent
|
|
|
188 (extent-property glyph-extent
|
|
|
189 'balloon-help))
|
|
|
190 glyph-extent))
|
|
|
191 (extent (and point
|
|
|
192 (extent-at point buffer 'balloon-help)))
|
|
|
193 (button (event-toolbar-button event))
|
|
|
194 (button (if (and button (toolbar-button-help-string button))
|
|
|
195 button
|
|
|
196 nil))
|
|
|
197 (object (or glyph-extent extent button))
|
|
|
198 (id balloon-help-timeout-id))
|
|
|
199 (if (null object)
|
|
|
200 (if (and balloon-help-frame
|
|
|
201 (not (eq frame balloon-help-frame)))
|
|
|
202 (progn
|
|
|
203 (setq balloon-help-help-object nil)
|
|
|
204 (if id
|
|
|
205 (disable-timeout id))
|
|
|
206 (if (balloon-help-displayed)
|
|
|
207 (balloon-help-undisplay-help))))
|
|
|
208 (let* ((params (frame-parameters frame))
|
|
|
209 (top (cdr (assq 'top params)))
|
|
|
210 (left (cdr (assq 'left params)))
|
|
|
211 (xtop-toolbar-height
|
|
26
|
212 (if (and (specifier-instance top-toolbar-visible-p frame)
|
|
|
213 (specifier-instance top-toolbar frame))
|
|
|
214 (specifier-instance top-toolbar-height frame)
|
|
0
|
215 0))
|
|
|
216 (xleft-toolbar-width
|
|
26
|
217 (if (and (specifier-instance left-toolbar-visible-p frame)
|
|
|
218 (specifier-instance left-toolbar frame))
|
|
|
219 (specifier-instance left-toolbar-width frame)
|
|
0
|
220 0))
|
|
26
|
221 (menubar-height
|
|
|
222 (if (and buffer
|
|
|
223 (specifier-instance menubar-visible-p)
|
|
|
224 (save-excursion (set-buffer buffer) current-menubar))
|
|
|
225 22 0)))
|
|
0
|
226 (setq balloon-help-help-object-x
|
|
|
227 (+ left xleft-toolbar-width (event-x-pixel event))
|
|
|
228 balloon-help-help-object-y
|
|
|
229 (+ top xtop-toolbar-height menubar-height
|
|
|
230 (event-y-pixel event))))
|
|
|
231 (cond ((eq frame balloon-help-frame) t)
|
|
|
232 ((eq object balloon-help-help-object)
|
|
22
|
233 (if (and (balloon-help-displayed)
|
|
|
234 balloon-help-aggressively-follow-mouse)
|
|
0
|
235 (balloon-help-move-help-frame)))
|
|
|
236 ((balloon-help-displayed)
|
|
|
237 (setq balloon-help-help-object object)
|
|
|
238 (balloon-help-display-help))
|
|
|
239 (t
|
|
|
240 (setq balloon-help-help-object object)
|
|
|
241 (if id
|
|
|
242 (disable-timeout id))
|
|
|
243 (setq balloon-help-timeout-id
|
|
|
244 (add-timeout (/ balloon-help-timeout 1000.0)
|
|
|
245 (function balloon-help-display-help)
|
|
|
246 nil)))))))))
|
|
|
247
|
|
|
248 (defun balloon-help-pre-command-hook (&rest ignored)
|
|
|
249 (setq balloon-help-help-object nil)
|
|
|
250 (if (balloon-help-displayed)
|
|
|
251 (balloon-help-undisplay-help)))
|
|
|
252
|
|
|
253 (fset 'balloon-help-post-command-hook 'balloon-help-pre-command-hook)
|
|
|
254 (fset 'balloon-help-mouse-leave-frame-hook 'balloon-help-pre-command-hook)
|
|
|
255 (fset 'balloon-help-deselect-frame-hook 'balloon-help-pre-command-hook)
|
|
|
256
|
|
|
257 (defun balloon-help-display-help (&rest ignored)
|
|
|
258 (setq balloon-help-timeout-id nil)
|
|
|
259 (if balloon-help-help-object
|
|
|
260 (let* ((object balloon-help-help-object)
|
|
|
261 (help (or (and (extent-live-p object)
|
|
|
262 (extent-property object 'balloon-help))
|
|
|
263 (and (toolbar-button-p object)
|
|
|
264 (toolbar-button-help-string object))
|
|
|
265 (and (stringp object) object))))
|
|
|
266 ;; if help is non-null and is not a string, run it as
|
|
|
267 ;; function to produuce the help string.
|
|
|
268 (if (or (null help) (not (symbolp help)))
|
|
|
269 nil
|
|
|
270 (condition-case data
|
|
|
271 (setq help (funcall help object))
|
|
|
272 (error
|
|
|
273 (setq help (format "help function signaled: %S" data)))))
|
|
|
274 (if (stringp help)
|
|
|
275 (save-excursion
|
|
|
276 (if (not (bufferp balloon-help-buffer))
|
|
|
277 (setq balloon-help-buffer
|
|
|
278 (get-buffer-create " *balloon-help*")))
|
|
|
279 (if (not (frame-live-p balloon-help-frame))
|
|
|
280 (setq balloon-help-frame (balloon-help-make-help-frame)))
|
|
|
281 (setq bar-cursor t)
|
|
|
282 (set-buffer balloon-help-buffer)
|
|
|
283 (erase-buffer)
|
|
|
284 (insert help)
|
|
|
285 (if (not (bolp))
|
|
|
286 (insert ?\n))
|
|
|
287 ;; help strings longer than 2 lines have the last
|
|
|
288 ;; line stolen by the minibuffer, so make sure the
|
|
|
289 ;; last line is blank. Make the top line blank for
|
|
|
290 ;; some symmetry.
|
|
|
291 (if (< 2 (count-lines (point-min) (point-max)))
|
|
|
292 (progn
|
|
|
293 (insert ?\n)
|
|
|
294 ;; add a second blank line at the end to
|
|
|
295 ;; prevent the modeline bar from clipping the
|
|
|
296 ;; descenders of the last line of text.
|
|
|
297 (insert ?\n)
|
|
|
298 (goto-char (point-min))
|
|
|
299 (insert ?\n)))
|
|
|
300 ;; cursor will be at point-min because we're just
|
|
|
301 ;; moving point which doesn't affect window-point
|
|
|
302 ;; when the window isn't selected. Indent
|
|
|
303 ;; everything so that the cursor will be over a
|
|
|
304 ;; space. The 1-pixel bar cursor will be
|
|
|
305 ;; completely invisible this way.
|
|
|
306 (indent-rigidly (point-min) (point-max) 1)
|
|
|
307 (balloon-help-move-help-frame)
|
|
|
308 (balloon-help-resize-help-frame)
|
|
|
309 (balloon-help-expose-help-frame))))))
|
|
|
310
|
|
|
311 (defun balloon-help-undisplay-help ()
|
|
|
312 (setq bar-cursor balloon-help-bar-cursor)
|
|
|
313 (balloon-help-hide-help-frame))
|
|
|
314
|
|
|
315 (defun balloon-help-hide-help-frame ()
|
|
|
316 (if (balloon-help-displayed)
|
|
|
317 (progn
|
|
|
318 (make-frame-invisible balloon-help-frame)
|
|
|
319 (if (and balloon-help-use-sound balloon-help-display-pending)
|
|
|
320 (play-sound 'balloon-help-disappears))
|
|
|
321 (setq balloon-help-display-pending nil))))
|
|
|
322
|
|
|
323 (defun balloon-help-expose-help-frame ()
|
|
|
324 (if (not (balloon-help-displayed))
|
|
|
325 (progn
|
|
|
326 (make-frame-visible balloon-help-frame)
|
|
|
327 (if (and balloon-help-use-sound (null balloon-help-display-pending))
|
|
|
328 (play-sound 'balloon-help-appears))
|
|
|
329 (setq balloon-help-display-pending t))))
|
|
|
330
|
|
|
331 (defun balloon-help-resize-help-frame ()
|
|
|
332 (save-excursion
|
|
|
333 (set-buffer balloon-help-buffer)
|
|
|
334 (let ((longest 0)
|
|
|
335 (lines 0)
|
|
|
336 (done nil)
|
|
|
337 (window-min-height 1)
|
|
|
338 (window-min-width 1))
|
|
|
339 (goto-char (point-min))
|
|
|
340 (while (not done)
|
|
|
341 (end-of-line)
|
|
|
342 (setq longest (max longest (current-column))
|
|
|
343 done (not (= 0 (forward-line))))
|
|
|
344 (and (not done) (setq lines (1+ lines))))
|
|
|
345 (set-frame-size balloon-help-frame (+ 1 longest) lines))))
|
|
|
346
|
|
26
|
347 (defun balloon-help-make-junk-frame ()
|
|
|
348 (let ((window-min-height 1)
|
|
|
349 (window-min-width 1))
|
|
|
350 (make-frame '(minibuffer t initially-unmapped t width 1 height 1))))
|
|
|
351
|
|
0
|
352 (defun balloon-help-make-help-frame ()
|
|
|
353 (save-excursion
|
|
|
354 (setq balloon-help-bar-cursor bar-cursor)
|
|
|
355 (set-buffer balloon-help-buffer)
|
|
|
356 (set-buffer-menubar nil)
|
|
|
357 (let* ((x (balloon-help-compute-help-frame-x-location))
|
|
|
358 (y (balloon-help-compute-help-frame-y-location))
|
|
|
359 (window-min-height 1)
|
|
|
360 (window-min-width 1)
|
|
|
361 (frame (make-frame (list
|
|
|
362 '(initially-unmapped . t)
|
|
|
363 ;; try to evade frame decorations
|
|
|
364 (cons 'name (or balloon-help-frame-name
|
|
|
365 "xclock"))
|
|
26
|
366 (cons 'border-width balloon-help-border-width)
|
|
0
|
367 (cons 'border-color balloon-help-border-color)
|
|
|
368 (cons 'top y)
|
|
|
369 (cons 'left x)
|
|
26
|
370 (cons 'popup (balloon-help-make-junk-frame))
|
|
0
|
371 '(width . 3)
|
|
|
372 '(height . 1)))))
|
|
|
373 (set-face-font 'default balloon-help-font frame)
|
|
|
374 (set-face-foreground 'default balloon-help-foreground frame)
|
|
|
375 (set-face-background 'default balloon-help-background frame)
|
|
|
376 (set-face-background-pixmap 'default balloon-help-background-pixmap
|
|
|
377 frame)
|
|
|
378 (set-window-buffer (frame-selected-window frame) balloon-help-buffer)
|
|
|
379 (set-specifier has-modeline-p (cons frame nil))
|
|
|
380 (set-specifier top-toolbar-height (cons frame 0))
|
|
|
381 (set-specifier left-toolbar-width (cons frame 0))
|
|
|
382 (set-specifier right-toolbar-width (cons frame 0))
|
|
|
383 (set-specifier bottom-toolbar-height (cons frame 0))
|
|
|
384 (set-specifier top-toolbar (cons frame nil))
|
|
|
385 (set-specifier left-toolbar (cons frame nil))
|
|
|
386 (set-specifier right-toolbar (cons frame nil))
|
|
|
387 (set-specifier bottom-toolbar (cons frame nil))
|
|
|
388 (set-specifier scrollbar-width (cons frame 0))
|
|
|
389 (set-specifier scrollbar-height (cons frame 0))
|
|
26
|
390 (and (boundp 'text-cursor-visible-p)
|
|
|
391 (specifierp text-cursor-visible-p)
|
|
|
392 (set-specifier text-cursor-visible-p (cons frame nil)))
|
|
0
|
393 (set-specifier modeline-shadow-thickness (cons frame 0))
|
|
|
394 (set-face-background 'modeline balloon-help-background frame)
|
|
|
395 frame )))
|
|
|
396
|
|
|
397 (defun balloon-help-compute-help-frame-x-location ()
|
|
|
398 (max 0 (+ 32 balloon-help-help-object-x)))
|
|
|
399
|
|
|
400 (defun balloon-help-compute-help-frame-y-location ()
|
|
|
401 (max 0 (+ 48 balloon-help-help-object-y)))
|
|
|
402
|
|
|
403 (defun balloon-help-move-help-frame ()
|
|
|
404 (let ((x (balloon-help-compute-help-frame-x-location))
|
|
|
405 (y (balloon-help-compute-help-frame-y-location)))
|
|
|
406 (set-frame-position balloon-help-frame x y)))
|
|
|
407
|
|
|
408 (add-hook 'mouse-motion-hook 'balloon-help-motion-hook)
|
|
|
409 (add-hook 'pre-command-hook 'balloon-help-pre-command-hook)
|
|
|
410 (add-hook 'post-command-hook 'balloon-help-post-command-hook)
|
|
|
411 (add-hook 'mouse-leave-frame-hook 'balloon-help-mouse-leave-frame-hook)
|
|
26
|
412 ;; loses with ClickToFocus under fvwm
|
|
|
413 ;;(add-hook 'deselect-frame-hook 'balloon-help-deselect-frame-hook)
|
