Application

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

Installation:

To use this API in your project, add the app plugin:

webworks plugin add com.blackberry.app

Learning Resources:

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

Example:

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>
Functions:
void exit()
void lockOrientation()
void minimize()
void rotate()
void unlockOrientation()
Properties:
String author
String authorEmail
String authorURL
String copyright
String description
String id
String license
String licenseURL
String name
String orientation
String version
String windowState

exit()

This function will cause the application to exit.

Synopsis:

void blackberry.app.exit()

lockOrientation()

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

Synopsis:

void blackberry.app.lockOrientation(orientation)

Parameters:

orientation {String}
The orientation to lock the device to. If the device is currently not in this orientation, the application will rotate then lock. BlackBerry 10 supports the following three orientations:
  • portrait-primary The device is held upright (the LED is located at the top right).
  • landscape-primary The device is rotated to the right (the LED is located at the bottom right).
  • landscape-secondary The device is rotated to the left (the LED is located at the top left).
receiveRotateEvents [Default is true] {Boolean}

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

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.

Synopsis:

void blackberry.app.minimize()

rotate()

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

Synopsis:

void blackberry.app.rotate(orientation)

Parameters:

orientation {String}
The orientation to lock the device to. If the device is currently not in this orientation, the application will rotate then lock. BlackBerry 10 supports the following three orientations:
  • portrait-primary The device is held upright (the LED is located at the top right).
  • landscape-primary The device is rotated to the right (the LED is located at the bottom right).
  • landscape-secondary The device is rotated to the left (the LED is located at the top left).

unlockOrientation()

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

Synopsis:

void blackberry.app.unlockOrientation()

keyboardClosed

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the keyboardClosed event.

Example:

<script type="text/javascript">

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

    document.addEventListener("keyboardClosed", onKeyboardClosed);

</script>

keyboardClosing

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the keyboardClosing event.

Example:

<script type="text/javascript">

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

    document.addEventListener("keyboardClosing", onKeyboardClosing);

</script>

keyboardOpened

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the keyboardOpened event.

Example:

<script type="text/javascript">

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

    document.addEventListener("keyboardOpened", onKeyboardOpened);

</script>
            

keyboardOpening

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the keyboardOpening event.

Example:

<script type="text/javascript">

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

    document.addEventListener("keyboardOpening", onKeyboardOpening);

</script>

keyboardPosition

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the keyboardPosition event.

yPosition {Number}

The absolute position of the virtual keyboard on the y axis of the screen.

Example:

<script type="text/javascript">

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

    document.addEventListener("keyboardPosition", onKeyboardPosition);

</script>

orientationchange

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the orientationchange event. BlackBerry 10 supports the following three orientations:

  • portrait-primary The device is held upright (the LED is located at the top right).
  • landscape-primary The device is rotated to the right (the LED is located at the bottom right).
  • landscape-secondary The device is rotated to the left (the LED is located at the top left).
orientation {String}

The current orientation of the device.

Example:

<script type="text/javascript">

    function onOrientationChange(orientation) {
        console.log("New orientation is: " + orientation);
    }

    document.addEventListener("orientationchange", 
        onOrientationChange);

</script>

pause

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the pause event.

Example:

<script type="text/javascript">

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

    document.addEventListener("pause", onPause);

</script>

resume

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the resume event.

Example:

<script type="text/javascript">

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

    document.addEventListener("resume", onResume);

</script>

swipedown

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

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the swipedown event.

Example:

<script type="text/javascript">

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

    document.addEventListener("swipedown", onSwipedown);

</script>

unhandledkeyinput

This event occurs when key input has not been handled by the web content of the application. Any event listeners for this event will receive a key event object. The key event object contains a keycode of the pressed key, as well as an alternateCharacter value which can be used for application-specific behavior. The event will happen once for the key being pressed, and once for the key being released.

Synopsis:

Event

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the unhandledkeyinput event.

altActive {Boolean}

True if the alt key is active.

ctrlActive {Boolean}

True if the ctrl key is active

shiftActive {Boolean}

True if the shift key is active

keyDown {Boolean}

True if the key is pressed down.

alternateCharacter {Number}

Value shown in the table below.

character {Number}

ASCII code

keycode {Number}

DOM event keycode

English hardware key Action alternateCharacter value
space scroll screen down 61526
shift + space scroll screen up 61525
T scroll top 61520
B scroll bottom 61527
N scroll next 62003
P scroll previous 62002
S search 61998
C create 61984
I zoom in 62010
O zoom out 62011
R reply 62022
U undo 61993
F forward 62023
E edit 61985

Example:

<script type="text/javascript">

    blackberry.event.addEventListener("unhandledkeyinput", 
        function (keyEventObject) {

        // Check for SCROLL TO BOTTOM event
        if (keyEventObject.alternateCharacter === 61527) {
            console.log("SCROLL TO BOTTOM detected");
            // Scroll to bottom of the page
            window.scrollTo(0, document.body.scrollHeight);
        }

        // Check for the letter A
        if (keyEventObject.keycode === 97) {
            console.log("Letter A pressed");
        }
    });

</script>

windowstatechanged

This event is fired by the system. If you want to listen to the event, you can do so using the document.addEventListener function and remove the listener using the document.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.

Synopsis:

void blackberry.app.windowstatechanged()

Parameters:

yourCallbackFunction {Function}

The callback function that will be invoked on the windowstatechanged event.

state {String}

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

Example:

<script type="text/javascript">

    function onWindowStateChange(state) {
        console.log("Window state was changed to: " + state);
    }

    document.addEventListener("windowstatechanged", 
        onWindowStateChange);

</script>

author

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

Synopsis:

read-only
String blackberry.app.author

authorEmail

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

Synopsis:

read-only
String blackberry.app.authorEmail

authorURL

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

Synopsis:

read-only
String blackberry.app.authorURL

copyright

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

Synopsis:

read-only
String blackberry.app.copyright

description

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

Synopsis:

read-only
String blackberry.app.description

id

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

Synopsis:

read-only
String blackberry.app.id

license

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

Synopsis:

read-only
String blackberry.app.license

licenseURL

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

Synopsis:

read-only
String blackberry.app.licenseURL

name

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

Synopsis:

read-only
String blackberry.app.name

orientation

The current orientation of the BlackBerry device.

Synopsis:

read-only
String blackberry.app.orientation

version

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

Synopsis:

read-only
String blackberry.app.version

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 the 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.

Synopsis:

read-only
String blackberry.app.windowState

Last modified: 2014-07-18



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus