Map Editor
- 7 minutes to read
The Map Editor is a built-in tool that allows end-users to create and modify map items. They can also rotate map items and resize them using the sizing and rotation handles, and relocate items on the map surface. The Map Editor’s active mode determines which actions a user can perform while editing the map. You can use the corresponding editor panel buttons to switch between the Default, Transform, Edit and Create modes.
Map Editor’s Panel
You can set the MapEditor.ShowEditorPanel property to true at design time using the Properties window to display the Map Editor’s panel.
Use the code below to show the Editor’s panel at runtime.
The following table lists the API members that allow you to manage the Map Editor’s settings:
| Member | Description |
|---|---|
| MapControl.MapEditor | Returns the Map Editor to configure its options. |
| MapEditor | The Map Editor that allows end users to edit map vector items. |
| MapEditor.ShowEditorPanel | Specifies whether the map editor’s panel is displayed. |
| VectorItemsLayer.AllowEditItems | Gets or sets the value specifying whether the map vector layer’s items can be edited. |
The Map Editor’s panel contains the following buttons:
| Button | Description | Visibility |
|---|---|---|
 “Undo” |
Cancels the last action. | EditorPanelOptions.ShowUndoRedoButtons |
 “Redo” |
Restores the last canceled action. | EditorPanelOptions.ShowUndoRedoButtons |
 “Default” |
Enables Default mode. | EditorPanelOptions.ShowDefaultModeButton |
 “Transform” |
Activates Transform mode. | EditorPanelOptions.ShowTransformModeButton |
 “Edit” |
Turns on Edit mode. | EditorPanelOptions.ShowEditModeButton |
 “Add Pushpin” |
Enables “Create Pushpin” mode to create MapPushpin items. | EditorPanelOptions.ShowAddPushpinButton |
 “Add Path” |
Enables “Create Path” mode to create MapPath items. | EditorPanelOptions.ShowAddPathButton |
 “Add Polyline” |
Activates “Create Polyline” mode to create MapPolyline items. | EditorPanelOptions.ShowAddPolylineButton |
 “Add Dot” |
Enables “Create Dot” mode to create MapDot items. | EditorPanelOptions.ShowAddDotButton |
 “Add Ellipse” |
Enables “Create Ellipse” mode to create MapEllipse items. | EditorPanelOptions.ShowAddEllipseButton |
 “Add Rectangle” |
Turns on “Create Rectangle” mode to create MapRectangle items. | EditorPanelOptions.ShowAddRectangleButton |
 “Add Line” |
Enables “Create Line” mode to create MapLine items. | EditorPanelOptions.ShowAddLineButton |
Map Editor Modes
The Map editor provides the following modes that define the available map editing actions:
Default Mode
You can only view the map and cannot edit, create and transform map items when the Default mode is enabled. You can use the
button to enable this mode.Transform Mode
Select the
symbol to enable the Transform mode. This mode allows you to resize and rotate the selected map items using the sizing and rotation handles that appear when selecting items. You can also move map items by dragging them.
Use the MapEditor.SetTransformMode method to enable the Transform mode from code. Refer to the Implementing Custom Map Editor UI section for more information.
Edit Mode
Use the
button to enable the Edit mode. It allows you to move, add, and remove item vertices to change vector map shapes. To edit a map item in this mode, select an item to display its points and perform one of the following actions:Action Animation Description Moving vertices 
Relocate an existing map shape’s point by dragging it to a new position. Adding vertices 
To add a new vertex, hover the mouse pointer over the item’s edge between two neighboring points and click where you want to insert a new vertex. Removing vertices 
Remove a map shape’s point by double-clicking it. Note that you can only edit the following map vector items:
Use the MapEditor.SetEditMode method to turn on Edit mode when implementing a custom map editor UI. Refer to the Implementing Custom Map Editor UI section for more information.
Create Mode
Create mode allows you to add new items to the map. To create a map item, enable the Create mode using buttons on the Editor panel:
You can add dots and pushpins by clicking at the required location. To create a complex map item, sequentially add points to form a map item. The following animation shows how to create a map path:
Use the MapEditor.SetCreateMode method to enable the Create mode when you are developing a custom map editor UI. Refer to the Implementing Custom Map Editor UI section for more information.
Implementing Custom Map Editor UI
This section describes the Map Editor’s API that allows you to design a custom map editing UI.
Switching modes
You can use the methods in the code below to activate a Map Editor mode in code.
private void OnTranformModeItemClick(object sender, ItemClickEventArgs e) {
mapControl.MapEditor.SetTransformMode(MapItemTransform.All);
}
private void OnEditModeItemClick(object sender, ItemClickEventArgs e) {
mapControl.MapEditor.SetEditMode();
}
private void OnCreatePolygonItemClick(object sender, ItemClickEventArgs e) {
mapControl.MapEditor.SetCreateMode(CreatableMapItemKind.Polygon);
}
private void OnDefaultModeItemClick(object sender, ItemClickEventArgs e) {
mapControl.MapEditor.ResetEditMode();
}
The table below lists API members that allow you to manage the Map Editor’s modes.
| Member | Description |
|---|---|
| MapEditor.SetTransformMode | Enables the Map Editor‘s Transformation mode that allows applying the specified transformation to the map items. |
| MapItemTransform | Lists transformations that can be applied to a map item. |
| MapEditor.SetEditMode | Sets the mode that allows end users to edit map items. |
| MapEditor.SetCreateMode | Enables the Map Editor‘s Create mode that allows creating items of the specified type. |
| CreatableMapItemKind | Lists the map item types that the Map Editor can create while it is in the Create mode. |
| MapEditor.ResetEditMode | Resets the Map Editor‘s edit mode. |
Handling the MapItemCreating event
The MapEditor.MapItemCreating event is raised when a user creates a vector item on the map. You can handle this event to customize map item options before it is drawn. For example, the code below shows you how to draw a map item with a specified color.
mapControl.MapEditor.MapItemCreating += OnMapItemCreating;
//...
private void OnMapItemCreating(object sender, MapItemCreatingEventArgs e) {
MapShape shape = e.Item as MapShape;
if(shape != null) {
shape.Fill = Color.Orange;
}
}
The code above uses the following API members:
| Member | Description |
|---|---|
| MapEditor.MapItemCreating | Occurs when a map item’s creation is started. |
| MapItemCreatingEventArgs | Provides data for the MapEditor.MapItemCreating event. |
Map Editor’s Active Layer
You can obtain the map vector layer that stores newly created items using the MapEditor.ActiveLayer property. See the code below to learn how to export active layer items to a KML file.
The code above uses the following API members:
| Member | Description |
|---|---|
| MapEditor.ActiveLayer | Returns the layer that the Map Editor uses to store newly created map items. |
Editing map items
You can edit a map item’s contours by updating, inserting, or removing points. For example, the following code shows how to update map polygon point coordinates:
The following table lists members that allow you to edit a map item’s contours:
| Member | Description |
|---|---|
| MapEditor.UpdateItemPoint | Updates a map item’s contour point coordinates. |
| MapEditor.InsertItemPoint | Inserts a new point to a map item’s contour. |
| MapEditor.RemoveItemPoint | Removes a map item’s contour point. |
Transforming Map Items
You can apply geometric transformations such as rotation, translation and scaling to map items. The code below illustrates how to translate map items.
The following table lists methods that allow you to transform map items:
| Method | Description |
|---|---|
| MapEditor.TranslateItems | Translates items at the specified offset. |
| MapEditor.ScaleItems | Scales the map items. |
| MapEditor.RotateItems | Rotates the items at the specified angle. |
Undo/Redo Prior Operations
The Map control stores all actions performed by a user while editing a map. The MapEditor.Undo method allows you to reverse the most recent action, while the MapEditor.Redo method enables you to return the last canceled action. Before calling the Undo/Redo methods, check whether these operations can be performed using the MapEditor.CanUndo/MapEditor.CanRedo properties. Use the MapEditor.ClearSavedActions method to clear the saved actions collection. The Map control does not save user actions if you set the MapEditor.AllowSaveActions property to false.