Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: Measurement
[ AMD Module Require | Legacy Module Require ]
dojo.require("esri.dijit.Measurement")
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
| Name | Summary |
|---|---|
| new esri.dijit.Measurement(params, srcNodeRef) | Creates a new Measurement widget. |
CSS
esri/dijit/Measurement | Download source
| Name | Description |
|---|---|
| areaIcon | Specify the icon used for the Measure Area tool. |
| distanceIcon | Specify the icon used for the Measure Distance tool. |
| locationIcon | Specify the icon used for the Get Location tool. |
| result | Define the style for the result text. |
| resultLabel | Define the style for the result label. |
| unitDropDown | Define the font used by the unit drop down list. |
Methods
| Name | Return type | Summary |
|---|---|---|
| clearResult() | None | Remove the measurement graphics and results. |
| destroy() | None | Destroy the measurement widget. |
| getTool() | Object | Returns an Object with two properties: toolName and unitName. |
| getUnit() | String | Returns current measurement unit of the active tool. |
| hide() | None | Hide the measurement widget. |
| hideTool(toolName) | None | Hide the specified tool. |
| measure(geometry) | None | Invoke the measurement functionality of the widget by passing in a previously created geometry. |
| setTool(toolName, activate) | None | Activate or deactivate a tool. |
| show() | None | Show the measurement widget after it has been hidden using the hide method. |
| showTool(toolName) | None | Display the specified tool. |
| startup() | None | Finalizes 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
| Name | Event Object | Summary |
|---|---|---|
| measure | {
geometry: < | Fires any time the mouse pointer moves while doing a distance measurement. |
| measure-end | {
geometry: < | Fired when the measurement is complete. |
| measure-start | {
toolName: < | Fires when a measurement operation begins (single-click). |
| tool-change | {
previousToolName: < | Fires when the primary tool is changed. |
| unit-change | {
toolName: < | Fires when the units currently being used by the Measurement widget changes. |
Constructor Details
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:
< |
Required | See options list for parameters. |
< |
Required | Reference or id of the HTML element where the widget should be rendered. |
params properties: < |
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. |
< |
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 |
< |
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. |
< |
Optional | Fill symbol used to symbolize the polygons representing the areas measured for the measure area tool. |
< |
Optional | Allows the user to immediately measure previously-created geometry on dijit creation. |
< |
Optional | Line symbol used to draw the lines for the measure line and measure distance tools. |
< |
Required | Reference to the map. The map parameter is required. |
< |
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:
var measurement = new esri.dijit.Measurement({
map: map,
defaultAreaUnit: esri.Units.SQUARE_MILES,
defaultLengthUnit: esri.Units.KILOMETERS
}, dojo.byId('measurement'));
var customPolyline = new esri.geometry.Polyline({"wkid":102100});
customPolyline.addPath([
new esri.geometry.Point(-13262764.15,2864328.22),
new esri.geometry.Point(-6237895.50, 5290745.25),
new esri.geometry.Point(-3283145.74, -618754.28)
]);
var measurement = new esri.dijit.Measurement({
geometry: customPolyline,
map: map
}, dojo.byId("measurement"));
measurement.startup();
Method Details
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:
ObjectHide the specified tool. (Added at v2.4)
Parameters:
< |
Required | Valid values are "area", "distance" or "location". |
Sample:
measurement.hideTool("distance");
Invoke the measurement functionality of the widget by passing in a previously created geometry. (Added at v3.10)
Sample:
var customPolyline = new esri.geometry.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);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:
< |
Required | The name of the tool to activate or deactivate. Valid values are "area", "distance", "location". |
< |
Required | When true, the specified tool is activated. Set to false to deactivate the tool. |
Sample:
measurementWidget.setTool("location",true);
Show the measurement widget after it has been hidden using the hide method.
Sample:
measurement.show();
Display the specified tool. (Added at v2.4)
Parameters:
< |
Required | Valid values are "area", "distance" or "location". |
Sample:
measurement.showTool("distance");
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 ]
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:
< |
The Point or Polygon geometry from the measurement. |
< |
The length of the last segment. As of v3.16. |
< |
The name (distance, area) of the active tool. |
< |
The name of the units currently being used by the Measurement widget. |
< |
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. |
Fired when the measurement is complete. (Added at v3.6)
Event Object Properties:
< |
The Point, Polyline, or Polygon geometry from the measurement. As of v2.7 |
< |
The name of the active tool, either location, distance, or area. |
< |
The name of the units currently being used by the Measurement widget. As of v3.11. |
< |
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);
});
...
});
Fires when a measurement operation begins (single-click). (Added at v3.11)
Fires when the primary tool is changed. (Added at v3.11)