Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Measurement

require(["esri/dijit/Measurement"], function(Measurement) { /* code goes here */ });

Description

(Added at v2.3)
The Measurement widget provides tools for calculating the current location (Get Location) and measuring distance (Measure Distance) and area (Measure Area). If the map's coordinate system is not Web Mercator or geographic or if complex polygons are drawn the measure widget will need to use the geometry service to project or simplify geometries. Use esri.config.defaults to specify the geometry service for your application.
require(["esri/config"], function(esriConfig) { 
  esriConfig.defaults.geometryService = new esri.tasks.GeometryService("https://sampleserver6.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer");
});

It is recommended that you create a geometry service for use within your applications. View the Geometry Services help topic in the Server Resource Center for details on creating and publishing a geometry service. Esri hosts a geometry service on sampleserver6 to support samples published in the Resource Center. You are welcome to use this service for development and testing purposes.

Samples

Search for samples that use this class.

Constructors

NameSummary
new Measurement(params, srcNodeRef)Creates a new Measurement widget.

CSS

esri/dijit/Measurement | Download source

NameDescription
areaIconSpecify the icon used for the Measure Area tool.
distanceIconSpecify the icon used for the Measure Distance tool.
locationIconSpecify the icon used for the Get Location tool.
resultDefine the style for the result text.
resultLabelDefine the style for the result label.
unitDropDownDefine the font used by the unit drop down list.

Methods

NameReturn typeSummary
clearResult()NoneRemove the measurement graphics and results.
destroy()NoneDestroy the measurement widget.
getTool()ObjectReturns an Object with two properties: toolName and unitName.
getUnit()StringReturns current measurement unit of the active tool.
hide()NoneHide the measurement widget.
hideTool(toolName)NoneHide the specified tool.
measure(geometry)NoneInvoke the measurement functionality of the widget by passing in a previously created geometry.
setTool(toolName, activate)NoneActivate or deactivate a tool.
show()NoneShow the measurement widget after it has been hidden using the hide method.
showTool(toolName)NoneDisplay the specified tool.
startup()NoneFinalizes the creation of the measurement widget .

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
measure
{
  geometry: <Geometry>,
  segmentLength: <Number>,
  toolName: <String>,
  unitName: <String>,
  values: <Number>
}
Fires any time the mouse pointer moves while doing a distance measurement.
measure-end
{
  geometry: <Geometry>,
  toolName: <String>,
  unitName: <String>,
  values: <Number[] | Number>
}
Fired when the measurement is complete.
measure-start
{
  toolName: <String>,
  unitName: <String>
}
Fires when a measurement operation begins (single-click).
tool-change
{
  previousToolName: <String>,
  toolName: <String>,
  unitName: <String>
}
Fires when the primary tool is changed.
unit-change
{
  toolName: <String>,
  unitName: <String>
}
Fires when the units currently being used by the Measurement widget changes.
Constructor Details

new Measurement(params, srcNodeRef)

Creates a new Measurement widget. The Measurement constructor should be called after the map is loaded, for example in the map's .on("load") event. (Added at v3.10)
Parameters:
<Object> params Required See options list for parameters.
<Node | String> srcNodeRef Required Reference or id of the HTML element where the widget should be rendered.
params properties:
<Boolean> advancedLocationUnits Optional Flag for showing full list of units in the Location tool. When set to true you also need to specify a geometry service for use by the application. This geometry service needs to support the toGeocoordinateString and fromGeoCoordinateString operations which were added at ArcGIS Server version 10.3. Default is false. Added at version 3.10.
<String> defaultAreaUnit Optional The default area unit for the measure area tool. Added at v 2.4. The following constants are not supported: ARES, SQUARE_INCHES, SQUARE_MILLIMETERS, SQUARE_CENTIMETERS, SQUARE_DECIMETERS
<String> defaultLengthUnit Optional The default length unit for the measure distance tool. Added at v 2.4. The following constants are not supported: CENTIMETERS, DECIMAL_DEGREES, DECIMETERS, INCHES, NAUTICAL_MILES, POINTS, UNKNOWN.
<SimpleFillSymbol> fillSymbol Optional Fill symbol used to symbolize the polygons representing the areas measured for the measure area tool.
<Point | Polyline | Polygon> geometry Optional Allows the user to immediately measure previously-created geometry on dijit creation.
<SimpleLineSymbol> lineSymbol Optional Line symbol used to draw the lines for the measure line and measure distance tools.
<Map> map Required Reference to the map. The map parameter is required.
<MarkerSymbol> pointSymbol Optional Marker symbol used to draw the points for the measure line tool. The default symbol, from version 3.11 is a 16x26 picture marker symbol with a vertical offset of 12 pixels.
Sample:
require([
  "esri/map", "esri/dijit/Measurement", "esri/units", "dojo/dom", ... 
], function(Map, Measurement, Units, dom, ... ) {
  var map = new Map( ... );
  var measurement = new Measurement({
    map: map,
    defaultAreaUnit: Units.SQUARE_MILES,
    defaultLengthUnit: Units.KILOMETERS
  }, dom.byId('measurement'));
  ...
});

require([
  "esri/map", "esri/dijit/Measurement", "esri/geometry/Polyline", "esri/geometry/Point", "dojo/dom", ... 
], function(Map, Measurement, Polyline, Point, dom, ... ) {
  var customPolyline = new Polyline({"wkid":102100});
  customPolyline.addPath([
    new Point(-13262764.15,2864328.22), 
    new Point(-6237895.50, 5290745.25), 
    new Point(-3283145.74, -618754.28)
  ]);

  var measurement = new Measurement({
    geometry: customPolyline,
    map: map
  }, dom.byId("measurement"));
  measurement.startup();
  ...
});
Method Details

clearResult()

Remove the measurement graphics and results. (Added at v2.4)

destroy()

Destroy the measurement widget.

getTool()

Returns an Object with two properties: toolName and unitName. These properties are based on the active tool and the selected measurement unit of that tool. (Added at v3.11)
Return type: Object

getUnit()

Returns current measurement unit of the active tool. (Added at v3.11)
Return type: String

hide()

Hide the measurement widget.
Sample:
measurement.hide();

hideTool(toolName)

Hide the specified tool. (Added at v2.4)
Parameters:
<String> toolName Required Valid values are "area", "distance" or "location".
Sample:
measurement.hideTool("distance");

measure(geometry)

Invoke the measurement functionality of the widget by passing in a previously created geometry. (Added at v3.10)
Parameters:
<Point | Polyline | Polygon> geometry Required Geometry to be measured.
Sample:
var customPolyline = new Polyline({"wkid":102100});
customPolyline.addPath([
  new Point(-13262764.15,2864328.22), 
  new Point(-6237895.50, 5290745.25), 
  new Point(-3283145.74, -618754.28)
]);
measurement.measure(customPolyline);

setTool(toolName, activate)

Activate or deactivate a tool. The widget must be created before using this method so wait until after startup to set the tool. (Added at v2.4)
Parameters:
<String> toolName Required The name of the tool to activate or deactivate. Valid values are "area", "distance", "location".
<Boolean> activate Required When true, the specified tool is activated. Set to false to deactivate the tool.
Sample:

measurementWidget.setTool("location",true);

show()

Show the measurement widget after it has been hidden using the hide method.
Sample:
measurement.show();

showTool(toolName)

Display the specified tool. (Added at v2.4)
Parameters:
<String> toolName Required Valid values are "area", "distance" or "location".
Sample:
measurement.showTool("distance");

startup()

Finalizes the creation of the measurement widget . Call startup() after creating the widget when you are ready for user interaction.
Sample:
measurement.startup();
Event Details
[ On Style Events | Connect Style Event ]

measure

Fires any time the mouse pointer moves while doing a distance measurement. (Added at v3.11). Note: Prior to v3.16, this event only fired on single-click.
Event Object Properties:
<Geometry> geometry The Point or Polygon geometry from the measurement.
<Number> segmentLength The length of the last segment. As of v3.16.
<String> toolName The name (distance, area) of the active tool.
<String> unitName The name of the units currently being used by the Measurement widget.
<Number> values If the toolName is distance or area then the values will be a number containing the length of the measurement in the units currently being used by the Measurement widget.

measure-end

Fired when the measurement is complete. (Added at v3.6)
Event Object Properties:
<Geometry> geometry The Point, Polyline, or Polygon geometry from the measurement. As of v2.7
<String> toolName The name of the active tool, either location, distance, or area.
<String> unitName The name of the units currently being used by the Measurement widget. As of v3.11.
<Number[] | Number> values If the toolName is location then the values will be an Array containing the location values, and if the toolName is distance or area then the values will be a number containing the length of the measurement in the units currently being used by the Measurement widget. As of v3.11.
Sample:
require([
 ... 
], function( ... ) {
  measurement.on("measure-end", function(evt){
    this.setTool(evt.toolName, false);
  });
  ...
});

measure-start

Fires when a measurement operation begins (single-click). (Added at v3.11)
Event Object Properties:
<String> toolName The name (location, distance, area) of the active tool.
<String> unitName The name of the units currently being used by the Measurement widget.

tool-change

Fires when the primary tool is changed. (Added at v3.11)
Event Object Properties:
<String> previousToolName The name (location, distance, area) of the previously active tool.
<String> toolName The name (location, distance, area) of the active tool.
<String> unitName The name of the units currently being used by the Measurement widget.

unit-change

Fires when the units currently being used by the Measurement widget changes. (Added at v3.11)
Event Object Properties:
<String> toolName The name (location, distance, area) of the active tool.
<String> unitName The name of the units currently being used by the Measurement widget.