An event is any action that can be detected by PhoneGap. It is similar to other JavaScript events. For Example, an onclick event might cause a preview pane to open, an onrollover event on a link might cause a pop-up window to appear. From that point of view, examples of events might be a mouse click, an image loading, rolling over a certain link or other DOM element, selecting an input field on a form, submitting a form, or even typing a certain letter using the keyboard. Some of the events are specific to PhoneGap, which are as follows:
- deviceready
- backbutton
- menubutton
- pause
- resume
- online
- offline
- searchbutton
- batterycritical
- batterylow
- startcallbutton
- endcallbutton
- batterystatus
- volumeupbutton
- volumedownbutton
Among all the events, deviceready is the most important one. Without it, your application won't know if PhoneGap has fully loaded. Once it has fired, you can safely call any PhoneGap function, which, in turn, can safely access the native API.
USING THE EVENTS LISTENER
To use any event, you'll want to use an event listener. For example, to detect the deviceready event, you'll want to do this:
<!DOCTYPE html>
<html>
<head>
<title>PhoneGap Device Ready Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap-1.3.0.js"></script>
<script type="text/javascript" charset="utf-8">
// Call onDeviceReady when PhoneGap is loaded.
//
// At this point, the document has loaded but phonegap-1.3.0.js has not.
// When PhoneGap is loaded and talking with the native device,
// it will call the event `deviceready`.
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is loaded and it is now safe to make calls PhoneGap methods
//
function onDeviceReady() {
// Now safe to use the PhoneGap API
}
</script>
</head>
<body onload="onLoad()">
</body>
</html
In the following code, notice that you are attaching an event listener with document.addEventListener. Typically, when the event listener fires for deviceready, it means that the HTML document's DOM has loaded. You'll have to use a separate listener for each event that you want to detect and respond to. All the other event listeners would be registered inside the onDeviceReady() function.
NOTE: deviceready may be an event but it's not a standard browser event. It only works within a PhoneGap context and if you try to run this event in a normal web browser, it would never fire.
Understanding an Events
1. deviceready
As mentioned, the deviceready event is the most important event you can detect. In terms of priority, you must detect it first, before you do anything else, because, once it fires, you are cleared to call the PhoneGap API. To detect this event, register an event listener as shown here:
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady(){
//ready!
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
2. backbutton
If you require to override the default backbutton behaviour so you can register an event listener for the 'backbutton' event and now you don't have to register to call any other method to override the backbutton behaviour. Now, you only need to register an event listener for the 'backbutton'. To detect this event, register an event listener as shown here:
document.addEventListener("backbutton", onBackButton, false);
function onBackButton(){
//handle the back button
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
3. menubutton
The menubutton event fires when the user presses the Menu button. If you need to override the default menu button behaviour you can register an event listener for the 'menubutton' event.To detect this event, register an event listener as shown here:
document.addEventListener("menubutton", onMenuButton, false);
function onMenuButton(){
//handle the menu button
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
4. pause
The pause event fires when an application is put into the background. An application is considered paused when it leaves the foreground, not when it is shut down. To detect this event, register an event listener as shown here:
document.addEventListener("pause", onPause, false);
function onPause(){
//handle the pause event
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
5. resume
The resume event fires when a paused application is put back into the foreground. To detect this event, register an event listener as shown here:
document.addEventListener("resume", onResume, false);
function onResume(){
//handle the resume event
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
6. online
The online event fires when a PhoneGap application is online (that is, connected to the Internet). This is a new event added with Version 0.9.6. When the application's network connection changes to being online, the online event is fired. To detect this event, register an event listener as shown here:
document.addEventListener("online", isOnline, false);
function isOnline(){
//handle the online event
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
7. offline
The offline event fires when a PhoneGap application is offline (that is, not connected to the Internet). This is a new event added with Version 0.9.6. To detect this event, register an event listener as shown here:
document.addEventListener("offline", isOffline, false);
function isOffline(){
//handle the offline event
}
Supported Platforms:
- Android
- BlackBerry WebWorks (OS 5.0 and higher)
- iOS
8. searchbutton
The searchbutton event fires when the user presses the Search button on an Android device. To detect this event, register an event listener as shown here:
document.addEventListener("searchbutton", onSearchButton, false);
function onSearchButton(){
//handle the search button
}
Supported Platforms:
RESOURCES
Some of the useful resources are
Working With JavaScript, CSS And HTML in PhoneGap
How to Get Device Information Using PhoneGap
Working with Accelerometer in PhoneGap
How to find Longitude & Latitude of Geolocation in PhoneGap