QML-тип Notification

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

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

Свойства

appIcon : string
appName : string
body : string
category : string
expireTimeout : int
icon : string
iconData : image
isTransient : bool
itemCount : int
maxContentLines : int
previewBody : string
previewSummary : string
progress : var
remoteActions : list<variant>
replacesId : int
sound : string
subText : string
summary : string
suppressSound : int
timestamp : date
urgency : enumeration

Сигналы

actionInvoked(string name)
clicked()
closed(uint reason)

Методы

void close()
void publish()

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

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

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

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

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

 Button {
     Notification {
         id: notification

         summary: "Notification summary"
         body: "Notification body"
     }
     text: "Application notification" + (notification.replacesId ? " ID:" + notification.replacesId : "")
     onClicked: notification.publish()
 }

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

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

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

 Button {
     Notification {
         id: notification
         category: "x-nemo.example"
         appName: "Example App"
         appIcon: "/usr/share/example-app/icon-l-application"
         summary: "Notification summary"
         body: "Notification body"
         previewSummary: "Notification preview summary"
         previewBody: "Notification preview body"
         itemCount: 5
         timestamp: "2013-02-20 18:21:00"
         remoteActions: [ {
             "name": "default",
             "displayName": "Do something",
             "icon": "icon-s-do-it",
             "service": "org.nemomobile.example",
             "path": "/example",
             "iface": "org.nemomobile.example",
             "method": "doSomething",
             "arguments": [ "argument", 1 ]
         },{
             "name": "ignore",
             "displayName": "Ignore the problem",
             "icon": "icon-s-ignore",
             "input" : {
                 "label": "Please select",
                 "editable": true,
                 "choices": [ "Yes", "No", "Maybe" ]
             },
             "service": "org.nemomobile.example",
             "path": "/example",
             "iface": "org.nemomobile.example",
             "method": "ignore",
             "arguments": [ "argument", 1 ]
         } ]
         onClicked: console.log("Clicked")
         onClosed: console.log("Closed, reason: " + reason)
     }
     text: "Application notification" + (notification.replacesId ? " ID:" + notification.replacesId : "")
     onClicked: notification.publish()
 }

В данном примере в уведомлении описана спецификация дистанционных действий. Эти действия представляют собой команды D-Bus, которые диспетчер уведомлений может разрешить вызвать пользователю. При вызове дистанционного действия над уведомлением составляется и вызывается соответствующая команда 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.

В качестве альтернативы свойство iconData может использоваться для установки декодированного изображения.

Данное свойство транслируется как значение стандартной подсказки "image-path".

iconData : image

Изображение, которое будет отображаться в уведомлении. Следует обратить внимание, что для этого требуется типизированное значение QImage, несовместимое с Image и т.п.

В качестве альтернативы свойство icon может использоваться для установки URI постоянного файла изображения или идентификатора темы для иконки.

Данное свойство транслируется как значение стандартной подсказки "image-data".

isTransient : bool

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

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

itemCount : int

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

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

maxContentLines : int

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

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

previewBody : string

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

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

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

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

previewSummary : string

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

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

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

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

progress : var

Свойство содержит прогресс, отображаемый в уведомлении. Значение может быть неопределённым для отсутствия прогресса, Notification.ProgressIndeterminate для неопределённого состояния или действительным значением от 0,0 до 1,0 для представления процента выполнения.

remoteActions : list<variant>

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

Удалённые действия указываются в виде списка объектов с обязательными свойствами 'name', 'displayName, 'icon', 'service', 'path', 'iface', 'method' и 'arguments'. Требуется всегда указывать 'Name', а также 'displayName', если действие отличается от "default" или "app".

Если необходим обратный вызов D-Bus, тогда должны быть установлены 'service', 'path, 'iface, 'method' и опционально 'arguments'.

Например:

 Notification {
     remoteActions: [ {
         "name": "default",
         "displayName": "Do something",
         "icon": "icon-s-do-it",
         "service": "org.nemomobile.example",
         "path": "/example",
         "iface": "org.nemomobile.example",
         "method": "doSomething",
         "arguments": [ "argument", 1 ]
     } ]
 }

 Notification {
     remoteAction: [ {
        "name": "default"
     }, {
        "name": "extraAction",
        "displayName": "Extra action (no callback)"
     } ]
 }

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

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

replacesId : int

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

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

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

sound : string

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

Данное свойство транслируется как значение стандартной подсказки "sound-file".

subText : string

Дополнительный текст уведомления, если он имеется.

Это указывает на некоторую краткую вторичную информацию, такую как адрес электронной почты отправителя в случае уведомления о «новом письме».

Данное свойство транслируется как значение расширенной подсказки "x-nemo-sub-text".

summary : string

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

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

suppressSound : int

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

Данное свойство передаётся в виде стандартного значения-хинта hint "suppress-sound".

timestamp : date

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

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

urgency : enumeration

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

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

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

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

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

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

actionInvoked(string name)

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

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

clicked()

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

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

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

closed(uint reason)

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

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

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

void close()

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

void publish()

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

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