1 ;;; type-break.el --- encourage rests from typing at appropriate intervals
3 ;;; Copyright (C) 1994 Noah S. Friedman
5 ;;; Author: Noah Friedman <friedman@prep.ai.mit.edu>
6 ;;; Maintainer: friedman@prep.ai.mit.edu
7 ;;; Keywords: extensions, timers
8 ;;; Status: known to work in GNU Emacs 19.25 or later.
9 ;;; Created: 1994-07-13
11 ;;; LCD Archive Entry:
12 ;;; type-break|Noah Friedman|friedman@prep.ai.mit.edu|
13 ;;; encourage rests from typing at appropriate intervals|
14 ;;; $Date$|$Revision$||
18 ;;; This program is free software; you can redistribute it and/or modify
19 ;;; it under the terms of the GNU General Public License as published by
20 ;;; the Free Software Foundation; either version 2, or (at your option)
21 ;;; any later version.
23 ;;; This program is distributed in the hope that it will be useful,
24 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
25 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 ;;; GNU General Public License for more details.
28 ;;; You should have received a copy of the GNU General Public License
29 ;;; along with this program; if not, you can either send email to this
30 ;;; program's maintainer or write to: The Free Software Foundation,
31 ;;; Inc.; 675 Massachusetts Avenue; Cambridge, MA 02139, USA.
35 ;;; The docstring for the function `type-break-mode' summarizes most of the
36 ;;; details of the interface.
38 ;;; This package relies on the assumption that you live entirely in emacs,
39 ;;; as the author does. If that's not the case for you (e.g. you often
40 ;;; suspend emacs or work in other windows) then this won't help very much;
41 ;;; it will depend on just how often you switch back to emacs. At the very
42 ;;; least, you will want to turn off the keystroke thresholds and rest
43 ;;; interval tracking.
45 ;;; Setting type-break-good-rest-interval makes emacs cons like a maniac
46 ;;; because of repeated calls to `current-time'. There's not really any
47 ;;; good way to avoid this without disabling the variable.
49 ;;; This package was inspired by Roland McGrath's hanoi-break.el.
56 ;; Make this nil initially so that the call to type-break-mode at the end
57 ;; will cause scheduling and so forth to happen.
59 (defvar type-break-mode nil
60 "*Non-`nil' means typing break mode is enabled.
61 See the docstring for the `type-break-mode' command for more information.")
64 (defvar type-break-interval (* 60 60)
65 "*Number of seconds between scheduled typing breaks.")
68 (defvar type-break-good-rest-interval (/ type-break-interval 6)
69 "*Number of seconds of idle time considered to be an adequate typing rest.
71 When this variable is non-`nil', emacs checks the idle time between
72 keystrokes. If this idle time is long enough to be considered a "good"
73 rest from typing, then the next typing break is simply rescheduled for later.
75 The user will also be admonished if a forced break isn't at least as long
76 as this time, to remind them to rest longer next time.")
79 (defvar type-break-query-interval 60
80 "*Number of seconds between queries to take a break, if put off.
81 The user will continue to be prompted at this interval until he or she
82 finally submits to taking a typing break.")
85 (defvar type-break-keystroke-threshold
86 ;; Assuming average typing speed is 45wpm and the average word length is
87 ;; about 5 letters, default upper threshold to the average number of
88 ;; keystrokes one is likely to type in a break interval. That way if the
89 ;; user goes through a furious burst of typing activity, cause a typing
90 ;; break to be required sooner than originally scheduled.
91 ;; Conversely, the minimum threshold should be about a quarter of this.
94 (upper (* wpm avg-word-length (/ type-break-interval 60)))
97 "*Upper and lower bound on number of keystrokes for considering typing break.
98 This structure is a pair of numbers.
100 The first number is the minimum number of keystrokes that must have been
101 entered since the last typing break before considering another one, even if
102 the scheduled time has elapsed; the break is simply rescheduled until later
103 if the minimum threshold hasn't been reached. If this first value is nil,
104 then there is no minimum threshold; as soon as the scheduled time has
105 elapsed, the user will always be queried.
107 The second number is the maximum number of keystrokes that can be entered
108 before a typing break is requested immediately, pre-empting the originally
109 scheduled break. If this second value is nil, then no pre-emptive breaks
110 will occur; only scheduled ones will.
112 Keys with bucky bits (shift, control, meta, etc) are counted as only one
113 keystroke even though they really require multiple keys to generate them.")
116 (defvar type-break-query-function 'yes-or-no-p
117 "*Function to use for making query for a typing break.
118 It should take a string as an argument, the prompt.
119 Usually this should be set to `yes-or-no-p' or `y-or-n-p'.")
121 (defvar type-break-demo-function-vector
122 [type-break-demo-life type-break-demo-hanoi]
123 "*Vector consisting of functions to run as demos during typing breaks.
124 When a typing break begins, one of these functions is selected randomly
125 to have emacs do something interesting.
127 Any function in this vector should start a demo which ceases as soon as a
130 ;; These are internal variables. Do not set them yourself.
132 ;; Non-nil when a scheduled typing break is due.
133 (defvar type-break-alarm-p nil)
135 (defvar type-break-keystroke-count 0)
137 (defvar type-break-time-last-break nil)
138 (defvar type-break-time-next-break nil)
139 (defvar type-break-time-last-command (current-time))
142 ;; Compute the difference, in seconds, between a and b, two structures
143 ;; similar to those returned by `current-time'.
144 ;; Use addition rather than logand since I found it convenient to add
145 ;; seconds to the cdr of some of my stored time values, which may throw off
146 ;; the number of bits in the cdr.
147 (defsubst type-break-time-difference (a b)
148 (+ (lsh (- (car b) (car a)) 16)
149 (- (car (cdr b)) (car (cdr a)))))
152 (defun type-break-mode (&optional prefix)
153 "Enable or disable typing-break mode.
154 This is a minor mode, but it is global to all buffers by default.
156 When this mode is enabled, the user is encouraged to take typing breaks at
157 appropriate intervals; either after a specified amount of time or when the
158 user has exceeded a keystroke threshold. When the time arrives, the user
159 is asked to take a break. If the user refuses at that time, emacs will ask
160 again in a short period of time. The idea is to give the user enough time
161 to find a good breaking point in his or her work, but be sufficiently
162 annoying to discourage putting typing breaks off indefinitely.
164 Calling this command with no prefix argument toggles this mode.
165 A negative prefix argument disables this mode.
166 A non-negative prefix argument or any other non-`nil' argument enables it.
168 The user may enable or disable this mode by setting the variable of the
169 same name, though setting it in that way doesn't reschedule a break or
170 reset the keystroke counter.
172 If the mode was previously disabled and is enabled as a consequence of
173 calling this function, it schedules a break with `type-break-schedule' to
174 make sure one occurs (the user can call that command to reschedule the
175 break at any time). It also initializes the keystroke counter.
177 The variable `type-break-interval' specifies the number of seconds to
178 schedule between regular typing breaks. This variable doesn't directly
179 affect the time schedule; it simply provides a default for the
180 `type-break-schedule' command.
182 The variable `type-break-query-interval' specifies the number of seconds to
183 schedule between repeated queries for breaks when the user answers \"no\"
184 to the previous query.
186 The variable `type-break-good-rest-interval' specifies the minimum amount
187 of time which is considered a reasonable typing break. Whenever that time
188 has elapsed, typing breaks are automatically rescheduled for later even if
189 emacs didn't prompt you to take one first. You can disable this behavior.
191 The variable `type-break-keystroke-threshold' is used to determine the
192 thresholds at which typing breaks should be considered. You can use
193 the command `type-break-guestimate-keystroke-threshold' to try to
194 approximate good values for this.
196 The variable `type-break-query-function' should contain a function (or the
197 symbolic name of a function) to be used to query the user for typing
200 Finally, the command `type-break-statistics' prints interesting things."
202 ;; make sure it's there.
203 (add-hook 'post-command-hook 'type-break-check 'append)
205 (let ((already-enabled type-break-mode))
208 (setq type-break-mode (not type-break-mode)))
209 ((numberp (prefix-numeric-value prefix))
210 (setq type-break-mode (>= (prefix-numeric-value prefix) 0)))
212 (setq type-break-mode t))
214 (setq type-break-mode nil)))
217 ((and already-enabled type-break-mode)
219 (message "type-break-mode was already enabled")))
221 (setq type-break-keystroke-count 0)
222 (type-break-schedule)
224 (message "type-break-mode is enabled and reset")))
226 (message "type-break-mode is disabled"))))
231 "Take a typing break.
233 During the break, a demo selected from the functions listed in
234 `type-break-demo-function-vector' is run.
236 After the typing break is finished, the next break is scheduled
237 as per the function `type-break-schedule', and the keystroke counter is
240 (setq type-break-time-last-break (current-time))
241 (save-window-excursion
243 (and (eq (selected-window) (minibuffer-window))
245 (delete-other-windows)
246 (scroll-right (window-width))
247 (message "Press any key to resume from typing break.")
250 (let* ((len (length type-break-demo-function-vector))
252 (fn (aref type-break-demo-function-vector idx)))
257 (and type-break-good-rest-interval
258 (< (type-break-time-difference type-break-time-last-command
260 type-break-good-rest-interval)
261 (message "That typing break wasn't really long enough. Rest more next time."))
263 (setq type-break-keystroke-count 0)
264 (type-break-schedule))
268 (defun type-break-schedule (&optional time)
269 "Schedule a typing break for TIME seconds from now.
270 If time is not specified, default to `type-break-interval'."
271 (interactive (list (and current-prefix-arg
272 (prefix-numeric-value current-prefix-arg))))
273 (or time (setq time type-break-interval))
274 ;; Remove any old scheduled break
275 (type-break-cancel-schedule)
276 (run-at-time time nil 'type-break-alarm)
278 (setq type-break-time-next-break (current-time))
279 (setcar (cdr type-break-time-next-break)
280 (+ time (car (cdr type-break-time-next-break)))))
282 (defun type-break-cancel-schedule ()
283 "Cancel scheduled typing breaks.
284 This does not prevent queries for typing breaks when the keystroke
285 threshold has been reached; to turn off typing breaks altogether, turn off
288 (let ((timer-dont-exit t))
289 (cancel-function-timers 'type-break-alarm))
290 (setq type-break-alarm-p nil)
291 (setq type-break-time-next-break nil))
293 (defun type-break-alarm ()
294 "This function is run when a scheduled typing break is due."
295 (setq type-break-alarm-p t))
297 (defun type-break-check ()
298 "Ask to take a typing break if appropriate.
299 This may be the case either because the scheduled time has come \(and the
300 minimum keystroke threshold has been reached\) or because the maximum
301 keystroke threshold has been exceeded."
304 (let* ((threshold-pair (and (consp type-break-keystroke-threshold)
305 type-break-keystroke-threshold))
306 (min-threshold (car threshold-pair))
307 (max-threshold (cdr threshold-pair)))
309 ;; Reset schedule and keystroke count if user has been idle longer
310 ;; than a normal resting period.
312 (type-break-good-rest-interval
313 (and (> (type-break-time-difference type-break-time-last-command
315 type-break-good-rest-interval)
317 (setq type-break-keystroke-count 0)
318 (type-break-schedule)))
319 (setq type-break-time-last-command (current-time))))
322 (setq type-break-keystroke-count
323 (+ type-break-keystroke-count (length (this-command-keys)))))
330 (< type-break-keystroke-count min-threshold)))
332 ;; If the keystroke count is within min-threshold characters of
333 ;; the maximum threshold, set the count to min-threshold. That
334 ;; way, if the count was really close the threshold and the user
335 ;; doesn't choose to take a break now, s/he won't be pestered
336 ;; almost immediately after saying "no"; that's what the query
337 ;; interval delay is for.
338 ;; On the other hand, don't set it too small (make it at least
339 ;; min-threshold); that way we can be sure the user will be asked
340 ;; again to take a break after the query interval has elapsed.
341 ;; If the user chooses to take a break now, the break function
342 ;; will reset the keystroke count anyway.
345 (< (- max-threshold type-break-keystroke-count) min-threshold)
346 (setq type-break-keystroke-count min-threshold))
347 (type-break-query))))
349 (> type-break-keystroke-count max-threshold))
350 ;; Set it to the min threshold if possible, to be sure the user
351 ;; will be pestered again in at least a minute.
352 (setq type-break-keystroke-count (or min-threshold 0))
353 (type-break-query)))))))
355 (defun type-break-query ()
358 ((funcall type-break-query-function "Take a break from typing now? ")
361 (type-break-schedule type-break-query-interval)))
363 (type-break-schedule type-break-query-interval))))
366 ;; This is a wrapper around hanoi that calls it with an arg large enough to
367 ;; make the largest discs possible that will fit in the window.
368 ;; Also, clean up the *Hanoi* buffer after we're done.
369 (defun type-break-demo-hanoi ()
370 "Take a hanoiing typing break."
371 (and (get-buffer "*Hanoi*")
372 (kill-buffer "*Hanoi*"))
375 (hanoi (/ (window-width) 8))
376 ;; Wait for user to come back.
378 (kill-buffer "*Hanoi*"))
382 (and (get-buffer "*Hanoi*")
383 (kill-buffer "*Hanoi*")))))
385 ;; This is a wrapper around life that calls it with a `sleep' arg to make
386 ;; it run a little more leisurely.
387 ;; Also, clean up the *Life* buffer after we're done.
388 (defun type-break-demo-life ()
389 "Take a typing break and get a life."
390 (and (get-buffer "*Life*")
391 (kill-buffer "*Life*"))
395 ;; Wait for user to come back.
397 (kill-buffer "*Life*"))
399 (and (get-buffer "*Life*")
400 (kill-buffer "*Life*")))))
404 (defun type-break-statistics ()
405 "Print statistics about typing breaks in a temporary buffer.
406 This includes the last time a typing break was taken, when the next one is
407 scheduled, the keystroke thresholds and the current keystroke count, etc."
409 (with-output-to-temp-buffer "*Typing Break Statistics*"
410 (princ (format "Typing break statistics\n-----------------------\n
411 Last typing break : %s
412 Next scheduled typing break : %s\n
413 Minimum keystroke threshold : %s
414 Maximum keystroke threshold : %s
415 Current keystroke count : %s"
416 (if type-break-time-last-break
417 (current-time-string type-break-time-last-break)
419 (if (and type-break-mode type-break-time-next-break)
420 (format "%s\t(%s from now)"
421 (current-time-string type-break-time-next-break)
422 (let* ((secs (type-break-time-difference
424 type-break-time-next-break))
427 (format "%d minutes" mins)
428 (format "%d seconds" secs))))
430 (or (car type-break-keystroke-threshold) "none")
431 (or (cdr type-break-keystroke-threshold) "none")
432 type-break-keystroke-count))))
435 (defun type-break-guestimate-keystroke-threshold (wpm &optional wordlen frac)
436 "Guess values for the minimum/maximum keystroke threshold for typing breaks.
437 If called interactively, the user is prompted for their guess as to how
438 many words per minute they usually type. From that, the command sets the
439 values in `type-break-keystroke-threshold' based on a fairly simple
440 algorithm involving assumptions about the average length of words (5).
441 For the minimum threshold, it uses about a quarter of the computed maximum
444 When called from lisp programs, the optional args WORDLEN and FRAC can be
445 used to override the default assumption about average word length and the
446 fraction of the maximum threshold to which to set the minimum threshold.
447 FRAC should be the inverse of the fractional value; for example, a value of
448 2 would mean to use one half, a value of 4 would mean to use one quarter, etc."
449 (interactive "nHow many words per minute do you type? ")
450 (let* ((upper (* wpm (or wordlen 5) (/ type-break-interval 60)))
451 (lower (/ upper (or frac 4))))
452 (or type-break-keystroke-threshold
453 (setq type-break-keystroke-threshold (cons nil nil)))
454 (setcar type-break-keystroke-threshold lower)
455 (setcdr type-break-keystroke-threshold upper)
457 (message "min threshold: %d\tmax threshold: %d" lower upper)
458 type-break-keystroke-threshold)))
461 (provide 'type-break)
465 ;;; type-break.el ends here