Mapas en Android (Google Maps Android API v2) – III

En los dos artículos anteriores (I y II) del curso hemos visto cómo crear aplicaciones utilizando la nueva versión de la API v2 de Google Maps para Android y hemos descrito las acciones principales sobre el mapa.

En este último artículo de la serie nos vamos a centrar en los eventos del mapa que podemos capturar y tratar, en la creación y gestión de marcadores, y en el dibujo de lineas y polígonos sobre el mapa.

Sin más preámbulos, comencemos con los eventos. Si hacemos un poco de memoria, con la versión anterior de la API debíamos crear una nueva capa (overlay) para capturar los eventos principales de pulsación. Sin embargo, el nuevo componente de mapas soporta directamente los eventos de click, click largo y movimiento de cámara y podemos implementarlos de la forma habitual, mediante su método set correspondiente.

Así por ejemplo, podríamos implementar el evento de onclick llamando al método setOnMapClickListener() con un nuevo listener y sobrescribir el método onMapClick(). Este método recibe como parámetro, en forma de objeto LatLng, las coordenadas de latitud y longitud sobre las que ha pulsado el usuario. Si quisiéramos traducir estas coordenadas física en coordenadas en pantalla podríamos utilizar un objeto Projection (similar al que ya comentamos para la API v1), obteniéndolo a partir del mapa a través del método getProjection() y posteriormente llamando a toScreenLocation() para obtener las coordenadas (x,y) de pantalla donde el usuario pulsó.

Así, por ejemplo, si quisiéramos mostrar un Toast con todos estos datos cada vez que se pulse sobre el mapa podríamos hacer lo siguiente:

mapa.setOnMapClickListener(new OnMapClickListener() {
	public void onMapClick(LatLng point) {
		Projection proj = mapa.getProjection();
		Point coord = proj.toScreenLocation(point);

		Toast.makeText(
			MainActivity.this,
			"Click\n" +
			"Lat: " + point.latitude + "\n" +
			"Lng: " + point.longitude + "\n" +
			"X: " + coord.x + " - Y: " + coord.y,
			Toast.LENGTH_SHORT).show();
	}
});

De forma similar podríamos implementar el evento de pulsación larga, con la única diferencia de que lo asignaríamos mediante setOnMapLongClickListener() y sobrescribiríamos el método onMapLongClick().

mapa.setOnMapLongClickListener(new OnMapLongClickListener() {
	public void onMapLongClick(LatLng point) {
		Projection proj = mapa.getProjection();
		Point coord = proj.toScreenLocation(point);

		Toast.makeText(
			MainActivity.this,
			"Click Largo\n" +
			"Lat: " + point.latitude + "\n" +
			"Lng: " + point.longitude + "\n" +
			"X: " + coord.x + " - Y: " + coord.y,
			Toast.LENGTH_SHORT).show();
	}
});

Así, cuando el usuario hiciera una pulsación larga sobre el mapa veríamos los datos en pantalla de la siguiente forma:

También podremos capturar el evento de cambio de cámara, de forma que podamos realizar determinadas acciones cada vez que el usuario se mueve manualmente por el mapa, desplazándolo, haciendo zoom, o modificando la orientación o el ángulo de visión. Este evento lo asignaremos al mapa mediante su método setOnCameraChangeListener() y sobrescribiendo el método onCameraChange(). Este método recibe como parámetro un objeto CameraPosition, que ya vimos en el artículo anterior, por lo que podremos recuperar de él todos los datos de la cámara en cualquier momento.

De esta forma, si quisiéramos mostrar un Toast con todos los datos podríamos hacer lo siguiente:

mapa.setOnCameraChangeListener(new OnCameraChangeListener() {
	public void onCameraChange(CameraPosition position) {
		Toast.makeText(
			MainActivity.this,
			"Cambio Cámara\n" +
			"Lat: " + position.target.latitude + "\n" +
			"Lng: " + position.target.longitude + "\n" +
			"Zoom: " + position.zoom + "\n" +
			"Orientación: " + position.bearing + "\n" +
			"Ángulo: " + position.tilt,
			Toast.LENGTH_SHORT).show();
	}
});

Hecho esto, cada vez que el usuario se mueva por el mapa veríamos lo siguiente:

El siguiente tema importante que quería tratar en este artículo es el de los marcadores. Rara es la aplicación Android que hace uso de mapas sin utilizar también este tipo de elementos para resaltar determinados puntos en el mapa. Si recordamos el artículo sobre la API v1, vimos cómo podíamos añadir marcadores añadiendo una nueva capa (overlay) al mapa y dibujando nuestro marcador como parte de su evento draw(). En la nueva versión de la API tendemos toda esta funcionalidad integrada en la propia vista de mapa, y agregar un marcador resulta tan sencillo como llamar al método addMarker() pasándole la posición en forma de objeto LatLng y el texto a mostrar en la ventana de información del marcador. En nuestra aplicación de ejemplo añadiremos un menú de forma que cuando lo pulsemos se añada automáticamente un marcador sobre España con el texto “Pais: España“. Veamos cómo escribir un método auxiliar que nos ayuda a hacer esto pasándole las coordenadas de latitud y longitud:

private void mostrarMarcador(double lat, double lng)
{
    mapa.addMarker(new MarkerOptions()
        .position(new LatLng(lat, lng))
        .title("Pais: España"));
}

Así de sencillo, basta con llamar al método addMarker() pasando como parámetro un nuevo objeto MarkerOptions sobre el que establecemos la posición del marcador (método position()) y el texto a incluir en la ventana de información del marcador (métodos title() para el título y snippet() para el resto del texto). Si ejecutamos la aplicación de ejemplo y pulsamos el menú “Marcadores” aparecerá el siguiente marcador sobre el mapa (la ventana de información aparece si además se pulsa sobre el marcador):

Además de facilitarnos la vida con la inclusión de marcadores en el mapa también tendremos ayuda a la hora de capturar el evento de pulsación sobre un marcador, ya que podremos asignar al mapa dicho evento como cualquiera de los comentados anteriormente. En este caso el evento se asignará al mapa mediante el método setOnMarkerClickListener() y sobrescribiremos el método onMarkerClick(). Dicho método recibe como parámetro el objeto Marker pulsado, de forma que podamos identificarlo accediendo a su información (posición, título, texto, …). Veamos un ejemplo donde mostramos un toast con el título del marcador pulsado:

mapa.setOnMarkerClickListener(new OnMarkerClickListener() {
	public boolean onMarkerClick(Marker marker) {
		Toast.makeText(
			MainActivity.this,
			"Marcador pulsado:\n" +
			marker.getTitle(),
			Toast.LENGTH_SHORT).show();

		return false;
	}
});

Con el código anterior, si pulsamos sobre el marcador de España aparecerá el siguiente mensaje informativo:

Todo lo explicado sobre marcadores corresponde al comportamiento por defecto de la API, sin embargo también es posible por supuesto personalizar determinadas cosas, como por ejemplo el aspecto de los marcadores. Esto se sale un poco de este artículo, donde pretendía describir los temas más básicos, pero para quien esté interesado tan sólo decir que mediante los métodos icon() y anchor() del objeto MakerOptions que hemos visto antes es posible utilizar una imagen personalizada para mostrar como marcador en el mapa. En la documentación oficial (en inglés) podéis encontrar un ejemplo de cómo hacer esto.

Como último tema, vamos a ver cómo dibujar líneas y polígonos sobre el mapa, elementos muy comunmente utilizados para trazar rutas o delimitar zonas del mapa. Para realizar esto en la versión 2 de la API vamos a actuar una vez más directamente sobre la vista de mapa, sin necesidad de añadir overlays o similares, y ayudándonos de los objetos PolylineOptions y PolygonOptions respectivamente.

Para dibujar una linea lo primero que tendremos que hacer será crear un nuevo objeto PolylineOptions sobre el que añadiremos utilizando su método add() las coordenadas (latitud-longitud) de todos los puntos que conformen la linea. Tras esto estableceremos el grosor y color de la linea llamando a los métodos width() y color() respectivamente, y por último añadiremos la linea al mapa mediante su método addPolyline() pasándole el objeto PolylineOptions recién creado.

En nuestra aplicación de ejemplo he añadido un nuevo menú para dibujar un rectángulo sobre España. Veamos cómo queda:

private void mostrarLineas()
{
	//Dibujo con Lineas

	PolylineOptions lineas = new PolylineOptions()
	        .add(new LatLng(45.0, -12.0))
	        .add(new LatLng(45.0, 5.0))
	        .add(new LatLng(34.5, 5.0))
	        .add(new LatLng(34.5, -12.0))
	        .add(new LatLng(45.0, -12.0));

	lineas.width(8);
	lineas.color(Color.RED);

	mapa.addPolyline(lineas);
}

Ejecutando esta acción en el emulador veríamos lo siguiente:

Pues bien, esto mismo podríamos haberlo logrado mediante el dibujo de polígonos, cuyo funcionamiento es muy similar. Para ello crearíamos un nuevo objeto PolygonOptions y añadiremos las coordenadas de sus puntos en el sentido de las agujas del reloj. En este caso no es necesario cerrar el circuito (es decir, que la primera coordenada y la última fueran iguales) ya que se hace de forma automática. Otra diferencia es que para polígonos el ancho y color de la linea los estableceríamos mediante los métodos strokeWidth() y strokeColor(). Además, el dibujo final del polígono sobre el mapa lo haríamos mediante addPolygon(). En nuestro caso quedaría como sigue:

//Dibujo con polígonos

PolygonOptions rectangulo = new PolygonOptions()
              .add(new LatLng(45.0, -12.0),
            	   new LatLng(45.0, 5.0),
            	   new LatLng(34.5, 5.0),
            	   new LatLng(34.5, -12.0),
            	   new LatLng(45.0, -12.0));

rectangulo.strokeWidth(8);
rectangulo.strokeColor(Color.RED);

mapa.addPolygon(rectangulo);

El resultado al ejecutar la acción en el emulador debería ser exactamente igual que el anterior.

Puedes consultar y/o descargar el código completo de los ejemplos desarrollados en este artículo accediendo a la pagina del curso en GitHub.

Y con esto habríamos concluido la serie de tres artículos destinados a describir el funcionamiento básico de la nueva API v2 de Google Maps para Android. Espero haber aclarado las dudas principales a la hora de comenzar a utilizar la nueva API. Tampoco descarto algún artículo adicional para comentar temas algo más avanzados sobre esta API, pero eso será más adelante.