1 ;;; org-timer.el --- The relative timer code for Org-mode
3 ;; Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
28 ;; This file contains the relative timer code for Org-mode
34 (declare-function org-notify
"org-clock" (notification &optional play-sound
))
35 (declare-function org-agenda-error
"org-agenda" ())
37 (defvar org-timer-start-time nil
38 "t=0 for the running timer.")
40 (defvar org-timer-pause-time nil
41 "Time when the timer was paused.")
43 (defconst org-timer-re
"\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
44 "Regular expression used to match timer stamps.")
46 (defcustom org-timer-format
"%s "
47 "The format to insert the time of the timer.
48 This format must contain one instance of \"%s\" which will be replaced by
49 the value of the relative timer."
53 (defcustom org-timer-default-timer
0
54 "The default timer when a timer is set.
55 When 0, the user is prompted for a value."
59 (defvar org-timer-start-hook nil
60 "Hook run after relative timer is started.")
62 (defvar org-timer-stop-hook nil
63 "Hook run before relative timer is stopped.")
65 (defvar org-timer-pause-hook nil
66 "Hook run before relative timer is paused.")
68 (defvar org-timer-continue-hook nil
69 "Hook run after relative timer is continued.")
71 (defvar org-timer-set-hook nil
72 "Hook run after countdown timer is set.")
74 (defvar org-timer-done-hook nil
75 "Hook run after countdown timer reaches zero.")
77 (defvar org-timer-cancel-hook nil
78 "Hook run before countdown timer is canceled.")
81 (defun org-timer-start (&optional offset
)
82 "Set the starting time for the relative timer to now.
83 When called with prefix argument OFFSET, prompt the user for an offset time,
84 with the default taken from a timer stamp at point, if any.
85 If OFFSET is a string or an integer, it is directly taken to be the offset
86 without user interaction.
87 When called with a double prefix arg, all timer strings in the active
88 region will be shifted by a specific amount. You will be prompted for
89 the amount, with the default to make the first timer string in
92 (if (equal offset
'(16))
93 (call-interactively 'org-timer-change-times-in-region
)
96 (setq org-timer-start-time
(current-time))
98 ((integerp offset
) (setq delta offset
))
99 ((stringp offset
) (setq delta
(org-timer-hms-to-secs offset
)))
101 (setq def
(if (org-in-regexp org-timer-re
)
105 (format "Restart timer with offset [%s]: " def
)))
106 (unless (string-match "\\S-" s
) (setq s def
))
107 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete s
)))))
108 (setq org-timer-start-time
110 (- (org-float-time) delta
))))
111 (org-timer-set-mode-line 'on
)
112 (message "Timer start time set to %s, current value is %s"
113 (format-time-string "%T" org-timer-start-time
)
114 (org-timer-secs-to-hms (or delta
0)))
115 (run-hooks 'org-timer-start-hook
))))
117 (defun org-timer-pause-or-continue (&optional stop
)
118 "Pause or continue the relative timer.
119 With prefix arg STOP, stop it entirely."
122 (stop (org-timer-stop))
123 ((not org-timer-start-time
) (error "No timer is running"))
124 (org-timer-pause-time
125 ;; timer is paused, continue
126 (setq org-timer-start-time
130 (- (org-float-time org-timer-pause-time
)
131 (org-float-time org-timer-start-time
))))
132 org-timer-pause-time nil
)
133 (org-timer-set-mode-line 'on
)
134 (run-hooks 'org-timer-continue-hook
)
135 (message "Timer continues at %s" (org-timer-value-string)))
138 (run-hooks 'org-timer-pause-hook
)
139 (setq org-timer-pause-time
(current-time))
140 (org-timer-set-mode-line 'pause
)
141 (message "Timer paused at %s" (org-timer-value-string)))))
143 (defun org-timer-stop ()
144 "Stop the relative timer."
146 (run-hooks 'org-timer-stop-hook
)
147 (setq org-timer-start-time nil
148 org-timer-pause-time nil
)
149 (org-timer-set-mode-line 'off
))
152 (defun org-timer (&optional restart no-insert-p
)
153 "Insert a H:MM:SS string from the timer into the buffer.
154 The first time this command is used, the timer is started. When used with
155 a \\[universal-argument] prefix, force restarting the timer.
156 When used with a double prefix argument \\[universal-argument], change all the timer string
157 in the region by a fixed amount. This can be used to recalibrate a timer
158 that was not started at the correct moment.
160 If NO-INSERT-P is non-nil, return the string instead of inserting
163 (when (or (equal restart
'(4)) (not org-timer-start-time
))
166 (org-timer-value-string)
167 (insert (org-timer-value-string))))
169 (defun org-timer-value-string ()
170 (format org-timer-format
(org-timer-secs-to-hms (floor (org-timer-seconds)))))
172 (defvar org-timer-timer-is-countdown nil
)
173 (defun org-timer-seconds ()
174 (if org-timer-timer-is-countdown
175 (- (org-float-time org-timer-start-time
)
176 (org-float-time (current-time)))
177 (- (org-float-time (or org-timer-pause-time
(current-time)))
178 (org-float-time org-timer-start-time
))))
181 (defun org-timer-change-times-in-region (beg end delta
)
182 "Change all h:mm:ss time in region by a DELTA."
184 "r\nsEnter time difference like \"-1:08:26\". Default is first time to zero: ")
185 (let ((re "[-+]?[0-9]+:[0-9]\\{2\\}:[0-9]\\{2\\}") p
)
186 (unless (string-match "\\S-" delta
)
189 (when (re-search-forward re end t
)
190 (setq delta
(match-string 0))
191 (if (equal (string-to-char delta
) ?-
)
192 (setq delta
(substring delta
1))
193 (setq delta
(concat "-" delta
))))))
194 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete delta
)))
195 (when (= delta
0) (error "No change"))
198 (while (re-search-backward re beg t
)
202 (org-timer-secs-to-hms (+ (org-timer-hms-to-secs (match-string 0)) delta
)))
207 (defun org-timer-item (&optional arg
)
208 "Insert a description-type item with the current timer value."
211 ;; In a timer list, insert with `org-list-insert-item-generic'.
212 ((and (org-in-item-p)
213 (save-excursion (org-beginning-of-item) (org-at-item-timer-p)))
214 (org-list-insert-item-generic
215 (point) nil
(concat (org-timer (when arg
'(4)) t
) ":: ")))
216 ;; In a list of another type, don't break anything: throw an error.
218 (error "This is not a timer list"))
219 ;; Else, insert the timer correctly indented at bol.
222 (org-indent-line-function)
224 (org-timer (when arg
'(4)))
227 (defun org-timer-fix-incomplete (hms)
228 "If hms is a H:MM:SS string with missing hour or hour and minute, fix it."
229 (if (string-match "\\(?:\\([0-9]+:\\)?\\([0-9]+:\\)\\)?\\([0-9]+\\)" hms
)
231 (format "%d:%02d:%02d"
232 (if (match-end 1) (string-to-number (match-string 1 hms
)) 0)
233 (if (match-end 2) (string-to-number (match-string 2 hms
)) 0)
234 (string-to-number (match-string 3 hms
)))
236 (error "Cannot parse HMS string \"%s\"" hms
)))
238 (defun org-timer-hms-to-secs (hms)
239 "Convert h:mm:ss string to an integer time.
240 If the string starts with a minus sign, the integer will be negative."
241 (if (not (string-match
242 "\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
245 (let* ((h (string-to-number (match-string 1 hms
)))
246 (m (string-to-number (match-string 2 hms
)))
247 (s (string-to-number (match-string 3 hms
)))
248 (sign (equal (substring (match-string 1 hms
) 0 1) "-")))
250 (* (if sign -
1 1) (+ s
(* 60 (+ m
(* 60 h
))))))))
252 (defun org-timer-secs-to-hms (s)
253 "Convert integer S into h:mm:ss.
254 If the integer is negative, the string will start with \"-\"."
256 (setq sign
(if (< s
0) "-" "")
258 m
(/ s
60) s
(- s
(* 60 m
))
259 h
(/ m
60) m
(- m
(* 60 h
)))
260 (format "%s%d:%02d:%02d" sign h m s
)))
262 (defvar org-timer-mode-line-timer nil
)
263 (defvar org-timer-mode-line-string nil
)
265 (defun org-timer-set-mode-line (value)
266 "Set the mode-line display of the relative timer.
267 VALUE can be `on', `off', or `pause'."
268 (or global-mode-string
(setq global-mode-string
'("")))
269 (or (memq 'org-timer-mode-line-string global-mode-string
)
270 (setq global-mode-string
271 (append global-mode-string
'(org-timer-mode-line-string))))
274 (when org-timer-mode-line-timer
275 (cancel-timer org-timer-mode-line-timer
)
276 (setq org-timer-mode-line-timer nil
))
277 (setq global-mode-string
278 (delq 'org-timer-mode-line-string global-mode-string
))
279 (force-mode-line-update))
280 ((equal value
'pause
)
281 (when org-timer-mode-line-timer
282 (cancel-timer org-timer-mode-line-timer
)
283 (setq org-timer-mode-line-timer nil
)))
285 (or global-mode-string
(setq global-mode-string
'("")))
286 (or (memq 'org-timer-mode-line-string global-mode-string
)
287 (setq global-mode-string
288 (append global-mode-string
'(org-timer-mode-line-string))))
289 (org-timer-update-mode-line)
290 (when org-timer-mode-line-timer
291 (cancel-timer org-timer-mode-line-timer
))
292 (setq org-timer-mode-line-timer
293 (run-with-timer 1 1 'org-timer-update-mode-line
)))))
295 (defun org-timer-update-mode-line ()
296 "Update the timer time in the mode line."
297 (if org-timer-pause-time
299 (setq org-timer-mode-line-string
300 (concat " <" (substring (org-timer-value-string) 0 -
1) ">"))
301 (force-mode-line-update)))
303 (defvar org-timer-current-timer nil
)
304 (defun org-timer-cancel-timer ()
305 "Cancel the current timer."
307 (when (eval org-timer-current-timer
)
308 (run-hooks 'org-timer-cancel-hook
)
309 (cancel-timer org-timer-current-timer
)
310 (setq org-timer-current-timer nil
)
311 (setq org-timer-timer-is-countdown nil
)
312 (org-timer-set-mode-line 'off
))
313 (message "Last timer canceled"))
315 (defun org-timer-show-remaining-time ()
316 "Display the remaining time before the timer ends."
319 (if (not org-timer-current-timer
)
320 (message "No timer set")
321 (let* ((rtime (decode-time
322 (time-subtract (timer--time org-timer-current-timer
)
324 (rsecs (nth 0 rtime
))
325 (rmins (nth 1 rtime
)))
326 (message "%d minute(s) %d seconds left before next time out"
330 (defun org-timer-set-timer (&optional opt
)
331 "Prompt for a duration and set a timer.
333 If `org-timer-default-timer' is not zero, suggest this value as
334 the default duration for the timer. If a timer is already set,
335 prompt the user if she wants to replace it.
337 Called with a numeric prefix argument, use this numeric value as
338 the duration of the timer.
340 Called with a `C-u' prefix arguments, use `org-timer-default-timer'
341 without prompting the user for a duration.
343 With two `C-u' prefix arguments, use `org-timer-default-timer'
344 without prompting the user for a duration and automatically
345 replace any running timer."
347 (let ((minutes (or (and (numberp opt
) (number-to-string opt
))
348 (and (listp opt
) (not (null opt
))
349 (number-to-string org-timer-default-timer
))
350 (read-from-minibuffer
351 "How many minutes left? "
352 (if (not (eq org-timer-default-timer
0))
353 (number-to-string org-timer-default-timer
))))))
354 (if (not (string-match "[0-9]+" minutes
))
355 (org-timer-show-remaining-time)
356 (let* ((mins (string-to-number (match-string 0 minutes
)))
359 ((string-match "Org Agenda" (buffer-name))
360 (let* ((marker (or (get-text-property (point) 'org-marker
)
362 (hdmarker (or (get-text-property (point) 'org-hd-marker
)
364 (pos (marker-position marker
)))
365 (with-current-buffer (marker-buffer marker
)
369 (or (ignore-errors (org-get-heading))
370 (concat "File:" (file-name-nondirectory (buffer-file-name)))))))
371 ((eq major-mode
'org-mode
)
372 (or (ignore-errors (org-get-heading))
373 (concat "File:" (file-name-nondirectory (buffer-file-name)))))
374 (t (error "Not in an Org buffer"))))
376 (if (or (and org-timer-current-timer
377 (or (equal opt
'(16))
378 (y-or-n-p "Replace current timer? ")))
379 (not org-timer-current-timer
))
382 (when org-timer-current-timer
383 (cancel-timer org-timer-current-timer
))
384 (setq org-timer-current-timer
387 (setq org-timer-current-timer nil
)
388 (org-notify ,(format "%s: time out" hl
) t
)
389 (setq org-timer-timer-is-countdown nil
)
390 (org-timer-set-mode-line 'off
)
391 (run-hooks 'org-timer-done-hook
))))
392 (run-hooks 'org-timer-set-hook
)
393 (setq org-timer-timer-is-countdown t
395 (time-add (current-time) (seconds-to-time (* mins
60))))
396 (org-timer-set-mode-line 'on
))
397 (message "No timer set"))))))
401 ;; arch-tag: 97538f8c-3871-4509-8f23-1e7b3ff3d107
403 ;;; org-timer.el ends here