Exploring ArcObjects

By Jeff Jackson, ESRI Development Lead

Editor’s Note: With the release of ArcInfo 8, GIS developers can use a new COM-based development technology, ArcObjects, that provides a well-
documented data model with embeddable components. With ArcObjects, developers can customize and extend ArcInfo at the lowest level or construct new
GIS applications. However, derivative applications require an ArcInfo license. ArcMap and ArcCatalog, two new applications available with the release of
ArcInfo 8, are COM based. The author examines the workings of the ArcMap object model to illustrate some of the basic concepts you need to understand
so that you can use ArcObjects. Because Visual Basic for Applications (VBA) is the development environment that comes with ArcInfo 8, the examples in the
article will be in Visual Basic. However, ArcInfo 8 can be customized with any COM-compliant programming language such as Visual C++. This article
assumes that you are conversant with ArcInfo, familiar with object-oriented programming, and have some basic knowledge of COM.

ArcObjects is the collection of COM components that provides Figure 2

the underpinning for two new ArcInfo 8 applications—ArcMap and
ArcCatalog. This set of components includes more than 1,200 objects Sub Zoom()
that may be used to customize, extend, or construct GIS applications. ‘ get the active view
Initially, an object model of this size can seem a little overwhelming. Dim mxDoc As IMxDocument
Taking a close look at the object model for ArcMap will familiarize you Set mxDoc = Application.Document
with some of the fundamental components in the larger object model.
Dim activeView As IActiveView
Set activeView = mxDoc.activeView

MxApplications ‘ get the active view’s extent

Dim ext As IEnvelope
Set ext = activeView.Extent

‘ shrink the extent

MxDocument ext.Expand 0.75, 0.75, True
ActiveView ‘ set the extent
activeView.Extent = ext
FocusMap IActiveView activeView.Refresh
End Sub

Working with Interfaces

In some cases you will want to work specifically with either the Map or
the PageLayout through a different interface. In this situation, a COM-
Map object model differs greatly from a traditional object-oriented model
PageLayout like Avenue or MapObjects. An interface is a collection of related meth-
ods and properties. COM objects expose multiple interfaces. For exam-
Figure 1 ple, the Map exposes not only the IActiveView interface but the IMap
interface and several others.
The Basic Structure
Figure 1 shows a conceptual object model for ArcMap. The top-level Figure 3 shows the Set statement being used to acquire the IMap inter-
object, MxApplication, represents ArcMap itself. MxApplication man- face from the activeView variable. Note that this script uses the TypeOf
ages a single document, MxDocument. ArcMap uses a Single Docu- statement to handle the situation in which the ActiveView is not a Map
ment Interface (SDI) in contrast to ArcView GIS, which uses a Multiple and consequently does not expose the IMap interface. If the TypeOf
Document Interface (MDI). MxDocument manages a collection of Map statement was not used, running the script when the ActiveView is a
objects and a PageLayout object. When ArcMap is in geographic view, PageLayout would result in a type mismatch error when the Set state-
the ActiveView is a Map. When it’s in layout view, the ActiveView is ment was encountered.
the PageLayout. Regardless of the type of view, there is always a single
FocusMap. Figure 3

Sub ClearLayers()
If ArcMap displays a document with three data frames in layout view,
‘ get the active view
there will be three Maps attached to the MxDocument, the ActiveView Dim mxDoc As IMxDocument
property will return the PageLayout, and the FocusMap will return the Set mxDoc = Application.Document
Map corresponding to the data frame that is highlighted. The VBA
script listed in Figure 2 illustrates this part of the object model. The Dim activeView As IActiveView
script changes the ActiveView’s extent and zooms in by 75 percent. Set activeView = mxDoc.activeView

This script is fairly straightforward. The real work is getting the current If TypeOf activeView Is IMap Then
Dim map As IMap
extent, which is an IEnvelope interface, from the ActiveView, shrinking
Set map = activeView ‘ acquire the IMap interface
it, and making the modified envelope the new extent. This script operates
on the ActiveView through the IActiveView interface. The ActiveView map.ClearLayers ‘ remove the layers
can be either the PageLayout or a Map depending on what the end user is mxDoc.UpdateContents ‘ refresh the table of contents
looking at. This script will function correctly in either case. activeView.Refresh ‘ refresh the display
End If
28 ArcUser April—June2000 End Sub www.esri.com
 Developer’s Corner

Looking at ScreenDisplay In the example in Figure 5, note that the drawing calls SetSymbol and
Both the PageLayout and the Map have an associated ScreenDisplay DrawText are bracketed within the StartDrawing and FinishDrawing
object that is used for all graphic rendering. ScreenDisplay maintains a methods.
DisplayTransformation. You can access the properties of DisplayTrans-
formation such as VisibleBounds and use the methods to convert coor- Working with Layers
dinates and distances between map and device units. This is illustrated Maps maintain a collection of layers. A layer is any object that imple-
by the diagram in Figure 4. ments the ILayer interface. Examples of layer objects include Feature-
Layer, GroupLayer, GraphicsLayer, AnnotationLayer, CadLayer, Tin-
Layer, and RasterLayer. The Layer(index) and LayerCount properties
IActiveView of the IMap interface can be used to navigate the layer collection. The
function illustrated in Figure 6 finds and returns the layer with the spec-
ified name.
Figure 6

DisplayTransformation Function FindLayer(map As IMap, name As String)

As ILayer
Dim i As Integer
For i = 0 To map.LayerCount - 1
If map.Layer(i).name = name Then
Set FindLayer = map.Layer(i)
ScreenDisplay Exit Function
End If
Next
Figure 4 End Function
Events such as adding a new layer to the map will cause the ScreenDis- A FeatureLayer manages a connection to a vector data source such as
play to trigger a redraw. The drawing process occurs in three phases. a coverage, shapefile, or Spatial Database Engine (SDE) layer through
The drawing order is the geography, the selection, and the annotation. a FeatureClass object. The script in Figure 7 obtains a FeatureClass
A drawing cache is an off-screen bitmap of the rendered map that is object for a shapefile by opening the Workspace that contains the shape-
stamped onto the screen whenever the window is painted. ScreenDis- file using ShapefileWorkspaceFactory. It then creates a FeatureLayer,
play manages several drawing caches. When you initiate drawing to a attaches the FeatureClass to the layer, and adds it to the FocusMap.
ScreenDisplay you must specify the destination cache. If the constant
esriNoScreenCache is specified, the graphics will draw directly on the Figure 7
ScreenDisplay’s window and will not be cached. If another window
obscures the display, the graphics will be lost. The following script Sub AddLayer()
draws the text “Hello” in the center of the ScreenDisplay using the esri- ‘ use a workspaceFactory to open the workspace
Dim wksFact As IWorkspaceFactory
NoScreenCache constant.
Set wksFact = New ShapefileWorkspaceFactory
Figure 5
Dim wks As IFeatureWorkspace
Set wks = wksFact.OpenFromFile(“c:\Data\shp”, 0)
Private Sub Hello()
Dim mxDoc As IMxDocument
‘ open the featureClass
Set mxDoc = Application.Document
Dim fc As IFeatureClass
Set fc = wks.OpenFeatureClass(“BigCypress”)
Dim activeView As IActiveView
Set activeView = mxDoc.activeView
‘ create a featureLayer
Dim lyr As IFeatureLayer
‘ set up a text symbol to draw with
Set lyr = New FeatureLayer
Dim sym As ITextSymbol
Set lyr.FeatureClass = fc
Set sym = New TextSymbol
‘ name the layer with the featureClass name
‘ change the font size to 18
Dim ds As IDataset
Dim fnt As IFontDisp
Set ds = fc
Set fnt = sym.Font
lyr.Name = ds.Name
fnt.Size = 18
sym.Font = fnt
‘ add the layer to the map
Dim mxDoc As IMxDocument
‘ draw into the active view’s display
Set mxDoc = Application.Document
With activeView.ScreenDisplay
.StartDrawing .hDC, esriNoScreenCache
Dim map As IMap
.SetSymbol sym
Set map = mxDoc.FocusMap
map.AddLayer lyr
Dim bnds As IArea
Set bnds =
End Sub
.DisplayTransformation.VisibleBounds
.DrawText bnds.Centroid, “Hello”

.FinishDrawing Continued on page 30

End With
End Sub
www.esri.com ArcUser April—June 2000 29
 Exploring ArcObjects
Continued from page 29

FeatureLayers manage a feature selection and expose the IFeatureSe- Responding to Events
lection interface to manipulate the selection. The script in Figure 8 Up until now we’ve only considered manipulating ArcObjects using
makes a selection using a logical query with a SQL WHERE clause. scripts that start with the top level object and navigate to the object that
will be manipulated. An interesting aspect of ArcObjects is the ability
Figure 8 to wire into the object model and attach code that will be executed
Sub SelectFeatures() whenever something noteworthy happens such as the map’s selection
Dim mxDoc As IMxDocument changing. Many parts of the object model fire events. COM provides a
Set mxDoc = Application.Document framework for listening and responding to events.
‘ find the layer we’re going to select from
Dim lyr As IFeatureLayer If you are using VBA or Visual Basic, most of the plumbing required
Set lyr = FindLayer(mxDoc.FocusMap, “BigCypress”) to respond to events is done for you behind the scenes. You just have
to write a script for each event you are interested in and a script to
‘ get the layer’s selection interface start listening for events. The example shown in Figure 9 illustrates
Dim sel As IFeatureSelection how to work with events in the VBA environment. The following code
Set sel = lyr declares a global variable using the WithEvents statement. WithEvents
tells the development environment that the object variable will be used
‘ create a query filter
Dim filter As IQueryFilter
to respond to the object’s events.
Set filter = New QueryFilter
Dim WithEvents g_Map As map
‘ set up the where clause and the spatial reference
filter.WhereClause = “NAME = ‘Hampton’” After the variable is declared, the variable can be chosen from the
Object drop-down list in the VBA interface. Clicking the Procedure
Dim shapeField As String drop-down list will show the various events that are exposed by the
shapeField = lyr.FeatureClass.ShapeFieldName Map. This example uses the SelectionChanged method to attach code
Set filter.OutputSpatialReference(shapeField) =_
mxDoc.FocusMap.SpatialReference
to that event. The script in Figure 9 responds to the SelectionChanged
event that is fired by the map whenever the selection changes and popu-
‘ invalidate the current selection on the display lates a ListBox in a UserForm with the names of the selected features.
mxDoc.ActiveView.PartialRefresh_
esriViewGeoSelection, Nothing, Nothing Figure 9
Private Sub g_Map_SelectionChanged()
‘ select features and invalidate the new selection ‘ show the form if it’s not visible
sel.SelectFeatures filter,_ If Not UserForm1.Visible Then
esriSelectionResultNew, False UserForm1.Show vbModeless
mxDoc.ActiveView.PartialRefresh_ End If
esriViewGeoSelection, Nothing, Nothing
‘ clear any previous results in the list
‘ notify everyone that we’ve modified the selection UserForm1.ListBox1.Clear
Dim selEvents As ISelectionEvents
Set selEvents = mxDoc.FocusMap ‘ get the map’s selection
selEvents.SelectionChanged Dim activeView As IActiveView
End Sub Set activeView = g_Map

‘ enumerate over the selected features

The SelectFeatures method on the IFeatureSelection interface does all Dim featureEnum As IEnumFeature
the work in this script. A QueryFilter object defines the criteria for the Set featureEnum = activeView.Selection
selection. The WhereClause property is set to a SQL expression and the
OutputSpatialReference property is set to control how the features are featureEnum.Reset ‘ reset the cursor
Dim feat As IFeature
projected on the fly as they are retrieved from the database. A Spatial-
Set feat = featureEnum.Next
Filter object could have been used instead of a QueryFilter in order to Do While Not feat Is Nothing
specify a spatial constraint. ‘ add the feature’s name to the list
Dim index As Long
The calls to PartialRefresh on the map through the IActiveView inter- index = feat.Fields.FindField(“Name”)
face take care of redrawing the display so that the old selection is erased If index <> -1 Then
and the new selection is drawn. The final three lines of the script call UserForm1.ListBox1.AddItem feat.Value(index)
the SelectionChanged method on the map through the ISelectionEvents End If
interface. This method notifies any components in the system that have
Set feat = featureEnum.Next ‘ get next feature
registered themselves with the map that the selection has changed. Loop
The Attribute Table Window listens for selection events so that it can End Sub
synchronize the highlighting of its rows to match the selection. If
the script in Figure 8 did not call the SelectionChanged method, the After showing the UserForm and clearing the ListBox, the script gets
Table Window would not reflect the selection in the active view. This the Selection from the Map’s IActiveView interface. The Selection’s
form of communication, called working with events, is used throughout IEnumFeature interface is used to navigate through the collection of
ArcObjects. selected features, returning an IFeature interface. The code searches
each feature’s Fields collection for the Name field. If the Name field is
present, the value is added to the ListBox.

30 ArcUser April—June2000 www.esri.com

 Developer’s Corner

Figure 10
Sub StartListening()
Dim mxDoc As IMxDocument
Set mxDoc = Application.Document
Set g_Map = mxDoc.FocusMap
End Sub

The final step is to initialize the global variable, g_Map, as shown in

Figure 10. Once this script has been run, the script in Figure 9 will
be executed whenever the selection changes and the selections will be
updated in the ListBox.

This is just an introduction to the many components that make up the

ArcObjects object model. To get the latest developer information for
ArcObjects and all ESRI developer products visit The Developer Con-
nection at www.esri.com/developer.

www.esri.com ArcUser April—June 2000 31