| blob | e839bc3a92323f8acc5b9dba41d858dc2394b5bb |
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$||
16 ;;; $Id$
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.
22 ;;;
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.
27 ;;;
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.
33 ;;; Commentary:
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 ;;; This package was inspired by Roland McGrath's hanoi-break.el.
46 ;;; Thanks to both Roland McGrath <roland@gnu.ai.mit.edu> and Mark Ashton
47 ;;; <mpashton@gnu.ai.mit.edu> for feedback and ideas.
49 ;;; Code:
51 \f
54 ;; Make this nil initially so that the call to type-break-mode at the end
55 ;; will cause scheduling and so forth to happen.
56 ;;;###autoload
58 "*Non-`nil' means typing break mode is enabled.
61 ;;;###autoload
65 ;;;###autoload
67 "*Number of seconds of idle time considered to be an adequate typing rest.
69 When this variable is non-`nil', emacs checks the idle time between
71 rest from typing, then the next typing break is simply rescheduled for later.
73 If a break is interrupted before this much time elapses, the user will be
76 ;;;###autoload
78 ;; Assuming typing speed is 35wpm (on the average, do you really
79 ;; type more than that in a minute? I spend a lot of time reading mail
80 ;; and simply studying code in buffers) and average word length is
81 ;; about 5 letters, default upper threshold to the average number of
82 ;; keystrokes one is likely to type in a break interval. That way if the
83 ;; user goes through a furious burst of typing activity, cause a typing
84 ;; break to be required sooner than originally scheduled.
85 ;; Conversely, the minimum threshold should be about a fifth of this.
91 "*Upper and lower bound on number of keystrokes for considering typing break.
92 This structure is a pair of numbers.
94 The first number is the minimum number of keystrokes that must have been
95 entered since the last typing break before considering another one, even if
96 the scheduled time has elapsed; the break is simply rescheduled until later
97 if the minimum threshold hasn't been reached. If this first value is nil,
98 then there is no minimum threshold; as soon as the scheduled time has
99 elapsed, the user will always be queried.
101 The second number is the maximum number of keystrokes that can be entered
102 before a typing break is requested immediately, pre-empting the originally
103 scheduled break. If this second value is nil, then no pre-emptive breaks
104 will occur; only scheduled ones will.
106 Keys with bucky bits (shift, control, meta, etc) are counted as only one
110 "*List of time intervals for warnings about upcoming typing break.
111 At each of the intervals (specified in seconds) away from a scheduled
115 "*List of keystroke measurements for warnings about upcoming typing break.
116 At each of the intervals (specified in keystrokes) away from the upper
117 keystroke threshold, print a warning in the echo area.
118 If either this variable or the upper threshold is set, then no warnings
122 "*Number of seconds between queries to take a break, if put off.
123 The user will continue to be prompted at this interval until he or she
127 "*Number of keystrokes for which warnings should be repeated.
128 That is, for each of this many keystrokes the warning is redisplayed
132 "Function to use for making query for a typing break.
133 It should take a string as an argument, the prompt.
138 "*List of functions to consider running as demos during typing breaks.
139 When a typing break begins, one of these functions is selected randomly
140 to have emacs do something interesting.
142 Any function in this list should start a demo which ceases as soon as a
148 ;; These are internal variables. Do not set them yourself.
160 \f
161 ;;;###autoload
163 "Enable or disable typing-break mode.
164 This is a minor mode, but it is global to all buffers by default.
166 When this mode is enabled, the user is encouraged to take typing breaks at
167 appropriate intervals; either after a specified amount of time or when the
168 user has exceeded a keystroke threshold. When the time arrives, the user
169 is asked to take a break. If the user refuses at that time, emacs will ask
170 again in a short period of time. The idea is to give the user enough time
171 to find a good breaking point in his or her work, but be sufficiently
172 annoying to discourage putting typing breaks off indefinitely.
174 A negative prefix argument disables this mode.
175 No argument or any non-negative argument enables it.
177 The user may enable or disable this mode by setting the variable of the
178 same name, though setting it in that way doesn't reschedule a break or
179 reset the keystroke counter.
181 If the mode was previously disabled and is enabled as a consequence of
182 calling this function, it schedules a break with `type-break-schedule' to
183 make sure one occurs (the user can call that command to reschedule the
184 break at any time). It also initializes the keystroke counter.
186 The variable `type-break-interval' specifies the number of seconds to
187 schedule between regular typing breaks. This variable doesn't directly
188 affect the time schedule; it simply provides a default for the
189 `type-break-schedule' command.
191 If set, the variable `type-break-good-rest-interval' specifies the minimum
192 amount of time which is considered a reasonable typing break. Whenever
193 that time has elapsed, typing breaks are automatically rescheduled for
194 later even if emacs didn't prompt you to take one first. Also, if a break
195 is ended before this much time has elapsed, the user will be asked whether
196 or not to continue.
198 The variable `type-break-keystroke-threshold' is used to determine the
199 thresholds at which typing breaks should be considered. You can use
200 the command `type-break-guestimate-keystroke-threshold' to try to
201 approximate good values for this.
203 Finally, the command `type-break-statistics' prints interesting things."
205 ;; make sure it's there.
223 type-break-mode)
225 ;;;###autoload
227 "Take a typing break.
229 During the break, a demo selected from the functions listed in
230 `type-break-demo-functions' is run.
232 After the typing break is finished, the next break is scheduled
233 as per the function `type-break-schedule'."
241 ;; Eat the screen.
263 ;; Don't be pedantic; if user's rest was only a minute short,
264 ;; why bother?
268 type-break-query-function
271 break-secs)))))
279 \f
281 "Schedule a typing break for TIME seconds from now.
282 If time is not specified, default to `type-break-interval'."
306 type-break-time-warning-intervals))
310 type-break-time-next-break)))
332 type-break-time-warning-intervals))
342 \f
348 "Ask to take a typing break if appropriate.
349 This may be the case either because the scheduled time has come \(and the
350 minimum keystroke threshold has been reached\) or because the maximum
351 keystroke threshold has been exceeded."
358 type-break-good-rest-interval)
369 ;; This has been optimized for speed; calls to input-pending-p and
370 ;; checking for the minibuffer window are only done if it would
371 ;; matter for the sake of querying user.
381 ;; If keystroke count is within min-threshold of
382 ;; max-threshold, lower it to reduce the liklihood of an
383 ;; immediate subsequent query.
385 min-threshold
392 max-threshold
403 ;; This should return t if warnings were enabled, nil otherwise.
406 type-break-keystroke-count)))
409 nil)
411 nil)
419 t))))
440 ;; Pause for a moment so previous messages can be seen.
445 type-break-time-next-break)))
460 type-break-keystroke-count))
467 \f
468 ;;;###autoload
470 "Print statistics about typing breaks in a temporary buffer.
471 This includes the last time a typing break was taken, when the next one is
472 scheduled, the keystroke thresholds and the current keystroke count, etc."
476 Last typing break : %s
478 Minimum keystroke threshold : %s
479 Maximum keystroke threshold : %s
480 Current keystroke count : %s"
490 type-break-time-next-break)))
494 type-break-keystroke-count))))
496 ;;;###autoload
498 "Guess values for the minimum/maximum keystroke threshold for typing breaks.
499 If called interactively, the user is prompted for their guess as to how
500 many words per minute they usually type. From that, the command sets the
501 values in `type-break-keystroke-threshold' based on a fairly simple
502 algorithm involving assumptions about the average length of words (5).
503 For the minimum threshold, it uses about a quarter of the computed maximum
504 threshold.
506 When called from lisp programs, the optional args WORDLEN and FRAC can be
507 used to override the default assumption about average word length and the
508 fraction of the maximum threshold to which to set the minimum threshold.
509 FRAC should be the inverse of the fractional value; for example, a value of
510 2 would mean to use one half, a value of 4 would mean to use one quarter, etc."
520 type-break-keystroke-threshold)))
522 \f
523 ;;; misc functions
525 ;; Compute the difference, in seconds, between a and b, two structures
526 ;; similar to those returned by `current-time'.
527 ;; Use addition rather than logand since that is more robust; the low 16
528 ;; bits of the seconds might have been incremented, making it more than 16
529 ;; bits wide.
534 ;; Return (in a new list the same in structure to that returned by
535 ;; `current-time') the sum of the arguments. Each argument may be a time
536 ;; list or a single integer, a number of seconds.
537 ;; This function keeps the high and low 16 bits of the seconds properly
538 ;; balanced so that the lower value never exceeds 16 bits. Otherwise, when
539 ;; the result is passed to `current-time-string' it will toss some of the
540 ;; "low" bits and return the wrong value.
545 tem)
583 type-break-keystroke-warning-intervals)
586 \f
587 ;;; Demo wrappers
589 ;; This is a wrapper around hanoi that calls it with an arg large enough to
590 ;; make the largest discs possible that will fit in the window.
591 ;; Also, clean up the *Hanoi* buffer after we're done.
593 "Take a hanoiing typing break."
599 ;; Wait for user to come back.
603 ;; eat char
608 ;; This is a wrapper around life that calls it with a `sleep' arg to make
609 ;; it run a little more leisurely.
610 ;; Also, clean up the *Life* buffer after we're done.
612 "Take a typing break and get a life."
621 ;; wait for user to return
627 ;; restart demo
633 ;; Boring demo, but doesn't use many cycles
635 "Boring typing break demo."
638 line col pos
639 elapsed timeleft tmsg)
649 rmsg)
659 type-break-time-last-break
682 \f
685 ;; Do not do this at load time because it makes it impossible to load this
686 ;; file into temacs and then dump it.
687 ;(type-break-mode t)
689 ;; local variables:
690 ;; vc-make-backup-files: t
691 ;; end:
693 ;;; type-break.el ends here