Application

The Application object provides functions and properties for the currently running application.

Warning ( Playbook 1.0 Notice):

For URI based APIs, webworks:// has been deprecated and replaced with http://localhost:8472. This change does not affect the procedural APIs.

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook
- Ripple Emulator

View Supported Platform Table

API	OS 5.0	OS 6.0	OS 7.0	PlayBook	Ripple
exit	Y	Y	Y	Y	Y
removeBannerIndicator	Y	Y	Y		Y
requestBackground	Y	Y	Y		Y
requestForeground	Y	Y	Y		Y
setHomeScreenIcon	Y	Y	Y		Y
setHomeScreenName	Y	Y	Y		Y
showBannerIndicator	Y	Y	Y		Y
http://localhost:8472/blackberry/app/get				Y
author	Y	Y	Y	Y	Y
authorEmail	Y	Y	Y	Y	Y
authorURL	Y	Y	Y	Y	Y
copyright	Y	Y	Y	Y	Y
description	Y	Y	Y	Y	Y
id	Y	Y	Y	Y	Y
isForeground	Y	Y	Y		Y
license	Y	Y	Y	Y	Y
licenseURL	Y	Y	Y	Y	Y
name	Y	Y	Y	Y	Y
version	Y	Y	Y	Y	Y

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature ID	OS 5.0	OS 6.0	OS 7.0	PlayBook	Ripple
<feature id="blackberry.app" />	Y	Y	Y	Y	Y

Permission Elements (PlayBook Only)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

API Summary

Functions

Properties

URI Functions

http://localhost:8472/blackberry/app/get

exit

static void exit()

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook
- Ripple Emulator

Description

This function will cause the application to exit.

removeBannerIndicator

static void removeBannerIndicator()

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This function will remove the indicator on the banner.

requestBackground

static void requestBackground()

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This function will move the application to the background.

requestForeground

static void requestForeground()

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This function will move the application to the foreground application.

setHomeScreenIcon

static Boolean setHomeScreenIcon(uri : String, [hover: Boolean])

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This method will set the icon that appears in the Home Screen of the Smartphone.

Returns

Returns true if successful, false otherwise. The hover icon can only be set when the application icon has been set first. Changes made using this API are NOT persisted across PlayBook resets.

Parameter	Type	Description
uri	String	Location of the image to use for the icon. The path to the image resource must be fully qualified. An example of a fully qualified path is local:///resourceFolder/icons/icon.png. The path to the resource must also be included in the whitelist. For example, accessing an image on the file system requires 'file:///' to be whitelisted
hover	Boolean Optional	[Default Value: false] If set to true then the hover icon for the application is changed. By default this is false, so the icon that is changed is the default main icon for the application.

setHomeScreenName

static Boolean setHomeScreenName(text : String)

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This method will set the text for the icon that appears in the Home Screen of the Smartphone.

Returns

Returns true if successful, false otherwise. Changes made using this API are NOT persisted across resets.

Parameter	Type	Description
text	String	Text to appear on the home screen icon.

showBannerIndicator

static void showBannerIndicator(icon : String, [value: Number])

Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator

Description

This function will show an icon on the banner. A banner indicator can have an optional numeric value that usually serves as a counter. The value can be negative, 0, or positive. If the indicator is used as a counter then the best practice is to hide it when its value is equal to 0. Some applications may choose to show 0 as a counter value if such information is important to user, for example, the number of financial transactions in the current business day. Due to limited real estate, the indicator value can be truncated if it is very large. In such case the indicator will display '99+' or '999+', which means 'over a hundred' or 'over a thousand'.

Indicators are not guaranteed to be displayed. Different factors play a role in whether the indicator is displayed, such as available indicators space, number of registered indicators, and current application preferences. Application indicators have the lowest drawing priority compared to system indicators such as the unread email counter or missed calls indicator.

Parameter	Type	Description
icon	String	The name of the icon to show on the banner. The icon must be a local resource and it's size varies from 10x10 up to 32x32 depending on current theme and device screen size.
value	Number Optional	Optional parameter to indicate the number to show on the banner.

Properties:

Property	Type	Description	Supported Platform(s)
author	Static String	The ID of the author's name that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
authorEmail	Static String	The author's email of the BlackBerry WebWorks application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
authorURL	Static String	The author's URL of the BlackBerry WebWorks application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
copyright	Static String	The copyright information of the BlackBerry WebWorks application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
description	Static String	The description of the BlackBerry WebWorks application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
id	Static String	The ID of the BlackBerry WebWorks Application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
isForeground	Static Boolean	A property that will return true if the BlackBerry WebWorks Application is in the foreground.	- BlackBerry OS 5.0+ - Ripple Emulator
license	Static String	The license of the BlackBerry WebWorks Application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
licenseURL	Static String	The license URL of the BlackBerry WebWorks Application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
name	Static String	The name of the BlackBerry WebWorks Application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator
version	Static String	The version of the BlackBerry WebWorks Application that is specified in the config.xml file.	- BlackBerry OS 5.0+ - BlackBerry PlayBook - Ripple Emulator

http://localhost:8472/blackberry/app/get

Supported Platform(s)

- BlackBerry PlayBook

Description

Returns a JSON object containing all properties of the application.

Returns

{
	"data":{
		"author":"John Doe",
		"name":"My WebWorks Widget",
		"authorEmail":"jdoe@company.com",
		"authorURL":"www.company.com",
		"description":"A sample widget",
		"license":"Legal stuff goes here",
		"id":"888",
		"version":"1.0",
		"copyright":"Company Ltd.",
		"licenseURL":"www.company.com/license"
	}
}

Code Example(s)

<html>
<head>
    <script type="text/javascript" src="js/jquery-1.4.2.js" ></script>
    <script type="text/javascript" src="js/jquery.form.js" ></script>
    <script type="text/javascript" src="js/jquery.populate.js" ></script>
    
    <script type="text/javascript">  
	function getAppData(){
		$.ajax({
		    type: "get",
		    url: "http://localhost:8472/blackberry/app/get",
		    success: function(msg){
		      $('#myAppDiv').populate(JSON.parse(msg).data);
		    }
		});
	}
     </script>
     
</head>
<body>

   <input type="button" onclick="getAppData();" value="Populate - APP"/>
   <div id="myAppDiv">
       Name: <span id="author"></span><br/>
       ID: <span id="id"></span>
   </div>
   
</body>
</html>

Code Example(s)

<script type="text/javascript">
	function makeTable() {
		try {
			var details = document.getElementById("details");
			if (details) {
				var output = "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
				output += "";
			
				details.innerHTML = output;
			}
		} catch(e) {
			alert("Exception in displayDetails: " + e);
		}
	}
</script>

            
            Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:15 GMT-0500 (EST)
        
Author " + blackberry.app.author + "
Author Email " + blackberry.app.authorEmail + "
Author URL " + blackberry.app.authorURL + "
Copyright " + blackberry.app.copyright + "
Description " + blackberry.app.description + "
ID " + blackberry.app.id + "
License " + blackberry.app.license + "
License URL " + blackberry.app.licenseURL + "
Name " + blackberry.app.name + "
Version " + blackberry.app.version + "

Author	" + blackberry.app.author + "
Author Email	" + blackberry.app.authorEmail + "
Author URL	" + blackberry.app.authorURL + "
Copyright	" + blackberry.app.copyright + "
Description	" + blackberry.app.description + "
ID	" + blackberry.app.id + "
License	" + blackberry.app.license + "
License URL	" + blackberry.app.licenseURL + "
Name	" + blackberry.app.name + "
Version	" + blackberry.app.version + "