1 1 1 1 1 1 Introducing ArcGIS Desktop development The ESRI ® ArcGIS ® Desktop Developer Guide is an introduction for anyone who wants to customize or extend ArcGIS Desktop applications, such as ArcMap" or ArcCatalog". This chapter introduces the ArcGIS Desktop development environment in the context of the ArcGIS product family. Topics covered in this chapter include an ArcGIS 9 developer overview, an ArcGIS Desktop developer overview, using this guide, and ArcGIS developer resources.
2 " ArcGIS Desktop Developer Guide ArcGIS 9 is an integrated family of geographic information system (GIS) soft- ware products for building a complete GIS. It is based on a common library of shared GIS software components called ArcObjects". ArcGIS 9 consists of four key parts: Desktop GIS , an integrated suite of advanced GIS applications.
" Embedded GIS , embeddable GIS component libraries for building custom applications using C++, COM, .NET, and Java". " Server GIS , a shared library of GIS software objects used to build server-side GIS applications in enterprise and Web computing frameworks. Used for building both SOAP-based Web services and Web applications using .NET/ ASP and Java/ JSP.
" Mobile GIS , GIS Web services to publish maps, data, and metadata through ... more. less.
open Internet protocols. ArcSDE ® Gateway is an interface for managing geodatabases in numerous rela- tional database management systems (RDBMSs). A RC GIS 9 DEVELOPER OVERVIEW Chapter 1 " Introducing ArcGIS Desktop development " 3 ArcGIS provides a scalable framework for implementing GIS for a single user or for many users on desktops and servers.<br><br> This book will be of greatest use to developers who want to use the ArcGIS Desktop Developer Kit to customize and extend the ArcView ® , ArcEditor", or ArcInfo ® desktop products. This book provides a general explanation of the options and opportunities available to developers with ArcGIS Desktop. Several scenarios will illustrate with code examples the different types of customization that can be developed with the ArcGIS Desktop Developer Kit.<br><br> ArcGIS is a platform for building geographic information systems. ArcGIS 9 will extend the system with major new capabilities in the areas of geoprocessing, 3D visualization, and developer tools. ArcGIS Engine and ArcGIS Server, developer- centric products, make ArcGIS a complete system for application and server development.<br><br> There is a wide range of possibilities when developing with ArcGIS, including the following: Configure/ Customize ArcGIS applications, such as ArcMap and ArcCatalog. " Extend the ArcGIS architecture and data model. " Embed maps and GIS functionality in other applications with ArcGIS Engine.<br><br> " Build and deploy custom desktop applications with ArcGIS Engine. " Build Web services and applications with ArcGIS Server. ArcGIS 9 has a common developer experience across all ArcGIS products (Engine, Server, and Desktop).<br><br> This book focuses on customizing and extending the ArcGIS Desktop applications. Developers wanting to build custom standalone applications or work with ArcGIS Server should refer to the A rcGIS Engine Developer Guide and the A rcGIS Server A dministration and Development Guide , respectively. The ArcGIS system is built and extended using ArcObjects software components.<br><br> ArcObjects includes a wide variety of programmable c omponents, ranging from fine-grained objects (for example, individual geometry objects) to coarse-grained objects (for example, a map object to interact with existing ArcMap documents), which aggregate comprehensive GIS functionality for developers. Developers work with ArcObjects using standard program- ming frameworks to extend ArcGIS Desktop, build custom applications with ArcGIS Engine, and implement server GIS applications for various enterprise purposes using ArcGIS Server. A RC GIS 9 DEVELOPER OVERVIEW ArcObjects ArcGIS Desktop ArcGIS Server ArcGIS Engine 4 " ArcGIS Desktop Developer Guide A RC GIS 9 DEVELOPER OVERVIEW Each of the ArcGIS product architectures built with ArcObjects represents alternative application development containers for GIS software developers, including desktops, embeddable engines, and servers.<br><br> A RC GIS SOFTWARE DEVELOPER KITS The ArcGIS Engine, Server, and Desktop have software developer kits (SDK) for working with ArcObjects. The developer kits provide everything needed to be successful with ArcObjects, including developer documentation, samples, and object model diagrams. The ArcGIS Desktop Developer Kit ArcGIS Desktop includes a series of Windows ® desktop application frame- works 4ArcMap, ArcCatalog, ArcToolbox" 4and more, each with user inter- face (UI) components.<br><br> ArcGIS Desktop is available at three functional levels (ArcView, ArcEditor, and ArcInfo) and can be customized and extended using the ArcGIS Desktop Developer Kit. The ArcGIS Desktop Developer Kit is included with ArcView, ArcEditor, and ArcInfo and supports the COM and .NET programming frameworks. Many users apply the ArcGIS Desktop Developer Kit to add extended functions, new GIS tools, custom user interfaces, and full extensions for improving professional GIS productivity of ArcGIS Desktop.<br><br> The ArcGIS Engine Developer Kit ArcGIS Engine is a simple, application-neutral programming environment for ArcObjects. The ArcGIS Engine Developer Kit is a separate product that pro- vides a series of embeddable ArcGIS components that are used outside the ArcGIS 9 DBMS Desktop GIS Embedded GIS Server GIS ArcGIS Desktop Geodatabase ArcSDE Mobile GIS ArcGIS Server ArcIMS ArcGIS Mobile ArcPad Desktop Developer Kit Engine Developer Kit Server Developer Kits .NET COM .NET C++ COM Java Java ADF .NET ADF ArcView ArcEditor ArcReader ArcInfo + ArcGIS Extensions File-based XML PEI Compact Framework Component Building Blocks Desktop Server Web Custom Applications ArcGIS Engine Web Templates Custom Templates ArcObjects Mobile Developer Kit ADF Developer Kit Server Developer Kit .NET COM Java Chapter 1 " Introducing ArcGIS Desktop development " 5 A RC GIS 9 DEVELOPER OVERVIEW ArcGIS Desktop application framework (for example, mapping objects are managed as part of ArcGIS Engine, rather than in ArcMap). Using the ArcGIS Engine Developer Kit, developers build focused GIS solutions with simple interfaces to access any set of GIS functions or can embed GIS logic in existing user applications to deploy GIS to broad groups of users.<br><br> ArcGIS Engine has a COM, .NET, Java, and C++ application programming interface (API) for devel- opers. The ArcGIS Server Developer Kit ArcGIS Server defines and implements a set of standard GIS Web services (for example, mapping, data access, and geocoding), as well as supports enterprise- level application development based on ArcObjects for the server. The ArcGIS Server Developer Kit enables developers to build central GIS servers to host GIS functions that are accessed by many users, perform back office pro- cessing on large central GIS databases, build and deliver GIS Web applications, and perform distributed GIS computing.<br><br> 6 " ArcGIS Desktop Developer Guide ArcGIS Desktop includes a suite of integrated applications, including ArcMap, ArcCatalog, and ArcToolbox. By using these applications and interfaces in unison, you can perform any GIS task, simple to advanced, including mapping, geographic analysis, data editing and compilation, data management, visualization, and geoprocessing. WHAT ARE A RC V IEW , A RC E DITOR , AND A RC I NFO ?<br><br> ArcGIS Desktop is the information authoring and usage tool for GIS profession- als. It is scalable as three separate software products to meet the needs of many types of users. ArcView provides comprehensive mapping and analysis tools along with simple editing and geoprocessing.<br><br> ArcEditor includes advanced editing capabilities for shapefiles and geodatabases in addition to the full functionality of ArcView. ArcInfo is the flagship ArcGIS Desktop product. It builds on the functionality of ArcEditor with advanced geoprocessing.<br><br> It also includes the legacy applica- tions for ArcInfo Workstation. Because ArcView, ArcEditor, and ArcInfo all share a common architecture, users working with any of these GIS desktops can share their work with other users. Maps, data, symbology, map layers, custom tools and interfaces, reports, metadata, and so on, can be accessed interchangeably in all three products.<br><br> This means that you benefit from using a single architecture, minimizing the need to learn and deploy several different architectures. New capabilities can be added to all seats through a series of ArcGIS Desktop extensions from ESRI and other organizations. Users can also develop their own custom extensions to ArcGIS Desktop by working with ArcObjects, the ArcGIS software component library.<br><br> Users develop extensions and custom tools using standard Windows programming interfaces, such as COM and .NET. ArcObjects is a framework that lets you create domain-specific components from other components. The ArcObjects components collaborate to serve every data management and map presentation function common to most GIS applications.<br><br> ArcObjects provides an infrastructure for application customization that lets you concentrate on serving the specific needs of your clients. ArcMap ArcMap is the central application in ArcGIS Desktop. It is the GIS application used for all map-based tasks, including cartography, map analysis, and editing.<br><br> In this application, you work with maps. Maps have a page layout containing a geographic window, or a data frame, with a series of layers, legends, scalebars, North arrows, and other elements. ArcMap offers different ways to view a map 9s geographic data and layout views in which you can perform a broad range of advanced GIS tasks.<br><br> A RC GIS D ESKTOP DEVELOPER OVERVIEW ArcMap is used for mapping and editing tasks as well as map-based analysis. Chapter 1 " Introducing ArcGIS Desktop development " 7 ArcCatalog The ArcCatalog application helps you organize and manage all of your GIS infor- mation (maps, globes, datasets, models, metadata, services, and so on). It includes tools to: " Browse and find geographic information.<br><br> " Record, view, and manage metadata. " Define geodatabase schemas and designs. " Administer an ArcGIS Server.<br><br> " Search for and discover GIS data on local networks and the Web. GIS users apply ArcCatalog to organize, find, and use GIS data as well as to document their data holdings using standards-based metadata. A GIS database administrator uses ArcCatalog to define and build geodatabases.<br><br> A GIS server administrator uses ArcCatalog to administer the GIS server framework. Customizing ArcGIS Desktop applications You may want the ArcMap and ArcCatalog interfaces to reflect your own prefer- ences and the way you work. You can customize ArcMap and ArcCatalog in many ways.<br><br> Here are some ex- amples: " Position toolbars in a specific area of the application. " Group commands in a way that works best for you. " Add new macros or load custom commands from another source.<br><br> " Always work with the same geographic data (via templates). If you work in a larger organization, others may want you to develop a customized work environ- ment for them. You can handle many customization tasks without writing a single line of code.<br><br> In fact, you may be able to instruct others on how to use the customization environment to create the look and feel they want on their own. You can change or create toolbars, menus, shortcut keys, and so on, to help you do your work in the most efficient way. You can provide additional functionality by linking code you or others have written to menu commands or tools.<br><br> Several toolbars are provided with ArcMap and ArcCatalog, but you may want to create new toolbars to organize commands that you often use together or to contain buttons that run your custom scripts. A RC GIS D ESKTOP DEVELOPER OVERVIEW ArcCatalog is used for managing your spatial data holdings, defining your geographic data schemas, and recording and viewing metadata. The Customize dialog box is used to create new toolbars and add or remove controls.<br><br> 8 " ArcGIS Desktop Developer Guide Writing VBA macros in ArcGIS applications Both ArcMap and ArcCatalog come with Visual Basic ® for Applications (VBA). VBA is not a standalone program; it 9s embedded in the applications. It provides an integrated programming environment, the Visual Basic Editor (VBE), which lets you write a Visual Basic (VB) macro, then debug and test it right away in ArcMap or ArcCatalog.<br><br> A macro can integrate some or all of VB 9s functionality, such as using message boxes for input, with the extensive object library that ArcMap and ArcCatalog expose. The ESRI object libraries are always available to you in the VBA environment. There is an easy way to create custom commands with VBA.<br><br> You can create a new button, tool, combo box, or edit box (collectively called UIControls), then attach code to the control 9s events, such as what happens when you click a but- ton. After you have created it, you can drag this new control onto a toolbar. As mentioned, you should start development by using the VBA environment in one of the existing ArcGIS applications.<br><br> VBA is a simple programming language with many utilities, such as design time code completion and the Object Browser that will help you assemble code quickly. Here are more reasons to choose the VBA environment: " It 9s fast and easy to create, test, and debug macros inside ArcMap and ArcCatalog. " The standard ESRI type libraries are already referenced for you.<br><br> " Important global variables, such as the Applica- tion and Document, are available. " It 9s simple to assemble UI forms using VBA and ActiveX ® components. " It 9s straightforward to integrate VBA code with new ArcObjects UIControls.<br><br> " It 9s relatively easy to migrate VBA code to VB ActiveX Dynamic Link Library (DLL) projects. " Many code samples available in the help system are macros that can be cut, pasted, and run within the VBA environment. Writing custom components to extend the ArcGIS Desktop applications You don 9t have to use VBA to create custom commands and toolbars 4in fact, in some cases, your custom commands and toolbars may require you to use another development environment.<br><br> You can create custom objects in any programming language that supports the Microsoft ® Component Object Model. Custom com- mands or toolbars created outside VBA are often distributed as ActiveX DLLs. If you have created some custom commands and toolbars, or someone else has given you an ActiveX DLL containing custom commands and toolbars, you can easily add these objects to ArcMap or ArcCatalog.<br><br> After adding a custom object to ArcMap or ArcCatalog, you can use it as you would any built-in command or toolbar. A RC GIS D ESKTOP DEVELOPER OVERVIEW A buffer command created in VBA Chapter 1 " Introducing ArcGIS Desktop development " 9 If you want to use a programming language other than VBA, or if you want to package ArcObjects functionality into a COM DLL, EXE, OCX, or .NET assem- bly, you will have to work outside the VBA development environment. This approach generally requires creating a project, referencing the ArcObjects type libraries required, implementing ArcObjects interfaces, adding code, then compil- ing the source into a binary file.<br><br> Following are some advantages of building custom components: " They can be easily delivered to end users via custom setup programs. " You can hide your code and logic in a binary file. " You can extend and customize virtually every aspect of the ArcGIS technol- ogy.<br><br> Components can be broadly categorized into two areas of customization: those that reside at the application level, such as custom buttons, toolbars, windows, and extensions, and those that reside at the geodatabase level, such as custom feature class extensions and features. Some of these more advanced customizations cannot be accomplished through the VBA environment. A RC GIS D ESKTOP DEVELOPER OVERVIEW The Production Line Tool Set (PLTS) is an example of a complex application extension created with ArcObjects.<br><br> 10 " ArcGIS Desktop Developer Guide The A rcGIS Desktop Developer Guide is an introduction for anyone who wants to customize or extend the ArcGIS Desktop applications, such as ArcMap or ArcCatalog. This guide will help you become a desktop developer by walking you through numerous VBA code samples and providing a problem-solving guide and devel- oper scenarios. Although the samples documented in this guide may not solve your immediate problem, they will serve as a framework or template on which you can build a more specific or complex solution.<br><br> To serve the greatest base of developers, most of the code samples in this guide are written in VBA. As necessary, some code samples are written in Microsoft Visual Basic, VB .NET, or Visual C++ ® . CHAPTER GUIDE Chapter 1, 8Introducing ArcGIS Desktop development 9, gives you an overview of the ArcGIS 9 product family, the desktop developer framework, the types of customizations that can be made, and additional resources.<br><br> Chapter 2, 8ArcGIS software architecture 9, describes the underlying technology used to create the ArcGIS Desktop products, ArcObjects, and the software architecture common to the ArcGIS product family. Chapter 3, 8Developing for ArcGIS Desktop applications 9, guides you through the basics of ArcGIS Desktop development. The chapter begins with some desktop application framework theory, then walks you through some small tutorials for toolbar customization and VBA macro writing.<br><br> The chapter concludes with the theory and steps in creating custom components that extend the ArcGIS Desktop framework. Chapter 4, 8Licensing and deployment 9, discusses license considerations when developing your customizations and how to package and deploy your customizations, including VBA macros and components, to other users. Chapter 5, 8Developer scenarios 9, guides you through the creation of several types of components that can plug into the ArcGIS Desktop applications.<br><br> Appendix A, 8Developer environments 9, describes in more detail the Microsoft Component Object Model, the foundation for ArcObjects, and continues with a language reference guide for each API supported by ArcGIS. These guides discuss issues and considerations while developing ArcGIS with a particular API. Appendix B, 8Reading the object model diagrams 9, discusses how to read and interpret the ArcGIS object model diagrams.<br><br> Understanding the structure and relationships of ArcObjects represented in these diagrams is essential in ArcGIS development. Appendix C, 8Illustrated code samples 9, shows numerous VBA code snippets for some common desktop applications. These are illustrated with components from the ArcGIS object model to help you understand the structure and relationships.<br><br> Appendix D, 8ArcObjects problem-solving guide, 9 presents a methodology to help you solve real-world ArcObjects programming tasks that customize or extend the ArcGIS Desktop applications. U SING THIS GUIDE Chapter 1 " Introducing ArcGIS Desktop development " 11 Appendix E, 8UIControls 9, shows class and interface diagrams for UIControls, which are VBA-based commands with interfaces available only in VBA. Appendix F, 8Bibliography 9, is not intended as a complete resource, but it does contain many of the everyday references that ESRI developers use when devel- oping Visual Basic, Visual C++, Visual Studio .NET code, and ArcObjects.<br><br> U SING THIS GUIDE 12 " ArcGIS Desktop Developer Guide The following topics describe some of the additional resources available to you as a developer. These include books and guides and various help systems. A RC GIS SOFTWARE DEVELOPER KIT The ArcGIS Developer Kit is a collection of diagrams, utilities, add-ins, samples, and documentation geared to help developers implement custom ArcGIS func- tionality.<br><br> ArcGIS Developer Help system The ArcGIS Developer Help system is the gateway to all developer documenta- tion, including help for the add-ins, developer tools, and samples; in addition, it serves as the complete syntactical reference for all object libraries. Each supported API has a version of the help system that works in concert with it. Regardless of the API you choose to use, you will see the appropriate library reference syntax and have a help system that is integrated with your development environment.<br><br> For example, if you are a Visual Basic 6 developer, you will use ArcGISDevHelp.chm, which has the VB6 syntax and integrates with the VB6 integrated development environment (IDE), thereby providing F1 help support in the Code window. The help systems reside in the DeveloperKit\ Help folder but are typically launched from the Start menu or F1 Help in Visual Basic 6 and Visual Studio .NET 2003. The graphic below shows the Start menu options for opening the help systems.<br><br> Samples The ArcGIS Desktop Developer Kit contains more than 600 samples, many of which are written in several languages. The samples are described in the help system, and source code and project files are installed in the DeveloperKit\ samples folder. The help system 9s table of contents for the samples section mirrors the samples directory structure.<br><br> The help system organizes samples by functionality. For example, all the geodatabase samples are grouped under Samples\ Geodatabase. Most first-tier groupings are further subdivided.<br><br> You can also find samples in the SDK using the 8Query the Samples 9 topic in the help system, which lists all the samples alpha- betically; in addition, you can sort the list by language. For example, you can elect to only list the available VB6 samples. A typical SDK installation A RC GIS DEVELOPER RESOURCES Chapter 1 " Introducing ArcGIS Desktop development " 13 Installing the sample source code and project files is an option in the Desktop Developer Kit install.<br><br> The samples are installed under the ArcGIS\ DeveloperKit\ samples folder. If you don 9t have this folder on your computer, you can rerun the install program and check Samples under Developer Kit. Developer tools The ArcGIS developer tools are executables that ESRI has provided to facilitate your ArcObjects development.<br><br> For example, if you are a Visual Basic 6 desktop developer, you will likely use the Categories.exe tool to register components in component categories. The list below features some of the more important developer tools available with ArcGIS Desktop. Refer to the help system for more developer tool details and instructions.<br><br> " Component Categories Manager 4Registers components within a specific component category " Library Locator 4Identifies an object library containing a specified interface, coclass, enumeration, or structure " ESRI Object Browser 4Lets you explore the structure of ArcObjects, over- coming certain limitations of other standard object browsers The developer tools are installed in the DeveloperKit\ tools folder. There is one exception 4the Component Category Manager is located in the ArcGIS\ bin folder. A RC GIS DEVELOPER RESOURCES You can use the 8Query the Samples 9 topic in the help system to find specific samples that interest you.<br><br> ESRI Library Locator ESRI Object Browser 14 " ArcGIS Desktop Developer Guide Add-ins The ESRI add-ins automate some of the tasks performed by the software engi- neer when developing with ArcObjects, as well as provide tools that make debug- ging code easier. ESRI provides add-ins for the Visual Basic 6 IDE and the Visual Studio .NET IDE. Listed below are the add-ins available for these development environments.<br><br> Visual Basic 6 " ESRI Align Controls With Tab Index 4 Ensures control creation order matches tab index " ESRI Automatic References 4Automatically adds ArcGIS library references " ESRI Code Converter 4Converts projects from ArcGIS 8.x to ArcGIS 9.x " ESRI Command Creation Wizard 4Facilitates the creation of commands and tools " ESRI Compile and Register 4Aids in compiling components and registering these in desired component categories " ESRI ErrorHandler Generator 4Automates the generation of error handling code " ESRI ErrorHandler Remover 4Removes the error handlers from the source files " ESRI Interface Implementer 4Automatically stubs out implemented inter- faces " ESRI License Initializer 4Automatically generates and adds license initializa- tion code to an ArcObjects project. Visual Studio .NET " ESRI Component Category Registrar 4Stubs out registration functions to enable self-component category registration " ESRI .NET Code Converter 4Converts projects from ArcGIS 8.x to ArcGIS 9.x " ESRI GUID Generator 4Inserts a Global Unique Identifier (GUID) attribute " ESRI Automatic References 4Automatically adds ArcGIS library references. " ESRI License Initializer 4Automatically generates and adds license initializa- tion code to an ArcObjects project.<br><br> The .NET add-ins are automatically installed during setup if a version of Visual Studio .NET 2003 is detected; the Visual Basic 6 add-ins are only installed if you select them on the install. Once installed the add-ins have to be registered manu- ally using the .bat files in the Addins directory. Visual Basic 6 add-ins are only installed if you select them on the install.<br><br> A RC GIS DEVELOPER RESOURCES Chapter 1 " Introducing ArcGIS Desktop development " 15 THE A RC GIS DEVELOPER DOCUMENTATION SERIES This guide is part of the ArcGIS Developer documentation series. The A rcGIS Engine Developer Guide provides information for developers who want to create applications based on ArcGIS Engine. ArcGIS Engine allows you to embed GIS functionality within other applications and create desktop-like applications using the supplied ArcGIS controls, such as MapControl, Toolbar, and PageLayout controls.<br><br> ArcGIS Engine is also based on ArcObjects compo- nents and may be programmed through a number of APIs. The A rcGIS Server A dministrator and Developer Guide is for developers who will create ArcGIS Server applications and customizations. At the core of ArcGIS Server is a rich ArcObjects object library that can be consumed in Web applica- tions and Web services to deliver advanced GIS functionality to a wide range of users who interact with the server through Web browsers and other thin client applications.<br><br> ArcGIS Server may also be programmed through a number of APIs. ESRI DEVELOPER NETWORK ONLINE ESRI Developer Network (EDN) online is the place to find the most up-to-date ArcGIS 9 developer information, including sample code, technical documents, object model diagrams, and the complete object library reference. The Web site is a reflection of the ArcGIS Developer Help system, except it is online and, therefore, more current.<br><br> The Web site has some additional features including an advanced search utility that enables you to control the scope of your searches. For example, you can create a search that only scans the library refer- ence portion of the help system. Visit the site at http:/ / edn.esri.com .<br><br> A RC GIS DEVELOPER RESOURCES 16 " ArcGIS Desktop Developer Guide ESRI SUPPORT CENTER The ESRI Support Center at http:/ / support.esri.com contains software information, technical documents, samples, forums, and a knowledge base for all ArcGIS products. ArcGIS developers can take advantage of the forums, knowledge base, and samples sections in particular to aid in development of their ArcGIS applications. TRAINING ESRI offers a number of instructor-led and Web-based training courses for the ArcGIS Desktop developer.<br><br> These courses range from the introductory level for VBA to more advanced courses in component development with specific APIs. For more information visit http:/ / www.esri.com and click the Training and Events tab. The ESRI Virtual Campus can also be found directly at http:/ / campus.esri.com/ .<br><br> A RC GIS DEVELOPER RESOURCES