Notification API

The Notification API provides a way to notify users of events that happen in an application.

For more information on the Notification features, see Notification Guide.

Since: 2.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
NotificationObject
NotificationManager
void post (Notification notification)
void update (Notification notification)
void removeAll ()
void playLEDCustomEffect (long timeOn, long timeOff, DOMString color, LEDCustomFlags[] flags)
void saveNotificationAsTemplate (DOMString name, Notification notification)
Notification
UserNotificationInit
NotificationTextContentInfo
NotificationImageInfo
NotificationThumbnailInfo
NotificationActionInfo
NotificationGroupContentInfo
NotificationLedInfo
UserNotification
NotificationDetailInfo

1. Type Definitions

1.1. NotificationId

A notification ID.
  typedef DOMString NotificationId;

Since: 2.0

1.2. NotificationType

A notification type.
  enum NotificationType { "STATUS" };

Since: 2.0

The following notification type is supported:

  • STATUS - The posted status notification is displayed on the status bar and the notification tray. The status notification consists of an icon, title, content, and time. The status notification can have an application control to launch the specific application when selected by the user.

1.3. StatusNotificationType

A status notification type.

Deprecated. Deprecated since 4.0. Use UserNotificationType instead.

  enum StatusNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };

Since: 2.0

The following status notification types are supported:

  • SIMPLE - A basic status notification type that is removed automatically when selected by the user. All simple status notifications can be removed by user interaction.
  • THUMBNAIL - The thumbnail status notification posts a thumbnail-format notification which includes several thumbnail image paths. The thumbnail status notification is also removed by user selection.
  • ONGOING - A status notification type that informs the user whether an application is running or not.
  • PROGRESS - A status notification that displays information on the progress of a job. However, this status notification should be removed by the application that posted the notification.

1.4. UserNotificationType

A user notification type.
  enum UserNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };

Since: 4.0

The following user notification types are supported:

  • SIMPLE - A basic user notification type that is removed automatically when selected by the user. All simple user notifications can be removed by user interaction.
  • THUMBNAIL - The thumbnail user notification posts a thumbnail-format notification which includes several thumbnail image paths. The thumbnail user notification is also removed by user selection.
  • ONGOING - An user notification type that informs the user whether an application is running or not.
  • PROGRESS - An user notification that displays information on the progress of a job. However, this user notification should be removed by the application that posted the notification.

1.5. NotificationProgressType

A notification progress type.
  enum NotificationProgressType { "PERCENTAGE", "BYTE" };

Since: 2.1

The following notification progress types are supported:

  • BYTE - The progress is indicated in bytes.
  • PERCENTAGE - The progress is indicated in percentage.

1.6. LEDCustomFlags

Specifies custom LED flags. The following values are supported in this release:
  enum LEDCustomFlags { "LED_CUSTOM_DUTY_ON", "LED_CUSTOM_DEFAULT" };

Since: 2.4

  • LED_CUSTOM_DUTY_ON - blink LED
  • LED_CUSTOM_DEFAULT - default flag

2. Interfaces

2.1. NotificationObject

Defines what is instantiated by the Tizen object.
  [NoInterfaceObject] interface NotificationObject {
    readonly attribute NotificationManager notification;
  };
  Tizen implements NotificationObject;

Since: 2.0

The tizen.notification object allows access to the Notification API.

Attributes

  • readonly NotificationManager notification
    Object representing a notification manager.

    Since: 2.0

2.2. NotificationManager

Notification manager interface that provides access to the API.
  [NoInterfaceObject] interface NotificationManager {
    void post(Notification notification) raises(WebAPIException);
    void update(Notification notification) raises(WebAPIException);
    void remove(NotificationId id) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    Notification get(NotificationId id) raises(WebAPIException);
    Notification getNotification(NotificationId id) raises(WebAPIException);
    Notification[] getAll() raises(WebAPIException);
    Notification[] getAllNotifications() raises(WebAPIException);
    void playLEDCustomEffect(long timeOn, long timeOff, DOMString color, LEDCustomFlags[] flags) raises(WebAPIException);
    void stopLEDCustomEffect() raises(WebAPIException);
    void saveNotificationAsTemplate(DOMString name, Notification notification) raises(WebAPIException);
    UserNotification createNotificationFromTemplate(DOMString name) raises(WebAPIException);
  };

Since: 2.0

The NotificationManager interface provides access to the notification object.

Methods

post
Posts a notification to display.
void post(Notification notification);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • notification: A notification to post.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  var appControl = new tizen.ApplicationControl(
      "http://tizen.org/appcontrol/operation/view", null, "image/jpg", null);

  var notificationGroupDict =
  {
    content: "This is a simple user notification.",
    actions: {soundPath: "music/Over the horizon.mp3", vibration: true, appControl: appControl}
  };

  /* Constructs and posts the simple user notification. */
  var notification =
      new tizen.UserNotification("SIMPLE", "User notification", notificationGroupDict);
  tizen.notification.post(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

Code example:

try
{
  var notificationGroupDict =
  {
    content: "This is a thumbnail user notification.",
    thumbnails: {thumbnailIconPath: "images/thumbnail.jpg"}
  };

  /* Constructs and posts the thumbnail user notification. */
  var notification =
      new tizen.UserNotification("THUMBNAIL", "User notification", notificationGroupDict);
  tizen.notification.post(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

Code example:

try
{
  var notificationGroupDict =
  {
    content: "This is an ongoing user notification.",
    images: {iconPath: "images/simple_icon.jpg"}
  };

  /* Constructs and posts the ongoing user notification. */
  var notification =
      new tizen.UserNotification("ONGOING", "User notification", notificationGroupDict);
  tizen.notification.post(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

Code example:

try
{
  var notificationGroupDict =
  {
    content: "This is a progress user notification.",
    textContents: {progressValue: 20},
    actions: {soundPath: "music/Over the horizon.mp3", vibration: false}
  };

  /* Constructs and posts the progress user notification. */
  var notification =
      new tizen.UserNotification("PROGRESS", "User notification", notificationGroupDict);
  tizen.notification.post(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
update
Updates a previously posted notification.
void update(Notification notification);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • notification: A notification to update.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  notification.content = "My notification";
  tizen.notification.update(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
remove
Removes a previously posted notification.
void remove(NotificationId id);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Parameters:

  • id: A previously posted notification ID to remove.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if NotificationId is not found in the previously posted notification.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  tizen.notification.remove(notification.id);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
removeAll
Removes all notifications that have been posted by the current application.
void removeAll();

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  tizen.notification.removeAll();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
get
Gets a notification that has previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE

Deprecated. Deprecated since 4.0. Use getNotification instead.

Since: 2.0

Remark: This method is designed to return old-style notification.

Parameters:

  • id: A previously posted notification ID.

Return value:

    Notification: Notification posted previously by the current application.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if NotificationId is not found in the previously posted notifications.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  /* Saves the notification ID for future use. */
  var myId = notification.id;

  var myNotification = tizen.notification.get(myId);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
getNotification
Gets a notification that has previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE.
Notification getNotification(NotificationId id);

Since: 4.0

Remark: This method is designed to return new representation of a notification.

Parameters:

  • id: A previously posted notification ID.

Return value:

    Notification: Notification previously been posted by the current application.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if NotificationId is not found in the previously posted notifications.

    • with error type AbortError, if any other error occurs.

Code example:

try
{
  /* Uses a variable for the previously posted notification. */
  /* Saves the notification ID for future use. */
  var myId = notification.id;

  var myNotification = tizen.notification.getNotification(myId);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
getAll
Gets all notifications that have previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE

Deprecated. Deprecated since 4.0. Use getAllNotifications instead.

Notification[] getAll();

Since: 2.0

Remark: This method is designed to return old-style notifications.

Return value:

    Notification[]: All notifications previously been posted by the current application.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  var notifications = tizen.notification.getAll();

  for (var index = 0; index < notifications.length; index++)
  {
    console.log(notifications[index].id);
    console.log(notifications[index].title);
    console.log(notifications[index].statusType);
    console.log(notifications[index].type);
    console.log(notifications[index].content);
    console.log(notifications[index].postedTime);
    console.log(notifications[index].iconPath);
    console.log(notifications[index].soundPath);
    console.log(notifications[index].vibration);
    console.log(notifications[index].appControl);
  }
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
getAllNotifications
Gets all notifications that have previously been posted by the current application. Note that the obtained notification's progressType is PERCENTAGE.
Notification[] getAllNotifications();

Since: 4.0

Remark: This method is designed to return new representation of a notifications.

Return value:

    Notification[]: All notifications posted previously by the current application.

Exceptions:

  • WebAPIException
    • with error type AbortError, if any error occurs.

Code example:

try
{
  var notifications = tizen.notification.getAllNotifications();

  for (var index = 0; index < notifications.length; index++)
  {
    console.log(notifications[index].id);
    console.log(notifications[index].type);
    console.log(notifications[index].userType);
    console.log(notifications[index].content);
    console.log(notifications[index].postedTime);
    console.log(notifications[index].images.iconPath);
    console.log(notifications[index].actions.soundPath);
    console.log(notifications[index].actions.vibration);
    console.log(notifications[index].actions.appControl);
  }
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
playLEDCustomEffect
Plays the custom effect of the service LED that is located to the front of a device.
void playLEDCustomEffect(long timeOn, long timeOff, DOMString color, LEDCustomFlags[] flags);

Since: 2.4

Given parameters consist of timeOn and timeOff in milliseconds, RGBA color and LEDCustomFlags combination. For the color first three bytes are RGB values. The last byte is opacity. For example "#FFFF0080". There is also another possibility when the last byte is not given (in this case alpha is assumed to have a value of 0xff). In this case only RGB values are given. For example: "#ff0000" that is equivalent of "#ff0000ff".

Privilege level: public

Privilege: http://tizen.org/privilege/led

Parameters:

  • timeOn: Turn on time in milliseconds.
  • timeOff: Turn off time in milliseconds.
  • color: The RGBA color value. The first three bytes are RGB values. The last byte is opacity. Exemplary string "#FFFF0080".
  • flags: The combination of enum LEDCustomFlags.

Exceptions:

  • WebAPIException
    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method or if the author signature does not match that of the designated application.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter

    • with error type UnknownError, if the method cannot be completed because of an unknown error.

Code example:

try
{
  tizen.notification.playLEDCustomEffect(
      1000, 1000, "#FFFF0080", ["LED_CUSTOM_DUTY_ON", "LED_CUSTOM_DEFAULT"]);
}
catch (err)
{
  console.log("Error Exception, error name : " + err.name + ", error message : " + err.message);
}
stopLEDCustomEffect
Stops the custom effect of the service LED that is located to the front of a device.
void stopLEDCustomEffect();

Since: 2.4

Privilege level: public

Privilege: http://tizen.org/privilege/led

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if the method cannot be completed because of an unknown error.

Code example:

try
{
  tizen.notification.playLEDCustomEffect(
      1000, 1000, "#FFFF0080", ["LED_CUSTOM_DUTY_ON", "LED_CUSTOM_DEFAULT"]);
  setTimeout(function()
  {
    tizen.notification.stopLEDCustomEffect();
  }, 5000);
}
catch (err)
{
  console.log("Error Exception, error name : " + err.name + ", error message : " + err.message);
}
saveNotificationAsTemplate
Saves a notification template to the notification database.
void saveNotificationAsTemplate(DOMString name, Notification notification);

Since: 4.0

An application can save the created notification as a template for later reuse. If the template has the same name as a saved one, the saved template will be overwritten.

A saved template can be loaded only by the application which saved it. All templates are removed when the application package is uninstalled.

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Remark: The number of templates is limited to 10. When you try to add more than 10 templates, exception is thrown.

Parameters:

  • name: The name of template to be saved.
  • notification: A notification to be saved as a template.

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type QuotaExceededError, if the allowed number of templates is exceeded.

    • with error type AbortError, if the method cannot be completed because of any error.

Code example:

try
{
  var notificationGroupDict =
  {
    content: "This is a progress notification.",
    images: {iconPath: "images/image2.jpg"},
    actions: {soundPath: "music/Over the horizon.mp3", vibration: true}
  };

  /* Constructs the progress notification. */
  var notification =
      new tizen.UserNotification("PROGRESS", "Progress notification", notificationGroupDict);

  tizen.notification.saveNotificationAsTemplate("PROGRESS_TEMPLATE", notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
createNotificationFromTemplate
Creates notification based on previously created template.
UserNotification createNotificationFromTemplate(DOMString name);

Since: 4.0

An application can load a saved template and post it. An application can load only templates that it has saved.

Privilege level: public

Privilege: http://tizen.org/privilege/notification

Remark: This method is designed to return only UserNotification objects, even if the template was saved as StatusNotification.

Parameters:

  • name: The name of template to be used as source of notification.

Return value:

    UserNotification: Created notification.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type NotFoundError, if the method cannot find a template with a given name.

    • with error type AbortError, if the method cannot be completed because of any error.

Code example:

/* The template with name "SIMPLE_TEMPLATE" should be previously created. */
try
{
  var notification = tizen.notification.createNotificationFromTemplate("SIMPLE_TEMPLATE");
  console.log("UserNotification - " + notification.title);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

2.3. Notification

The Notification interface offers common attributes to represent the Notification object.
  [NoInterfaceObject] interface Notification {
    readonly attribute NotificationId id;
    readonly attribute NotificationType type;
    readonly attribute Date postedTime;
    attribute DOMString title;
    attribute DOMString? content;
  };

Since: 2.0

Attributes

  • readonly NotificationId id
    The Notification identifier. Before the notification is posted, this value is undefined.

    Since: 2.0

  • readonly NotificationType type
    The Notification type.

    Since: 2.0

  • readonly Date postedTime
    The time when the notification is posted. Before the notification is posted, this value is undefined.

    Since: 2.0

  • DOMString title
    The title to display in a notification.

    Since: 2.0

  • DOMString content [nullable]
    The content to display in a notification.

    Since: 2.0

2.4. StatusNotificationInit

The properties of StatusNotification, to pass to the constructor.

Deprecated. Deprecated since 4.0. Use UserNotificationInit instead.

  dictionary StatusNotificationInit {
    DOMString? content;
    DOMString? iconPath;
    DOMString? soundPath;
    boolean? vibration;
    ApplicationControl? appControl;
    ApplicationId? appId;
    NotificationProgressType? progressType;
    unsigned long? progressValue;
    long? number;
    DOMString? subIconPath;
    NotificationDetailInfo[]? detailInfo;
    DOMString? ledColor;
    unsigned long ledOnPeriod;
    unsigned long ledOffPeriod;
    DOMString? backgroundImagePath;
    DOMString[]? thumbnails;
  };

Since: 2.0

2.5. UserNotificationInit

The properties of UserNotification, to pass to the constructor, grouped by its functions.
  dictionary UserNotificationInit {
    DOMString? content;
    NotificationTextContentInfo? textContents;
    NotificationImageInfo? images;
    NotificationThumbnailInfo? thumbnails;
    NotificationActionInfo? actions;
    NotificationGroupContentInfo? groupContents;
    NotificationLedInfo? leds;
  };

Since: 4.0

For detailed descriptions of properties, please refer to Notification and UserNotification.

Remark: Some of the specified options might be ignored if the device does not support the related features (e.g. LED notification settings).

2.6. NotificationTextContentInfo

Additional properties of UserNotification. These properties are used for modifying values contained in a notification.
  dictionary NotificationTextContentInfo {
    NotificationProgressType? progressType;
    unsigned long? progressValue;
    long? eventsNumber;
    NotificationDetailInfo[]? detailInfo;
    DOMString[]? buttonsTexts;
    DOMString? contentForOff;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

NotificationProgressType? progressType
Defines the type for a PROGRESS notification's progress. By default, this attribute is set to PERCENTAGE.

Since: 4.0

unsigned long? progressValue
Defines the current notification progress value (PERCENTAGE or BYTE), depending on the progressType.

If progressValue is set, the progressbar will be displayed in the notification. The progressValue can change the amount of progress as it moves forward or backward. It gets the progress value of the current notification. If 0, the indeterminate progressbar will be shown. This attribute only affects for UserNotification of type PROGRESS.

Applications should keep the progress value for their job because the saved value in the notification status tray can be different from the exact progress value.

The range of progressValue for PERCENTAGE progressType is from 0 to 100.

Since: 4.0

Code example:

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

  var notificationGroupDict =
  {
    content: "This is a progress notification.",
    textContents: {progressValue: 20},
    images: {iconPath: "images/image2.jpg"},
    actions: {soundPath: "music/Over the horizon.mp3", vibration: true, appControl: appControl}
  };

  /* Constructs the progress notification. */
  var notification =
      new tizen.UserNotification("PROGRESS", "Progress notification", notificationGroupDict);
  /* Posts the notification. */
  tizen.notification.post(notification);

  /* Updates the progress value of the notification. */
  notification.textContents.progressValue = 59;
  tizen.notification.update(notification);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
long? eventsNumber
The number of events to display in the notification.

Since: 4.0

NotificationDetailInfo[]? detailInfo
Appends lines of the detail information to the notification. This attribute is available in a simple status notification.

By default, this attribute is initialized with an empty array. The maximum number of detail information elements in the array is 2.

Since: 4.0

DOMString[]? buttonsTexts
The text for buttons.

Since: 4.0

DOMString? contentForOff
The content to show when the option to display content is off in the settings.

Since: 4.0

2.7. NotificationImageInfo

Additional properties of UserNotification. These properties are used for modifying the appearance of a notification.
  dictionary NotificationImageInfo {
    DOMString? iconPath;
    DOMString? subIconPath;
    DOMString? indicatorIconPath;
    DOMString? lockScreenIconPath;
    DOMString[]? buttonIconPaths;
    DOMString? backgroundImagePath;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

DOMString? iconPath
The icon path to display in the notification.

Since: 4.0

DOMString? subIconPath
The sub icon path to display in the notification.

Since: 4.0

DOMString? indicatorIconPath
The path for the indicator icon.

Since: 4.0

DOMString? lockScreenIconPath
The path for the lock screen icon.

Since: 4.0

DOMString[]? buttonIconPaths
The paths for button icons.

Since: 4.0

DOMString? backgroundImagePath
The image path to use as the background of the notification. This attribute is available on simple or thumbnail status notifications.

Since: 4.0

2.8. NotificationThumbnailInfo

Additional properties of UserNotification. These properties are used for modifying the thumbnails of a notification.
  dictionary NotificationThumbnailInfo {
    DOMString? lockScreenThumbnailIconPath;
    DOMString? thumbnailIconPath;
    DOMString[]? thumbnails;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

DOMString? lockScreenThumbnailIconPath
The path for the lock screen thumbnail icon.

Since: 4.0

DOMString? thumbnailIconPath
The path for the thumbnail icon.

Since: 4.0

DOMString[]? thumbnails
The image paths associated with the thumbnail status notification.

By default, this attribute is initialized with an empty array. The maximum number of thumbnail path elements in the array is 4.

Since: 4.0

2.9. NotificationActionInfo

Additional properties of UserNotification. These properties are used for modifying the actions related to the notification.
  dictionary NotificationActionInfo {
    DOMString? soundPath;
    boolean? vibration;
    ApplicationControl? appControl;
    ApplicationId? appId;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

DOMString? soundPath
The path of a sound file to play when the notification is shown.

Since: 4.0

boolean? vibration
Checks whether to vibrate when the notification is shown. By default, this attribute is set to false.

Since: 4.0

ApplicationControl? appControl
Holds the application control to launch an application when the notification is selected from the notification tray.

Since: 4.0

ApplicationId? appId
Holds the application ID to launch when the notification is selected from the notification tray.

Since: 4.0

2.10. NotificationGroupContentInfo

Additional properties of UserNotification. These properties are used for modifying the appearance of group content of a notification.
  dictionary NotificationGroupContentInfo {
    DOMString? groupTitle;
    DOMString? groupContent;
    DOMString? groupContentForOff;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

DOMString? groupTitle
The group title.

Since: 4.0

DOMString? groupContent
The group content.

Since: 4.0

DOMString? groupContentForOff
The group content to show when the option to display content is off in the settings.

Since: 4.0

2.11. NotificationLedInfo

Additional properties of UserNotification. These properties are used for modifying the LED behaviour of a notification.
  dictionary NotificationLedInfo {
    DOMString? ledColor;
    unsigned long ledOnPeriod;
    unsigned long ledOffPeriod;
  };

Since: 4.0

Remark: Some members of notification could have no effect depending on the device.

Dictionary members

DOMString? ledColor
Sets the notification LED indicator color property. The color is a numerical RGB value(#rrggbb). The format of an RGB value in hexadecimal notation is a "#" immediately followed by exactly six hexadecimal characters(0-9, A-F). The color format is case-insensitive.

The LED indicator color will show that it's a close approximation. LED will only light on when the screen is off. To turn the LED off, set "#000000" or null to ledColor. This method has effects when the device has a notification LED.

Since: 4.0

unsigned long ledOnPeriod
The milliseconds for which the light is on. The light continuously toggles on (ledOnPeriod) and off (ledOffPeriod). By default, this attribute is set to 0

Since: 4.0

unsigned long ledOffPeriod
The milliseconds for which the light is off. By default, this attribute is set to 0.

Since: 4.0

2.12. StatusNotification

The StatusNotification interface represents a status notification and offers additional attributes to represent a notification displayed in the notification tray.

Deprecated. Deprecated since 4.0. Use UserNotification instead.

  [Constructor(StatusNotificationType statusType, DOMString title, optional StatusNotificationInit? notificationInitDict)]
  interface StatusNotification : Notification {
    readonly attribute StatusNotificationType statusType;
    attribute DOMString? iconPath;
    attribute DOMString? subIconPath;
    attribute long? number;
    attribute NotificationDetailInfo[]? detailInfo;
    attribute DOMString? ledColor;
    attribute unsigned long ledOnPeriod;
    attribute unsigned long ledOffPeriod;
    attribute DOMString? backgroundImagePath;
    attribute DOMString[]? thumbnails;
    attribute DOMString? soundPath;
    attribute boolean vibration;
    attribute ApplicationControl? appControl;
    attribute ApplicationId? appId;
    attribute NotificationProgressType progressType;
    attribute unsigned long? progressValue;
  };

Since: 2.0

All notifications must have a title attribute.

Warning: Some members of notification could have no effect depending on the device.

Constructors

Constructor (StatusNotificationType, DOMString, StatusNotificationInit?)
StatusNotification(StatusNotificationType statusType, DOMString title, optional StatusNotificationInit? notificationInitDict);

Attributes

  • readonly StatusNotificationType statusType
    The status notification type.

    Since: 2.0

  • DOMString iconPath [nullable]
    The icon path to display in the notification.

    Since: 2.0

  • DOMString subIconPath [nullable]
    The sub icon path to display in the notification.

    Since: 2.1

  • long number [nullable]
    The number of events to display in the notification.

    Since: 2.1

  • NotificationDetailInfo[] detailInfo [nullable]
    Appends lines of the detail information to the notification. This attribute is available in a simple status notification. By default, this attribute is initialized with an empty array. The maximum number of detail information elements in the array is 2.

    Since: 2.1

  • DOMString ledColor [nullable]
    Sets the notification LED indicator color property. The color is a numerical RGB value(#rrggbb). The format of an RGB value in hexadecimal notation is a "#" immediately followed by exactly six hexadecimal characters(0-9, A-F). The color format is case-insensitive. The LED indicator color will show that it's a close approximation. LED will only light on when the screen is off. To turn the LED off, set "#000000" or null to ledColor. This method has effects when the device has notification LED.

    Since: 2.2

    Code example:

    try
    {
      var notificationDict =
      {
        content: "This is a simple notification.",
        iconPath: "images/image1.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        ledColor: "#FFFF00",
        ledOnPeriod: 1000,
        ledOffPeriod: 500
      };
    
      var notification =
          new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);
    
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • unsigned long ledOnPeriod
    The milliseconds for which the light is on. The light continuously toggles on (ledOnPeriod) and off (ledOffPeriod). By default, this attribute is set to 0

    Since: 2.2

  • unsigned long ledOffPeriod
    The milliseconds for which the light is off. By default, this attribute is set to 0.

    Since: 2.2

  • DOMString backgroundImagePath [nullable]
    The image path to use as the background of the notification. This attribute is available on simple or thumbnail status notifications.

    Since: 2.1

  • DOMString[] thumbnails [nullable]
    The image paths associated with the thumbnail status notification. By default, this attribute is initialized with an empty array. The maximum number of thumbnail path elements in the array is 4.

    Since: 2.1

  • DOMString soundPath [nullable]
    The path of a sound file to play when the notification is shown.

    Since: 2.0

  • boolean vibration
    Checks whether to vibrate when the notification is shown. By default, this attribute is set to false.

    Since: 2.0

  • ApplicationControl appControl [nullable]
    Holds the application control to launch an application when the notification is selected from the notification tray.

    Since: 2.0

  • ApplicationId appId [nullable]
    Holds the application ID to launch when the notification is selected from the notification tray.

    Since: 2.0

    Code example:

    try
    {
      /* Gets the current application information with tizen.application.getAppInfo. */
      var myappInfo = tizen.application.getAppInfo();
    
      var notificationDict =
      {
        content: "This is a simple notification.",
        iconPath: "images/image1.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        appId: myappInfo.id
      };
    
      var notification =
          new tizen.StatusNotification("SIMPLE", "Simple notification", notificationDict);
    
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationProgressType progressType
    Defines the type for an ongoing notification's progress. By default, this attribute is set to PERCENTAGE.

    Since: 2.1

  • unsigned long progressValue [nullable]
    Defines the current notification progress value (PERCENTAGE or BYTE), depending on the progressType

    If progressValue is set, the progressbar will be displayed in the notification. The progressValue can change the amount of progress as it moves forward or backward. It gets the progress value of the current notification. If 0, the indeterminate progressbar will be shown. This attribute is only available for StatusNotification of type PROGRESS.

    Applications should keep the progress value for its job because the saved value in the notification status tray would be different from the exact progress value.

    The range of progressValue: percent (0 to 100).

    Since: 2.0

    Code example:

    try
    {
      var appControl = new tizen.ApplicationControl(
          "http://tizen.org/appcontrol/operation/create_content", null, "image/jpg", null);
    
      var notificationDict =
      {
        content: "This is a progress notification.",
        iconPath: "images/image2.jpg",
        soundPath: "music/Over the horizon.mp3",
        vibration: true,
        appControl: appControl,
        progressValue: 20
      };
      /* Constructs the progress notification. */
      var notification =
          new tizen.StatusNotification("PROGRESS", "Progress notification", notificationDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    
      /* Updates the progress value of the notification. */
      notification.progressValue = 59;
      tizen.notification.update(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    

2.13. UserNotification

The UserNotification interface represents a notification and offers additional attributes to represent a notification displayed in the notification tray.
  [Constructor(UserNotificationType userType, DOMString title, optional UserNotificationInit? notificationGroupedInitDict)]
  interface UserNotification : Notification {
    readonly attribute UserNotificationType userType;
    attribute NotificationTextContentInfo? textContents;
    attribute NotificationImageInfo? images;
    attribute NotificationThumbnailInfo? thumbnails;
    attribute NotificationActionInfo? actions;
    attribute NotificationGroupContentInfo? groupContents;
    attribute NotificationLedInfo? leds;
  };

Since: 4.0

All notifications must have a title attribute.

Warning: Some members of notification could have no effect depending on the device.

Constructors

Constructor (UserNotificationType, DOMString, UserNotificationInit?)
UserNotification(UserNotificationType userType, DOMString title, optional UserNotificationInit? notificationGroupedInitDict);

Attributes

  • readonly UserNotificationType userType
    The type of notification.

    Since: 4.0

  • NotificationTextContentInfo textContents [nullable]
    Defines content-related settings of a notification.

    If this is null, all property values of a NotificationTextContentInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var notificationGroupDict =
      {
        content: "This is a progress notification.",
        textContents: {progressValue: 20}
      };
    
      /* Constructs the progress notification. */
      var notification =
          new tizen.UserNotification("PROGRESS", "Progress notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    
      /* Updates the progress value of the notification. */
      notification.textContents.progressValue = 59;
      tizen.notification.update(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationImageInfo images [nullable]
    Defines additional image-related settings of a notification.

    If this is null, all property values of a NotificationImageInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var notificationGroupDict =
      {
        content: "This is a SIMPLE notification with icon.",
        images: {iconPath: "images/image2.jpg"}
      };
    
      /* Constructs the simple notification. */
      var notification =
          new tizen.UserNotification("SIMPLE", "Simple notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationThumbnailInfo thumbnails [nullable]
    Defines additional thumbnail-related settings of a notification.

    If this is null, all property values of a NotificationThumbnailInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var notificationGroupDict =
      {
        content: "This is an ongoing notification with thumbnail and icon",
        images: {iconPath: "images/image2.jpg"},
        thumbnails: {thumbnailIconPath: "images/thumbnail.jpg"}
      };
    
      /* Constructs the ongoing notification. */
      var notification =
          new tizen.UserNotification("ONGOING", "Ongoing notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationActionInfo actions [nullable]
    Defines additional action-related settings of a notification.

    If this is null, all property values of a NotificationActionInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var appControl = new tizen.ApplicationControl(
          "http://tizen.org/appcontrol/operation/create_content", null, "image/jpg", null);
    
      var notificationGroupDict =
      {
        content: "This is a progress notification with sound and appcontrol",
        images: {iconPath: "images/image2.jpg"},
        actions: {soundPath: "music/Over the horizon.mp3", vibration: true, appControl: appControl}
      };
    
      /* Constructs the progress notification. */
      var notification =
          new tizen.UserNotification("PROGRESS", "Progress notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationGroupContentInfo groupContents [nullable]
    Defines additional group-content-related settings of a notification.

    If this is null, all property values of a NotificationGroupContentInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var notificationGroupDict =
      {
        content: "This is a progress notification with groupContents",
        groupContents: {groupTitle: "A group title", groupContent: "Some group content"},
        images: {iconPath: "images/image2.jpg"}
      };
    
      /* Constructs the progress notification with groupContents. */
      var notification =
          new tizen.UserNotification("PROGRESS", "Progress notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    
  • NotificationLedInfo leds [nullable]
    Defines additional LED-related settings of a notification.

    If this is null, all property values of a NotificationLedInfo dictionary are ignored.

    Since: 4.0

    Code example:

    try
    {
      var notificationGroupDict =
      {
        content: "This is a SIMPLE notification with blinking LED",
        leds: {ledColor: "#FFFF00", ledOnPeriod: 1000, ledOffPeriod: 500}
      };
    
      /* Constructs the simple notification. */
      var notification =
          new tizen.UserNotification("SIMPLE", "Simple notification", notificationGroupDict);
      /* Posts the notification. */
      tizen.notification.post(notification);
    }
    catch (err)
    {
      console.log(err.name + ": " + err.message);
    }
    

2.14. NotificationDetailInfo

The NotificationDetailInfo object that contains the detail information of the notification.
  [Constructor(DOMString mainText, optional DOMString? subText)]
  interface NotificationDetailInfo {
    attribute DOMString mainText;
    attribute DOMString? subText;
  };

Since: 2.1

Code example:

var detailInfo1 = new tizen.NotificationDetailInfo("Missed Call from James", "Feb 11 2013");
notification.detailInfo = [detailInfo1];

Constructors

Constructor (DOMString, DOMString?)
NotificationDetailInfo(DOMString mainText, optional DOMString? subText);

Attributes

  • DOMString mainText
    The main content of the detail information. This attribute is available on simple status notifications.

    Since: 2.1

  • DOMString subText [nullable]
    The secondary content of the detail information.

    By default, this attribute is set to null.

    Since: 2.1

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

If an application uses playLEDCustomEffect() or stopLEDCustomEffect(), declare the following feature requirements in the config file to guarantee the running of this application on a device which has an LED:

  • http://tizen.org/feature/led
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Notification {
      typedef DOMString NotificationId;
      enum NotificationType { "STATUS" };
      enum UserNotificationType { "SIMPLE", "THUMBNAIL", "ONGOING", "PROGRESS" };
      enum NotificationProgressType { "PERCENTAGE", "BYTE" };
      enum LEDCustomFlags { "LED_CUSTOM_DUTY_ON", "LED_CUSTOM_DEFAULT" };
      dictionary UserNotificationInit {
        DOMString? content;
        NotificationTextContentInfo? textContents;
        NotificationImageInfo? images;
        NotificationThumbnailInfo? thumbnails;
        NotificationActionInfo? actions;
        NotificationGroupContentInfo? groupContents;
        NotificationLedInfo? leds;
      };
      dictionary NotificationTextContentInfo {
        NotificationProgressType? progressType;
        unsigned long? progressValue;
        long? eventsNumber;
        NotificationDetailInfo[]? detailInfo;
        DOMString[]? buttonsTexts;
        DOMString? contentForOff;
      };
      dictionary NotificationImageInfo {
        DOMString? iconPath;
        DOMString? subIconPath;
        DOMString? indicatorIconPath;
        DOMString? lockScreenIconPath;
        DOMString[]? buttonIconPaths;
        DOMString? backgroundImagePath;
      };
      dictionary NotificationThumbnailInfo {
        DOMString? lockScreenThumbnailIconPath;
        DOMString? thumbnailIconPath;
        DOMString[]? thumbnails;
      };
      dictionary NotificationActionInfo {
        DOMString? soundPath;
        boolean? vibration;
        ApplicationControl? appControl;
        ApplicationId? appId;
      };
      dictionary NotificationGroupContentInfo {
        DOMString? groupTitle;
        DOMString? groupContent;
        DOMString? groupContentForOff;
      };
      dictionary NotificationLedInfo {
        DOMString? ledColor;
        unsigned long ledOnPeriod;
        unsigned long ledOffPeriod;
      };
      Tizen implements NotificationObject;
      [NoInterfaceObject] interface NotificationObject {
        readonly attribute NotificationManager notification;
      };
      [NoInterfaceObject] interface NotificationManager {
        void post(Notification notification) raises(WebAPIException);
        void update(Notification notification) raises(WebAPIException);
        void remove(NotificationId id) raises(WebAPIException);
        void removeAll() raises(WebAPIException);
        Notification getNotification(NotificationId id) raises(WebAPIException);
        Notification[] getAllNotifications() raises(WebAPIException);
        void playLEDCustomEffect(long timeOn, long timeOff, DOMString color, LEDCustomFlags[] flags) raises(WebAPIException);
        void stopLEDCustomEffect() raises(WebAPIException);
        void saveNotificationAsTemplate(DOMString name, Notification notification) raises(WebAPIException);
        UserNotification createNotificationFromTemplate(DOMString name) raises(WebAPIException);
      };
      [NoInterfaceObject] interface Notification {
        readonly attribute NotificationId id;
        readonly attribute NotificationType type;
        readonly attribute Date postedTime;
        attribute DOMString title;
        attribute DOMString? content;
      };
      [Constructor(UserNotificationType userType, DOMString title, optional UserNotificationInit? notificationGroupedInitDict)]
      interface UserNotification : Notification {
        readonly attribute UserNotificationType userType;
        attribute NotificationTextContentInfo? textContents;
        attribute NotificationImageInfo? images;
        attribute NotificationThumbnailInfo? thumbnails;
        attribute NotificationActionInfo? actions;
        attribute NotificationGroupContentInfo? groupContents;
        attribute NotificationLedInfo? leds;
      };
      [Constructor(DOMString mainText, optional DOMString? subText)]
      interface NotificationDetailInfo {
        attribute DOMString mainText;
        attribute DOMString? subText;
      };
    };