Skip to main content
All docs
V25.1
  • DevExpress v25.1 Update — Your Feedback Matters

    Our What's New in v25.1 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

    Take the survey Not interested

    Measurements Class

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

    Namespace: DevExpress.XtraMap

    Assembly: DevExpress.XtraMap.v25.1.dll

    NuGet Package: DevExpress.Win.Map

    #Declaration

    public class Measurements :
        IMapEditor,
        IRulerActionListener,
        IMapRulerStyleProvider,
        IMapStyleOwner,
        IMapOverlayActionListener

    The following members 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

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

    Distance Ruler

    Click an intermediate point on the ruler to see the distance to this point.

    To specify the measurement unit for the newly created distance ruler, set the DistanceUnits property to one of the following values:

    To apply the distance unit to the ruler, specify the unit before you create 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

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

    Area Ruler

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

    To apply the area unit to the ruler, specify the unit before you create the ruler. The following code creates a ruler that measures the area in square miles:

    mapControl1.Measurements.AreaUnits = AreaMeasurementUnit.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 created, the Measurements object activates Edit mode. The SetEditMode() method also enables Edit mode.

    The following actions are available in Edit mode:

    Action

    Description

    Add a ruler point.

    Click the position on the ruler where you wish to add a point.

    Change the ruler polyline.

    Click and drag the point to a new location.

    Delete a ruler point.

    Double-click the ruler 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.

    RemovePoint(MapRuler, Int32)

    Removes the point with the specified index.

    UpdatePoint(MapRuler, CoordPoint, Int32)

    Changes the coordinates of the point with the specified index.

    The example below creates a ruler to measure the distance between Paris, Milan and Vienna. After calculating this distance, the code updates the ruler as follows:

    • a point is added at Berlin’s coordinates;
    • the first point is moved from Paris to Dusseldorf;
    • the point at Milan’s coordinates is removed 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 method returns information on the map elements located at the ruler’s first point. The e.StartPoint property returns this point.

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

    The following example cancels area ruler creation. First, use the e.MapRuler property in the AfterMeasurement event handler to get the newly created ruler. To determine whether this ruler is an area ruler, use the MapRuler.RulerType property. If it is an area ruler, set the e.Cancel property to true to prevent the ruler from being displayed.

    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

    Use the Style property to define the style for all rulers on the map.

    Map ruler style

    mapControl1.Measurements.Style.Fill = Color.OrangeRed;
    mapControl1.Measurements.Style.AreaTransparency = 100;
    mapControl1.Measurements.Style.Stroke = Color.DarkRed;
    mapControl1.Measurements.Style.StrokeWidth = 2;
    

    The fill color is also used to draw the outline border of area rulers and distance ruler borders.

    To change style settings for a newly created ruler, handle the BeforeMeasurement event. Use the e.Style property to define a new ruler style as follows:

    private void Measurements_BeforeMeasurement(object sender, BeforeMeasurementEventArgs e) {
      e.Style.Stroke = Color.Gray;
      e.Style.StrokeWidth = 4; 
    }
    

    You can also 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:

    Map ruler style

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

    #Inheritance

    Object
    Measurements
    See Also