Introduction to ArcGIS Add-Ins

ExercisesGIS/LIS Conference, 2014

Rochester, MN

Introduction to ArcGIS Add-ins 2

Exercise 1 – Add-Ins with Python

In this exercise you will be using the Python Add-In Wizard and PyScripter to create an Add-In to ArcMap that contains a toolbar with a tool for creating a map package file (.mpk).

1. Open the Python Add-In Wizard by Double-clicking on the AddIn Assistant shortcut on your desktop.

2. The first thing you’ll need to do is define your Add-In project root folder. Navigate to C:\temp\IntroductiontoAddInsforArcGIS\Exercise1 and create a folder called ‘CreateMapPackage’

Click ‘OK’

Introduction to ArcGIS Add-ins 3

3. In the Wizard window that appears enter the information as shown in the graphic to the right.

Select Product: ArcMapName: Create Map Package ToolVersion: 1.0Company: MN DNRDescription: Provides a tool to create a map package based onthe user defined extent.Author: <your name here>Image: C:\temp\Introduction to AddIns for ArcGIS\Exercise1\Package64.png.

4. Click on the ‘Add-In Contents’ Tab

Introduction to ArcGIS Add-ins 4

5. In the contents tab you can define buttons/tools/etc to be included in the add-in. Add a toolbar by right-clicking on the TOOLBARS item and select ‘New Toolbar’. Enter the information as shown in the graphic below.

Caption: Map PackageID: CreateMapPackage_addin.mpktoolbarShow Initially: Checked

Introduction to ArcGIS Add-ins 5

6. Under your new Map Package toolbar add a new Tool by right-clicking on the ‘Map Package’ item and select ‘New Tool’. Enter the information as shown in the graphic below.

Caption: Create Map PackageClass Name: CreateMPKToolID: CreateMapPackage_addin.mpktoolTooltip: Create Map PackageMessage: Create Map Packagefor user defined extentHelp Heading: Create Map PackageHelp Content: Create Map Package for user defined extent

Image: C:\temp\Introduction to AddIns for ArcGIS\Exercise1\Package16.png

Introduction to ArcGIS Add-ins 6

7. Next add an extension that will listen for changes to the Active View. Add an extension by right-clicking on the ‘EXTENSIONS’ item and select ‘New Extension’. Enter the information as shown in the graphic below.

Name: Create Map PackageClass Name: CreateMPKExtID: CreateMapPackage_addin.mpkextDescription: Checks Active View and disables Create Map Package if the Active View is Page LayoutMethods to Implement: ActiveViewChanged

Click ‘Save’. The Add-In structure is created in the C:\temp\IntroductiontoAddIns forArcGIS\Exercise1\CreateMapPackage folder

Introduction to ArcGIS Add-ins 7

8. The Add-In structure has been created in the C:\temp\IntroductiontoAddInsfor ArcGIS\Exercise1\CreateMapPackage folder. The next step is to modify the code behind the tool and extension so that they perform as expected. Open Windows Explorer and navigate to C:\temp\IntroductiontoAddInsforArcGIS\Exercise1\CreateMapPackage\Install. Right-click on the CreateMapPackage_addin.py file and select ‘Edit With PyScripter’.

Introduction to ArcGIS Add-ins 8

9. Some custom code needs to be added to this file. For simplicity, the code is sitting in a text file at C:\temp\IntroductiontoAddInsforArcGIS\Exercise1\customCode.txt. Open this file and copy its contents. Replace ALL of the code in the CreateMapPackage_addin.py and then Save your Changes (FileSave). It should look similar to the screen shot below:

Introduction to ArcGIS Add-ins 9

10. All the pieces are now ready to be compiled into the ESRI Add-In. Go to C:\temp\IntroductiontoAddInsforArcGIS\Exercise1\CreateMapPackage and double-click on the makeaddin.py file. This will create the add-in file in the same directory.

11. Install the Add-in. To do this, double-click on the file (C:\temp\IntroductiontoAddInsforArcGIS\Exercise1\CreateMapPackage\CreateMapPackage.esriaddin). When the Installation Utility appears click on ‘Install Add-In’.

Introduction to ArcGIS Add-ins 10

12. Now test the add-in. Launch ArcMap and open the sample project at C:\temp\IntroductiontoAddInsforArcGIS\Exercise1\sampleMap.mxd.

13. Turn on the Create Map Package Extension by going to CustomizeExtensions and checking “on” the Create Map Package extension.Your new toolbar should be visible with your one tool. If it’s not, go to CustomizeToolbars and turn on the Create Map Package toolbar. To use the tool select it and then click and drag a rectangle on the map. All data within that rectangle will be extracted and bundled and saved out to a map package located next to the sampleMap.mxd called sampleMap.mpk.

Introduction to ArcGIS Add-ins 11

Exercise 2 – Add-Ins with Visual Studio

In this exercise you will be using Visual Studio Express 2010 to create an Add-In to ArcMap that contains a toolbar with two tools – one for finding upstream watersheds and one for finding downstream watersheds from a user’s mouse-click.

1. Open Visual Studio by Double-clicking on the Visual Studio shortcut on your desktop or from the Start menu.

2. Select “New Project” from the options on the left side of the window that opens.

3. Select “Desktop Add-Ins”on the left side, “ArcMapAdd-in” from the middlepane, and at the bottomof the New Project window type in “WatershedTools” for the name of your Add-in project. Click ‘OK’.

Introduction to ArcGIS Add-ins 12

4. Enter the information as shownin the graphic to the right.

Add-in Name: WatershedToolsCompany: MN DNRAuthor: <your name here>Description: These tools are for analyzing watersheds.Image: C:\temp\IntroductiontoAddInsforArcGIS\Exercise2\Watershed.png.

Click ‘Next’

Introduction to ArcGIS Add-ins 13

5. Enter the information as shownin the graphic to the right.

Add-in Type: ToolClass Name: toolUpstreamCaption: Find Upstream WatershedsImage: C:\temp\Introduction to AddIns for ArcGIS\Exercise2\Upstream.pngCategory: WatershedOn Demand: CheckedTooltip: Find Upstream WatershedsDescription: This tool selects all watersheds upstream of a user’s click

Click ‘Finish’

A new project is created with the parametersthat you’ve chosen – an Add-in with anupstream tool. The next step is to add thedownstream tool.

Introduction to ArcGIS Add-ins 14

6. Next you’ll add the 2nd tool to your project. To do this go to ProjectAdd New Item. Select the options as shown below:

Installed Template: Desktop Add-insType: Add-in ComponentName: toolDownstream.vb

Click ‘Add’

Introduction to ArcGIS Add-ins 15

7. Enter the information as shownin the graphic to the right.

Add-in Type: ToolClass Name: toolDownstreamCaption: Find Downstream WatershedsImage: C:\temp\IntroductiontoAddIns forArcGIS\Exercise2\Downstream.pngCategory: WatershedOn Demand: CheckedTooltip: Find Downstream WatershedsDescription: This tool selects all watersheds downstream of a user’s click

Click ‘Finish’

The new tool is added to your project.

Introduction to ArcGIS Add-ins 16

8. Next you’ll add the toolbar which will contain the two tools. To do this go to ProjectAdd New Item. Enter the information as shown in the graphic below.

Installed Template: Desktop Add-insType: Add-in Command ContainerName: toolbarWatershedTools.vb

Click ‘Add’

Introduction to ArcGIS Add-ins 17

9. Enter the information as shown in the graphic below.

Add-in Command Bar Type: ToolbarCaption: Watershed ToolsPremier Toolbar: UncheckedItems: Select the Upstream and Downstream tools from the combobox

Click ‘Finish’

Introduction to ArcGIS Add-ins 18

10. There is some preexisting code that needs to be added which does the actual work behind the tools. To add it to the project go to ProjectAdd Existing Item. Add this file: C:\temp\IntroductiontoAddInsforArcGIS\Exercise2\ArcMapCode.vb.

11. This custom code also requires that some ArcObjects references be loaded. Go to ProjectAdd Reference and add the following .NET References (Note: You can click on the Component Name column header to sort the list):

ESRI.ArcGIS.CartoESRI.ArcGIS.DisplayESRI.ArcGIS.EditorESRI.ArcGIS.GeodatabaseESRI.ArcGIS.GeometryESRI.ArcGIS.Location

Introduction to ArcGIS Add-ins 19

12. You now have all the pieces necessary for your Add-In toolbar. Now add functionality to the tools. Open the toolDownstream.vb file and update it to look like the graphic below:

Protected Overrides Sub OnMouseDown(ByVal arg As ESRI.ArcGIS.Desktop.AddIns.Tool.MouseEventArgs)

MyBase.OnMouseDown(arg) ArcMapCode.HU_Find_Downstream(arg.X, arg.Y) End Sub

Introduction to ArcGIS Add-ins 20

13. Do the same for the Upstream tool. Open the toolUpstream.vb file and update it to look like the graphic below:

Protected Overrides Sub OnMouseDown(ByVal arg As ESRI.ArcGIS.Desktop.AddIns.Tool.MouseEventArgs)

MyBase.OnMouseDown(arg) ArcMapCode.HU_Find_Upstream(arg.X, arg.Y) End Sub

Introduction to ArcGIS Add-ins 21

14. Next save your project. Go to FileSave All. All files and images will be saved to the same project directory.

15. Now compile by going to DebugBuild Watershed Tools. (If using Visual Studio 2012, go to BuildBuild Watershed Tools.)This will build the Add-In at C:\temp\IntroductiontoAddInsforArcGIS\Exercise2\WatershedTools\WatershedTools\bin\Release\WatershedTools.esriAddIn and it also installs it to Arcmap’s well-known Add-In folder located at c:\Users\<username>\Documents\ArcGIS\AddIns\Desktop10.1

Introduction to ArcGIS Add-ins 22

16. To test your add-in, open the test MXD located at C:\temp\IntroductiontoAddInsforArcGIS\Exercise2\Watersheds.mxd.

Go to CustomizeToolbarsWatershed Tools to open your toolbar.Select the Watershed layer by single clicking on it in the table of contents.Select the Upstream or Downstream tool and click on a watershed. The respective upstream/downstream path for that watershed should become selected.