All docs
V20.2
20.2 (EAP/Beta)
20.1
The page you are viewing does not exist in version 20.1. This link will take you to the root page.
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
You are viewing help content for pre-release software. This document and the features it describes are subject to change.

Measurements Class

Contains API to manage rulers that help users measure distances and areas on a map.

Namespace: DevExpress.XtraMap

Assembly: DevExpress.XtraMap.v20.2.dll

Declaration

public class Measurements :
    IMapEditor,
    IRulerActionListener
Public Class Measurements
    Implements IMapEditor,
               IRulerActionListener

Related API Members

The following members accept/return Measurements objects:

Remarks

The Measurements class allows you to manage distance and area rulers on a map.

Distance Ruler Area Ruler
Map Distance Ruler Map Area Ruler

Measurements Toolbar

The Measurements toolbar contains buttons that allow users to add rulers to a map. To display this toolbar, set the ShowToolbar property to true in the Properties window at design time.

Measurement Toolbar

Use the code below to show the toolbar at runtime.

mapControl1.Measurements.ShowToolbar = true;

Toolbar buttons include:

Button

Name

Visibility

Distance Ruler Button

Add Distance Ruler

ToolbarOptions.ShowDistanceButton

Area Ruler Button

Add Area Ruler

ToolbarOptions.ShowAreaButton

Distance Ruler

This ruler calculates the distance between two or more points on a map. The total distance is shown in a map callout. Measurements ignore changes in elevation.

Distance Ruler

To specify units for newly created distance rulers, assign one of the following values to the DistanceUnits property:

Specify measurement units before you create the ruler to apply these units to the ruler. The following code creates a ruler that measures distance in miles:

mapControl1.Measurements.DistanceUnits = MeasureUnit.Mile;
MapRuler ruler= mapControl1.Measurements.CreateRuler(RulerType.Distance, new List<CoordPoint>() {
                                                                                  new GeoPoint(0, 0),
                                                                                  new GeoPoint(10, 0),
                                                                                  new GeoPoint(10, 10)});

Area Ruler

This ruler calculates the area inside a polygon. The result is shown in a map callout.

Area Ruler

To define area units, set the AreaUnits property to one of the following values:

Specify area units before you create the ruler to apply these units to the ruler. The following code creates a ruler that measures area in square miles:

mapControl1.Measurements.AreaUnits = AreaMeasureUnit.SquareMile;
MapRuler ruler= mapControl1.Measurements.CreateRuler(RulerType.Area, new List<CoordPoint>() {
                                                                                  new GeoPoint(0, 0),
                                                                                  new GeoPoint(10, 0),
                                                                                  new GeoPoint(10, 10) });

Ruler Management

Create Rulers

To create a ruler, a user can click the Add Distance Ruler or Add Area Ruler toolbar button, click the map to set ruler points, and then double-click the map to complete the ruler.

The following image shows how to create an area ruler:

Add Ruler on Map

You can also call the SetCreateMode(RulerType) method to activate the Measurements object's Create mode. In this mode, users can click the map to create a ruler. They do not need to click toolbar buttons.

To create a ruler programmatically, call the CreateRuler(RulerType, IList<CoordPoint>) method. The following code creates a distance ruler:

MapRuler ruler = mapControl1.Measurements.CreateRuler(RulerType.Distance, 
                                                        new List<CoordPoint>(){
                                                           new GeoPoint(48.864716, 2.349014),   // Paris
                                                           new GeoPoint(45.46427, 9.18951),     // Milan
                                                           new GeoPoint(48.20849, 16.37208) }); // Vienna

Map Ruler

Configure Rulers

After a ruler is added to the map, the Measurements object activates Edit mode. The SetEditMode() method also enables Edit mode.

Action

Description

Add a ruler point.

Click the position on the ruler.

Move a ruler point.

Click and drag the point to a new location.

Delete a ruler point.

Double-click the point.

The image below shows how to change a distance ruler:

Edit Ruler

Use the following methods to configure a ruler programmatically:

Name

Description

InsertPoint(MapRuler, CoordPoint, Int32)

Adds a new point to the ruler passed as a parameter.

RemovePoint(MapRuler, Int32)

Removes the point with the specified index.

UpdatePoint(MapRuler, CoordPoint, Int32)

Changes coordinates of the point with the specified index.

The example below creates a ruler to measure the Paris-Milan-Vienna distance. After that, the code updates the ruler: adds a point at Berlin's coordinates, moves the first point from Paris to Dusseldorf, and removes the point at Milan's coordinates from the ruler.

MapRuler ruler = mapControl1.Measurements.CreateRuler(RulerType.Distance,
                                                        new List<CoordPoint>() {
                                                            new GeoPoint(48.864716, 2.349014), // Paris
                                                            new GeoPoint(45.46427, 9.18951),   // Milan
                                                            new GeoPoint(48.20849, 16.37208)   // Vienna
                                                        });
//The code below updates the ruler.                                                        
mapControl1.Measurements.InsertPoint(ruler, new GeoPoint(52.520008, 13.404954), 2); // Berlin
mapControl1.Measurements.UpdatePoint(ruler, new GeoPoint(51.2217200, 6.7761600), 0); // Dusseldorf
mapControl1.Measurements.RemovePoint(ruler, 1); // Milan
Before Update After Update
Before update ruler points  After update ruler points

Remove Rulers

To remove a ruler, a user can click the cross button on the map callout that displays the ruler's measurement value:

Remove Ruler

The RemoveRuler(MapRuler) method removes the ruler passed as a parameter.

mapControl1.Measurements.RemoveRuler(ruler);

To delete all rulers from the map, call the RemoveRulers() method.

mapControl1.Measurements.RemoveRulers();

Control Ruler Creation

You can handle the BeforeMeasurement and AfterMeasurement events to implement custom logic during ruler creation.

The example below cancels ruler creation if a ruler starts inside an ellipse. The MapControl.CalcHitInfo returns information on the map elements located at the ruler's first point, that the e.StartPoint property returns.

private void Measurements_BeforeMeasurement(object sender, BeforeMeasurementEventArgs e) {
 MapHitInfo info = this.mapControl1.CalcHitInfo(e.StartPonit);
 if (info.InMapEllipse) {
     e.Cancel = true;
 }    
}

The following example cancels area ruler creation. Use the e.MapRuler property in the AfterMeasurement event handler to get a created ruler. To determine the type of the ruler, use the MapRuler.RulerType property.

private void Measurements_AfterMeasurement(object sender, AfterMeasurementEventArgs e) {
  MapRuler ruler1 = e.MapRuler;
  if (ruler1.RulerType == RulerType.Area) {
      e.Cancel = true;
  }
}
TIP

You can also use the GeoUtils class to calculate geometric values on the map. This class contains cartography measurement API for maps with a geographic coordinate system.

Customize Ruler Appearance

Call the CreateRuler(RulerType, IList<CoordPoint>, MapRulerStyle) method and pass ruler style options as the style parameter.

The following example changes the ruler's outline color and width:

MapRulerStyle style = new MapRulerStyle();
style.Stroke = Color.Red;
style.StrokeWidth = 3;
MapRuler ruler1 = mapControl1.Measurements.CreateRuler(RulerType.Distance, 
                                                      new List<CoordPoint>() {
                                                          new GeoPoint(51.2217200, 6.7761600), // Dusseldorf
                                                          new GeoPoint(52.520008, 13.404954),  // Berlin
                                                          new GeoPoint(48.20849, 16.37208)   // Vienna
                                                      }, style);

Related API members:

Name

Description

CreateRuler(RulerType, IList<CoordPoint>, MapRulerStyle)

Creates a ruler with the specified style.

MapRulerStyle

Contains ruler style options.

Stroke

Gets or sets the ruler's outline color.

StrokeWidth

Gets or sets the ruler's outline width.

Inheritance

Object
Measurements
See Also