Luciad Developer Platform

Overview

The CPillar EditorEditorEditor translates input eventsinput eventsinput events to edit actions that are applied to a configuredconfiguredconfigured selection of features. For these features, the editor retrievesretrievesretrieves and visualizesvisualizesvisualizes a set of handleshandleshandles. The handles are linked to edit actions that perform the actual feature modificationfeature modificationfeature 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.

Observable feature and geometries

To make it easier to observe the changes that are happening to an edited feature or geometry, the Observable<T>Observable<T>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

IEditHandleIEditHandleIEditHandle is a visualvisualvisual component on the map that triggers concrete edit actions based on input eventsinput eventsinput 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 IEditHandlesIEditHandlesIEditHandles can modify a feature or geometry.

Figure 1. Editing a polyline ring using an edit handle

Example IEditHandleIEditHandleIEditHandle implementations are:

PointEditHandlePointEditHandlePointEditHandle: This handle is visualized by a point icon. It allows you to drag it around, click, or touch press it. It uses IPointEditActionIPointEditActionIPointEditAction to signal that an action is performed.
TranslateEditHandleTranslateEditHandleTranslateEditHandle: This handle is either not visualized, or visualized by a shadow geometryshadow geometryshadow geometry. It allows you to drag it around, and translate an entire geometry. It uses ITranslateEditActionITranslateEditActionITranslateEditAction to signal that an action is performed.

IEditHandles

IEditHandlesIEditHandlesIEditHandles is a collection of IEditHandleIEditHandleIEditHandle 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 changeexternal changeexternal change to the feature or geometry, for example originating from an IFeatureModelIFeatureModelIFeatureModel event

In both cases, the observableobservableobservable featurefeaturefeature or geometrygeometrygeometry will notify the IEditHandlesIEditHandlesIEditHandles that it has changed. Triggered by this notification, IEditHandlesIEditHandlesIEditHandles can update its list of handles.

IEditHandles provider

IFeatureHandlesProviderIFeatureHandlesProviderIFeatureHandlesProvider and IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider can create an IEditHandlesIEditHandlesIEditHandles instance for a given feature or geometry. These classes are typically stateless, and can be reused for more than one feature or geometry.

Example IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider implementations:

PointHandlesProviderPointHandlesProviderPointHandlesProvider: provides handles to edit Point geometries
PolylineHandlesProviderPolylineHandlesProviderPolylineHandlesProvider: provides handles to edit Polyline geometries
PolylineRingHandlesProviderPolylineRingHandlesProviderPolylineRingHandlesProvider: provides handles to edit PolylineRing geometries
PatchHandlesProviderPatchHandlesProviderPatchHandlesProvider: provides handles to edit patches. This class doesn’t provide any handles itself, but it asks another IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider to provide handles for its base geometry, for example a PolylineRingHandlesProviderPolylineRingHandlesProviderPolylineRingHandlesProvider.
PolygonHandlesProviderPolygonHandlesProviderPolygonHandlesProvider: provides handles to edit polygons. This class doesn’t provide any handles itself, but it asks another IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider to provide handles for its exterior and interior rings, for example a PolylineRingHandlesProviderPolylineRingHandlesProviderPolylineRingHandlesProvider.

Example IFeatureHandlesProviderIFeatureHandlesProviderIFeatureHandlesProvider implementations:

FeatureHandlesProviderFeatureHandlesProviderFeatureHandlesProvider: provides handles to edit a Feature by extractingextractingextracting a geometry from the feature and using an IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider to provide handles for that geometry. After the geometry is modified, it is used to create modified Feature.

Editor

EditorEditorEditor determines which features are edited, and delegates its input eventsinput eventsinput events to the edit handlesedit handlesedit handles for that feature. It also provides a layerprovides a layerprovides 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 interaction is wired together using callbacks and observers:

IEditHandleIEditHandleIEditHandle implementations typically use an action to notify IEditHandlesIEditHandlesIEditHandles that they have been modified. Based on this callback, the IEditHandlesIEditHandlesIEditHandles implementation can modify the feature or geometry. An example is PointEditHandlePointEditHandlePointEditHandle which uses IPointEditActionIPointEditActionIPointEditAction to communicate that the handle has been interacted with.
IFeatureEditCallbackIFeatureEditCallbackIFeatureEditCallback or IGeometryEditCallbackIGeometryEditCallbackIGeometryEditCallback notify EditorEditorEditor or other IEditHandlesIEditHandlesIEditHandles that the feature or geometry has been modified.
ObservableObservableObservable of Feature and Geometry send notifications when a feature or geometry has been modified. This allows the IEditHandlesIEditHandlesIEditHandles to update its handles. The change can be:
- external change: for example based on an event originating from IFeatureModelIFeatureModelIFeatureModel
- editing changes: triggered by EditorEditorEditor when receiving a callback from IFeatureEditCallbackIFeatureEditCallbackIFeatureEditCallback or IGeometryEditCallbackIGeometryEditCallbackIGeometryEditCallback

Configuring feature editing

To configure feature editing, you can use these classes:

Editor::Builder: to configure the edit candidatesconfigure the edit candidatesconfigure the edit candidates used.
FeatureLayer::Builder: to enable or disableenable or disableenable or disable feature editing for a layer and to define an edit configurationedit configurationedit configuration. With this edit configuration, you can:
- Configure the handlesConfigure the handlesConfigure the handles used to edit a Feature.
- ConfigureConfigureConfigure when the IFeatureModelIFeatureModelIFeatureModel is updated by the Editor.
- DisableDisableDisable editing for a single feature
- Provide the geometryProvide the geometryProvide the geometry used for editing a a Feature, and specify how to apply edited geometries to the Feature. This provider is mainly used by the default feature handles providerfeature handles providerfeature handles provider.

Constraining geometries during editing

The editing API has out of the box support for geometry constraints. Most IGeometryHandlesProviderIGeometryHandlesProviderIGeometryHandlesProvider 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 EditorEditorEditor class as a part of an IControllerIControllerIController implementation. To integrate the feature editor:

Delegate input eventsinput eventsinput 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 or touch events if there is no Feature at the position of those events. The controller can still use these events to navigate the map, though.
Add the handle layerhandle layerhandle layer to the controller’s layer listlayer listlayer list. You need to do that so that the map can visualize the edit handles.
Change the mouse cursormouse cursormouse cursor at the appropriate momentappropriate momentappropriate moment.

Examples of customizations

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

How to use a custom edit configuration.
How to change the geometry that is used to edit a Feature.
How to make a layer non-editable.
How to change the default editing behavior.
How to disable a handle.
This tutorial shows you how to customize existing handles provider.
This tutorial shows you how you can extra handles to an existing handles provider.
This tutorial shows how you can implement your own handles provider.

Editing features on a Map