Commit 9d439415 authored by Eli Zaretskii's avatar Eli Zaretskii

Implement tray notifications for MS-Windows

* src/w32fns.c (MY_NOTIFYICONDATAW): New typedef.
(NI_Severity): New enumeration.
(get_dll_version, utf8_mbslen_lim, add_tray_notification)
(delete_tray_notification, Fw32_notification_notify)
(Fw32_notification_close): New functions.
(syms_of_w32fns): Defsubr functions exposed to Lisp.  DEFSYM
keywords used by w32-notification-notify.

* doc/lispref/os.texi (Desktop Notifications): Describe the native
w32 tray notifications.
parent ef75c3b5
......@@ -2323,10 +2323,11 @@ Emacs is restarted by the session manager.
@cindex notifications, on desktop
Emacs is able to send @dfn{notifications} on systems that support the Desktop Notifications Specification. In order to use
this functionality, Emacs must have been compiled with D-Bus support,
and the @code{notifications} library must be loaded. @xref{Top, ,
D-Bus,dbus,D-Bus integration in Emacs}. 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 @code{notifications} library
must be loaded. @xref{Top, , D-Bus,dbus,D-Bus integration in Emacs}.
The following function is supported when D-Bus support is available:
@defun notifications-notify &rest params
This function sends a notification to the desktop via D-Bus,
......@@ -2559,6 +2560,85 @@ If @var{spec_version} is @code{nil}, the server supports a
specification prior to @samp{"1.0"}.
@end defun
@cindex tray notifications, MS-Windows
When Emacs runs on MS-Windows as a GUI session, it supports a small
subset of the D-Bus notifications functionality via a native
@defun w32-notification-notify &rest params
This function displays an MS-Windows tray notification as specified by
@var{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 @code{w32-notification-close}, described
below. If the function fails, the return value is @code{nil}.
The arguments @var{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 @code{nil}.
The following parameters are supported:
@table @code
@item :icon @var{icon}
Display @var{icon} in the system tray. If @var{icon} is a string, it
should specify a file name from which to load the icon; the specified
file should be a @file{.ico} Windows icon file. If @var{icon} is not
a string, or if this parameter is not specified, the standard Emacs
icon will be used.
@item :tip @var{tip}
Use @var{tip} as the tooltip for the notification. If @var{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
@var{tip} is not a string, or if this parameter is not specified, the
default tooltip text is @samp{Emacs notification}. The tooltip text can
be up to 127 characters long (63 on Windows versions before W2K).
Longer strings will be truncated.
@item :level @var{level}
Notification severity level, one of @code{info}, @code{warning}, or
@code{error}. If given, the value determines the icon displayed to the
left of the notification title, but only if the @code{:title} parameter
(see below) is also specified and is a string.
@item :timeout @var{timeout}
@var{timeout} is the time in seconds after which the notification
disappears. The value can be integer or floating-point. This is
ignored on Vista and later systems, where the duration is fixed at 9
sec and can only be customized via system-wide Accessibility settings.
@item :title @var{title}
The title of the notification. If @var{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.
@item :body @var{body}
The body of the notification. If @var{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.
@end table
Note that versions of Windows before W2K support only @code{:icon} and
@code{: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
@code{w32-notification-close} before a new one can be shown.
@end defun
To remove the notification and its icon from the taskbar, use the
following function:
@defun w32-notification-close id
This function removes the tray notification given by its unique
@end defun
@node File Notifications
@section Notifications on File Changes
@cindex file notifications
This diff is collapsed.
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