---

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

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>жирный текст</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. Если значение является строкой, функция интерпретирует его как имя файла и преобразует в абсолютное с помощью 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 "Сообщение %d, нажата клавиша \"%s\"" id key))
     ⇒ my-on-action-function

(defun my-on-close-function (id reason)
  (message "Сообщение %d, закрыто из-за \"%s\"" id reason))
     ⇒ my-on-close-function

(notifications-notify
 :title "Заголовок"
 :body "Это <b>важно</b>."
 :actions '("Confirm" "Я согласен" "Refuse" "Я не согласен")
 :on-action 'my-on-action-function
 :on-close 'my-on-close-function)
     ⇒ 22

На рабочем столе открывается окно сообщения. Нажмите «Я согласен».
     ⇒ Сообщение 22, нажата клавиша "Confirm"
        Сообщение 22, закрыто из-за "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.

Когда 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, он заменяется строкой ‘"Уведомления рабочего стола"’.

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

:icon icon

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

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

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

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