1 ;;; notifications.el --- Client interface to desktop notifications.
3 ;; Copyright (C) 2010 Free Software Foundation, Inc.
5 ;; Author: Julien Danjou <julien@danjou.info>
6 ;; Keywords: comm desktop notifications
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; This package provides an implementation of the Desktop Notifications
26 ;; <http://www.galago-project.org/specs/notification/>.
28 ;; In order to activate this package, you must add the following code
31 ;; (require 'notifications)
37 ;; Pacify byte-compiler. D-Bus support in the Emacs core can be
38 ;; disabled with configuration option "--without-dbus". Declare used
39 ;; subroutines and variables of `dbus' therefore.
40 (declare-function dbus-call-method
"dbusbind.c")
41 (declare-function dbus-register-signal
"dbusbind.c")
45 (defconst notifications-specification-version
"1.1"
46 "The version of the Desktop Notifications Specification implemented.")
48 (defconst notifications-application-name
"Emacs"
49 "Default application name.")
51 (defconst notifications-application-icon
53 "images/icons/hicolor/scalable/apps/emacs.svg"
55 "Default application icon.")
57 (defconst notifications-service
"org.freedesktop.Notifications"
58 "D-Bus notifications service name.")
60 (defconst notifications-path
"/org/freedesktop/Notifications"
61 "D-Bus notifications service path.")
63 (defconst notifications-interface
"org.freedesktop.Notifications"
64 "D-Bus notifications service path.")
66 (defconst notifications-notify-method
"Notify"
67 "D-Bus notifications service path.")
69 (defconst notifications-close-notification-method
"CloseNotification"
70 "D-Bus notifications service path.")
72 (defconst notifications-action-signal
"ActionInvoked"
73 "D-Bus notifications action signal.")
75 (defconst notifications-closed-signal
"NotificationClosed"
76 "D-Bus notifications closed signal.")
78 (defconst notifications-closed-reason
81 (3 close-notification
)
83 "List of reasons why a notification has been closed.")
85 (defvar notifications-on-action-map nil
86 "Mapping between notification and action callback functions.")
88 (defvar notifications-on-close-map nil
89 "Mapping between notification and close callback functions.")
91 (defun notifications-on-action-signal (id action
)
92 "Dispatch signals to callback functions from `notifications-on-action-map'."
93 (let ((entry (assoc id notifications-on-action-map
)))
95 (funcall (cadr entry
) id action
)
96 (remove entry
'notifications-on-action-map
))))
100 notifications-service
102 notifications-interface
103 notifications-action-signal
104 'notifications-on-action-signal
)
106 (defun notifications-on-closed-signal (id reason
)
107 "Dispatch signals to callback functions from `notifications-on-closed-map'."
108 (let ((entry (assoc id notifications-on-close-map
)))
110 (funcall (cadr entry
)
111 id
(cadr (assoc reason notifications-closed-reason
)))
112 (remove entry
'notifications-on-close-map
))))
114 (dbus-register-signal
116 notifications-service
118 notifications-interface
119 notifications-closed-signal
120 'notifications-on-closed-signal
)
122 (defun notifications-notify (&rest params
)
123 "Send notification via D-Bus using the Freedesktop notification protocol.
124 Various PARAMS can be set:
126 :title The notification title.
127 :body The notification body text.
128 :app-name The name of the application sending the notification.
129 Default to `notifications-application-name'.
130 :replaces-id The notification ID that this notification replaces.
131 :app-icon The notification icon.
132 Default is `notifications-application-icon'.
133 Set to nil if you do not want any icon displayed.
134 :actions A list of actions in the form:
135 (KEY TITLE KEY TITLE ...)
136 where KEY and TITLE are both strings.
137 The default action (usually invoked by clicking the
138 notification) should have a key named \"default\".
139 The title can be anything, though implementations are free
141 :timeout The timeout time in milliseconds since the display
142 of the notification at which the notification should
144 If -1, the notification's expiration time is dependent
145 on the notification server's settings, and may vary for
146 the type of notification.
147 If 0, the notification never expires.
149 :urgency The urgency level.
150 Either `low', `normal' or `critical'.
151 :category The type of notification this is.
152 :desktop-entry This specifies the name of the desktop filename representing
154 :image-data This is a raw data image format which describes the width,
155 height, rowstride, has alpha, bits per sample, channels and
156 image data respectively.
157 :image-path This is represented either as a URI (file:// is the
158 only URI schema supported right now) or a name
159 in a freedesktop.org-compliant icon theme.
160 :sound-file The path to a sound file to play when the notification pops up.
161 :sound-name A themeable named sound from the freedesktop.org sound naming
162 specification to play when the notification pops up.
163 Similar to icon-name,only for sounds. An example would
164 be \"message-new-instant\".
165 :suppress-sound Causes the server to suppress playing any sounds, if it has
167 :x Specifies the X location on the screen that the notification
168 should point to. The \"y\" hint must also be specified.
169 :y Specifies the Y location on the screen that the notification
170 should point to. The \"x\" hint must also be specified.
171 :on-action Function to call when an action is invoked.
172 The notification id and the key of the action are passed
173 as arguments to the function.
174 :on-close Function to call when the notification has been closed
175 by timeout or by the user.
176 The function receive the notification id and the closing
178 - `expired' if the notification has expired
179 - `dismissed' if the notification was dismissed by the user
180 - `close-notification' if the notification was closed
181 by a call to CloseNotification
183 This function returns a notification id, an integer, which can be
184 used to manipulate the notification item with
185 `notifications-close'."
186 (let ((title (plist-get params
:title
))
187 (body (plist-get params
:body
))
188 (app-name (plist-get params
:app-name
))
189 (replaces-id (plist-get params
:replaces-id
))
190 (app-icon (plist-get params
:app-icon
))
191 (actions (plist-get params
:actions
))
192 (timeout (plist-get params
:timeout
))
195 (urgency (plist-get params
:urgency
))
196 (category (plist-get params
:category
))
197 (desktop-entry (plist-get params
:desktop-entry
))
198 (image-data (plist-get params
:image-data
))
199 (image-path (plist-get params
:image-path
))
200 (sound-file (plist-get params
:sound-file
))
201 (sound-name (plist-get params
:sound-name
))
202 (suppress-sound (plist-get params
:suppress-sound
))
203 (x (plist-get params
:x
))
204 (y (plist-get params
:y
))
208 (add-to-list 'hints
`(:dict-entry
210 (:variant
:byte
,(case urgency
215 (add-to-list 'hints
`(:dict-entry
217 (:variant
:string
,category
)) t
))
219 (add-to-list 'hints
`(:dict-entry
221 (:variant
:string
,desktop-entry
)) t
))
223 (add-to-list 'hints
`(:dict-entry
225 (:variant
:struct
,image-data
)) t
))
227 (add-to-list 'hints
`(:dict-entry
229 (:variant
:string
,image-path
)) t
))
231 (add-to-list 'hints
`(:dict-entry
233 (:variant
:string
,sound-file
)) t
))
235 (add-to-list 'hints
`(:dict-entry
237 (:variant
:string
,sound-name
)) t
))
239 (add-to-list 'hints
`(:dict-entry
241 (:variant
:boolean
,suppress-sound
)) t
))
243 (add-to-list 'hints
`(:dict-entry
"x" (:variant
:int32
,x
)) t
))
245 (add-to-list 'hints
`(:dict-entry
"y" (:variant
:int32
,y
)) t
))
247 ;; Call Notify method
249 (dbus-call-method :session
250 notifications-service
252 notifications-interface
253 notifications-notify-method
255 notifications-application-name
)
256 :uint32
(or replaces-id
0)
258 (expand-file-name app-icon
)
259 ;; If app-icon is nil because user
260 ;; requested it to be so, send the
262 (if (plist-member params
:app-icon
)
264 ;; Otherwise send the default icon path
265 notifications-application-icon
))
266 :string
(or title
"")
269 (or hints
'(:array
:signature
"{sv}"))
270 :int32
(or timeout -
1)))
272 ;; Register close/action callback function
273 (let ((on-action (plist-get params
:on-action
))
274 (on-close (plist-get params
:on-close
)))
276 (add-to-list 'notifications-on-action-map
(list id on-action
)))
278 (add-to-list 'notifications-on-close-map
(list id on-close
))))
280 ;; Return notification id
283 (defun notifications-close-notification (id)
284 "Close a notification with identifier ID."
285 (dbus-call-method :session
286 notifications-service
288 notifications-interface
289 notifications-close-notification-method
292 (provide 'notifications
)