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.| 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
- Ripple Emulator
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| onBackground | Y | Y | Y | Y | Y |
| onExit | Y | Y | Y | Y | |
| onForeground | Y | Y | Y | Y | Y |
| onSwipeDown | Y | Y | |||
| onSwipeStart | 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.event" /> | 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. |
onBackground
| static void onBackground(onBackgroundCallback : function) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
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.| Parameter | Type | Description |
|---|---|---|
| onBackgroundCallback | function() | Function to be called when the application goes to the background. Expected signature: function onBackgroundCallback(). |
Code Example(s)
<script type="text/javascript">
function onBackgroundCallback() {
alert("Going to the background!");
}
function notifyMeWhenMinimized() {
blackberry.app.event.onBackground(onBackgroundCallback);
}
notifyMeWhenMinimized();
</script>
onExit
| static void onExit(onExitCallback : function) |
Supported Platform(s)
- BlackBerry OS 5.0+- Ripple Emulator
Description
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.| Parameter | Type | Description |
|---|---|---|
| onExitCallback | function() | Function to be called when the application is about to exit. Expected signature: function onExitCallback(). |
onForeground
| static void onForeground(onForegroundCallback : function) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
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 onBackground documentation for details.| Parameter | Type | Description |
|---|---|---|
| onForegroundCallback | function() | Function to be called when the application goes to the foreground. Expected signature: function onForegroundCallback(). |
onSwipeDown
| static void onSwipeDown(onSwipeDownCallback : function) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
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.| Parameter | Type | Description |
|---|---|---|
| onSwipeDownCallback | function() | Function to be called when the swipe down action occurs. Expected signature: function onSwipeDownCallback(). |
onSwipeStart
| static void onSwipeStart(onSwipeStartCallback : function) |
Supported Platform(s)
- BlackBerry PlayBook- Ripple Emulator
Description
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.| Parameter | Type | Description |
|---|---|---|
| onSwipeStartCallback | function() | 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 Sun Dec 30 2012 13:31:17 GMT-0500 (EST)