Badge API
For more information about how to use Badge API, see Badge Guide.
Since: 2.3
Table of Contents
- 1. Interfaces
- 1.1. BadgeManagerObject
- 1.2. BadgeManager
- 1.3. BadgeChangeCallback
- 2. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
BadgeManagerObject | |
BadgeManager |
void setBadgeCount (ApplicationId appId, long count)
long getBadgeCount (ApplicationId appId)
void removeChangeListener (ApplicationId[] appIdList)
|
BadgeChangeCallback | void onsuccess (ApplicationId appId, long count) |
1. Interfaces
1.1. BadgeManagerObject
[NoInterfaceObject] interface BadgeManagerObject { readonly attribute BadgeManager badge; };
Tizen implements BadgeManagerObject;
Since: 2.3
There is a tizen.badge object that allows accessing the functionality of the Badge API.
Attributes
-
readonly
BadgeManager badgeObject representing a badge manager object.
Since: 2.3
1.2. BadgeManager
[NoInterfaceObject] interface BadgeManager { readonly attribute long maxBadgeCount; void setBadgeCount(ApplicationId appId, long count) raises(WebAPIException); long getBadgeCount(ApplicationId appId) raises(WebAPIException); void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback) raises(WebAPIException); void removeChangeListener(ApplicationId[] appIdList) raises(WebAPIException); };
Since: 2.3
Attributes
-
readonly
long maxBadgeCountMaximum length of a badge number.
Since: 2.3
Code example:
console.log("Maximum length of a badge number is " + tizen.badge.maxBadgeCount);
Methods
-
setBadgeCount
-
Sets the badge count for the designated application. Only applications with the same author signature can have their badge count modified.
void setBadgeCount(ApplicationId appId, long count);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/notification
Parameters:
- appId: ID of the application to update the badge.
-
count:
Number to display as the badge on the application icon
To remove the badge, set the value of this param to 0.
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 UnknownError, if the method cannot be completed because of an unknown error.
Code example:
var app = tizen.application.getCurrentApplication(); var appid = app.appInfo.id; tizen.badge.setBadgeCount(appid, 3);
-
getBadgeCount
-
Gets the badge count for the designated application.
long getBadgeCount(ApplicationId appId);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/notification
Parameters:
- appId: ID of the designated application.
Return value:
-
long:
Count of the badge.
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 UnknownError, if the method cannot be completed because of an unknown error.
Code example:
var app = tizen.application.getCurrentApplication(); var appid = app.appInfo.id; var count = tizen.badge.getBadgeCount(appid);
-
addChangeListener
-
Adds a listener to receive a notification when the badge number for the designated application changes.
void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/notification
Parameters:
- appIdList: Array of the ID of the designated application.
- successCallback: Callback method to be invoked when a badge number change notification is received.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not of the expected type for that parameter.
with error type InvalidValuesError, if any of the input parameters contains an invalid value.
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:
/* Assume that at least two applications are installed. */ function onListInstalledApps(appsInfo) { function watcher(appId, count) { console.log(appId + " badge number were updated: " + count); } /* Registers to be notified when the badge number changes. */ tizen.badge.addChangeListener([appsInfo[0].id, appsInfo[1].id], watcher); } tizen.application.getAppsInfo(onListInstalledApps);
-
removeChangeListener
-
Unsubscribes from receiving notifications for badge number changes.
void removeChangeListener(ApplicationId[] appIdList);
Since: 2.3
Nothing will be done for app ids which do not have any registered listeners.
Privilege level: public
Privilege: http://tizen.org/privilege/notification
Parameters:
- appIdList: Array of the ID of the designated application.
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 UnknownError if any other error occurs.
Code example:
/* Assume that at least two applications are installed. */ function onListInstalledApps(appsInfo) { function watcher(appId, count) { console.log(appId + " badge number were updated: " + count); } /* Registers to be notified when the badge number changes. */ tizen.badge.addChangeListener([appsInfo[0].id, appsInfo[1].id], watcher); /* Cancels the watch operation. */ tizen.badge.removeChangeListener([appsInfo[0].id, appsInfo[1].id]); } tizen.application.getAppsInfo(onListInstalledApps);
1.3. BadgeChangeCallback
[Callback=FunctionOnly, NoInterfaceObject] interface BadgeChangeCallback { void onsuccess(ApplicationId appId, long count); };
Since: 2.3
Methods
-
onsuccess
-
Called when the badge number of a specified application is updated.
void onsuccess(ApplicationId appId, long count);
Since: 2.3
Parameters:
- appId: ID of the designated application.
- count: Count of the badge.
Code example:
/* Logs the number of badge changes. */ function watcher(appId, count) { console.log(appId + " -> badge number updates: " + count); } /* Gets Application's ID. */ var appId = tizen.application.getCurrentApplication().appInfo.id; /* Assume that the application "TestSample.main" has been installed. */ var targetAppId = "TestSample.main"; /* Registers to be notified when the badge number changes for either */ /* this or targetAppId application. */ tizen.badge.addChangeListener([appId, targetAppId], watcher);
2. Full WebIDL
module Badge { Tizen implements BadgeManagerObject; [NoInterfaceObject] interface BadgeManagerObject { readonly attribute BadgeManager badge; }; [NoInterfaceObject] interface BadgeManager { readonly attribute long maxBadgeCount; void setBadgeCount(ApplicationId appId, long count) raises(WebAPIException); long getBadgeCount(ApplicationId appId) raises(WebAPIException); void addChangeListener(ApplicationId[] appIdList, BadgeChangeCallback successCallback) raises(WebAPIException); void removeChangeListener(ApplicationId[] appIdList) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface BadgeChangeCallback { void onsuccess(ApplicationId appId, long count); }; };