Events

Certify and Increase Opportunity.
Be
Govt. Certified Blackberry Apps Developer

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

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	BB5.0	BB6.0	BB7.0	PB1.0	PB2.0	BB10	Ripple
<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

void	blackberry.app.event.onBackground
void	blackberry.app.event.onExit
void	blackberry.app.event.onForeground
void	blackberry.app.event.onSwipeDown
void	blackberry.app.event.onSwipeStart

Functions

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

BB10 API ChangesThis 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 ChangesThis 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”.