Commit 9ff687e1 authored by Michael Albinus's avatar Michael Albinus
Browse files

* 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.
parent 66b907dc
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> 2012-04-01 Chong Yidong <cyd@gnu.org>
* files.texi (Kinds of Files): file-subdir-of-p renamed to * files.texi (Kinds of Files): file-subdir-of-p renamed to
......
...@@ -1390,6 +1390,8 @@ Operating System Interface ...@@ -1390,6 +1390,8 @@ Operating System Interface
* Batch Mode:: Running Emacs without terminal interaction. * Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with * Session Management:: Saving and restoring state with
X Session Management. X Session Management.
* Notifications:: Desktop notifications.
* Dynamic Libraries:: On-demand loading of support libraries.
Preparing Lisp code for distribution Preparing Lisp code for distribution
......
...@@ -35,6 +35,7 @@ terminal and the screen. ...@@ -35,6 +35,7 @@ terminal and the screen.
* X11 Keysyms:: Operating on key symbols for X Windows. * X11 Keysyms:: Operating on key symbols for X Windows.
* Batch Mode:: Running Emacs without terminal interaction. * Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with X Session Management. * Session Management:: Saving and restoring state with X Session Management.
* Notifications:: Desktop notifications.
* Dynamic Libraries:: On-demand loading of support libraries. * Dynamic Libraries:: On-demand loading of support libraries.
@end menu @end menu
...@@ -273,7 +274,7 @@ startup screen. ...@@ -273,7 +274,7 @@ startup screen.
@ignore @ignore
@c I do not think this should be mentioned. AFAICS it is just a dodge @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. @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 ignore
@end defopt @end defopt
...@@ -461,7 +462,7 @@ experimenting with your own peculiar customizations. ...@@ -461,7 +462,7 @@ experimenting with your own peculiar customizations.
You can also arrange to override some of the actions of the You can also arrange to override some of the actions of the
terminal-specific library by setting the variable terminal-specific library by setting the variable
@code{term-setup-hook}. This is a normal hook that Emacs runs @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 your init file and any terminal-specific libraries. You could
use this hook to define initializations for terminals that do not use this hook to define initializations for terminals that do not
have their own libraries. @xref{Hooks}. have their own libraries. @xref{Hooks}.
...@@ -2249,6 +2250,151 @@ Emacs is restarted by the session manager. ...@@ -2249,6 +2250,151 @@ Emacs is restarted by the session manager.
@end group @end group
@end example @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 @node Dynamic Libraries
@section Dynamically Loaded Libraries @section Dynamically Loaded Libraries
@cindex dynamic libraries @cindex dynamic libraries
......
...@@ -1412,6 +1412,8 @@ Operating System Interface ...@@ -1412,6 +1412,8 @@ Operating System Interface
* Batch Mode:: Running Emacs without terminal interaction. * Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with * Session Management:: Saving and restoring state with
X Session Management. X Session Management.
* Notifications:: Desktop notifications.
* Dynamic Libraries:: On-demand loading of support libraries.
Preparing Lisp code for distribution Preparing Lisp code for distribution
......
...@@ -1411,6 +1411,8 @@ Operating System Interface ...@@ -1411,6 +1411,8 @@ Operating System Interface
* Batch Mode:: Running Emacs without terminal interaction. * Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with * Session Management:: Saving and restoring state with
X Session Management. X Session Management.
* Notifications:: Desktop notifications.
* Dynamic Libraries:: On-demand loading of support libraries.
Preparing Lisp code for distribution Preparing Lisp code for distribution
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment