1 ;;; org-timer.el --- Timer code for Org mode -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2008-2018 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: https://orgmode.org
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
27 ;; This file implements two types of timers for Org buffers:
29 ;; - A relative timer that counts up (from 0 or a specified offset)
30 ;; - A countdown timer that counts down from a specified time
32 ;; The relative and countdown timers differ in their entry points.
33 ;; Use `org-timer' or `org-timer-start' to start the relative timer,
34 ;; and `org-timer-set-timer' to start the countdown timer.
41 (declare-function org-agenda-error
"org-agenda" ())
43 (defvar org-timer-start-time nil
44 "t=0 for the running timer.")
46 (defvar org-timer-pause-time nil
47 "Time when the timer was paused.")
49 (defvar org-timer-countdown-timer nil
50 "Current countdown timer.
51 This is a timer object if there is an active countdown timer,
52 `paused' if there is a paused countdown timer, and nil
55 (defvar org-timer-countdown-timer-title nil
56 "Title for notification displayed when a countdown finishes.")
58 (defconst org-timer-re
"\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
59 "Regular expression used to match timer stamps.")
61 (defcustom org-timer-format
"%s "
62 "The format to insert the time of the timer.
63 This format must contain one instance of \"%s\" which will be replaced by
64 the value of the timer."
68 (defcustom org-timer-default-timer
"0"
69 "The default timer when a timer is set, in minutes or hh:mm:ss format.
70 When 0, the user is prompted for a value."
73 :package-version
'(Org .
"8.3")
76 (defcustom org-timer-display
'mode-line
77 "Define where running timer is displayed, if at all.
78 When a timer is running, Org can display it in the mode line
79 and/or frame title. Allowed values are:
81 both displays in both mode line and frame title
82 mode-line displays only in mode line (default)
83 frame-title displays only in frame title
84 nil current timer is not displayed"
87 (const :tag
"Mode line" mode-line
)
88 (const :tag
"Frame title" frame-title
)
89 (const :tag
"Both" both
)
90 (const :tag
"None" nil
)))
92 (defvar org-timer-start-hook nil
93 "Hook run after relative timer is started.")
95 (defvar org-timer-stop-hook nil
96 "Hook run before relative or countdown timer is stopped.")
98 (defvar org-timer-pause-hook nil
99 "Hook run before relative or countdown timer is paused.")
101 (defvar org-timer-continue-hook nil
102 "Hook run after relative or countdown timer is continued.")
104 (defvar org-timer-set-hook nil
105 "Hook run after countdown timer is set.")
107 (defvar org-timer-done-hook nil
108 "Hook run after countdown timer reaches zero.")
111 (defun org-timer-start (&optional offset
)
112 "Set the starting time for the relative timer to now.
113 When called with prefix argument OFFSET, prompt the user for an offset time,
114 with the default taken from a timer stamp at point, if any.
115 If OFFSET is a string or an integer, it is directly taken to be the offset
116 without user interaction.
117 When called with a double prefix arg, all timer strings in the active
118 region will be shifted by a specific amount. You will be prompted for
119 the amount, with the default to make the first timer string in
123 ((equal offset
'(16))
124 (call-interactively 'org-timer-change-times-in-region
))
125 (org-timer-countdown-timer
126 (user-error "Countdown timer is running. Cancel first"))
130 (setq org-timer-start-time
(current-time))
132 ((integerp offset
) (setq delta offset
))
133 ((stringp offset
) (setq delta
(org-timer-hms-to-secs offset
)))
135 (setq def
(if (org-in-regexp org-timer-re
)
139 (format "Restart timer with offset [%s]: " def
)))
140 (unless (string-match "\\S-" s
) (setq s def
))
141 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete s
)))))
142 (setq org-timer-start-time
144 ;; Pass `current-time' result to `float-time' (instead
145 ;; of calling without arguments) so that only
146 ;; `current-time' has to be overridden in tests.
147 (- (float-time (current-time)) delta
))))
148 (setq org-timer-pause-time nil
)
149 (org-timer-set-mode-line 'on
)
150 (message "Timer start time set to %s, current value is %s"
151 (format-time-string "%T" org-timer-start-time
)
152 (org-timer-secs-to-hms (or delta
0)))
153 (run-hooks 'org-timer-start-hook
)))))
156 (defun org-timer-pause-or-continue (&optional stop
)
157 "Pause or continue the relative or countdown timer.
158 With prefix arg STOP, stop it entirely."
161 (stop (org-timer-stop))
162 ((not org-timer-start-time
) (error "No timer is running"))
163 (org-timer-pause-time
164 (let ((start-secs (float-time org-timer-start-time
))
165 (pause-secs (float-time org-timer-pause-time
)))
166 (if org-timer-countdown-timer
167 (let ((new-secs (- start-secs pause-secs
)))
168 (setq org-timer-countdown-timer
169 (org-timer--run-countdown-timer
170 new-secs org-timer-countdown-timer-title
))
171 (setq org-timer-start-time
172 (time-add (current-time) (seconds-to-time new-secs
))))
173 (setq org-timer-start-time
174 ;; Pass `current-time' result to `float-time' (instead
175 ;; of calling without arguments) so that only
176 ;; `current-time' has to be overridden in tests.
177 (seconds-to-time (- (float-time (current-time))
178 (- pause-secs start-secs
)))))
179 (setq org-timer-pause-time nil
)
180 (org-timer-set-mode-line 'on
)
181 (run-hooks 'org-timer-continue-hook
)
182 (message "Timer continues at %s" (org-timer-value-string))))
185 (when org-timer-countdown-timer
186 (cancel-timer org-timer-countdown-timer
)
187 (setq org-timer-countdown-timer
'paused
))
188 (run-hooks 'org-timer-pause-hook
)
189 (setq org-timer-pause-time
(current-time))
190 (org-timer-set-mode-line 'paused
)
191 (message "Timer paused at %s" (org-timer-value-string)))))
194 (defun org-timer-stop ()
195 "Stop the relative or countdown timer."
197 (unless org-timer-start-time
198 (user-error "No timer running"))
199 (when (timerp org-timer-countdown-timer
)
200 (cancel-timer org-timer-countdown-timer
))
201 (run-hooks 'org-timer-stop-hook
)
202 (setq org-timer-start-time nil
203 org-timer-pause-time nil
204 org-timer-countdown-timer nil
)
205 (org-timer-set-mode-line 'off
)
206 (message "Timer stopped"))
209 (defun org-timer (&optional restart no-insert
)
210 "Insert a H:MM:SS string from the timer into the buffer.
211 The first time this command is used, the timer is started.
213 When used with a `\\[universal-argument]' prefix, force restarting the timer.
215 When used with a `\\[universal-argument] \\[universal-argument]' \
216 prefix, change all the timer strings
217 in the region by a fixed amount. This can be used to re-calibrate
218 a timer that was not started at the correct moment.
220 If NO-INSERT is non-nil, return the string instead of inserting
223 (if (equal restart
'(16))
224 (org-timer-start restart
)
225 (when (or (equal restart
'(4)) (not org-timer-start-time
))
228 (org-timer-value-string)
229 (insert (org-timer-value-string)))))
231 (defun org-timer-value-string ()
232 "Set the timer string."
233 (format org-timer-format
234 (org-timer-secs-to-hms
235 (abs (floor (org-timer-seconds))))))
237 (defun org-timer-seconds ()
238 ;; Pass `current-time' result to `float-time' (instead of calling
239 ;; without arguments) so that only `current-time' has to be
240 ;; overridden in tests.
241 (if org-timer-countdown-timer
242 (- (float-time org-timer-start-time
)
243 (float-time (or org-timer-pause-time
(current-time))))
244 (- (float-time (or org-timer-pause-time
(current-time)))
245 (float-time org-timer-start-time
))))
248 (defun org-timer-change-times-in-region (beg end delta
)
249 "Change all h:mm:ss time in region by a DELTA."
251 "r\nsEnter time difference like \"-1:08:26\". Default is first time to zero: ")
252 (let ((re "[-+]?[0-9]+:[0-9]\\{2\\}:[0-9]\\{2\\}") p
)
253 (unless (string-match "\\S-" delta
)
256 (when (re-search-forward re end t
)
257 (setq delta
(match-string 0))
258 (if (equal (string-to-char delta
) ?-
)
259 (setq delta
(substring delta
1))
260 (setq delta
(concat "-" delta
))))))
261 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete delta
)))
262 (when (= delta
0) (error "No change"))
265 (while (re-search-backward re beg t
)
269 (org-timer-secs-to-hms (+ (org-timer-hms-to-secs (match-string 0)) delta
)))
274 (defun org-timer-item (&optional arg
)
275 "Insert a description-type item with the current timer value."
277 (let ((itemp (org-in-item-p)) (pos (point)))
279 ;; In a timer list, insert with `org-list-insert-item',
280 ;; then fix the list.
281 ((and itemp
(goto-char itemp
) (org-at-item-timer-p))
282 (let* ((struct (org-list-struct))
283 (prevs (org-list-prevs-alist struct
))
284 (s (concat (org-timer (when arg
'(4)) t
) ":: ")))
285 (setq struct
(org-list-insert-item pos struct prevs nil s
))
286 (org-list-write-struct struct
(org-list-parents-alist struct
))
287 (looking-at org-list-full-item-re
)
288 (goto-char (match-end 0))))
289 ;; In a list of another type, don't break anything: throw an error.
290 (itemp (goto-char pos
) (error "This is not a timer list"))
291 ;; Else, start a new list.
296 (org-timer (when arg
'(4)))
299 (defun org-timer-fix-incomplete (hms)
300 "If hms is a H:MM:SS string with missing hour or hour and minute, fix it."
301 (if (string-match "\\(?:\\([0-9]+:\\)?\\([0-9]+:\\)\\)?\\([0-9]+\\)" hms
)
303 (format "%d:%02d:%02d"
304 (if (match-end 1) (string-to-number (match-string 1 hms
)) 0)
305 (if (match-end 2) (string-to-number (match-string 2 hms
)) 0)
306 (string-to-number (match-string 3 hms
)))
308 (error "Cannot parse HMS string \"%s\"" hms
)))
310 (defun org-timer-hms-to-secs (hms)
311 "Convert h:mm:ss string to an integer time.
312 If the string starts with a minus sign, the integer will be negative."
313 (if (not (string-match
314 "\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
317 (let* ((h (string-to-number (match-string 1 hms
)))
318 (m (string-to-number (match-string 2 hms
)))
319 (s (string-to-number (match-string 3 hms
)))
320 (sign (equal (substring (match-string 1 hms
) 0 1) "-")))
322 (* (if sign -
1 1) (+ s
(* 60 (+ m
(* 60 h
))))))))
324 (defun org-timer-secs-to-hms (s)
325 "Convert integer S into h:mm:ss.
326 If the integer is negative, the string will start with \"-\"."
328 (setq sign
(if (< s
0) "-" "")
330 m
(/ s
60) s
(- s
(* 60 m
))
331 h
(/ m
60) m
(- m
(* 60 h
)))
332 (format "%s%d:%02d:%02d" sign h m s
)))
334 (defvar org-timer-mode-line-timer nil
)
335 (defvar org-timer-mode-line-string nil
)
337 (defun org-timer-set-mode-line (value)
338 "Set the mode-line display for relative or countdown timer.
339 VALUE can be `on', `off', or `paused'."
340 (when (or (eq org-timer-display
'mode-line
)
341 (eq org-timer-display
'both
))
342 (or global-mode-string
(setq global-mode-string
'("")))
343 (or (memq 'org-timer-mode-line-string global-mode-string
)
344 (setq global-mode-string
345 (append global-mode-string
'(org-timer-mode-line-string)))))
346 (when (or (eq org-timer-display
'frame-title
)
347 (eq org-timer-display
'both
))
348 (or (memq 'org-timer-mode-line-string frame-title-format
)
349 (setq frame-title-format
350 (append frame-title-format
'(org-timer-mode-line-string)))))
353 (when org-timer-mode-line-timer
354 (cancel-timer org-timer-mode-line-timer
)
355 (setq org-timer-mode-line-timer nil
))
356 (when (or (eq org-timer-display
'mode-line
)
357 (eq org-timer-display
'both
))
358 (setq global-mode-string
359 (delq 'org-timer-mode-line-string global-mode-string
)))
360 (when (or (eq org-timer-display
'frame-title
)
361 (eq org-timer-display
'both
))
362 (setq frame-title-format
363 (delq 'org-timer-mode-line-string frame-title-format
)))
364 (force-mode-line-update))
366 (when org-timer-mode-line-timer
367 (cancel-timer org-timer-mode-line-timer
)
368 (setq org-timer-mode-line-timer nil
)))
370 (when (or (eq org-timer-display
'mode-line
)
371 (eq org-timer-display
'both
))
372 (or global-mode-string
(setq global-mode-string
'("")))
373 (or (memq 'org-timer-mode-line-string global-mode-string
)
374 (setq global-mode-string
375 (append global-mode-string
'(org-timer-mode-line-string)))))
376 (when (or (eq org-timer-display
'frame-title
)
377 (eq org-timer-display
'both
))
378 (or (memq 'org-timer-mode-line-string frame-title-format
)
379 (setq frame-title-format
380 (append frame-title-format
'(org-timer-mode-line-string)))))
381 (org-timer-update-mode-line)
382 (when org-timer-mode-line-timer
383 (cancel-timer org-timer-mode-line-timer
)
384 (setq org-timer-mode-line-timer nil
))
385 (when org-timer-display
386 (setq org-timer-mode-line-timer
387 (run-with-timer 1 1 'org-timer-update-mode-line
))))))
389 (defun org-timer-update-mode-line ()
390 "Update the timer time in the mode line."
391 (if org-timer-pause-time
393 (setq org-timer-mode-line-string
394 (concat " <" (substring (org-timer-value-string) 0 -
1) ">"))
395 (force-mode-line-update)))
397 (defun org-timer-show-remaining-time ()
398 "Display the remaining time before the timer ends."
401 (if (not org-timer-countdown-timer
)
402 (message "No timer set")
403 (let* ((rtime (decode-time
404 (time-subtract (timer--time org-timer-countdown-timer
)
406 (rsecs (nth 0 rtime
))
407 (rmins (nth 1 rtime
)))
408 (message "%d minute(s) %d seconds left before next time out"
412 (defun org-timer-set-timer (&optional opt
)
413 "Prompt for a duration in minutes or hh:mm:ss and set a timer.
415 If `org-timer-default-timer' is not \"0\", suggest this value as
416 the default duration for the timer. If a timer is already set,
417 prompt the user if she wants to replace it.
419 Called with a numeric prefix argument, use this numeric value as
420 the duration of the timer in minutes.
422 Called with a `C-u' prefix arguments, use `org-timer-default-timer'
423 without prompting the user for a duration.
425 With two `C-u' prefix arguments, use `org-timer-default-timer'
426 without prompting the user for a duration and automatically
427 replace any running timer.
429 By default, the timer duration will be set to the number of
430 minutes in the Effort property, if any. You can ignore this by
431 using three `C-u' prefix arguments."
433 (when (and org-timer-start-time
434 (not org-timer-countdown-timer
))
435 (user-error "Relative timer is running. Stop first"))
436 (let* ((default-timer
437 ;; `org-timer-default-timer' used to be a number, don't choke:
438 (if (numberp org-timer-default-timer
)
439 (number-to-string org-timer-default-timer
)
440 org-timer-default-timer
))
441 (effort-minutes (ignore-errors (floor (org-get-at-eol 'effort-minutes
1))))
442 (minutes (or (and (numberp opt
) (number-to-string opt
))
443 (and (not (equal opt
'(64)))
445 (number-to-string effort-minutes
))
446 (and (consp opt
) default-timer
)
447 (and (stringp opt
) opt
)
448 (read-from-minibuffer
449 "How much time left? (minutes or h:mm:ss) "
450 (and (not (string-equal default-timer
"0")) default-timer
)))))
451 (when (string-match "\\`[0-9]+\\'" minutes
)
452 (setq minutes
(concat minutes
":00")))
453 (if (not (string-match "[0-9]+" minutes
))
454 (org-timer-show-remaining-time)
455 (let ((secs (org-timer-hms-to-secs (org-timer-fix-incomplete minutes
))))
456 (if (and org-timer-countdown-timer
457 (not (or (equal opt
'(16))
458 (y-or-n-p "Replace current timer? "))))
459 (message "No timer set")
460 (when (timerp org-timer-countdown-timer
)
461 (cancel-timer org-timer-countdown-timer
))
462 (setq org-timer-countdown-timer-title
463 (org-timer--get-timer-title))
464 (setq org-timer-countdown-timer
465 (org-timer--run-countdown-timer
466 secs org-timer-countdown-timer-title
))
467 (run-hooks 'org-timer-set-hook
)
468 (setq org-timer-start-time
469 (time-add (current-time) (seconds-to-time secs
)))
470 (setq org-timer-pause-time nil
)
471 (org-timer-set-mode-line 'on
))))))
473 (defun org-timer--run-countdown-timer (secs title
)
474 "Start countdown timer that will last SECS.
475 TITLE will be appended to the notification message displayed when
477 (let ((msg (format "%s: time out" title
)))
480 (setq org-timer-countdown-timer nil
481 org-timer-start-time nil
)
482 (org-notify ,msg
,org-clock-sound
)
483 (org-timer-set-mode-line 'off
)
484 (run-hooks 'org-timer-done-hook
)))))
486 (defun org-timer--get-timer-title ()
487 "Construct timer title from heading or file name of Org buffer."
489 ((derived-mode-p 'org-agenda-mode
)
490 (let* ((marker (or (get-text-property (point) 'org-marker
)
492 (hdmarker (or (get-text-property (point) 'org-hd-marker
)
494 (with-current-buffer (marker-buffer marker
)
495 (org-with-wide-buffer
498 (or (ignore-errors (org-get-heading))
499 (buffer-name (buffer-base-buffer)))))))
500 ((derived-mode-p 'org-mode
)
501 (or (ignore-errors (org-get-heading))
502 (buffer-name (buffer-base-buffer))))
503 (t (error "Not in an Org buffer"))))
508 ;; generated-autoload-file: "org-loaddefs.el"
511 ;;; org-timer.el ends here