Уведомления рабочего стола

Emacs может отправлять уведомления в системах, поддерживающих спецификацию уведомлений рабочего стола freedesktop.org, MS-Windows, Haiku и Android.

Чтобы использовать эту функциональность на 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>bold text</b>"’, гиперссылки или изображения. Специальные символы HTML необходимо кодировать, например так: ‘"Contact &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. Если значение является строкой, функция интерпретирует его как имя файла и преобразует в абсолютный путь с помощью expand-file-name; если оно является символом, функция использует его имя (что удобно при использовании спецификации именования значков).

: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 (на данный момент поддерживается только схема URI ‘file://’), либо как имя в теме значков, совместимой с 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

Поддерживается отображение ровно одного кадра из любого заданного массива изображений. Это значение несовместимо с :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 notification’. Длина текста подсказки может составлять до 127 символов (63 символов в версиях Windows до W2K). Более длинные строки будут усечены.

:level level

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

:title title

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

:body body

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

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

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

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

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

Эта функция удаляет уведомление из трея по его уникальному идентификатору id. При удалении уведомления должен быть выбран тот же кадр Emacs, который был выбран при его создании. Программа на Lisp, показывающая уведомления, должна отслеживать соответствие кадров уведомлениям id и выбирать соответствующий кадр при удалении уведомления. (При удалении кадра созданное им уведомление, если оно есть, будет удалено MS-Windows.)

При запуске Emacs под Haiku в качестве графической программы также предоставляется ограниченная имитация ранее рассмотренного интерфейса уведомлений рабочего стола D-Bus. Среди основных возможностей, отсутствующих в описанной ниже функции, — функции обратного вызова, такие как :actions, :on-action и :on-close.

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

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

:title title

:body body

:replaces-id replaces-id

:urgency urgency

Имеют то же значение, что и при вызовах notifications-notify.

:app-icon app-icon

Должно быть именем файла изображения, которое будет использоваться в качестве значка отображаемого уведомления. Если задано nil, вместо него будет показан значок приложения Emacs.

Возвращаемое значение — число, идентифицирующее уведомление; его можно использовать в качестве параметра :replaces-id при последующем вызове этой функции.

Если Emacs собран в виде пакета приложения Android, отображение уведомлений обеспечивается функцией android-notifications-notify. Эта функция не поддерживает обратные вызовы и имеет ряд особенностей по сравнению с notifications-notify.

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

Эта функция отображает уведомление рабочего стола. params — список параметров, аналогичный одноимённому списку в notifications-notify. Параметры:

:title title

:body body

:replaces-id replaces-id

:on-action on-action

:on-cancel on-close

:actions actions

:timeout timeout

:resident resident

Имеют то же значение, что и при вызовах notifications-notify, за исключением того, что будет отображено не более трёх действий, отличных от действия по умолчанию.

:urgency urgency

Набор допустимых значений для urgency такой же, как и для notifications-notify, но уровень срочности применяется ко всем уведомлениям, отображаемым с заданной группой group, за исключением Android 7.1 и более ранних версий.

:group group

group — строка, обозначающая категорию, к которой будет относиться отправленное уведомление. Эта категория отображается в меню системных настроек уведомлений, но не используется в Android 7.1 и более ранних версиях.

Если group равно nil или отсутствует в params, вместо него используется строка ‘"Desktop Notifications"’.

Для каждого типа отправляемых уведомлений вызывающим программам следует использовать одну стабильную комбинацию значений urgency и group, поскольку система может проигнорировать urgency, если оно не совпадает со значением для какого-либо уведомления, ранее отправленного в группу group.

:icon icon

Этот параметр управляет символическим значком, с которым отображается уведомление. Его значение — строка, обозначающая значок в системном пакете android.R.drawable. Список таких значков см. в разделе R.drawable | Разработчики Android.

Если он не задан в params или значок icon не существует, по умолчанию используется ‘"ic_dialog_alert"’.

Функция возвращает число, идентифицирующее уведомление; его можно передать в качестве параметра :replaces-id при последующем вызове этой функции.

Если в Android 13 и более поздних версиях у Emacs нет разрешения на отображение уведомлений (см. раздел Среда Android в Руководстве GNU Emacs), все отправленные уведомления будут молча игнорироваться.