Events
Eventos PhoneGap.
Tipos de Eventos
deviceready
Este evento se dispara cuando PhoneGap esta completamente listo.
document.addEventListener("deviceready", yourCallbackFunction, false);
Detalles
Este evento es muy importante y todas las aplicaciones deben usarlo.
PhoneGap consiste en dos partes de código, la parte nativa y la JavaScript. Mientras el código nativo esta cargando, se muestra una imagen personalizada. En cambio, JavaScript solo se inicia cuando el DOM carga. Por tanto si no usamos este evento su aplicación podría, potencialmente, llamar a funciones PhoneGap antes de que PhoneGap este listo para usarse.
El evento deviceready
se dispara una vez PhoneGap este totalmente iniciado. Después de este evento, ya puedes hacer llamadas a las funciones de PhoneGap de una forma segura.
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que el árbol DOM se halla cargado.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
// Ahora es seguro utilizar la API PhoneGap
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie.
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
// Ahora es seguro usar la API PhoneGap
}
</script>
</head>
<body>
</body>
</html>
Peculiaridades BlackBerry (OS 4.6)
Los Eventos personalizados no estan soportados por el componente "RIM BrowserField" (el webviewer del sistema RIM), por lo que el evento deviceready
nunca sera disparado.
Un aproximación similar seria consultar manualmente la variable PhoneGap.available
hasta que PhoneGap indique que fue totalmente iniciado.
function onLoad() {
// El navegador de BlackBerry OS 4 no soporta eventos,
// entonces esperaremos hasta que PhoneGap este disponible.
//
var intervalID = window.setInterval(
function() {
if (PhoneGap.available) {
window.clearInterval(intervalID);
onDeviceReady();
}
},
500
);
}
function onDeviceReady() {
// Ahora es seguro usar la API PhoneGap
}
pause
Este evento se dispara cuando la aplicación PhoneGap pierde el foco y pasa a segundo plano.
document.addEventListener("pause", yourCallbackFunction, false);
Detalles
PhoneGap consiste en dos partes de código, la parte nativa y la JavaScript. Cuando la parte nativa manda la aplicación a segundo plano, PhoneGap disparara el evento pause.
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que PhoneGap dispare 'deviceready'.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
document.addEventListener("pause", onPause, false);
function onPause() {
// Maneja el evento 'pause'
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
document.addEventListener("pause", onPause, false);
}
// Maneja el evento online
//
function onPause() {
}
</script>
</head>
<body>
</body>
</html>
Peculiaridades iOS
En el manejador de pausa, cualquier función que pase sobre Objetive-C no funcionara, tampoco ninguna función interactiva como las alertas. Esto quiere decir que no puedes llamar a console.log (o sus variantes), ni ninguna función de los plugins o de la API PhoneGap. Todas las llamadas de este tipo que realices, serán ejecutadas cuando la aplicación se reanude, en el siguiente ciclo del bucle de ejecución).
resume
Este evento se dispara cuando la aplicación PhoneGap recupera el foco y se lanza a primer plano.
document.addEventListener("resume", yourCallbackFunction, false);
Detalles
PhoneGap consiste en dos partes de código, la parte nativa y la JavaScript. Cuando la parte nativa recupera la aplicación del segundo plano, PhoneGap disparara el evento
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que PhoneGap dispare 'deviceready'.
Plataformas Soportada
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
document.addEventListener("resume", onResume, false);
function onResume() {
// maneja el evento 'resume'
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
document.addEventListener("resume", onResume, false);
}
// maneja el evento 'resume'
//
function onResume() {
}
</script>
</head>
<body>
</body>
</html>
online
Este evento se dispara cuando una aplicación PhoneGap se encuentra online (con conexión a internet).
document.addEventListener("online", yourCallbackFunction, false);
Detalles
Cuando la conectividad de la aplicación establece conexión, el evento online se disparara.
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que PhoneGap dispare 'deviceready'.
Plataformas Soportadas
- iOS
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
Ejemplo Rápido
document.addEventListener("online", onOnline, false);
function onOnline() {
// Maneja el evento 'online'
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
document.addEventListener("online", onOnline, false);
}
// Maneja el evento online
//
function onOnline() {
}
</script>
</head>
<body>
</body>
</html>
Peculiaridades iOS
Durante el primer arranque, el primer evento online (Si lo hubiera) podría tardar al menos un segundo en dispararse.
offline
Este evento se dispara cuando una aplicación PhoneGap se encuentra offline (sin conexión a internet).
document.addEventListener("offline", yourCallbackFunction, false);
Detalles
Cuando la conectividad de la aplicación se quede sin conexión, el evento offline se disparara.
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que PhoneGap dispare 'deviceready'.
Plataformas Soportadas
- iOS
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
Ejemplo Rápido
document.addEventListener("offline", onOffline, false);
function onOffline() {
// Manejar el evento 'offline'
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
document.addEventListener("offline", onOffline, false);
}
// Maneja el evento offline
//
function onOffline() {
}
</script>
</head>
<body>
</body>
</html>
Peculiaridades iOS
Durante el primer arranque, el primer evento offline (Si lo hubiera) podría tardar al menos un segundo en dispararse.
backbutton
Este evento se dispara cuando el usuario presiona el botón "Atrás" en Android.
document.addEventListener("backbutton", yourCallbackFunction, false);
Detalles
Si necesitas cambiar la funcionalidad del botón "Atrás" en Android, puedes registrar una función para el evento 'backbutton'. Ya no es necesario llamar a otros métodos para sobre escribir el evento "backbutton", solo necesitas registrar un función 'callback' para este evento.
En la mayoría de los casos solo necesitaras enlazar una función al evento con document.addEventListener
justo después de que PhoneGap dispare 'deviceready'.
Plataformas Soportadas
- Android
Ejemplo Rápido
document.addEventListener("backbutton", onBackKeyDown, false);
function onBackKeyDown() {
// Maneja el evento del botón atrás
}
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie.
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap este listo y se comunique con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
// Añade una función 'callback' al evento 'backbutton'
document.addEventListener("backbutton", onBackKeyDown, false);
}
// Maneja el evento del botón "Atrás"
//
function onBackKeyDown() {
}
</script>
</head>
<body>
</body>
</html>
menubutton
Este evento se disparara cuando el usuario presione el botón Menú en Android.
document.addEventListener("menubutton", yourCallbackFunction, false);
Detalles
Si necesitas sobreescribir la funcionalidad del botón 'Menú', puedes añadir una función al evento 'menubutton'.
En la mayoría de los casos lo que querrás sera añadir una función al evento con document.addEventListener
justo después de que PhoneGap dispara deviceready
Plataformas Soportadas
- Android
Ejemplo Rápido
document.addEventListener("menubutton", onMenuKeyDown, false);
function onMenuKeyDown() {
// Maneja el evento del botón menú
}
Ejemplo Completo
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap esta listo y se comunica con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
// Añade una función 'callback' al evento 'menubutton'
document.addEventListener("menubutton", onMenuKeyDown, false);
}
// Maneja el evento del botón "Menú"
//
function onMenuKeyDown() {
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>
searchbutton
Este evento se dispara cuando el usuario presiona el botón de búsqueda en Android.
document.addEventListener("searchbutton", yourCallbackFunction, false);
Detalles
Si necesitas cambiar la funcionalidad del botón "Búsqueda" en Android, puedes registrar una función para el evento 'searchbutton'. Ya no es necesario llamar a otros métodos para sobreescribir el evento "searchbutton", solo necesitas registrar un función 'callback' para este evento.
En la mayoría de los casos lo que querrás sera añadir una función al evento con document.addEventListener
justo después de que PhoneGap dispara deviceready
Plataformas Soportadas
- Android
Ejemplo Rápido
document.addEventListener("searchbutton", onSearchKeyDown, false);
function onSearchKeyDown() {
// Maneja el evento del botón search
}
Ejemplo Completo
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Ejemplo de Events</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Llama a onDeviceReady cuando PhoneGap se inicie
//
// En este momento, el documento esta cargado pero phonegap.js aun no.
// Cuando PhoneGap esta listo y se comunica con el dispositivo nativo
// se lanzara el evento `deviceready`.
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap esta listo y ahora ya se pueden hacer llamadas a PhoneGap
//
function onDeviceReady() {
// Registra una función 'callback' al evento.
document.addEventListener("searchbutton", onSearchKeyDown, false);
}
// Maneja el evento del botón search
//
function onSearchKeyDown() {
}
</script>
</head>
<body onload="onLoad()">
</body>
</html>