Map

• Check the availability of the map
• Implement the legal notice

Create a map

First of all, you need to initialize the map after the deviceready event. plugin.google.maps.Map.getMap() is a static method. Since this plugin provides singleton map, if a map has not created, return the map, and if a map has created, return the same map instance. You can not create multiple maps currently.

document.addEventListener("deviceready", function() {
  // Define a div tag with id="map_canvas"
  var mapDiv = document.getElementById("map_canvas");

  // Initialize the map plugin
  var map = plugin.google.maps.Map.getMap(mapDiv);

  map.on(plugin.google.maps.event.MAP_READY, onMapInit);
});

function onMapInit(map) {
}

Related pages

• Create a map with initialize options
• Check the availability of the map
• Show a map with full screen

---

###How does the plugin work? As of version 1.2.0, you can put any HTMLs on the map. You need to understand how this works.

The map is native view, not JavaScript. It means the map and the browser are different view, the map is not rendered on the browser view, such as HTML.

In order to put HTML contents on the map, the map places under the browser view. And HTML background color must be transparent (The plugin changes automatically).

If you want to change the background color of your app, use map.setBackgroundColor()

---

###Put HTML elements on the map You can put any HTMLs on the map, such as button and input field. The html elements under the map_canvas div, the plugin watches their position.

<div id="map_canvas">
  <div id="searchBox">
    <input type="text" id="query" size="30" />
    <button id="searchBtn">Search</button>
  </div>
</div>

Example:

---

###map.setDebuggable() map.setDebuggable( true ) allows you to confirm where is the clickable regions visually.

---

###map.setClickable() If you want to show your HTML above the map, such as sidebar, you need to use map.setClickable( false ) before showing it.

Because the plugin watches ONLY under the map_canvas div, not others. That's why you need to call map.setClickable( false ) to be clickable the HTML (sidebar), then call map.setClickable( true ) after closing.

###Listen events You can listen several events, such as map clicked. Available events for Map class are the below:

• MAP_CLICK
• MAP_LONG_CLICK
• MY_LOCATION_BUTTON_CLICK
• CAMERA_CHANGE
• CAMERA_IDLE(iOS)
• MAP_READY
• MAP_LOADED(Android)
• MAP_WILL_MOVE(iOS)
• MAP_CLOSE

example1

var evtName = plugin.google.maps.event.MAP_LONG_CLICK;
map.on(evtName, function(latLng) {
  alert("Map was long clicked.\n" +
        latLng.toUrlValue());
});

example2

document.addEventListener("deviceready", function()  {
  var div = document.getElementById("map_canvas");
  var map = plugin.google.maps.Map.getMap(div);

  map.on(plugin.google.maps.event.CAMERA_CHANGE, onMapCameraChanged);
}
function onMapCameraChanged(position) {
  var map = this;
  console.log(JSON.stringify(position));
}

---

###Change the map type You can choose the map type using setMapTypeId() method. Available map types are ROADMAP, SATELLITE, HYBRID, TERRAIN and NONE.

map.setMapTypeId(plugin.google.maps.MapTypeId.HYBRID);

---

###Move the camera Google Maps for mobile has a view camera. You see the map via the camera, thus if you want to show a specific location, you need to move the camera. To do that, this plugin provides animateCamera() and moveCamera() methods. The animateCamera() moves the camera with animation, while the other hand without animation. Default animation time of animateCamera() method is 5 seconds.

map.animateCamera({
  'target': GOOGLE,
  'tilt': 60,
  'zoom': 18,
  'bearing': 140
});

Both methods take a callback function as the second argument. This callback is involved when the movement is finished.

map.moveCamera({
  'target': STATUE_OF_LIBERTY,
  'zoom': 17,
  'tilt': 30
}, function() {
  var mapType = plugin.google.maps.MapTypeId.HYBRID;
  map.setMapTypeId(mapType);
  map.showDialog();
});

---

###Move the camera within the specified duration time The animateCamera() acepts the duration time for animating with duration option. If you want to animate slowly, you can specify the duration in millisecond.

map.animateCamera({
  'target': GOOGLE,
  'tilt': 60,
  'zoom': 18,
  'bearing': 140,
  'duration': 10000
});

---

###Get the camera position If you want to know the camera position, just call getCameraPosition() method.

map.getCameraPosition(function(camera) {
  var buff = ["Current camera position:\n",
      "latitude:" + camera.target.lat,
      "longitude:" + camera.target.lng,
      "zoom:" + camera.zoom,
      "tilt:" + camera.tilt,
      "bearing:" + camera.bearing].join("\n");
  alert(buff);
});

---

###Get my location If you want to know where you are, just call getMyLocation() method.

var onSuccess = function(location) {
  var msg = ["Current your location:\n",
    "latitude:" + location.latLng.lat,
    "longitude:" + location.latLng.lng,
    "speed:" + location.speed,
    "time:" + location.time,
    "bearing:" + location.bearing].join("\n");
  
  map.addMarker({
    'position': location.latLng,
    'title': msg
  }, function(marker) {
    marker.showInfoWindow();
  });
};

var onError = function(msg) {
  alert("error: " + msg);
};
map.getMyLocation(onSuccess, onError);

---

###Get the visible region If you want to know the coordinates of the corners (Left/Top and Right/Bottom), call the map.getVisibleRegion().

map.getVisibleRegion(function(latLngBounds) {
  alert(latLngBounds.northeast.toUrlValue() + ", " + latLngBounds.southwest.toUrlValue()); 
});

Related pages:

• LatLngBounds.contains() : Detects the given coordinates are in the bounds or not.

---

#Map Class Reference

Method	Return value	Description
getMap()	Map	Return the instance of a Map class. Plugin does not make multiple maps.
isAvailable(Function)	Map	Check the availability of Google Maps Android API v2
showDialog()	void	Open the map dialog.
closeDialog()	void	Hide the map dialog.
getLicenseInfo(Function)	void	Return the license text of the Google Maps SDK.
setCenter(LatLng)	void	Set the center position of the camera view.
setZoom(Number)	void	Set the camera zoom.
setMapTypeId(String)	void	Change the map type.
setTilt(Number)	void	Change the angle of the camera view.
animateCamera(CameraPosition)	void	Change the camera position with animation.
moveCamera(CameraPosition)	void	Change the camera position without animation.
setMyLocationEnabled(Boolean)	void	Set true if you want to show the MyLocation button.
setIndoorEnabled(Boolean)	void	Set true if you want to show the indoor map.
setTrafficEnabled(Boolean)	void	Set true if you want to show the traffic layer.
setCompassEnabled(Boolean)	void	Set true if you want to show the compass button.
setAllGesturesEnabled(Boolean)	void	Sets the preference for whether all gestures should be enabled or disabled.
getMyLocation(Function, Function)	void	The callback function will be involved with current your location as Location data.
getCameraPosition(Function)	void	The callback function will be involved with current camera position as CameraPosition data.
addMarker(options)	Marker	Add a marker on the map. See Marker class
addCircle(options)	Circle	Add a circle on the map. See Circle class.
addPolygon(options)	Polygon	Add a polygon on the map. See Polygon class.
addPolyline(options)	Polyline	Add a polyline on the map. See Polyline class.
addTileOverlay(options)	TileOverlay	Add a tile overlay on the map. See TileOverlay class.
addGroundOverlay(options)	GroundOverlay	Add a ground overlay on the map. See GroundOverlay class.
setDiv(DOM node)	void	Embed a map into the specified DOM node.
setVisible(boolean)	void	If set false, the map is hidden.
setOptions(options)	void	Set the attributions of the map
setBackgroundColor(String)	void	Set the attributions of the map
clear()	void	Remove all mark-ups, such as marker.
refreshLayout()	void	Force recalculate the map view location when the map is embedded.
fromLatLngToPoint(LatLng)	[x, y]	Converts latitude, longitude to pixels from left-top.
fromPointToLatLng([x,y])	LatLng	Converts pixels from left-top to latitude, longitude.
toDataURL(Function)	void	Generate the map screen capture image as base64 encoded data, like HTML5's Canvas.
getVisibleRegion(Function)	void	Get the latitude and longitude coordinates of the corner of the map as LatLngBounds.
remove()	void	Destroy the map completely.