The ArcGIS Runtime SDK for .NET enables developers to build connected or offline Windows apps that provide end users with focused editing workflows across native Microsoft platforms (Desktop, Store, Phone). A common developer requirement is to implement a measure tool for calculating distances and areas based on a geometric shape sketched by a user who is interacting with the map. The Editor provides support for drawing shapes that aid in building a functional measure tool.
This blog post aims to help you build your own measure tool by introducing the following Editor concepts:
I. Sketching with the Editor.
II. Editor vs. Map Navigation.
III. Customizing Editor Symbology.
IV. Tracking Editor’s progress.
Two universal apps (Simple and Advanced measure tool) will be used to provide examples that help clarify these concepts; these apps target both Windows Store and Windows Phone platforms and illustrate that the ArcGIS Runtime SDK for .NET implementation helps facilitate creating shared logic between apps. The Simple measure tool will cover concepts from the first two sections, while the Advanced measure tool will build on those concepts and cover sections III and IV. Demo code can be obtained here.
I – Sketching with the Editor.
In order to measure distance and area on the map, you can work with the Editor to sketch geometries as graphics on the topmost layer of the map. The MapView control maintains a Graphics overlay collection which can be used to create and display these geometries on a temporary basis. The MapView control also provides convenient access to an Editor instance that will support geometry creation via the RequestShapeAsync method. Calling RequestShapeAsync will return geometry based on a specified DrawShape parameter.
Tip: RequestShapeAsync is an awaitable task that uses the (TAP) Task-based asynchronous pattern.
The following code puts the map in sketch mode and returns a polyline geometry upon completion of the asynchronous task.
Example DrawShape parameters and the geometry types that are returned based on a user sketch are listed in the following table:
|
DrawShape Parameter |
Return Geometry |
| Point | MapPoint |
| Polyline, LineSegment, Freehand | Polyline |
| Polygon, Triangle, RectangleCircle, Ellipse, Arrow | Polygon |
| Envelope | Envelope |
Once a geometry is returned, it can be analyzed using the GeometryEngine to compute area and length (including Geodesic calculations).
II – Editor vs. Map Navigation.
While digitizing a new geometry for measurement, you may need to interact with the map. For example, you may need to change the current map position by panning to a new location or zooming to an area of interest.
It is helpful to gain some familiarity with some of the Editor properties and commands that can be used to distinguish whether or not the Editor needs to respond to a platform event. Some of the key properties and commands are listed in the following table:
| Name | Property / Command | Use When: |
| IsActive | Property | Indicate when the Editor is in the middle of a sketch or edit |
| IsSuspended | Property | Indicate when the Editor has been suppressed from responding to a platform event property |
| Cancel | Command | Deactivate the Editor without returning geometry |
| Complete | Command | Allow the Editor to return geometry before it is deactivated |
The following code example illustrates how to enable a Suspend button (based on the IsActive property) and a Complete command.
III Customizing Editor Symbology.
The following image shows the default symbology used by the edit tools of the Editor:
There are various use cases for overriding the Editor symbology:
- Display incremental distances during measure
- Number vertices to indicate their position in the collection
- De-emphasize the mid-vertex
- Disregard vertex selection state.
In addition, there are several approaches for providing custom symbology based on the application requirements.
| Approach | Use When: |
| Pass a symbol to RequestShapeAsync() | Overriding the symbol used while sketching a geometry shape. |
| Use EditorConfiguration | Defining a new symbol for an edit tool. |
| Sub-class Editor and override the OnGenerateSymbol method | Defining a new symbol for an edit tool that requires a CompositeSymbol |
Tip: EditorConfiguration is useful for modifying both symbology and general editor capabilities at the same time.
The following example overrides the symbol for the requested geometry shape:
The next example uses EditorConfiguration to provide an edit tool with a symbol that matches the required geometry type:
The final code example demonstrates sub-classing the Editor and overriding the OnGenerateSymbol method:
IV – Tracking Editor’s progress.
The third optional parameter of RequestShapeAsync can be used to track sketch progress; this is useful when you need a measure tool to calculate lengths between intermediate segments as you digitize a geometry. This parameter (of type IProgress<GeometryEditStatus>) is responsible for capturing various changes to vertices (add, move or delete).
Tapping into progress reporting requires two steps:
- Declare an instance of Progress<GeometryEditStatus>, which accepts an Action delegate that takes the same parameter type
- Pass the Progress instance a parameter to RequestShapeAsync.
The following code illustrates the two steps that are needed to start tracking:
The GeometryEditStatus delegate is used to capture the current state of geometry through its NewGeometry property.
GeometryEditStatus also contains other useful information pertaining to geometry and vertex updates:
| Property | Use When: |
| GeometryEditAction | Determining whether a geometry was rotated, scaled, moved, or a vertex was added, moved, or deleted |
| OldGeometry | Getting the geometry before an edit. |
| OldVertex | Getting the removed vertex or the vertex prior to it being moved. |
| NewVertex | Getting the added vertex or the vertex after it was moved. |
In conclusion, the Editor exposes properties, commands, configuration parameters and override methods for customization and progress reporting. All of these capabilities in combination enable you to quickly sketch geometries and perform necessary calculations to implement robust measurement and analysis capabilities.
To gain familiarity with other general editing workflows, download the ArcGIS Runtime SDK for .NET samples from GitHub, or take advantage of the newly enhanced ability to search and browse the samples with the ArcGIS for Developers site.
If you are interested in a seeing another example of a measure tool that calculates both area and distance as a component of a more complex implementation, check out the ArcGIS Portal Viewer for .NET. This application has a rich set of functionality, illustrating MVVM patterns and tight integration with the ArcGIS Platform.
As always the development team welcomes your feedback and would like to hear examples of how you successfully created custom editing solutions using the ArcGIS Runtime SDK for .NET!
Article Discussion: