Eventos

La librería de PhoneGap incluye una serie de eventos JavaScript a los cuales podemos escuchar para realizar determinadas acciones cuando se produzcan. Estos eventos son:

  • deviceready

  • pause

  • resume

  • backbutton

  • menubutton

  • searchbutton

  • startcallbutton

  • endcallbutton

  • volumedownbutton

  • volumeupbutton

Si instalamos el plugin para el control de la batería (org.apache.cordova.battery-status) se añadirán los siguientes eventos (ver sección de plugins):

  • batterycritical

  • batterylow

  • batterystatus

Si instalamos el plugin para obtener información de la red (org.apache.cordova.network-information) se añadirán los siguientes eventos (ver sección de plugins):

  • online

  • offline

En general para suscribirnos a un evento utilizaremos el siguiente código:

document.addEventListener("nombre-evento", funcionCallback, false);

Donde:

  • nombre-evento: es el evento al que queremos escuchar.

  • funcionCallback: es la función que se llamará cuando el evento se produzca.

  • false: afecta al orden en el que se lanzará el evento, al inicio (cuando se producte) o al final (cuando ya ha terminado).

A continuación se describen los principales eventos de PhoneGap y se incluyen ejemplos de uso.

deviceready

Este evento se ejecuta cuando la librería de PhoneGap se ha cargado completamente. Su uso es esencial para cualquier aplicación y lo tendremos que utilizar de forma inicial para asegurarnos de que la API se ha cargado completamente.

A continuación se incluye un ejemplo de uso:

<!DOCTYPE html>
<html>
<head>
<title>Ejemplo</title>
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
// Esperamos a que se cargue la API de PhoneGap
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// La API de PhoneGap ya está disponible
function onDeviceReady() {
// Ya podemos usar la librería de PhoneGap
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>

pause

Este evento se produce cuando la aplicación pasa a segundo plano. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
<head>
<title>Pause Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// Añadimos el evento cuando la API esté lista
function onDeviceReady() {
document.addEventListener("pause", onPause, false);
}
// Se ha producido el evento pause!
function onPause() {
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>

En todos los eventos tendremos que esperar a que la API de PhoneGap termine de cargar.

resume

Este evento se produce cuando la aplicación estaba en segundo plano y se vuelve a mostrar en primer plano. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
<head>
<title>Resume Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// Añadimos el evento cuando la API esté lista
function onDeviceReady() {
document.addEventListener("resume", onResume, false);
}
// Se ha producido el evento "resume"!
function onResume() {
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>

backbutton

Este evento se produce cuando el usuario pulsa el botón atrás. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
<head>
<title>Back Button Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// Añadimos el evento cuando la API esté lista
function onDeviceReady() {
document.addEventListener("backbutton", onBackKeyDown, false);
}
// Se ha producido el evento "backbutton"!
function onBackKeyDown() {
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>

Salir de la aplicación

Por defecto, al pulsar el botón back no se cerrará la aplicación. Si queremos que se cierre tendremos que hacer:

document.addEventListener("backbutton", onBackKeyDown, false);
function onBackKeyDown() {
navigator.app.exitApp()
}

Hemos de tener cuidado con esta funcionalidad porque cerrará la aplicación siempre que se pulse dicha tecla. Si nuestra aplicación tiene varias páginas y queremos que se use el botón back para volver a la página anterior y además que en la primera página cierre la aplicación tendremos que distinguir entre las páginas y solo cerrar en la primera.

menubutton

Este evento se produce cuando el usuario pulsa el botón menú. Para su utilización, igual que en el resto de casos, simplemente tendremos que hacer (ejemplo abreviado):

document.addEventListener("menubutton", onMenuKeyDown, false);
function onMenuKeyDown() {
// Se ha producido el evento "menubutton"!
}

volumedownbutton

Este evento se produce cuando el usuario pulsa el botón para bajar el volumen. A continuación se incluye un ejemplo abreviado de uso:

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);
function onVolumeDownKeyDown() {
// Se ha producido el evento "volumedownbutton"!
}

volumeupbutton

Este evento se lanza cuando se pulsa el botón para subir el volumen. Igual que en el resto de casos, para su utilización tenemos que hacer:

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
function onVolumeUpKeyDown() {
// Se ha producido el evento "volumeupbutton"!
}