Extending the ArcGIS Desktop Applications

Copyright © 2005–2006 ESRI All rights reserved. Course version 2.1. Revised D ecem ber2006. Printed in the United States of America.

The information contained in this document is the exclusive property of ESRI. This work is protected under United States copyright law and other international copyright treaties and conventions. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or by any information storage or retrieval system, except as expressly permitted in writing by ESRI. All requests should be sent to Attention: Contracts and Legal Services Manager, ESRI, 380 New York Street, Redlands, CA 92373-8100, USA.

The information contained in this document is subject to change without notice.

U. S. GOVERNMENT RESTRICTED/LIMITED RIGHTS Any software, documentation, and/or data delivered hereunder is subject to the terms of the License Agreement. In no event shall the U.S. Government acquire greater than RESTRICTED/LIMITED RIGHTS. At a minimum, use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR §52.227-14 Alternates I, II, and III (JUN 1987); FAR §52.227-19 (JUN 1987) and/or FAR §12.211/12.212 (Commercial Technical Data/Computer Software); and DFARS §252.227-7015 (NOV 1995) (Technical Data) and/or DFARS §227.7202 (Computer Software), as applicable. Contractor/Manufacturer is ESRI, 380 New York Street, Redlands, CA 92373-8100, USA. @esri.com, 3D Analyst, ADF, AML, ArcInfo, ArcAtlas, ArcCAD, ArcCatalog, ArcCOGO, ArcData, ArcDoc, ArcEdit, ArcEditor, ArcEurope, ArcExplorer, ArcExpress, ArcFM, ArcGIS, ArcGlobe, ArcGrid, ArcIMS, ArcInfo Librarian, ArcInfo, ArcInfoProfessional GIS, ArcInfo-The World's GIS, ArcLocation, ArcLogistics, ArcMap, ArcNetwork, ArcNews, ArcObjects, ArcOpen, ArcPad, ArcPlot, ArcPress, ArcQuest, ArcReader, ArcScan, ArcScene, ArcSchool, ArcSDE, ArcSdl, ArcStorm, ArcSurvey, ArcTIN, ArcToolbox, ArcTools, ArcUSA, ArcUser, ArcView, ArcVoyager, ArcWatch, ArcWeb, ArcWorld, Atlas GIS, AtlasWare, Avenue, BusinessMAP, Database Integrator, DBI Kit, ESRI, ESRI-Team GIS, ESRI-The GIS Company, ESRI-The GIS People, FormEdit, Geographic Design System, Geography Matters, Geography Network, GIS by ESRI, GIS Day, GIS for Everyone, GISData Server, InsiteMAP, JTX, MapBeans, MapCafé, MapObjects, ModelBuilder, MOLE, NetEngine, PC ArcInfo, PC ARCPLOT, PC ARCSHELL, PC DATA CONVERSION, PC STARTER KIT, PC TABLES, PC ARCEDIT, PC NETWORK, PC OVERLAY, PLTS, Rent-a-Tech, RouteMAP, SDE, SML, Spatial Database Engine, StreetEditor, StreetMap, TABLES, the ArcInfo logo, the ArcCAD logo, the ArcCAD WorkBench logo, the ArcCOGO logo, the ArcData logo, the ArcData Online logo, the ArcEdit logo, the ArcExplorer logo, the ArcExpress logo, the ArcFM logo, the ArcFM Viewer logo, the ArcGIS logo, the ArcGrid logo, the ArcIMS logo, the ArcInfo logo, the ArcLogistics Route logo, the ArcNetwork logo, the ArcPad logo, the ArcPlot logo, the ArcPress for ArcView logo, the ArcPress logo, the ArcScan logo, the ArcScene logo, the ArcSDE CAD Client logo, the ArcSDE logo, the ArcStorm logo, the ArcTIN logo, the ArcTools logo, the ArcView 3D Analyst logo, the ArcView Business Analyst logo, the ArcView Data Publisher logo, the ArcView GIS logo, the ArcView Image Analysis logo, the ArcView Internet Map Server logo, the ArcView logo, the ArcView Network Analyst logo, the ArcView Spatial Analyst logo, the ArcView StreetMap 2000 logo, the ArcView StreetMap logo, the ArcView Tracking Analyst logo, the Atlas GIS logo, the Avenue logo, the BusinessMAP logo, the Data Automation Kit logo, the ESRI ArcAtlas Data logo, the ESRI ArcEurope Data logo, the ESRI ArcScene Data logo, the ESRI ArcUSA Data logo, the ESRI ArcWorld Data logo, the ESRI Digital Chart of the World Data logo, the ESRI globe logo, the ESRI Press logo, the Geography Network logo, the MapCafé logo, the MapObjects Internet Map Server logo, the MapObjects logo, the MOLE logo, the NetEngine logo, the PC ArcInfo logo, the Production Line Tool Set logo, the RouteMAP IMS logo, the RouteMAP logo, the SDE logo, The World's Leading Desktop GIS, Water Writes, www.esri.com, www.geographynetwork.com, www.gisday.com, and Your Personal Geographic Information System are trademarks, registered trademarks, or service marks of ESRI in the United States, the European Community, or certain other jurisdictions. Other companies and products mentioned herein are trademarks or registered trademarks of their respective trademark owners.

C O N T E

N

1

Introduction

2

Fundamentals of Developing Desktop Applications

T

S

Welcome to Extending ArcGIS Desktop Applications Logistics ArcGIS overview ESRI Educational Services Additional ArcGIS materials and resources ESRI Support Center ESRI Developer Network Course objectives Course timeline Course materials Getting started with desktop development Extending ArcGIS Desktop applications Why extend the desktop applications? What can be customized and extended? The ArcGIS Desktop development process The developer resources Installation and configuration 1. Preinstallation 2. ArcGIS Desktop installation 3. Desktop Developer Kit options ArcGIS Desktop product licensing Developer resources and environments Exercise options Exercise 1 overview Lesson 1 review Exercise 1A: Install the class data and configure development environments

Lesson 2A overview ArcGIS architecture ArcGIS libraries ArcObjects COM ArcObjects and the COM API COM classes

Copyright © 2005-2006 ESRI

1-2 1-3 1-4 1-5 1-6 1-7 1-8 1-9 1-10 1-11 1-12 1-13 1-14 1-15 1-16 1-17 1-18 1-19 1-20 1-21 1-22 1-23 1-24 1-25 1-26

2-2 2-3 2-4 2-5 2-6 2-7 2-8

i

Extending the ArcGIS Desktop Applications

Contents

COM interfaces Other topics: Working with GUIDs ArcObjects and the .NET API ArcGIS .NET assemblies and namespaces .NET interfaces Lesson 2B overview The application framework Creating custom commands Commands: Framework/Background Developing custom COM components (.NET) Step 1: Create a .NET project Step 2: Create a COM class Step 3: Reference ArcGIS libraries Step 4: Implement an ArcObjects interface Finding the correct interface Commands: Implementation details ICommand: Properties ICommand: Event properties ICommand: Referencing the application Custom commands: HookHelper class ICommand: Clicking the command Step 5: Compile Step 6: Register in a component category Application startup cycle Component categories Exercise 2A overview Exercise 2A: Fundamentals of extending ArcGIS applications (Visual Basic 6.0) Lesson 2B overview .Net new project templates .Net base classes Add Class Wizard .Net code snippets Add import/using statements .NET classes .NET outbound interfaces Other topics Registering/unregistering components Exercise 2B overview

ii

2-9 2-10 2-11 2-12 2-13 2-14 2-15 2-16 2-17 2-18 2-19 2-20 2-21 2-22 2-23 2-24 2-25 2-26 2-27 2-28 2-29 2-30 2-31 2-32 2-33 2-34 2-35 2-36 2-37 2-38 2-39 2-40 2-41 2-42 2-43 2-44 2-45

Copyright © 2005-2006 ESRI

Contents

Lesson 2 review Exercise 2B: Fundamentals of extending ArcGIS applications (VB.NET) Exercise 2C: Visual Studio Integration (VB.NET) Exercise 2D: Fundamentals of extending ArcGIS applications (C#) Exercise 2E: Visual Studio Integration (C#)

3

2-46

Custom UI Controls Lesson 3A overview Types of custom UI controls ArcGIS UI control application framework The CommandItem list Working with CommandItems ICommand: Managing bitmaps Commands: Implementing custom help files ICommand: Associating help files Commands: Working with forms Commands: Sinking events Commands: Implementing multiple commands Commands: Other important concepts Custom Tools Tools: Framework/Background Tools: Implementation details ITool: Mouse properties ITool: Key properties ITool: Deactivation ITool: Showing custom context menus Exercise 3A overview Lesson 3B overview Custom toolbars Toolbars: Implementation details IToolBarDef: Properties IToolBarDef: Defining commands Custom menus Menus: Framework/Background Menus: Implementation details IMenuDef: Properties IMenuDef: Defining commands Menus: Creating multi-item menus Framework components working together

Copyright © 2005-2006 ESRI

3-2 3-3 3-4 3-5 3-6 3-7 3-8 3-9 3-10 3-11 3-12 3-13 3-14 3-15 3-16 3-17 3-18 3-19 3-20 3-21 3-22 3-23 3-24 3-25 3-26 3-27 3-28 3-29 3-30 3-31 3-32 3-33

iii

Extending the ArcGIS Desktop Applications

Exercise 3B – 3D overview Lesson 3 review Exercise 3A: Build a custom menu (VB6) Exercise 3B: Build an animation tool (VB6) (optional) Exercise 3C: Build a toolbar (VB6) Exercise 3D: Build a custom tool (VB.NET) Exercise 3E: Build a custom menu (VB.NET) Exercise 3F: Build an animation tool (VB.NET) (optional) Exercise 3G: Build a toolbar (VB.NET) Exercise 3H: Build a custom tool (C#) Exercise 3I: Build a custom menu (C#) Exercise 3J: Build an animation tool (C#) (optional) Exercise 3K: Build a toolbar (C#)

4

iv

Contents

3-34 3-35

Extending the Application Windows Lesson 4 overview Types of custom windows ArcGIS windows application framework Loading custom windows Parent and child windows Custom contents views Contents views: Framework/Background Contents views: Implementation details IContentsView: Activating and deactivating IContentsView: Window properties IContentsView: Managing selected items Contents views: Listening for events Custom catalog views Catalog views: Implementation details IGxView: Activating and deactivating IGxView: Applying to a GxObject Catalog views: Reacting to selected GxObjects IGxView: Window properties Exercise 4 overview Dockable windows Dockable Windows: Implementation details IDockableWindowDef: Main properties IDockableWindowDef: Properties DockableWindows: Associating with commands DockableWindows: Synchronizing with commands

4-2 4-3 4-4 4-5 4-6 4-7 4-8 4-9 4-10 4-11 4-12 4-13 4-14 4-15 4-16 4-17 4-18 4-19 4-20 4-21 4-22 4-23 4-24 4-25 4-26

Copyright © 2005-2006 ESRI

Contents

Dockable Windows: Managing the dock state Dockable Windows: Other important topics Custom property pages Property pages: Framework/Background Property pages: Implementation details Exercise 4 overview Lesson 4 review Exercise 4A: Extending the Application Windows (VB6) Exercise 4B: Extending the Application Windows (VB.NET) Exercise 4C: Extending the Application Windows (C#)

5

4-27 4-28 4-29 4-30 4-32 4-33 4-34

Custom Application Extensions Lesson 5A overview ArcGIS application framework for extensions Application extensions: Framework/Background Application extensions: Framework/background Application extensions: Framework/Background Application extensions: Implementation details IExtension: Invisible extensions Custom extensions: Document events IExtensionConfig: Visible extensions IExtensionConfig: Extension state Custom extensions: Managing state Custom extensions: Finding extensions Custom extensions: Controlling commands Just in Time (JIT) extensions JIT Extensions: Implementation details Exercise 5A overview Lesson 5B overview Document persistence Document persistence: Framework/Background Document persistence: Objects that store data Document persistence: Implementation details Persistence: Members Document persistence: Persistence mechanism Document persistence: Writing to streams Document persistence: Read/write concepts IPersistVariant: Saving data IPersistVariant: Loading data

Copyright © 2005-2006 ESRI

5-2 5-3 5-4 5-5 5-6 5-7 5-8 5-9 5-10 5-11 5-12 5-13 5-14 5-15 5-16 5-17 5-18 5-19 5-20 5-21 5-22 5-23 5-24 5-25 5-26 5-27 5-28

v

Extending the ArcGIS Desktop Applications

Contents

Document persistence: Other important topics Application licensing Application licensing: Product Application licensing: Extension Application licensing: Status codes Application licensing: Handling HRESULTs Exercise 5B overview Lesson 5 review Exercise 5A: Custom application extensions (VB6) Exercise 5B: Implement persistence and license checking (VB6) Exercise 5C: Building application extensions (VB.NET) Exercise 5D: Implement Persistence and license checking (VB.NET) Exercise 5E: Building application extensions (C#) Exercise 5F: Implement Persistence and license checking (C#)

6

vi

5-29 5-30 5-31 5-32 5-34 5-35 5-36 5-37

Extending the Editor Lesson 6 overview The ArcMap Editor Types of Editor customizations Editor components Custom Editor tools Editor load cycle Editor tools: Implementation details Editor tools: Accessing the Editor Custom editor tools: Editor events IEditEvents: Session and operation events IEditEvents: Environment change events IEditEvents: Reacting to draw events Custom editor tools: Other important concepts Creating custom sketch tools Sketch tools: Framework/Background Sketch tools: Accessing the geometry Custom sketch tools: Using DisplayFeedback Custom sketch tools: Working with the sketch Custom sketch tools: Working with the sketch cont. Editor sketch tools: Context menus Creating custom Editor extensions Editor extensions: Framework/Background Creating custom edit tasks

6-2 6-3 6-4 6-5 6-6 6-7 6-8 6-9 6-10 6-11 6-12 6-13 6-14 6-15 6-16 6-17 6-18 6-20 6-21 6-22 6-23 6-24 6-25

Copyright © 2005-2006 ESRI

Contents

Edit tasks: Framework/Background Edit tasks: Implementation details IEditTask: Activating and deactivating IEditTask: Working with the sketch Edit tasks: Other important concepts Exercise 6 overview Lesson 6 review Exercise 6A: Extending the Editor (VB6) Exercise 6B: Extending the Editor (VB.NET) Exercise 6C: Extending the editor (C#)

7

6-26 6-27 6-28 6-29 6-30 6-31 6-32

Extending the Geodatabase Lesson 7 overview What is a geodatabase? Geodatabase terminology Levels of geodatabase customization Class extensions Class extensions: Framework/Background Geodatabase vs application customization Class extensions: Implementation details Class extensions: Accessing the class IObjectClassEvents: Access object events IObjectClassEvents: Listening to edits IFeatureClassDraw: Custom drawing Custom renderers: Implementation details IFeatureRenderer: Custom drawing Custom object inspectors Custom object inspector: Implementation details Registering class extensions with the geodatabase Registration with the geodatabase using ArcObjects Storing custom data Retrieving custom data Exercise 7 overview Lesson 7 review Exercise 7A: Extending the geodatabase (VB6) Exercise 7B: Extending the geodatabase (VB.NET) Exercise 7C: Extending the geodatabase (C#)

Copyright © 2005-2006 ESRI

7-2 7-3 7-4 7-5 7-6 7-7 7-8 7-9 7-10 7-11 7-12 7-13 7-14 7-15 7-16 7-17 7-18 7-19 7-20 7-21 7-22 7-23

vii

Extending the ArcGIS Desktop Applications

viii

8

Building Geoprocessing Function Tools

9

Deployment

Lesson 8 overview ArcGIS geoprocessing application framework Creating custom geoprocessing tools Geoprocessing tools vs commands Geoprocessing: Framework/Background Invoking existing tool dialog boxes Executing existing tools Types of geoprocessing tools Geoprocessing tools: Implementation details IGPFunctionFactory IGPFunction IGPFunction:: ParameterInfo IGPParameterEdit Parameter values Data types IGPFunction::Validate GPUtilities GPUtilities::InternalValidate IGPFunction::Validate IGPFunction::Execute GPMessages Other topics: GPToolExtension Exercise 8 overview Lesson 8 review Exercise 8A: Building GP function tools (VB6) Exercise 8B: Building GP function tools (VB.NET) Exercise 8C: Building GP function tools (C#)

Lesson 9 overview Deployment requirements: End user Deployment requirements: Developer ArcGIS version and license information Installing and registering COM components (VB6) VB6 Package and Deployment Wizard Registering with component categories .NET Setup Projects

Contents

8-2 8-3 8-4 8-5 8-6 8-7 8-8 8-9 8-10 8-11 8-12 8-13 8-14 8-16 8-17 8-18 8-19 8-20 8-21 8-22 8-24 8-25 8-26 8-27

9-2 9-3 9-4 9-5 9-6 9-7 9-8 9-9

Copyright © 2005-2006 ESRI

Contents

.NET installer classes .NET Framework 2.0 requirement Exercise 9 overview (.Net only) Lesson 9 review Exercise 9A: Exercise 9 overview (.Net only) Exercise 9B: Creating a .Net install program (VB.NET) Exercise 9C: Creating a .Net install program (C#)

10 11

9-10 9-11 9-12 9-13 9-12

Course conclusion Course objectives ESRI educational support Where do you go from here? Course evaluation Thank you for attending

10-2 10-3 10-4 10-5 10-6

Appendix A: ArcGIS Developer Resources and Developing Custom Components with VB6 Overview ArcGIS core libraries (COM) ArcGIS core libraries (.NET) Organization of the ArcGIS libraries ArcGIS Controls Library ArcGIS Developer Kit Overview of the ArcGIS developer help Getting started with the developer help Learning about the APIs Getting language-specific help Learning about the libraries Use the samples and walkthroughs Explore the Object Model Diagrams Developer tools Other developer resources Overview Creating custom components: Visual Basic 6 Step 1: Create a COM project Step 2: Create a COM class Step 3: Reference ArcGIS libraries Step 4: Implement an ArcObjects interface

Copyright © 2005-2006 ESRI

11-2 11-3 11-4 11-5 11-6 11-8 11-9 11-10 11-11 11-12 11-13 11-14 11-15 11-16 11-17 11-18 11-19 11-20 11-21 11-22 11-23

ix