Creating a custom DockWindow


Summary This walkthrough topic shows how to create a custom DockWindow for ArcGIS Explorer.

Click here to get the sample associated with this walkthrough.

In this topic


Creating a project in Visual Studio

The DockWindow class provides a custom implementation of a dockable window with which users can interact. In this topic, you will create a dockable window that captures the location of where the Map is clicked by the user, add a graphic at each clicked point, then record the coordinates in a tree view control.  
The process for creating a DockWindow is similar to creating a Button. The easiest way to create a DockWindow or Button is to use the templates provided for you with this software development kit (SDK).
Do the following steps to create a custom DockWindow:
  1. Start Visual Studio.
While this topic refers to and shows screen shots from Visual Studio 2008 running on Windows Vista, you can also follow the steps in Visual Studio 2010, Visual Basic or Visual C# Express, and Windows XP or Windows 7.
  1. Click File, click New, and click New Project. The New Project dialog box appears.
To complete this scenario, use C# or VB .NET. The code for both is shown; however, this topic only shows the C# dialog boxes in the screen shots, since the dialog boxes and views you interact with in VB .NET are very similar.
  1. On the New Project dialog box click the Visual C# or Visual Basic Projects node under the Project types pane, click the ArcGIS node, then click the Explorer node.
  2. Click the ArcGIS Explorer DockWindow template under the Templates pane.
  3. Name the project TrackPoint, then click Browse to locate where you want to save the project. See the following screen shot:

  1. Click OK on the New Project dialog box to create the project. The New ArcGIS Explorer DockWindow Project dialog box appears where you can set additional properties for your dockable window.

Setting additional DockWindow properties

Do the following steps to set additional DockWindow properties:
  1. On the New ArcGIS Explorer DockWindow Project (Enter Project Settings) dialog box, the Name property is automatically added. In the Description, Group Caption, (displays on the Add-Ins tab), and Publisher text boxes, type an appropriate name. See the following screen shot:


  2. Click Next on the preceding dialog box. The second page (Enter DockWindow Settings) of the New ArcGIS Explorer DockWindow Project dialog box appears. See the following screen shot:


  3. Type a caption, for example, Track Point in the Caption text box. Type a ToolTip in the ToolTip text box, for example, Click the map to create a point graphic and retrieve its location.
  4. Click Finish. At this point, you do not have to select any conditions from the Availability drop-down list or alternate images for the add-in.

Designing the Track Point form

Do the following steps to design the Track Point form:
  1. Double-click the DockWindow.cs class in the Solution Explorer to view the design form. Add a button and tree view to the form.
  2. Set the button's name to btnPoint and set the button's text property to Track Point.
  3. Set the tree view's name to tvTrackedGeometries. See the following screen shot:

Adding the Track Point functionality

Do the following steps to add the Track Point functionality:
  1. Double-click the Track Point button to access the code for the DockWindow. The following code example is automatically generated:
[C#]
public partial class DockWindow: ESRI.ArcGISExplorer.Application.DockWindow
{

    public DockWindow()
    {
        InitializeComponent();
    }
[VB.NET]
Public Partial Class DockWindow
Inherits ESRI.ArcGISExplorer.Application.DockWindow

Public Sub New()
    InitializeComponent()
End Sub
  1. Insert the following code example to track the user clicked point on the map and add a pushpin at that location:
[C#]
private void btnPoint_Click(object sender, EventArgs e)
{

    MapDisplay md = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay;
    //Track Point.
    ESRI.ArcGISExplorer.Geometry.Point trackedPoint = md.TrackPoint();
    //Turn Point to Graphic.
    Graphic trackedGraphic = new Graphic(trackedPoint, Symbol.Marker.Pushpin.Red);
    //Add the Graphic to the Map Display.
    md.Graphics.Add(trackedGraphic);
    //Create a string to hold the coordinates of the Point.
    string title = trackedPoint.GeometryType.ToString() + " with center at " +
        trackedPoint.X + ", " + trackedPoint.Y;
    //Add the Point coordinates to the TreeView.
    GraphicToTreeView(trackedGraphic, title);
}
[VB.NET]
Private Sub btnPoint_Click(ByVal sender As Object, ByVal e As EventArgs)
    
    Dim md As MapDisplay = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay
    'Track Point.
    Dim trackedPoint As ESRI.ArcGISExplorer.Geometry.Point = md.TrackPoint()
    'Turn Point to Graphic.
    Dim trackedGraphic As Graphic = New Graphic(trackedPoint, Symbol.Marker.Pushpin.Red)
    'Add the Graphic to the Map Display.
    md.Graphics.Add(trackedGraphic)
    'Create a string to hold the coordinates of the Point.
    Dim title As String = trackedPoint.GeometryType.ToString() & " with center at " & trackedPoint.X & ", " & trackedPoint.Y
    'Add the Point coordinates to the TreeView.
    GraphicToTreeView(trackedGraphic, title)
End Sub
  1. Insert the following code example to add the point's coordinate information to the tree view:
[C#]
private void GraphicToTreeView(Graphic trackedGraphic, string title)
{
    tvTrackedGeometries.BeginUpdate();
    //Create a tree node with the Point's coordinates as the title.
    TreeNode tn = new TreeNode(title);
    //Add the new tree node to the tree view.
    tvTrackedGeometries.Nodes.Insert(tvTrackedGeometries.Nodes.Count, tn);
    tvTrackedGeometries.EndUpdate();
    tvTrackedGeometries.Refresh();
}
[VB.NET]
Private Sub GraphicToTreeView(ByVal trackedGraphic As Graphic, ByVal title As String)
    tvTrackedGeometries.BeginUpdate()
    'Create a tree node with the Point's coordinates as the title.
    Dim tn As TreeNode = New TreeNode(title)
    'Add the new tree node to the tree view.
    tvTrackedGeometries.Nodes.Insert(tvTrackedGeometries.Nodes.Count, tn)
    tvTrackedGeometries.EndUpdate()
    tvTrackedGeometries.Refresh()
End Sub

Compiling the project

Do the following steps to build your project:
  1. Save your project.
  2. Click the Build menu and click Build Solution.
  3. If your project built correctly, a report states the build succeeded in the Output window at the bottom of the Visual Studio .NET integrated development environment (IDE).
You can also check the results of the build operation by reviewing the subdirectories of your project. By default, you will build a debug version of your project. The dynamic-link library (DLL) that results from the build operation will be stored in the Bin\Debug subdirectory of your project. This directory also contains debug information (.pdb) and a type library (.tlb) file, produced by the Assembly Registration tool.
 
The obj subdirectory of the project directory contains temporary files used by the compiler and Visual Studio.
  1. If you successfully followed this walkthrough, your build will succeed. Close Visual Studio now that your dockable window has been created. If your build operation did not succeed, click View and click Task List to view the errors, correct the errors as indicated, then close Visual Studio when you have a successful build.
If you double-click the task, the line of code causing the error is automatically selected.
On a successful build, the necessary files are automatically added to the following locations:
  • For Windows Vista and Windows 7—C:\Users\<username>\AppData\Roaming\ESRI\ArcGIS Explorer\Addins.
  • For Windows XP—C:\Documents and Settings\<username>\Application Data\ESRI\ArcGIS Explorer\AddIns.

Using the add-in in ArcGIS Explorer

Do the following steps to use the DockWindow in ArcGIS Explorer:
  1. Start ArcGIS Explorer and zoom to a location, such as a city or neighborhood.
  2. Click the Add-Ins tab to view your dockable window.
  3. Click the dockable window, click the Track Point button, then click a location on the map.

Debugging the add-in

Running the add-in in debug mode allows you to step through the code when it is executed. This is helpful when you encounter bugs in custom add-ins. If you followed the steps in this topic, you should not have to debug the add-in you have created in this walkthrough. However, for more information about debugging add-ins, see How to debug add-ins in Visual Studio.


See Also:

Sample: DockWindow Walkthrough
How to debug add-ins in Visual Studio