| blob | 690f0842a3934fc6d3816aef34befa1a712f1461 |
1 ;;; type-break.el --- encourage rests from typing at appropriate intervals
3 ;; Copyright (C) 1994 Free Software Foundation, Inc.
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
10 ;; $Id$
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software; you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation; either version 2, or (at your option)
17 ;; any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs; see the file COPYING. If not, write to
26 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
28 ;;; Commentary:
30 ;;; The docstring for the function `type-break-mode' summarizes most of the
31 ;;; details of the interface.
33 ;;; This package relies on the assumption that you live entirely in emacs,
34 ;;; as the author does. If that's not the case for you (e.g. you often
35 ;;; suspend emacs or work in other windows) then this won't help very much;
36 ;;; it will depend on just how often you switch back to emacs. At the very
37 ;;; least, you will want to turn off the keystroke thresholds and rest
38 ;;; interval tracking.
40 ;;; This package was inspired by Roland McGrath's hanoi-break.el.
41 ;;; Thanks to both Roland McGrath <roland@gnu.ai.mit.edu> and Mark Ashton
42 ;;; <mpashton@gnu.ai.mit.edu> for feedback and ideas.
44 ;;; Code:
46 \f
49 ;; Make this nil initially so that the call to type-break-mode at the end
50 ;; will cause scheduling and so forth to happen.
51 ;;;###autoload
53 "*Non-`nil' means typing break mode is enabled.
56 ;;;###autoload
60 ;;;###autoload
62 "*Number of seconds of idle time considered to be an adequate typing rest.
64 When this variable is non-`nil', emacs checks the idle time between
66 rest from typing, then the next typing break is simply rescheduled for later.
68 If a break is interrupted before this much time elapses, the user will be
71 ;;;###autoload
73 ;; Assuming typing speed is 35wpm (on the average, do you really
74 ;; type more than that in a minute? I spend a lot of time reading mail
75 ;; and simply studying code in buffers) and average word length is
76 ;; about 5 letters, default upper threshold to the average number of
77 ;; keystrokes one is likely to type in a break interval. That way if the
78 ;; user goes through a furious burst of typing activity, cause a typing
79 ;; break to be required sooner than originally scheduled.
80 ;; Conversely, the minimum threshold should be about a fifth of this.
86 "*Upper and lower bound on number of keystrokes for considering typing break.
87 This structure is a pair of numbers.
89 The first number is the minimum number of keystrokes that must have been
90 entered since the last typing break before considering another one, even if
91 the scheduled time has elapsed; the break is simply rescheduled until later
92 if the minimum threshold hasn't been reached. If this first value is nil,
93 then there is no minimum threshold; as soon as the scheduled time has
94 elapsed, the user will always be queried.
96 The second number is the maximum number of keystrokes that can be entered
97 before a typing break is requested immediately, pre-empting the originally
98 scheduled break. If this second value is nil, then no pre-emptive breaks
99 will occur; only scheduled ones will.
101 Keys with bucky bits (shift, control, meta, etc) are counted as only one
105 "*List of time intervals for warnings about upcoming typing break.
106 At each of the intervals (specified in seconds) away from a scheduled
110 "*List of keystroke measurements for warnings about upcoming typing break.
111 At each of the intervals (specified in keystrokes) away from the upper
112 keystroke threshold, print a warning in the echo area.
113 If either this variable or the upper threshold is set, then no warnings
117 "*Number of seconds between queries to take a break, if put off.
118 The user will continue to be prompted at this interval until he or she
122 "*Number of keystrokes for which warnings should be repeated.
123 That is, for each of this many keystrokes the warning is redisplayed
127 "Function to use for making query for a typing break.
128 It should take a string as an argument, the prompt.
133 "*List of functions to consider running as demos during typing breaks.
134 When a typing break begins, one of these functions is selected randomly
135 to have emacs do something interesting.
137 Any function in this list should start a demo which ceases as soon as a
143 ;; These are internal variables. Do not set them yourself.
155 \f
156 ;;;###autoload
158 "Enable or disable typing-break mode.
159 This is a minor mode, but it is global to all buffers by default.
161 When this mode is enabled, the user is encouraged to take typing breaks at
162 appropriate intervals; either after a specified amount of time or when the
163 user has exceeded a keystroke threshold. When the time arrives, the user
164 is asked to take a break. If the user refuses at that time, emacs will ask
165 again in a short period of time. The idea is to give the user enough time
166 to find a good breaking point in his or her work, but be sufficiently
167 annoying to discourage putting typing breaks off indefinitely.
169 A negative prefix argument disables this mode.
170 No argument or any non-negative argument enables it.
172 The user may enable or disable this mode by setting the variable of the
173 same name, though setting it in that way doesn't reschedule a break or
174 reset the keystroke counter.
176 If the mode was previously disabled and is enabled as a consequence of
177 calling this function, it schedules a break with `type-break-schedule' to
178 make sure one occurs (the user can call that command to reschedule the
179 break at any time). It also initializes the keystroke counter.
181 The variable `type-break-interval' specifies the number of seconds to
182 schedule between regular typing breaks. This variable doesn't directly
183 affect the time schedule; it simply provides a default for the
184 `type-break-schedule' command.
186 If set, the variable `type-break-good-rest-interval' specifies the minimum
187 amount of time which is considered a reasonable typing break. Whenever
188 that time has elapsed, typing breaks are automatically rescheduled for
189 later even if emacs didn't prompt you to take one first. Also, if a break
190 is ended before this much time has elapsed, the user will be asked whether
191 or not to continue.
193 The variable `type-break-keystroke-threshold' is used to determine the
194 thresholds at which typing breaks should be considered. You can use
195 the command `type-break-guestimate-keystroke-threshold' to try to
196 approximate good values for this.
198 Finally, the command `type-break-statistics' prints interesting things."
200 ;; make sure it's there.
218 type-break-mode)
220 ;;;###autoload
222 "Take a typing break.
224 During the break, a demo selected from the functions listed in
225 `type-break-demo-functions' is run.
227 After the typing break is finished, the next break is scheduled
228 as per the function `type-break-schedule'."
236 ;; Eat the screen.
258 ;; Don't be pedantic; if user's rest was only a minute short,
259 ;; why bother?
263 type-break-query-function
266 break-secs)))))
274 \f
276 "Schedule a typing break for TIME seconds from now.
277 If time is not specified, default to `type-break-interval'."
301 type-break-time-warning-intervals))
305 type-break-time-next-break)))
327 type-break-time-warning-intervals))
337 \f
343 "Ask to take a typing break if appropriate.
344 This may be the case either because the scheduled time has come \(and the
345 minimum keystroke threshold has been reached\) or because the maximum
346 keystroke threshold has been exceeded."
353 type-break-good-rest-interval)
364 ;; This has been optimized for speed; calls to input-pending-p and
365 ;; checking for the minibuffer window are only done if it would
366 ;; matter for the sake of querying user.
376 ;; If keystroke count is within min-threshold of
377 ;; max-threshold, lower it to reduce the liklihood of an
378 ;; immediate subsequent query.
380 min-threshold
387 max-threshold
398 ;; This should return t if warnings were enabled, nil otherwise.
401 type-break-keystroke-count)))
404 nil)
406 nil)
414 t))))
435 ;; Pause for a moment so previous messages can be seen.
440 type-break-time-next-break)))
455 type-break-keystroke-count))
462 \f
463 ;;;###autoload
465 "Print statistics about typing breaks in a temporary buffer.
466 This includes the last time a typing break was taken, when the next one is
467 scheduled, the keystroke thresholds and the current keystroke count, etc."
471 Last typing break : %s
473 Minimum keystroke threshold : %s
474 Maximum keystroke threshold : %s
475 Current keystroke count : %s"
485 type-break-time-next-break)))
489 type-break-keystroke-count))))
491 ;;;###autoload
493 "Guess values for the minimum/maximum keystroke threshold for typing breaks.
494 If called interactively, the user is prompted for their guess as to how
495 many words per minute they usually type. From that, the command sets the
496 values in `type-break-keystroke-threshold' based on a fairly simple
497 algorithm involving assumptions about the average length of words (5).
498 For the minimum threshold, it uses about a quarter of the computed maximum
499 threshold.
501 When called from lisp programs, the optional args WORDLEN and FRAC can be
502 used to override the default assumption about average word length and the
503 fraction of the maximum threshold to which to set the minimum threshold.
504 FRAC should be the inverse of the fractional value; for example, a value of
505 2 would mean to use one half, a value of 4 would mean to use one quarter, etc."
515 type-break-keystroke-threshold)))
517 \f
518 ;;; misc functions
520 ;; Compute the difference, in seconds, between a and b, two structures
521 ;; similar to those returned by `current-time'.
522 ;; Use addition rather than logand since that is more robust; the low 16
523 ;; bits of the seconds might have been incremented, making it more than 16
524 ;; bits wide.
529 ;; Return (in a new list the same in structure to that returned by
530 ;; `current-time') the sum of the arguments. Each argument may be a time
531 ;; list or a single integer, a number of seconds.
532 ;; This function keeps the high and low 16 bits of the seconds properly
533 ;; balanced so that the lower value never exceeds 16 bits. Otherwise, when
534 ;; the result is passed to `current-time-string' it will toss some of the
535 ;; "low" bits and return the wrong value.
540 tem)
578 type-break-keystroke-warning-intervals)
581 \f
582 ;;; Demo wrappers
584 ;; This is a wrapper around hanoi that calls it with an arg large enough to
585 ;; make the largest discs possible that will fit in the window.
586 ;; Also, clean up the *Hanoi* buffer after we're done.
588 "Take a hanoiing typing break."
594 ;; Wait for user to come back.
598 ;; eat char
603 ;; This is a wrapper around life that calls it with a `sleep' arg to make
604 ;; it run a little more leisurely.
605 ;; Also, clean up the *Life* buffer after we're done.
607 "Take a typing break and get a life."
616 ;; wait for user to return
622 ;; restart demo
628 ;; Boring demo, but doesn't use many cycles
630 "Boring typing break demo."
633 line col pos
634 elapsed timeleft tmsg)
644 rmsg)
654 type-break-time-last-break
677 \f
680 ;; Do not do this at load time because it makes it impossible to load this
681 ;; file into temacs and then dump it.
682 ;(type-break-mode t)
684 ;; local variables:
685 ;; vc-make-backup-files: t
686 ;; end:
688 ;;; type-break.el ends here