This guide explains how you can interactively edit features on a Map, and integrate this capability in an IController.

Overview

The CPillar Editor translates input events to edit actions that are applied to a configured selection of features. For these features, the editor retrieves and visualizes a set of handles. The handles are linked to edit actions that perform the actual feature modification.

Programmatically creating geometries

link: If you want to edit geometries through the API instead of editing them interactively on the map, see the related article on geometries.

Editing Features and Geometries

Base concepts

To understand how features or geometries are edited, a few concepts need to be explained.

IFeatureHandlesProvider

Observable feature and geometries

To make it easier to observe the changes that are happening to an edited feature or geometry, the Observable<T> class is used in the edit API:

This class stores a Feature or Geometry that can change during editing. It allows you to get the current state, and observe changes to the Feature or Geometry. This for example allows you to update the handles of an object that is being edited.

IEditHandle

IEditHandle is a visual component on the map that triggers concrete edit actions based on input events. An example is a point handle that is visualized as an icon, and that you can drag around, click on, or touch press.

An edit handle triggers a change to the feature or geometry by notifying that it has changed. A point handle will for example send a notification that it has moved. Based on that notification, the IEditHandles can modify a feature or geometry.

edit handle
Figure 1. Editing a polyline ring using an edit handle

Example IEditHandle implementations are:

IEditHandles

IEditHandles is a collection of IEditHandle instances that is created for a specific feature or geometry.

This collection must update its own handles whenever the edited object changes. The edited object can change in two cases:

In both cases, the observable feature or geometry will notify the IEditHandles that it has changed. Triggered by this notification, IEditHandles can update its list of handles.

IEditHandles provider

IFeatureHandlesProvider and IGeometryHandlesProvider can create an IEditHandles instance for a given feature or geometry. These classes are typically stateless, and can be reused for more than one feature or geometry.

Editor

Editor determines which features are edited, and delegates its input events to the edit handles for that feature. It also provides a layer that can visualize the used handles on the Map.

Handle interactions

The following diagram shows the most common interactions between the different concepts:

Handle interactions

Handle interaction is wired together using callbacks and observers:

Configuring feature editing

To configure feature editing, you can use these classes:

Constraining geometries during editing

The editing API has out of the box support for geometry constraints. Most IGeometryHandlesProvider implementations allow you to configure a constraint that is applied during editing. See the related article for more information.

Integrating an editor with a controller

You can use the Editor class as a part of an IController implementation. To integrate the feature editor:

Examples of customizations

The following articles and tutorials give examples of how you can customize the edit behavior: