Application Event

The Application Event object allows you to access events triggered by the application

The Application Event Object is static; all of its functions and properties are used directly from the object.


Learning Resources:

Sample - Swipe Down Menu Sample that demonstrates how to add a swipe-down menu to your PlayBook application using the onSwipeDown function [BlackBerry Developer Resource Center].

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.app.event.onBackground Y Y Y Y Y  Y
blackberry.app.event.onExit Y Y Y      Y
blackberry.app.event.onForeground Y Y Y Y Y  Y
blackberry.app.event.onSwipeDown       Y Y  Y
blackberry.app.event.onSwipeStart       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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.app.event" /> Y Y Y Y Y  Y

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.

Functions

static void blackberry.app.event.onBackground (onBackgroundCallback: function())

BB10 API Changes

This function has been migrated to blackberry.app.pause in BlackBerry 10.


Assigns a listener that is called when the application goes to the background.

This event is dispatched whenever the application goes to the background, but has not ended. Only one function can be assigned to this event. To unregister the callback, call the onBackground method and pass in null for the callback parameter.

Note: The BlackBerry PlayBook's "Application Behavior" setting has an impact on when onBackground gets dispatched. When "Application Behavior" is set to "Default", onBackground does not get dispatched until another application goes fullscreen. When "Application Behavior" is set to "Showcase", onBackground does not get dispatched because all open applications stay active. When "Application Behavior" is set to "Paused", onBackground gets dispatched once the application is sent to the background.


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


Parameters
onBackgroundCallback Function to be called when the application goes to the background. Expected signature: function onBackgroundCallback().

Code Example:
<script type="text/javascript">
function onBackgroundCallback() {
	alert("Going to the background!");
}

function notifyMeWhenMinimized() {
	blackberry.app.event.onBackground(onBackgroundCallback);
}

notifyMeWhenMinimized();
</script>

static void blackberry.app.event.onExit (onExitCallback: function())


Assigns a listener for when the application is about to exit.

Only one function can be assigned to this event. To unregister the callback, simply call the onExit method and pass in null for the callback parameter. This event will be fired when the application is about to exit. When you trap for the onExit event you must control the exit of the application in your JavaScript. If you choose to allow the application to exit, you must call blackberry.app.exit() to terminate the application.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
onExitCallback Function to be called when the application is about to exit. Expected signature: function onExitCallback().

static void blackberry.app.event.onForeground (onForegroundCallback: function())

BB10 API Changes

This function has been migrated to blackberry.app.resume in BlackBerry 10.


Assigns a listener that is called when the application goes to the foreground.

This event is dispatched whenever the application comes to the foreground, for example, when the user re-opens the application from the application list. Only one function can be assigned to this event. To unregister the callback call the onForeground method and pass in null for the callback parameter.

Note: The BlackBerry PlayBook's "Application Behavior" setting has an impact on when onForeground gets dispatched. Refer to blackberry.app.event.onBackground documentation for details.


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


Parameters
onForegroundCallback Function to be called when the application goes to the foreground. Expected signature: function onForegroundCallback().

static void blackberry.app.event.onSwipeDown (onSwipeDownCallback: function())


Assigns a listener that is called when a user swipes down from the top bezel of the BlackBerry PlayBook onto the screen.

This event is dispatched when a user swipes down from the top bezel of the BlackBerry PlayBook onto the screen. Only one function can be assigned to this event. To unregister the callback call the onSwipeDown method and pass in null for the callback parameter.


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
onSwipeDownCallback Function to be called when the swipe down action occurs. Expected signature: function onSwipeDownCallback().

static void blackberry.app.event.onSwipeStart (onSwipeStartCallback: function())


Assigns a listener for when when a user begins to swipe from the top bezel of the BlackBerry PlayBook into the screen.

This event is dispatched when the user starts a swipe from the top bezel of the BlackBerry PlayBook. Only one function can be assigned to this event. To unregister the callback call the onSwipeStart method and pass in null for the callback parameter.


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
onSwipeStartCallback Function to be called when the user starts a swipe from the top bezel of the PlayBook. Expected signature: function onSwipeStartCallback(). Static="true" returns="void".
Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:06 GMT-0500 (EST)