* notifications.el (notifications-specification-version): Change to "1.2".

(notifications-notify): Add :action-items, :resident and
:transient hints.  Change "image_data" to "image-data" and
"image_path" to "image-path".
(notifications-get-capabilities): Return a list of keywords.

* os.texi (Notifications): Extend possible notification hints.

4 files changed, 90 insertions, 38 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 3bb2abd7cfe..1c37e1600f4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,6 +1,7 @@
 2012-04-24  Michael Albinus  <michael.albinus@gmx.de>
 
-        * os.texi: (Notifications): Add notifications-get-capabilities.
+        * os.texi (Notifications): Extend possible notification hints.
+        Add notifications-get-capabilities.
 
 2012-04-20  Chong Yidong  <cyd@gnu.org>
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 424cddaff0a..d825a3f18c4 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2271,7 +2271,7 @@ The notification title.
 @item :body @var{text}
 The notification body text.  Depending on the implementation of the
 notification server, the text could contain HTML markups, like
-@samp{"<b>bold text</b>"}, or hyperlinks.
+@samp{"<b>bold text</b>"}, hyperlinks, or images.
 
 @item :app-name @var{name}
 The name of the application sending the notification.  The default is
@@ -2301,6 +2301,10 @@ the notification never expires.  Default value is -1.
 @item :urgency @var{urgency}
 The urgency level.  It can be @code{low}, @code{normal}, or @code{critical}.
 
+@item :action-items 
+When this keyword is given, the @var{title} string of the actions is
+interpreted as icon name.
+
 @item :category @var{category}
 The type of notification this is, a string.
 
@@ -2331,6 +2335,17 @@ example would be @samp{"message-new-instant"}.
 Causes the server to suppress playing any sounds, if it has that
 ability.
 
+@item :resident
+When set the server will not automatically remove the notification
+when an action has been invoked. The notification will remain resident
+in the server until it is explicitly removed by the user or by the
+sender. This hint is likely only useful when the server has the
+@code{:persistence} capability.
+
+@item :transient
+When set the server will treat the notification as transient and
+by-pass the server's persistence capability, if it should exist.
+
 @item :x @var{position}
 @itemx :y @var{position}
 Specifies the X, Y location on the screen that the
@@ -2402,35 +2417,39 @@ This function closes a notification with identifier @var{id}.
 Returns the capabilities of the notification server, a list of strings.
 The following capabilities can be expected:
 
-@table @asis
-@item "actions"
+@table @code
+@item :actions
 The server will provide the specified actions to the user.
 
-@item "body"
+@item :body
 Supports body text.
 
-@item "body-hyperlinks"
+@item :body-hyperlinks
 The server supports hyperlinks in the notifications.
 
-@item "body-images"
+@item :body-images
 The server supports images in the notifications.
 
-@item "body-markup"
+@item :body-markup
 Supports markup in the body text.
 
-@item "icon-multi"
+@item :icon-multi
 The server will render an animation of all the frames in a given image
 array.
 
-@item "icon-static"
+@item :icon-static
 Supports display of exactly 1 frame of any given image array.  This
-value is mutually exclusive with "icon-multi".
+value is mutually exclusive with @code{:icon-multi}.
+
+@item :persistence
+The server supports persistence of notifications.
 
-@item "sound"
+@item :sound
 The server supports sounds on notifications.
 @end table
 
-Further vendor-specific caps start with "x-vendor", like "x-gnome-foo-cap".
+Further vendor-specific caps start with @code{:x-vendor}, like
+@code{:x-gnome-foo-cap}.
 @end defun
 
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 0eda6b28936..13d401b8413 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -22,10 +22,14 @@
 
 2012-04-24  Michael Albinus  <michael.albinus@gmx.de>
 
-        * notifications.el (notifications-interface)
-        (notifications-notify-method, notifications-notify)
+        * notifications.el (notifications-specification-version): Change
+        to "1.2".
+        (notifications-interface, notifications-notify-method)
         (notifications-close-notification-method): Fix docstring.
         (notifications-get-capabilities-method): New defconst.
+        (notifications-notify): Add :action-items, :resident and
+        :transient hints.  Change "image_data" to "image-data" and
+        "image_path" to "image-path".
         (notifications-get-capabilities): New defun.
 
 2012-04-24  Leo Liu  <sdl.web@gmail.com>
diff --git a/lisp/notifications.el b/lisp/notifications.el
index 9dad2a91b93..1b24f530c6d 100644
--- a/lisp/notifications.el
+++ b/lisp/notifications.el
@@ -23,7 +23,7 @@
 ;;; Commentary:
 
 ;; This package provides an implementation of the Desktop Notifications
-;; <http://www.galago-project.org/specs/notification/>.
+;; <http://developer.gnome.org/notification-spec/>.
 
 ;; In order to activate this package, you must add the following code
 ;; into your .emacs:
@@ -45,7 +45,7 @@
 
 (require 'dbus)
 
-(defconst notifications-specification-version "1.1"
+(defconst notifications-specification-version "1.2"
   "The version of the Desktop Notifications Specification implemented.")
 
 (defconst notifications-application-name "Emacs"
@@ -157,6 +157,8 @@ Various PARAMS can be set:
                  Default value is -1.
  :urgency        The urgency level.
                  Either `low', `normal' or `critical'.
+ :action-items   Whether the TITLE of the actions is interpreted as
+                 a named icon.
  :category       The type of notification this is.
  :desktop-entry  This specifies the name of the desktop filename representing
                  the calling program.
@@ -173,6 +175,11 @@ Various PARAMS can be set:
                  be \"message-new-instant\".
  :suppress-sound Causes the server to suppress playing any sounds, if it has
                  that ability.
+ :resident       When set the server will not automatically remove the
+                 notification when an action has been invoked.
+ :transient      When set the server will treat the notification as transient
+                 and by-pass the server's persistence capability, if it
+                 should exist. 
  :x              Specifies the X location on the screen that the notification
                  should point to.  The \"y\" hint must also be specified.
  :y              Specifies the Y location on the screen that the notification
@@ -212,9 +219,12 @@ of another `notifications-notify' call."
         (desktop-entry (plist-get params :desktop-entry))
         (image-data (plist-get params :image-data))
         (image-path (plist-get params :image-path))
+        (action-items (plist-get params :action-items))
         (sound-file (plist-get params :sound-file))
         (sound-name (plist-get params :sound-name))
         (suppress-sound (plist-get params :suppress-sound))
+        (resident (plist-get params :resident))
+        (transient (plist-get params :transient))
         (x (plist-get params :x))
         (y (plist-get params :y))
         id)
@@ -236,12 +246,16 @@ of another `notifications-notify' call."
                             (:variant :string ,desktop-entry)) t))
     (when image-data
       (add-to-list 'hints `(:dict-entry
-                            "image_data"
+                            "image-data"
                             (:variant :struct ,image-data)) t))
     (when image-path
       (add-to-list 'hints `(:dict-entry
-                            "image_path"
+                            "image-path"
                             (:variant :string ,image-path)) t))
+    (when action-items
+      (add-to-list 'hints `(:dict-entry
+                            "action-items"
+                            (:variant :boolean ,action-items)) t))
     (when sound-file
       (add-to-list 'hints `(:dict-entry
                             "sound-file"
@@ -254,6 +268,14 @@ of another `notifications-notify' call."
       (add-to-list 'hints `(:dict-entry
                             "suppress-sound"
                             (:variant :boolean ,suppress-sound)) t))
+    (when resident
+      (add-to-list 'hints `(:dict-entry
+                            "resident"
+                            (:variant :boolean ,resident)) t))
+    (when transient
+      (add-to-list 'hints `(:dict-entry
+                            "transient"
+                            (:variant :boolean ,transient)) t))
     (when x
       (add-to-list 'hints `(:dict-entry "x" (:variant :int32 ,x)) t))
     (when y
@@ -332,24 +354,30 @@ of another `notifications-notify' call."
   "Return the capabilities of the notification server, a list of strings.
 The following capabilities can be expected:
 
-  \"actions\"         The server will provide the specified actions
-                    to the user.
-  \"body\"            Supports body text.
-  \"body-hyperlinks\" The server supports hyperlinks in the notifications.
-  \"body-images\"     The server supports images in the notifications.
-  \"body-markup\"     Supports markup in the body text.
-  \"icon-multi\"      The server will render an animation of all the
-                    frames in a given image array.
-  \"icon-static\"     Supports display of exactly 1 frame of any
-                    given image array.  This value is mutually exclusive
-                    with \"icon-multi\".
-  \"sound\"           The server supports sounds on notifications.
-
-Further vendor-specific caps start with \"x-vendor\", like \"x-gnome-foo-cap\"."
-  (dbus-call-method :session
-                    notifications-service
-                    notifications-path
-                    notifications-interface
-                    notifications-get-capabilities-method))
+  `:actions'         The server will provide the specified actions
+                     to the user.
+  `:action-icons'    Supports using icons instead of text for
+                     displaying actions.
+  `:body'            Supports body text.
+  `:body-hyperlinks' The server supports hyperlinks in the notifications.
+  `:body-images'     The server supports images in the notifications.
+  `:body-markup'     Supports markup in the body text.
+  `:icon-multi'      The server will render an animation of all the
+                     frames in a given image array.
+  `:icon-static'     Supports display of exactly 1 frame of any
+                     given image array.  This value is mutually exclusive
+                     with `:icon-multi'.
+  `:persistence'     The server supports persistence of notifications.
+  `:sound'           The server supports sounds on notifications.
+
+Further vendor-specific caps start with `:x-vendor', like `:x-gnome-foo-cap'."
+  (dbus-ignore-errors
+   (mapcar
+    (lambda (x) (intern (concat ":" x)))
+    (dbus-call-method :session
+                      notifications-service
+                      notifications-path
+                      notifications-interface
+                      notifications-get-capabilities-method))))
 
 (provide 'notifications)