QML-тип Notification

Разрешает публикацию уведомлений Подробнее...

Строка импорта: import Nemo.Notifications 1.0
Создает экземпляр: Notification

Свойства

Сигналы

Методы

Подробное описание

Тип Notification представляет собой удобный способ работы с уведомлениями. Тип основан на спецификации уведомлений рабочего стола (Desktop Notifications Specification), реализованной в Nemo.

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

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

Ниже приведен простой пример использования типа Notification в приложении QML:

 Button {
     Notification {
         id: notification

         summary: "Краткие сведения об уведомлении"
         body: "Тело уведомления"
         onClicked: console.log("Нажато")
     }
     text: "Уведомление приложения" + (notification.replacesId ? " ID:" + notification.replacesId : "")
     onClicked: notification.publish()
 }

При нажатии на кнопку новое уведомление публикуется в диспетчере уведомлений. Свойства этого уведомления задаются в определении объекта типа Notification. Все свойства, заданные в файле определения категории, будут автоматически применены диспетчером уведомлений во время публикации. Диспетчер выделяет идентификатор для уведомления, который записывается в свойство replacesId.

Когда пользователь вызывает дистанционное действие 'default' для уведомления, экземпляр этого уведомления испускает сигнал clicked. Если в это время приложение уже не работает, данный сигнал может быть пропущен.

Ниже приведен расширенный пример использования типа Notification в приложении QML:

 Button {
     Notification {
         id: notification
         category: "x-nemo.example"
         appName: "Пример приложения"
         appIcon: "/usr/share/example-app/icon-l-application"
         summary: "Краткие сведения об уведомлении"
         body: "Тело уведомления"
         previewSummary: "Краткие сведения о предварительном просмотре уведомления"
         previewBody: "Тело предварительного просмотра уведомления"
         itemCount: 5
         timestamp: "2013-02-20 18:21:00"
         remoteActions: [ {
             "name": "default",
             "displayName": "Сделать что-то",
             "icon": "icon-s-сделать-что-то",
             "service": "org.nemomobile.example",
             "path": "/example",
             "iface": "org.nemomobile.example",
             "method": "doSomething",
             "arguments": [ "argument", 1 ]
         },{
             "name": "ignore",
             "displayName": "Игнорировать проблему",
             "icon": "icon-s-игнорировать",
             "service": "org.nemomobile.example",
             "path": "/example",
             "iface": "org.nemomobile.example",
             "method": "ignore",
             "arguments": [ "argument", 1 ]
         } ]
         onClicked: console.log("Нажато")
         onClosed: console.log("Закрыто, причина: " + reason)
     }
     text: "Уведомление приложения" + (notification.replacesId ? " ID:" + notification.replacesId : "")
     onClicked: notification.publish()
 }

В данном примере в уведомлении описана спецификация дистанционных действий. Эти действия представляют собой команды D-Bus, которые диспетчер уведомлений может разрешить вызвать пользователю. (Следует обратить внимание, что на текущий момент графическая оболочка Lipstick поддерживает только вызов дистанционного действия с названием "default"). При вызове дистанционного действия над уведомлением составляется и вызывается соответствующая команда D-Bus. Таким образом, например, может быть запущено приложение для обработки действия над уведомлением.

Описание свойств

appIcon : string

Значок приложения, с которым связано уведомление. Значением свойства может быть либо URI, либо абсолютный путь к файлу, либо токен, интерпретируемый объектом Theme.

Данное свойство транслируется как параметр "app_icon" метода Notify.

appName : string

Отображаемое название приложения, с которым связано уведомление.

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

Данное свойство транслируется как параметр "app_name" метода Notify.

body : string

Необязательный текст тела уведомления.

Данное свойство транслируется как параметр "body" метода Notify.

category : string

Категория, чьи свойства должны применяться к уведомлению с помощью диспетчера уведомлений.

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

Данное свойство транслируется как значение стандартной подсказки "category". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

expireTimeout : int

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

Значение по умолчанию: -1.

Данное свойство транслируется как параметр "expire_timeout" метода Notify.

icon : string

Значок уведомления. Значением свойства может быть либо URI, либо абсолютный путь к файлу, либо токен, интерпретируемый объектом Theme.

В зависимости от реализации платформы, данное свойство может иметь приоритет на свойством appIcon.

Данное свойство транслируется как значение расширенной подсказки "x-nemo-icon". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

isTransient : int

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

Данное свойство транслируется как значение стандартной подсказки "transient". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

itemCount : int

Количество элементов, представляемых в уведомлении. Например, в одном уведомлении может сообщаться о четырех пропущенных звонках. Для этого значение данного свойство необходимо установить равным 4. Значение по умолчанию: 1.

Данное свойство транслируется как значение расширенной подсказки "x-nemo-item-count". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

maxContentLines : int

Данное свойство определяет максимальное число строк содержимого, отображаемого в уведомлении. В это число входит строка с краткими сведениями об уведомлении. Если уведомление состоит из одной строки, то тело уведомления не отображается.

Данное свойство транслируется как значение расширенной подсказки "x-nemo-max-content-lines". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

previewBody : string

Текст тела, показываемый в области предварительного просмотра уведомления.

Если свойствам previewSummary или previewBody заданы значения, то при публикации уведомления графическая оболочка Lipstick создаст для него область предварительного просмотра (при условии, что предварительный просмотр уведомлений не запрещен в диспетчере уведомлений).

Данное свойство транслируется как значение расширенной подсказки "x-nemo-preview-body". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

previewSummary : string

Текст кратких сведений, показываемый в области предварительного просмотра уведомления.

Если свойствам previewSummary или previewBody заданы значения, то при публикации уведомления графическая оболочка Lipstick создаст для него область предварительного просмотра (при условии, что предварительный просмотр уведомлений не запрещен в диспетчере уведомлений).

Данное свойство транслируется как значение расширенной подсказки "x-nemo-preview-summary". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

remoteActions : list

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

Дистанционные действия указываются в виде списка объектов с обязательными свойствами 'name', 'service', 'path', 'iface' и 'method', а также необязательными свойствами 'displayName', 'icon' и 'arguments'.

Например:

 Notification {
     remoteActions: [ {
         "name": "default",
         "displayName": "Сделать что-то",
         "icon": "icon-s-сделать-что-то",
         "service": "org.nemomobile.example",
         "path": "/example",
         "iface": "org.nemomobile.example",
         "method": "doSomething",
         "arguments": [ "аргумент", 1 ]
     } ]
 }

Примечание: текущая реализация графической оболочки Lipstick вызовет действие с названием "default" при активации пользователем отдельного уведомления. Если пользователь активирует группу уведомлений, будет вызвано действие с названием "app" при условии, что данное действие распространяется на всех пользователей группы.

Данное свойство транслируется как параметр "actions" метода Notify и как значение расширенной подсказки "x-nemo-remote-action-". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

replacesId : int

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

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

Данное свойство транслируется как параметр "replaces_id" метода Notify.

summary : string

Текст, кратко описывающий уведомление. Это краткое описание должно умещаться в одну строку.

Данное свойство транслируется как параметр "summary" метода Notify.

timestamp : date

Отметка времени обычно связывается с событием, к которому относится уведомление, а не со временем создания самого уведомления. Если значение свойства не задано, то отметкой времени уведомления будет время публикации этого уведомления.

Данное свойство транслируется как значение расширенной подсказки "x-nemo-timestamp". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

urgency : enumeration

Уровень срочности уведомления. Данное свойство может принимать одно из следующих значений:

  • Notification.Low - низкий уровень срочности;
  • Notification.Normal - обычный уровень срочности;
  • Notification.Critical - критический уровень срочности.

Уровень срочности интерпретируется диспетчером уведомлений во время публикации. Например, в зависимости от текущей активности пользователя или состояния устройства, диспетчер может показывать или блокировать уведомления. При этом, уведомления с уровнем срочности Critical будут показаны с большей степенью вероятности и с большим приоритетом.

Значение по умолчанию: Notification.Normal.

Данное свойство транслируется как значение стандартной подсказки "urgency". Подсказки (hints) - это дополнительные необязательные данные, передаваемые на сервер уведомлений.

Описание сигналов

clicked()

Испускается при изменении активации уведомления пользователем.

Обработка сигнала clicked имеет смысл только в том случае, когда пользователь активирует уведомление, что может произойти спустя достаточно продолжительное время после публикации уведомления. Более продвинутым решением будет зарегистрировать дистанционное действие в диспетчере уведомлений с тем, чтобы можно было вызвать обработчик запроса.

См. также Notification::remoteActions.

closed(uint reason)

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

  • Notification.Expired - срок действия уведомления истек;
  • Notification.DismissedByUser - уведомление отклонено пользователем;
  • Notification.Closed - уведомление закрыто.

Описание методов

void close()

Закрывает уведомление с идентификатором replacesId.

void publish()

Публикует текущее состояние уведомления в диспетчере уведомлений.

Если значением свойства replacesId является 0, будет создано новое уведомление, а значение свойства replacesId будет обновлено этим идентификатором. В противном случае будет обновлено существующее уведомление с заданным идентификатором.