Notification: Notifying the User of Application Events

This tutorial demonstrates how you can display notifications in your application.

Warm-up

Become familiar with the Notification API basics by learning about:

Set-up
- Initializing Notifications
  Initialize the notification functionalities for use.
- Creating a Notification
  Create a notification.
- Setting Notification Attributes
  Set attributes for a notification.
Management
- Posting a Notification
  Post a notification.
- Updating Notification Content
  Update the content of a notification.
- Deleting a Notification
  Delete a notification.

Follow-up

Once we have learned the basics of the Notification API, we can now move on to more advanced tasks, including:

Displaying the Progress Bar
Create, display, and update a progress bar.

Initializing Notifications

To initialize notifications:

To use the functions and data types of the Notification API (in mobile and wearable applications), include the <notification.h> header file in your application:
```
#include <notification.h>
```

To follow this tutorial, place an image file in, for example, your application's shared resource directory. The following variables are used in the tutorial code:

static notification_h notification = NULL;
char *image_path[BUFLEN];
char * shared_path = app_get_shared_resource_path();
snprintf(image_path, BUFLEN, "%stutorial_native_api_application.png", shared_path);
free(shared_path);

Creating a Notification

To create a notification:

Initialize a notification handle by calling the notification_create() function:

notification_h notification_create(notification_type_e type)

The function takes the following parameters:

[in] type: Notification type.

The possible values for the type parameter are:

NOTIFICATION_TYPE_NOTI: Create a regular notification.
NOTIFICATION_TYPE_ONGOING: Create an ongoing notification.

The following example code creates an ongoing notification and checks whether the initialization was successful:

notification = notification_create(NOTIFICATION_TYPE_ONGOING);
if (notification != NULL)
{
   // Notification was initialized successfully
}

Setting Notification Attributes

You can set the following attributes for a notification:

Notification text
Timestamp
Image
Display options
LED options
Properties

Setting the Notification Text

To set the text to display in the notification view, use the notification_set_text() function:

notification_set_text (notification_h noti, notification_text_type_e type, const char *text, const char *key, int args_type, ...)

The function takes the following parameters:

[in] noti: Notification handle.
[in] type: Notification text type.
[in] text: Text to display in the notification view.
[in] key: Text key for localization.
[in] args_type: Variable parameter for a type-value pair.

The possible values for the type parameter are:

NOTIFICATION_TEXT_TYPE_TITLE
NOTIFICATION_TEXT_TYPE_CONTENT
NOTIFICATION_TEXT_TYPE_CONTENT_FOR_DISPLAY_OPTION_IS_OFF
NOTIFICATION_TEXT_TYPE_EVENT_COUNT
NOTIFICATION_TEXT_TYPE_INFO_1
NOTIFICATION_TEXT_TYPE_INFO_SUB_1
NOTIFICATION_TEXT_TYPE_INFO_2
NOTIFICATION_TEXT_TYPE_INFO_SUB_2
NOTIFICATION_TEXT_TYPE_INFO_3
NOTIFICATION_TEXT_TYPE_INFO_SUB_3
NOTIFICATION_TEXT_TYPE_GROUP_TITLE
NOTIFICATION_TEXT_TYPE_GROUP_CONTENT
NOTIFICATION_TEXT_TYPE_GROUP_CONTENT_FOR_DISPLAY_OPTION_IS_OFF

The notification_set_text() function sets the title and content string. If the text is formatted data (only d, f, and s are supported), set the type-value pair:

If d, the type is NOTIFICATION_VARIABLE_TYPE_INT and the value is an integer.
If f, the type is NOTIFICATION_VARIABLE_TYPE_DOUBLE and the value is a double.
If s, the type is NOTIFICATION_VARIABLE_TYPE_STRING and the value is a string.

If the type is NOTIFICATION_VARIABLE_TYPE_COUNT, the notification count is displayed with the text. If the value is NOTIFICATION_COUNT_POS_LEFT, the count is displayed to the left of the text. If the value is NOTIFICATION_COUNT_POS_IN, the count is displayed in the text when the text is of the d format. If the value is NOTIFICATION_COUNT_POS_RIGHT, the count is displayed to the right of the text. Variable parameters should be terminated by NOTIFICATION_VARIABLE_TYPE_NONE.

Check whether the operation was successful by retrieving and comparing the return value of any function to NOTIFICATION_ERROR_NONE:

int ret =0;
ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_TITLE, "text", NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Setting the Notification Timestamp

To set the timestamp to display in the notification text, use the notification_set_time_to_text() function:

notification_set_time_to_text (notification_h noti, notification_text_type_e type, time_t time)

The function takes the following parameters:

[in] noti: Notification handle.
[in] type: Notification text type. For information about the possible values, see Setting the Notification Text.
[in] time_t: Timestamp to display in the notification text.

ret = notification_set_time_to_text(notification, NOTIFICATION_TEXT_TYPE_CONTENT, time(NULL));
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Setting the Notification Image

To set the image to display in the notification view, use the notification_set_image() function:

notification_set_image (notification_h noti, notification_image_type_e type, const char *image_path)

The function takes the following parameters:

[in] noti: Notification handle.
[in] type: Notification image type.
[in] image_path: Absolute path and file name of the image file.

The possible values for the type parameter are:

NOTIFICATION_IMAGE_TYPE_ICON
NOTIFICATION_IMAGE_TYPE_ICON_FOR_INDICATOR
NOTIFICATION_IMAGE_TYPE_ICON_FOR_LOCK
NOTIFICATION_IMAGE_TYPE_THUMBNAIL
NOTIFICATION_IMAGE_TYPE_THUMBNAIL_FOR_LOCK
NOTIFICATION_IMAGE_TYPE_ICON_SUB
NOTIFICATION_IMAGE_TYPE_BACKGROUND
NOTIFICATION_IMAGE_TYPE_LIST_1
NOTIFICATION_IMAGE_TYPE_LIST_2
NOTIFICATION_IMAGE_TYPE_LIST_3
NOTIFICATION_IMAGE_TYPE_LIST_4
NOTIFICATION_IMAGE_TYPE_LIST_5

ret = notification_set_image(notification, NOTIFICATION_IMAGE_TYPE_ICON, image_path);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Setting the Notification Display Options

To set how applications display the notification, use the notification_set_display_applist() function:

notification_set_display_applist (notification_h noti, int applist)

The function takes the following parameters:

[in] noti: Notification handle.
[in] applist: Notification display option. You can set multiple options with the "|" pipe operation.

The possible values for the applist parameter are:

NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY
NOTIFICATION_DISPLAY_APP_TICKER
NOTIFICATION_DISPLAY_APP_LOCK
NOTIFICATION_DISPLAY_APP_INDICATOR
NOTIFICATION_DISPLAY_APP_ALL

You can combine the flags in the function by using the pipe "|" operation:

ret = notification_set_display_applist(notification, NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY | NOTIFICATION_DISPLAY_APP_TICKER);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Setting the LED Options

To set the LED options for a notification, use the notification_set_led() and notification_set_led_time_period() functions:

notification_set_led (notification_h noti, notification_led_op_e operation, int led_argb)

The function takes the following parameters:

[in] noti: Notification handle.
[in] operation: LED notification operation.
[in] led_argb: Notification LED color.

The possible values for the operation parameter are:

NOTIFICATION_LED_OP_ON
NOTIFICATION_LED_OP_ON_CUSTOM_COLOR

notification_set_led_time_period (notification_h noti, int on_ms, int off_ms)

The function takes the following parameters:

[in] noti: Notification handle.
[in] on_ms: Time for turning on the LED.
[in] off_ms: Time for turning off the LED.

ret = notification_set_led(notification, NOTIFICATION_LED_OP_ON, 100);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}
ret = notification_set_led_time_period(notification, 100, 100);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Setting Notification Properties

To set a notification property, use the notification_set_property() function:

notification_set_property (notification_h noti, int flags)

The function takes the following parameters:

[in] noti: Notification handle.
[in] flags: Notification property. You can set multiple properties with the "|" pipe operation.

The possible values for the flags parameter are:

NOTIFICATION_PROP_DISPLAY_ONLY_SIMMODE
NOTIFICATION_PROP_DISABLE_APP_LAUNCH
NOTIFICATION_PROP_DISABLE_AUTO_DELETE
NOTIFICATION_PROP_LAUNCH_UG
NOTIFICATION_PROP_DISABLE_TICKERNOTI
NOTIFICATION_PROP_DISABLE_UPDATE_ON_INSERT
NOTIFICATION_PROP_DISABLE_UPDATE_ON_DELETE
NOTIFICATION_PROP_VOLATILE_DISPLAY

ret = notification_set_property(notification, NOTIFICATION_PROP_DISABLE_APP_LAUNCH);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Posting a Notification

To post a notification to the database, use the notification_post() function:

notification_post (notification_h noti)

The function takes the following parameters:

[in] noti: Notification handle.

ret = notification_post(notification);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Updating Notification Content

To update the content of a notification, use the notification_update() function:

notification_update (notification_h noti)

The function takes the following parameters:

[in] noti: Notification handle.

The notification_update() function works only for ongoing notifications.

ret = notification_update (notification);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}

Deleting a Notification

To delete a notification:

To delete a notification from the database, use the notification_delete() function:
```
notification_delete(notification_h noti)
```
The function takes the following parameters:
- [in] noti: Notification handle.
```
ret = notification_delete(notification);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}
```
After deleting the notification, free the internal structure data of the notification handle by calling the notification_free() function:
```
notification_free (notification_h noti)
```
The function takes the following parameters:
- [in] noti: Notification handle.
```
ret = notification_free(notification);
if (ret != NOTIFICATION_ERROR_NONE)
{
   // Error handling
}
```

Displaying the Progress Bar

To display the progress bar:

Use the NOTIFICATION_TYPE_ONGOING parameter to create a notification with a progress bar. The following example illustrates how the progress data is updated.

To set the initial progress:

notification_h notification = NULL;

// Create a notification
notification = notification_create(NOTIFICATION_TYPE_ONGOING);
PRINT_MSG("notification_create %s", (notification != NULL) ? "succeed" : "failed");

// Set the parameters
int ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_TITLE, "text", NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
PRINT_MSG("notification_set_text %s", (ret == 0) ? "succeed" : "failed");

ret = notification_set_progress(notification, 0);
PRINT_MSG("notification_set_progress %s", (ret == 0) ? "succeed" : "failed");

ret = notification_set_tag(notification, "noti_tag");
PRINT_MSG("notification_set_tag %s", (ret == 0) ? "succeed" : "failed");

// Send the notification
ret = notification_post(notification);
PRINT_MSG("notification_post %s", (ret == 0) ? "succeed" : "failed");

// Change the status of the notification
ecore_timer_add(1, timeout_func, NULL);

To update the progress bar, use the notification_load_by_tag() function for getting the notification handle:

static Eina_Bool timeout_func(void *data)
{
   static int i = 0;
   double progress = 0;
   i++;
   notification_h notification = notification_load_by_tag("noti_tag");
   notification_set_progress(notification, ((double) i / 10.0));
   notification_get_progress(notification, &progress);
   notification_update(notification);

   dlog_print(DLOG_INFO, "NOTIFICATION", "Progress: %f\n", progress);

   if (10 == i)
   { 
      dlog_print(DLOG_INFO, "NOTIFICATION", "End of awaiting!n"); 
      notification_delete(notification);

      return ECORE_CALLBACK_DONE; 
   } 

   return ECORE_CALLBACK_PASS_ON;
}

Figure: Progress bar

Progress bar