Back to Devexpress

Map Editor

windowsforms-120215-controls-and-libraries-map-control-end-user-features-map-editor.md

latest23.0 KB
Original Source

Map Editor

  • Mar 21, 2023
  • 10 minutes to read

The Map Editor allows users to create and modify map items. They can rotate map items and resize them with the sizing and rotation handles, and relocate items on the map surface. The Map Editor’s active mode determines the actions a user can perform. The editor panel buttons allow users to switch between Default, Transform, Edit and Create modes.

Map Editor Panel

You can set the MapEditor.ShowEditorPanel property to true at design time in the Properties window to display the Map Editor’s panel.

Use the code below to show the Editor’s panel at runtime.

csharp
mapControl.MapEditor.ShowEditorPanel = true;
vb
mapControl.MapEditor.ShowEditorPanel = true

The following table lists the API members that allow you to manage the Map Editor’s settings:

MemberDescription
MapControl.MapEditorReturns the Map Editor to configure its options.
MapEditorThe Map Editor that allows end users to edit map vector items.
MapEditor.ShowEditorPanelSpecifies whether the map editor’s panel is displayed.
VectorItemsLayer.AllowEditItemsGets or sets the value that specifies whether a user can edit the map vector layer’s items.

The Map Editor’s panel contains the following buttons:

ButtonDescriptionVisibility
“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 edit actions:

Default Mode

You can only view the map and cannot edit, create and transform map items in Default mode. You can use the button to enable this mode.

Transform Mode

Select to enable Transform mode. Use the sizing and rotation handles that appear when you select items to resize and rotate the selected map items, and drag items to move them.

Use the MapEditor.SetTransformMode method to enable the Transform mode from code. Refer to the Map Editor API section for more information.

Edit Mode

Use the button to enable Edit mode. In this mode, you can 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:

ActionAnimationDescription
Move verticesDrag a map shape’s point to a new position to relocate the point.
Add verticesTo add a new vertex, hover the mouse pointer over the item’s edge between two points and click where you want to insert a new vertex.
Remove verticesDouble-click a map shape’s point to remove it.

Note that you can only edit the following map vector items:

Use the MapEditor.SetEditMode method to enable Edit mode when you implement a custom map editor UI. Refer to the Map Editor API section for more information.

Create Mode

Create mode allows you to add new items to the map. Use the following buttons on the Editor panel to enable the Create mode:

Click the location where you want to add dots and pushpins.

To add rectangles and ellipses, click a map to add start point. Drag the pointer, click again to add an end point and finish item.

To create a complex map item, sequentially add points to form a map item. Press the Enter key or double-click the item to finish its creation. The following animation shows how to create a map path:

Use the MapEditor.SetCreateMode method to enable the Create mode when you develop a custom map editor UI. Refer to the Map Editor API section for more information.

Map Editor API

This section describes the Map Editor’s API that allows you to design a custom map edit UI.

Switch modes

You can use the methods below to change a Map Editor mode programmatically:

csharp
private void OnTransformModeItemClick(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();
}
vb
Private Sub OnTransformModeItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    mapControl.MapEditor.SetTransformMode(MapItemTransform.All)
End Sub
Private Sub OnEditModeItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    mapControl.MapEditor.SetEditMode()
End Sub
Private Sub OnCreatePolygonItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    mapControl.MapEditor.SetCreateMode(CreatableMapItemKind.Polygon)
End Sub
Private Sub OnDefaultModeItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    mapControl.MapEditor.ResetEditMode()
End Sub

The table below lists API members that allow you to manage the Map Editor’s modes.

MemberDescription
MapEditor.SetTransformModeEnables Transformation mode. This mode allows you to apply the specified transformation to the map items.
MapItemTransformLists transformations that can be applied to a map item.
MapEditor.SetEditModeEnables Edit mode. This mode allows end users to edit map items.
MapEditor.SetCreateModeEnables Create mode. This mode allows end users to create items of the specified type.
CreatableMapItemKindLists the map item types that the Map Editor can create while it is in the Create mode.
MapEditor.ResetEditModeResets the Map Editor‘s edit mode (sets the EditMode property to None).

Handle 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.

csharp
mapControl.MapEditor.MapItemCreating += OnMapItemCreating;
//...
private void OnMapItemCreating(object sender, MapItemCreatingEventArgs e) {
    MapShape shape = e.Item as MapShape;
    if(shape != null) {
        shape.Fill = Color.Orange;
    }
}
vb
AddHandler mapControl.MapEditor.MapItemCreating, AddressOf OnMapItemCreating
'...
Private Sub OnMapItemCreating(ByVal sender As Object, ByVal e As MapItemCreatingEventArgs)
    Dim shape As MapShape = TryCast(e.Item, MapShape)
    If shape IsNot Nothing Then
        shape.Fill = Color.Orange
    End If
End Sub

If necessary, use the MapItemCreatingEventArgs.Cancel property to interrupt a map item’s creation.

Handle the MapItemEditing and MapItemEdited events

The Map Editor provides two events that allow you to track users’ actions while they edit map items:

csharp
mapControl.MapEditor.MapItemEditing += OnMapItemEditing;
mapControl.MapEditor.MapItemEdited += OnMapItemEdited;
// ...
private void OnMapItemEditing(object sender, MapItemEditingEventArgs e) {
    if(e.Action == MapEditorAction.PointUpdate) {
        Cursor.Current = Cursors.Hand;
    }
}
private void OnMapItemEdited(object sender, MapItemEditedEventArgs e) {
        MessageBox.Show("Action: " + e.Action);
}
vb
AddHandler mapControl.MapEditor.MapItemEditing, AddressOf OnMapItemEditing
AddHandler mapControl.MapEditor.MapItemEdited, AddressOf OnMapItemEdited  
' ...    
Private Sub OnMapItemEditing(ByVal sender As Object, ByVal e As MapItemEditingEventArgs)
    If (e.Action = MapEditorAction.PointUpdate) Then
        Cursor.Current = Cursors.Hand
    End If    
End Sub
Private Sub OnMapItemEdited(ByVal sender As Object, ByVal e As MapItemEditedEventArgs)
    MessageBox.Show(("Action: " + e.Action))
End Sub

Access Active Layer and Its Items

Use the MapEditor.ActiveLayer property to obtain the map vector layer that stores newly created items.

How to Export the Layer with Newly Created Items

The code below exports active layer items to a KML file.

csharp
mapControl.MapEditor.ActiveLayer.ExportToKml(filePath);
vb
mapControl.MapEditor.ActiveLayer.ExportToKml(filePath)

How to Access Newly Created Items and Their Coordinates

The following code paints newly created paths and uses path vertex coordinates to create dots when a user clicks a button:

csharp
private void simpleButton1_Click(object sender, EventArgs e) {
    VectorItemsLayer activeLayer = mapControl1.MapEditor.ActiveLayer as VectorItemsLayer;
    if (activeLayer != null) {
        MapItemStorage activeLayerData = activeLayer.Data as MapItemStorage;
        if (activeLayerData != null) {
            // Create a new layer for dots:
            VectorItemsLayer dotLayer = new VectorItemsLayer();
            MapItemStorage storage = new MapItemStorage();
            dotLayer.Data = storage;
            mapControl1.Layers.Add(dotLayer);
            // Access active layer items:
            foreach (MapPath item in activeLayerData.Items) {
                item.Fill = Color.Coral;
                foreach (MapPathSegment segment in item.Segments) {
                    foreach (GeoPoint point in segment.Points) {                            
                            storage.Items.Add(new MapDot() { Location = point, Size = 18, Stroke = Color.Blue });
                    }
                }

            }
        }
    }
}
vb
Private Sub simpleButton1_Click(ByVal sender As Object, ByVal e As EventArgs)
    Dim activeLayer As VectorItemsLayer = TryCast(mapControl1.MapEditor.ActiveLayer, VectorItemsLayer)

    If activeLayer IsNot Nothing Then
        Dim activeLayerData As MapItemStorage = TryCast(activeLayer.Data, MapItemStorage)

        If activeLayerData IsNot Nothing Then
            ' Create a new layer for dots:
            Dim dotLayer As VectorItemsLayer = New VectorItemsLayer()
            Dim storage As MapItemStorage = New MapItemStorage()
            dotLayer.Data = storage
            mapControl1.Layers.Add(dotLayer)
            ' Access active layer items:
            For Each item As MapPath In activeLayerData.Items
                item.Fill = Color.Coral

                For Each segment As MapPathSegment In item.Segments

                    For Each point As GeoPoint In segment.Points
                        storage.Items.Add(New MapDot() With {
                            .Location = point,
                            .Size = 18,
                            .Stroke = Color.Blue
                        })
                    Next
                Next
            Next
        End If
    End If
End Sub

Edit Map Items

You can update, insert, or remove points to edit a map item’s contours. For example, the following code shows how to update map polygon point coordinates:

csharp
mapControl.MapEditor.UpdateItemPoint(mapPolygon, new GeoPoint(57.1, 16.5), 0, 0);
vb
mapControl.MapEditor.UpdateItemPoint(mapPolygon, New GeoPoint(57.1, 16.5), 0, 0)

The following table lists members that allow you to edit a map item’s contours:

MemberDescription
MapEditor.UpdateItemPointUpdates a map item’s contour point coordinates.
MapEditor.InsertItemPointInserts a new point to a map item’s contour.
MapEditor.RemoveItemPointRemoves a map item’s contour point.

Transform Map Items

You can apply geometric transformations such as rotation, translation and scaling to map items. The code translates map items:

csharp
mapControl.MapEditor.TranslateItems(items, 20, 0);
vb
mapControl.MapEditor.TranslateItems(items, 20, 0)

The following table lists methods that allow you to transform map items:

MethodDescription
MapEditor.TranslateItemsTranslates items at the specified offset.
MapEditor.ScaleItemsScales the map items.
MapEditor.RotateItemsRotates the items at the specified angle.

Undo/Redo Prior Operations

The Map control stores all user edit actions. The MapEditor.Undo method allows you to undo the most recent action, and the MapEditor.Redo method restores the last canceled action. You should check whether these operations can be performed via the MapEditor.CanUndo/MapEditor.CanRedo properties before you call the Undo / Redo methods. 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.

Simplify Map Shapes

The Map control allows you to simplify detailed vector items to reduce memory consumption and enhance a map’s responsiveness. Use the MapEditor.SimplifyItems method to decrease the number of map shape vertices. The Map control changes the existing vertex positions and removes unnecessary vertices. The resulting shape’s resolution depends on the tolerance parameter passed with SimplifyItems. You can use the Undo operation to cancel this action.

The following example shows how to simplify items and use the TrackBarControl to change the tolerance:

csharp
private void Form_Load(object sender, EventArgs e) {
    trackBarControl.Properties.Maximum = 100;
    trackBarControl.Properties.Minimum = 0;
    trackBarControl.Value = 100;
    trackBarControl.EditValueChanged += trackBarControl_EditValueChanged;
}
private void trackBarControl_EditValueChanged(object sender, EventArgs e) {
    double tolerance = Convert.ToDouble(trackBarControl.EditValue);
    mapControl.MapEditor.SimplifyItems(mapControl.MapEditor.ActiveLayer.Data.Items, tolerance);
}
vb
Private Sub Form_Load(ByVal sender As Object, ByVal e As EventArgs)
    trackBarControl.Properties.Maximum = 100
    trackBarControl.Properties.Minimum = 0
    trackBarControl.Value = 100
    trackBarControl.EditValueChanged += AddressOf trackBarControl_EditValueChanged
End Sub

Private Sub trackBarControl_EditValueChanged(ByVal sender As Object, ByVal e As EventArgs)
    Dim tolerance As Double = Convert.ToDouble(trackBarControl.EditValue)
    mapControl.MapEditor.SimplifyItems(mapControl.MapEditor.ActiveLayer.Data.Items, tolerance)
End Sub

You can use the ShapeSimplifierBase.Simplify(IEnumerable<MapItem>, Double) method to simplify items before they are displayed on a layer.

Geometric Measurements

The GeoUtils class exposes methods that measure geometric values based on geographical coordinates. You can use this information to develop map measurement instruments (for example, a map ruler) in a custom map editor.

See Also

Map Vector Data