Skip to content

Latest commit

 

History

History
104 lines (89 loc) · 5.3 KB

README.md

File metadata and controls

104 lines (89 loc) · 5.3 KB
Raw

Measurement Tool for Google Maps API V3

A handy measurement widget for Google Maps API v3. The functionalities are implemented as close as to what current Google Maps offers.

Demo

Visit demo page

demo screen shot

Developer usage

Dependency

Make sure the geometry library is referenced in the Google Maps JavaScript API loading script.

libraries=geometry

Basic use

To create the measurement widget, pass in a Google Map instance.

var measureTool = new MeasureTool(map);

Pass in MeasureToolOptions

You could also pass in a MeasureToolOptions as the second argument to customize to your preference.

var measureTool = new MeasureTool(map, {
  showSegmentLength: true,
  unit: MeasureTool.UnitTypeId.IMPERIAL // or just use 'imperial'
});

Bind to your own UI

The MeasureTool comes with a context menu out of box for saving your time to create your own. However, if you'd like to bind the MeasureTool to your own UI, you could specify contextMenu to false when constructing the MeasureTool. The MeasureTool exposes two public methods start() and end() to start and end measuring. For example,

<button onclick="measureTool.start()">start</button>
<button onclick="measureTool.end()">end</button>
var measureTool = new MeasureTool(map, {
  contextMenu: false
  // some other options...
});

User usage

  1. To start measuring, right click the map and choose Measure distance.
  2. Left click the map, and the measurement between the two locations will display. Keep clicking to add more measurement waypoints.
  3. To remove a waypoint, left click on the waypoint (the first point cannot be removed).
  4. To insert a waypoint on the measurement line, click the line. Waypoints can be moved by clicking and dragging them.
  5. When the first point and the last point are close enough, the area will display.
  6. To end measuring, right click the map and choose Clear measurement.

API

MeasureTool class

Constructor Description
MeasureTool(map:google.maps.Map, opts?:MeasureToolOptions) Creates a new measure tool for the google.maps.Map instance.
Methods Description
addListener(eventName: string, handler:Function) Return Value: None - addes the given listener function to the given event name.
end() Return Value: None - ends measuring.
removeListener(eventName: string) Return Value: None - removes the given listener.
start() Return Value: None - starts measuring.
setOption(option: string, value: string) Return Value: None - updates a confirguration option and re-generates the drawn shape.
Properties Description
area Type: number - the total area of the enclosed polygon, the unit is m² for metric unit and ft² for imperial unit.
areaText Type: string - the formatted total area with unit of the enclosed polygon.
length Type: number - the total length of the path drawn, the unit is m for metric unit and ft for imperial unit.
lengthText Type: string - the formatted total length with unit of the path drawn.
Events Description
measure_change Arguments: MeasureEvent - This event is fired when a measure step is completed
measure_end Arguments: MeasureEvent - This event is fired when the user ends measuring
measure_start Arguments: None - This event is fired when the user starts measuring

MeasureToolOptions object specification

Properties Description
showSegmentLength Type: boolean - display segment length along the path. Enabled by default.
tooltip Type: boolean - display tooltip when hover the drawing path. Enabled by default.
unit Type: UnitTypeId - the unit type to use for the measured length and area. Defaults to MeasureTool.UnitTypeId.METRIC.

MeasureEvent object specification

Properties Description
result Type: MeasureResult - The result of the measuring.

MeasureResult object specification

Properties Description
area Type: number - the total area of the enclosed polygon, the unit is m² for metric unit and ft² for imperial unit.
areaText Type: string - the formatted total area with unit of the enclosed polygon.
length Type: number - the total length of the path drawn, the unit is m for metric unit and ft for imperial unit.
lengthText Type: string - the formatted total length with unit of the path drawn.

UnitTypeId constants

Identifiers for common UnitType. Specify these by value, or by using the constant's name. For example, 'metric' or MeasureTool.UnitTypeId.METRIC.

Constant Description
IMPERIAL This unit type shows measured length in US foot (ft) and mile (mi), and area in US square foot (ft²) and square mile (mi²).
METRIC This unit type shows measured length in meter (m) and kilometer (km), and area in square meter (m²) and square kilometer (km²).