ProGuide Using Embeddable Controls

Language:      C#
Subject:       Map Exploration
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024
ArcGIS Pro:    3.4
Visual Studio: 2022

This guide demonstrates how to create a map tool with an embeddable control. The coordinates of where you click on the map are displayed in the embeddable control. Note that this map tool does not use sketching (IsSketchTool is not set in the constructor). See ProConcepts Map Exploration, MapTool for more information on the MapTool pattern.

Prerequisites

• Download and install the sample data required for this guide as instructed in Arcgis Pro SDK Community Samples Releases.
• Create a new ArcGIS Pro Module Add-in, and name the project MapToolWithOverlayControl. If you are not familiar with the ArcGIS Pro SDK, you can follow the steps in the ProGuide Build your first add-in to get started.
• Add a new ArcGIS Pro Add-ins | ArcGIS Pro Map Tool item to the add-in project, and name the item ShowCoordinatesTool.
• Add a new ArcGIS Pro Add-ins | ArcGIS Pro Embeddable Control item to the add-in project, and name the item EmbeddedControl.
  

Step 1

Modify the Config.daml file tool item as follows:

• Change the caption to "Show Coordinates".
• Change the tool heading to "Show Coordinates" and the ToolTip text to "Tool shows Coordinates of clicked location."

<tool id="MapToolWithOverlayControl_ShowCoordinatesTool" 
        caption="Show Coordinates" className="ShowCoordinatesTool" 
        loadOnClick="true" 
        smallImage="GenericButtonRed16" largeImage="GenericButtonRed32"
        condition="esri_mapping_mapPane" keytip="z2">
    <tooltip heading="Show Coordinates">Tool shows Coordinates of clicked location.
        <disabledText />
    </tooltip>
</tool>

Build the sample and validate the UI on the ArcGIS Pro ribbon.

Step 2

Modify the EmbeddedControl.xaml file, and add the Border tag as shown below:

...
<Border Background="{DynamicResource Esri_Gray100}" 
        BorderBrush="{DynamicResource Esri_Gray125}" BorderThickness="1">
    <TextBlock Text="{Binding Text}" HorizontalAlignment="Center" 
        VerticalAlignment="Center" Margin="4"/>
</Border>
...

Modify the EmbeddedControlViewModel.cs file, and replace the _text property as shown below:

...
private string _text = "Click in view to show coordinates";
...

Step 3

The required Show Coordinates functions must be implemented in the ShowCoordinatesTool class.

First, remove all code from the constructor along with the two overriden methods (OnToolActivateAsync, OnSketchCompleteAsync) as they are not needed.

Add the following to the constructor.

• Set the OverlayControlID in the constructor to the embedded control's ID (copied from the config.daml file). This allows an embeddable control to be displayed over the map display when the tool is activated.
• Set the OverlayControlCanResize property to true to allow the embeddable control to be resized.
• The OverlayControlPositionRatio of the MapTool is used to set the position of the embeddable control on the map view as a ratio between 0 to 1.

  public ShowCoordinatesTool()
  {
    //Set the tools OverlayControlID to the DAML id of the embeddable control
    OverlayControlID = "MapToolWithOverlayControl_EmbeddedControl";
    //Embeddable control can be resized
    OverlayControlCanResize = true;
    //Specify ratio of 0 to 1 to place the control
    OverlayControlPositionRatio = new System.Windows.Point(0, 0); //top left
  }

Next, add code to support the coordinate display. First, override OnToolMouseDown to signal to the ArcGIS Pro FrameworkApplication that ShowCoordinatesTool will handle the left mouse down event. Then, override HandleMouseDownAsync to implement the actual handler for your mouse-controlled coordinate display. In the handler, using the map point that was clicked, project that point to WGS1984, and update the text in the embeddable control with the projected coordinates. 3D coordinates are handled specially by detecting the presence of a Z coordinate.

Use the OverlayEmbeddableControl property to retrieve the embeddable control specified using the OverlayControlID property. Cast the embeddable control to the view model object in order to access the Text property on the view model.

protected override void OnToolMouseDown(MapViewMouseButtonEventArgs e)
{
  // On mouse down check if the mouse button pressed is the left mouse button. 
  // If it is handle the event.
  if (e.ChangedButton == System.Windows.Input.MouseButton.Left)
    e.Handled = true;
}

/// <summary>
/// Called when the OnToolMouseDown event is handled. Allows the opportunity 
/// to perform asynchronous operations corresponding to the event.
/// </summary>
protected override Task HandleMouseDownAsync(MapViewMouseButtonEventArgs e)
{
  //Get the instance of the ViewModel
  var vm = OverlayEmbeddableControl as EmbeddedControlViewModel;
  if (vm == null)
    return Task.FromResult(0);

  //Get the map coordinates from the click point and set the property on the ViewModel.
  return QueuedTask.Run(() =>
  {
    var mapPoint = ActiveMapView.ClientToMap(e.ClientPoint);
    var coords = GeometryEngine.Instance.Project(mapPoint, SpatialReferences.WGS84) as MapPoint;
    if (coords == null) return;
    var sb = new StringBuilder();
    sb.AppendLine($"X: {coords.X:0.000}");
    sb.Append($"Y: {coords.Y:0.000}");
    if (coords.HasZ)
    {
      sb.AppendLine();
      sb.Append($"Z: {coords.Z:0.000}");
    }         
    vm.Text = sb.ToString();
  });
}

Step 4

Rebuild the add-in. Fix any compilation errors.

Step 5

Debug the add-in. Run the debugger and start ArcGIS Pro. Open the C:\Data\Interacting with Maps\Interacting with Maps.aprx project that contains 2D and 3D maps with feature data. Try the tool on the 2D map as shown here:

Try the tool on the 3D scene as shown here: