wpf-devexpress-dot-xpf-dot-map-8cbde352.md
Contains API to manage rulers that help users measure distances and areas on a map.
Namespace : DevExpress.Xpf.Map
Assembly : DevExpress.Xpf.Map.v25.2.dll
NuGet Package : DevExpress.Wpf.Map
public class Measurements :
MapDependencyObject,
IMapEditor,
IOwnedElement,
IRulerActionListener
Public Class Measurements
Inherits MapDependencyObject
Implements IMapEditor,
IOwnedElement,
IRulerActionListener
The following members return Measurements objects:
The Measurements class allows you to manage distance and area rulers on a map.
| Distance Ruler | Area Ruler |
|---|---|
The Measurements toolbar contains buttons that allow users to add rulers to a map. To display this toolbar, initialize a new instance of the Measurements class.
In markup:
<dxm:MapControl x:Name="mapControl1">
<dxm:MapControl.Measurements>
<dxm:Measurements/>
</dxm:MapControl.Measurements>
</dxm:MapControl>
In code:
mapControl1.Measurements = new Measurements();
mapControl1.Measurements.ToolbarOptions = new MeasurementToolbarOptions();
mapControl1.Measurements = New Measurements()
mapControl1.Measurements.ToolbarOptions = New MeasurementToolbarOptions()
Use the ToolbarOptions.Visible property to manage the toolbar visibility.
Toolbar buttons include:
|
Button
|
Name
|
Visibility
| | --- | --- | --- | |
|
Add Distance Ruler
|
ToolbarOptions.ShowDistanceButton
| |
|
Add Area Ruler
|
|
This 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.
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)});
mapControl1.Measurements.DistanceUnits = MeasureUnit.Mile
Dim ruler As MapRuler = mapControl1.Measurements.CreateRuler(RulerType.Distance,
New List(Of CoordPoint)() From {
New GeoPoint(0, 0),
New GeoPoint(10, 0),
New GeoPoint(10, 10)})
The following ruler calculates the area inside a polygon. The result is shown in a map callout.
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 = AreaMeasureUnit.SquareMile;
MapRuler ruler= mapControl1.Measurements.CreateRuler(RulerType.Area, new List<CoordPoint>() {
new GeoPoint(0, 0),
new GeoPoint(10, 0),
new GeoPoint(10, 10) });
mapControl1.Measurements.AreaUnits = AreaMeasureUnit.SquareMile
Dim ruler As MapRuler = mapControl1.Measurements.CreateRuler(RulerType.Area,
New List(Of CoordPoint)() From {
New GeoPoint(0, 0),
New GeoPoint(10, 0),
New GeoPoint(10, 10)})
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:
The Measurements object supports Create mode. In this mode, users can click the map to create a ruler. They do not need to click the toolbar buttons. You can activate Create mode in markup:
<dxm:MapControl.Measurements>
<dxm:Measurements>
<dxm:Measurements.Mode>
<dxm:MeasurementCreateMode RulerType="Area"/>
</dxm:Measurements.Mode>
</dxm:Measurements>
</dxm:MapControl.Measurements>
To enable Create mode in code, specify the Mode property as follows:
MeasurementCreateMode mode = new MeasurementCreateMode();
mode.RulerType = RulerType.Area;
mapControl1.Measurements.Mode = mode;
Dim mode As MeasurementCreateMode = New MeasurementCreateMode()
mode.RulerType = RulerType.Area
mapControl1.Measurements.Mode = mode
The SetCreateModeCommand also switches the Measurements object to Create mode.
Call the CreateRuler(RulerType, IList<CoordPoint>) method to create a ruler programmatically. The following code adds a distance ruler to the map:
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
Dim ruler As MapRuler = mapControl1.Measurements.CreateRuler(RulerType.Distance,
New List(Of CoordPoint)() From {
New GeoPoint(48.864716, 2.349014), ' Paris
New GeoPoint(45.46427, 9.18951), ' Milan
New GeoPoint(48.20849, 16.37208) }) ' Vienna
After a ruler is created, the Measurements object activates Edit mode. You can also enable Edit mode as follows:
In XAML:
<dxm:MapControl.Measurements>
<dxm:Measurements>
<dxm:Measurements.Mode>
<dxm:MeasurementEditMode/>
</dxm:Measurements.Mode>
</dxm:Measurements>
</dxm:MapControl.Measurements>
In code:
mapControl1.Measurements.Mode = new MeasurementEditMode();
mapControl1.Measurements.Mode = New MeasurementEditMode()
The SetEditModeCommand also switches the Measurements object to 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:
Use the following methods to configure rulers programmatically:
|
Name
|
Description
| | --- | --- | |
InsertPoint(MapRuler, CoordPoint, Int32)
|
Adds a new point to the ruler.
| |
|
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
Dim ruler As MapRuler = mapControl1.Measurements.CreateRuler(RulerType.Distance,
New List(Of CoordPoint)() From {
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 |
|---|---|
A user can click the cross button on the map callout that displays the ruler’s measurement value to remove a ruler:
The RemoveRuler(MapRuler) method removes the ruler passed as a parameter.
mapControl1.Measurements.RemoveRuler(ruler);
mapControl1.Measurements.RemoveRuler(ruler)
To delete all rulers from the map, call the RemoveRulers() method.
mapControl1.Measurements.RemoveRulers();
mapControl1.Measurements.RemoveRulers()
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) {
// Convert coordinates to the screen point.
Point startPoint = mapControl1.CoordPointToScreenPoint(e.StartPoint);
MapHitInfo info = mapControl1.CalcHitInfo(startPoint);
if (info.InMapEllipse) {
e.Cancel = true;
}
}
Private Sub Measurements_BeforeMeasurement(ByVal sender As Object, ByVal e As BeforeMeasurementEventArgs)
' Convert coordinates to the screen point.
Dim startPoint As Point = mapControl1.CoordPointToScreenPoint(e.StartPoint)
Dim info As MapHitInfo = mapControl1.CalcHitInfo(startPoint)
If info.InMapEllipse Then
e.Cancel = True
End If
End Sub
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;
}
}
Private Sub Measurements_AfterMeasurement(ByVal sender As Object, ByVal e As AfterMeasurementEventArgs)
Dim ruler1 As MapRuler = e.MapRuler
If ruler1.RulerType Is RulerType.Area Then
e.Cancel = True
End If
End Sub
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.
Use the MeasurementsControl object to specify appearance settings for all map rulers. The following example changes the ruler fill color, opacity, line color, and line thickness.
<Window.Resources>
<Style TargetType="{x:Type dxm:MeasurementsControl}">
<Setter Property="AreaOpacity" Value="0.5"/>
<Setter Property="Fill" Value="OrangeRed"/>
<Setter Property="Stroke" Value="DarkRed"/>
<Setter Property="StrokeThickness" Value="2"/>
</Style>
</Window.Resources>
<Grid>
<!--...-->
<dxm:MapControl x:Name="mapControl1" >
<dxm:MapControl.Measurements>
<dxm:Measurements/>
</dxm:MapControl.Measurements>
<!--...-->
</dxm:MapControl>
</Grid>
Related API members:
|
Name
|
Description
| | --- | --- | |
|
Gets or sets the area ruler opacity.
| |
|
Gets or sets the Brush object used to fill area rulers.
| |
|
Gets or sets the Brush object used to draw ruler lines.
| |
|
Gets or sets the ruler line thickness.
|
Handle the BeforeMeasurement event to change appearance settings for a newly created ruler. Use the e.RulerAppearance property to define the new ruler appearance as follows:
private void Measurements_BeforeMeasurement(object sender, BeforeMeasurementEventArgs e) {
e.RulerAppearance.Stroke = Brushes.DarkRed;
e.RulerAppearance.Fill = Brushes.Red;
e.RulerAppearance.StrokeStyle = new StrokeStyle() { Thickness = 3 };
}
Private Sub Measurements_BeforeMeasurement(ByVal sender As Object, ByVal e As BeforeMeasurementEventArgs)
e.RulerAppearance.Stroke = Brushes.DarkRed
e.RulerAppearance.Fill = Brushes.Red
e.RulerAppearance.StrokeStyle = New StrokeStyle() With {
.Thickness = 3
}
End Sub
You can also call the CreateRuler(RulerType, IList<CoordPoint>, RulerAppearance) method and pass ruler appearance options as a parameter.
The following example changes the ruler’s color and width:
RulerAppearance style = new RulerAppearance();
style.Stroke= Brushes.DarkRed;
style.Fill = Brushes.Red;
style.StrokeStyle = new StrokeStyle() { Thickness = 3};
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
style);
Dim style As RulerAppearance = New RulerAppearance()
style.Stroke = Brushes.DarkRed
style.Fill = Brushes.Red
style.StrokeStyle = New StrokeStyle() With {
.Thickness = 3
}
Dim ruler As MapRuler = mapControl1.Measurements.CreateRuler(RulerType.Distance,
New List(Of CoordPoint)() From {
New GeoPoint(48.864716, 2.349014), ' Paris
New GeoPoint(45.46427, 9.18951), ' Milan
New GeoPoint(48.20849, 16.37208)}, ' Vienna
style)
Object DispatcherObject DependencyObject Freezable MapDependencyObject Measurements
See Also