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 following classes are used in the edit API:

The classes store 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 or click on.

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:

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:

  • By an edit action performed by one of its handles.

  • By an external change to the feature or geometry, for example originating from an IFeatureModel event

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.

Example IGeometryHandlesProvider implementations:

Example IFeatureHandlesProvider implementations:

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:

  • Delegate input events. The editor may or may not consume those events. Based on that information, the controller can decide to ignore the event, or use it for something else. For example, an editor can ignore mouse drag events when there is no Feature under the mouse cursor. The controller can still use these events to navigate the map, though.

  • Add the handle layer to the controller’s layer list. You need to do that so that the map can visualize the edit handles.

  • Change the mouse cursor at the appropriate moment.

Examples of customizations

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