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 `.