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:

1. 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 ensure that a Notification function has been executed properly, make sure that the return is equal to NOTIFICATION_ERROR_NONE.

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

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

The parameter is the notification type, whose possible values are listed in the _notification_type enumeration (in mobile and wearable applications).

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:

  To set the text (title and content string) to display in the notification view, use the notification_set_text() function.

  The second parameter defines the notification type, whose possible values are listed in the _notification_text_type enumeration (in mobile and wearable applications).

  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
  }
  

• Notification timestamp:

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

  The second parameter defines the notification text type in which the timestamp is shown. Its values are listed in the _notification_text_type enumeration.

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

• Notification image:

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

  The second parameter defines the notification image type, whose possible values are listed in the _notification_image_type enumeration (in mobile and wearable applications).

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

• Notification display options:

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

  The second parameter defines the notification display option, whose possible values are listed in the _notification_display_applist enumeration (in mobile and wearable applications). You can set multiple options with 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
  }
  

• LED options:

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

  • The notification_set_led() function sets the LED operation. The second parameter defines the LED notification, whose values are listed in the _notification_led_op enumeration (in mobile and wearable applications).

  • The notification_set_led_time_period() function sets the time period when the LED is switched on and off (second and third parameters).

  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
  }
  

• Notification properties:

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

  The second parameter defines the notification property, whose possible values are listed in the _notification_property enumeration (in mobile and wearable applications). You can set multiple properties with the "|" pipe operation.

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

• Button on the active notification:

  To add a button on the active notification, use the notification_add_button() and notification_set_event_handler() functions:

  • The notification_add_button() adds the button. The second parameter defines the button index, whose possible values are listed in the _notification_button_index enumeration (in mobile and wearable applications).

  • The notification_set_event_handler() function defines the application control that launches the application at the button click. The third parameter defines the app control handle, whose possible values are listed in the _notification_event_type enumeration (in mobile and wearable applications).

    noti_err = notification_add_button(noti, NOTIFICATION_BUTTON_1);
    if (noti_err != NOTIFICATION_ERROR_NONE) 
    {
       // Error handling
    }
    
    app_control_h app_control = NULL;
    
    app_control_create(&app_control);
    app_control_set_app_id(app_control, "org.tizen.app");
    noti_err  = notification_set_event_handler(noti, NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1, app_control);
    if (noti_err != NOTIFICATION_ERROR_NONE) 
    {
       // Error handling
    }
    
    app_control_destroy(app_control);
    

Posting a Notification

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

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. The function works only for ongoing notifications.

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

Deleting a Notification

To delete a notification:

1. To delete a notification from the database, use the notification_delete() function:

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

2. After deleting the notification, free the internal structure data of the notification handle by calling the notification_free() function:

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

Displaying the Progress Bar

To display the progress bar and update the progress data:

1. Use the NOTIFICATION_TYPE_ONGOING parameter to create a notification with a progress bar. To be able to retrieve the notification n handle later on to update the progress data, set a notification tag with the notification_set_tag() function.

   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);
   

2. To update the progress bar, retrieve the notification handle with the notification_load_by_tag() function, set and get the progress data, and update the notification:

   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