elisp: Desktop Notifications
38.19 Desktop Notifications
===========================
Emacs is able to send “notifications” on systems that support the
freedesktop.org Desktop Notifications Specification and on MS-Windows.
In order to use this functionality on Posix hosts, Emacs must have been
compiled with D-Bus support, and the ‘notifications’ library must be
loaded. 
D-Bus (dbus)Top. The following function is supported
when D-Bus support is available:
-- Function: notifications-notify &rest params
This function sends a notification to the desktop via D-Bus,
consisting of the parameters specified by the PARAMS arguments.
These arguments should consist of alternating keyword and value
pairs. The supported keywords and values are as follows:
‘:bus BUS’
The D-Bus bus. This argument is needed only if a bus other
than ‘:session’ shall be used.
‘:title TITLE’
The notification title.
‘:body TEXT’
The notification body text. Depending on the implementation
of the notification server, the text could contain HTML
markups, like ‘"<b>bold text</b>"’, hyperlinks, or images.
Special HTML characters must be encoded, as ‘"Contact
<postmaster@localhost>!"’.
‘:app-name NAME’
The name of the application sending the notification. The
default is ‘notifications-application-name’.
‘:replaces-id ID’
The notification ID that this notification replaces. ID must
be the result of a previous ‘notifications-notify’ call.
‘:app-icon ICON-FILE’
The file name of the notification icon. If set to ‘nil’, no
icon is displayed. The default is
‘notifications-application-icon’.
‘:actions (KEY TITLE KEY TITLE ...)’
A list of actions to be applied. KEY and TITLE are both
strings. The default action (usually invoked by clicking the
notification) should have a key named ‘"default"’. The title
can be anything, though implementations are free not to
display it.
‘:timeout 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.
‘:urgency URGENCY’
The urgency level. It can be ‘low’, ‘normal’, or ‘critical’.
‘:action-items’
When this keyword is given, the TITLE string of the actions is
interpreted as icon name.
‘:category CATEGORY’
The type of notification this is, a string. See the Desktop
Notifications Specification
(http://developer.gnome.org/notification-spec/#categories) for
a list of standard categories.
‘:desktop-entry FILENAME’
This specifies the name of the desktop filename representing
the calling program, like ‘"emacs"’.
‘:image-data (WIDTH HEIGHT ROWSTRIDE HAS-ALPHA BITS CHANNELS DATA)’
This is a raw data image format that describes the width,
height, rowstride, whether there is an alpha channel, bits per
sample, channels and image data, respectively.
‘:image-path PATH’
This is represented either as a URI (‘file://’ is the only URI
schema supported right now) or a name in a
freedesktop.org-compliant icon theme from
‘$XDG_DATA_DIRS/icons’.
‘:sound-file FILENAME’
The path to a sound file to play when the notification pops
up.
‘:sound-name NAME’
A themable named sound from the freedesktop.org sound naming
specification from ‘$XDG_DATA_DIRS/sounds’, to play when the
notification pops up. Similar to the icon name, only for
sounds. An example would 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. 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 ‘:persistence’
capability.
‘:transient’
When set the server will treat the notification as transient
and by-pass the server’s persistence capability, if it should
exist.
‘:x POSITION’
‘:y POSITION’
Specifies the X, Y location on the screen that the
notification should point to. Both arguments must be used
together.
‘:on-action FUNCTION’
Function to call when an action is invoked. The notification
ID and the KEY of the action are passed as arguments to the
function.
‘:on-close FUNCTION’
Function to call when the notification has been closed by
timeout or by the user. The function receive the notification
ID and the closing REASON as arguments:
• ‘expired’ if the notification has expired
• ‘dismissed’ if the notification was dismissed by the user
• ‘close-notification’ if the notification was closed by a
call to ‘notifications-close-notification’
• ‘undefined’ if the notification server hasn’t provided a
reason
Which parameters are accepted by the notification server can be
checked via ‘notifications-get-capabilities’.
This function returns a notification id, an integer, which can be
used to manipulate the notification item with
‘notifications-close-notification’ or the ‘:replaces-id’ argument
of another ‘notifications-notify’ call. For example:
(defun my-on-action-function (id key)
(message "Message %d, key \"%s\" pressed" id key))
⇒ my-on-action-function
(defun my-on-close-function (id reason)
(message "Message %d, closed due to \"%s\"" id reason))
⇒ my-on-close-function
(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)
⇒ 22
A message window opens on the desktop. Press ``I agree''.
⇒ Message 22, key "Confirm" pressed
Message 22, closed due to "dismissed"
-- Function: notifications-close-notification id &optional bus
This function closes a notification with identifier ID. BUS can be
a string denoting a D-Bus connection, the default is ‘:session’.
-- Function: notifications-get-capabilities &optional bus
Returns the capabilities of the notification server, a list of
symbols. BUS can be a string denoting a D-Bus connection, the
default is ‘:session’. 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’.
‘: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’.
-- Function: notifications-get-server-information &optional bus
Return information on the notification server, a list of strings.
BUS can be a string denoting a D-Bus connection, the default is
‘:session’. The returned list is ‘(NAME VENDOR VERSION
SPEC-VERSION)’.
NAME
The product name of the server.
VENDOR
The vendor name. For example, ‘"KDE"’, ‘"GNOME"’.
VERSION
The server’s version number.
SPEC-VERSION
The specification version the server is compliant with.
If SPEC_VERSION is ‘nil’, the server supports a specification prior
to ‘"1.0"’.
When Emacs runs on MS-Windows as a GUI session, it supports a small
subset of the D-Bus notifications functionality via a native primitive:
-- Function: w32-notification-notify &rest params
This function displays an MS-Windows tray notification as specified
by PARAMS. MS-Windows tray notifications are displayed in a
balloon from an icon in the notification area of the taskbar.
Value is the integer unique ID of the notification that can be used
to remove the notification using ‘w32-notification-close’,
described below. If the function fails, the return value is ‘nil’.
The arguments PARAMS are specified as keyword/value pairs. All the
parameters are optional, but if no parameters are specified, the
function will do nothing and return ‘nil’.
The following parameters are supported:
‘:icon ICON’
Display ICON in the system tray. If ICON is a string, it
should specify a file name from which to load the icon; the
specified file should be a ‘.ico’ Windows icon file. If ICON
is not a string, or if this parameter is not specified, the
standard Emacs icon will be used.
‘:tip TIP’
Use TIP as the tooltip for the notification. If TIP is a
string, this is the text of a tooltip that will be shown when
the mouse pointer hovers over the tray icon added by the
notification. If TIP is not a string, or if this parameter is
not specified, the default tooltip text is ‘Emacs
notification’. The tooltip text can be up to 127 characters
long (63 on Windows versions before W2K). Longer strings will
be truncated.
‘:level LEVEL’
Notification severity level, one of ‘info’, ‘warning’, or
‘error’. If given, the value determines the icon displayed to
the left of the notification title, but only if the ‘:title’
parameter (see below) is also specified and is a string.
‘:title TITLE’
The title of the notification. If TITLE is a string, it is
displayed in a larger font immediately above the body text.
The title text can be up to 63 characters long; longer text
will be truncated.
‘:body BODY’
The body of the notification. If BODY is a string, it
specifies the text of the notification message. Use embedded
newlines to control how the text is broken into lines. The
body text can be up to 255 characters long, and will be
truncated if it’s longer. Unlike with D-Bus, the body text
should be plain text, with no markup.
Note that versions of Windows before W2K support only ‘:icon’ and
‘:tip’. The other parameters can be passed, but they will be
ignored on those old systems.
There can be at most one active notification at any given time. An
active notification must be removed by calling
‘w32-notification-close’ before a new one can be shown.
To remove the notification and its icon from the taskbar, use the
following function:
-- Function: w32-notification-close id
This function removes the tray notification given by its unique ID.
Info Catalog
elisp: Session Management
elisp: System Interface
elisp: File Notifications