1 ;;; org-notify.el --- Notifications for Org-mode
3 ;; Copyright (C) 2012 Free Software Foundation, Inc.
5 ;; Author: Peter Münster <pmrb@free.fr>
6 ;; Keywords: notification, todo-list, alarm, reminder, pop-up
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
23 ;; Get notifications, when there is something to do.
24 ;; Sometimes, you need a reminder a few days before a deadline, e.g. to buy a
25 ;; present for a birthday, and then another notification one hour before to
26 ;; have enough time to choose the right clothes.
27 ;; For other events, e.g. rolling the dustbin to the roadside once per week,
28 ;; you probably need another kind of notification strategy.
29 ;; This package tries to satisfy the various needs.
31 ;; In order to activate this package, you must add the following code
34 ;; (require 'org-notify)
38 ;; (org-notify-add 'appt
39 ;; '(:time "-1s" :period "20s" :duration 10
40 ;; :actions (-message -ding))
41 ;; '(:time "15m" :period "2m" :duration 100
43 ;; '(:time "2h" :period "5m" :actions -message)
44 ;; '(:time "3d" :actions -email))
45 ;; This means for todo-items with `notify' property set to `appt': 3 days
46 ;; before deadline, send a reminder-email, 2 hours before deadline, start to
47 ;; send messages every 5 minutes, then 15 minutes before deadline, start to
48 ;; pop up notification windows every 2 minutes. The timeout of the window is
49 ;; set to 100 seconds. Finally, when deadline is overdue, send messages and
52 ;; Take also a look at the function `org-notify-add'.
56 (eval-when-compile (require 'cl
))
57 (require 'org-element
)
59 (declare-function appt-delete-window
"appt" ())
60 (declare-function notifications-notify
"notifications" (&rest prms
))
61 (declare-function article-lapsed-string
"gnus-art" (t &optional ms
))
63 (defgroup org-notify nil
64 "Options for Org-mode notifications."
68 (defcustom org-notify-audible t
69 "Non-nil means beep to indicate notification."
73 (defconst org-notify-actions
74 '("show" "show" "done" "done" "hour" "one hour later" "day" "one day later"
75 "week" "one week later")
76 "Possible actions for call-back functions.")
78 (defconst org-notify-window-buffer-name
"*org-notify-%s*"
79 "Buffer-name for the `org-notify-action-window' function.")
81 (defvar org-notify-map nil
82 "Mapping between names and parameter lists.")
84 (defvar org-notify-timer nil
85 "Timer of the notification daemon.")
87 (defvar org-notify-parse-file nil
88 "Index of current file, that `org-element-parse-buffer' is parsing.")
90 (defvar org-notify-on-action-map nil
91 "Mapping between on-action identifiers and parameter lists.")
93 (defun org-notify-string->seconds
(str)
94 "Convert time string STR to number of seconds."
96 (let* ((conv `(("s" .
1) ("m" .
60) ("h" .
,(* 60 60))
97 ("d" .
,(* 24 60 60)) ("w" .
,(* 7 24 60 60))
98 ("M" .
,(* 30 24 60 60))))
100 (mapcar (lambda (x) (string-to-char (car x
))) conv
)))
101 (case-fold-search nil
))
102 (string-match (concat "\\(-?\\)\\([0-9]+\\)\\([" letters
"]\\)") str
)
103 (* (string-to-number (match-string 2 str
))
104 (cdr (assoc (match-string 3 str
) conv
))
105 (if (= (length (match-string 1 str
)) 1) -
1 1)))))
107 (defun org-notify-make-todo (heading &rest ignored
)
108 "Create one todo item."
109 (macrolet ((get (k) `(plist-get list
,k
))
110 (pr (k v
) `(setq result
(plist-put result
,k
,v
))))
111 (let* ((list (nth 1 heading
)) (notify (or (get :notify
) "default"))
112 (deadline (get :deadline
)) (heading (get :raw-value
))
114 (when (and (eq (get :todo-type
) 'todo
) heading deadline
)
115 (pr :heading heading
) (pr :notify
(intern notify
))
116 (pr :begin
(get :begin
))
117 (pr :file
(nth org-notify-parse-file
(org-agenda-files 'unrestricted
)))
118 (pr :timestamp deadline
) (pr :uid
(md5 (concat heading deadline
)))
119 (pr :deadline
(- (org-time-string-to-seconds deadline
)
123 (defun org-notify-todo-list ()
124 "Create the todo-list for one org-agenda file."
125 (let* ((files (org-agenda-files 'unrestricted
))
126 (max (1- (length files
))))
127 (setq org-notify-parse-file
128 (if (or (not org-notify-parse-file
) (>= org-notify-parse-file max
))
130 (1+ org-notify-parse-file
)))
132 (with-current-buffer (find-file-noselect
133 (nth org-notify-parse-file files
))
134 (org-element-map (org-element-parse-buffer 'headline
)
135 'headline
'org-notify-make-todo
)))))
137 (defun org-notify-maybe-too-late (diff period heading
)
138 "Print waring message, when notified significantly later than defined by
140 (if (> (/ diff period
) 1.5)
141 (message "Warning: notification for \"%s\" behind schedule!" heading
))
144 (defun org-notify-process ()
145 "Process the todo-list, and possibly notify user about upcoming or
147 (macrolet ((prm (k) `(plist-get prms
,k
)) (td (k) `(plist-get todo
,k
)))
148 (dolist (todo (org-notify-todo-list))
149 (let* ((deadline (td :deadline
)) (heading (td :heading
))
150 (uid (td :uid
)) (last-run-sym
151 (intern (concat ":last-run-" uid
))))
152 (dolist (prms (plist-get org-notify-map
(td :notify
)))
153 (when (< deadline
(org-notify-string->seconds
(prm :time
)))
154 (let ((period (org-notify-string->seconds
(prm :period
)))
155 (last-run (prm last-run-sym
)) (now (org-float-time))
156 (actions (prm :actions
)) diff plist
)
157 (when (or (not last-run
)
158 (and period
(< period
(setq diff
(- now last-run
)))
159 (org-notify-maybe-too-late diff period heading
)))
160 (setq prms
(plist-put prms last-run-sym now
)
161 plist
(append todo prms
))
162 (if (if (plist-member prms
:audible
)
166 (unless (listp actions
)
167 (setq actions
(list actions
)))
168 (dolist (action actions
)
169 (funcall (if (fboundp action
) action
170 (intern (concat "org-notify-action"
171 (symbol-name action
))))
175 (defun org-notify-add (name &rest params
)
176 "Add a new notification type. The NAME can be used in Org-mode property
177 `notify'. If NAME is `default', the notification type applies for todo items
178 without the `notify' property. This file predefines such a default
181 Each element of PARAMS is a list with parameters for a given time
182 distance to the deadline. This distance must increase from one element to
184 List of possible parameters:
185 :time Time distance to deadline, when this type of notification shall
186 start. It's a string: an integral value (positive or negative)
187 followed by a unit (s, m, h, d, w, M).
188 :actions A function or a list of functions to be called to notify the
189 user. Instead of a function name, you can also supply a suffix
190 of one of the various predefined `org-notify-action-xxx'
192 :period Optional: can be used to repeat the actions periodically. Same
194 :duration Some actions use this parameter to specify the duration of the
195 notification. It's an integral number in seconds.
196 :audible Overwrite the value of `org-notify-audible' for this action.
198 For the actions, you can use your own functions or some of the predefined
199 ones, whose names are prefixed with `org-notify-action-'."
200 (setq org-notify-map
(plist-put org-notify-map name params
)))
202 (defun org-notify-start (&optional secs
)
203 "Start the notification daemon. If SECS is positive, it's the
204 period in seconds for processing the notifications of one
205 org-agenda file, and if negative, notifications will be checked
206 only when emacs is idle for -SECS seconds. The default value for
210 (setq secs
(or secs
20)
211 org-notify-timer
(if (< secs
0)
212 (run-with-idle-timer (* -
1 secs
) t
214 (run-with-timer secs secs
'org-notify-process
))))
216 (defun org-notify-stop ()
217 "Stop the notification daemon."
218 (when org-notify-timer
219 (cancel-timer org-notify-timer
)
220 (setq org-notify-timer nil
)))
222 (defun org-notify-on-action (plist key
)
223 "User wants to see action."
224 (let ((file (plist-get plist
:file
))
225 (begin (plist-get plist
:begin
)))
226 (if (string-equal key
"show")
228 (switch-to-buffer (find-file-noselect file
))
229 (org-with-wide-buffer
233 (search-forward "DEADLINE: <")
234 (if (display-graphic-p)
235 (x-focus-frame nil
)))
237 (with-current-buffer (find-file-noselect file
)
238 (org-with-wide-buffer
240 (search-forward "DEADLINE: <")
242 ((string-equal key
"done") (org-todo))
243 ((string-equal key
"hour") (org-timestamp-change 60 'minute
))
244 ((string-equal key
"day") (org-timestamp-up-day))
245 ((string-equal key
"week") (org-timestamp-change 7 'day
)))))))))
247 (defun org-notify-on-action-notify (id key
)
248 "User wants to see action after mouse-click in notify window."
249 (org-notify-on-action (plist-get org-notify-on-action-map id
) key
)
250 (org-notify-on-close id nil
))
252 (defun org-notify-on-action-button (button)
253 "User wants to see action after button activation."
254 (macrolet ((get (k) `(button-get button
,k
)))
255 (org-notify-on-action (get 'plist
) (get 'key
))
256 (org-notify-delete-window (get 'buffer
))
257 (cancel-timer (get 'timer
))))
259 (defun org-notify-delete-window (buffer)
260 "Delete the notification window."
262 (let ((appt-buffer-name buffer
)
264 (appt-delete-window)))
266 (defun org-notify-on-close (id reason
)
267 "Notification window has been closed."
268 (setq org-notify-on-action-map
(plist-put org-notify-on-action-map id nil
)))
270 (defun org-notify-action-message (plist)
272 (message "TODO: \"%s\" at %s!" (plist-get plist
:heading
)
273 (plist-get plist
:timestamp
)))
275 (defun org-notify-action-ding (plist)
277 (let ((timer (run-with-timer 0 1 'ding
)))
278 (run-with-timer (or (plist-get plist
:duration
) 3) nil
279 'cancel-timer timer
)))
281 (defun org-notify-body-text (plist)
282 "Make human readable string for remaining time to deadline."
285 (replace-regexp-in-string
287 (article-lapsed-string
288 (time-add (current-time)
289 (seconds-to-time (plist-get plist
:deadline
))) 2))
290 (plist-get plist
:timestamp
)))
292 (defun org-notify-action-email (plist)
293 "Send email to user."
294 (compose-mail user-mail-address
(concat "TODO: " (plist-get plist
:heading
)))
295 (insert (org-notify-body-text plist
))
296 (funcall send-mail-function
)
297 (flet ((yes-or-no-p (prompt) t
))
300 (defun org-notify-select-highest-window ()
301 "Select the highest window on the frame, that is not is not an
302 org-notify window. Mostly copied from `appt-select-lowest-window'."
303 (let ((highest-window (selected-window))
304 (bottom-edge (nth 3 (window-edges)))
306 (walk-windows (lambda (w)
308 (not (string-match "^\\*org-notify-.*\\*$"
311 (> bottom-edge
(setq next-bottom-edge
312 (nth 3 (window-edges w
)))))
313 (setq bottom-edge next-bottom-edge
314 highest-window w
))) 'nomini
)
315 (select-window highest-window
)))
317 (defun org-notify-action-window (plist)
318 "Pop up a window, mostly copied from `appt-disp-window'."
320 (macrolet ((get (k) `(plist-get plist
,k
)))
321 (let ((this-window (selected-window))
322 (buf (get-buffer-create
323 (format org-notify-window-buffer-name
(get :uid
)))))
326 (and (minibufferp) (display-multi-frame-p) (other-frame 1)))
327 (if (cdr (assq 'unsplittable
(frame-parameters)))
328 (progn (set-buffer buf
) (display-buffer buf
))
329 (unless (or (special-display-p (buffer-name buf
))
330 (same-window-p (buffer-name buf
)))
331 (org-notify-select-highest-window)
332 (when (>= (window-height) (* 2 window-min-height
))
333 (select-window (split-window nil nil
'above
))))
334 (switch-to-buffer buf
))
335 (setq buffer-read-only nil buffer-undo-list t
)
337 (insert (format "TODO: %s, %s.\n" (get :heading
)
338 (org-notify-body-text plist
)))
339 (let ((timer (run-with-timer (or (get :duration
) 10) nil
340 'org-notify-delete-window buf
)))
341 (dotimes (i (/ (length org-notify-actions
) 2))
342 (let ((key (nth (* i
2) org-notify-actions
))
343 (text (nth (1+ (* i
2)) org-notify-actions
)))
344 (insert-button text
'action
'org-notify-on-action-button
345 'key key
'buffer buf
'plist plist
'timer timer
)
347 (shrink-window-if-larger-than-buffer (get-buffer-window buf t
))
348 (set-buffer-modified-p nil
) (setq buffer-read-only t
)
349 (raise-frame (selected-frame)) (select-window this-window
)))))
351 (defun org-notify-action-notify (plist)
352 "Pop up a notification window."
353 (require 'notifications
)
354 (let* ((duration (plist-get plist
:duration
))
355 (id (notifications-notify
356 :title
(plist-get plist
:heading
)
357 :body
(org-notify-body-text plist
)
358 :timeout
(if duration
(* duration
1000))
359 :actions org-notify-actions
360 :on-action
'org-notify-on-action-notify
)))
361 (setq org-notify-on-action-map
362 (plist-put org-notify-on-action-map id plist
))))
364 (defun org-notify-action-notify/window
(plist)
365 "For a graphics display, pop up a notification window, for a text
366 terminal an emacs window."
367 (if (display-graphic-p)
368 (org-notify-action-notify plist
)
369 (org-notify-action-window plist
)))
371 ;;; Provide a minimal default setup.
372 (org-notify-add 'default
'(:time
"1h" :actions -notify
/window
373 :period
"2m" :duration
60))
375 (provide 'org-notify
)
377 ;;; org-notify.el ends here