Рабочие уведомления

Emacs может отправлять уведомления на системах, поддерживающих спецификацию freedesktop.org Рабочие уведомления, и на MS-Windows. Для использования этой функциональности на хостах POSIX Emacs должен быть скомпилирован с поддержкой D-Bus, и должна быть загружена библиотека notifications. См. D-Bus в Интеграция D-Bus в Emacs. Следующая функция поддерживается при наличии поддержки D-Bus:

Функция: notifications-notify &rest params

Эта функция отправляет уведомление на рабочий стол через D-Bus, состоящее из параметров, указанных аргументами params. Эти аргументы должны состоять из чередующихся пар ключевое слово и значение. Поддерживаемые ключевые слова и значения следующие:

:bus bus

Шина D-Bus. Этот аргумент необходим только если используется шина, отличная от :session.

:title title

Заголовок уведомления.

:body text

Текст тела уведомления. В зависимости от реализации сервера уведомлений, текст может содержать HTML-разметку, например, ‘"<b>жирный текст</b>"’, гиперссылки или изображения. Специальные HTML-символы должны быть закодированы, как ‘"Свяжитесь с &lt;postmaster@localhost&gt;!"’.

:app-name name

Имя приложения, отправляющего уведомление. По умолчанию notifications-application-name.

:replaces-id id

Идентификатор id уведомления, которое заменяется этим уведомлением. id должен быть результатом предыдущего вызова notifications-notify.

:app-icon icon-file

Имя файла значка уведомления. Если установлено значение nil, значок не отображается. По умолчанию notifications-application-icon.

:actions (key title key title ...)

Список действий, которые необходимо применить. key и title оба являются строками. Действие по умолчанию (обычно вызываемое щелчком по уведомлению) должно иметь ключ, именованный ‘"default"’. Заголовок может быть любым, хотя реализации могут его не отображать.

:timeout timeout

Время таймаута в миллисекундах с момента отображения уведомления, по истечении которого уведомление должно автоматически закрыться. Если -1, время истечения уведомления зависит от настроек сервера уведомлений и может отличаться для типа уведомления. Если 0, уведомление никогда не истекает. Значение по умолчанию -1.

:urgency urgency

Уровень срочности. Может быть low, normal, или critical.

:action-items

Когда это ключевое слово задано, строка title действий интерпретируется как имя значка.

:category category

Тип уведомления, строка. См. Спецификацию рабочих уведомлений для списка стандартных категорий.

:desktop-entry filename

Указывает имя файла рабочего стола, представляющее вызывающую программу, например, ‘"emacs"’.

:image-data (width height rowstride has-alpha bits channels data)

Это формат изображения с необработанными данными, который описывает ширину, высоту, строку, есть ли альфа-канал, количество бит на образец, каналы и данные изображения соответственно.

:image-path path

Представлено либо как URI (‘file://’ — единственная поддерживаемая схема URI на данный момент), либо как имя в совместимой с freedesktop.org теме значков из ‘$XDG_DATA_DIRS/icons’.

:sound-file filename

Путь к файлу звука, который должен воспроизводиться при появлении уведомления.

:sound-name name

Настраиваемое именованное звуковое объявление из спецификации именования звука freedesktop.org из ‘$XDG_DATA_DIRS/sounds’, чтобы воспроизводиться при появлении уведомления. Аналогично имени значка, только для звуков. Примером может служить ‘"message-new-instant"’.

:suppress-sound

Приводит к тому, что сервер подавляет воспроизведение звуков, если у него есть такая возможность.

:resident

Если установлено, сервер не будет автоматически удалять уведомление при вызове действия. Уведомление останется на сервере до тех пор, пока оно не будет явно удалено пользователем или отправителем. Эта подсказка, вероятно, полезна только тогда, когда у сервера есть возможность :persistence.

:transient

При установке сервер будет рассматривать уведомление как временное и обойдёт возможности сохранения сервера, если они должны существовать.

:x position

:y position

Указывает положение X, Y на экране, к которому должно указывать уведомление. Оба аргумента должны использоваться вместе.

:on-action function

Функция, вызываемая при вызове действия. Идентификатор уведомления id и ключ key действия передаются в качестве аргументов функции.

:on-close function

Функция, вызываемая при закрытии уведомления по таймауту или пользователем. Функция получает идентификатор уведомления id и причину закрытия reason в качестве аргументов:

• expired если уведомление истекло
• dismissed если уведомление было закрыто пользователем
• close-notification если уведомление было закрыто вызовом notifications-close-notification
• undefined если сервер уведомлений не предоставил причину

Какие параметры принимаются сервером уведомлений можно проверить с помощью notifications-get-capabilities.

Эта функция возвращает идентификатор уведомления, целое число, которое может быть использовано для управления элементом уведомления с помощью notifications-close-notification или аргумента :replaces-id другого вызова notifications-notify. Например:

(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"

Функция: notifications-close-notification id &optional bus

Эта функция закрывает уведомление с идентификатором id. bus может быть строкой, обозначающей соединение D-Bus, по умолчанию :session.

Функция: notifications-get-capabilities &optional bus

Возвращает возможности сервера уведомлений, список символов. bus может быть строкой, обозначающей соединение D-Bus, по умолчанию :session. Ожидаются следующие возможности:

:actions

Сервер предоставит пользователю указанные действия.

:body

Поддерживает текст тела.

:body-hyperlinks

Сервер поддерживает гиперссылки в уведомлениях.

:body-images

Сервер поддерживает изображения в уведомлениях.

:body-markup

Поддерживает разметку в тексте тела.

:icon-multi

Сервер будет рендерить анимацию всех кадров в заданном массиве изображений.

:icon-static

Сервер поддерживает отображение ровно 1 кадра любого заданного массива изображений. Это значение взаимоисключает :icon-multi.

:persistence

Сервер поддерживает сохранение уведомлений.

:sound

Сервер поддерживает звуки в уведомлениях.

Дополнительные возможности, специфичные для поставщика, начинаются с :x-vendor, например, :x-gnome-foo-cap.

Функция: notifications-get-server-information &optional bus

Возвращает информацию о сервере уведомлений, список строк. bus может быть строкой, обозначающей соединение D-Bus, по умолчанию :session. Возвращаемый список (name vendor version spec-version).

name

Имя продукта сервера.

vendor

Имя поставщика. Например, ‘"KDE"’, ‘"GNOME"’.

version

Номер версии сервера.

spec-version

Версия спецификации, с которой сервер совместим.

Если spec_version равно nil, сервер поддерживает спецификацию, предшествующую ‘"1.0"’.

Когда Emacs работает на MS-Windows как сеанс графического интерфейса, он поддерживает небольшой поднабор функциональности уведомлений D-Bus через собственный примитив:

Функция: w32-notification-notify &rest params

Данная функция отображает системное уведомление MS-Windows, как указано в params. Уведомления MS-Windows отображаются в виде всплывающего окна от значка в области уведомлений панели задач.

Значение — уникальный целочисленный идентификатор уведомления, который может быть использован для удаления уведомления с помощью w32-notification-close, описанного ниже. В случае ошибки функция возвращает nil.

Аргументы params задаются в виде пар «ключ/значение». Все параметры необязательны, но если параметры не указаны, функция ничего не сделает и вернёт nil.

Поддерживаются следующие параметры:

:icon icon

Отобразить icon в области уведомлений. Если icon — строка, она должна указывать имя файла, из которого загрузить значок; указанный файл должен быть файлом значка Windows .ico. Если icon не является строкой или этот параметр не указан, будет использован стандартный значок Emacs.

:tip tip

Использовать tip в качестве всплывающей подсказки для уведомления. Если tip — строка, это текст всплывающей подсказки, который будет отображаться при наведении курсора на значок в области уведомлений, добавленный уведомлением. Если tip не является строкой или этот параметр не указан, используется текст всплывающей подсказки по умолчанию «Уведомление Emacs». Текст всплывающей подсказки может содержать до 127 символов (63 на версиях Windows до W2K). Более длинные строки будут усечены.

:level level

Уровень серьёзности уведомления, один из info, warning, или error. Если указано, это значение определяет значок, отображаемый слева от заголовка уведомления, но только если также указан параметр :title (см. ниже) и он является строкой.

:title title

Заголовок уведомления. Если title — строка, она отображается крупным шрифтом непосредственно над текстом тела. Текст заголовка может содержать до 63 символов; более длинный текст будет усечён.

:body body

Тело уведомления. Если body — строка, она определяет текст сообщения уведомления. Используйте встроенные переводы строк для управления тем, как текст разбивается на строки. Текст тела может содержать до 255 символов и будет усечен, если он длиннее. В отличие от D-Bus, текст тела должен быть текстом без форматирования.

Обратите внимание, что версии Windows до W2K поддерживают только :icon и :tip. Другие параметры могут быть переданы, но будут проигнорированы на старых системах.

Одновременно может быть не более одного активного уведомления. Активное уведомление необходимо удалить, вызвав w32-notification-close, прежде чем можно будет отобразить новое.

Для удаления уведомления и его значка из панели задач используйте следующую функцию:

Функция: w32-notification-close id

Эта функция удаляет системное уведомление, заданное его уникальным id.