ArcGIS Engine Developer Guide

524 Pages·2004·6.55 MB·English

ArcGIS® Engine Developer Guide
ArcGIS® 9.1
PUBLISHED BY
ESRI
380 New York Street
Redlands, California 92373-8100
Copyright © 2004 ESRI ESRI, ArcView, ArcIMS, SDE, Spatial Database Engine, the ESRI globe
All rights reserved. logo, ArcObjects, ArcGIS, ArcMap, ArcCatalog, ArcScene, ArcInfo, ArcEditor,
Printed in the United States of America. ArcGlobe, ArcReader, ArcToolbox, 3D Analyst, ArcSDE, GIS by ESRI,
the ArcGIS logo, www.esri.com, and @esri.com are trademarks, registered
The information contained in this document is the exclusive property of trademarks, or service marks of ESRI in the United States, the European
ESRI. This work is protected under United States copyright law and Community, or certain other jurisdictions.
other copyright treaties and conventions. No part of this work may be
reproduced or transmitted in any form or by any means, electronic or Other companies and products mentioned herein are trademarks or
mechanical, including photocopying and recording, or by any information registered trademarks of their respective trademark owners.
storage or retrieval system, except as expressly permitted in writing by
ESRI. All requests should be sent to Attention: Contracts Manager, ESRI,
380 New York Street, Redlands, California 92373-8100, USA.
The information contained in this document is subject to change without
notice.
CCCCCooooonnnnntttttrrrrriiiiibbbbbuuuuutttttiiiiinnnnnggggg WWWWWrrrrriiiiittttteeeeerrrrrsssss
Euan Cameron, Chris Davies, Rob Elkins, Kylie Evans, Anne
Frankland, Shelly Gill, Natalie Hansen, Sean Jones, Allan
Laframboise, Glenn Meister, Dan O’Neill, Rohit Singh, Steve
Van Esch, Zhiqian Yu, and Mark Zollinger
UUUUU.....SSSSS..... GGGGGOOOOOVVVVVEEEEERRRRRNNNNNMMMMMEEEEENNNNNTTTTT RRRRREEEEESSSSSTTTTTRRRRRIIIIICCCCCTTTTTEEEEEDDDDD/////LLLLLIIIIIMMMMMIIIIITTTTTEEEEEDDDDD RRRRRIIIIIGGGGGHHHHHTTTTTSSSSS
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, California 92373-8100, USA.
Attribution.pmd 1 1/25/2005, 3:24 PM
Contents
CHAPTER 1: INTRODUCING ARCGIS ENGINE....................................................1
ArcGIS 9 overview...............................................................................................................................2
Overview of ArcGIS Engine..............................................................................................................6
Who can use ArcGIS Engine?.......................................................................................................10
ArcGIS Engine capabilities..............................................................................................................12
Getting started..................................................................................................................................16
Using this book..................................................................................................................................19
Developer resources........................................................................................................................20
CHAPTER 2: ARCGIS SOFTWARE ARCHITECTURE...........................................23
ArcGIS software architecture.......................................................................................................24
ArcGIS application programming interfaces.............................................................................29
ArcGIS Engine libraries....................................................................................................................32
CHAPTER 3: DEVELOPING WITH ARCGIS CONTROLS.................................41
Working with the ArcGIS controls..............................................................................................42
Building applications with the ArcGIS controls.......................................................................50
CHAPTER 4: DEVELOPER ENVIRONMENTS........................................................57
The Microsoft Component Object Model...............................................................................58
Developing with ArcObjects..........................................................................................................70
The Visual Basic 6 environment....................................................................................................79
The Visual Basic 6 development environment..........................................................................92
Visual C++...........................................................................................................................................99
.NET application programming interface................................................................................141
Java application programming interface...................................................................................182
C++ application programming interface..................................................................................197
CHAPTER 5: LICENSING AND DEPLOYMENT................................................253
ArcGIS licensing options...............................................................................................................254
ArcGIS Engine Developer Kit......................................................................................................261
Application development and license initialization...............................................................286
Testing with ArcGIS Engine Runtime........................................................................................274
Deployment......................................................................................................................................277
CHAPTER 6: DEVELOPER SCENARIOS................................................................281
Building applications with ActiveX............................................................................................282
Building applications with visual JavaBeans.............................................................................304
Building applications with Windows Controls.......................................................................331
Building applications with C++ and control widgets...........................................................357
Building a command-line Java application................................................................................409
Building a command-line C++ application...............................................................................427
Toc.pmd 3 1/25/2005, 5:02 PM
APPENDIX A: READING THE OBJECT MODEL DIAGRAMS.....................441
Object model key............................................................................................................................442
Classes and relationships..............................................................................................................443
Interfaces and members................................................................................................................446
Putting it together—An example..............................................................................................449
APPENDIX B: ARCGIS DEVELOPER RESOURCES ............................................451
ArcGIS software developer kit....................................................................................................452
ArcGIS Developer Online Web site...........................................................................................454
APPENDIX C: CONVERTING PERSONAL GEODATABASES.....................457
Converting data for use with the GIS Server on UNIX.....................................................458
APPENDIX D: INSTALLING ARCGIS ENGINE RUNTIME ON
WINDOWS, SOLARIS, AND LINUX............................................................463
Installing ArcGIS Engine Runtime on Windows.....................................................................464
Installing ArcGIS Engine Runtime on Solaris and Linux......................................................479
GLOSSARY..........................................................................................................................491
INDEX .................................................................................................................................507
iv • ArcGIS Engine Developer Guide
Toc.pmd 4 1/25/2005, 5:02 PM
1
Introducing
ArcGIS Engine
ESRI® ArcGIS® Engine is a platform for building custom standalone geographic
information system (GIS) applications that support multiple application
programming interfaces (APIs), include advanced GIS functionality, and are built
using industry standards.
This chapter will introduce you, the developer, to the ArcGIS Engine developer kit
and the ArcGIS Engine Runtime, discussing how to use it and its different
components.
Topics covered in this chapter include:
(cid:127) an overview of ArcGIS 9 (cid:127) introduction to ArcGIS Engine (cid:127) ArcGIS Engine
users (cid:127) capabilities of ArcGIS Engine (cid:127) a description of this book
Ch01_Intro.pmd 1 1/25/2005, 3:14 PM
ARCGIS 9 OVERVIEW
ArcGIS provides a scalable framework for implementing GIS for a single user or
for many users on desktops and servers. This book focuses on building and de-
Developers wanting to customize ArcGIS
Desktop applications or work with ArcGIS Server ploying custom applications using ArcGIS Engine. It will be of greatest use to
should refer to the ArcGIS Desktop Devel- developers who want to embed mapping and GIS functionality in custom appli-
oper Guide and the ArcGIS Server Adminis- cations. It provides an overview of ArcGIS Engine, its components, and the
trator and Developer Guide.
possibilities ArcGIS Engine offers developers who want to build and deploy
custom GIS applications and solutions. In addition, several scenarios are used to
illustrate, with code examples, the various types of applications that can be
developed with ArcGIS Engine.
AN OVERVIEW OF ARCGIS 9
ArcGIS 9 is an integrated family of GIS software products for building a com-
plete GIS. It is based on a common library of shared GIS software components
called ArcObjects™. ArcGIS 9 consists of four key parts:
• ArcGIS Desktop—an integrated suite of advanced GIS applications.
• ArcGIS Engine—embeddable GIS component libraries for building custom
applications using multiple application programming interfaces.
• ArcGIS Server—a platform for building server-side GIS applications in enter-
prise and Web computing frameworks. Used for building both Web services
and Web applications.
• ArcIMS®—GIS Web server to publish maps, data, and metadata through open
Internet protocols.
2 • ArcGIS Engine Developer Guide
Ch01_Intro.pmd 2 1/25/2005, 3:14 PM
ARCGIS 9 OVERVIEW
Each of the GIS frameworks also includes the ArcSDE® gateway, an interface for
managing geodatabases in numerous relational database management systems
(RDBMS).
ArcGIS is a platform for building geographic information systems. ArcGIS 9
extends 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.
There is a wide range of possibilities when developing with ArcGIS. Developers
can:
• 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.
• Build and deploy custom desktop applications with ArcGIS Engine.
• Build Web services and applications with ArcGIS Server.
The ArcGIS system is built and extended using software components called
ArcObjects. ArcObjects includes a wide variety of programmable components
ranging from fine-grained objects, such as individual geometry objects, to coarse-
grained objects, such as a map
object, that can be used to interact
with existing ArcMap documents.
ArcGIS These components aggregate com-
Engine prehensive GIS functionality for
developers.
ArcGIS 9 has a common developer
experience across all ArcGIS prod-
ArcGIS ucts (Engine, Server, and Desktop).
You, as a developer, can work with
Server
ArcObjects using standard pro-
gramming frameworks to extend
ArcGIS Desktop, build custom
applications with ArcGIS Engine,
and implement enterprise GIS
applications using ArcGIS Server.
As noted previously, this book
ArcObjects
focuses on building and deploying
ArcGIS custom applications using ArcGIS
Desktop Engine. If you want to customize
ArcGIS Desktop applications or
work with ArcGIS Server, refer to
the ArcGIS Desktop Developer Guide
and the ArcGIS Server Administrator
and Developer Guide.
Chapter 1 (cid:127) Introducing ArcGIS Engine (cid:127) 3
Ch01_Intro.pmd 3 1/25/2005, 3:15 PM
ARCGIS 9 OVERVIEW
The ArcGIS system is available in a number of programming frameworks includ-
ing C++, Component Object Model (COM), .NET, and Java™.
Each of the ArcGIS product architectures built with ArcObjects represents
alternative application development containers for GIS software developers,
including desktops, embeddable engines, and servers.
ArcGIS Desktop ArcGIS Mobile GIS Application
Engine Applications servers
ArcView ArcInfo
ArcGIS Server
ArcGIS PDA
Custom
Clients
applications ArcIMS
Tablet
ArcReader ArcEditor PC
ArcSDE
Desktop ArcEngine ArcGIS Server
Components Developer Kit Developer Kit Developer Kit
ArcObjects
Numerous
Data File-based DBMS
data types XML
ArcGIS Desktop includes a series of Windows® desktop application frameworks
(for example, applications for map, catalog, toolbox, and globes) with user inter-
face (UI) components. 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 software developer kit (SDK) for ArcGIS Desktop is included with
ArcView, ArcEditor, and ArcInfo and supports the COM and .NET programming
frameworks. Many developers apply the ArcGIS Desktop SDK to add extended
functions, new GIS tools, custom user interfaces, and full extensions for improv-
ing professional GIS productivity of the ArcGIS Desktop applications.
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.
4 (cid:127) ArcGIS Engine Developer Guide
Ch01_Intro.pmd 4 1/25/2005, 3:15 PM
ARCGIS 9 OVERVIEW
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.
ArcGIS Engine, the focus of this guide, is a simple, application-neutral program-
ming environment for ArcObjects. Its SDK provides a series of embeddable
ArcGIS components that are used outside the ArcGIS Desktop application
framework—for example, mapping objects are managed as a part of ArcGIS
Engine, rather than in ArcMap. Using the ArcGIS Engine Developer Kit, devel-
opers can build focused GIS solutions with simple interfaces to access any set of
ArcGIS Engine and its developer resources will
be discussed in more detail later in this chapter GIS functions or embed GIS logic in existing user applications to deploy GIS to
and throughout this book. broad groups of users.
Chapter 1 (cid:127) Introducing ArcGIS Engine (cid:127) 5
Ch01_Intro.pmd 5 1/25/2005, 3:15 PM
OVERVIEW OF ARCGIS ENGINE
ArcGIS Engine is a complete library of embeddable GIS components for
developers to build custom applications. Using ArcGIS Engine, you can
embed GIS functions into
existing applications, including
Microsoft® Office products,
ArcGIS Engine Developer Kit and Runtime used
such as Word and Excel, and
to build and deploy a custom solution to many
users. build focused custom applica-
tions that deliver advanced
GIS systems to many users.
ArcGIS Engine consists of a
software developer kit and a
redistributable runtime provid-
ing the platform for all ArcGIS
applications. Since ArcGIS
Engine is supported on
Windows, Solaris, and Linux
(Intel), developers can create
cross-platform custom solu-
tions for a wide range of users.
The five parts of ArcGIS Engine
Extensions are outlined below:

1. Base Services—The core GIS
ArcObjects required for
Developer
almost any GIS application,
Components such as feature geometry and
display.
2. Data Access—ArcGIS Engine provides access to a wide variety of raster and
Map
vector formats including the power and flexibility of the geodatabase.
Presentation
3. Map Presentation—ArcObjects for map creation and display with symbology,
labeling, and thematic mapping capabilities including custom applications.
Data 4. Developer Components—High-level user interface controls for rapid applica-
Access tion development and a comprehensive help system for effective development.
5. Extensions—ArcGIS Engine Runtime is deployable with the standard func-
tionality or with additional extensions for advanced functionality.
Base
Each of these parts, including the extension functionality, is made available
Services
through the ArcGIS Engine Developer Kit. The ArcGIS Engine Runtime and its
extensions, although integral factors in the development of a custom GIS appli-
Components of ArcGIS Engine cation, specifically involve application deployment and are, therefore, considered
separately.
ARCGIS ENGINE DEVELOPER KIT
The ArcGIS Engine Developer Kit is a component-based software development
product for building and deploying custom GIS and mapping applications. The
ArcGIS Engine Developer Kit is not an end user product, but rather a toolkit for
application developers. It can be used to build basic map viewers or comprehen-
sive and dynamic GIS editing tools. With the ArcGIS Engine Developer Kit, you,
as a developer, have an unprecedented flexibility for creating customized inter-
6 (cid:127) ArcGIS Engine Developer Guide
Ch01_Intro.pmd 6 1/25/2005, 3:15 PM