Events

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

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

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

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

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

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

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

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

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>