Skip to content

Latest commit

 

History

History
451 lines (376 loc) · 14.4 KB

README.md

File metadata and controls

451 lines (376 loc) · 14.4 KB
Raw

⚠️ This document is aim for older versions (from 2.3.0 to 2.5.3). Document for new version is https://github.com/mapsplugin/cordova-plugin-googlemaps-doc/blob/master/v2.6.0/README.md

Map class

This class extends BaseClass.

Contents

Overview

Create a map

You can create a google maps (map instance) using plugin.google.maps.Map.getMap() after the deviceready event.

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);

  // The MAP_READY event notifies the native map view is fully ready to use.
  map.one(plugin.google.maps.event.MAP_READY, onMapInit);
});

function onMapInit(map) {

}

How does the plugin work?

Before using this plugin, please understand how this plugin work.

  • App background becomes transparent

    This plugin embeds native Google Maps view under the browser view. Because of this, this plugin changes the application background as transparent. If you want to set the background color, you need to use Environment.setBackgroundColor().

  • Map is not HTML element!

    The Google Maps generated by this plugin is not HTML element. You CAN NOT do like this:

    map.appendChild(button);

  • Positioning is delay a little

    Positioning is one of the difficult task. Since the map is not in the browser, the plugin follows the map div position and size when you manipulate the your app. Because of this, the map follows the map div position with little delay.

    If you are not acceptable, please use alternative solutions, such as Google Maps JavaScript API v3 or MapBox.

  • Manipulate like a HTML element!

    The biggest benefit of this plugin is you can put/cover any HTML elements on the map, just like HTML!

    The maps plugin recognizes all touches before browser, calculates who should receive the touch event, then pass it.

  • What's camera?

    The native Google Map APIs have a 3D map internally. We can only see the map through the camera.

Events

  • User interface events

    A map instance tells us what UI changes are occurred through these events:

    • MAP_READY
    • MAP_CLICK
    • MAP_LONG_CLICK
    • CAMERA_MOVE_START (including map dragging)
    • CAMERA_MOVE
    • CAMERA_MOVE_END
    • MY_LOCATION_BUTTON_CLICK
    • MY_LOCATION_CLICK
    • POI_CLICK

    The above events passes with event information in parameter, such as where is clicked.

    map.on(plugin.google.maps.event.MAP_CLICK, function(latLng) {
  alert(latLng + " is clicked!");
});

    And also, event listener is involved with the instance of the map. This allows you to write your event listener code in a separate place.

    map.on(plugin.google.maps.event.MAP_CLICK, onMapClick);

function onMapClick(latLng) {
  var map = this;

  map.addMarker({
    position: latLng
  });
}

  • MVC status change events

    The map class extends BaseClass. The BaseClass has set() and get() methods. This is very useful methods.

    If you set a value through set() method, you can listen the (key)_changed event.

    The benefit of this is you can write your code Model-View-Controller separately.

    map.on(plugin.google.maps.event.MAP_CLICK, function(latLng) {
  map.set("clickPosition", latLng);
});

map.on("clickPosition_changed", function() {
  var clickPosition = this.get("clickPosition");
});

Camera

  • Changing the camera position

    This plugin has two basic methods:

    • map.animateCamera() changes the camera position with animation.
    • map.moveCamera() changes the camera position without animation.
    map.animateCamera({
  target: {lat: 37.422359, lng: -122.084344},
  zoom: 17,
  tilt: 60,
  bearing: 140,
  duration: 5000
}, function() {
  //alert("Camera target has been changed");
});

    Other methods animateCameraZoomIn(), moveCameraZoomIn(), setCameraTarget()...etc use one of the above methods internally.

    Since this plugin stops other methods execution during the camera moving, this is bad performance code.

    Bad performance code

    map.setCameraZoom(10);
map.setCameraTilt(30);
map.setCameraBearing(45);

    Recommended way is using one method as much as possible.

    Good performance code

    map.moveCamera({
  zoom: 10,
  tilt: 30,
  bearing: 45
});

  • Get the camera position

    You can get the camera position through these method anytime.

    • map.getCameraPosition() // Returns center, zoom, bearing, and tilt values
    • map.getCameraZoom()
    • map.getCameraTarget()
    • map.getCameraBearing()
    • map.getCameraTilt()

    Also you can listen the CAMERA_MOVE events.

    map.on(plugin.google.maps.event.CAMERA_MOVE, function(cameraPosition) {
  console.log(cameraPosition.target);
});

    If you want to listen particular property, you can do like this:

    map.on('camera_target_changed', function(latLng) {
  console.log("map center = " + latLng);
});

API reference

Create

getMap() Gets a new map class instance.

Methods

setDiv() Changes the map div.
getDiv() Returns the map div.
setMapTypeId() Changes the map type id.
animateCamera() Moves the camera with animation.
animateCameraZoomIn() Zooming in the camera with animation.
animateCameraZoomOut() Zooming out the camera with animation.
moveCamera() Moves the camera without animation.
moveCameraZoomIn() Zooming in the camera without animation.
moveCameraZoomOut() Zooming out the camera without animation.
getCameraPosition() Get the current camera position, including the target, zoom, tilt and bearing.
getCameraTarget() Get the current camera target position.
getCameraZoom() Get the current camera zoom level.
getCameraBearing() Get the current camera bearing.
getCameraTilt() Get the current camera tilt (view angle).
setCameraTarget() Set the center position of the camera view.
setCameraZoom() Set zoom level of the camera.
setCameraTilt() Set the camera view angle.
setCameraBearing() Set the camera bearing.
panBy() Change the center of the map by the given distance in pixels.
getVisibleRegion() Get the current visible region (sw and ne).
getMyLocation() Get the current device location.
setClickable() Set false to ignore all clicks on the map.
remove() Destroy a map completely.
clear() Remove all overlays, such as marker.
fromLatLngToPoint() Convert the unit from LatLng to the pixels from the left/top of the map div.
fromPointToLatLng() Convert the unit from the pixels from the left/top to the LatLng.
setMyLocationButtonEnabled() Set true if you want to show the MyLocation button.
setMyLocationEnabled() Set true if you want to show the MyLocation control (blue dot).
getFocusedBuilding() Get the currently focused building.
setIndoorEnabled() Set true if you want to show the indoor map.
setTrafficEnabled() Set true if you want to show the traffic layer.
setCompassEnabled() Set true if you want to show the compass button.
setAllGesturesEnabled() Sets the preference for whether all gestures should be enabled or disabled.
setVisible() Set visibility of the map.
setPadding() Adjust the map padding.
setOptions() Adjust the map padding.
toDataURL() Generate the map screen capture image as base64 encoded data, like HTML5's Canvas.
map.addMarker() Add a marker.
map.addPolyline() Add a polyline.
map.addPolygon() Add a polygon.
map.addCircle() Add a circle.
map.addGroundOverlay() Add a ground overlay.
map.addTileLayer() Add tile layer.
map.addKmlOverlay() Add kml layer.

Events

MAP_CLICK This event is fired when you click on the map.
MAP_LONG_CLICK This event is fired when you press your finger a few seconds on the map.
MY_LOCATION_BUTTON_CLICK This event is fired when you tap on the location button.
MY_LOCATION_CLICK This event is fired when you tap on the location control (blue dot).
POI_CLICK This event is fired when you tap on POIs(such as building icon).
CAMERA_MOVE_START
CAMERA_MOVE
CAMERA_MOVE_END		 This events are fired when the camera moves.
MAP_DRAG_START
MAP_DRAG
MAP_DRAG_END		 This events are fired when the camera moves with gestures.
MAP_READY This event is fired when the map is created using the map.getMap() method.