ContextQMD
Back to Devexpress

Select and Highlight Map Items

windowsforms-16857-controls-and-libraries-map-control-end-user-features-select-and-highlight-map-items.md

latest10.3 KB
Original Source

Select and Highlight Map Items

  • Oct 18, 2021
  • 4 minutes to read

The Map Control allows end users to select one or multiple vector items on a map surface, and provides API to interact with these items in code. Users can also highlight map items.

This article explains how to:

Allow Users to Highlight Items

Use the MapItemsLayerBase.EnableHighlighting property to specify whether users can highlight map items on the layer:

csharp
informationLayer.EnableHighlighting = true;
vb
informationLayer.EnableHighlighting = True

Configure Highlighted Items’ Appearance

The following code customizes the appearance of vector items highlighted by the user:

csharp
informationLayer.HighlightedItemStyle.Fill = Color.Gray;
informationLayer.HighlightedItemStyle.Stroke = Color.Orange;
informationLayer.HighlightedItemStyle.StrokeWidth = 2;
informationLayer.HighlightedItemStyle.TextColor = Color.White;
vb
informationLayer.HighlightedItemStyle.Fill = Color.Gray
informationLayer.HighlightedItemStyle.Stroke = Color.Orange
informationLayer.HighlightedItemStyle.StrokeWidth = 2
informationLayer.HighlightedItemStyle.TextColor = Color.White

The table below lists API members used by code listed above:

MemberDescription
MapItemsLayerBase.HighlightedItemStyleSpecifies a style to apply to highlighted items on the layer.
MapItemStyle.FillDefines a highlighted item’s fill color.
MapItemStyle.StrokeDefines a highlighted item’s stroke color.
MapItemStyle.StrokeWidthSpecifies a highlighted item’s stroke width in pixels.
MapItemTextStyle.TextColorDefines a highlighted item’s text color.

Allow Users to Select Items

Use the MapItemsLayerBase.EnableSelection property to define whether users can select items on the layer:

csharp
informationLayer.EnableSelection = false;
vb
informationLayer.EnableSelection = False

The MapControl.SelectionMode property allows you to enable/disable selection for all map layers. The ElementSelectionMode enumeration lists available modes:

|

Mode

|

Example

|

Description

| | --- | --- | --- | |

Single

|

|

A single map item can be selected on the map at the same time.

  • Tap a map item on a touchscreen device.
  • Hover over a map item with the mouse pointer and click it.

| |

Multiple

|

|

Multiple map items can be selected at the same time.

You can use Rectangular Selection to select several items at once.

  • Hold the Shift key and the left mouse button;
  • Drag the mouse pointer to mark an area that includes map items to be selected;
  • Release the left mouse button. All map items within the area are selected.

| |

Extended

|

|

Extended mode combines Single and Multiple selection mode behaviors.

  • Click an element to select it.
  • To select/deselect multiple elements, click them while the Ctrl key is pressed.

Extended mode also allows you to use Rectangular Selection

| |

None

| |

Users cannot select any map items.

|

The code below enables Multiple mode:

csharp
mapControl.SelectionMode = ElementSelectionMode.Multiple;
vb
mapControl.SelectionMode = ElementSelectionMode.Multiple

Customize Selected Items’ Appearance

The following code customizes the appearance of items a user selects:

csharp
informationLayer.SelectedItemStyle.Fill = Color.Gray;
informationLayer.SelectedItemStyle.Stroke = Color.Orange;
informationLayer.SelectedItemStyle.StrokeWidth = 4;
informationLayer.SelectedItemStyle.TextColor = Color.White;
vb
informationLayer.SelectedItemStyle.Fill = Color.Gray
informationLayer.SelectedItemStyle.Stroke = Color.Orange
informationLayer.SelectedItemStyle.StrokeWidth = 4
informationLayer.SelectedItemStyle.TextColor = Color.White

The table below lists the API members that code listed above uses:

MemberDescription
MapItemsLayerBase.SelectedItemStyleSpecifies a style to apply to selected items in the layer.
MapItemStyle.FillDefines a selected item’s fill color.
MapItemStyle.StrokeDefines a selected item’s stroke color.
MapItemStyle.StrokeWidthSpecifies a selected item stroke’s width in pixels.
MapItemTextStyle.TextColorDefines selected item text’s color.

Specify Selection Rectangle Appearance

You can change the selection rectangle’s fill color and outline appearance:

The code below configures the selection rectangle as in the image above:

csharp
mapControl.SelectedRegionStyle.Fill = Color.FromArgb(80, 255, 165, 0);
mapControl.SelectedRegionStyle.Stroke = Color.FromArgb(144, 255, 165, 0);
vb
mapControl.SelectedRegionStyle.Fill = Color.FromArgb(80, 255, 165, 0)
mapControl.SelectedRegionStyle.Stroke = Color.FromArgb(144, 255, 165, 0)

The table below lists the API members that code listed above uses:

MemberDescription
MapControl.SelectedRegionStyleSpecifies a style to apply to the Selection Rectangle’s area.
BackgroundStyle.FillGets or sets the Selection Rectangle’s fill color.
BorderedElementStyle.StrokeGets or sets the Selection Rectangle’s stroke color.

Interact with Selected Items in Code

The MapItemsLayerBase.SelectedItems collection stores the items a user selects. The MapItemsLayerBase.SelectedItem property keeps the SelectedItems collection’s first item.

The Map control raises the MapControl.SelectionChanged event after the SelectedItems collection is changed.

The MapControl.SelectionChanging event occurs before any map item is selected. Set the MapSelectionChangingEventArgs.Cancel property to true to cancel the item’s selection.

csharp
mapControl1.SelectionChanging += mapControl1_SelectionChanging;
mapControl1.SelectionChanged += mapControl1_SelectionChanged;
//...
private void mapControl1_SelectionChanged(object sender, MapSelectionChangedEventArgs e) {
        dataGenerator.SelectedPlane = e.Selection.Count > 0 ? (PlaneInfo)e.Selection[0] : null;
        OnActivePlaneChanged();   
}
private void mapControl1_SelectionChanging(object sender, MapSelectionChangingEventArgs e) {
    PlaneInfo plainInfo = e.Selection.Count > 0 ? e.Selection[0] as PlaneInfo : null;
    e.Cancel = plainInfo == null;
}
vb
mapControl1.SelectionChanging = (mapControl1.SelectionChanging + mapControl1_SelectionChanging)
mapControl1.SelectionChanged = (mapControl1.SelectionChanged + mapControl1_SelectionChanged) 
'...
Private Sub mapControl1_SelectionChanged(ByVal sender As Object, ByVal e As MapSelectionChangedEventArgs)
    dataGenerator.SelectedPlane = If(e.Selection.Count > 0, CType(e.Selection(0), PlaneInfo), Nothing)
    If e.Selection.Count > 0 Then
        dataGenerator.SelectedPlane = CType(e.Selection(0), PlaneInfo)
    Else
        dataGenerator.SelectedPlane = Nothing
    End If
    OnActivePlaneChanged()
End Sub
Private Sub mapControl1_SelectionChanging(ByVal sender As Object, ByVal e As MapSelectionChangingEventArgs)
        Dim plainInfo As PlaneInfo
        If (e.Selection.Count > 0) Then
            plainInfo = CType(e.Selection(0),PlaneInfo)
        Else
            plainInfo = Nothing
        End If
        e.Cancel = (plainInfo Is Nothing)
End Sub

Run Demo: Map Elements

Note

Use MapItem.IsHitTestVisible to specify whether a user can highlight or select the item.