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>
* files.texi (Kinds of Files): file-subdir-of-p renamed to
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
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