Dependencies

Tizen 2.4 and Higher for Mobile
Tizen 3.0 and Higher for Wearable

Content

Notification Types
Notification Display Types
Notification Layouts
Prerequisites
Set-up @@ -43,10 +44,13 @@

Displaying the Progress Bar

Creating an Active Notification with Text Input

Using a Notification Template

Related Info

@@ -58,64 +62,84 @@

Notifications

An application can use notifications to keep the user informed of important information.

This feature is supported in mobile applications only.

The main features of the Notification API include:

Creating a notification -
You can create a notification. There are 3 notification types and 4 notification layouts you can choose from.

You can create a notification. There are 5 notification display types and 4 notification layouts you can choose from.

Setting notification attributes
You can set notification attributes, such as the notification text, timestamp, and various display and LED options.
Posting a notification -
You can post a simple notification using the notification_post() function, which accepts a notification handle as a parameter.
+
You can post a simple notification using the notification_post() function, which accepts a notification handle as a parameter.

The posted notification has a default notification icon and the application name as the title.
Updating notification content -
You can update the content of a notification using the notification_update() function.

You can update the content of a notification using the notification_update() function.

Deleting a notification
You can delete notifications when no longer needed.
Displaying the progress bar -
You can create, display, and update a progress bar in a notification.

Using advanced notification features +

You can create, display, and update a progress bar in a notification.
You can create and active notification with a text input field.
You can create a template that can be reused in multiple notifications.

+ -

Notification Types

Tizen provides notifications by using a combination of any of the following notification types:

Notification Display Types

Tizen provides notifications by using a combination of any of the following notification display types:

Quick panel
Active notification
Indicator
Indicator
Lock screen
Status message

You can specify the message for the quick panel, active notification, or indicator.

The notification display type determines where and how the notification message is displayed.

Notifications on the Quick Panel

Quick Panel Notifications

The display area for quick panel notifications can be one of the following:

Notification area +

Notification area
The notification area is the reserved space for displaying all notifications, except the on-going notifications.
On-going area +
On-going area
The on-going area is the application screen area and is only used to display notifications for the currently running application.

Figure: Notification and on-going areas

Notification and on-going areas

Active Notifications

Active notifications can be used to show a notification on the upper side of the screen.

You can add several buttons for user interaction.

An active notification is displayed on the upper side of the screen. You can add several buttons for user interaction.

Figure: Active notification

Active notification

Indicator Notifications

The indicator type notification is displayed for a few seconds in the indicator area. Only a simple string and icon can be displayed.

+ +

Figure: Notification on the ticker and the indicator

Notification on the ticker and the indicator

+ +

Lock Screen Notifications

You can display a notification on the lock screen. The notification content can be displayed or hidden.

+ +

Figure: Notification on the lock screen

Notification on the lock screen

+ +

Status Message Notifications

A status message type notification can be used like a pop-up. It is displayed for a few seconds and then disappears.

+ +

Figure: Status message

Status message

Notification Layouts

The following notification layouts are provided:

NOTIFICATION_LY_NOTI_EVENT_SINGLE +

NOTIFICATION_LY_NOTI_EVENT_SINGLE
Layout for a single event notification.
NOTIFICATION_LY_NOTI_EVENT_MULTIPLE +
NOTIFICATION_LY_NOTI_EVENT_MULTIPLE
Layout for a multiple event notification.
NOTIFICATION_LY_NOTI_THUMBNAIL +
NOTIFICATION_LY_NOTI_THUMBNAIL
Layout for a notification displaying images.
NOTIFICATION_LY_ONGOING_PROGRESS +
NOTIFICATION_LY_ONGOING_PROGRESS
Layout for an ongoing notification displaying progress.

Figure: Notification layouts

Notification layouts

Prerequisites

@@ -123,7 +147,7 @@

To enable your application to use the notification functionality:

To use the Notification API, the application has to request permission by adding the following privilege to the tizen-manifest.xml file: +

To use the Notification API (in mobile and wearable applications), the application has to request permission by adding the following privilege to the tizen-manifest.xml file:

 <privileges>
    <privilege>http://tizen.org/privilege/notification</privilege>
@@ -147,19 +171,19 @@ free(shared_path);
 
 
 
- Creating a Notification
+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.
+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);
+notification = notification_create(NOTIFICATION_TYPE_NOTI);
 if (notification != NULL)
     /* Notification was initialized successfully */
 
 
 
 
- Setting Notification Attributes
+Setting Notification Attributes
 
 You can set the following attributes for a notification:
 
@@ -167,7 +191,7 @@ if (notification != NULL)
 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.
+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",
@@ -176,6 +200,7 @@ ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_TITLE, "te
 if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
+To implement multi-language support, define the text string key (msgid field in the .po file) as the fourth parameter.
 
 
 Notification timestamp:
@@ -183,7 +208,8 @@ if (ret != NOTIFICATION_ERROR_NONE)
 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));
+ret = notification_set_time_to_text(notification, NOTIFICATION_TEXT_TYPE_CONTENT,
+                                    time(NULL));
 if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
@@ -192,7 +218,7 @@ if (ret != NOTIFICATION_ERROR_NONE)
 
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.
+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)
@@ -203,10 +229,11 @@ if (ret != NOTIFICATION_ERROR_NONE)
 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. You can set multiple options with the "|" pipe operation.
+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);
+                                       NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY
+                                       | NOTIFICATION_DISPLAY_APP_TICKER);
 if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
@@ -217,7 +244,7 @@ if (ret != NOTIFICATION_ERROR_NONE)
 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.
+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).
 
 
 
@@ -237,7 +264,7 @@ if (ret != NOTIFICATION_ERROR_NONE)
 
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. You can set multiple properties with the "|" pipe operation.
+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)
@@ -249,10 +276,10 @@ if (ret != NOTIFICATION_ERROR_NONE)
 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.
+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.
+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);
@@ -263,7 +290,9 @@ 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);
+noti_err = notification_set_event_handler(noti,
+                                          NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1,
+                                          app_control);
 if (noti_err != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
@@ -274,7 +303,7 @@ app_control_destroy(app_control);
 
 
 
- Posting a Notification
+Posting a Notification
 
 To post a notification to the database, use the notification_post() function:
 @@ -283,7 +312,7 @@ if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
 
- Updating Notification Content
+Updating Notification Content
 
 To update the content of a notification, use the notification_update() function. The function works only for ongoing notifications.
 @@ -292,9 +321,9 @@ if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
 
- Deleting a Notification
+Deleting a Notification
 
-To delete a notification:			
+To delete a notification:
 To delete a notification from the database, use the notification_delete() function:
 
 @@ -309,7 +338,7 @@ if (ret != NOTIFICATION_ERROR_NONE)
     /* Error handling */
 
 
- Displaying the Progress Bar
+Displaying the Progress Bar
 
 To display the progress bar and update the progress data:
 
@@ -369,8 +398,309 @@ Eina_Bool timeout_func(void *data)
 }

Figure: Progress bar

Progress bar

Figure: Progress bar

Progress bar

+ +

Creating an Active Notification with Text Input

+ +

To create an active notification and an input text field, with which the user can directly reply to the notification:

+ +

To create an active notification, add the NOTIFICATION_DISPLAY_APP_ACTIVE type to the display application list. +

You can create up to 3 buttons, and each button must have an application control that can handle the event.

+notification_h notification = NULL;
+app_control_h app_control = NULL;
+
+/* Create a new notification */
+notification = notification_create(NOTIFICATION_TYPE_NOTI);
+if (noti == NULL)
+    /* Error handling */
+
+/* Set notification attributes */
+int ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_TITLE, "text",
+                                NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_image(notification, NOTIFICATION_IMAGE_TYPE_ICON, image_path);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_add_button(notification, NOTIFICATION_BUTTON_1);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_BUTTON_1, "button1",
+                                NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_add_button(notification, NOTIFICATION_BUTTON_2);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_BUTTON_2, "button2",
+                                NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_add_button(notification, NOTIFICATION_BUTTON_3);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_BUTTON_3, "button3",
+                                NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_display_applist(notification, NOTIFICATION_DISPLAY_APP_ACTIVE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+/* Button 1 */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+/* Button 2 */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_2,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+/* Button 3 */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_3,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+/* Post a notification */
+ret = notification_post(notification);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+if (notification)
+    notification_free(notification);
+

To allow the user to reply to the active notification directly, set a text input field. +

Set the text field size, and add the settings for the placeholder text and input button. The field can be displayed directly on the active notification, or only when the button is pressed.

+/* Set notification attributes */
+
+ret = notification_set_text_input(notification, 160);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification,
+                            NOTIFICATION_TEXT_TYPE_TEXT_INPUT_PLACEHOLDER,
+                            "Text message", NULL,
+                            NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification,
+                            NOTIFICATION_TEXT_TYPE_TEXT_INPUT_BUTTON,
+                            "Send", NULL,
+                            NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+/* Text input button */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_TEXT_INPUT_BUTTON,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+/* Post a notification */
+

Figure: Text input box

Text input box

+ +

Using a Notification Template

+ +

To create a template from an existing notification, and reuse that template in another notification:

+ +

Create a notification as usual.

The following example creates an active notification with 2 buttons (accept and cancel), a background image, sound, led, and vibration:

+ +

+notification_h notification = NULL;
+app_control_h app_control = NULL;
+
+/* Create a new notification */
+notification = notification_create(NOTIFICATION_TYPE_NOTI);
+if (noti == NULL)
+    /* Error handling */
+
+/* Set notification attributes */
+int ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_TITLE, "text",
+                                NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_image(notification, NOTIFICATION_IMAGE_TYPE_ICON, image_path);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_image(notification, NOTIFICATION_IMAGE_TYPE_BACKGROUND,
+                             image_path);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_sound(notification, NOTIFICATION_SOUND_TYPE_USER_DATA,
+                             sound_path);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+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 */
+
+ret = notification_set_display_applist(notification,
+                                       NOTIFICATION_DISPLAY_APP_NOTIFICATION_TRAY
+                                       | NOTIFICATION_DISPLAY_APP_ACTIVE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_add_button(notification, NOTIFICATION_BUTTON_1);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_BUTTON_1,
+                            "accept", NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_add_button(notification, NOTIFICATION_BUTTON_2);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_text(notification, NOTIFICATION_TEXT_TYPE_BUTTON_2,
+                            "cancel", NULL, NOTIFICATION_VARIABLE_TYPE_NONE);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+/* Button 1 */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_1,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+/* Button 2 */
+app_control = NULL;
+
+ret = app_control_create(&app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_set_app_id(app_control, "appid");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+
+ret = notification_set_event_handler(notification,
+                                     NOTIFICATION_EVENT_TYPE_CLICK_ON_BUTTON_2,
+                                     app_control);
+if (ret != NOTIFICATION_ERROR_NONE)
+    /* Error handling */
+
+ret = app_control_destroy(app_control);
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+

To save the notification handle as a template and define a name for the template, use the notification_save_as_template() function:

+ret = notification_save_as_template(notification, "CALL_ACCEPT");
+if (ret != APP_CONTROL_ERROR_NONE)
+    /* Error handling */
+

To use the template when creating a new notification, call the notification_create_from_template() function:

+notification_h notification = NULL;
+notification = notification_create_from_template("CALL_ACCEPT")
+if (noti == NULL)
+    /* Error handling */
+

@@ -394,4 +724,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file +