diff --git a/source/img/NotificationLowDisk.png b/source/img/NotificationLowDisk.png
new file mode 100644
index 0000000..74432ce
Binary files /dev/null and b/source/img/NotificationLowDisk.png differ
diff --git a/source/plattform/notification.rst b/source/plattform/notification.rst
index 0f8814f..953ab6f 100644
--- a/source/plattform/notification.rst
+++ b/source/plattform/notification.rst
@@ -1,103 +1,112 @@
Notification
============
Notifications are a way to inform users of your app about events, even if the
applications has no focus, is minimzed or is only running in the background.
Examples
--------
+.. figure:: /img/NotificationLowDisk.png
+ :alt:
+
+ Low disk space notification
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
Use notifications to inform the user of events that are of interest to the
user, even if your app is not in foregound, but don't spam the user with
notifications.
- Complition of long running tasks an user has started manually
- Incoming communication from other users
- Hardware related events like, low battery, lost network connection, running
out of disk space
Don't use a notification for:
- Actions of your app that don't require user interaction, background
processes, syncing, updates, ...
- Advertisment, rating or feedback requests, cross promoting, ...
- If an unexpected or potentially dangerous condition has been reached and the
user must make a decision. Use an :doc:`/components/assistance/message`
instead.
- Don't send notifications, if an user has never opened your application
+.. figure:: /img/NotificationHistory.png
+ :alt:
+
+ Notification history
+
Behavior
~~~~~~~~
Notifications are provided by the system to the user, and formost the
user settings for notification govern the behavior and apeparance of
notifications. But there are serveral options to influence the and enrich the
behavior of your notifications.
Persistence
"""""""""""
Setting the notification to persistent will prevent the notification from
closing after a timeout. If you set the notification to persistent, you need to
make sure to revoke the notification, if the reason for the notification no
longer applies, like a power adpter was plugged after a "Battery level is
critical" notifcation.
Urgency
"""""""
It is recommended that a notification carrys an urgency hint:
- 0 – Low, “Matt is now online”, “You just plugged in your AC adapter”
- 1 – Normal, “You have new mail”
- 2 – Critical, “Battery level is critical”
Actions
"""""""
You can add up to three action buttons to the notification to enable the user
to react to the event, without opening the app first.
Preview
"""""""
You can specify an url to an image associated with the notifcation. The image
will be displayed as a preview in the notifcation.
.. Quick Reply
"""""""""""
This enables the user to reply to an Email or SMS from within the
notification. A “Reply” text field is placed in the notification window
whose content is eventually sent back to the application through the
notification server.
Code
----
.. code-block:: c++
KNotification *notification= new KNotification ( "contactOnline", widget );
notification->setText( i18n("The contact %1 has gone online",
contact->name() );
notification->setPixmap( contact->pixmap() );
notification->setActions( QStringList( i18n( "Open chat" ) ) );
foreach( const QString &group , contact->groups() ) {
notification->addContext( "group" , group ) ;
}
connect(notification, SIGNAL(activated(unsigned int )), contact ,
SLOT(slotOpenChat()) );
notification->sendEvent();
Use :knotificationsapi:`` to send notifications to the
:doc:`Plasma Workspaces `.