1 ;;; working --- Display a "working" message in the minibuffer.
3 ;;; Copyright (C) 1998, 1999, 2000, 2001, 2002 Eric M. Ludlam
5 ;; Author: Eric M. Ludlam <zappo@gnu.org>
9 ;; This program is free software; you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; This program is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs; see the file COPYING. If not, write to the
21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 ;; Boston, MA 02111-1307, USA.
26 ;; Working lets Emacs Lisp programmers easily display working messages.
27 ;; These messages typically come in the form of a percentile, or generic
28 ;; doodles if a maximum is unknown.
30 ;; The working entry points are quite simple. If you have a loop that needs
31 ;; to display a status as it goes along, it would look like this:
33 ;; (working-status-forms "Doing stuff" "done"
35 ;; (working-status (calc-percentile))
37 ;; (working-status t))
39 ;; If you cannot calculate a percentile, use the function
40 ;; `working-dynamic-status' instead, and pass in what you know. For
41 ;; both status printing functions, the first argument is optional,
42 ;; and you may pass in additional arguments as `format' elements
43 ;; to the first argument of `working-status-forms'.
45 ;; See the examples at the end of the buffer.
47 ;;; Backwards Compatibility:
49 ;; If you want to use working in your program, but don't want to force people
50 ;; to install working, use could add this at the beginning of your program for
54 ;; (condition-case nil
58 ;; (defmacro working-status-forms (message donestr &rest forms)
59 ;; "Contain a block of code during which a working status is shown."
60 ;; (list 'let (list (list 'msg message) (list 'dstr donestr)
62 ;; (cons 'progn forms)))
64 ;; (defun working-status (&optional percent &rest args)
65 ;; "Called within the macro `working-status-forms', show the status."
66 ;; (message "%s%s" (apply 'format msg args)
67 ;; (if (eq percent t) (concat "... " dstr)
68 ;; (format "... %3d%%"
70 ;; (floor (* 100.0 (/ (float (point))
71 ;; (point-max)))))))))
73 ;; (defun working-dynamic-status (&optional number &rest args)
74 ;; "Called within the macro `working-status-forms', show the status."
75 ;; (message "%s%s" (apply 'format msg args)
76 ;; (format "... %c" (aref [ ?- ?/ ?| ?\\ ] (% ref1 4))))
77 ;; (setq ref1 (1+ ref1)))
79 ;; (put 'working-status-forms 'lisp-indent-function 2)))))
81 ;; Depending on what features you use, it is, of course, easy to
82 ;; reduce the total size of the above by omitting those features you
89 ;; 1.1 Working messages are no longer logged.
90 ;; Added a generic animation display funciton:
91 ;; Convert celeron to animator
92 ;; Added a bounce display
93 ;; Made working robust under a multi-frame environment (speedbar)
95 ;; 1.2 Fix up documentation.
96 ;; Updated dotgrowth function for exceptionally large numbers of dots.
97 ;; Added the percentage bubble displays.
99 ;; 1.3 Added `working-status-timeout' and `working-status-call-process'.
100 ;; Added test fns `working-wait-for-keypress' and `working-verify-sleep'.
106 (defgroup working nil
107 "Working messages display."
112 ;;; User configurable variables
114 (defcustom working-status-percentage-type 'working-bar-percent-display
115 "*Function used to display the percent status.
116 Functions provided in `working' are:
117 `working-percent-display'
118 `working-bar-display'
119 `working-bar-percent-display'
120 `working-percent-bar-display'
121 `working-bubble-display'
122 `working-bubble-precent-display'
123 `working-celeron-percent-display'"
125 :type '(choice (const working-percent-display)
126 (const working-bar-display)
127 (const working-bar-percent-display)
128 (const working-percent-bar-display)
129 (const working-bubble-display)
130 (const working-bubble-percent-display)
131 (const working-celeron-percent-display)
134 (defcustom working-status-dynamic-type 'working-celeron-display
135 "*Function used to display an animation indicating progress being made.
136 Dynamic working types occur when the program does not know how long
137 it will take ahead of time. Functions provided in `working' are:
138 `working-number-display'
139 `working-text-display'
140 `working-spinner-display'
141 `working-dotgrowth-display'
142 `working-celeron-display'
143 `working-bounce-display'"
145 :type '(choice (const working-number-display)
146 (const working-text-display)
147 (const working-spinner-display)
148 (const working-dotgrowth-display)
149 (const working-celeron-display)
150 (const working-bounce-display)
153 (defcustom working-percentage-step 2
154 "*Percentage display step.
155 A number representing how large a step must be taken when working a
156 percentage display. A number such as `2' means `2%'."
162 ;; When the user doesn't want messages in the minibuffer, hack the mode
163 ;; line of the current buffer.
164 (if (featurep 'xemacs)
165 (defalias 'working-mode-line-update 'redraw-modeline)
166 (defalias 'working-mode-line-update 'force-mode-line-update))
168 (defvar working-mode-line-message nil
169 "Message used by working when showing status in the mode line.")
171 (if (boundp 'global-mode-string)
173 ;; If this variable exists, use it to push the working message into
174 ;; an interesting part of the mode line.
175 (if (null global-mode-string)
176 (setq global-mode-string (list "")))
177 (setq global-mode-string
178 (append global-mode-string '(working-mode-line-message))))
179 ;; Else, use minor mode trickery to get a reliable way of doing the
180 ;; same thing across many versions of Emacs.
181 (setq minor-mode-alist (cons
182 '(working-mode-line-message working-mode-line-message)
186 (defvar working-use-echo-area-p t
187 "*Non-nil use the echo area to display working messages.")
189 ;;; Variables used in stages
191 (defvar working-message nil
192 "Message stored when in a status loop.")
193 (defvar working-donestring nil
194 "Done string stored when in a status loop.")
195 (defvar working-ref1 nil
196 "A reference number used in a status loop.")
197 (defvar working-last-percent 0
198 "A reference number used in a status loop.")
200 ;;; Programmer functions
203 (or (fboundp 'noninteractive)
204 ;; Silence the Emacs byte compiler
205 (defun noninteractive nil))
206 (or (boundp 'noninteractive)
207 ;; Silence the XEmacs byte compiler
208 (defvar noninteractive))
211 (defun working-message-emacs (&rest args)
212 "Print but don't log a one-line message at the bottom of the screen.
213 See the function `message' for details on ARGS."
215 (let ((message-log-max nil)) ;; No logging
216 (apply 'message args))))
218 (defun working-message-xemacs (&rest args)
219 "Print but don't log a one-line message at the bottom of the screen.
220 See the function `message' for details on ARGS."
222 (let ((log-message-filter-function #'ignore)) ;; No logging
223 (apply 'message args))))
226 (defalias 'working-message-echo
227 (if (boundp 'log-message-filter-function)
228 'working-message-xemacs
229 'working-message-emacs))
230 (defalias 'working-current-message
231 (if (fboundp 'current-message)
236 (defun working-message (&rest args)
237 "Display a message using `working-message-echo' or in mode line.
238 See the function `message' for details on ARGS."
239 (if working-use-echo-area-p
240 (apply 'working-message-echo args)
241 (when (not working-mode-line-message)
242 ;; If we start out nil, put stuff in to show we are up to
243 (setq working-mode-line-message "Working...")
244 (working-mode-line-update)
249 (cond ((fboundp 'run-with-timer)
250 (defalias 'working-run-with-timer 'run-with-timer)
251 (defalias 'working-cancel-timer 'cancel-timer)
253 ;;Add compatibility here
255 ;; This gets the message out but has no timers.
256 (defun working-run-with-timer (&rest foo)
257 (working-message working-message))
258 (defun working-cancel-timer (&rest foo)
259 (working-message "%s%s"
261 working-donestring)))
264 (defmacro working-status-forms (message donestr &rest forms)
265 "Contain a block of code during which a working status is shown.
266 MESSAGE is the message string to use and DONESTR is the completed text
267 to use when the functions `working-status' is called from FORMS."
268 (let ((current-message (make-symbol "working-current-message")))
269 `(let ((,current-message (working-current-message))
270 (working-message ,message)
271 (working-donestring ,donestr)
273 (working-last-percent 0))
276 (setq working-mode-line-message nil)
277 (if working-use-echo-area-p
278 (message ,current-message)
279 (working-mode-line-update)
282 (put 'working-status-forms 'lisp-indent-function 2)
284 (defmacro working-status-timeout (timeout message donestr &rest forms)
285 "Contain a block of code during which working status is shown.
286 The code may call `sit-for' or `accept-process-output', so a timer
287 is needed to update the message.
288 TIMEOUT is the length of time to wait between message updates.
289 MESSAGE is the message string to use and DONESTR is the completed text
290 to use when the functions `working-status' is called from FORMS."
291 (let ((current-message (make-symbol "working-current-message")))
292 `(let* ((,current-message (working-current-message))
293 (working-message ,message)
294 (working-donestring ,donestr)
298 (working-run-with-timer time time 'working-dynamic-status)))
301 (working-cancel-timer working-timer)
302 (working-dynamic-status t)
303 (setq working-mode-line-message nil)
304 (if working-use-echo-area-p
305 (message ,current-message)
306 (working-mode-line-update)
309 (put 'working-status-timeout 'lisp-indent-function 3)
311 (defun working-status-call-process
312 (timeout message donestr program &optional infile buffer display &rest args)
313 "Display working messages while running a process.
314 TIMEOUT is how fast to display the messages.
315 MESSAGE is the message to show, and DONESTR is the string to add when done.
316 CALLPROCESSARGS are the same style of args as passed to `call-process'.
317 The are: PROGRAM, INFILE, BUFFER, DISPLAY, and ARGS.
318 Since it actually calls `start-process', not all features will work."
319 (working-status-timeout timeout message donestr
320 (let ((proc (apply 'start-process "working"
321 (if (listp buffer) (car buffer) buffer)
323 (set-process-sentinel proc 'list)
324 (while (eq (process-status proc) 'run)
325 (accept-process-output proc)
326 ;; accept-process-output caused my solaris Emacs 20.3 to crash.
327 ;; If this is unreliable for you, use the below which will work
328 ;; in that situation.
329 ;; (if (not (sit-for timeout)) (read-event))
332 (defun working-status (&optional percent &rest args)
333 "Called within the macro `working-status-forms', show the status.
334 If PERCENT is nil, then calculate PERCENT from the value of `point' in
335 the current buffer. If it is a number or float, use it as the raw
337 Additional ARGS are passed to fill on % elements of MESSAGE from the
338 macro `working-status-forms'."
339 (when working-status-percentage-type
341 (floor (* 100.0 (/ (float (point)) (point-max)))))))
343 (> (- p working-last-percent) working-percentage-step))
344 (let* ((m1 (apply 'format working-message args))
345 (m2 (funcall working-status-percentage-type (length m1) p)))
346 (working-message "%s%s" m1 m2)
347 (setq working-last-percent p))))))
349 (defun working-dynamic-status (&optional number &rest args)
350 "Called within the macro `working-status-forms', show the status.
351 If NUMBER is nil, then increment a local NUMBER from 0 with each call.
352 If it is a number or float, use it as the raw percentile.
353 Additional ARGS are passed to fill on % elements of MESSAGE from the
354 macro `working-status-forms'."
355 (when working-status-dynamic-type
356 (let* ((n (or number working-ref1))
357 (m1 (apply 'format working-message args))
358 (m2 (funcall working-status-dynamic-type (length m1) n)))
359 (working-message "%s%s" m1 m2)
360 (setq working-ref1 (1+ working-ref1)))))
364 (defun working-message-frame-width ()
365 "Return the width of the frame the working message will be in."
366 (let* ((mbw (cond ((fboundp 'frame-parameter)
367 (frame-parameter (selected-frame) 'minibuffer))
368 ((fboundp 'frame-property)
369 (frame-property (selected-frame) 'minibuffer))))
370 (fr (if (and mbw (not (eq mbw t)))
371 (window-frame mbw) default-minibuffer-frame)))
374 ;;; Percentage display types.
376 (defun working-percent-display (length percent)
377 "Return the percentage of the buffer that is done in a string.
378 LENGTH is the amount of display that has been used. PERCENT
379 is t to display the done string, or the percentage to display."
380 (cond ((eq percent t) (concat "... " working-donestring))
381 ;; All the % signs because it then gets passed to message.
382 (t (format "... %3d%%" percent))))
384 (defun working-bar-display (length percent)
385 "Return a string with a bar-graph showing percent.
386 LENGTH is the amount of display that has been used. PERCENT
387 is t to display the done string, or the percentage to display."
388 (let ((bs (- (working-message-frame-width) length 5)))
389 (cond ((eq percent t)
390 (concat ": [" (make-string bs ?#) "] " working-donestring))
392 (t (let ((bsl (floor (* (/ percent 100.0) bs))))
395 (make-string (- bs bsl) ?.)
398 (defun working-bar-percent-display (length percent)
399 "Return a string with a bar-graph and percentile showing percentage.
400 LENGTH is the amount of display that has been used. PERCENT
401 is t to display the done string, or the percentage to display."
402 (let* ((ps (if (eq percent t)
403 (concat "... " working-donestring)
404 (working-percent-display length percent)))
405 (psl (+ 2 length (if (eq percent t) working-ref1 (length ps)))))
406 (cond ((eq percent t)
407 (concat (working-bar-display psl 100) " " ps))
409 (setq working-ref1 (length ps))
410 (concat (working-bar-display psl percent) " " ps)))))
412 (defun working-percent-bar-display (length percent)
413 "Return a string with a percentile and bar-graph showing percentage.
414 LENGTH is the amount of display that has been used. PERCENT
415 is t to display the done string, or the percentage to display."
416 (let* ((ps (if (eq percent t)
417 (concat "... " working-donestring)
418 (working-percent-display length percent)))
419 (psl (+ 1 length (if (eq percent t) working-ref1 (length ps)))))
420 (cond ((eq percent t)
421 (concat ps " " (working-bar-display psl 100)))
423 (setq working-ref1 (length ps))
424 (concat ps " " (working-bar-display psl percent))))))
426 (defun working-bubble-display (length percent)
427 "Return a string with a bubble graph indicating the precent completed.
428 LENGTH is the amount of the display that has been used. PERCENT
429 is t to display the done string, or the percentage to display."
431 (concat " [@@@@@@@@@@@@@@@@@@@@] " working-donestring)
433 (bubbles [ ?. ?- ?o ?O ?@ ]))
435 (setq bs (concat bs (make-string (/ (floor percent) 5) ?@))))
437 (char-to-string (aref bubbles (% (floor percent) 5)))))
438 (if (< (/ (floor percent) 5) 20)
439 (setq bs (concat bs (make-string (- 19 (/ (floor percent) 5)) ? ))))
442 (defun working-bubble-percent-display (length percent)
443 "Return a string with a percentile and bubble graph showing percentage.
444 LENGTH is the amount of display that has been used. PERCENT
445 is t to display the done string, or the percentage to display."
446 (let* ((ps (if (eq percent t)
447 (concat " ... " working-donestring)
448 (working-percent-display length percent)))
449 (psl (+ 1 length (if (eq percent t) working-ref1 (length ps)))))
450 (cond ((eq percent t)
451 (concat (working-bubble-display psl t)))
453 (setq working-ref1 (length ps))
454 (concat (working-bubble-display psl percent) ps)))))
456 (defun working-celeron-percent-display (length percent)
457 "Return a string with a celeron and string showing percent.
458 LENGTH is the amount of display that has been used. PERCENT
459 is t to display the done string, or the percentage to display."
461 (cond ((eq percent t) (working-celeron-display length t))
462 ;; All the % signs because it then gets passed to message.
463 (t (format "%s %3d%%"
464 (working-celeron-display length 0)
466 (setq working-ref1 (1+ working-ref1))))
468 ;;; Dynamic display types.
470 (defun working-number-display (length number)
471 "Return a string displaying the number of things that happened.
472 LENGTH is the amount of display that has been used. NUMBER
473 is t to display the done string, or the number to display."
474 (cond ((eq number t) (concat "... " working-donestring))
475 ;; All the % signs because it then gets passed to message.
476 (t (format "... %d" number))))
478 (defun working-text-display (length text)
479 "Return a string displaying the name of things that happened.
480 LENGTH is the amount of display that has been used. TEXT
481 is t to display the done string, or the text to display."
483 (concat "... " working-donestring)
484 (format "... %s" text)))
486 (defun working-spinner-display (length number)
487 "Return a string displaying a spinner based on a number.
488 LENGTH is the amount of display that has been used. NUMBER
489 is t to display the done string, or the number to display."
490 (cond ((eq number t) (concat "... " working-donestring))
491 ;; All the % signs because it then gets passed to message.
492 (t (format "... %c" (aref [ ?- ?/ ?| ?\\ ] (% working-ref1 4))))))
494 (defun working-dotgrowth-display (length number)
495 "Return a string displaying growing dots due to activity.
496 LENGTH is the amount of display that has been used. NUMBER
497 is t to display the done string, or the number to display.
498 This display happens to ignore NUMBER."
499 (let* ((width (- (working-message-frame-width) 4 length))
500 (num-wrap (/ working-ref1 width))
501 (num-. (% working-ref1 width))
502 (dots [ ?. ?, ?o ?* ?O ?@ ?# ]))
503 (concat " (" (make-string num-. (aref dots (% num-wrap (length dots)))) ")"
504 (if (eq number t) (concat " " working-donestring) ""))))
506 (defun working-frame-animation-display (length number frames)
507 "Manage a simple frame-based animation for working functions.
508 LENGTH is the number of characters left. NUMBER is a passed in
509 number (which happens to be ignored.). While coders pass t into
510 NUMBER, functions using this should convert NUMBER into a vector
511 describing how to render the done message.
512 Argument FRAMES are the frames used in the animation."
513 (cond ((vectorp number)
514 (let ((zone (- (length (aref frames 0)) (length (aref number 0))
515 (length (aref number 1)))))
516 (if (< (length working-donestring) zone)
517 (concat " " (aref number 0)
519 (ceiling (/ (- (float zone)
520 (length working-donestring)) 2)) ? )
523 (floor (/ (- (float zone)
524 (length working-donestring)) 2)) ? )
526 (concat " " (aref frames (% working-ref1 (length frames)))
527 " " working-donestring))))
528 (t (concat " " (aref frames (% working-ref1 (length frames)))))))
530 (defvar working-celeron-strings
531 [ "[O ]" "[oO ]" "[-oO ]" "[ -oO ]" "[ -oO ]" "[ -oO]"
532 "[ -O]" "[ O]" "[ Oo]" "[ Oo-]" "[ Oo- ]" "[ Oo- ]"
534 "Strings representing a silly celeron.")
536 (defun working-celeron-display (length number)
537 "Return a string displaying a celeron as things happen.
538 LENGTH is the amount of display that has been used. NUMBER
539 is t to display the done string, or the number to display."
541 (working-frame-animation-display length [ "[" "]" ]
542 working-celeron-strings))
543 ;; All the % signs because it then gets passed to message.
544 (t (working-frame-animation-display length number
545 working-celeron-strings))))
547 (defvar working-bounce-strings
561 "Strings for the bounce animation.")
563 (defun working-bounce-display (length number)
564 "Return a string displaying a celeron as things happen.
565 LENGTH is the amount of display that has been used. NUMBER
566 is t to display the done string, or the number to display."
568 (working-frame-animation-display length [ "[" "]" ]
569 working-bounce-strings))
570 ;; All the % signs because it then gets passed to message.
571 (t (working-frame-animation-display length number
572 working-bounce-strings))))
574 ;;; Some edebug hooks
579 (def-edebug-spec working-status-forms (form form def-body))
580 (def-edebug-spec working-status-timeout (form form form def-body))))
582 ;;; Example function using `working'
584 (defun working-verify-parenthesis-a ()
585 "Verify all the parenthesis in an elisp program buffer."
588 (goto-char (point-min))
589 (working-status-forms "Scanning" "done"
591 ;; Use default buffer position.
596 (working-status t))))
598 (defun working-verify-parenthesis-b ()
599 "Verify all the parenthesis in an elisp program buffer."
602 (goto-char (point-min))
603 (working-status-forms "Scanning" "done"
605 ;; Use default buffer position.
606 (working-dynamic-status nil)
610 (working-dynamic-status t))))
612 (defun working-wait-for-keypress ()
613 "Display funny graphics while waiting for a keypress."
615 (working-status-timeout .1 "Press a key" "done"
616 (while (sit-for 10))))
618 (defun working-verify-sleep ()
619 "Display funny graphics while waiting for sleep to sleep."
621 (working-status-call-process .1 "Zzzzz" "Snort" "sleep" nil nil nil "5"))
623 (defun working-verify-mode-line ()
624 "Display graphics in the mode-line for timeout."
626 (let ((working-use-echo-area-p nil))
627 (message "Pres a Key")
628 (working-status-timeout .1 "" ""
629 (while (sit-for 10)))
634 ;;; working.el ends here