|
0
|
1 ;;; Balloon help for XEmacs (requires 19.12 or later)
|
|
98
|
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
|
|
98
|
60 (defvar balloon-help-version "1.03"
|
|
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
|
|
|
84 (defvar balloon-help-use-sound nil
|
|
|
85 "*Non-nil value means play a sound to herald the appearance
|
|
|
86 and disappearance of the help frame.
|
|
|
87
|
|
|
88 `balloon-help-appears' will be played when the frame appears.
|
|
|
89 `balloon-help-disappears' will be played when the frame disappears.
|
|
|
90
|
|
|
91 See the documentation for the function load-sound-file to see how
|
|
|
92 define sounds.")
|
|
|
93
|
|
|
94 (defvar balloon-help-frame-name nil
|
|
|
95 "*The frame name to use for the frame to display the balloon help.")
|
|
|
96
|
|
98
|
97 (defvar balloon-help-aggressively-follow-mouse nil
|
|
|
98 "*Non-nil means the balloon should move with the mouse even if the mouse
|
|
|
99 is over the same object as the last mouse motion event.")
|
|
|
100
|
|
0
|
101 ;;;
|
|
|
102 ;;; End of user variables.
|
|
|
103 ;;;
|
|
|
104
|
|
|
105 (defvar mouse-motion-hook mouse-motion-handler
|
|
|
106 "Hooks to be run whenever the user moves the mouse.
|
|
|
107 Each hook is called with one argument, the mouse motion event.")
|
|
|
108
|
|
|
109 (defun mouse-motion-hook (event)
|
|
|
110 "Run the hooks attached to mouse-motion-hook."
|
|
|
111 (run-hook-with-args 'mouse-motion-hook event))
|
|
|
112
|
|
|
113 (setq mouse-motion-handler 'mouse-motion-hook)
|
|
|
114
|
|
|
115 (defvar balloon-help-frame nil
|
|
|
116 "Balloon help is displayed in this frame.")
|
|
|
117
|
|
|
118 (defvar balloon-help-help-object nil
|
|
|
119 "Object that the mouse is over that has a help property, nil otherwise.")
|
|
|
120
|
|
|
121 (defvar balloon-help-help-object-x nil
|
|
|
122 "Last horizontal mouse position over balloon-help-help-object.")
|
|
|
123
|
|
|
124 (defvar balloon-help-help-object-y nil
|
|
|
125 "Last vertical mouse position over balloon-help-help-object.")
|
|
|
126
|
|
|
127 (defvar balloon-help-buffer nil
|
|
|
128 "Buffer used to display balloon help.")
|
|
|
129
|
|
|
130 (defvar balloon-help-timeout-id nil
|
|
|
131 "Timeout id for the balloon help timeout.")
|
|
|
132
|
|
|
133 (defvar balloon-help-display-pending nil
|
|
|
134 "Non-nil value means the help frame will be visible as soon
|
|
|
135 as the X server gets around to displaying it. Nil means it
|
|
|
136 will be invisible as soon as the X server decides to hide it.")
|
|
|
137
|
|
70
|
138 (defvar balloon-help-bar-cursor nil)
|
|
|
139
|
|
0
|
140 (defun balloon-help-mode (&optional arg)
|
|
|
141 "Toggle Balloon Help mode.
|
|
|
142 With arg, turn Balloon Help mode on iff arg is positive.
|
|
|
143
|
|
|
144 With Balloon Help enabled, a small frame is displayed whenever
|
|
|
145 the mouse rests on an object that has a help property of some
|
|
|
146 kind. The text of that help property is displayed in the frame.
|
|
|
147
|
|
|
148 For extents, the 'balloon-help' property is
|
|
|
149 checked.
|
|
|
150
|
|
|
151 For toolbar buttons, the help-string slot of the toolbar button
|
|
|
152 is checked.
|
|
|
153
|
|
|
154 If the value is a string, it is used as the help message.
|
|
|
155
|
|
|
156 If the property's value is a symbol, it is assumed to be the name
|
|
|
157 of a function and it will be called with one argument, the object
|
|
|
158 under the mouse, and the return value of that function will be
|
|
|
159 used as the help message."
|
|
|
160 (interactive "P")
|
|
|
161 (setq balloon-help-mode (or (and arg (> (prefix-numeric-value arg) 0))
|
|
|
162 (and (null arg) (null balloon-help-mode))))
|
|
|
163 (if (null balloon-help-mode)
|
|
|
164 (balloon-help-undisplay-help)))
|
|
|
165
|
|
|
166 (defun balloon-help-displayed ()
|
|
|
167 (and (frame-live-p balloon-help-frame)
|
|
|
168 (frame-visible-p balloon-help-frame)))
|
|
|
169
|
|
|
170 (defun balloon-help-motion-hook (event)
|
|
|
171 (cond
|
|
|
172 ((null balloon-help-mode) t)
|
|
|
173 ((button-press-event-p event)
|
|
|
174 (setq balloon-help-help-object nil)
|
|
|
175 (if balloon-help-timeout-id
|
|
|
176 (disable-timeout balloon-help-timeout-id))
|
|
|
177 (if (balloon-help-displayed)
|
|
|
178 (balloon-help-undisplay-help)))
|
|
|
179 (t
|
|
|
180 (let* ((buffer (event-buffer event))
|
|
|
181 (frame (event-frame event))
|
|
|
182 (point (and buffer (event-point event)))
|
|
|
183 (glyph-extent (event-glyph-extent event))
|
|
|
184 (glyph-extent (if (and glyph-extent
|
|
|
185 (extent-property glyph-extent
|
|
|
186 'balloon-help))
|
|
|
187 glyph-extent))
|
|
|
188 (extent (and point
|
|
|
189 (extent-at point buffer 'balloon-help)))
|
|
|
190 (button (event-toolbar-button event))
|
|
|
191 (button (if (and button (toolbar-button-help-string button))
|
|
|
192 button
|
|
|
193 nil))
|
|
70
|
194 (object (or glyph-extent extent button))
|
|
0
|
195 (id balloon-help-timeout-id))
|
|
|
196 (if (null object)
|
|
|
197 (if (and balloon-help-frame
|
|
|
198 (not (eq frame balloon-help-frame)))
|
|
|
199 (progn
|
|
|
200 (setq balloon-help-help-object nil)
|
|
|
201 (if id
|
|
|
202 (disable-timeout id))
|
|
|
203 (if (balloon-help-displayed)
|
|
|
204 (balloon-help-undisplay-help))))
|
|
|
205 (let* ((params (frame-parameters frame))
|
|
|
206 (top (cdr (assq 'top params)))
|
|
|
207 (left (cdr (assq 'left params)))
|
|
|
208 (xtop-toolbar-height
|
|
70
|
209 (if (specifier-instance top-toolbar)
|
|
|
210 (specifier-instance top-toolbar-height)
|
|
0
|
211 0))
|
|
|
212 (xleft-toolbar-width
|
|
70
|
213 (if (specifier-instance left-toolbar)
|
|
|
214 (specifier-instance left-toolbar-width)
|
|
0
|
215 0))
|
|
70
|
216 (menubar-height (if current-menubar 22 0)))
|
|
0
|
217 (setq balloon-help-help-object-x
|
|
|
218 (+ left xleft-toolbar-width (event-x-pixel event))
|
|
|
219 balloon-help-help-object-y
|
|
|
220 (+ top xtop-toolbar-height menubar-height
|
|
|
221 (event-y-pixel event))))
|
|
|
222 (cond ((eq frame balloon-help-frame) t)
|
|
|
223 ((eq object balloon-help-help-object)
|
|
98
|
224 (if (and (balloon-help-displayed)
|
|
|
225 balloon-help-aggressively-follow-mouse)
|
|
0
|
226 (balloon-help-move-help-frame)))
|
|
|
227 ((balloon-help-displayed)
|
|
|
228 (setq balloon-help-help-object object)
|
|
|
229 (balloon-help-display-help))
|
|
|
230 (t
|
|
|
231 (setq balloon-help-help-object object)
|
|
|
232 (if id
|
|
|
233 (disable-timeout id))
|
|
|
234 (setq balloon-help-timeout-id
|
|
|
235 (add-timeout (/ balloon-help-timeout 1000.0)
|
|
|
236 (function balloon-help-display-help)
|
|
|
237 nil)))))))))
|
|
|
238
|
|
|
239 (defun balloon-help-pre-command-hook (&rest ignored)
|
|
|
240 (setq balloon-help-help-object nil)
|
|
|
241 (if (balloon-help-displayed)
|
|
|
242 (balloon-help-undisplay-help)))
|
|
|
243
|
|
|
244 (fset 'balloon-help-post-command-hook 'balloon-help-pre-command-hook)
|
|
|
245 (fset 'balloon-help-mouse-leave-frame-hook 'balloon-help-pre-command-hook)
|
|
|
246 (fset 'balloon-help-deselect-frame-hook 'balloon-help-pre-command-hook)
|
|
|
247
|
|
|
248 (defun balloon-help-display-help (&rest ignored)
|
|
|
249 (setq balloon-help-timeout-id nil)
|
|
|
250 (if balloon-help-help-object
|
|
|
251 (let* ((object balloon-help-help-object)
|
|
|
252 (help (or (and (extent-live-p object)
|
|
|
253 (extent-property object 'balloon-help))
|
|
|
254 (and (toolbar-button-p object)
|
|
|
255 (toolbar-button-help-string object))
|
|
|
256 (and (stringp object) object))))
|
|
|
257 ;; if help is non-null and is not a string, run it as
|
|
|
258 ;; function to produuce the help string.
|
|
|
259 (if (or (null help) (not (symbolp help)))
|
|
|
260 nil
|
|
|
261 (condition-case data
|
|
|
262 (setq help (funcall help object))
|
|
|
263 (error
|
|
|
264 (setq help (format "help function signaled: %S" data)))))
|
|
|
265 (if (stringp help)
|
|
|
266 (save-excursion
|
|
|
267 (if (not (bufferp balloon-help-buffer))
|
|
|
268 (setq balloon-help-buffer
|
|
|
269 (get-buffer-create " *balloon-help*")))
|
|
|
270 (if (not (frame-live-p balloon-help-frame))
|
|
|
271 (setq balloon-help-frame (balloon-help-make-help-frame)))
|
|
70
|
272 (setq bar-cursor t)
|
|
0
|
273 (set-buffer balloon-help-buffer)
|
|
|
274 (erase-buffer)
|
|
|
275 (insert help)
|
|
|
276 (if (not (bolp))
|
|
|
277 (insert ?\n))
|
|
|
278 ;; help strings longer than 2 lines have the last
|
|
|
279 ;; line stolen by the minibuffer, so make sure the
|
|
|
280 ;; last line is blank. Make the top line blank for
|
|
|
281 ;; some symmetry.
|
|
|
282 (if (< 2 (count-lines (point-min) (point-max)))
|
|
|
283 (progn
|
|
|
284 (insert ?\n)
|
|
|
285 ;; add a second blank line at the end to
|
|
|
286 ;; prevent the modeline bar from clipping the
|
|
|
287 ;; descenders of the last line of text.
|
|
|
288 (insert ?\n)
|
|
|
289 (goto-char (point-min))
|
|
|
290 (insert ?\n)))
|
|
|
291 ;; cursor will be at point-min because we're just
|
|
|
292 ;; moving point which doesn't affect window-point
|
|
|
293 ;; when the window isn't selected. Indent
|
|
|
294 ;; everything so that the cursor will be over a
|
|
|
295 ;; space. The 1-pixel bar cursor will be
|
|
|
296 ;; completely invisible this way.
|
|
|
297 (indent-rigidly (point-min) (point-max) 1)
|
|
|
298 (balloon-help-move-help-frame)
|
|
|
299 (balloon-help-resize-help-frame)
|
|
|
300 (balloon-help-expose-help-frame))))))
|
|
|
301
|
|
|
302 (defun balloon-help-undisplay-help ()
|
|
70
|
303 (setq bar-cursor balloon-help-bar-cursor)
|
|
0
|
304 (balloon-help-hide-help-frame))
|
|
|
305
|
|
|
306 (defun balloon-help-hide-help-frame ()
|
|
|
307 (if (balloon-help-displayed)
|
|
|
308 (progn
|
|
|
309 (make-frame-invisible balloon-help-frame)
|
|
|
310 (if (and balloon-help-use-sound balloon-help-display-pending)
|
|
|
311 (play-sound 'balloon-help-disappears))
|
|
|
312 (setq balloon-help-display-pending nil))))
|
|
|
313
|
|
|
314 (defun balloon-help-expose-help-frame ()
|
|
|
315 (if (not (balloon-help-displayed))
|
|
|
316 (progn
|
|
|
317 (make-frame-visible balloon-help-frame)
|
|
|
318 (if (and balloon-help-use-sound (null balloon-help-display-pending))
|
|
|
319 (play-sound 'balloon-help-appears))
|
|
|
320 (setq balloon-help-display-pending t))))
|
|
|
321
|
|
|
322 (defun balloon-help-resize-help-frame ()
|
|
|
323 (save-excursion
|
|
|
324 (set-buffer balloon-help-buffer)
|
|
|
325 (let ((longest 0)
|
|
|
326 (lines 0)
|
|
|
327 (done nil)
|
|
|
328 (window-min-height 1)
|
|
|
329 (window-min-width 1))
|
|
|
330 (goto-char (point-min))
|
|
|
331 (while (not done)
|
|
|
332 (end-of-line)
|
|
|
333 (setq longest (max longest (current-column))
|
|
|
334 done (not (= 0 (forward-line))))
|
|
|
335 (and (not done) (setq lines (1+ lines))))
|
|
|
336 (set-frame-size balloon-help-frame (+ 1 longest) lines))))
|
|
|
337
|
|
|
338 (defun balloon-help-make-help-frame ()
|
|
|
339 (save-excursion
|
|
70
|
340 (setq balloon-help-bar-cursor bar-cursor)
|
|
0
|
341 (set-buffer balloon-help-buffer)
|
|
|
342 (set-buffer-menubar nil)
|
|
|
343 (let* ((x (balloon-help-compute-help-frame-x-location))
|
|
|
344 (y (balloon-help-compute-help-frame-y-location))
|
|
|
345 (window-min-height 1)
|
|
|
346 (window-min-width 1)
|
|
|
347 (frame (make-frame (list
|
|
|
348 '(initially-unmapped . t)
|
|
|
349 ;; try to evade frame decorations
|
|
|
350 (cons 'name (or balloon-help-frame-name
|
|
|
351 "xclock"))
|
|
70
|
352 '(border-width . 2)
|
|
0
|
353 (cons 'border-color balloon-help-border-color)
|
|
|
354 (cons 'top y)
|
|
|
355 (cons 'left x)
|
|
70
|
356 (cons 'popup (selected-frame))
|
|
0
|
357 '(width . 3)
|
|
|
358 '(height . 1)))))
|
|
|
359 (set-face-font 'default balloon-help-font frame)
|
|
|
360 (set-face-foreground 'default balloon-help-foreground frame)
|
|
|
361 (set-face-background 'default balloon-help-background frame)
|
|
|
362 (set-face-background-pixmap 'default balloon-help-background-pixmap
|
|
|
363 frame)
|
|
|
364 (set-window-buffer (frame-selected-window frame) balloon-help-buffer)
|
|
|
365 (set-specifier has-modeline-p (cons frame nil))
|
|
|
366 (set-specifier top-toolbar-height (cons frame 0))
|
|
|
367 (set-specifier left-toolbar-width (cons frame 0))
|
|
|
368 (set-specifier right-toolbar-width (cons frame 0))
|
|
|
369 (set-specifier bottom-toolbar-height (cons frame 0))
|
|
|
370 (set-specifier top-toolbar (cons frame nil))
|
|
|
371 (set-specifier left-toolbar (cons frame nil))
|
|
|
372 (set-specifier right-toolbar (cons frame nil))
|
|
|
373 (set-specifier bottom-toolbar (cons frame nil))
|
|
|
374 (set-specifier scrollbar-width (cons frame 0))
|
|
|
375 (set-specifier scrollbar-height (cons frame 0))
|
|
|
376 (set-specifier modeline-shadow-thickness (cons frame 0))
|
|
|
377 (set-face-background 'modeline balloon-help-background frame)
|
|
|
378 frame )))
|
|
|
379
|
|
|
380 (defun balloon-help-compute-help-frame-x-location ()
|
|
|
381 (max 0 (+ 32 balloon-help-help-object-x)))
|
|
|
382
|
|
|
383 (defun balloon-help-compute-help-frame-y-location ()
|
|
|
384 (max 0 (+ 48 balloon-help-help-object-y)))
|
|
|
385
|
|
|
386 (defun balloon-help-move-help-frame ()
|
|
|
387 (let ((x (balloon-help-compute-help-frame-x-location))
|
|
|
388 (y (balloon-help-compute-help-frame-y-location)))
|
|
|
389 (set-frame-position balloon-help-frame x y)))
|
|
|
390
|
|
|
391 (add-hook 'mouse-motion-hook 'balloon-help-motion-hook)
|
|
|
392 (add-hook 'pre-command-hook 'balloon-help-pre-command-hook)
|
|
|
393 (add-hook 'post-command-hook 'balloon-help-post-command-hook)
|
|
|
394 (add-hook 'mouse-leave-frame-hook 'balloon-help-mouse-leave-frame-hook)
|
|
70
|
395 (add-hook 'deselect-frame-hook 'balloon-help-deselect-frame-hook)
|
