1 ;;; org-timer.el --- The relative timer code for Org-mode
3 ;; Copyright (C) 2008-2014 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://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 <http://www.gnu.org/licenses/>.
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
27 ;; This file contains the relative timer code for Org-mode
33 (declare-function org-notify
"org-clock" (notification &optional play-sound
))
34 (declare-function org-agenda-error
"org-agenda" ())
36 (defvar org-timer-start-time nil
37 "t=0 for the running timer.")
39 (defvar org-timer-pause-time nil
40 "Time when the timer was paused.")
42 (defconst org-timer-re
"\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
43 "Regular expression used to match timer stamps.")
45 (defcustom org-timer-format
"%s "
46 "The format to insert the time of the timer.
47 This format must contain one instance of \"%s\" which will be replaced by
48 the value of the relative timer."
52 (defcustom org-timer-default-timer
0
53 "The default timer when a timer is set.
54 When 0, the user is prompted for a value."
59 (defcustom org-timer-display
'mode-line
60 "When a timer is running, org-mode can display it in the mode
61 line and/or frame title.
64 both displays in both mode line and frame title
65 mode-line displays only in mode line (default)
66 frame-title displays only in frame title
67 nil current timer is not displayed"
70 (const :tag
"Mode line" mode-line
)
71 (const :tag
"Frame title" frame-title
)
72 (const :tag
"Both" both
)
73 (const :tag
"None" nil
)))
75 (defvar org-timer-start-hook nil
76 "Hook run after relative timer is started.")
78 (defvar org-timer-stop-hook nil
79 "Hook run before relative timer is stopped.")
81 (defvar org-timer-pause-hook nil
82 "Hook run before relative timer is paused.")
84 (defvar org-timer-continue-hook nil
85 "Hook run after relative timer is continued.")
87 (defvar org-timer-set-hook nil
88 "Hook run after countdown timer is set.")
90 (defvar org-timer-done-hook nil
91 "Hook run after countdown timer reaches zero.")
93 (defvar org-timer-cancel-hook nil
94 "Hook run before countdown timer is canceled.")
97 (defun org-timer-start (&optional offset
)
98 "Set the starting time for the relative timer to now.
99 When called with prefix argument OFFSET, prompt the user for an offset time,
100 with the default taken from a timer stamp at point, if any.
101 If OFFSET is a string or an integer, it is directly taken to be the offset
102 without user interaction.
103 When called with a double prefix arg, all timer strings in the active
104 region will be shifted by a specific amount. You will be prompted for
105 the amount, with the default to make the first timer string in
108 (if (equal offset
'(16))
109 (call-interactively 'org-timer-change-times-in-region
)
112 (setq org-timer-start-time
(current-time))
114 ((integerp offset
) (setq delta offset
))
115 ((stringp offset
) (setq delta
(org-timer-hms-to-secs offset
)))
117 (setq def
(if (org-in-regexp org-timer-re
)
121 (format "Restart timer with offset [%s]: " def
)))
122 (unless (string-match "\\S-" s
) (setq s def
))
123 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete s
)))))
124 (setq org-timer-start-time
126 (- (org-float-time) delta
))))
127 (org-timer-set-mode-line 'on
)
128 (message "Timer start time set to %s, current value is %s"
129 (format-time-string "%T" org-timer-start-time
)
130 (org-timer-secs-to-hms (or delta
0)))
131 (run-hooks 'org-timer-start-hook
))))
133 (defun org-timer-pause-or-continue (&optional stop
)
134 "Pause or continue the relative timer.
135 With prefix arg STOP, stop it entirely."
138 (stop (org-timer-stop))
139 ((not org-timer-start-time
) (error "No timer is running"))
140 (org-timer-pause-time
141 ;; timer is paused, continue
142 (setq org-timer-start-time
146 (- (org-float-time org-timer-pause-time
)
147 (org-float-time org-timer-start-time
))))
148 org-timer-pause-time nil
)
149 (org-timer-set-mode-line 'on
)
150 (run-hooks 'org-timer-continue-hook
)
151 (message "Timer continues at %s" (org-timer-value-string)))
154 (run-hooks 'org-timer-pause-hook
)
155 (setq org-timer-pause-time
(current-time))
156 (org-timer-set-mode-line 'pause
)
157 (message "Timer paused at %s" (org-timer-value-string)))))
159 (defvar org-timer-current-timer nil
)
160 (defun org-timer-stop ()
161 "Stop the relative timer."
163 (run-hooks 'org-timer-stop-hook
)
164 (setq org-timer-start-time nil
165 org-timer-pause-time nil
166 org-timer-current-timer nil
)
167 (org-timer-set-mode-line 'off
)
168 (message "Timer stopped"))
171 (defun org-timer (&optional restart no-insert-p
)
172 "Insert a H:MM:SS string from the timer into the buffer.
173 The first time this command is used, the timer is started. When used with
174 a \\[universal-argument] prefix, force restarting the timer.
175 When used with a double prefix argument \\[universal-argument], change all the timer string
176 in the region by a fixed amount. This can be used to recalibrate a timer
177 that was not started at the correct moment.
179 If NO-INSERT-P is non-nil, return the string instead of inserting
182 (when (or (equal restart
'(4)) (not org-timer-start-time
))
185 (org-timer-value-string)
186 (insert (org-timer-value-string))))
188 (defun org-timer-value-string ()
189 "Set the timer string."
190 (format org-timer-format
191 (org-timer-secs-to-hms
192 (abs (floor (org-timer-seconds))))))
194 (defvar org-timer-timer-is-countdown nil
)
195 (defun org-timer-seconds ()
196 ;; Pass `current-time' result to `org-float-time'
197 ;; (instead of calling without arguments) so that only
198 ;; `current-time' has to be overriden in tests.
199 (if org-timer-timer-is-countdown
200 (- (org-float-time org-timer-start-time
)
201 (org-float-time (current-time)))
202 (- (org-float-time (or org-timer-pause-time
(current-time)))
203 (org-float-time org-timer-start-time
))))
206 (defun org-timer-change-times-in-region (beg end delta
)
207 "Change all h:mm:ss time in region by a DELTA."
209 "r\nsEnter time difference like \"-1:08:26\". Default is first time to zero: ")
210 (let ((re "[-+]?[0-9]+:[0-9]\\{2\\}:[0-9]\\{2\\}") p
)
211 (unless (string-match "\\S-" delta
)
214 (when (re-search-forward re end t
)
215 (setq delta
(match-string 0))
216 (if (equal (string-to-char delta
) ?-
)
217 (setq delta
(substring delta
1))
218 (setq delta
(concat "-" delta
))))))
219 (setq delta
(org-timer-hms-to-secs (org-timer-fix-incomplete delta
)))
220 (when (= delta
0) (error "No change"))
223 (while (re-search-backward re beg t
)
227 (org-timer-secs-to-hms (+ (org-timer-hms-to-secs (match-string 0)) delta
)))
232 (defun org-timer-item (&optional arg
)
233 "Insert a description-type item with the current timer value."
235 (let ((itemp (org-in-item-p)) (pos (point)))
237 ;; In a timer list, insert with `org-list-insert-item',
238 ;; then fix the list.
239 ((and itemp
(goto-char itemp
) (org-at-item-timer-p))
240 (let* ((struct (org-list-struct))
241 (prevs (org-list-prevs-alist struct
))
242 (s (concat (org-timer (when arg
'(4)) t
) ":: ")))
243 (setq struct
(org-list-insert-item pos struct prevs nil s
))
244 (org-list-write-struct struct
(org-list-parents-alist struct
))
245 (looking-at org-list-full-item-re
)
246 (goto-char (match-end 0))))
247 ;; In a list of another type, don't break anything: throw an error.
248 (itemp (goto-char pos
) (error "This is not a timer list"))
249 ;; Else, start a new list.
254 (org-timer (when arg
'(4)))
257 (defun org-timer-fix-incomplete (hms)
258 "If hms is a H:MM:SS string with missing hour or hour and minute, fix it."
259 (if (string-match "\\(?:\\([0-9]+:\\)?\\([0-9]+:\\)\\)?\\([0-9]+\\)" hms
)
261 (format "%d:%02d:%02d"
262 (if (match-end 1) (string-to-number (match-string 1 hms
)) 0)
263 (if (match-end 2) (string-to-number (match-string 2 hms
)) 0)
264 (string-to-number (match-string 3 hms
)))
266 (error "Cannot parse HMS string \"%s\"" hms
)))
268 (defun org-timer-hms-to-secs (hms)
269 "Convert h:mm:ss string to an integer time.
270 If the string starts with a minus sign, the integer will be negative."
271 (if (not (string-match
272 "\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)"
275 (let* ((h (string-to-number (match-string 1 hms
)))
276 (m (string-to-number (match-string 2 hms
)))
277 (s (string-to-number (match-string 3 hms
)))
278 (sign (equal (substring (match-string 1 hms
) 0 1) "-")))
280 (* (if sign -
1 1) (+ s
(* 60 (+ m
(* 60 h
))))))))
282 (defun org-timer-secs-to-hms (s)
283 "Convert integer S into h:mm:ss.
284 If the integer is negative, the string will start with \"-\"."
286 (setq sign
(if (< s
0) "-" "")
288 m
(/ s
60) s
(- s
(* 60 m
))
289 h
(/ m
60) m
(- m
(* 60 h
)))
290 (format "%s%d:%02d:%02d" sign h m s
)))
292 (defvar org-timer-mode-line-timer nil
)
293 (defvar org-timer-mode-line-string nil
)
295 (defun org-timer-set-mode-line (value)
296 "Set the mode-line display of the relative timer.
297 VALUE can be `on', `off', or `pause'."
298 (when (or (eq org-timer-display
'mode-line
)
299 (eq org-timer-display
'both
))
300 (or global-mode-string
(setq global-mode-string
'("")))
301 (or (memq 'org-timer-mode-line-string global-mode-string
)
302 (setq global-mode-string
303 (append global-mode-string
'(org-timer-mode-line-string)))))
304 (when (or (eq org-timer-display
'frame-title
)
305 (eq org-timer-display
'both
))
306 (or (memq 'org-timer-mode-line-string frame-title-format
)
307 (setq frame-title-format
308 (append frame-title-format
'(org-timer-mode-line-string)))))
311 (when org-timer-mode-line-timer
312 (cancel-timer org-timer-mode-line-timer
)
313 (setq org-timer-mode-line-timer nil
))
314 (when (or (eq org-timer-display
'mode-line
)
315 (eq org-timer-display
'both
))
316 (setq global-mode-string
317 (delq 'org-timer-mode-line-string global-mode-string
)))
318 (when (or (eq org-timer-display
'frame-title
)
319 (eq org-timer-display
'both
))
320 (setq frame-title-format
321 (delq 'org-timer-mode-line-string frame-title-format
)))
322 (force-mode-line-update))
323 ((equal value
'pause
)
324 (when org-timer-mode-line-timer
325 (cancel-timer org-timer-mode-line-timer
)
326 (setq org-timer-mode-line-timer nil
)))
328 (when (or (eq org-timer-display
'mode-line
)
329 (eq org-timer-display
'both
))
330 (or global-mode-string
(setq global-mode-string
'("")))
331 (or (memq 'org-timer-mode-line-string global-mode-string
)
332 (setq global-mode-string
333 (append global-mode-string
'(org-timer-mode-line-string)))))
334 (when (or (eq org-timer-display
'frame-title
)
335 (eq org-timer-display
'both
))
336 (or (memq 'org-timer-mode-line-string frame-title-format
)
337 (setq frame-title-format
338 (append frame-title-format
'(org-timer-mode-line-string)))))
339 (org-timer-update-mode-line)
340 (when org-timer-mode-line-timer
341 (cancel-timer org-timer-mode-line-timer
)
342 (setq org-timer-mode-line-timer nil
))
343 (when org-timer-display
344 (setq org-timer-mode-line-timer
345 (run-with-timer 1 1 'org-timer-update-mode-line
))))))
347 (defun org-timer-update-mode-line ()
348 "Update the timer time in the mode line."
349 (if org-timer-pause-time
351 (setq org-timer-mode-line-string
352 (concat " <" (substring (org-timer-value-string) 0 -
1) ">"))
353 (force-mode-line-update)))
355 (defun org-timer-cancel-timer ()
356 "Cancel the current timer."
358 (when (eval org-timer-current-timer
)
359 (run-hooks 'org-timer-cancel-hook
)
360 (cancel-timer org-timer-current-timer
)
361 (setq org-timer-current-timer nil
)
362 (setq org-timer-timer-is-countdown nil
)
363 (org-timer-set-mode-line 'off
))
364 (message "Last timer canceled"))
366 (defun org-timer-show-remaining-time ()
367 "Display the remaining time before the timer ends."
370 (if (not org-timer-current-timer
)
371 (message "No timer set")
372 (let* ((rtime (decode-time
373 (time-subtract (timer--time org-timer-current-timer
)
375 (rsecs (nth 0 rtime
))
376 (rmins (nth 1 rtime
)))
377 (message "%d minute(s) %d seconds left before next time out"
380 (defvar org-clock-sound
)
383 (defun org-timer-set-timer (&optional opt
)
384 "Prompt for a duration and set a timer.
386 If `org-timer-default-timer' is not zero, suggest this value as
387 the default duration for the timer. If a timer is already set,
388 prompt the user if she wants to replace it.
390 Called with a numeric prefix argument, use this numeric value as
391 the duration of the timer.
393 Called with a `C-u' prefix arguments, use `org-timer-default-timer'
394 without prompting the user for a duration.
396 With two `C-u' prefix arguments, use `org-timer-default-timer'
397 without prompting the user for a duration and automatically
398 replace any running timer."
400 (let ((minutes (or (and (numberp opt
) (number-to-string opt
))
401 (and (listp opt
) (not (null opt
))
402 (number-to-string org-timer-default-timer
))
403 (read-from-minibuffer
404 "How many minutes left? "
405 (if (not (eq org-timer-default-timer
0))
406 (number-to-string org-timer-default-timer
))))))
407 (if (not (string-match "[0-9]+" minutes
))
408 (org-timer-show-remaining-time)
409 (let* ((mins (string-to-number (match-string 0 minutes
)))
412 ((string-match "Org Agenda" (buffer-name))
413 (let* ((marker (or (get-text-property (point) 'org-marker
)
415 (hdmarker (or (get-text-property (point) 'org-hd-marker
)
417 (pos (marker-position marker
)))
418 (with-current-buffer (marker-buffer marker
)
422 (or (ignore-errors (org-get-heading))
423 (concat "File:" (file-name-nondirectory (buffer-file-name)))))))
424 ((derived-mode-p 'org-mode
)
425 (or (ignore-errors (org-get-heading))
426 (concat "File:" (file-name-nondirectory (buffer-file-name)))))
427 (t (error "Not in an Org buffer"))))
429 (if (or (and org-timer-current-timer
430 (or (equal opt
'(16))
431 (y-or-n-p "Replace current timer? ")))
432 (not org-timer-current-timer
))
435 (when org-timer-current-timer
436 (cancel-timer org-timer-current-timer
))
437 (setq org-timer-current-timer
440 (setq org-timer-current-timer nil
)
441 (org-notify ,(format "%s: time out" hl
) ,org-clock-sound
)
442 (setq org-timer-timer-is-countdown nil
)
443 (org-timer-set-mode-line 'off
)
444 (run-hooks 'org-timer-done-hook
))))
445 (run-hooks 'org-timer-set-hook
)
446 (setq org-timer-timer-is-countdown t
448 (time-add (current-time) (seconds-to-time (* mins
60))))
449 (org-timer-set-mode-line 'on
))
450 (message "No timer set"))))))
455 ;; generated-autoload-file: "org-loaddefs.el"
458 ;;; org-timer.el ends here