Alert is a Growl-workalike for Emacs which uses a common notification interface and multiple, selectable "styles", whose use is fully customizable by the user.
For desktop notifications, the notifications package that is installed with emacs, provides a probably better alternative for most users.
For module writers
Just use alert instead of message as follows:
(require 'alert)
;; This is the most basic form usage
(alert "This is an alert")
;; You can adjust the severity for more important messages
(alert "This is an alert" :severity 'high)
;; Or decrease it for purely informative ones
(alert "This is an alert" :severity 'trivial)
;; Alerts can have optional titles. Otherwise, the title is the
;; buffer-name of the (current-buffer) where the alert originated.
(alert "This is an alert" :title "My Alert")
;; Further, alerts can have categories. This allows users to
;; selectively filter on them.
(alert "This is an alert" :title "My Alert" :category 'debug)
;; If a backend allows replacing alerts, you may pass an id
;; to your alert; then the next one with the same id will replace the
;; first one:
(alert "You have 30 unread mails" :title "Mail!" :id 'new-mail-alert)
(alert "You have 49 unread mails" :title "Mail!" :id 'new-mail-alert)
;; This avoids piling up lots of alerts, when only the last one is
;; relevant.For users
For the user, there are several variables to control when and how alerts are presented. By default, they appear in the minibuffer much the same as a normal Emacs message. But there are many more possibilities:
-
alert-fade-timeNormally alerts disappear after this many seconds, if the style supports it. The default is 5 seconds. -
alert-default-stylePick the style to use if no other config rule matches. The default ismessage, butgrowlworks well too. -
alert-reveal-idle-timeIf a config rule choose to match onidle, this is how many seconds idle the user has to be. Defaults to 5 so that users don't miss any alerts, but 120 is also good. -
alert-persist-idle-timeAfter this many idle seconds, alerts will become sticky, and not fade away more. The default is 15 minutes. -
alert-log-messagesBy default, all alerts are logged to *Alerts* (and to *Messages*, if themessagestyle is being used). Set to nil to disable. -
alert-hide-all-notificationsWant alerts off entirely? They still get logged, however, unless you've turned that off too. -
alert-user-configurationThis variable lets you control exactly how and when a particular alert, a class of alerts, or all alerts, get reported -- or if at all. Use this to make some alerts use Growl, while others are completely silent.
Programmatically adding rules
Users can also programmatically add configuration rules, in addition to
customizing alert-user-configuration. Here is one that the author
currently uses with ERC, so that the fringe gets colored whenever people
chat on BitlBee:
(alert-add-rule :status '(buried visible idle)
:severity '(moderate high urgent)
:mode 'erc-mode
:predicate
#'(lambda (info)
(string-match (concat "\\`[^&].*@BitlBee\\'")
(erc-format-target-and/or-network)))
:persistent
#'(lambda (info)
;; If the buffer is buried, or the user has been
;; idle for `alert-reveal-idle-time' seconds,
;; make this alert persistent. Normally, alerts
;; become persistent after
;; `alert-persist-idle-time' seconds.
(memq (plist-get info :status) '(buried idle)))
:style 'fringe
:continue t)Builtin alert styles
There are several builtin styles, and it is trivial to create new ones. The builtins are:
| Name | Summary |
|---|---|
| fringe | Changes the current frame's fringe background color |
| mode-line | Changes the current frame's mode-line background color |
| gntp | Uses gntp, it requires gntp.el |
| growl | Uses Growl on OS X, if growlnotify is on the PATH |
| ignore | Ignores the alert entirely |
| libnotify | Uses libnotify if notify-send is on the PATH |
| log | Logs the alert text to Alerts, with a timestamp |
| message | Uses the Emacs message facility |
| notifications | Uses notifications library via D-Bus |
| notifier | Uses terminal-notifier on OS X, if it is on the PATH |
| osx-notifier | Native OSX notification using AppleScript |
| toaster | Use the toast notification system |
| x11 | Changes the urgency property of the window in the X Window System |
| termux | Use termux-notification from the Termux API |
Defining new styles
To create a new style, you need to at least write a notifier, which is
a function that receives the details of the alert. These details are
given in a plist which uses various keyword to identify the parts of the
alert. Here is a prototypical style definition:
(alert-define-style 'style-name :title "My Style's title"
:notifier
(lambda (info)
;; The message text is :message
(plist-get info :message)
;; The :title of the alert
(plist-get info :title)
;; The :category of the alert
(plist-get info :category)
;; The major-mode this alert relates to
(plist-get info :mode)
;; The buffer the alert relates to
(plist-get info :buffer)
;; Severity of the alert. It is one of:
;; `urgent'
;; `high'
;; `moderate'
;; `normal'
;; `low'
;; `trivial'
(plist-get info :severity)
;; Whether this alert should persist, or fade away
(plist-get info :persistent)
;; Data which was passed to `alert'. Can be
;; anything.
(plist-get info :data))
;; Removers are optional. Their job is to remove
;; the visual or auditory effect of the alert.
:remover
(lambda (info)
;; It is the same property list that was passed to
;; the notifier function.
))