Notification: Notifying Users of Application Events

This tutorial demonstrates how you can manage notifications created based on application events.

The Notification API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Notification API basics by learning about:

Creating Simple Notifications
Create a simple notification.
Creating Progress Notifications
Create a progress notification.
Managing Notifications
Retrieve, update, and remove posted notifications.

Creating Simple Notifications

Learning how to create status notifications allows you to design interactive applications that provide the user information about their events:

Define the status notification properties of the StatusNotificationInit interface (in mobile and wearable applications):

/* Application control */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/create_content", 
                                              null, "image/jpg", null, null);

var notificationDict = 
{
   /* Notification content */
   content: "This is a simple notification.",
   /* Path to the notification icon */
   iconPath: "images/image1.jpg",
   /* Path to the sound file to be played when the notification is displayed */
   soundPath: "music/Over the horizon.mp3",
   /* Device vibrates when the notification is displayed */
   vibration: true, 
   /* Application control to be launched when the user selects the notification */
   appControl: appControl
};

The path in the iconPath and soundPath parameters means a relative file location defined in the Filesystem API (in mobile and wearable applications). The path is not an absolute file location, but instead uses a virtual root location (such as images in images/image1.jpg).

To be able to display the notification, create a StatusNotification object (in mobile and wearable applications) with the status notification type, title, and the additional notification properties defined in the previous step.
```
var notification = new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);
```
To post the notification, use the post() method of the NotificationManager interface (in mobile and wearable applications):
```
tizen.notification.post(notification);  
```

Creating Progress Notifications

Learning how to create progress notifications allows you to design interactive applications that inform the user about the progress of an activity:

Define the status notification properties of the StatusNotificationInit dictionary (in mobile and wearable applications):

/* Application control */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/create_content",
                                              null, "image/jpg", null, null);

var notificationDict =
{
   content: "This is a progress notification.",
   iconPath: "images/image1.jpg",
   vibration: false,
   appControl: appControl,
   progressType: "PERCENTAGE",
   progressValue: 0
};

The path in the iconPath and soundPath parameters means a file location defined in the Filesystem API (in mobile and wearable applications). The path is not an absolute file location, but instead uses a virtual root location (such as images in images/image1.jpg).

To be able to display the notification, create a StatusNotification object (in mobile and wearable applications) with the status notification type, title, and the additional notification properties defined in the previous step:
```
var notification = new tizen.StatusNotification("PROGRESS", "Progress notification", notificationDict);
```

Define a function which uses the update() method of the NotificationManager interface (in mobile and wearable applications) to update the posted notification every second:

function updateProgressNotification(progress)
{
   if (progress <= 100)
   {
      notification.progressValue = progress;
      tizen.notification.update(notification);
      setTimeout(function()
                 {
                    updateProgressNotification(progress + 10);
                 },
                 1000);
   }
   else
   {
      tizen.notification.remove(notification.id);
   }
}

To post the notification, use the post() method of the NotificationManager interface. If the progress value is set, the progress bar is displayed in the notification. The progress value can change the amount of progress as it moves forward or backward.

The application must keep the progress value for its job, because the saved value in the notification status tray can be different (rounded) from the exact progress value.
```
tizen.notification.post(notification);
updateProgressNotification(0);
```

Managing Notifications

Learning how to manage notifications allows you to design interactive applications that provide the user information about their events:

To retrieve notifications:

To retrieve a previously posted notification, use the get() method of the NotificationManager interface (in mobile and wearable applications with the notification ID as a parameter:
```
var myId = notification.id;
var myNotification = tizen.notification.get(myId);    
```

To retrieve all previously posted notifications, use the getAll() method, which returns all the notifications as an array:

var notifications = tizen.notification.getAll();
var index = 0;

/* For each notification, write the ID and title in the console log */
for (index = 0; index < notifications.length; index++)       
{           
   console.log(notifications[index].id);           
   console.log(notifications[index].title); 
}

To update a previously posted notification, use the update() method by specifying the updated notification object:
```
myNotification.content = "My notification";
tizen.notification.update(myNotification);    
```
To remove notifications:
1. To remove a previously posted notification, use the remove() method with the notification ID as a parameter:
```
tizen.notification.remove(myNotification.id);
```
2. To remove all notifications previously posted by the current application, use the removeAll() method:
```
tizen.notification.removeAll();
```