Measuring Class Reference

Handles built-in distance and area measuring on the map. More...

Collaboration diagram for Measuring:
Collaboration graph

Public Member Functions

void Clear ()
 Clears all measurements. More...
 
bool Deserialize (string state)
 Restores the state of object from the string. More...
 
void FinishMeasuring ()
 Finishes measuring. The measured path won't be cleared from map immediately. More...
 
double get_AreaWithClosingVertex (double lastPointProjX, double lastPointProjY)
 Gets an area within the path polygon including an additional point (typically the current position of mouse cursor). More...
 
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specific error code. More...
 
bool get_PointXY (int PointIndex, out double x, out double y)
 Gets coordinates of specified point in the path. More...
 
string Serialize ()
 Saves the state of the class to the string More...
 
bool UndoPoint ()
 Undoes entering of the last point in the path. More...
 

Properties

tkAngleFormat AngleFormat [get, set]
 Gets or sets angle format to be used to display bearing. More...
 
int AnglePrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display bearing. More...
 
double Area [get]
 Gets the measured area (in square meters if WGS84 compatible projection is set for map and in current square map units otherwise). More...
 
int AreaPrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display area. More...
 
tkAreaDisplayMode AreaUnits [get, set]
 Gets or sets the area units to be displayed. More...
 
tkBearingType BearingType [get, set]
 Gets or sets type of the bearing to be display for line segments. More...
 
uint FillColor [get, set]
 Gets or sets fill color for polygon display. More...
 
byte FillTransparency [get, set]
 Gets or sets fill transparency for polygon display. More...
 
ICallback GlobalCallback [get, set]
 Gets or sets a Callback object which handles progress and error messages. More...
 
bool IsEmpty [get]
 Returns true if measured path contains at least one point. More...
 
bool IsStopped [get]
 Gets value indicating whether measurement was stopped. More...
 
bool IsUsingEllipsoid [get]
 Gets a value indicating whether calculations are performed taking into account the shape of Earth (when map projection is defined), or on 2D plane (Euclidean geometry). More...
 
string Key [get, set]
 A text string associated with object. Any value can be stored by developer in this property. More...
 
int LastErrorCode [get]
 Gets the code of last error which took place inside this object. More...
 
double Length [get]
 Gets the length of measured path (in meters if WGS84 compatible projection is set for map and in current map units otherwise). More...
 
int LengthPrecision [get, set]
 Gets or sets the number of decimal degrees to be used to display length. More...
 
tkLengthDisplayMode LengthUnits [get, set]
 Gets or sets type of the length units to be displayed. More...
 
uint LineColor [get, set]
 Gets or sets line color to display measured path. More...
 
tkDashStyle LineStyle [get, set]
 Gets or sets line style to display measured path. More...
 
float LineWidth [get, set]
 Gets or sets line width to display measured path. More...
 
tkMeasuringType MeasuringType [get, set]
 The type of measurement, either distance or area. More...
 
bool Persistent [get, set]
 Gets or sets a value indicating whether the finished path will be preserved on map when map cursor changes to something other than cmMeasure. More...
 
int PointCount [get]
 Gets number of points in the measured path. More...
 
bool PointLabelsVisible [get, set]
 Gets or sets a value indicating whether labels with indices of points will be visible near the vertices. More...
 
bool PointsVisible [get, set]
 Gets or sets a value indicating whether vertices of the measured path will be visible. More...
 
bool ShowBearing [get, set]
 Gets or sets a value indicating whether bearing of the line segments will be displayed. More...
 
bool ShowLength [get, set]
 Gets or sets a value indicating whether length of the line segments will be displayed. More...
 
bool ShowTotalLength [get, set]
 Gets or sets a value indicating whether accumulated length will be shown in brackets for each line segment. More...
 
tkUndoShortcut UndoButton [get, set]
 Gets or sets the type of user input to be used to undo the last point of the measured path. More...
 

Detailed Description

Handles built-in distance and area measuring on the map.

To start measuring set AxMap.CursorMode to cmMeasure. Then the following buttons can be used.

  • Left-click to add new points;
  • Right-click to undo the last point;
  • Double-click to finish the path;
  • Ctrl-click on one of the preceding vertices in distance mode, to close polygon and measure its area;
  • Shift-click to snap to the closest vertex of shapefile.

There are 2 modes of measuring:

  • distance (a path consisting of a number of points can be measured);
  • area (area of single closed polygon can be measured);

To toggle to area measuring mode:

axMap1.Measuring.MeasuringType= tkMeasuringType.MeasureArea;

Measurements will be performed:

  • if geoprojection is not empty - by converting coordinates to decimal degrees and using precise calculation on ellipsoid (GeographicLib);
  • otherwise - planar calculations using Euclidean geometry and AxMap.MapUnits property;

Current implementation support only metric units (meters, kilometers). The abbreviated name of units can be changed to a localized one using GlobalSettings.set_LocalizedString:

gs.set_LocalizedString(tkLocalizedStrings.lsKilometers) = "ΠΊΠΌ";

Custom logic to be executed during measuring can be added by handling AxMap.MeasuringChanged event. Area and length of measured path are available via Measuring.Length and Measuring.Area (in meters and square meters respectively; or map units if no projection is set). Measured points can be accessed using Measuring.get_PointXY and Measuring.PointCount. Use AxMap.ProjToDegrees to get latitude, longitude in decimal degrees.

axMap1.MeasuringChanged += (s, e) =>
{
if (e.action == tkMeasuringAction.PointAdded)
{
if (axMap1.Measuring.IsUsingEllipsoid)
{
Debug.WriteLine("Calculations on ellipsoid.");
Debug.WriteLine("Area: " + axMap1.Measuring.Area + "sq.m");
Debug.WriteLine("Distance: " + axMap1.Measuring.Length + "m");
}
else
{
Debug.WriteLine("Calculations on plane.");
Debug.WriteLine("Area: " + axMap1.Measuring.Area + "map units");
Debug.WriteLine("Distance: " + axMap1.Measuring.Length + "map units");
}
double x, y;
Debug.WriteLine("Measured points (in map units.): " + axMap1.Measuring.PointCount);
for (int i = 0; i < axMap1.Measuring.PointCount; i++)
{
if (axMap1.Measuring.get_PointXY(i, out x, out y))
{
Debug.WriteLine("x={0}; y={1}", x, y);
}
}
}
};
New API 4.9.1:
Added in version 4.9.1

Member Function Documentation

◆ Clear()

void Measuring.Clear ( )

Clears all measurements.

◆ Deserialize()

bool Measuring.Deserialize ( string  state)

Restores the state of object from the string.

Parameters
stateA string generated by Measuring.Serialize() method
Returns
True on success.
New API 4.9.3:
Added in version 4.9.3

◆ FinishMeasuring()

void Measuring.FinishMeasuring ( )

Finishes measuring. The measured path won't be cleared from map immediately.

◆ get_AreaWithClosingVertex()

double Measuring.get_AreaWithClosingVertex ( double  lastPointProjX,
double  lastPointProjY 
)

Gets an area within the path polygon including an additional point (typically the current position of mouse cursor).

Parameters
lastPointProjXX coordinate of the last point (in map coordinates).
lastPointProjYY coordinate of the last point (in map coordinates).
Returns
Area in square meters if WGS84 compatible projection is set for map and in current square map units otherwise.

◆ get_ErrorMsg()

string Measuring.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specific error code.

Parameters
ErrorCodeThe error code returned by LastErrorCode property.
Returns
String with the description.
New API 4.9.3:
Added in version 4.9.3

◆ get_PointXY()

bool Measuring.get_PointXY ( int  PointIndex,
out double  x,
out double  y 
)

Gets coordinates of specified point in the path.

Parameters
PointIndexIndex of a point.
xX coordinate of the point in map coordinates.
yY coordinate of the point in map coordinates.
Returns
True on success.

◆ Serialize()

string Measuring.Serialize ( )

Saves the state of the class to the string

Returns
A string with the state or an empty string on failure.
New API 4.9.3:
Added in version 4.9.3

◆ UndoPoint()

bool Measuring.UndoPoint ( )

Undoes entering of the last point in the path.

Returns
True on success.

Property Documentation

◆ AngleFormat

tkAngleFormat Measuring.AngleFormat
getset

Gets or sets angle format to be used to display bearing.

New API 4.9.3:
Added in version 4.9.3

◆ AnglePrecision

int Measuring.AnglePrecision
getset

Gets or sets the number of decimal degrees to be used to display bearing.

This setting is not used when AngleFormat is set to minutes or seconds.

New API 4.9.3:
Added in version 4.9.3

◆ Area

double Measuring.Area
get

Gets the measured area (in square meters if WGS84 compatible projection is set for map and in current square map units otherwise).

◆ AreaPrecision

int Measuring.AreaPrecision
getset

Gets or sets the number of decimal degrees to be used to display area.

New API 4.9.3:
Added in version 4.9.3

◆ AreaUnits

tkAreaDisplayMode Measuring.AreaUnits
getset

Gets or sets the area units to be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ BearingType

tkBearingType Measuring.BearingType
getset

Gets or sets type of the bearing to be display for line segments.

New API 4.9.3:
Added in version 4.9.3

◆ FillColor

uint Measuring.FillColor
getset

Gets or sets fill color for polygon display.

New API 4.9.3:
Added in version 4.9.3

◆ FillTransparency

byte Measuring.FillTransparency
getset

Gets or sets fill transparency for polygon display.

New API 4.9.3:
Added in version 4.9.3

◆ GlobalCallback

ICallback Measuring.GlobalCallback
getset

Gets or sets a Callback object which handles progress and error messages.

New API 4.9.3:
Added in version 4.9.3
Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ IsEmpty

bool Measuring.IsEmpty
get

Returns true if measured path contains at least one point.

New API 4.9.3:
Added in version 4.9.3

◆ IsStopped

bool Measuring.IsStopped
get

Gets value indicating whether measurement was stopped.

◆ IsUsingEllipsoid

bool Measuring.IsUsingEllipsoid
get

Gets a value indicating whether calculations are performed taking into account the shape of Earth (when map projection is defined), or on 2D plane (Euclidean geometry).

New API 4.9.1:
Added in version 4.9.1

◆ Key

string Measuring.Key
getset

A text string associated with object. Any value can be stored by developer in this property.

New API 4.9.3:
Added in version 4.9.3

◆ LastErrorCode

int Measuring.LastErrorCode
get

Gets the code of last error which took place inside this object.

New API 4.9.3:
Added in version 4.9.3

◆ Length

double Measuring.Length
get

Gets the length of measured path (in meters if WGS84 compatible projection is set for map and in current map units otherwise).

◆ LengthPrecision

int Measuring.LengthPrecision
getset

Gets or sets the number of decimal degrees to be used to display length.

New API 4.9.3:
Added in version 4.9.3

◆ LengthUnits

tkLengthDisplayMode Measuring.LengthUnits
getset

Gets or sets type of the length units to be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ LineColor

uint Measuring.LineColor
getset

Gets or sets line color to display measured path.

New API 4.9.3:
Added in version 4.9.3

◆ LineStyle

tkDashStyle Measuring.LineStyle
getset

Gets or sets line style to display measured path.

New API 4.9.3:
Added in version 4.9.3

◆ LineWidth

float Measuring.LineWidth
getset

Gets or sets line width to display measured path.

New API 4.9.3:
Added in version 4.9.3

◆ MeasuringType

tkMeasuringType Measuring.MeasuringType
getset

The type of measurement, either distance or area.

◆ Persistent

bool Measuring.Persistent
getset

Gets or sets a value indicating whether the finished path will be preserved on map when map cursor changes to something other than cmMeasure.

◆ PointCount

int Measuring.PointCount
get

Gets number of points in the measured path.

◆ PointLabelsVisible

bool Measuring.PointLabelsVisible
getset

Gets or sets a value indicating whether labels with indices of points will be visible near the vertices.

New API 4.9.3:
Added in version 4.9.3

◆ PointsVisible

bool Measuring.PointsVisible
getset

Gets or sets a value indicating whether vertices of the measured path will be visible.

New API 4.9.3:
Added in version 4.9.3

◆ ShowBearing

bool Measuring.ShowBearing
getset

Gets or sets a value indicating whether bearing of the line segments will be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ ShowLength

bool Measuring.ShowLength
getset

Gets or sets a value indicating whether length of the line segments will be displayed.

New API 4.9.3:
Added in version 4.9.3

◆ ShowTotalLength

bool Measuring.ShowTotalLength
getset

Gets or sets a value indicating whether accumulated length will be shown in brackets for each line segment.

New API 4.9.3:
Added in version 4.9.3

◆ UndoButton

tkUndoShortcut Measuring.UndoButton
getset

Gets or sets the type of user input to be used to undo the last point of the measured path.

New API 4.9.3:
Added in version 4.9.3