/
notifications.dox
234 lines (234 loc) · 16.6 KB
/
notifications.dox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
/*! \page notifications Notifications
*
* Lipstick implements a desktop notifications service based on the
* <a href="https://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html">Desktop
* Notifications Specification</a>. The service is registered as
* org.freedesktop.Notifications on the D-Bus session bus in the path
* /org/freedesktop/Notifications. Please refer to the specification for an
* overview of the notification service.
*
* \section specifics Notes specific to the behavior of this particular implementation
*
* \subsection unsupported Unsupported elements of the specification
*
* - Some optional features of the specification are not supported: body text
* containing markup is not supported.
* - Multiple actions per notification are correctly handled, but the user
* interface provides no means for displaying or activating actions other
* than "default".
* - Some standard hints are not supported. These are:
* - 'action-icons'
* - 'desktop-entry'
* - 'image-data'
* - 'sound-name'
* - 'x'
* - 'y'
*
* \subsection behavior Behavior notes
*
* - Notifications are grouped by their 'appName' property. The group can be
* compressed or expanded, and removed collectively. The group is treated as
* having individual values equivalent to the composite of its member
* notifications.
* - Priority level >= 100 will cause a notification group to be shown in the
* lock screen of the device.
* - Notifications can have a preview mode, in addition to or as a replacement
* for their appearance in the events view. The preview is shown as a brief
* display over the current application, which can have different content to
* the events view notification.
* - Two different preview presentations are used: if a preview has both a summary
* and a body or has a remote action defined, a clickable popup will be used.
* Otherwise, a minimal scrolling banner will briefly display the text of the
* notification.
* - Urgency level 2 (critical) will cause a notification preview to be processed
* even if the device is showing the notification list, the lock screen, the
* PIN query, or if the device is locked.
* - A notification group can define an action to be invoked for the group
* in addition to those of the individual notifications. This action must
* have the \c actionname "app", and must be present and identical in each member
* of the group.
*
* \subsection capabilities Capabilities
*
* - The service implements the \c "persistence" capability which allows notifications
* to be stored persistenly.
* - The service implements the \c "body" capability which allows notifications
* to contain body text. See the body parameter for Notify().
* - The service implements the \c "actions" capability which allows actions to
* be associated with notifications. When an action is executed, the
* \c ActionInvoked() signal is sent. However, this requires the application
* related to the notification to be running in order to receive the signal.
* For this reason the service also implements a \c "x-nemo-remote-actions"
* capability, which allows remote actions to be associated with
* notifications. When such an action is executed, the notification manager
* makes the D-Bus call defined for the action. See the
* \c x-nemo-remote-action-actionname hint.
* - The service implements the \c "sound" capability which allows changing audible
* feedback behavior using \c "sound-file" and \c "suppress-sound" hints.
* - The service implements a number of extensions via hints; these are reported
* as capabilities, and their use is described in the \c Hints section.
*
* \subsection hints Hints
*
* - The \c "category" hint is used to load a definition for notifications in
* that category from
* \c /usr/share/lipstick/notificationcategories/categoryname.conf. This allows
* defining common properties for all notifications in each category.
* - Each category definition file contains a list of \c hint=value pairs,
* one per line.
* - Each \c hint=value pair in the category definition file is added to
* the hints of the notification, unless already defined.
*
* - The service supports the following Nemo specific hints:
* - \c x-nemo-icon: icon ID or path for the notification. This may be a file:// URL, else if the string begins with a / it's interpreted to be an absolute path. Otherwise it's interpreted to be an icon ID, in which case the icon with the given ID is fetched from the theme. This hint is deprecated in favor of the standard \c image-path hint.
* - \c x-nemo-item-count: the number of items represented by this notification. For example, a single notification can represent four missed calls by setting the count to 4.
* - \c x-nemo-priority: the priority of the notification as an integer. Priorities can be used by UI implementations to present notifications in a specific order, for example. If not specified, the priority level will be allocated 50.
* - \c x-nemo-timestamp: the timestamp for the notification. Should be set to the time when the event the notification is related to has occurred, not when the notification itself was sent.
* - \c x-nemo-preview-icon: icon ID or path to use in the preview banner for the notification, if any.
* - \c x-nemo-preview-body: body text to be shown in the preview banner for the notification, if any.
* - \c x-nemo-preview-summary: summary text to be shown in the preview banner for the notification, if any.
* - \c x-nemo-max-content-lines: the maximum number of content lines to display in the events view, inclusive of the summary. If 1, then no body lines will be displayed.
* - \c x-nemo-remote-action-actionname: details of the D-Bus call to be made when the action "actionname" is executed. "actionname" should be listed in the notification's \c actions array. The required format is "serviceName objectPath interface methodName [argument...]", where each argument must be separately encoded by serializing to QDataStream, then encoding the resulting byte sequence to Base64.
* - \c x-nemo-visibility: the confidentiality of the notification. Currently allows "public" to make notification show even on locked device, "private" and "secret" like on Android API might come later if needed.
*
* - The following hints are used by system notifications, and may be excluded from application notifications:
* - \c x-nemo-feedback: a token used to generate a pre-defined feedback event when the notification preview is displayed
* - \c x-nemo-display-on: if true, the display will be turned on when required for the duration of the notification preview
* - \c x-nemo-led-disabled-without-body-and-summary: if false, a notification may invoke a feedback event even with empty body and summary properties
* - \c x-nemo-hidden: if true, the notification is not displayed and does not cause any feedback to be invoked
* - \c x-nemo-user-removable: a boolean value for defining whether the user is able to remove the notification manually; otherwise it may only be removed programmatically. Defaults to true.
*
* \section howto How to use notifications in various use cases
*
* \subsection chat Incoming chat messages
*
* A typical scenario for using notifications would be to let the user know
* when an incoming chat message has been received. Since the user probably
* does not want a separate notification about each received message to
* clutter up the notification area but still does want some kind of a
* notification about each message, notification coalescing is required.
*
* \subsubsection first_chat_message Sending the notification for the first incoming chat message
*
* When calling Notify() to a display a notification related to the first chat message, the parameters should be set as follows:
* - \c app_name should be a string identifying the sender application, such as the name of its binary, for example. "chat"
* - \c replaces_id should be 0 since the notification is a new one and not related to any existing notification
* - \c app_icon should be "icon-lock-chat" to use the icon with that ID on the notification area. Can be left empty; icons can be handled completely with notification hints (see below)
* - \c summary should contain a brief description about the notification to be shown on the notification area, like "John Doe"
* - \c body should contain informative text related to the notification to be shown on the notification area, like "Hi!"
* - \c actions should contain a list of \c actionname followed by optional display name for each available action, such as ["default" ""]
* - \c hints should contain the following:
* - \c category should be "im.received" to categorize the notification to be related to an instant message
* - \c urgency should be 1 (normal) since chat messages are not specifically low or high priority
* - \c x-nemo-icon should be "icon-lock-chat" to define that the icon with that ID is to be shown on the notification area
* - \c x-nemo-preview-icon should be "icon-preview-chat" to define that the icon with that ID is to be shown on the preview banner
* - \c x-nemo-preview-summary should match the summary text ("John Doe") in order to show it also on the preview banner
* - \c x-nemo-preview-body should match the body text ("Hi!") in order to show it also on the preview banner
* - \c x-nemo-timestamp should be set to the time when the chat message was sent (or received, depending on the intended application logic)
* - \c x-nemo-remote-action-default should be set to "org.example.chat / org.example.chat showMessage <encoded-message-id>" which will cause a D-Bus call with the given details to be made when the notification is tapped, and the action named "default" is invoked
* - \c expire_timeout should be -1 to let the notification manager choose an appropriate expiration time
*
* The Notify() call will return a notification ID which should be stored by
* the application in order to be able to update the notification when more
* related chat messages come in.
*
* \subsubsection second_chat_message Updating the notification for the second incoming chat message
*
* When calling Notify() to a display a notification related to the second chat message, the parameters should be set as follows:
* - \c app_name should be a string identifying the sender application, such as the name of its binary, for example. "chat"
* - \c replaces_id should be the notification ID returned by the first Notify() call in order to update the existing notification
* - \c app_icon should be "icon-lock-chat" to use the icon with that ID on the notification area. Can be left empty; icons can be handled completely with notification hints (see below)
* - \c summary should contain a brief description about the notification to be shown on the notification area, like "John Doe"
* - \c body should contain informative text related to the notification to be shown on the notification area, like "2 messages"
* - \c actions should contain a list of \c actionname followed by optional display name for each available action, such as ["default" ""]
* - \c hints should contain the following:
* - \c category should be "im.received" to categorize the notification to be related to an instant message
* - \c urgency should be 1 (normal) since chat messages are not specifically low or high priority
* - \c x-nemo-icon should be "icon-lock-chat" to define that the icon with that ID is to be shown on the notification area
* - \c x-nemo-item-count should be 2 to make the notification represent two chat messages
* - \c x-nemo-preview-icon should be "icon-preview-chat" to define that the icon with that ID is to be shown on the preview banner
* - \c x-nemo-preview-summary should contain a brief description about the notification to be shown on the preview banner, like "John Doe"
* - \c x-nemo-preview-body should contain informative text about the notification to be shown on the preview banner, like "Are you there?"
* - \c x-nemo-timestamp should be set to the time when the latest chat message was sent (or received, depending on the intended application logic)
* - \c x-nemo-remote-action-default should be set to "org.example.chat / org.example.chat showMessagesFrom <encoded-contact-id>" which will cause a D-Bus call with the given details to be made when the notification is tapped
* - \c expire_timeout should be -1 to let the notification manager choose an appropriate expiration time
*
* Notice that the summary/body and the preview summary/body now differ in
* order to show different information on the notification area and in the
* preview banner. Also the item count should be set when the notification
* represents multiple content items.
*
* \subsection system Transient notifications
*
* Transient notifications are similar to other kinds of notifications but since
* they convey information relevant only when the notification is sent they
* should not appear in the events view. To achieve this only
* \c x-nemo-preview-summary and \c x-nemo-preview-body should be set; the body
* and the summary of the notification should be left empty. If the notification
* is intended to be for informational purposes only, then the notification
* should contain no remote actions, and should omit the preview summary
* property. In this case, the preview body text will be displayed in a minimal
* banner to avoid interrupting user activity.
*
* If a notification is intended to have no presence in the events view, it
* should set the 'transient' hint to true. This will cause it to be closed
* immediately after it has been displayed to the user.
*
* When calling Notify() to a display a transient notification, the parameters should be set as follows:
* - \c app_name should be a string identifying the sender application, such as the name of its binary, for example. "batterynotifier"
* - \c replaces_id should be 0 since the notification is a new one and not related to any existing notification
* - \c app_icon should be left empty; it will not be used in this scenario
* - \c summary should be left empty for nothing to be shown in the events view
* - \c body should be left empty for nothing to be shown in the events view
* - \c actions should be left empty
* - \c hints should contain the following:
* - \c category should be "device" to categorize the notification to be related to the device
* - \c urgency should be 2 (critical) to show the notification over the lock screen
* - \c transient should be true to automatically close the notification after display
* - \c x-nemo-preview-icon should be "icon-battery-low" to define that the icon with that ID is to be shown on the preview banner
* - \c x-nemo-preview-body should be "Battery low" in order to show it on the preview banner
* - \c expire_timeout should be -1 to let the notification manager choose an appropriate expiration time
*
* \subsection categorydefinitions Using category definition files
*
* When notifications in a certain category always share the same hints it's
* possible to write a category definition file in
* \c /usr/share/lipstick/notificationcategories/categoryname.conf and then just
* set the category hint to categoryname when calling Notify(). The category
* definition file contains a list of hint=value pairs, one per line. Each
* \c hint=value pair in the category definition file is added to the hints of
* the notification.
*
* For example, if /usr/share/lipstick/notificationcategories/device.conf
* contains
*
* \code
* transient=true
* urgency=2
* x-nemo-preview-icon=icon-battery-low
* \endcode
*
* and Notify() is called with the hints dictionary containing the value \c "device"
* for the \c "category" hint and the value \c "Charging" for the \c "x-nemo-preview-body"
* hint, the hints will be combined so that the effective hints used are
*
* \code
* category=device
* transient=true
* urgency=2
* x-nemo-preview-body=Charging
* x-nemo-preview-icon=icon-battery-low
* \endcode
*
* It is also possible to define the following notification properties in the category
* definition file:
* - \c appName
* - \c appIcon
* - \c summary
* - \c body
* - \c expireTimeout
*
* Note that category definitions do not currently support any mechanism for translating
* strings to the device locale, so it should not be used for defining strings for
* display to the user.
*/