* os.texi (Terminal-Specific): Fix typo.

(Notifications): New section.

* elisp.texi (Top):
* vol1.texi (Top):
* vol2.texi (Top): Add "Notifications" and "Dynamic Libraries"
menu entries.

5 files changed, 164 insertions, 2 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5fb4220d86a..c392cb6cf96 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2012-04-03  Michael Albinus  <michael.albinus@gmx.de>
+
+        * os.texi (Terminal-Specific): Fix typo.
+        (Notifications): New section.
+
+        * elisp.texi (Top):
+        * vol1.texi (Top):
+        * vol2.texi (Top): Add "Notifications" and "Dynamic Libraries"
+        menu entries.
+
 2012-04-01  Chong Yidong  <cyd@gnu.org>
 
         * files.texi (Kinds of Files): file-subdir-of-p renamed to
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index e3a92d42460..22fc5fac0f0 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1390,6 +1390,8 @@ Operating System Interface
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index ebf2a35925a..96221f328d6 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -35,6 +35,7 @@ terminal and the screen.
 * X11 Keysyms::         Operating on key symbols for X Windows.
 * Batch Mode::          Running Emacs without terminal interaction.
 * Session Management::  Saving and restoring state with X Session Management.
+* Notifications::       Desktop notifications.
 * Dynamic Libraries::   On-demand loading of support libraries.
 @end menu
 
@@ -273,7 +274,7 @@ startup screen.
 @ignore
 @c I do not think this should be mentioned.  AFAICS it is just a dodge
 @c around inhibit-startup-screen not being settable on a site-wide basis.
-If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. 
+If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.
 @end ignore
 @end defopt
 
@@ -461,7 +462,7 @@ experimenting with your own peculiar customizations.
   You can also arrange to override some of the actions of the
 terminal-specific library by setting the variable
 @code{term-setup-hook}.  This is a normal hook that Emacs runs
-at the end its initialization, after loading both
+at the end of its initialization, after loading both
 your init file and any terminal-specific libraries.  You could
 use this hook to define initializations for terminals that do not
 have their own libraries.  @xref{Hooks}.
@@ -2249,6 +2250,151 @@ Emacs is restarted by the session manager.
 @end group
 @end example
 
+@node Notifications
+@section Desktop Notifications
+@cindex desktop notifications
+
+Emacs is able to send notifications on systems which support the
+desktop notification specification of freedesktop.org.  In order to
+use this functionality, the package @code{notifications} must be loaded.
+
+@defun notifications-notify &rest params
+This function sends a notification to the desktop via D-Bus.
+Various @var{params} can be set, none of them is mandatory:
+
+@table @code
+@item :title @var{title}
+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.
+
+@item :app-name @var{name}
+The name of the application sending the notification. Default is
+@code{notifications-application-name}.
+
+@item :replaces-id @var{id}
+The notification @var{id} that this notification replaces.  @var{id}
+must be the result of a previous @code{notifications-notify} call.
+
+@item :app-icon @var{icon-file}
+The file name of the notification icon.  If set to @code{nil}, no icon
+is displayed. Default is @code{notifications-application-icon}.
+
+@item :actions (@var{key} @var{title} @var{key} @var{title} ...)
+A list of actions to be applied.  @var{key} and @var{title} are both
+strings.  The default action (usually invoked by clicking the
+notification) should have a key named @samp{"default"}.  The title can
+be anything, though implementations are free not to display it.
+
+@item :timeout @var{timeout}
+The timeout time in milliseconds since the display of the notification
+at which the notification should automatically close.  If -1, the
+notification's expiration time is dependent on the notification
+server's settings, and may vary for the type of notification.  If 0,
+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 :category @var{category}
+The type of notification this is, a string.
+
+@item :desktop-entry @var{filename}
+This specifies the name of the desktop filename representing the
+calling program, like @samp{"emacs"}.
+
+@item :image-data (@var{width} @var{height} @var{rowstride} @var{has-alpha} @var{bits} @var{channels} @var{data})
+This is a raw data image format which describes the width, height,
+rowstride, has alpha, bits per sample, channels and image data
+respectively.
+
+@item :image-path @var{path}
+This is represented either as a URI (@samp{file://} is the only URI
+schema supported right now) or a name in a freedesktop.org-compliant
+icon theme from @samp{$XDG_DATA_DIRS/icons}, like @samp{"mail-message-new"}.
+
+@item :sound-file @var{filename}
+The path to a sound file to play when the notification pops up.
+
+@item :sound-name @var{name}
+A themable named sound from the freedesktop.org sound naming
+specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the
+notification pops up.  Similar to the icon name, only for sounds. An
+example would be @samp{"message-new-instant"}.
+
+@item :suppress-sound
+Causes the server to suppress playing any sounds, if it has that
+ability.
+
+@item :x @var{position}
+@itemx :y @var{position}
+Specifies the X respectively Y location on the screen that the
+notification should point to.  Both arguments must be used together.
+
+@item :on-action @var{function}
+Function to call when an action is invoked.  The notification @var{id}
+and the @var{key} of the action are passed as arguments to the
+function.
+
+@item :on-close @var{function}
+Function to call when the notification has been closed by timeout or
+by the user.  The function receive the notification @var{id} and the closing
+@var{reason} as arguments:
+
+@itemize
+@item @code{expired} if the notification has expired
+@item @code{dismissed} if the notification was dismissed by the user
+@item @code{close-notification} if the notification was closed by a call to
+@code{notifications-close-notification}
+@item @code{undefined} if the notification server hasn't provided a reason
+@end itemize
+@end table
+
+This function returns a notification id, an integer, which can be used
+to manipulate the notification item with
+@code{notifications-close-notification} or the @code{:replaces-id}
+argument of another @code{notifications-notify} call.
+
+Example:
+
+@example
+@group
+(defun my-on-action-function (id key)
+  (message "Message %d, key \"%s\" pressed" id key))
+     @result{} my-on-action-function
+@end group
+
+@group
+(defun my-on-close-function (id reason)
+  (message "Message %d, closed due to \"%s\"" id reason))
+     @result{} my-on-close-function
+@end group
+
+@group
+(notifications-notify
+ :title "Title"
+ :body "This is <b>important</b>."
+ :actions '("Confirm" "I agree" "Refuse" "I disagree")
+ :on-action 'my-on-action-function
+ :on-close 'my-on-close-function)
+     @result{} 22
+@end group
+
+@group
+A message window opens on the desktop.  Press "I agree"
+     @result{} Message 22, key "Confirm" pressed
+        Message 22, closed due to "dismissed"
+@end group
+@end example
+@end defun
+
+@defun notifications-close-notification id
+This function closes a notification with identifier ID.
+@end defun
+
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries
 @cindex dynamic libraries
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index f2cbb18af1c..a4af27cf279 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -1412,6 +1412,8 @@ Operating System Interface
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 837fcbe7f59..af4e455788d 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -1411,6 +1411,8 @@ Operating System Interface
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
+* Notifications::           Desktop notifications.
+* Dynamic Libraries::       On-demand loading of support libraries.
 
 Preparing Lisp code for distribution