Application

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


Code Example:
<script type="text/javascript">
 function makeTable() {
   try {
     var details = document.getElementById("details");
     if (details) {
       var output = "<table>";
       output += "<tr><td><b>Author</td><td>" + blackberry.app.author + "</td></tr>";
       output += "<tr><td><b>Author Email</b></td><td>" + blackberry.app.authorEmail + "</td></tr>";
       output += "<tr><td><b>Author URL</b></td><td>" + blackberry.app.authorURL + "</td></tr>";
       output += "<tr><td><b>Copyright</b></td><td>" + blackberry.app.copyright + "</td></tr>";
       output += "<tr><td><b>Description</b></td><td>" + blackberry.app.description + "<</tr>";
       output += "<tr><td><b>ID</b></td><td>" + blackberry.app.id + "</td></tr>";
       output += "<tr><td><b>License</b></td><td>" + blackberry.app.license + "</td></tr>";
       output += "<tr><td><b>License URL</b></td><td>" + blackberry.app.licenseURL + "</td></tr>";
       output += "<tr><td><b>Name</b></td><td>" + blackberry.app.name + "</td></tr>";
       output += "<tr><td><Version</b></td><td>" + blackberry.app.version + "</td></tr>";
       output += "<tr><td><Orientation</b></td><td>" + blackberry.app.orientation + "</td></tr>";
       output += "<tr><td><Window State</b></td><td>" + blackberry.app.windowState + "</td></tr>";

       details.innerHTML = output;
     }
   } catch(e) {
       alert("Exception in displayDetails: " + e);
   }
 }
</script>


Learning Resources:

Sample - Using Orientation Sample that demonstrates how to use the Orientation API [BlackBerry on GitHub].

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.app.exit Y Y Y Y Y YY
blackberry.app.lockOrientation           YY
blackberry.app.minimize           Y 
blackberry.app.removeBannerIndicator Y Y Y      Y
blackberry.app.requestBackground Y Y Y      Y
blackberry.app.requestForeground Y Y Y      Y
blackberry.app.rotate           YY
blackberry.app.setHomeScreenIcon Y Y Y      Y
blackberry.app.setHomeScreenName Y Y Y      Y
blackberry.app.showBannerIndicator Y Y Y      Y
blackberry.app.unlockOrientation           YY
http://localhost:8472/blackberry/app/get       Y Y   
author Y Y Y Y Y YY
authorEmail Y Y Y Y Y YY
authorURL Y Y Y Y Y YY
copyright Y Y Y Y Y YY
description Y Y Y Y Y YY
id Y Y Y Y Y YY
isForeground Y Y Y      Y
license Y Y Y Y Y YY
licenseURL Y Y Y Y Y YY
name Y Y Y Y Y YY
orientation           YY
version Y Y Y Y Y YY
windowState           Y 
blackberry.app.keyboardClosed           Y 
blackberry.app.keyboardClosing           Y 
blackberry.app.keyboardOpened           Y 
blackberry.app.keyboardOpening           Y 
blackberry.app.keyboardPosition           Y 
blackberry.app.orientationchange           Y 
blackberry.app.pause           Y 
blackberry.app.resume           Y 
blackberry.app.swipedown           Y 
blackberry.app.windowstatechanged           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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.app" /> Y Y Y Y Y YY

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



Properties

String author
String authorEmail
String authorURL
String copyright
String description
String id
Boolean isForeground
String license
String licenseURL
String name
String orientation
String version
String windowState

URI Functions

JSON of all the properties http://localhost:8472/blackberry/app/get

Functions

static void blackberry.app.exit ()


This function will cause the application to exit.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static void blackberry.app.lockOrientation (orientation : String, [recieveRotateEvents : Boolean])


This function will lock the application's screen to the given orientation.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
orientation The orientation to lock the device to. If the device is currently not in this orientation, the application will rotate then lock.Orientation can be landscape-primary, landscape-secondary, portrait-primary, portrait-secondary.
recieveRotateEvents [Default Value: true]

If set to true, rotation events will be sent and bezel gestures will be aligned with the physical rotation of the device.

static void blackberry.app.minimize ()


Minimizes the application window to a thumbnail and sends the user to the application switcher on the home screen. This will trigger the pause event.


Supported Platforms
 - BlackBerry 10

static void blackberry.app.removeBannerIndicator ()


This function will remove the indicator on the banner.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static void blackberry.app.requestBackground ()


This function will move the application to the background.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static void blackberry.app.requestForeground ()


This function will move the application to the foreground application.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static void blackberry.app.rotate (orientation : String)


This function will rotate the application even if the application is locked.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
orientation The orientation to rotate the device to. Orientation can be landscape-primary, landscape-secondary, portrait-primary, portrait-secondary.

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


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


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
uri 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 [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.


Return:

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.


static Boolean blackberry.app.setHomeScreenName (text : String)


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


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
text Text to appear on the home screen icon.

Return:

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


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


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
icon 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 Optional parameter to indicate the number to show on the banner.

static void blackberry.app.unlockOrientation ()


This function will unlock the screen rotating if it was previously locked.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

Events

blackberry.app.keyboardClosed


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The keyboardClosed event is triggered when the virtual keyboard has finished sliding out of view of the application.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the keyboardClosed event

Code Example:
<script type="text/javascript">

function onKeyboardClosed() {
  console.log("Keyboard closed event occured.");
}

blackberry.event.addEventListener("keyboardClosed", onKeyboardClosed);

</script>

blackberry.app.keyboardClosing


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The keyboardClosing event is triggered when the virtual keyboard is toggled to slide out of view of the application.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the keyboardClosing event

Code Example:
<script type="text/javascript">

function onKeyboardClosing() {
  console.log("Keyboard closing event occured.");
}

blackberry.event.addEventListener("keyboardClosing", onKeyboardClosing);

</script>

blackberry.app.keyboardOpened


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The keyboardOpened event is triggered when the virtual keyboard has finished sliding into view of the application.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the keyboardOpening event

Code Example:
<script type="text/javascript">

function onKeyboardOpened() {
  console.log("Keyboard opened event occured.");
}

blackberry.event.addEventListener("keyboardOpened", onKeyboardOpened);

</script>

blackberry.app.keyboardOpening


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The keyboardOpening event is triggered when the virtual keyboard is toggled to slide into view of the application.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the keyboardOpening event

Code Example:
<script type="text/javascript">

function onKeyboardOpening() {
  console.log("Keyboard opened event occured.");
}

blackberry.event.addEventListener("keyboardOpening", onKeyboardOpening);

</script>

blackberry.app.keyboardPosition


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The keyboardPosition event is triggered when the virtual keyboard's position has changed.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the keyboardPosition event

yPosition: The absolute position of the virtual keyboard on the Y-axis of the screen.

Code Example:
<script type="text/javascript">

function onKeyboardPosition() {
  console.log("Keyboard position event occured. Keyboard position is " + yPosition + "px");
}

blackberry.event.addEventListener("keyboardPosition", onKeyboardPosition);

</script>

blackberry.app.orientationchange


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The orientationchange event is triggered when the user changes the orientation of the device.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the orientationchange event. Orientation can be landscape-primary, landscape-secondary, portrait-primary, portrait-secondary.

Code Example:
<script type="text/javascript">

function onOrientationChange(orientation) {
  alert("New orientation is: " + orientation);
}

blackberry.event.addEventListener("orientationchange", onOrientationChange);

</script>

blackberry.app.pause


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The pause event is triggered whenever the the application is put into the background.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the pause event

Code Example:
<script type="text/javascript">

function onPause() {
  alert("The app is about to be paused.");
}

blackberry.event.addEventListener("pause", onPause);

</script>

blackberry.app.resume


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The resume event is triggered whenever the the application is retrieved from the background.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the resume event

Code Example:
<script type="text/javascript">

function onResume() {
  alert("The app is resumed.");
}

blackberry.event.addEventListener("resume", onResume);

</script>

blackberry.app.swipedown


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The swipedown event is triggered when the user swipes down from the top of the application.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the swipedown event

Code Example:
<script type="text/javascript">

function onSwipedown() {
  alert("Swipe down event occured.");
}

blackberry.event.addEventListener("swipedown", onSwipedown);

</script>

blackberry.app.windowstatechanged


This event is fired by the system. If you want to listen to the event you can do so using the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
The windowstatechanged event is triggered whenever the application window's state has changed. Something important to note is that this event will not be triggered on application startup. If you need to know the window state when an application starts, look at the value of the windowState property.


Supported Platforms
 - BlackBerry 10


Parameters
yourCallbackFunction The callback function that will be invoked on the windowstatechanged event

state: The new window state of the application (i.e. "fullscreen", "thumbnail", or "invisible")

Code Example:
<script type="text/javascript">

function onWindowStateChange(state) {
  alert("Window state was changed to: " + state);
}

blackberry.event.addEventListener("windowstatechanged", onWindowStateChange);

</script>

Properties

static String author


The ID of the author's name that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String authorEmail


The author's email of the BlackBerry WebWorks application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String authorURL


The author's URL of the BlackBerry WebWorks application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String copyright


The copyright information of the BlackBerry WebWorks application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String description


The description of the BlackBerry WebWorks application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String id


The ID of the BlackBerry WebWorks Application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static Boolean isForeground


A property that will return true if the BlackBerry WebWorks Application is in the foreground.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static String license


The license of the BlackBerry WebWorks Application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String licenseURL


The license URL of the BlackBerry WebWorks Application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String name


The name of the BlackBerry WebWorks Application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String orientation


The current orientation of the BlackBerry device.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String version


The version of the BlackBerry WebWorks Application that is specified in the config.xml file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator

static String windowState


The current window state of the application. This will be equal to "fullscreen" when the application is considered to be fullscreen and should be running normally. It will have a value of "thumbnail" when the application has been sized smaller than fullscreen. It will be equal to "invisible" when the application's window is not visible to the user. This could be due to being positioned off the screen or when the LCD is turned off.


Supported Platforms
 - BlackBerry 10

URI Functions

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


Returns a JSON object containing all properties of the application.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Return:
 {
    "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:
<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>
Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:02 GMT-0500 (EST)