Lipstick

Графическая оболочка Lipstick реализует службу уведомлений рабочего стола на основе Спецификации уведомлений рабочего стола. Служба регистрируется как org.freedesktop.Notifications на сессионной шине D-Bus по пути /org/freedesktop/Notifications. Следует обратиться к спецификации для получения дополнительной информации о службе уведомлений.

• Примечания, относящиеся к поведению этой конкретной реализации
  • Неподдерживаемые элементы спецификации
  • Примечания о поведении
  • Возможности
  • Подсказки
• Как использовать уведомления в различных сценариях использования
  • Входящие сообщения чата
    • Отправка уведомления о первом входящем сообщении чата
    • Обновление уведомления для второго входящего сообщения чата
  • Временные уведомления
  • Использование файлов определения категорий

Примечания, относящиеся к поведению этой конкретной реализации

Неподдерживаемые элементы спецификации

• Некоторые дополнительные функции спецификации не поддерживаются: основной текст, содержащий разметку.
• Некоторые стандартные подсказки не поддерживаются:
  • action-icons;
  • desktop-entry;
  • x;
  • y.

Примечания о поведении

• Уведомления группируются по свойству 'appName'. Группу можно сжать или расширить, а также удалить вместе с элементами. Группа рассматривается как имеющая индивидуальные значения, эквивалентные комбинации уведомлений её участников.
• Уровень приоритета >= 100 приведёт к отображению группы уведомлений на экране блокировки устройства.
• Уведомления могут иметь режим предварительного просмотра в дополнение к их появлению на экране событий или вместо него. Предварительный просмотр отображается в виде краткого элемента поверх текущего приложения, содержание которого может отличаться от содержимого уведомления на экране событий.
• Используются две разные презентации предварительного просмотра: если предварительный просмотр имеет и сводку, и тело, или определено удалённое действие, то будет использоваться всплывающее окно с возможностью нажатия. В противном случае минимальный бегущий баннер ненадолго отобразит текст уведомления.
• Уровень срочности 2 (критический) приведёт к обработке предварительного просмотра уведомления, даже если на устройстве отображается список уведомлений, экран блокировки, запрос PIN-кода или если устройство заблокировано.
• Группа уведомлений может определять действие, которое будет вызываться для группы в дополнение к действиям отдельных уведомлений. Это действие должно иметь actionname "app", должно присутствовать и быть идентичным для каждого члена группы.

Возможности

• "persistence", которая позволяет постоянно сохранять уведомления.
• "body", которая позволяет уведомлениям содержать основной текст. См. параметр body для Notify().
• "actions", которая позволяет связывать действия с уведомлениями. Когда действие выполняется, отправляется сигнал ActionInvoked(). Однако для этого требуется, чтобы приложение, связанное с уведомлением, работало, чтобы могло получить сигнал. По этой причине служба также реализует возможность "x-nemo-remote-actions", которая позволяет связывать удалённые действия с уведомлениями. Когда такое действие выполняется, диспетчер уведомлений выполняет вызов D-Bus, определённый для действия. См. подсказку x-nemo-remote-action-actionname.
• "sound", которая позволяет изменять поведение звуковой обратной связи с помощью подсказок "sound-file" и "suppress-sound".
• Ряд расширений с помощью подсказок. Они указаны как возможности, и их использование описано в разделе «Подсказки».

Подсказки

• Подсказка "category" используется для загрузки определения для уведомлений в этой категории из /usr/share/lipstick/notificationcategories/categoryname.conf. Это позволяет определять общие свойства для всех уведомлений в каждой категории.
  • Каждый файл определения категории содержит список пар подсказка=значение, по одной в строке.
  • Каждая пара подсказка=значение в файле определения категории добавляется к подсказкам уведомления, если они ещё не определены.
• Сервис поддерживает следующие специфические подсказки Nemo:
  • x-nemo-item-count: например, одно уведомление может означать четыре пропущенных вызова, если установить счётчик на 4.
  • x-nemo-priority: приоритет уведомления как целое число. Приоритеты могут использоваться реализациями пользовательского интерфейса, например, для представления уведомлений в определённом порядке. Если не указано другое значение, уровень приоритета будет 50.
  • x-nemo-timestamp: отметка времени для уведомления. Следует установить время, когда произошло событие, с которым связано уведомление, а не время отправки самого уведомления.
  • x-nemo-preview-body: основной текст, который будет отображаться в баннере предварительного просмотра для уведомления, если таковой имеется.
  • x-nemo-preview-summary: сводный текст, который будет отображаться в баннере предварительного просмотра для уведомления, если таковой имеется.
  • x-nemo-remote-action-actionname: подробные сведения о вызове D-Bus, который должен быть сделан при выполнении действия "actionname". "actionname" должно быть указано в массиве actions уведомления. Требуемый формат — «serviceName objectPath interface methodName [argument...]», где каждый аргумент должен быть отдельно закодирован путем сериализации в QDataStream, а затем кодирования результирующей последовательности байтов в Base64.
  • x-nemo-visibility: конфиденциальность уведомления. В настоящее время позволяет «public» показывать уведомления даже на заблокированном устройстве, «private» и «secret», как в Android API, могут появиться позже, если это необходимо.
• Следующие подсказки используются системными уведомлениями и могут быть исключены из уведомлений приложений:
  • x-nemo-feedback: токен, используемый для создания заранее определённого события обратной связи при отображении предварительного просмотра уведомления;
  • x-nemo-display-on: если true, экран будет включаться при необходимости на время предварительного просмотра уведомления preview.
  • x-nemo-user-removable: логическое значение, определяющее, может ли пользователь удалить уведомление вручную. В противном случае его можно удалить только программно. По умолчанию true.

Как использовать уведомления в различных сценариях использования

Входящие сообщения чата

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

Примечание:

При выборе опции "Доступ к событиям, когда устройство заблокировано" в пункте настроек "Экран событий" на экране событий будут показываться уведомления с любыми значениями, указанными в полях x-nemo-priority и urgency.

Отправка уведомления о первом входящем сообщении чата

При вызове Notify() для отображения уведомления, относящегося к первому сообщению чата, параметры должны быть установлены следующим образом:

• app_name должно быть строкой, идентифицирующей приложение-отправитель, например, именем его двоичного файла. "chat";
• replaces_id должен быть равен 0, поскольку уведомление является новым и не связано с каким-либо существующим уведомлением;
• app_icon должен быть "icon-lock-chat", чтобы использовать иконку с этим идентификатором в области уведомлений. Можно оставить пустым; значки можно полностью обрабатывать с помощью подсказок уведомлений (см. ниже);
• summary должен содержать краткое описание уведомления, которое будет отображаться в области уведомлений, например «Иван Иванов»;
• body должен содержать информативный текст, относящийся к уведомлению, которое будет отображаться в области уведомлений, например «Привет!»;
• actions должен содержать список actionname, за которым следует необязательное отображаемое имя для каждого доступного действия, например ["default" ""];
• hints должен содержать следующее:
  • category должен иметь значение "im.received", чтобы отнести уведомление к категории мгновенного сообщения,
  • urgency должен быть 1 (нормальный), поскольку сообщения чата не имеют особого низкого или высокого приоритета,
  • x-nemo-preview-summary должен соответствовать тексту сводки ("Иван Иванов"), чтобы он также отображался на баннере предварительного просмотра,
  • x-nemo-preview-body должен соответствовать основному тексту («Привет!»), чтобы он также отображался на баннере предварительного просмотра,
  • x-nemo-timestamp должен быть установлен на время, когда сообщение чата было отправлено (или получено, в зависимости от предполагаемой логики приложения),
  • x-nemo-remote-action-default должен быть установлен на «org.example.chat / org.example.chat showMessage <encoded-message-id>», что вызовет вызов D-Bus с указанными деталями, когда уведомление нажимается, и вызывается действие с именем «default»;
• expire_timeout должен быть -1, чтобы позволить диспетчеру уведомлений выбрать подходящее время истечения.

Вызов Notify() вернёт идентификатор уведомления, который должен быть сохранён приложением, чтобы иметь возможность обновлять уведомление при поступлении других связанных сообщений чата.

Обновление уведомления для второго входящего сообщения чата

При вызове Notify() для отображения уведомления, относящегося ко второму сообщению чата, параметры должны быть установлены следующим образом:

• app_name должно быть строкой, идентифицирующей приложение-отправитель, например, именем его двоичного файла. "chat";
• replaces_id должен быть идентификатором уведомления, возвращаемым первым вызовом Notify(), чтобы обновить существующее уведомление;
• app_icon должен быть "icon-lock-chat", чтобы использовать иконку с этим идентификатором в области уведомлений. Можно оставить пустым. значки можно полностью обрабатывать c помощью подсказок уведомлений (см. ниже);
• summary должен содержать краткое описание уведомления, которое будет отображаться в области уведомлений, например «Иван Иванов»;
• body должен содержать информативный текст, относящийся к уведомлению, которое будет отображаться в области уведомлений, например «2 сообщения»;
• actions должен содержать список actionname, за которым следует необязательное отображаемое имя для каждого доступного действия, например ["default" ""];
• hints должен содержать следующее:
  • category должен иметь значение "im.received", чтобы отнести уведомление к категории мгновенного сообщения,
  • urgency должен быть 1 (нормальный), поскольку сообщения чата не имеют особого низкого или высокого приоритета,
  • x-nemo-item-count должен быть 2, чтобы уведомление представляло два сообщения чата,
  • x-nemo-preview-summary должен содержать краткое описание уведомления, которое будет отображаться на баннере предварительного просмотра, например «Иван Иванов»,
  • x-nemo-preview-body должен содержать информативный текст об уведомлении, которое будет отображаться на баннере предварительного просмотра, например «Вы здесь?»,
  • x-nemo-timestamp должен быть установлен на время, когда последнее сообщение чата было отправлено (или получено, в зависимости от предполагаемой логики приложения),
  • x-nemo-remote-action-default должен быть установлен как «org.example.chat / org.example.chat showMessagesFrom <encoded-contact-id>», что инициирует вызов D-Bus с указанными деталями, когда уведомление нажимается;
• expire_timeout должен быть -1, чтобы позволить диспетчеру уведомлений выбрать подходящее время истечения.

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

Временные уведомления

Временные уведомления аналогичны другим видам уведомлений, но поскольку они передают информацию, имеющую отношение только к отправке уведомления, они не должны отображаться в представлении событий. Для этого должны быть установлены только x-nemo-preview-summary и x-nemo-preview-body, body и summary уведомления следует оставить пустыми. Если уведомление предназначено только для информационных целей, оно не должно содержать удалённых действий и должно опускать свойство summary предварительного просмотра. В этом случае основной текст предварительного просмотра будет отображаться в минимальном баннере, чтобы не прерывать действия пользователя.

Если предполагается, что уведомление не будет присутствовать в представлении событий, оно должно установить для подсказки «transient» значение true. Это приведёт к его закрытию сразу после того, как оно будет показано пользователю.

При вызове Notify() для отображения временного уведомления параметры должны быть установлены следующим образом:

• app_name должно быть строкой, идентифицирующей приложение-отправитель, например, именем его двоичного файла. "batterynotifier";
• replaces_id должен быть равен 0, поскольку уведомление является новым и не связано с каким-либо существующим уведомлением;
• app_icon должен иметь значение «icon-battery-low», чтобы определить, что значок с этим идентификатором должен отображаться на баннере предварительного просмотра;
• summary следует оставить пустым, чтобы ничего не отображалось на экране просмотра событий;
• body следует оставить пустым, чтобы ничего не отображалось на экране просмотра событий;
• actions следует оставить пустым;
• hints должен содержать следующее:
  • category должен быть «device», чтобы отнести уведомление к категории устройства,
  • urgency должен быть 2 (критический), чтобы уведомление отображалось на экране блокировки,
  • transient должен быть истинным, чтобы автоматически закрывать уведомление после отображения,
  • x-nemo-preview-body должен быть «Батарея разряжена», чтобы отображать его на баннере предварительного просмотра;
• expire_timeout должен быть -1, чтобы позволить диспетчеру уведомлений выбрать подходящее время истечения.

Использование файлов определения категорий

Когда уведомления в определенной категории всегда имеют одни и те же подсказки, можно записать файл определения категории в /usr/share/lipstick/notificationcategories/categoryname.conf, а затем просто установить подсказку категории как categoryname при вызове Notify(). Файл определения категории содержит список пар подсказка=значение, по одной в строке. Каждая пара подсказка=значение в файле определения категории добавляется к подсказкам уведомления.

Например, если /usr/share/lipstick/notificationcategories/device.conf содержит

transient=true
urgency=2
app_icon=icon-battery-low

и Notify() вызывается со словарём подсказок, содержащим значение "device" для подсказки "category" и значение "Charging" для подсказки "x-nemo-preview-body", подсказки будут объединены, чтобы эффективные используемые подсказки были

category=device
transient=true
urgency=2
x-nemo-preview-body=Charging
app_icon=icon-battery-low

Также можно определить следующие свойства уведомления в файле определения категории:

• appName,
• appIcon,
• summary,
• body,
• expireTimeout.

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