You are on page 1of 580

MapObjects

Programmer's
Reference

cover.p65 1 6/24/99, 10:27 AM


Copyright 1996, 1999 Environmental Systems Research, Institute, Inc.

All Rights Reserved.

Printed in the United States of America.

The information contained in this document is the exclusive property of Environmental Systems
Research Institute, Inc. This work is protected under United States copyright law and the copyright laws
of the given countries of origin and applicable international laws, treaties, and/or conventions. No part
of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical,
including photocopying or recording, or by any information storage or retrieval system, except as
expressly permitted in writing by Environmental Systems Research Institute, Inc. All requests should be
sent to Attention: Contracts Manager, Environmental Systems Research Institute, Inc., 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 restric-
tions 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 Environmental Systems Research Institute, Inc., 380 New York Street,
Redlands, CA 92373-8100 USA.

ESRI, MapObjects, ARC/INFO, and ArcView are trademarks of Environmental Systems Research
Institute, Inc., registered in the United States and certain other countries; registration is pending in the
European Community. Spatial Database Engine, SDE, the ArcView GIS logo, GIS by ESRI, the
MapObjects logo, and the ESRI globe logo are trademarks and www.esri.com is a service mark of
Environmental Systems Research Institute, Inc. Other companies and products mentioned herein are
trademarks or registered trademarks of their respective trademark owners.

ProgrammersReference.pmd 1 10/28/2004, 10:00 AM


Introduction
This book is an alphabetic reference that contains a list of the objects, methods, properties and
events associated with the MapObjects Custom Control. Each entry includes a description, a
syntactical summary, remarks, references to other entries, and in some cases, example code,
written in Microsoft Visual Basic.

The material in this book reflects the information available at the time of publication and is
essentially identical to the information contained in the MapObjects online help. In some
cases, more up-to-date information may be available in the online help.

Document Conventions and Programming Style


The MapObjects Programmers Reference uses typographic conventions in its descriptions,
and a programming style in its examples, similar to those used in the Visual Basic documenta-
tion. Consult the Microsoft Visual Basic Programmers Guide or the Microsoft Visual Basic
Language Reference for a listing of these conventions and programming guidelines.

ProgrammersReference.pmd 2 10/28/2004, 10:00 AM


Contents 3

Contents

Add Method 18
AddEvent Method 19
AddGeoDataset Method 21
AddIndex Method 25
AddNew Method 29
AddressLocation Object 30
AddRelate Method 30
AfterLayerDraw Event 34
AfterTrackingLayerDraw Event 34
Alignment Constants 36
AllowDuplicates Property 36
AllowSharing Property 39
Appearance Constants 40
Appearance Property 41
Area Property 41
AreaOfInterest Property 42
AutoFlush Property 43
Axis Property 46
BackColor Property 47
BackgroundRenderer Property 48
BarHeight Property 52
BarWidth Property 53
BatchMatch Method 54
BatchMatchVariableField Property 60
BeforeLayerDraw Event 60
BeforeTrackingLayerDraw Event 62
BorderStyle Property 63
Bottom Property 64

ProgrammersReference.pmd 3 10/28/2004, 2:48 PM


4 MapObjects Programmers Reference

Break Property 66
BreakCount Property 68
Buffer Method 68
BuildIndex Method 72
BuildIndices Method 73
CalculateStatistics Method 74
CancelAction Constants 76
CancelAction Property 76
CancelUpdate Method 78
Candidate Property 81
CandidateCount Property 87
Ceiling Property 88
Center Property 89
CenterAt Method 90
CenterOnAscent Property 91
Centroid Property 93
CharacterIndex Property 94
ChartRenderer Object 95
ChartType Constants 98
ChartType Property 98
ClassBreaksRenderer Object 98
Clear Method 99
Click Event 100
ClearConnectError Method 100
ClearEvents Method 102
CodePage Constants 103
CodePage Property 104
Color Constants 104
Color Property 106
CommitTransaction Method 107
Connect Method 111
Connected Property 112

ProgrammersReference.pmd 4 10/28/2004, 2:42 PM


Contents 5

ConnectError Property 114


Connection Property 115
ConnectionError Constants 116
CoordinateSystem Property 127
CopyMap Method 128
Count Property 129
Custom Property 130
Database Property 131
DataConnection Object 131
Datum Constants 132
Datum Object 133
Datum Property 133
DblClick Event 135
DefaultSymbol Property 135
Delete Method 137
DeleteGeoDataset Method 138
DensificationTolerance Property 140
Depth Property 141
Difference Method 142
Direction Constants 145
Direction Property 146
Disconnect Method 150
DistanceTo Method 150
DistanceToSegment Method 152
DotColor Property 154
DotDensityRenderer Object 156
DotSize Property 156
DotValue Property 157
DragDrop Event 159
DragFiles Event 159
DragOver Event 162
DragState Constants 163

ProgrammersReference.pmd 5 10/28/2004, 2:42 PM


6 MapObjects Programmers Reference

DrawBackground Property 163


DrawError Event 166
DrawingCanceled Event 167
DrawShape Method 167
DrawText Method 169
DropFiles Event 170
Edit Method 171
EditMode Constants 172
EditMode Property 172
Ellipse Object 173
Enabled Property 173
EnableGIF Method 174
EnableTIFFLZW Method 175
EndMeasureField Property 175
EnhancedGeocodingError Constants 176
EOF Property 178
EraseIndices Method 179
Event Property 179
EventCount Property 181
EventRenderer Object 182
EventRouteIDField Property 185
EventTable Property 186
Export Method 186
ExportMap Constants 189
ExportMap Method 190
ExportMap2 Method 191
ExtendedError Property 192
ExtendedErrorString Property 193
Extent Property 193
Factor Property 194
FeatureRouteIDField Property 196
Field Object 197

ProgrammersReference.pmd 6 10/28/2004, 2:42 PM


Contents 7

Field Property 197


FieldCount Property 199
FieldLength Property 200
FieldName Property 201
FieldPrecision Property 202
Fields Collection 202
Fields Property 203
FieldScale Property 203
FieldType Constants 204
FieldType Property 205
FieldValue Property 207
File Property 208
FillStyle Constants 209
FilterExpression Property 210
FilterFields Property 214
FilterOperator Property 214
FilterOrder Constants 217
FilterOrder Property 217
FilterShape Property 218
Find Method 219
FindAllPlaceNames Method 220
FindApproximateMatches Method 225
FindArcInfoCoordinateSystem Method 225
FindCoordinateSystem Method 227
FindEvent Method 228
FindGeoDataset Method 229
Fitted Property 230
FittedField Property 232
FlashShape Method 235
Flattening Property 235
Flip Property 236
Floor Property 238

ProgrammersReference.pmd 7 10/28/2004, 2:42 PM


8 MapObjects Programmers Reference

Font Property 239


FromGeoCoordSys Property 240
FromMapDistance Method 241
FromMapPoint Method 242
FullExtent Property 243
FullRedrawOnPan Property 244
GenerateCandidates Method 246
Geocoder Object 246
GeocodeSuccess Constants 252
GeoCoordSys Object 252
GeoCoordSys Property 253
GeoDataset Object 255
GeoDatasets Collection 255
GeoDatasets Property 255
GeoEvent Object 257
GeographicCoordSys Constants 258
GeographicTransformation Constants 258
GeographicTransformation Property 258
GeoTransformation Object 260
GetCrossings Method 265
GetParameter Method 267
GotFocus Event 269
GroupRenderer Object 269
HasMeasure Property 272
HasZ Property 273
Height Property 274
HeightField Property 275
HorizontalAlignment Property 277
hWnd Property 281
ImageLayer Object 283
Index Property 284
Indexed Property 286

ProgrammersReference.pmd 8 10/28/2004, 2:42 PM


Contents 9

IndexEvents Property 287


IndexExtent Property 291
IndexStatus Constants 292
IndexStatus Method 292
IndexType Constants 293
Insert Method 293
Inset Method 295
Intersect Method 297
IntersectionMatchRules Property 300
IntersectionMatchVariable Property 300
IntersectionMatchVariableCount Property 301
IntersectionStandardizingRules Property 301
Intersects Method 302
InvalidateIndex Method 304
IsCustom Property 304
IsFullyMeasured Property 306
IsPointIn Method 308
IsProjected Property 310
Item Method 310
KeyDown Event 312
KeyPress Event 313
LabelPlacer Object 313
LabelRenderer Object 316
LastError Property 318
Layers Collection 322
Layers Property 322
LayerType Constants 323
LayerType Property 323
Left Property 324
Length Property 325
LevelField Property 326
Line Object 329

ProgrammersReference.pmd 9 10/28/2004, 2:42 PM


10 MapObjects Programmers Reference

LineStyle Constants 330


LinkGroup Constants 331
ListIndices Method 331
Locate Method 331
LocateCandidate Method 332
Location Property 333
Longitude Property 337
LostFocus Event 339
Map Control 339
MapLayer Object 342
MarkerStyle Constants 343
MaskColor Property 343
MaskLabels Property 345
MatchRules Property 346
MatchScore Property 350
MatchVariable Property 354
MatchVariableCount Property 354
MatchVariableField Property 355
MatchVariableIntersectionLink Property 355
MatchWhenAmbiguous Property 356
Max Property 357
MaxFileBuffer Property 357
MaxLevel Property 359
MaxPieSize Property 359
Mean Property 360
Measure Property 360
Method Constants 362
Method Property 364
Min Property 364
MinimumMatchScore Property 365
MinLevel Property 365
MinPieSize Property 366

ProgrammersReference.pmd 10 10/28/2004, 2:42 PM


Contents 11

MinWidth Property 367


MouseDown, Mouse Up Events 368
MouseMove Event 369
MousePointer Constants 370
MousePointer Property 371
Move Method 372
MoveFirst Method 374
MoveNext Method 375
MovePrevious Method 377
MoveTo Method 378
MoveToBottom Method 379
MoveToTop Method 380
MultiplyMeasures Method 382
Name Property 383
NoNullValue Method 384
NormalizationField Property 386
NullValue Property 387
Offset Method 387
Offset Property 388
OffsetMeasures Method 395
OutputMap Method 397
OutputMap2 Method 398
Outline Property 399
OutlineColor Property 401
Pan Method 402
ParameterType Constants 402
Parts Collection 404
Parts Property 405
Password Property 406
Perimeter Property 408
PlaceAbove Property 408
PlaceBelow Property 410

ProgrammersReference.pmd 11 10/28/2004, 2:42 PM


12 MapObjects Programmers Reference

PlaceLocator Object 411


PlaceNameTable Property 412
PlaceOn Property 412
Point Object 413
Points Collection 414
Polygon Object 415
PopulateWithDatums Method 417
PopulateWithGeographicCoordSys Method 417
PopulateWithGeoTransformations Method 418
PopulateWithMeridians Method 418
PopulateWithParameters Method 419
PopulateWithProjectedCoordSys Method 419
PopulateWithProjections Method 420
PopulateWithSpheroids Method 420
PopulateWithUnits Method 421
PrimeMeridian Constants 421
PrimeMeridian Object 422
PrimeMeridian Property 422
PrintMap Method 424
ProjCoordSys Object 425
ProjectedCoordSys Constants 426
Projection Constants 426
Projection Object 428
Projection Property 428
RampColors Method 429
Records Property 429
Recordset Object 431
Rectangle Object 432
Refresh Method 433
RefreshCount Property 435
RefreshLayer Method 436
RefreshRect Method 438

ProgrammersReference.pmd 12 10/28/2004, 2:42 PM


Contents 13

Remove Method 439


RemoveEvent Method 439
RemoveRelates Method 440
Renderer Property 441
ReturnDescription Method 443
ReturnLineEvent Method 443
ReturnMeasure Method 446
ReturnPointEvents Method 448
Reverse Method 449
Right Property 450
RollbackTransaction Method 451
Rotation Property 452
RotationAngle Property 454
RotationField Property 455
ScaleRectangle Method 458
ScalingField Property 458
ScrollBars Property 460
SearchExpression Method 461
SearchMethod Constants 463
SearchByDistance Method 465
SearchShape Method 467
SecondDirection Property 469
SecondName Property 470
SecondType Property 471
Server Property 472
Set Method 472
SetMeasures Method 475
SetMeasuresAsLength Method 475
SetParameter Method 476
ShapeType Constants 476
ShapeType Property 477
ShowOutline Property 478

ProgrammersReference.pmd 13 10/28/2004, 2:42 PM


14 MapObjects Programmers Reference

Size Property 479


SizeField Property 480
SizeSymbols Method 481
SpellingSensitivity Property 482
Spheroid Constants 483
Spheroid Object 483
Spheroid Property 484
SplinedText Property 486
SqueezeFactor Property 487
Standardizer Object 488
Standardizer Property 490
StartMeasureField Property 491
StartTransaction Method 492
Statistics Object 492
StdDev Property 493
StopEditing Method 493
StreetSide Constants 494
StreetSide Property 494
StreetTable Property 495
Strings Collection 497
Style Property 498
Sum Property 499
SupportsTransactions Property 500
Symbol Object 501
Symbol Property 502
SymbolCount Property 503
SymbolHeight Property 505
SymbolField Property 506
SymbolIndex Property 509
SymbolType Constants 511
SymbolType Property 511
SymbolWidth Property 512

ProgrammersReference.pmd 14 10/28/2004, 2:42 PM


Contents 15

Table Object 515


TableDesc Object 516
TableDesc Property 516
Tag Property 518
TextSymbol Object 520
ToGeoCoordSys Property 521
ToMapDistance Method 521
ToMapPoint Method 523
Top Property 525
TrackCircle Method 526
TrackingLayer Object 527
TrackingLayer Property 528
TrackLine Method 529
TrackPolygon Method 530
TrackRectangle Method 531
Transform Method 531
Transparent Property 535
TransparentColor Property 537
Type Property 538
Union Method 540
Unique Property 544
Unit Constants 545
Unit Object 547
Unit Property 547
Updatable Property 548
Update Method 549
UpdateMeasures Method 549
UpdateWhileDrawing Property 550
UseDefault Property 551
User Property 552
Valid Property 553
Value Property 554

ProgrammersReference.pmd 15 10/28/2004, 2:42 PM


16 MapObjects Programmers Reference

ValueAsString Property 556


ValueCalculation Property 558
ValueCount Property 560
ValueField Property 561
ValueMapRenderer Object 562
VerticalAlignment Property 563
Visible Property 563
VisibleRegion Property 565
Width Property 566
WindowMode Constants 567
WindowMode Property 568
X, Y Properties 569
XOffsetField Property 571
XOr Method 571
YOffsetField Property 574
Z Property 575
ZRenderer Object 578
ZValueCalc Constants 579

ProgrammersReference.pmd 16 10/28/2004, 2:42 PM


MapObjects Programmers Reference 17

ProgrammersReference.pmd 17 10/28/2004, 2:42 PM


18 MapObjects Programmers Reference

Add Method
Applies To Parts Collection, Points Object, Strings Collection, GroupRenderer Object, Layers Object

Description Adds a member to a collection object.

Syntax [Set variable] = object.Add (item)

The Add method syntax has the following parts:

Part Description

variable A boolean expression that indicates whether item was added successfully.
Strings or Layers collections only.

object An object expression that evaluates to an object in the Applies To list.

item An expression of any type that specifies the member to add to the collection.

Remarks The Add method will only return a Boolean variable if the object is a MapObjects Strings or
Layers collection.

When you add a MapLayer or an ImageLayer to a Layers collection, youre adding it to the
beginning or top of the collection; consequently its index is 0 and the numeric index of
previously added members of the collection increment by one. You can use the MoveTo and
MoveToBottom methods to change the position of a member of the collection. Note that you
can refer to an existing layer in the Layers collection using the Item method with either its
name or its numeric index.

See Also Count Property, Item Method

Example This example uses the Add method to add MapLayer objects to a Map. To try this example,
paste the code into the Declarations section of a form containing a CommonDialog control, a
CommandButton named Command1 and a Map named Map1 and then press F5 and click
Command1. Move to a folder containing ESRI shapefiles and open the file.
Option Explicit
Private Sub Command1_Click()
Dim oConnect As New DataConnection
Dim oDataset As GeoDataset
Dim sName As String
Dim oLayer As MapObjects2.MapLayer

CommonDialog1.Filter = ESRI Shapefiles (*.shp)|*.shp


CommonDialog1.ShowOpen

ProgrammersReference.pmd 18 10/28/2004, 10:00 AM


MapObjects Programmers Reference 19

If Len(CommonDialog1.FileName) = 0 Then Exit Sub

oConnect.Database = CurDir
If Not oConnect.Connect Then Exit Sub

sName = Left(CommonDialog1.FileTitle, Len(CommonDialog1.FileTitle) _


- 4)

Set oDataset = oConnect.FindGeoDataset(sName)


If oDataset Is Nothing Then Exit Sub

Set oLayer = New MapLayer


oLayer.GeoDataset = oDataset
Map1.Layers.Add oLayer

End Sub

AddEvent Method
Applies To TrackingLayer Object

Description Creates a new GeoEvent based on a given shape. The method draws the GeoEvent using the
Symbol referenced by the SymbolIndex property.

Syntax Set variable = object.AddEvent( shape, symbolIndex)

The AddEvent method syntax has these parts:

Part Description

variable An object expression that evaluates to a GeoEvent object.

object An object expression that evaluates to a TrackingLayer object.

shape An object expression that evaluates to a Point, Line, Polygon, Rectangle,


or Ellipse object, or a Points collection.

symbolIndex An integer index that indicates with which Symbol to draw the GeoEvent.

Remarks Care should be taken when adding GeoEvents of different shape types to the TrackingLayer.
If a GeoEvent is added, but given the SymbolIndex of a symbol with an incorrect
SymbolType, MapObjects will add the GeoEvent using the correct SymbolType, but the
default properties of that SymbolType will be used.

ProgrammersReference.pmd 19 10/28/2004, 10:00 AM


20 MapObjects Programmers Reference

For example, if you add a Point as a GeoEvent to a TrackingLayer, but use a SymbolType
of moFillSymbol, that GeoEvent will be drawn with a black circle Symbol.

See Also GeoEvent Object,Point Object,Symbol Object

Example This example uses the AddEvent method to place a GeoEvent on the TrackingLayer of a map
interactively. The addition of GeoEvents as different shapes is also demonstrated. This code
adds the GeoEvent to the TrackingLayer at the location(s) you click. To try this example, paste
the code into the Declarations section of a form containing a Map named Map1 that contains
at least one MapLayer, and then press F5 and click the map. Note that if you click the map
with the left mouse button, the GeoEvent is marked with a red symbol. If you click the map
with the right mouse button, you must then track a polygon, which is added to the
TrackingLayer as a GeoEvent.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)
If Button = 1 Then
Dim pt As MapObjects2.Point
Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.AddEvent pt, Button - 1
ElseIf Button = 2 Then
Dim poly As MapObjects2.Polygon
Set poly = Map1.TrackPolygon
Map1.TrackingLayer.AddEvent poly, Button - 1
End If
End Sub

Private Sub Form_Load()


defines two Symbols for the TrackingLayer
Dim fnt As New StdFont
fnt.Name = Wingdings
fnt.Bold = False
Map1.TrackingLayer.SymbolCount = 2

the following properties will display when you click the


left button
With Map1.TrackingLayer.Symbol(0)
.Color = moRed
.Style = moTrueTypeMarker
.Font = fnt
.Size = 18
.CharacterIndex = 129
End With

ProgrammersReference.pmd 20 10/28/2004, 10:00 AM


MapObjects Programmers Reference 21

the following properties will display when you click the


right button
With Map1.TrackingLayer.Symbol(1)
.SymbolType = moFillSymbol
.Color = moBlue
.Style = moGrayFill
End With

End Sub

AddGeoDataset Method
Applies To DataConnection Object

Description Creates a new GeoDataset object and adds it to a DataConnection.

Syntax object.AddGeoDataset name, shapeType, TableDesc, HasZ, HasM

The AddGeoDataset method syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

name A string expression that evaluates to the name of the GeoDataset object to
add to the DataConnection.

shapeType The type of feature represented in the GeoDataset as described in Settings.

TableDesc An object expression that evaluates to a TableDesc object.

HasZ Optional. A boolean expression. If True, the GeoDataset to be added will be


able to store shapes with Z values.

HasM Optional. A boolean expression. If True, the GeoDataset to be added will


be able to store shapes with Measure values.

Settings The values for shapeType are ShapeTypeConstants. Note that as the new GeoDataset will be
stored as a Shapefile, only the Point, Points, Line and Polygon shape types are valid.

Remarks The AddGeoDataset method creates a new GeoDataset stored as a Shapefile. To successfully
create a new GeoDataset; the data source of the DataConnection object must be a folder to
which your application has write access. If MapObjects fails to create a new GeoDataset, the
method will return nil. In Visual Basic, your application can test for this as follows:
Dim gdNew as MapObjects2.GeoDataset

ProgrammersReference.pmd 21 10/28/2004, 10:00 AM


22 MapObjects Programmers Reference

Set gdNew = myDataConnection.AddGeoDataset(Test, moShapeTypePoint _


, tdNew)
If gdNew Is Nothing Then
Debug.Print Failed to create GeoDataset.
End If
The HasZ and HasM arguments can be used to specify whether the new GeoDataset has
support for Z and Measure values. These arguments are optional and default to False.
GeoDatasets without support for Z or Measure values are created as Shapefiles with shape
types of Point, PolyLine, Polygon or MultiPoint. GeoDatasets with support for Measure
values are created as Shapefiles with shape types of PointM, PolyLineM, PolygonM or
MultiPointM. GeoDatasets with support for Z values (and, if required, Measure values) are
created as Shapefiles with shape types of PointZ, PolyLineZ, PolygonZ or MultiPointZ. See
the ESRI Shapefile Technical Description for more details.

Shapefiles with support for Z and Measure values are only fully supported as of ArcView 3.1
and MapObjects 2.0. In some cases, older applications may not be able to read such
Shapefiles. If you intend to use geographic data created in MapObjects with older applica-
tions, you may wish to leave the HasZ and HasM arguments as their default values of False.

MapObjects does not directly support the MultiPatch shape type and can not create a
GeoDataset that stores shapes of this type.

See Also GeoDataset Object, TableDesc Object

Example This example uses the AddGeoDataset method and the TableDesc properties to create a new
shapefile that represents a GeoDataset with polygon features in a DataConnection. In addition,
the code associates the GeoDataset with a MapLayer, adding it to the Map. The TableDesc
properties define three additional fields in the Recordset. For each feature added, the code
invokes the AddNew and Update methods to populate the fields of the Recordset. To try this
example, paste the code into the Declarations section of a form containing a CommonDialog
control named CommonDialog1, a CommandButton named Command1 and Map named
Map1 that contains a MapLayer or an ImageLayer. This layer will serve as a background layer,
providing the coordinates and map units of the new MapLayer. Click F5, and track polygons
by clicking on the map, a double-click signals the end of a polygon. When youve added the
polygons you want, click the Save button to specify the name of the shapefile.
Option Explicit
Dim moSymbol As New MapObjects2.Symbol
Dim moPolygons As New Collection

Private Sub Command1_Click()

Dim gds As MapObjects2.GeoDataset


Dim sName As String
Dim Desc As New TableDesc
Dim dc As New DataConnection

ProgrammersReference.pmd 22 10/28/2004, 10:00 AM


MapObjects Programmers Reference 23

Dim lyr As New MapObjects2.MapLayer


Dim lPoly As Long

With CommonDialog1
.Filter = ESRI Shapefiles (*.shp)|*.shp
.DefaultExt = .shp
.ShowSave

If Len(.FileName) = 0 Then Exit Sub cancel


dc.Database = CurDir

If Not dc.Connect Then Exit Sub bad dataConnection


remove the extension
sName = Left(.FileTitle, Len(.FileTitle) - 4)
End With

With Desc
define three additional fields
.FieldCount = 3

set the field names


.FieldName(0) = Name
.FieldName(1) = Area
.FieldName(2) = Perimeter

set the type of field


.FieldType(0) = moString
.FieldType(1) = moDouble
.FieldType(2) = moDouble

set the length of a character field


.FieldLength(0) = 16

set the number of digits used in the field


.FieldPrecision(1) = 15
.FieldPrecision(2) = 15

set the number of digits to the right of the decimal point


.FieldScale(1) = 3
.FieldScale(2) = 3
End With

Set gds = dc.AddGeoDataset(sName, moPolygon, Desc)


If gds Is Nothing Then Exit Sub invalid file

Set lyr.GeoDataset = gds

ProgrammersReference.pmd 23 10/28/2004, 10:00 AM


24 MapObjects Programmers Reference

Map1.Layers.Add lyr
Map1.Refresh

For lPoly = 1 To moPolygons.Count


With lyr.Records
.AddNew
.Fields(Shape).Value = moPolygons(lPoly)
.Fields(Name).Value = Name & lPoly
.Fields(Area).Value = moPolygons(lPoly).Area
.Fields(Perimeter).Value = moPolygons(lPoly).Perimeter
.Update
End With
Next
End Sub

Private Sub Form_Load()


With moSymbol
.SymbolType = moFillSymbol
.Style = moSolidFill
.Color = moPaleYellow
End With
Command1.Caption = Save
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
Dim oPoly As MapObjects2.Polygon

If moPolygons.Count <> 0 Then


For Each oPoly In moPolygons
Map1.DrawShape oPoly, moSymbol
Next
End If

End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)

Dim oRect As MapObjects2.Rectangle


Dim oPoly As New MapObjects2.Polygon

If Button = 1 Then
Set oPoly = Map1.TrackPolygon
moPolygons.Add oPoly
Map1.TrackingLayer.Refresh True

ProgrammersReference.pmd 24 10/28/2004, 10:00 AM


MapObjects Programmers Reference 25

Else
Set oRect = Map1.Extent
oRect.ScaleRectangle 0.5
Map1.Extent = oRect
End If

End Sub

AddIndex Method
Applies To Geocoder Object

Description This method is used to define which fields of the StreetTable have logical indices built when
the BuildIndices method is used.

Syntax Set variable = object.AddIndex (fieldName, secondaryFieldName, indexType)

The AddIndex Method syntax has these parts:

Part Description

variable A boolean expression that indicates whether an index is specified


correctly.

object An object expression that evaluates to an object in the Applies To list.

fieldName A string expression that specifies the name of the field in the
StreetTables GeoDataset.

secondaryFieldName A string expression that specifies the name of the Field in the
StreetTables GeoDataset. This option is used if more than one
Field is indexed as one query variable, for example, left ZIP and right
ZIP. This field is optional and you can use an empty string (two
double quotes), if no other field needs to be indexed for the query
variable.

IndexType A value or constant that specifies the type of index as defined in the
IndexTypeConstants.

Settings The settings for indexType are IndexTypeConstants:

Remarks All logical indices have to be defined before the indices are built using the BuildIndices
method. The AddIndex method defines which Fields are indexed, and the type of index which
is built. Multiple logical indices can be specified; there will be more options available when
defining a search query if more logical indices are specified.

ProgrammersReference.pmd 25 10/28/2004, 10:00 AM


26 MapObjects Programmers Reference

For a large street network, it is common to index street name and ZIP or city name Fields. For
example, two streets in different cities may have the same name, so you may want to search on
both street name and ZIP fields. A search query can also be relaxed by querying only on the
street name if no ZIP or an uncertain ZIP is provided in the address.

When you have added indices to a Geocoder object, the SearchQueries property should be
defined accordingly, based on those indices.

A normal (mgIndexTypeNormal) index can be used on any field in the StreetTable. You may
like to use a Soundex (mgIndexTypeSoundex) index on fields which can be misspelled, for
example street names.

See Also BuildIndices Method, EraseIndices Method, IndexStatus Method, ListIndices Method,
SearchQueries Property, IndexType Constants

Example This example demonstrates the use of the AddIndex, BuildIndices, ListIndices, EraseIndices
and IndexStatus methods. To try this example, paste the code into the Declarations section of a
form that contains a Map named Map1 and three CommandButtons named Command1,
Command2, and Command3. Next to the three buttons, add three Labels named Label1,
Label2 and Label3. Substitute appropriate values for the data paths. Then press F5 and click
each button to see what will happen.
Option Explicit

Dim geo As New MapObjects2.Geocoder

Set global variables with field names in the StreetTable


Modify if fields names in StreetTable are different
Private Const m_FromLeft = L_f_add
Private Const m_FromRight = R_f_add
Private Const m_ToLeft = L_t_add
Private Const m_ToRight = R_t_add
Private Const m_PreDir = Prefix
Private Const m_PreType = Pre_type
Private Const m_StreetName = Name
Private Const m_StreetType = Type
Private Const m_SufDir = Suffix
Private Const m_LeftZone = Cityl
Private Const m_RightZone = CityR

Private Sub Command1_Click()

Build indices using the AddIndex and BuildIndices methods

If Not geo.IndexStatus = _
MapObjects2.IndexStatusConstants.mgIndexExists Then

ProgrammersReference.pmd 26 10/28/2004, 10:00 AM


MapObjects Programmers Reference 27

If Not geo.AddIndex(m_StreetName, , mgIndexTypeSoundex) Then


MsgBox Cannot build geocoding index., vbCritical
Exit Sub
End If
If Not geo.AddIndex(m_LeftZone, m_RightZone, _
mgIndexTypeNormal) Then
MsgBox Cannot build geocoding index., vbCritical
Exit Sub
End If
If Not geo.BuildIndices(True) Then
MsgBox Cannot build geocoding index., vbCritical
Exit Sub
Else
Label1.Caption = Indices are built.
End If
Else
Label1.Caption = Index already exists.
End If

End Sub

Private Sub Command2_Click()

Remove the index file if it exists and not read-only using


the EraseIndices method
If geo.IndexStatus = MapObjects2.IndexStatusConstants. _
mgIndexExists Then
If geo.EraseIndices Then
Label2.Caption = Indices are removed.
Else
Label2.Caption = Cant remove indices.
End If
Else
Label2.Caption = No indices to remove
End If

End Sub

Private Sub Command3_Click()

Show the indices information using the ListIndices method


Dim i As Integer
Dim msg As String
Dim l As New MapObjects2.Strings

Set l = geo.ListIndices

ProgrammersReference.pmd 27 10/28/2004, 10:00 AM


28 MapObjects Programmers Reference

If geo.IndexStatus = MapObjects2.IndexStatusConstants. _
mgIndexExists Then
msg = The index file contains & l.count & _
logical index/indices, including: & vbCrLf
For i = 0 To l.count - 1
msg = msg & l.Item(i) & vbCrLf
Next i
Else
msg = No indices are found
End If

Label3.Caption = msg

End Sub

Private Sub Form_Load()

Dim dc As New MapObjects2.DataConnection


Dim gd As Object
Dim lyr As New MapLayer

Command1.Caption = Build Indices


Command2.Caption = Remove Indices
Command3.Caption = Show Indices

Label1.Caption =
Label2.Caption =
Label3.Caption =

dc.Database = C:\Program Files\ESRI\MapObjects2\ _


Samples\Data\Redlands
dc.Connect
If Not dc.Connected Then
MsgBox dc.connected error
End
End If

Set gd = dc.FindGeoDataset(Redlands)
lyr.GeoDataset = gd
lyr.Symbol.Color = moBlue
Map1.Layers.Add lyr
geo.StreetTable = gd
Change the path below to ones appropriate for your data
geo.MatchRules = C:\Program Files\ESRI\MapObjects2\ _

ProgrammersReference.pmd 28 10/28/2004, 10:00 AM


MapObjects Programmers Reference 29

GeoRules\us_addr1.mat

Link the Match Variables to fields in the StreetTable


geo.MatchVariableField(FromLeft) = m_FromLeft
geo.MatchVariableField(FromRight) = m_FromRight
geo.MatchVariableField(ToLeft) = m_ToLeft
geo.MatchVariableField(ToRight) = m_ToRight
geo.MatchVariableField(PreDir) = m_PreDir
geo.MatchVariableField(PreType) = m_PreType
geo.MatchVariableField(StreetName) = m_StreetName
geo.MatchVariableField(StreetType) = m_StreetType
geo.MatchVariableField(SufDir) = m_SufDir
geo.MatchVariableField(LeftZone) = m_LeftZone
geo.MatchVariableField(RightZone) = m_RightZone

End Sub

AddNew Method
Applies To Recordset Object

Description Creates a new record for a Recordset object.

Syntax object.AddNew

The AddNew property syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

Remarks The AddNew method creates a new record you can edit and add to the Recordset referenced
by object. This method sets the fields to null or default values, if any.

After you modify the new record, use the Update method to save the changes and add the
record to the Recordset. No changes are made to the data set until you use the Update
method.

Invoke AddNew on complete Recordset objects only. MapObjects will issue a run-time error
if you invoke AddNew on a Recordset that represents a subset of a MapLayer objects
Recordset created by one of the following Recordset methods: SearchShape,
SearchByDistance, or SearchExpression.

Make sure that any editing operations your program carries out are made to the same
Recordset object for which you called the AddNew method. The safest approach is to create a

ProgrammersReference.pmd 29 10/28/2004, 10:00 AM


30 MapObjects Programmers Reference

local Recordset object, on which all the editing operations are carried out. The following
Visual Basic example shows how this can be done for a given MapLayer, called new_layer:
Dim recs As MapObjects2.Recordset
Set recs = new_layer.Records
If recs.Updatable Then
recs.AddNew
If recs.EditMode = moEditAdd Then
Add new feature and attributes
recs.Update
Else
MsgBox AddNew failed.
End If
End If
See Also Recordset Object

Example See AddGeoDataset Method

AddressLocation Object
An AddressLocation object represents the results of an address match. When you locate a
successfully matched address using LocateCandidate, an AddressLocation object is re-
turned. MapObjects finds the geographic location of an address by searching the Geocoder
objects StreetTable.

You can return the status of the matched AddressLocation by reading its MatchScore
property. If your MatchScore is low, you might decide to provide a means for manual
intervention in order to match the address. If the match was successful, you can return the
Location of the address as a Point object, and side of the street with the StreetSide property
if applicable.

See Also Geocoder Object, Standardizer Object

Properties

Location Property, MatchScore Property, StreetSide Property

AddRelate Method
Applies To MapLayer Object

Description Creates a relate between the Recordset associated with a MapLayer and the Recordset of
another Table.

ProgrammersReference.pmd 30 10/28/2004, 10:00 AM


MapObjects Programmers Reference 31

Syntax object.AddRelate( toField, sourceTable, fromField,[checkFields as Boolean])

The AddRelate method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

toField A string expression that evaluates to the name of a Field in the Recordset
associated with the MapLayer.

sourceTable An object expression that evaluates to a Table object that contains the data
to relate to the MapLayer objects Recordset.

fromField A string expression that evaluates to the name of a Field in sourceTable.

checkFields (Optional) A boolean expression specifying whether the AddRelate method


performs additional checks on the Fields of the Table before attempting the
relate. See Remarks below.

Remarks When the AddRelate method is used, checks are performed on the sourceTable to ensure that
the relate is possible. The following checks are carried out:

1. Does the Table actually exist?

2. If so, do the specified Fields exist?

3. If they do, are they supported relate types?

The supported relate types: are numeric fields, character/string fields and Boolean fields. If
either the toField or fromField is not of a supported type then AddRelate will return False,
and the relate will not be successful.

The default value for checkFields is True. When checkFields is True, the AddRelate method
carries out further checks against the toField in the sourceTable. The following checks are
made:

1. Is the toField the key field of the sourceTable?

2. If not, is the toField indexed?

3. If not, does a request to build an index on the toField return successfully?

If one or more of these conditions are true, then AddRelate will succeed. If checkFields is
false, this last set of checks will not be carried out and AddRelate will succeed if the first sets
of checks are successful. Depending on the database that contains the sourceTable, it may not
be possible for MapObjects to carry out the last set of checks. Certain ODBC drivers do not

ProgrammersReference.pmd 31 10/28/2004, 10:00 AM


32 MapObjects Programmers Reference

support the necessary functionality to determine these conditions. In these cases, you may
wish to set checkFields to False in order to carry out the relate; for example when carrying out
a relate to an Oracle view. This should be done with care, particularly with large data sets, as
the performance of any relate without an index may be inefficient.

The checkFields parameter can also be used when the AddRelate is to be carried out using a
database table that is not owned by the current user. If the user specified in the User property
of the Table object does not have sufficient privileges, MapObjects can not carry out the
required indexing operations. In this case, the checkFields parameter should be set to False.

See Also Table Object

Example This example uses the AddRelate method to associate records from a foreign table (referred to
as sourceTable in the usage) with the records in a MapLayer objects Recordset. It also uses
the RemoveRelates method to drop all the related fields. To try this example, paste the code
into the Declarations section of a form containing a CommonDialog control named
CommonDialog1, two CommandButton controls named Command1 and Command2, a
ListBox named List1, and a Map named Map1 that has a MapLayer. The example assumes
that you have a Microsoft dBase Driver (*.dbf) DataSource named the same as the folder that
contains the dBase Table that you want to relate to the MapLayer. In addition, youll have to
change the field names that you pass as parameters to AddRelate. Press F5, then click Com-
mand1. Youll see the additional fields in the ListBox. If the Recordset has more than 100
records, youll have to create an index on the field in the sourceTable.
Option Explicit
Dim recset As MapObjects2.Recordset
Dim f As MapObjects2.field

Private Sub Command1_Click()

Dim fName As String


Dim dName As String
Dim relTable As New MapObjects2.Table

CommonDialog1.Filter = dBASE files (*.dbf)|*.dbf


CommonDialog1.ShowOpen

SplitFN CommonDialog1.FileName, dName, fName


assumes the ODBC DataSource name is the directory name
relTable.Database = dName
relTable.Name = fName

field names in next line are hard-coded


If Map1.Layers(0).AddRelate(ABBREVNAME, relTable, COUNTRY) Then
List1.Clear
Set recset = Map1.Layers(0).Records

ProgrammersReference.pmd 32 10/28/2004, 10:00 AM


MapObjects Programmers Reference 33

For Each f In recset.Fields


List1.AddItem f.Name
Next f
Else
MsgBox
End If

End Sub

Private Sub Command2_Click()


Map1.Layers(0).RemoveRelates
Set recset = Map1.Layers(0).Records
List1.Clear
For Each f In recset.Fields
List1.AddItem f.Name
Next f
End Sub

Private Sub Form_Load()


Set recset = Map1.Layers(0).Records

For Each f In recset.Fields


List1.AddItem f.Name
Next f
Command1.Caption = Add Relate
Command2.Caption = Remove Relates
End Sub

Sub SplitFN(pathName As String, dName As String, fName As String)


Dim dirName As String
Dim nCurPos As Integer, nLastPos As Integer

find the last occurrence of a file separator


in the path
nCurPos = 0
Do
nLastPos = nCurPos
nCurPos = InStr(nCurPos + 1, pathName, )
Loop Until nCurPos = 0

If nLastPos = 0 Then Exit Sub

dirName = Left(pathName, nLastPos - 1)


dName = Dir(dirName, vbDirectory)
fName = Right(pathName, Len(pathName) - nLastPos)
End Sub

ProgrammersReference.pmd 33 10/28/2004, 10:00 AM


34 MapObjects Programmers Reference

AfterLayerDraw Event
Applies To Map Object

Description Occurs when a Map finishes drawing a specified layer.

Syntax Private Sub object_AfterLayerDraw(ByVal index As Integer, ByVal canceled As Boolean,


ByVal hDC As Stdole.OLE_HANDLE)

The AfterLayerDraw event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

index An integer that uniquely identifies a member of the Layers collection.

hDC A handle provided by the Microsoft Windows operating environment to the


device context of the Map.

Remarks You can use the hDC to refer to the handle for an objects device context. This provides a
value to pass to Windows API calls.

See Also AfterTrackingLayerDraw Event, BeforeLayerDraw Event, BeforeTrackingLayerDraw


Event

Example This example illustrates when the AfterLayerDraw Event occurs. Prior to drawing each layer
on the Map, the code displays a simple message that indicates the name of the layer. To try this
example, paste the code into the Declarations section of a form containing a Map named Map1
that contains at least one MapLayer, and then press F5.
Option Explicit

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As stdole.OLE_HANDLE)
MsgBox Completed drawing & Map1.Layers(index).Name, _
vbInformation
End Sub

AfterTrackingLayerDraw Event
Applies To Map Object

Description Occurs when a Map completes drawing all the GeoEvent objects on its TrackingLayer.

ProgrammersReference.pmd 34 10/28/2004, 10:00 AM


MapObjects Programmers Reference 35

Syntax Private Sub object_AfterTrackingLayerDraw(ByVal hDC As Stdole.OLE_HANDLE)

The AfterTrackingLayerDraw event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

hDC A handle provided by the Microsoft Windows operating environment to the


device context of the Map.

Remarks You can use the hDC to refer to the handle for an objects device context. This provides a
value to pass to Windows API calls.

See Also AfterLayerDraw Event, BeforeLayerDraw Event, BeforeTrackingLayerDraw Event

Example This example demonstrates when the AfterTrackingLayerDraw Event occurs. Clicking on the
map adds a GeoEvent to the TrackingLayer. The event code reports on the number of
GeoEvent objects on the TrackingLayer. To try this example, paste the code into the Declara-
tions section of a form containing a Map named Map1 that contains at least one MapLayer,
and then press F5. Click on the Map to add GeoEvent objects.
Option Explicit

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
Dim msg As String
Select Case Map1.TrackingLayer.EventCount
Case 0
msg = No GeoEvents on the TrackingLayer yet
Case 1
msg = One GeoEvent on the TrackingLayer
Case Else
msg = Map1.TrackingLayer.EventCount & GeoEvents on _
the TrackingLayer
End Select
MsgBox msg, vbInformation, MapObjects
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


X As Single, Y As Single)
Dim pt As MapObjects2.Point
Set pt = Map1.ToMapPoint(X, Y)
Map1.TrackingLayer.AddEvent pt, 0
Map1.TrackingLayer.Refresh True
End Sub

ProgrammersReference.pmd 35 10/28/2004, 10:00 AM


36 MapObjects Programmers Reference

Alignment Constants
MapObjects defines the following constants for use with the HorizontalAlignment property
(H in the table below)and the VerticalAlignment property (V in the table below) of a
TextSymbol object.

Constant Value Use with Description

moAlignTop 1 V Align the top of the text with the feature.

moAlignBottom 2 V Align the bottom of the text with the


feature.

moAlignLeft 3 H Align the left side of the text with the


feature.

moAlignRight 4 H Align the right side of the text with the


feature.

moAlignCenter 5 V, H Align the center of the text with the feature.

moAlignBaseline 6 V Align the baseline of the text with the


feature.

See Also LabelRenderer Object, TextSymbol Object

AllowDuplicates Property
Applies To LabelRenderer Object, LabelPlacer Object

Description Returns or sets a value indicating whether a LabelPlacer or LabelRenderer object will draw
duplicate labels if it has already drawn a label with the same text.

Syntax object.AllowDuplicates [= boolean]

The AllowDuplicates property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 36 10/28/2004, 10:00 AM


MapObjects Programmers Reference 37

boolean A boolean expression specifying whether the LabelRenderer or


LabelPlacer object will draw duplicate labels if it has already drawn a label
with the same text, as described in Settings.

Settings The settings for boolean are:

Setting Description

True (Default) The object will draw duplicate labels.

False The object will not draw duplicate labels.

See Also TextSymbol Object

Example This example uses three of the LabelRenderer properties to control the appearance of the text
drawn by the renderer. It uses the AllowDuplicates property to control whether a
LabelRenderer object will draw more than one instance of the same text to a MapLayer. It uses
the DrawBackground property to control whether the features of the MapLayer draw. It also
uses the SplinedText property to control whether text splines when the MapLayer displays line
features. Note that while the example initializes AllowDuplicates to False; its actual default is
True. To try this example, paste the code into the Declarations section of a form containing a
Map named Map1 that contains a MapLayer that displays polygon features, a ListBox named
List1, three CheckBox controls named Check1, Check2, and Check3, and a CommandButton
named Command1. The code will position and size the controls; just make sure to leave
enough room below the map on the Form. Press F5 and double-click the name of a Field that
will serve as the source or the text. Toggle the check box controls to set the properties.
Option Explicit

Private Sub List1_DblClick()

Dim sFldname As String


Dim oFont As New StdFont
Dim oRecs As MapObjects2.Recordset
Dim oRenderer As New MapObjects2.LabelRenderer

If List1.ListIndex <> -1 Then must have a field selected

use a TrueType Font


oFont.Name = Arial

set up the LabelRenderer


Set Map1.Layers(0).Renderer = oRenderer

With oRenderer
.SymbolCount = 1

ProgrammersReference.pmd 37 10/28/2004, 10:00 AM


38 MapObjects Programmers Reference

.AllowDuplicates = Check1.Value
.DrawBackground = Check2.Value
.SplinedText = Check3.Value

.Symbol(0).Font = oFont
.Symbol(0).Color = moBlack
.Symbol(0).Height = Map1.Extent.Height * 0.08

sFldname = List1.List(List1.ListIndex)
.Field = sFldname text values stored in this field
End With

Map1.Refresh redraw the map

disassociate objects
Set oFont = Nothing
Set oRecs = Nothing
Set oRenderer = Nothing
End If

End Sub

Private Sub Check1_Click()


List1_DblClick
End Sub

Private Sub Check2_Click()


List1_DblClick
End Sub

Private Sub Check3_Click()


List1_DblClick
End Sub

Private Sub Form_Load()


Dim oField As MapObjects2.Field

Command1.Caption = Full Extent


Check1.Caption = Allow duplicate labels
Check2.Caption = Draw background
Check3.Caption = Splined text

List1.Left = Map1.Left
Check1.Left = List1.Left + List1.Width + 100
Check2.Left = Check1.Left
Check3.Left = Check1.Left

ProgrammersReference.pmd 38 10/28/2004, 10:00 AM


MapObjects Programmers Reference 39

Command1.Left = Check1.Left

List1.Top = Map1.Top + Map1.Height + 100


Check1.Top = List1.Top
Check2.Top = Check1.Top + Check1.Height
Check3.Top = Check2.Top + Check2.Height
Command1.Top = Check3.Top + Check3.Height

Check1.Width = Check1.Width + Check1.Width


Check2.Width = Check2.Width + Check2.Width
Check3.Width = Check3.Width + Check3.Width

Check1.Value = 0 AllowDuplicates initialized to False


Check2.Value = 1 DrawBackground initialized to True
Check3.Value = 1 SplinedText initialized to True

For Each oField In Map1.Layers(0).Records.Fields


List1.AddItem oField.Name
Next

End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


X As Single, Y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

AllowSharing Property
Applies To GeoDataset Object

Description Returns or sets a value indicating whether other applications may write to the GeoDataset
object.

Syntax object.AllowSharing [= shared]

The AllowSharing property syntax has these parts:

ProgrammersReference.pmd 39 10/28/2004, 10:00 AM


40 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to a GeoDataset object.

shared A boolean expression specifying whether other applications may write to the
GeoDataset object, as described in Settings.

Settings The settings for shared are:

Setting Description

True Shares to other applications for writing to the GeoDataset object.

False (Default) Shares to other applications for reading the GeoDataset object.

Remarks The AllowSharing property can be used to allow other applications to make edits to a
GeoDataset that is being used in a MapObjects application. By default, when a GeoDataset is
returned its AllowSharing property is set to False. If a GeoDataset has already been opened
by another application for editing, then MapObjects will return the GeoDataset with its
AllowSharing property set to True.

If you wish other applications to be able to edit the GeoDataset, and the MapObjects applica-
tion is not editing the Recordset (see the EditMode property page), set the AllowSharing
property to True after it is returned. As neither MapObjects nor the computers operating
system can efficiently cache files that have been opened with shared write privileges, perfor-
mance may be slower when using a GeoDataset with its AllowSharing property is set to True.

See Also Recordset Object, Table Object

Example See MaxFileBuffer Property

Appearance Constants
MapObjects defines the following constants for use with the Appearance property of a Map
object.

Constant Value Description


moFlat 0 (Default) Flat. Paints the map without visual effects.
mo3D 1 3D. Paints the map with three-dimensional effects.

See Also Map Object, Appearance Property

ProgrammersReference.pmd 40 10/28/2004, 10:00 AM


MapObjects Programmers Reference 41

Appearance Property
Applies To Map Object

Description Returns or sets the paint style of a Map object at run time. Read-only at run time.

Syntax object.Appearance [= value]

The Appearance property syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

value A value or constant that determines the appearance of an object, as de-


scribed in Settings.

Settings The settings of Appearance are AppearanceConstants.

See Also BackColor Property, BorderStyle Property, ScrollBars Property

Area Property
Applies To Polygon Object

Description Returns the area of an object in square map units.

Syntax object.Area [=value]

The Area property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A value of double data type equating to the area of the Polygon.

See Also Perimeter Property

Example This example makes use of some of the geometric properties of a Polygon to report back some
standard information about a feature you select. To try this example, copy the code into the
Declarations section of a Form that contains a Map named Map1 that contains a MapLayer
with polygon features. Press F5 and click on a polygon.

ProgrammersReference.pmd 41 10/28/2004, 10:00 AM


42 MapObjects Programmers Reference

Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)
Dim oRecset As MapObjects2.Recordset
Dim oPoint As MapObjects2.Point
Dim oFld As MapObjects2.Field

Set oPoint = Map1.ToMapPoint(x, y)


Set oRecset = Map1.Layers(0).SearchShape(oPoint, _
moPointInPolygon, )

If Not oRecset.EOF Then


Set oFld = oRecset(shape)
Map1.FlashShape oFld.Value, 4
oRecset.MoveFirst reset the cursor
report the results
With oFld.Value
MsgBox Area: & .Area & vbCr & _
Perimeter: & .Perimeter & vbCr & _
Centroid X: & .Centroid.x & vbCr & _
Centroid Y: & .Centroid.y
End With
End If

End Sub

AreaOfInterest Property
Applies To MapLayer Object

Description Returns the default area of interest for a MapLayer object. The property is read-only at both
design time and run time.

Syntax object.AreaOfInterest [= area]

The AreaOfInterest property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

area An object expression that evaluates to a Rectangle object.

ProgrammersReference.pmd 42 10/28/2004, 10:00 AM


MapObjects Programmers Reference 43

Remarks For MapLayer objects based on shapefiles, the area of interest is the same as the Extent. The
area of interest for an SDE layer may be a subset of the entire layer extent.

See Also Rectangle Object, Extent Property

Example This example uses the AreaOfInterest property to zoom to the extent of a MapLayer. To try
this example, paste the code into the Declarations section of a form containing a
CommandButton named Command1 and a Map named Map1 that has at least one MapLayer.
Press F5. Drag a rectangle to zoom in and press Command1 to zoom to the extent of the
topmost MapLayer.
Option Explicit

Private Sub Command1_Click()


Map1.Extent = Map1.Layers(0).AreaOfInterest
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)
Map1.Extent = Map1.TrackRectangle
End Sub

AutoFlush Property
Applies To Recordset Object

Description Returns or sets a value that indicates whether changes to a Recordset are automatically
flushed on each write.

Syntax object.AutoFlush [= boolean]

The AutoFlush property syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

boolean A boolean expression specifying whether changes to the Recordset are


automatically made on each write, as described in Settings.

Settings The settings for boolean are:

Setting Description

True (Default). Changes are automatically flushed on each write.

ProgrammersReference.pmd 43 10/28/2004, 10:00 AM


44 MapObjects Programmers Reference

False Changes are not automatically flushed on each write.

Remarks Setting AutoFlush to False will result in performance improvements for batch type opera-
tions such as creating new Shapefiles. For updates to be reliably seen as they occur,
AutoFlush should be set to True. Setting AutoFlush to True will flush the file, as will
StopEditing or releasing the Recordset object.

See Also Recordset Object, Edit Property

Example This example uses the SearchShape method to select features in order to create a new
shapefile based on the Recordset the method returns. The example makes use of the AutoFlush
method to optimize the write operations. To try this example, paste the code into the declara-
tions section of a form that contains a Map named Map1 that has at least one MapLayer that
contains polygon features; then press F5. Track a polygon shape to select the features you
want to save to a new shapefile. Note that this example creates a hard-coded shapefile named
shptemp in the current path.
Option Explicit
Dim moPoly As MapObjects2.Polygon
Dim moRecset As MapObjects2.Recordset

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)

Dim oSym As New MapObjects2.Symbol

If moRecset Is Nothing Then Exit Sub

With oSym
.SymbolType = moFillSymbol
.Style = moSolidFill
.Color = moYellow
End With

Map1.DrawShape moRecset, oSym


Call MakeShapeFromSelection(moRecset)
Set moRecset = Nothing
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)

Set moPoly = Map1.TrackPolygon


Set moRecset = Map1.Layers(0).SearchShape(moPoly, _
moEdgeTouchOrAreaIntersect, )

ProgrammersReference.pmd 44 10/28/2004, 10:00 AM


MapObjects Programmers Reference 45

moRecset.MoveFirst
Map1.TrackingLayer.Refresh True
End Sub

Private Sub MakeShapeFromSelection(ByVal oRecset As _


MapObjects2.Recordset)
Dim oTable As MapObjects2.TableDesc
Dim oDataset As MapObjects2.GeoDataset
Dim oConnection As New MapObjects2.DataConnection
Dim oLayer As New MapObjects2.MapLayer
Dim oField As MapObjects2.Field
Dim otemprecs As MapObjects2.Recordset

Check out the path of your current directory - you may wish to
change
this path to a more suitable location.
oConnection.Database = CurDir
If oConnection.Connect Then
Set oTable = oRecset.TableDesc
Set oDataset = oConnection.AddGeoDataset(shptemp, _
moPolygon, oTable)
If oDataset Is Nothing Then Exit Sub
Set oLayer.GeoDataset = oDataset
Map1.Layers.Add oLayer
oRecset.MoveFirst

Set otemprecs = Map1.Layers(shptemp).Records

otemprecs.AutoFlush = False optimize by not flushing


changes automatically

Do While Not oRecset.EOF


With otemprecs
.AddNew
For Each oField In moRecset.Fields
.Fields(oField.Name).Value = oField.Value
Next
.Update
End With
oRecset.MoveNext
Loop
otemprecs.AutoFlush = True flush the file
End If

MsgBox Shapefile written to & CurDir, vbInformation _

ProgrammersReference.pmd 45 10/28/2004, 10:00 AM


46 MapObjects Programmers Reference

, Shapefile Exported

Map1.Layers.Remove 1

Map1.Layers(shptemp).Visible = True
Map1.Extent = Map1.Layers(shptemp).Extent

End Sub

Axis Property
Applies To Spheroid Object

Description Sets or returns a value that identifies the semimajor Axis upon which the Spheroid is based.

Syntax object.Axis [= value ]

The Axis property syntax has these parts:

Part Description

object An object expression that evaluates to a Spheroid object.

value A double value that specifies the length of the semimajor Axis of the
Spheroid.

Remarks A Spheroid is based on the two radii of an Ellipse, the shorter of which is referred to as the
semiminor axis, and the longer as the semimajor. The line of latitude midway between the
poles of the earth is called the Equator, and defines the semimajor axis of the earth. The
vertical axis (the Polar axis), connecting the centre of the earth with either pole, may also be
referred to as the PrimeMeridian.

See Also Datum Object

Example This example demonstrates how the Flattening and Axis properties of the Spheroid object may
be changed. To try this example, paste the code into the Declarations section of a new Form
which has two textboxes named Text1 and Text2, and a CommandButton named Command1.
Also, there you should add a Map named Map1 containing one MapLayer which has a
GeoCoordSys set. Then press F5, enter different values in the two textboxes, and click
Command1.
Option Explicit

Private Sub Command1_Click()


Dim theSphere As New MapObjects2.Spheroid
Dim theDatum As New MapObjects2.Datum

ProgrammersReference.pmd 46 10/28/2004, 10:00 AM


MapObjects Programmers Reference 47

Dim theGCS As New MapObjects2.GeoCoordSys


theSphere.Type = Map1.Layers(0).CoordinateSystem. _
GeoCoordSys.Datum.Spheroid.Type
theSphere.Axis = Text1.Text
theSphere.Flattening = Text2.Text

theDatum.Type = Map1.Layers(0).CoordinateSystem. _
GeoCoordSys.Datum.Spheroid.Type
theDatum.Spheroid = theSphere
theGCS.Type = Map1.Layers(0).CoordinateSystem._
GeoCoordSys.Datum.Spheroid.Type
theGCS.Datum = theDatum

Map1.Layers(0).CoordinateSystem = theGCS
Map1.Refresh

End Sub

Private Sub Form_Load()


Text1.Text = Map1.Layers(0).CoordinateSystem. _
GeoCoordSys.Datum.Spheroid.Axis
Text2.Text = Map1.Layers(0).CoordinateSystem.GeoCoordSys _
.Datum.Spheroid.Flattening
Command1.Caption = Set New Values
End Sub

BackColor Property
Applies To Map Object

Description Returns or sets the background color for a Map

See Also Appearance Property, BorderStyle Property, ScrollBars Property

Syntax object.BackColor [= color]

The BackColor property syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

color A value or constant that determines the color of the background of the Map
control.

ProgrammersReference.pmd 47 10/28/2004, 10:00 AM


48 MapObjects Programmers Reference

Settings See ColorConstants

Remarks Note that when using a Map control with its WindowMode property set to Windowless
Transparent, the BackColor will not be used, as the background of the Map is transparent.
Any features in MapLayers with the same color as the BackColor property will also be
rendered transparent.

Example This example uses the BackColor property to toggle the background color of a Map. To try
this example, paste the code into the Declarations section of a form containing a
CommandButton named Command1 and a Map named Map1 and then press F5 and click the
button.
Option Explicit
Private Sub Command1_Click()
If Map1.BackColor = moBlack Then
Map1.BackColor = moWhite
Command1.Caption = Black
Else
Map1.BackColor = moBlack
Command1.Caption = White
End If
End Sub

Private Sub Form_Load()


Command1.Caption = Black
End Sub

BackgroundRenderer Property
Applies To LabelPlacer Object

Description Returns or sets a reference to the renderer MapObjects will use to render the MapLayer
features prior to invoking the LabelPlacer.

Syntax object.BackgroundRenderer [= renderer]

The BackgroundRenderer property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

renderer An object expression that evaluates to a MapObjects renderer object. This


can be any of the renderers in the See Also list.

ProgrammersReference.pmd 48 10/28/2004, 10:00 AM


MapObjects Programmers Reference 49

Remarks A Renderer is a creatable object in MapObjects. In Visual Basic, heres one way to create one
of the kinds of renderers:
Set Map1.Layers(0).Renderer = New MapObjects2.ValueMapRenderer
To draw with a single symbol, set the Renderer property to Nothing.

See Also ClassBreaksRenderer Object, ChartRenderer Object, DotDensityRenderer Object,


Symbol Object, ValueMapRenderer Object, ZRenderer Object

Example This example uses a GroupRenderer to serve as the BackgroundRenderer of a LabelPlacer to


render a street network. To try this example, paste the code into the Declarations section of a
form that contains a CommandButton named Command1, two CheckBox controls named
Check1 and Check2, and a Map control named Map1 that contains a MapLayer with line
features. The example assumes the MapLayer is based on the Redlands shapefile in the sample
data. Press F5. You can click-drag to zoom in or use the right-mouse button to pan.
Option Explicit
Dim g_StreetRenderer As New MapObjects2.GroupRenderer
Dim LabelPlacer As New MapObjects2.LabelPlacer

Private Sub Check1_Click()


If Check1.Value = vbChecked Then
re-attach the group renderer
Set Map1.Layers(0).Renderer.BackgroundRenderer = g_StreetRenderer
Else
detach the group renderer
Set g_StreetRenderer = Map1.Layers(0).Renderer.BackgroundRenderer
Set Map1.Layers(0).Renderer.BackgroundRenderer = Nothing
End If
Map1.Refresh
End Sub

Private Sub Check2_Click()


Map1.Layers(0).Renderer.MaskLabels = (Check2.Value = 1)
Map1.Refresh
End Sub

Private Sub Command1_Click()


Dim r As Rectangle
Set r = Map1.Extent
r.ScaleRectangle 1.5
Map1.Extent = r
End Sub

Private Sub Form_Load()

ProgrammersReference.pmd 49 10/28/2004, 10:00 AM


50 MapObjects Programmers Reference

Check1.Caption = Use GroupRenderer as BackgroundRenderer


Command1.Caption = Zoom Out

Check2.Caption = Mask Labels


Check2.Value = vbUnchecked

set a backcolor for the map


Map1.BackColor = 14811135

set an initial extent


Dim r As New Rectangle
r.Left = -117.183964079772
r.Right = -117.160018438746
r.Top = 34.047951088234
r.Bottom = 34.0285801368372
r.ScaleRectangle 0.75

Set Map1.Extent = r

default color for the layer


Map1.Layers(0).Symbol.Color = moNavy

create a font to be used by the LabelPlacer


Dim fnt As New StdFont
fnt.Name = Times
fnt.Bold = False

setup the LabelPlacer


Dim LabelPlacer As New MapObjects2.LabelPlacer
Set Map1.Layers(0).Renderer = LabelPlacer

LabelPlacer.Field = NAME
LabelPlacer.DrawBackground = True

default symbol
LabelPlacer.DefaultSymbol.Height = Map1.FullExtent.Height / 150
Set LabelPlacer.DefaultSymbol.Font = fnt
LabelPlacer.AllowDuplicates = False

add a specific value for major roads


LabelPlacer.ValueField = CFCC
LabelPlacer.ValueCount = 1
LabelPlacer.Value(0) = A31
fnt.Bold = True
Set LabelPlacer.Symbol(0).Font = fnt
LabelPlacer.Symbol(0).Height = Map1.FullExtent.Height / 100

ProgrammersReference.pmd 50 10/28/2004, 10:00 AM


MapObjects Programmers Reference 51

mask the labels


labelPlacer.masklabels = True
LabelPlacer.MaskColor = Map1.BackColor

create a group renderer to act as the background


renderer for the LabelPlacer and populate it with
two renderers to draw the streets
Set LabelPlacer.BackgroundRenderer = g_StreetRenderer

create a renderer for the interior part of the


roads
Dim vR As New ValueMapRenderer
vR.Field = CFCC
vR.ValueCount = 1
vR.SymbolType = moLineSymbol
vR.Value(0) = A31
vR.Symbol(0).Color = moRed
vR.Symbol(0).Size = 6
vR.DefaultSymbol.Color = moLightGray
vR.DefaultSymbol.Size = 6
g_StreetRenderer.Add vR first renderer for the group

setup a value map renderer to draw the exterior


part of the road
Set vR = New ValueMapRenderer
vR.Field = CFCC
vR.SymbolType = moLineSymbol
vR.DefaultSymbol.Size = 2
vR.DefaultSymbol.Color = moWhite
g_StreetRenderer.Add vR next renderer for the group

Check1.Value = Checked
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

ProgrammersReference.pmd 51 10/28/2004, 10:00 AM


52 MapObjects Programmers Reference

BarHeight Property
Applies To ChartRenderer Object

Description Returns or sets the full height of the bar chart in points.

Syntax object.BarHeight [= value]

The BarHeight property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value An integer that represents the full height of the bar chart in points.

Remarks Bar charts are scaled such that the largest bar will equal the specified BarHeight. If any of the
data the ChartRenderer renders has a negative value, then the full size of the chart will be
twice the BarHeight. If no BarHeight is specified a default value of 20 points is used.

See Also BarWidth Property

Example This example uses the BarHeight and BarWidth properties of the ChartRenderer to control the
height and width of the bar charts drawn on the map features. To try this example, paste the
code in the Declarations section of a form that contains two TextBoxes named Text1 and
Text2, a CommandButton named Command1 and a Map named Map1 that contains a
MapLayer that has numeric data to render. This example assumes the MapLayer is the USA
Counties sample data, therefore if needed, you should change the values in the Field property
array. Press F5 to run the example; you can change the values of the dimensions of the bar
charts and then click Command1 to display them.
Option Explicit
Dim cr As New MapObjects2.ChartRenderer

Private Sub Command1_Click()


With cr
.ChartType = moBar
.FieldCount = 2
.Field(0) = Males
.Field(1) = Females
.Color(0) = moRed
.Color(1) = moGreen
.BarHeight = Text1.Text
.BarWidth = Text2.Text
End With

ProgrammersReference.pmd 52 10/28/2004, 10:00 AM


MapObjects Programmers Reference 53

Map1.Refresh
End Sub

Private Sub Form_Load()


Set Map1.Layers.Item(0).Renderer = cr
Text1.Text = 30
Text2.Text = 15
Command1.Caption = Show Renderer

Dim ext As New MapObjects2.Rectangle


ext.Left = -74.5
ext.Right = -73.5
ext.Top = 41
ext.Bottom = 40
Map1.Extent = ext
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

BarWidth Property
Applies To ChartRenderer Object

Description Returns or sets the full width of the bar chart in points.

Syntax object.BarWidth [= value]

The BarWidth property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value An integer that represents the full width of the bar chart in points.

Remarks All the bars of the bar chart will be scaled to fit within the specified BarWidth value. If no
BarWidth is specified a default value of 20 points is used.

See Also BarHeight Property

ProgrammersReference.pmd 53 10/28/2004, 10:00 AM


54 MapObjects Programmers Reference

Example See BarHeight Property

BatchMatch Method
Applies To Geocoder Object

Description This method matches all the addresses in a Table, and creates a Shapefile containing the
results of the BatchMatch.

Syntax Set variable = object.BatchMatch (addressTable, addressField, dataConnection,


outputTable, streetFields)

The BatchMatch method syntax has these parts:

Part Description

variable A numeric expression that specifies the number of records have been
matched.

object An object expression that evaluates to an object in the Applies To list.

addressTable An object expression that evaluates to a Table that contains addresses.

addressField A string expression that represents the name of the field in addressTable that
contains the addresses to match against the StreetTable of the Geocoder
object. The addressField is the field that is parsed by the Standardizer
object. For example, the addressField may contain records such as 380
New York St. If there is an additional field used for matching, such as ZIP
or city name, specify the field in the Geocoder objects
BatchMatchVariable field property

dataConnection A DataConnection object whose Database property contains the location


in which to write outputTable.

outputTable A string expression that represents the name of the shapefile containing the
results of the BatchMatch method action.

streetFields An object expression that evaluates to a MapObjects Strings object. The


members of the collection are the names of the StreetTable fields to write to
outputTable.

Remarks The addressTable can be created either within MapObjects, or by connecting to a file, see the
Table Object page for more information.

ProgrammersReference.pmd 54 10/28/2004, 10:00 AM


MapObjects Programmers Reference 55

The results of the BatchMatch can be found in the outputTable, the dataConnection param-
eter of the BatchMatch method determines where the outputTable will be located. The
outputTable is a shapefile, whose Shape field contains Point features. These Point features
represent the Location of each address which is matched.

The BatchMatch method returns the number of addresses that have been matched.
MapObjects adds all addressTable fields, plus any specified streetFields to the outputTable. If
you do not want to add any streetFields, specify an empty Strings object or Nothing as the
argument.

Fields named Side, Status and Score are also added to the outputTable, giving you
information about the matching process. A Side Field will only be added to the outputTable
if the addresses are geocoded to a StreetTable that specifies house number fields on the left
and right street sides. The Status Field shows the match status of the address. It is either M
(successfully matched) or U (not matched). Addresses with a MatchScore below the
MinimumMatchScore are not matched.

The Score Field stores the MatchScore of each address. In a range of 0 to 100, 100 signifies
a highly confident or exact match. If an address is not matched (U in the Status field), the
Score Field will be blank and the Value of the Shape Field will be Nothing.

A Geocoder used for batch matching must be valid, i.e. must be set up in a similar way as a
Geocoder used with the LocateCandidate method.

See Also Table Object, StreetTable Property, BatchMatchVariable Property,


MatchWhenAmbiguous Property, MinimumMatchScore Property

Example This example demonstrates how to use the BatchMatch method and set the
BatchMatchVariableField property to match a file of addresses. To try this example, paste the
code into the Declarations section of a form that contains a CommonDialog named
CommonDialog1, a Map named Map1, and a CommandButton named Command. Substitute
appropriate values for all the data paths. Press F5, then click Addresses to specify the name of
a dBASE file that contains a list of addresses. Note that the name of the Table objects
Database property for the dBASE Driver DataSource is hard-coded in Command1_Click. You
should ensure you have set an appropriate Data Source Name in using the ODBC utility in
Windows Control Panel. Try different values in the MinimumMatchScore and
MatchWhenAmbiguous properties and see the different results.
Option Explicit
Dim geo As New MapObjects2.Geocoder
Dim stan As New MapObjects2.Standardizer
Dim dcx As New MapObjects2.DataConnection

Set global variables with field names in the StreetTable


Modify if fields names in StreetTable are different.
If a field is not available, set it with an empty string

ProgrammersReference.pmd 55 10/28/2004, 10:00 AM


56 MapObjects Programmers Reference

Private Const m_FromLeft = L_f_add


Private Const m_FromRight = R_f_add
Private Const m_ToLeft = L_t_add
Private Const m_ToRight = R_t_add
Private Const m_PreDir = Prefix
Private Const m_PreType = Pre_type
Private Const m_StreetName = Name
Private Const m_StreetType = Type
Private Const m_SufDir = Suffix
Private Const m_LeftZone = Zipl
Private Const m_RightZone = ZipR

Private Sub Command1_Click()


Dim AddressTable As New MapObjects2.Table
Dim ml As New MapObjects2.MapLayer
Dim ft As String, fn As String
Dim count As Integer

geo.MinimumMatchScore = 70
geo.MatchWhenAmbiguous = True

With CommonDialog1
.FileName =
.Filter = dBASE (*.dbf)|*.dbf
.DefaultExt = *.dbf
.CancelError = True
On Error Resume Next
.ShowOpen
If Err.Number = cdlCancel Then
Unload Me
End If
ft = .FileTitle
fn = .FileName
End With

This example uses an AddressTable from an ODBC DataSource.


If using an ODBC DataSource to create an AddressTable you
should ensure that you have an appropriate DataSourceName set
(see Windows Control Panel, ODBC) You can access other data
sources to create a MapObjects2.Table object, for details see
the online help.
AddressTable.Database = CustomerDB name of ODBC DataSource
AddressTable.name = Left(ft, Len(ft) - 4)
FileTitle without extension

dcx.Database = Left(fn, Len(fn) - Len(ft) - 1) where to

ProgrammersReference.pmd 56 10/28/2004, 10:00 AM


MapObjects Programmers Reference 57

write outputTable

If AddressTable.name <> And dcx.Connect Then


geo.BatchMatchVariableField(LeftZone) = ZIPl
geo.BatchMatchVariableField(RightZone) = ZIPr
count = geo.BatchMatch(AddressTable, ADDRESS, dcx, _
results, Nothing)
MsgBox Successfully geocoded & count & addresses!

Debug.Print AddressTable.Records.count

If count <> 0 Then


Set ml.GeoDataset = dcx.FindGeoDataset(results)
Map1.Layers.Add ml
With Map1.Layers(results).Symbol
.SymbolType = moPointSymbol
.Color = moRed
.Style = moCircleMarker
End With
Map1.Refresh
End If
Else
MsgBox Didnt match addresses in dbf file
End If

End Sub

Private Sub Form_Load()

Dim dc As New MapObjects2.DataConnection


Dim gd As Object
Dim lyr As New MapLayer
Dim f, i As Integer
Dim name As String

Set up Standardizer
Change the paths below to ones appropriate for your data
stan.StandardizingRules = C:\Program Files\ESRI\MapObjects2 _
\GeoRules\us_addr.stn
stan.IntersectionStandardizingRules = C:\Program Files _
\ESRI\MapObjects2\GeoRules\us_intsc.stn
Set geo.Standardizer = stan

Change the paths below to ones appropriate for your data


dc.Database = C:\Program Files\ESRI\MapObjects2 _
\Samples\Data\Redlands

ProgrammersReference.pmd 57 10/28/2004, 10:00 AM


58 MapObjects Programmers Reference

dc.Connect
If Not dc.Connected Then
MsgBox dc.connected error
End
End If

Set up the StreetTable


Set gd = dc.FindGeoDataset(redlands)
lyr.GeoDataset = gd
lyr.Symbol.Color = moBlue
Map1.Layers.Add lyr
geo.StreetTable = gd

Set up the match rules and variables


Change the paths below to ones appropriate for your data
geo.MatchRules = C:\Program Files\ESRI\MapObjects2\ _
GeoRules\us_addr1.mat
geo.IntersectionMatchRules = C:\Program Files\ESRI\MapObjects2 _
\GeoRules\us_intsc1.mat

Link the Match Variables to fields in the StreetTable


geo.MatchVariableField(FromLeft) = m_FromLeft
geo.MatchVariableField(FromRight) = m_FromRight
geo.MatchVariableField(ToLeft) = m_ToLeft
geo.MatchVariableField(ToRight) = m_ToRight
geo.MatchVariableField(PreDir) = m_PreDir
geo.MatchVariableField(PreType) = m_PreType
geo.MatchVariableField(StreetName) = m_StreetName
geo.MatchVariableField(StreetType) = m_StreetType
geo.MatchVariableField(SufDir) = m_SufDir
geo.MatchVariableField(LeftZone) = m_LeftZone
geo.MatchVariableField(RightZone) = m_RightZone

Link the intersection group 1 variables


geo.MatchVariableIntersectionLink(PreDir, _
mgLinkPrimary) = PreDir1
geo.MatchVariableIntersectionLink(PreType, _
mgLinkPrimary) = PreType1
geo.MatchVariableIntersectionLink(StreetName, _
mgLinkPrimary) = StreetName1
geo.MatchVariableIntersectionLink(StreetType,_
mgLinkPrimary) = StreetType1
geo.MatchVariableIntersectionLink(SufDir, _
mgLinkPrimary) = SufDir1
geo.MatchVariableIntersectionLink(LeftZone, _
mgLinkPrimary) = LeftZone1

ProgrammersReference.pmd 58 10/28/2004, 10:00 AM


MapObjects Programmers Reference 59

geo.MatchVariableIntersectionLink(RightZone, _
mgLinkPrimary) = RightZone1

Link up intersection group 2 variables


geo.MatchVariableIntersectionLink(PreDir, _
mgLinkSecondary) = PreDir2
geo.MatchVariableIntersectionLink(PreType, _
mgLinkSecondary) = PreType2
geo.MatchVariableIntersectionLink(StreetName, _
mgLinkSecondary) = StreetName2
geo.MatchVariableIntersectionLink(StreetType, _
mgLinkSecondary) = StreetType2
geo.MatchVariableIntersectionLink(SufDir, _
mgLinkSecondary) = SufDir2
geo.MatchVariableIntersectionLink(LeftZone, _
mgLinkSecondary) = LeftZone2
geo.MatchVariableIntersectionLink(RightZone, _
mgLinkSecondary) = RightZone2

Build indices if havent


If Not geo.IndexStatus = MapObjects2.IndexStatusConstants. _
mgIndexExists Then
If Not geo.AddIndex(m_StreetName, , mgIndexTypeSoundex) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.AddIndex(m_LeftZone, m_RightZone, _
mgIndexTypeNormal) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.BuildIndices(True) Then
MsgBox Cannot build geocoding index., vbCritical
End
Else
MsgBox Indices are built.
End If
End If

Set search queries


Dim queries As New MapObjects2.Strings
queries.Add SN? & ZN
queries.Add SN?
Set geo.SearchQueries = queries

Command1.Caption = Addresses

ProgrammersReference.pmd 59 10/28/2004, 10:00 AM


60 MapObjects Programmers Reference

End Sub

BatchMatchVariableField Property
Applies To Geocoder Object

Description Returns or sets field names in addition to the addressField specified in the Geocoder objects
BatchMatch method.

Syntax object.BatchMatchVariableField [ = fieldName]

The BatchMatchVariableField property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

fieldName A string expression that specifies the name of the field in the address table
for batch matching. This is an additional field used for matching, such as
ZIP or city name. Unlike the addressField, this field will not parsed with a
Standardizer object.

Remarks The addressField parameter of the BatchMatch method defines the Field that is parsed by a
Standardizer object. If there is an additional Field which is required for matching, for
example a separate Field in the addressTable such as ZIP or city name, this Field needs to be
specified in the objects BatchMatchVariableField property.

If the Field specified in the addressField parameter is not valid, the


BatchMatchVariableField property returns False.

This property is optional, if no additional Table Fields are required for the batch match, you
do not need to set a BatchMatchVariableField.

See Also BatchMatch Method, StreetTable Property, FieldValue Property

Example See BatchMatch Method

BeforeLayerDraw Event
Applies To Map Object

Description Occurs when a Map starts to draw a specified layer.

ProgrammersReference.pmd 60 10/28/2004, 10:00 AM


MapObjects Programmers Reference 61

Syntax Private Sub object_BeforeLayerDraw(ByVal index As Integer, ByVal hDC As


Stdole.OLE_HANDLE)

The BeforeLayerDraw event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

index An integer that uniquely identifies a member of the Layers collection.

hDC A handle provided by the Microsoft Windows operating environment to the


device context of the Map.

Remarks You can use the hDC to refer to the handle for an objects device context. This provides a
value to pass to Windows API calls.

See Also AfterLayerDraw Event, AfterTrackingLayerDraw Event, BeforeTrackingLayerDraw


Event

Example This example illustrates when the BeforeLayerDraw Event occurs. Prior to drawing each layer
on the Map, the code determines which of two layers to draw based on how close youve
zoomed in to the map. To try this example, paste the code into the Declarations section of a
form containing a command button called Command1 and a Map named Map1 that contains
two MapLayer objects, one with greater detail than another, and then press F5. Click on the
map to zoom in or press Command1 to zoom to the full extent of the map.
Option Explicit

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

Private Sub Map1_BeforeLayerDraw(ByVal index As Integer, ByVal hDC _


As stdole.OLE_HANDLE)
greater detail in layers(1)
If Map1.Extent.Width < Map1.FullExtent.Width / 4 Then
Map1.Layers(0).Visible = False
Map1.Layers(1).Visible = True
Else
Map1.Layers(0).Visible = True
Map1.Layers(1).Visible = False
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)

ProgrammersReference.pmd 61 10/28/2004, 10:00 AM


62 MapObjects Programmers Reference

Dim rect As MapObjects2.Rectangle


Set rect = Map1.Extent
rect.ScaleRectangle 0.5
Map1.Extent = rect
End Sub

Private Sub Form_Load()


Command1.Caption = Full Extent
End Sub

BeforeTrackingLayerDraw Event
Applies To Map Object

Description Occurs when a Map starts to display the GeoEvent objects on its TrackingLayer.

Syntax Private Sub object_BeforeTrackingLayerDraw(ByVal hDC As Stdole.OLE_HANDLE)

The BeforeTrackingLayerDraw event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

hDC A handle provided by the Microsoft Windows operating environment to the


device context of the Map.

Remarks You can use the hDC to refer to the handle for an objects device context. This provides a
value to pass to Windows API calls.

See Also BeforeLayerDraw Event, AfterLayerDraw Event, AfterTrackingLayerDraw Event

Example This example illustrates when the BeforeTrackingLayerDraw Event occurs. The example
traces the path of a GeoEvent initially added to the TrackingLayer at the center of the Maps
extent. Clicking on the Map designates a new location for the GeoEvent. The code in the
BeforeTrackingLayerDraw event draws the trail. To try this example, paste the code into the
Declarations section of a form containing ListBox named List1 and a Map named Map1 that
contains at least one MapLayer, and then press F5. Click on the map to specify a new location.
Change the symbol of the trail by selecting from the list.
Option Explicit
Dim ln As New MapObjects2.Line

Private Sub Form_Load()


Dim pt As MapObjects2.Point
List1.AddItem Solid Line

ProgrammersReference.pmd 62 10/28/2004, 10:00 AM


MapObjects Programmers Reference 63

List1.AddItem Dashed Line


List1.AddItem Dotted Line
List1.AddItem Dash-Dot Line
List1.AddItem Dash-Dot-Dot Line
List1.ListIndex = 0
Set pt = Map1.Extent.Center
Map1.TrackingLayer.AddEvent pt, 0
End Sub

Private Sub Map1_BeforeTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If Not ln Is Nothing Then
Dim sym As New MapObjects2.Symbol

sym.SymbolType = moLineSymbol
sym.Style = List1.ListIndex
sym.Color = moBlue
Map1.DrawShape ln, sym
End If

End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim evpt As New MapObjects2.Point
Dim newpt As New MapObjects2.Point
Set newpt = Map1.ToMapPoint(X, Y)
With Map1.TrackingLayer.Event(0)
evpt.X = .X
evpt.Y = .Y
End With
Dim pts As New MapObjects2.Points
pts.Add evpt
pts.Add newpt
ln.Parts.Add pts
Map1.TrackingLayer.Event(0).MoveTo newpt.X, newpt.Y

Map1.TrackingLayer.Refresh True
End Sub

BorderStyle Property
Applies To Map Object

Description Returns or sets the border style for a Map.

ProgrammersReference.pmd 63 10/28/2004, 10:00 AM


64 MapObjects Programmers Reference

Syntax object.BorderStyle [= value]

The BorderStyle property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A value or constant that determines the border style, as described in Set-
tings.

Settings The BorderStyle property settings for a Map control are:

Setting Description

0 None.

1 (Default) Fixed Single.

See Also Appearance Property, BackColor Property, Scrollbars Property

Example This example uses the BorderStyle property to toggle the border of a Map. To try this ex-
ample, paste the code into the Declarations section of a form containing a CommandButton
named Command1 and a Map named Map1 and then press F5 and click the button.
Option Explicit
Private Sub Command1_Click()
If Map1.BorderStyle = 1 Then
Map1.BorderStyle = 0
Command1.Caption = Border
Else
Map1.BorderStyle = 1
Command1.Caption = No Border
End If
End Sub

Private Sub Form_Load()


Command1.Caption = No Border
End Sub

Bottom Property
Applies To Ellipse Object, Rectangle Object

Description Returns or sets the distance between the internal bottom edge of an object and the top edge of
its container.

ProgrammersReference.pmd 64 10/28/2004, 10:00 AM


MapObjects Programmers Reference 65

Syntax object.Bottom [= value]

The Bottom property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression specifying distance.

See Also Top Property, Left Property

Example This example uses the Bottom property to provide a coordinate point to use to position
graphic text on a map. To try this example, paste the code into the Declarations section of a
form containing a Map named Map1 that contains at least one MapLayer. Press F5 and then
click-drag a Rectangle after the MapLayers finish drawing.
Option Explicit
Dim oRect As New MapObjects2.Rectangle
Private mbTextAlreadyDisplayed As Boolean

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As Stdole.OLE_HANDLE)
Dim oSymbol As New MapObjects2.Symbol
Dim oTextsymbol As New MapObjects2.TextSymbol
Dim oPoint As New MapObjects2.Point
Dim oFont As New StdFont

If Not mbTextAlreadyDisplayed Then


oFont.name = Arial
With oTextsymbol
Set .Font = oFont This assigns the Font object
set the alignment properties of the Textsymbol object
.HorizontalAlignment = moAlignLeft
.VerticalAlignment = moAlignBaseline
End With

derive point location from the rectangles corner


With oPoint
.x = oRect.Left
.y = oRect.Bottom
End With

draw the rectangle and the text


oSymbol.Style = moTransparentFill
Map1.DrawShape oRect, oSymbol
oTextsymbol.Height = oRect.Height text height in map units

ProgrammersReference.pmd 65 10/28/2004, 10:00 AM


66 MapObjects Programmers Reference

Map1.DrawText MapObjects2, oPoint, oTextsymbol


mbTextAlreadyDisplayed = True
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Set oRect = Map1.TrackRectangle
mbTextAlreadyDisplayed = False
Map1.Refresh
End Sub

Break Property
Applies To ClassBreaksRenderer Object, ZRenderer Object

Description Returns or sets the upper bound of a category or class of data in a renderer object.

Syntax object.Break( index) [= value]

The Break property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index An integer that specifies a category. The integer must be a number from 0 to
one less than the value of the renderers BreakCount property.

value A numeric expression that evaluates to the upper bound of the category or
class of data. (Data type is Double.)

See Also BreakCount Property

Example This example uses the properties and methods of the ClassBreaksRenderer to create a standard
deviation classification. The code initializes a ClassBreaksRenderer with class breaks of three
standard deviations away from the mean in both directions. Only those break values that are
within the data range are added to the renderer. To try this example, paste the code into the
Declarations section of a form containing a CommonDialog control, a CommandButton named
Command1, a ListBox named List1, and a Map named Map1 that contains one MapLayer with
polygon features. Press F5 and select the name of a numeric field appropriate to your data
from the list; click the button to see the results.
Option Explicit

Private Sub Command1_Click()

ProgrammersReference.pmd 66 10/28/2004, 10:00 AM


MapObjects Programmers Reference 67

Dim oClassRend As New MapObjects2.ClassBreaksRenderer


Dim oStats As New MapObjects2.Statistics
Dim i As Integer
Dim fBreakVal As Double

Appropriate logical tests for the chosen maplayer should be


inserted below.
If Not Map1.Layers(0).Records.Fields(List1.Text).Type = _
moString Then

With oClassRend
.SymbolType = moFillSymbol
.Field = List1.Text
Set oStats = Map1.Layers(0).Records. _
CalculateStatistics(List1.Text)

calculate breaks away from the mean in both directions,


but only add those breaks that are within the range of values
fBreakVal = oStats.Mean - (oStats.StdDev * 3)
For i = 0 To 6
If fBreakVal >= oStats.Min And fBreakVal <= oStats.Max Then
.BreakCount = .BreakCount + 1
.Break(.BreakCount - 1) = fBreakVal
Debug.Print Break Val = ; fBreakVal
End If
fBreakVal = fBreakVal + oStats.StdDev
Next

.RampColors moYellow, moBlue


Set Map1.Layers(0).Renderer = oClassRend
End With
Map1.Refresh

Else
MsgBox Data type not suitable: & _
Map1.Layers(0).Records.Fields(List1.Text).Type
End If
End Sub

Private Sub Form_Load()


Dim oField As MapObjects2.Field
For Each oField In Map1.Layers(0).Records.Fields
List1.AddItem oField.name
Next
End Sub

ProgrammersReference.pmd 67 10/28/2004, 10:00 AM


68 MapObjects Programmers Reference

BreakCount Property
Applies To ClassBreaksRenderer Object, ZRenderer Object

Description Returns or sets the number of breaks between categories or classes of data used to classify the
values of the Field property of a ClassBreaksRenderer object. For a ZRenderer object, the
shapes Z values are used.

Syntax object.BreakCount [= value]

The BreakCount property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value An integer that species the number of breaks between categories or classes
of data. (Data type is Integer.)

Remarks There is always one more category than the value of BreakCount.

See Also Break Property

Example See Break property

Buffer Method
Applies To Point Object, Points Collection, Line Object, Polygon Object, Rectangle Object, Ellipse
Object

Description Returns a shape object that represents the perimeter of another shape object that has been
increased or decreased by a specific distance in all directions.

Syntax Set resultShape = object.Buffer (bufferDistance [,extent])

The Buffer method syntax has these parts:

Part Description

resultShape An object expression that evaluates to a shape object. Will contain the
resulting buffered shape.

ProgrammersReference.pmd 68 10/28/2004, 10:00 AM


MapObjects Programmers Reference 69

object An object expression that evaluates to an object in the Applies To list. This
is the object which is to be buffered.

bufferDistance A numeric expression that represents the distance by which object should be
buffered. This distance must be positive for Point, Points or Line objects.

extent An object expression that evaluates to a Rectangle object. This Rectangle


should entirely contain the objects extent, and is used.

Remarks A negative buffer distance can be specified for Rectangle, Polygon and Ellipse objects only.
In this case, the resulting buffered shape will be inset from the input object (i.e. it will have a
smaller radius). If a negative number is specified for a Point object, Points object or Line
object, then it is treated as a positive number of the same absolute value.

Buffering of a self-intersecting Polygon is not supported, however a self-intersecting Line


may be buffered.

If you set a buffer distance of zero on an Ellipse object, the resultShape will be a Polygon
clone of that ellipse. A buffer distance of zero on a Point, Points, Line, Rectangle or Polygon
object will not set the resultShape object.

See Also Difference Method

Example This example uses the Buffer method to allow the user to buffer points, lines, rectangles,
polygons and ellipses. The user point and the new shape generated by the buffer operation are
added to the tracking layer as GeoEvents. To try this example, paste the code into the Declara-
tions section of a form containing a Map named Map1 that has at least one MapLayer, and 5
OptionButtons named Option1 to Option5. Also add a Textbox named Text1. Press F5, and
choose an option, then click on the map to create a point, or track a line, rectangle, ellipse or
polygon. Try changing the value in the textbox.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Point buffering
If Option1.Value Then
Dim pt As New MapObjects2.Point
Dim eventPt As New MapObjects2.GeoEvent
Dim buffPt As New MapObjects2.Polygon
Dim buffEventPt As New MapObjects2.GeoEvent

Set pt = Map1.ToMapPoint(x, y)
Set eventPt = Map1.TrackingLayer.AddEvent(pt, 0)
Set buffPt = pt.Buffer(Text1.Text, Map1.FullExtent)
Set buffEventPt = Map1.TrackingLayer.AddEvent(buffPt, 3)

ProgrammersReference.pmd 69 10/28/2004, 10:00 AM


70 MapObjects Programmers Reference

Line buffering
ElseIf Option2.Value Then
Dim line As New MapObjects2.line
Dim eventLine As New MapObjects2.GeoEvent
Dim buffLine As New MapObjects2.Polygon
Dim buffEventLine As New MapObjects2.GeoEvent

Set line = Map1.TrackLine


Set eventLine = Map1.TrackingLayer.AddEvent(line, 1)
Set buffLine = line.Buffer(Text1.Text, Map1.FullExtent)
Set buffEventLine = Map1.TrackingLayer.AddEvent(buffLine, 3)

Rectangle buffering
ElseIf Option3.Value Then
Dim rect As New MapObjects2.Rectangle
Dim eventRect As New MapObjects2.GeoEvent
Dim buffRect As New MapObjects2.Polygon
Dim buffEventRect As New MapObjects2.GeoEvent

Set rect = Map1.TrackRectangle


Set eventRect = Map1.TrackingLayer.AddEvent(rect, 2)
Set buffRect = rect.Buffer(Text1.Text, Map1.FullExtent)
Set buffEventRect = Map1.TrackingLayer.AddEvent(buffRect, 3)

Polygon buffering
ElseIf Option4.Value Then
Dim poly As New MapObjects2.Polygon
Dim eventPoly As New MapObjects2.GeoEvent
Dim buffPoly As New MapObjects2.Polygon
Dim buffEventPoly As New MapObjects2.GeoEvent

Set poly = Map1.TrackPolygon


Set eventPoly = Map1.TrackingLayer.AddEvent(poly, 2)
Set buffPoly = poly.Buffer(Text1.Text, Map1.FullExtent)
Set buffEventPoly = Map1.TrackingLayer.AddEvent(buffPoly, 3)

Ellipse buffering
ElseIf Option5.Value Then
Dim arect As New MapObjects2.Rectangle
Dim elli As New MapObjects2.Ellipse
Dim eventElli As New MapObjects2.GeoEvent
Dim buffElli As New MapObjects2.Polygon
Dim buffEventElli As New MapObjects2.GeoEvent

Set arect = Map1.TrackRectangle

ProgrammersReference.pmd 70 10/28/2004, 10:00 AM


MapObjects Programmers Reference 71

elli.Top = arect.Top
elli.Bottom = arect.Bottom
elli.Left = arect.Left
elli.Right = arect.Right

Set eventElli = Map1.TrackingLayer.AddEvent(elli, 2)


Set buffElli = elli.Buffer(Text1.Text, Map1.FullExtent)
Set buffEventElli = Map1.TrackingLayer.AddEvent(buffElli, 3)

End If

End Sub
Private Sub Form_Load()
Option1.Caption = Point
Option2.Caption = Line
Option3.Caption = Rectangle
Option4.Caption = Polygon
Option5.Caption = Ellipse
Text1.Text = 100
Map1.TrackingLayer.SymbolCount = 4
With Map1.TrackingLayer.Symbol(0)
.SymbolType = moPointSymbol
.Style = moTriangleMarker
.Color = moRed
.Size = 3
End With
With Map1.TrackingLayer.Symbol(1)
.SymbolType = moLineSymbol
.Color = moRed
.Size = 3
End With
With Map1.TrackingLayer.Symbol(2)
.SymbolType = moFillSymbol
.Style = moGrayFill
.Color = moRed
.OutlineColor = moRed
End With
With Map1.TrackingLayer.Symbol(3)
.SymbolType = moFillSymbol
.Style = moGrayFill
.Color = moBlue
.OutlineColor = moBlue
End With
End Sub

ProgrammersReference.pmd 71 10/28/2004, 10:00 AM


72 MapObjects Programmers Reference

BuildIndex Method
Applies To MapLayer Object, PlaceLocator Object

Description Builds a spatial index on a MapLayer object that is based on a Shapefile GeoDataset, or an
index for a field of a PlaceNameTable of a PlaceLocator object.

Syntax object.BuildIndex( [field], force)

The BuildIndex method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

field A string expression that specifies the name of a field in a PlaceNameTable.


This parameter is only valid when object is a PlaceLocator.

force A boolean expression that determines whether MapObjects will build an


index regardless of the previous state of the index, as described in Settings.

Settings The settings for force are:

Setting Description

True The objects index rebuilds regardless of its previous state. Note that
building an index may take an appreciable amount of time.

False The objects index will not rebuild if it already exists.

Remarks The BuildIndex method returns True if the index built successfully. Otherwise, it returns
False.

BuildIndex should not be used on a MapLayer based on ARC/INFO Coverages, SDE layers,
or CAD files. However, MapObjects does make use of spatial indices built in the original
applications for these data sources.

When applied to a MapLayer object based on a shapefile, the BuildIndex method creates a
spatial index and stores it in two files that have the name of the GeoDataset as a prefix and
the following suffixes: .sbn and .sbx. The two files are stored in the same folder as the
GeoDataset. The spatial index enhances performance when zooming, panning, using the
SearchShape method, and the SearchByDistance method.

See Also Indexed Property, PlaceNameTable Property

ProgrammersReference.pmd 72 10/28/2004, 10:00 AM


MapObjects Programmers Reference 73

Example This example uses the Indexed property and BuildIndex method to add an index to the first
MapLayer in a map control. To try this example, paste the code into the Declarations section
of a form containing a CommonDialog Control named Common1, and a Map named Map1
that has at least one MapLayer, and a command button called Command1. Press F5, then click
the button.
Option Explicit
Private Sub Command1_Click()
If Not Map1.Layers(0).Indexed Then
If Map1.Layers(0).BuildIndex(False) Then
MsgBox Index Built for layer: & Map1.Layers(0).name
Else
MsgBox No index Built
End If
Else
MsgBox Layer & Map1.Layers(0).name & has an existing index.
End If
End Sub

Private Sub Form_Load()


Command1.Caption = Build Index
End Sub

BuildIndices Method
Applies To Geocoder Object

Description This method builds the indices on the Geocoder object which are defined in the AddIndex
method.

Syntax Set variable = object.BuildIndices ( force )

The BuildIndices Method syntax has these parts:

Part Description

variable A boolean expression that indicates whether the indices are built success-
fully.

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 73 10/28/2004, 10:00 AM


74 MapObjects Programmers Reference

force A boolean expression that evaluates whether MapObjects will build the
indices regardless of the previous state of the indices, as described in
Settings.

Settings The settings for force are:

Setting Description

True The objects indices rebuild regardless of its previous state. Note that
building the indices may take an appreciable amount of time.

False The objects indices will not rebuild if the index file already exists.

Remarks This method builds a geocoding index, or multiple indices, on match variables of the
StreetTable of a Geocoder. The indices must be specified before building, by using the
AddIndex method.

The BuildIndices method returns True if the index was built successfully. Otherwise, it returns
False. Use the Geocoder objects IndexStatus method to evaluate the status of the index. An
index file with a .gcd file extension will be created in the workspace of the StreetTables
GeoDataset if the indices are built successfully.

See Also IndexStatus Method, AddIndex Method

Example See AddIndex method

CalculateStatistics Method
Applies To Recordset Object

Description Creates a Statistics object whose statistical properties you can return.

Syntax Set variable = object.CalculateStatistics( fieldname)

The CalculateStatistics method syntax has these parts:

Part Description

variable An object expression that evaluates to a Statistics object.

object An object expression that evaluates to the name of an open Recordset.

fieldname A string expression that evaluates to the name of the Field in the Recordset
for which to calculate statistics. Field must contain numeric values.

ProgrammersReference.pmd 74 10/28/2004, 10:00 AM


MapObjects Programmers Reference 75

Remarks The CalculateStatistics method calculates statistics for a Field whose records contain non-
null numeric values only.

See Also Statistics Object

Example This example uses the Min, Max, Mean, StdDev, and Sum properties to report statistics for a
numeric field. To try this example, paste the code into the Declarations section of a form
containing a List control named List1, two Label control arrays named Label1() and Label2(),
and a Map named Map1 that contains one MapLayer that has at least one numeric field. To
create the Label control arrays, set the Index property of each Label control to 0. The code in
Form_Load will create additional instances, but you should align Label1(0) with Label2(0)
vertically. Press F5 and click the field name in the list to see the statistics for the field.
Option Explicit

Private Sub Form_Load()


Dim i As Integer
Label1(0).AutoSize = True
Label2(0).AutoSize = True
Label2(0).Caption =
For i = 1 To 4 Create four more instances of Label1 and Label2.
Load Label1(i)
Load Label2(i)
Set the location of the new option button.
Label1(i).Top = Label1(i - 1).Top + Label1(0).Height + 40
Label1(i).Visible = True
Label2(i).Top = Label2(i - 1).Top + Label2(0).Height + 40
Label2(i).Visible = True
Next i

Label1(0).Caption = Min
Label1(1).Caption = Max
Label1(2).Caption = Mean
Label1(3).Caption = StdDev
Label1(4).Caption = Sum

End Sub

Private Sub List1_Click()


Dim oStats As MapObjects2.Statistics
Set oStats = Map1.Layers(0).Records.CalculateStatistics _
(List1.List(List1.ListIndex))
Label2(0) = oStats.Min
Label2(1) = oStats.Max
Label2(2) = oStats.Mean
Label2(3) = oStats.StdDev

ProgrammersReference.pmd 75 10/28/2004, 10:00 AM


76 MapObjects Programmers Reference

Label2(4) = oStats.Sum
End Sub

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As Stdole.OLE_HANDLE)
Dim oField As MapObjects2.Field
For Each oField In Map1.Layers(0).Records.Fields
fields that only contain numeric values:
If VarType(oField.Value) > vbNull And VarType(oField.Value) _
< moString Then
List1.AddItem oField.Name
End If
Next
End Sub

CancelAction Constants
MapObjects defines the following constants for use with the Map objects CancelAction
property to control what action to take if the application receives an ESC keypress.

Constant Value Description

moCancelNone 0 None. No action occurs, the application ignores


the ESC key.

moCancelMap 1 (Default). Your application will stop drawing all


layers. Only those features drawn before the user
pressed the ESC key will be visible.

moCancelLayer 2 Your application will stop drawing the layer its


currently drawing and start to draw any remain-
ing layers in the MapLayers collection.

See Also AfterLayerDraw Event, AfterTrackingLayerDraw Event, Map Object

CancelAction Property
Applies To Map Object

Description Returns or sets a value indicating what action to take if the user presses the ESC key when the
application draws the Map.

Syntax object.CancelAction [= action]

ProgrammersReference.pmd 76 10/28/2004, 10:00 AM


MapObjects Programmers Reference 77

The CancelAction property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

action A constant or value corresponding to the type of CancelAction you to take


when the user presses the ESC key, as described in Settings.

Settings The settings for action are CancelActionConstants.

See Also DrawingCancelled Event

Example This example demonstrates the role of the value of the CancelAction property if the user
presses ESC while the map is drawing. To try this example, paste the code into the Declara-
tions section of a form containing a ComboBox named Combo1, a CommandButton named
Command1 and a Map named Map1 that contains more than one MapLayer, and then press
F5. While the map is drawing, press the ESC key. Change the CancelAction setting in the
ComboBox to see what effect a different CancelAction setting has. Use Command1 to zoom to
the full extent of the map.
Option Explicit

Private Sub Combo1_Click()


Map1.CancelAction = Combo1.ListIndex
End Sub

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

Private Sub Form_Load()


Combo1.AddItem None
Combo1.AddItem Map
Combo1.AddItem Layer
Combo1.ListIndex = 1
Map1.CancelAction = moCancelMap
End Sub

Private Sub Map1_DrawingCanceled()


Dim response As Variant
response = MsgBox(The map is in an incomplete state. Zoom in? _
, vbYesNo)
If response = vbYes Then
Dim rect As New MapObjects2.Rectangle
Set rect = Map1.Extent

ProgrammersReference.pmd 77 10/28/2004, 10:00 AM


78 MapObjects Programmers Reference

rect.ScaleRectangle 0.1
Map1.Extent = rect
End If
End Sub

CancelUpdate Method
Applies To Recordset Object

Description Cancels any pending updates for the Recordset object represented by the object placeholder.

Syntax object.CancelUpdate

The CancelUpdate method syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

Remarks The CancelUpdate method cancels any updates made after a call to Edit or AddNew but
before a call to the Update method. Calling MoveNext before a call to Update has the same
effect as calling CancelUpdate.

Use the EditMode property to determine if there is a pending operation that can be canceled.

See Also Recordset Object, Edit Property, EditMode Property, and Updatable Property

Example This example uses the Edit method and the Updatable property in the context of a simple
record editing application. The code also demonstrates how to use the CancelUpdate method
to back out of making a change. In addition, the first time you change a record the code
demonstrates the EditMode property. Note that the example determines the number of records
by iterating through the Recordset. To try this example, paste the code into the Declarations
section of a form containing a CommandButton control named Command1, a ComboBox
named Combo1, a TextBox named Text1, and a Map named Map1 that has a MapLayer. For
the CommandButton, set its Index property to 0 in the Control Properties dialog box to create
a control array of one element, and then press F5. Choose a Field whose values you want to
change. Enter the new value in the text box and press the Change button. You can iterate
through the Recordset with the buttons named Next and Previous.
Dim editbufr As Variant
Dim recset As MapObjects2.Recordset
Dim TotalRecs As Integer

Private Sub Combo1_Click()


Text1.Text = recset.Fields(Combo1.List(Combo1.ListIndex)).Value

ProgrammersReference.pmd 78 10/28/2004, 10:00 AM


MapObjects Programmers Reference 79

End Sub

Private Sub Command1_Click(Index As Integer)


Static recnum

With recset.Fields(Combo1.List(Combo1.ListIndex))
Select Case Index
Case 0 Next
If recnum < TotalRecs Then
recset.MoveNext
Text1.Text = .Value
recnum = recnum + 1
Command1(1).Enabled = True
If recnum = TotalRecs - 1 Then
Command1(0).Enabled = False
Else
Command1(0).Enabled = True
End If
Map1.TrackingLayer.Refresh True
End If
Case 1 Previous
If recnum > 0 Then
recset.MovePrevious
Text1.Text = .Value
recnum = recnum - 1
Command1(0).Enabled = True
If recnum = 0 Then
Command1(1).Enabled = False
Else
Command1(1).Enabled = True
End If
Map1.TrackingLayer.Refresh True
End If
Case 2 Change
editbufr = .Value
recset.Edit
.Value = Text1.Text
resp$ = MsgBox(Are you sure you want to change the value _
?, vbYesNo + vbInformation, MapObjects)
If resp$ = vbYes Then
GetEditMode demonstrates EditMode property
recset.Update
GetEditMode
Else
recset.CancelUpdate
Text1.Text = editbufr

ProgrammersReference.pmd 79 10/28/2004, 10:00 AM


80 MapObjects Programmers Reference

End If
End Select
End With
End Sub

Sub GetEditMode()
Static Demonstrated As Integer
If Demonstrated < 2 Then
Select Case recset.EditMode
Case 0
Msg$ = No editing operation is in progress.
Button$ = vbInformation
Case 1
Msg$ = Edit in progress
Button$ = vbExclamation
Case 2
Msg$ = AddNew method has been invoked.
Button$ = vbExclamation
End Select
MsgBox Msg$, Button$, MapObjects
End If
Demonstrated = Demonstrated + 1
End Sub

Private Sub Form_Load()

For i = 1 To 2 Create two more instances of Command1.


Set the location of the new option button.
Command1(i).Top = Command1(i - 1).Top + Command1(0).Height + 40
Command1(i).Visible = True
Next i

Command1(0).Caption = Next
Command1(1).Caption = Previous
Command1(2).Caption = Change

Set recset = Map1.Layers(0).Records


For Each f In recset.Fields
Combo1.AddItem f.Name
Next f
Combo1.ListIndex = 0

count the number of records


ctr = 0
Do While Not recset.EOF
TotalRecs = TotalRecs + 1

ProgrammersReference.pmd 80 10/28/2004, 10:00 AM


MapObjects Programmers Reference 81

recset.MoveNext
Loop

recset.MoveFirst
Text1.Text = recset.Fields(Combo1.List(Combo1.ListIndex)).Value
Command1(1).Enabled = False
If Not recset.Updatable Then
Command1(2).Enabled = False
End If
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
Map1.FlashShape recset.Fields(Shape).Value, 3
End Sub

Candidate Property
Applies To Geocoder Object

Description Returns the information of a candidate address associated with the Geocoder object.

Syntax object.Candidate ( index) [= value]

The Candidate property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index A numeric expression that specifies the relative position of a member of the
group of Candidate values associated with the Geocoder object. Index
must be a number from 0 to a number that is one less than the value of the
Geocoder objects CandidateCount property.

value A string expression that specifies the information in a candidate.

Remarks The string returned from this property contains the following fields of information. Each field
is delimited by a vertical bar, |:

Score: The matching score in a range of 0 to 100; 100 indicates a highly confident or exact
match and 0 means the candidate is not a match.

Street side: The side of a centerline in relation to the reference StreetTable where the address
is successfully matched to. The values are L (left), R (right), and blank if it doesnt apply. This

ProgrammersReference.pmd 81 10/28/2004, 10:00 AM


82 MapObjects Programmers Reference

information is only available if the address is geocoded against a StreetTable containing left/
right house numbers.

Percentage along the line segment: This value indicates the location of the geocoded point
(the candidates address location) along a line in terms of percentage. By simple linear
interpolation, 50.0 indicates that the geocoded point is on the mid-point of the arc.

Although 0.0 and 100.0 represent the two end points of the arc, the geocoded point may not be
actually placed on the end point if the objects SqueezeFactor property is set with a value
other than 0.

MatchVariable fields: The values of the MatchVariable or IntersectionMatchVariable


fields associated with the StreetTable, e.g. the Street Name, Zip Code etc..

Record number of the StreetTable: This number indicates the record number of the candi-
date within the StreetTable.

See Also CandidateCount Property, GenerateCandidates Property

Example This example demonstrates how to review the candidates that a Geocoder finds using the
GenerateCandidates method, Candidate and CandidateCount properties. Then an address can
be geocoded against a selected candidate using and LocateCandidate method. To try this
example, paste the code into the Declarations section of a form that contains a Map named
Map1, two TextBoxes named Text1 and Text2, a CommandButton named Command1, two
Labels named Label1 and Label2, and two ListBoxes named List1 and List2. Substitute
appropriate values for the data paths and then press F5. Try different values in the
SpellingSensitivity property and see the different number of candidates returned.
Option Explicit

Dim geo As New MapObjects2.Geocoder


Dim stan As New MapObjects2.Standardizer

Set global variables with field names in the StreetTable


Modify if fields names in StreetTable are different
If a field is not available, set it with an empty string
Private Const m_FromLeft = L_f_add
Private Const m_FromRight = R_f_add
Private Const m_ToLeft = L_t_add
Private Const m_ToRight = R_t_add
Private Const m_PreDir = Prefix
Private Const m_PreType = Pre_type
Private Const m_StreetName = Name
Private Const m_StreetType = Type
Private Const m_SufDir = Suffix
Private Const m_LeftZone = Zipl

ProgrammersReference.pmd 82 10/28/2004, 10:00 AM


MapObjects Programmers Reference 83

Private Const m_RightZone = ZipR

Private Sub Command1_Click()

Locate an address to its best candidate


Dim foundLoc As MapObjects2.AddressLocation
Dim geoStatus, num, i As Integer
Dim msg As String

If stan.StandardizeAddress(Text1.Text) Then
stan.FieldValue(ZN) = Text2.Text
geoStatus = geo.GenerateCandidates

Select Case geoStatus


Case 0
msg = No candidates re found. Geocoding fails
Case 1
msg = Successful match. One best candidate scored _
& Left(geo.Candidate(0), 3) & is found.
Case 2
msg = Successful match. Multiple best candidates scored _
& Left(geo.Candidate(0), 3) & are found.
Case 3
msg = One or more candidates are found, but none of them _
have score equal or higher than the minimum match score _
& geo.MinimumMatchScore
End Select

Label1.Caption = msg

show all the candidates in List1 and list the individual


item of the first candidate in List2
each component in a candidate is delimited by an | symbol.
See the Geocoder.Canididate topic for description.
num = geo.CandidateCount
If num = 0 Then
List1.AddItem < No candidates >
Else
For i = 0 To num - 1
List1.AddItem geo.Candidate(i), i
Next i

Dim cand As String


Dim a, b As Integer
Dim s As New MapObjects2.Strings

ProgrammersReference.pmd 83 10/28/2004, 10:00 AM


84 MapObjects Programmers Reference

cand = geo.Candidate(0)
Label2.Caption = Here are the & num & candidates:
List2.AddItem Detail information of the first candidate:
List2.AddItem
s.Add Score
s.Add Side
s.Add Percent
If InStr(1, Text1.Text, &) = 0 Then
For i = 0 To geo.MatchVariableCount - 1
s.Add geo.MatchVariable(i)
Next i
Else
For i = 0 To 13 geo.IntersectionMatchVariableCount - 1
s.Add geo.IntersectionMatchVariable(i)
Next i
End If
s.Add Record no

a = 1
For i = 0 To s.count - 2
b = InStr(a, cand, |)
List2.AddItem s.Item(i) & vbTab & Mid(cand, a, b - a)
a = b + 1
Next i
List2.AddItem s.Item(s.count - 1) & vbTab & vbTab & _
Right(cand, Len(cand) - b)
End If

Locate to the best candidate


If geo.CandidateCount > 0 Then
Set foundLoc = geo.LocateCandidate(0)
Map1.FlashShape foundLoc.location, 3
End If

End If

End Sub

Private Sub Form_Load()

Dim dc As New MapObjects2.DataConnection


Dim gd As Object
Dim lyr As New MapLayer
Dim f, i As Integer
Dim name As String

ProgrammersReference.pmd 84 10/28/2004, 10:00 AM


MapObjects Programmers Reference 85

Set up Standardizer
Change the paths below to ones appropriate for your data
stan.StandardizingRules = C:\Program Files\ESRI\ _
MapObjects2\GeoRules\us_addr.stn
stan.IntersectionStandardizingRules = C:\Program Files\ESRI\ _
MapObjects2\GeoRules\us_intsc.stn
geo.Standardizer = stan

Change the paths below to ones appropriate for your data


dc.Database = C:\Program Files\ESRI\ _
MapObjects2\Samples\Data\Redlands
dc.Connect
If Not dc.Connected Then
MsgBox dc.connected error
End
End If

Set up the StreetTable


Set gd = dc.FindGeoDataset(Redlands)
Set lyr.GeoDataset = gd
lyr.Symbol.Color = moBlue
Map1.Layers.Add lyr
geo.StreetTable = gd

Set up the match rules and variables


Change the paths below to ones appropriate for your data
geo.MatchRules = C:\Program Files\ESRI\MapObjects2\ _
GeoRules\us_addr1.mat
geo.IntersectionMatchRules = C:\Program Files\ESRI\ _
MapObjects2\GeoRules\us_intsc1.mat

Link the Match Variables to fields in the StreetTable


geo.MatchVariableField(FromLeft) = m_FromLeft
geo.MatchVariableField(FromRight) = m_FromRight
geo.MatchVariableField(ToLeft) = m_ToLeft
geo.MatchVariableField(ToRight) = m_ToRight
geo.MatchVariableField(PreDir) = m_PreDir
geo.MatchVariableField(PreType) = m_PreType
geo.MatchVariableField(StreetName) = m_StreetName
geo.MatchVariableField(StreetType) = m_StreetType
geo.MatchVariableField(SufDir) = m_SufDir
geo.MatchVariableField(LeftZone) = m_LeftZone
geo.MatchVariableField(RightZone) = m_RightZone

Link the intersection group 1 variables

ProgrammersReference.pmd 85 10/28/2004, 10:00 AM


86 MapObjects Programmers Reference

geo.MatchVariableIntersectionLink(PreDir, mgLinkPrimary) _
= PreDir1
geo.MatchVariableIntersectionLink(PreType, mgLinkPrimary) _
= PreType1
geo.MatchVariableIntersectionLink(StreetName, mgLinkPrimary) _
= StreetName1
geo.MatchVariableIntersectionLink(StreetType, mgLinkPrimary) _
= StreetType1
geo.MatchVariableIntersectionLink(SufDir, mgLinkPrimary) _
= SufDir1
geo.MatchVariableIntersectionLink(LeftZone, mgLinkPrimary) _
= LeftZone1
geo.MatchVariableIntersectionLink(RightZone, mgLinkPrimary) _
= RightZone1

Link up intersection group 2 variables


geo.MatchVariableIntersectionLink(PreDir, mgLinkSecondary) _
= PreDir2
geo.MatchVariableIntersectionLink(PreType, mgLinkSecondary) _
= PreType2
geo.MatchVariableIntersectionLink(StreetName, mgLinkSecondary) _
= StreetName2
geo.MatchVariableIntersectionLink(StreetType, mgLinkSecondary) _
= StreetType2
geo.MatchVariableIntersectionLink(SufDir, mgLinkSecondary) _
= SufDir2
geo.MatchVariableIntersectionLink(LeftZone, mgLinkSecondary) _
= LeftZone2
geo.MatchVariableIntersectionLink(RightZone, mgLinkSecondary) _
= RightZone2

Build indices if havent


If Not geo.IndexStatus = MapObjects2.IndexStatusConstants. _
mgIndexExists Then
If Not geo.AddIndex(m_StreetName, , mgIndexTypeSoundex) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.AddIndex(m_LeftZone, m_RightZone._
mgIndexTypeNormal) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.BuildIndices(True) Then
MsgBox Cannot build geocoding index., vbCritical
End

ProgrammersReference.pmd 86 10/28/2004, 10:00 AM


MapObjects Programmers Reference 87

Else
MsgBox Indices are built.
End If
End If

Set search queries


Dim queries As New MapObjects2.Strings
queries.Add SN? & ZN
queries.Add SN?
Set geo.SearchQueries = queries

geo.SpellingSensitivity = 80

Command1.Caption = Locate Address


Text1.Text = 260 Cajon St
Text2.Text = 92373
Label1.Caption =
Label2.Caption =

End Sub

Private Sub Text1_Change()


List1.Clear
List2.Clear
End Sub

CandidateCount Property
Applies To Geocoder Object

Description Returns the number of the candidate addresses found associated with the Geocoder object.

Syntax object.CandidateCount [= value]

The CandidateCount property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A variable declared to be of the integer data type that specifies the number
of candidate addresses returned from the GenerateCandidates method.

See Also Candidate Property, GenerateCandidates Method

ProgrammersReference.pmd 87 10/28/2004, 10:00 AM


88 MapObjects Programmers Reference

Example See Candidate property

Ceiling Property
Applies To Rectangle Object

Description Returns or sets the top height coordinate of a Rectangle object.

Syntax object.Ceiling [= value]

The Ceiling property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression specifying a height coordinate.

See Also Floor Property, Depth Property

Example This example illustrates setting of the Ceiling and Floor properties of a rectangle, and return-
ing the Depth property to check the dimensions of the rectangle. To try this example, paste the
code into the Declarations section of a form containing a Map named Map1, and a
CommandButton named Command. Also add three TextBoxes named Text1, Text2 and Text3,
and three corresponding Labels named Label1, Label2 and Label3. Press F5, and try changing
the ceiling and floor properties of the rectangle by typing new values in the TextBoxes, and
then pressing the CommandButton. If the depth of the rectangle is below 0.5, the rectangle will
draw in red.
Option Explicit
Dim rectSym As New MapObjects2.Symbol
Dim drawRect As New MapObjects2.Rectangle

Private Sub Command1_Click()


drawRect.Ceiling = Text1.Text
drawRect.Floor = Text2.Text
changeDepth
End Sub

Private Sub changeDepth()


Text3.Text = drawRect.Depth
Map1.Refresh
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _

ProgrammersReference.pmd 88 10/28/2004, 10:00 AM


MapObjects Programmers Reference 89

Stdole.OLE_HANDLE)

If drawRect.Depth > 0.5 Then


rectSym.Color = moBlue
Else
rectSym.Color = moRed
End If
Map1.DrawShape drawRect, rectSym

End Sub

Private Sub Form_Load()

With drawRect
.Left = 0.3
.Right = 0.8
.Floor = 0
.Bottom = 0.3
.Top = 0.8
.Ceiling = 1
End With

With rectSym
.SymbolType = moFillSymbol
.Outline = True
.Size = 2
.Style = moGrayFill
End With

Label1.Caption = Ceiling
Text1.Text = drawRect.Ceiling
Label2.Caption = Floor
Text2.Text = drawRect.Floor
Label3.Caption = Depth
Text3.Text = drawRect.Depth
Text3.Enabled = False

Command1.Caption = Set Dimensions

End Sub

Center Property
Applies To Ellipse Object, Rectangle Object

ProgrammersReference.pmd 89 10/28/2004, 10:00 AM


90 MapObjects Programmers Reference

Description Returns the center point of an object as a Point object.

Syntax Set variable = object.Center

The Center property syntax has these parts:

Part Description

variable A variable that has been declared as a Point object.

object An object expression that evaluates to an object in the Applies To list.

See Also Point Object

Example This example uses the Center property to report the coordinates of the center of the maps
current extent. To try this example, paste the code into the Declarations section of a form
containing a Map named Map1 that contains at least one MapLayer. Press F5 and click-drag to
pan the map. Dismiss the Message Box and pan again.
Option Explicit

Private Sub Form_Load()


Dim oRect As MapObjects2.Rectangle
Set oRect = Map1.FullExtent
oRect.ScaleRectangle (0.5)
Map1.Extent = oRect
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Map1.Pan
With Map1.Extent.Center
MsgBox .x & , & .y
End With
End Sub

CenterAt Method
Applies To Map Object

Description Moves the center of the Map to the specified location.

Syntax object.CenterAt x, y

The CenterAt method syntax has the following parts:

ProgrammersReference.pmd 90 10/28/2004, 10:00 AM


MapObjects Programmers Reference 91

Part Description

object An object expression that evaluates to an object in the Applies To list.

x The horizontal coordinate to position at the center of the Map. (Data type is
Double.)

y The vertical coordinate to position at the center of the Map. (Data type is
Double.)

See Also Pan Method, Offset Method

Example This example uses the CenterAt method to pan the display to a specified location. To try this
example, paste the code into the Declarations section of a form that contains a Map named
Map1 that contains at least one MapLayer, and then press F5; click the Map. The display will
refresh and display the position you clicked at the center of the Map.
Option Explicit
Private Sub Form_Load()
Dim rect As MapObjects2.Rectangle
Set rect = Map1.Extent
rect.ScaleRectangle 0.5
Map1.Extent = rect
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim pt As New MapObjects2.Point
Map1.Visible = False
Set pt = Map1.ToMapPoint(X, Y)
Map1.CenterAt pt.X, pt.Y
Map1.Visible = True
Map1.Refresh
End Sub

CenterOnAscent Property
Applies To Symbol Object

Description Returns or sets whether MapObjects centers TrueType symbols by font ascent or by the actual
glyph bounds.

Syntax object.CenterOnAscent [= boolean]

The CenterOnAscent property syntax has these parts:

ProgrammersReference.pmd 91 10/28/2004, 10:00 AM


92 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

boolean A boolean expression specifying whether to center the object by font Ascent
or not as indicated in Settings.

Settings The settings for boolean are:

Setting Description

True Centers TrueType symbols by font Ascent .

False (Default) Centers TrueType symbols by actual glyph bounds.

See Also Font Object, Point Object, TextSymbol Object

Example This example uses the CenterOnAscent property to control how to align TrueType symbols,
either centered by font Ascent or by the actual glyph bounds. To try this example, paste the
code into the Declarations section of a form containing a CheckBox named Check1 and a Map
named Map1. Press F5, then click the Map. Toggle the CheckBox to see the effect of the
property.
Option Explicit
Dim pt As MapObjects2.Point

Private Sub Check1_Click()


Map1.TrackingLayer.Refresh True
End Sub

Private Sub Form_Load()


Check1.Caption = Center on Ascent
Check1.Value = 0
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
If Not pt Is Nothing Then
Dim sym As New MapObjects2.Symbol

With sym
.Style = moTrueTypeMarker
.SymbolType = moPointSymbol

If Check1.Value = 1 Then
.CenterOnAscent = True
ElseIf Check1.Value = 0 Then

ProgrammersReference.pmd 92 10/28/2004, 10:00 AM


MapObjects Programmers Reference 93

.CenterOnAscent = False
End If

.Font = ESRI Transportation & Municipal


.Size = 36
.Style = moTrueTypeMarker

.CharacterIndex = 45
.Color = moRed
Map1.DrawShape pt, sym

.CharacterIndex = 46
.Color = moBlue
Map1.DrawShape pt, sym
End With
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.Refresh True
End Sub

Centroid Property
Applies To Polygon Object

Description Returns the centroid of an object as a Point object.

Syntax Set variable = object.Centroid

The Centroid property syntax has these parts:

Part Description

variable A variable that has been declared as a Point.

object An object expression that evaluates to an object in the Applies To list.

Remarks The centroid represents the geometric center of a Polygon. For an irregular polygon, the
location of this Point will differ from the location of the Center of the Rectangle representing
the Extent of the Polygon.

See Also Extent Property

ProgrammersReference.pmd 93 10/28/2004, 10:00 AM


94 MapObjects Programmers Reference

Example See Area property

CharacterIndex Property
Applies To Symbol Object

Description Returns or sets the character code in the Font associated with a Symbol object. To return or
set a Symbol objects Font, use the Font property.

Syntax object.CharacterIndex [= index]

The CharacterIndex property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index A numeric expression that specifies the character code in the Symbols Font.

See Also Font Property

Example This example uses the CharacterIndex property to change the Symbol associated with a
GeoEvent on a TrackingLayer. As you click on the Map, the code increments the
CharacterIndex value associated with the Symbol. In this example, the CharacterIndex
property refers to the Wingdings character number. To try this example, paste the code into the
Declarations section of a form containing a Map named Map1 that contains at least one
MapLayer. Press F5 and click the Map repeatedly to see the different symbols.
Option Explicit

Private Sub Form_Load()


Dim fnt As New StdFont
fnt.Name = Wingdings TrueType font
Map1.TrackingLayer.SymbolCount = 1

With Map1.TrackingLayer.Symbol(0)
.Font = fnt
.Size = 18
.Style = moTrueTypeMarker
.Color = moBlack
End With
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)

ProgrammersReference.pmd 94 10/28/2004, 10:00 AM


MapObjects Programmers Reference 95

Static chridx
With Map1.TrackingLayer
If .EventCount > 0 Then .RemoveEvent 0
End With

If chridx = 0 Then chridx = 33

With Map1.Extent.Center
Dim pt As MapObjects2.Point
Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.AddEvent pt, 0
End With

Map1.TrackingLayer.Symbol(0).CharacterIndex = chridx

chridx = chridx + 1

End Sub

ChartRenderer Object
The ChartRenderer Objects properties and methods provide the ability to compare multiple
attributes of a feature by depicting the attributes as elements of either a pie chart or a bar chart.
In addition, you can compare one feature to another by the relative size of each features chart.

Use the ChartType property to set whether the chart is a pie chart or a bar chart. Use the
ShowOutline property to control the appearance of the chart outlines. Set the number of fields
represented in the chart with the FieldCount property, and for each attribute, set an indexed
Field property and an indexed Color property. To determine the dimensions of each bar chart,
use the BarHeight and BarWidth properties. To normalize bar charts, use the
NormalizationField property. To control the size of pie charts, use the SizeField,
MinPieSize, and MaxPieSize properties. You can set what value to consider as a null value
with the NullValue property and cancel the specified null value with the NoNullValue
method. A chart which contains data totaling zero will not be displayed.

A ChartRenderer is a creatable object in MapObjects. In Visual Basic, heres one way to


create a ChartRenderer :
Set Map1.Layers(0).Renderer = New MapObjects2.ChartRenderer
See Also ClassBreaksRenderer Object, DotDensityRenderer Object, EventRenderer Object,
LabelRenderer Object, ValueMapRenderer Object, ZRenderer Object,

Properties

BarHeight Field MinPieSize ShowOutline

ProgrammersReference.pmd 95 10/28/2004, 10:00 AM


96 MapObjects Programmers Reference

BarWidth FieldCount NormalizationField

ChartType MaxPieSize NullValue

Methods

NoNullValue

Example This example demonstrates how to use the properties and methods of a ChartRenderer object
to compare multiple attributes of the same feature and the relative magnitude of the features of
a MapLayer. To try this example, paste the code into the Declarations section of a Form that
contains a Map named Map1 with a MapLayer that references the USA Samples data states
shapefile, two OptionButton objects named Option1 and Option2, and a ListBox named List1.
Set the ListBox MultiSelect property to 2-Extended to allow for multiple selections and set the
ListBox Sorted property to True. Press F5; select one or more field names, and then choose a
chart type.
Option Explicit
Dim cr As New MapObjects2.ChartRenderer

Private Sub Form_Load()


Dim recset As New MapObjects2.Recordset
Dim fld As MapObjects2.Field
Option1.Caption = Pie Chart
Option2.Caption = Bar Chart

Set Map1.Layers.Item(states).Renderer = cr
Set recset = Map1.Layers.Item(states).Records
For Each fld In recset.Fields
If fld.Type > 0 And fld.Type < 8 Then
List1.AddItem fld.Name
End If
Next fld
End Sub

Private Sub Map1_BeforeLayerDraw(ByVal index As Integer, ByVal hDC _


As Stdole.OLE_HANDLE)

Dim i As Integer, ctr As Integer


If Option1.Value = True Or Option2.Value = True Then
Select Case cr.ChartType heights, widths, and sizes are
somewhat arbitrary
Case moBar
cr.BarHeight = Map1.Height * 0.01
cr.BarWidth = Map1.Width * 0.002
Case moPie

ProgrammersReference.pmd 96 10/28/2004, 10:00 AM


MapObjects Programmers Reference 97

cr.MinPieSize = Map1.Height * 0.005


cr.MaxPieSize = Map1.Height * 0.015
End Select
If List1.ListIndex > 0 Then
For i = 0 To List1.ListCount - 1
If List1.Selected(i) = True Then

ctr = ctr + 1
With cr
.FieldCount = ctr
.Field(ctr - 1) = List1.List(i)
.Color(ctr - 1) = QBColor(ctr + 1)
End With
End If
Next i
End If
End If
End Sub

Private Sub Option1_Click()


If Option1.Value = True Then
cr.ChartType = moPie
Map1.Refresh
End If
End Sub

Private Sub Option2_Click()


If Option2.Value = True Then
cr.ChartType = moBar
Map1.Refresh
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, _


x As Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

ProgrammersReference.pmd 97 10/28/2004, 10:00 AM


98 MapObjects Programmers Reference

ChartType Constants
MapObjects defines the following ChartType constants to describe the type of chart in a
ChartRenderer.

Constant Value Description

moPie 0 The ChartRenderer represents data values for each feature as a


pie chart.

moBar 1 The ChartRenderer represents data values for each feature as a


bar chart.

See Also ChartRenderer Object

ChartType Property
Applies To ChartRenderer Object

Description Returns or sets which type of charts are drawn by the ChartRenderer object.

Syntax object.ChartType [= value]

The ChartType property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A value or constant that determines the chart type as described in Settings.

Settings The settings for value are ChartTypeConstants.

See Also ChartTypeConstants

Example See ChartRenderer Object

ClassBreaksRenderer Object
A ClassBreaksRenderer is an object that represents a way of classifying features into
categories or classes, by drawing different symbols for features. The Symbol used to render
the feature depends upon the value contained in the specified Field. You can specify the

ProgrammersReference.pmd 98 10/28/2004, 10:00 AM


MapObjects Programmers Reference 99

number of categories (number of different Symbols you wish to use) in the BreakCount
property, and use the Break property to specify the values in Field which determine which
Symbol is used.

When setting the BreakCount property, remember that there is always one more category than
the number of breaks, so if you set BreakCount to be 2, there will be three categories. A
features Field value determines the category it falls into. The ClassBreaksRenderer assigns
a symbol to a feature using the indexed Symbol property. You can assign a specific Symbol to
each category. You can specify the type of Symbol to associate with the
ClassBreaksRenderer, depending on what kinds of features are associated with the
MapLayer, by setting the SymbolType property.

If you want, you can use the RampColors method to assign a start color to the first class and
an end color to the last class. The ClassBreaksRenderer will interpolate colors for interven-
ing classes. In a similar fashion, you can use the SizeSymbols method to create graduated
symbols by assigning an initial size in points to the Symbol associated with the first class and
a maximum size to the symbol associated with the last class. The ClassBreaksRenderer will
interpolate sizes for the intervening classes linearly.

A ClassBreaksRenderer is a creatable object in MapObjects. In Visual Basic, heres one way


to create a ClassBreaksRenderer:
Set Map1.Layers(0).Renderer = New MapObjects2.ClassBreaksRenderer
See Also Field Object, Recordset Object, Symbol Object

Properties

Break Field SymbolType

BreakCount Symbol Tag

Methods

RampColors SizeSymbols

Clear Method
Applies To Layers Collection, Strings Collection

Description Removes all members of a collection.

Syntax object.Clear

The Clear method syntax has the following object qualifier and part:

ProgrammersReference.pmd 99 10/28/2004, 10:00 AM


100 MapObjects Programmers Reference

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

See Also Remove Method

Example This example uses the Clear method to clear all layers from the map. To try this example,
paste the code into the Declarations section of a form containing a CommandButton named
Command1 and a Map named Map1 containing at least one MapLayer or ImageLayer and
then press F5 and click Command1.
Option Explicit
Private Sub Command1_Click()
Map1.Layers.Clear
End Sub

Click Event
Applies To Map Object

Description The Click event is a standard ActiveX control event, which occurs when the user presses and
then releases a mouse button over the map.

Syntax Private Sub object_Click()

The Click event syntax has one part:

Part Description

object An object expression that evaluates to a Map control.

Remarks For more information about the Click event, see the Visual Basic online reference.

See Also DblClick Event, MouseDown Event, MouseUp Event, MouseMove Event

ClearConnectError Method
Applies To DataConnection Object

Description Clears any ConnectError value from the DataConnection object

Syntax object.ClearConnectError

ProgrammersReference.pmd 100 10/28/2004, 10:00 AM


MapObjects Programmers Reference 101

The ClearConnectError method syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

Remarks You should use the ClearConnectError method after reporting the value of the
ConnectError property, to ensure that the most recent error status is always reported.

See Also GeoDataset Object

Example This example uses the ConnectError property to return messages about problems encountered
when connecting to an SDE database. If Connect returns False, the code returns a message
about the type of error. To try this example, paste the code into the Declarations section of a
form containing a Map named Map1. Substitute appropriate values for the DataConnection
objects properties. Press F5.
Option Explicit

Private Sub Form_Load()


Dim dc As New MapObjects2.DataConnection
Dim sMsg As String

With dc
.Server = silver
.User = paul
.Password = revere
.Database = Midnight

If .Connect Then
MsgBox Connected successfully, vbInformation, MapObjects
Else
Select Case .ConnectError
Case 1
SDEErr = Unknown error
Case 2
SDEErr = Access denied
Case 3
SDEErr = Invalid user
Case 4
SDEErr = Network timeout
Case 5
SDEErr = Dataset invalid
Case 6
SDEErr = Tasks exceeded
Case 7

ProgrammersReference.pmd 101 10/28/2004, 10:00 AM


102 MapObjects Programmers Reference

SDEErr = File not found


Case 8
SDEErr = Invalid directory
Case 9
SDEErr = Host unknown
Case Else
SDEErr = SDEErr(.ConnectError)
End Select

Dim result As Integer


Dim msg As String

Build message
msg = Connection Error: & sMsg & Chr(13)
If Not dc.ExtendedError = 0 Then
msg = msg & dc.ExtendedError & : & dc.ExtendedErrorString
End If
msg = msg & Chr(13) & Do you want to clear the last _
connect error?

get user response


result = MsgBox(msg, vbYesNo, Error: & .ConnectError _
, MapObjects2, 0)
If result = 6 Then yes
dc.ClearConnectError
End If

End If
End With
End Sub

For details of the SDEErr Function, see the CommitTransaction example

ClearEvents Method
Applies To TrackingLayer Object

Description Deletes all GeoEvent objects and their corresponding Symbols from the TrackingLayer.

Syntax object.ClearEvents

The ClearEvents method syntax has these parts:

ProgrammersReference.pmd 102 10/28/2004, 10:00 AM


MapObjects Programmers Reference 103

Part Description

object An object expression that evaluates to a TrackingLayer object.

Remarks To remove individual events from the TrackingLayer, use the RemoveEvent method. To
clear all Symbol objects, set SymbolCount to 0.

See Also GeoEvent Object Event, Symbol Object

Example This example uses the ClearEvents method to remove all GeoEvents from the TrackingLayer
at once. This code prompts the user when there are more than 5 GeoEvents to see if they want
to clear all events. To try this example, paste the code into the Declarations section of a form
containing a Map named Map1 that contains at least one MapLayer, and then press F5 and
click the map to add GeoEvents.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Dim pt As MapObjects2.Point
Dim Response As Variant

Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.AddEvent pt, 0

If Map1.TrackingLayer.EventCount > 5 Then


Response = MsgBox(There are now six GeoEvents on the _
TrackingLayer, OK to remove all?, vbYesNo)
If Response = vbYes Then User chose Yes.
Map1.TrackingLayer.ClearEvents
End If
End If
End Sub

CodePage Constants
MapObjects defines the following code page constants to describe the CodePage property of
a TableDesc object derived from a Recordset of a MapLayer.

Constant Value Description

moDefaultCodePage 0 Determines the TableDesc objects code page by


reading the associated dBASE file header.

ProgrammersReference.pmd 103 10/28/2004, 10:00 AM


104 MapObjects Programmers Reference

moOEMCodePage 1 Forces the characters in the associated dBASE


file to be treated as OEM characters.

moAnsiCodePage 2 Forces the characters in the associated dBASE


file to be treated as ANSI characters.

See Also TableDesc Object, CodePage Property

CodePage Property
Applies To TableDesc Object

Description Returns or sets the code page for a TableDesc object.

Syntax object.CodePage [= value]

The FieldCount property syntax has these parts:

Part Description

object An object expression that evaluates to a TableDesc.

value An integer or constant that indicates the code page, as described in Settings.

Settings The settings for value are CodePageConstants

Remarks The dBASE V specification has a byte in its header for a locale id (the 29th byte). If the byte
contains a value of 0x57, this indicates that all of the characters are stored in the ANSI code
page. MapObjects version 2.0 treats everything else as OEM. If the data is not correctly
marked with a code page specifier, you can override the behavior by setting the code page
value to one of the CodePage constants. To do this, access the TableDesc from a Recordset:
Map1.Layers(0).Records.TableDesc.CodePage = moAnsiCodePage
The code page will then be set for the duration of the project for all Recordset objects
subsequently derived from the specified MapLayer.

See Also Recordset Object

Color Constants
MapObjects defines the following color constants for use with Symbol objects.

ProgrammersReference.pmd 104 10/28/2004, 10:00 AM


MapObjects Programmers Reference 105

Constant Value Description

moBlack 0x0 Black

moRed 0xFF Red

moGreen 0xFF00 Green

moBlue 0xFF0000 Blue

moMagenta 0xFF00FF Magenta

moCyan 0xFFFF00 Cyan

moWhite 0xFFFFFF White

moLightGray 12632256 Light Gray

moDarkGray 4210752 Dark Gray

moGray 8421504 Gray

moPaleYellow 13697023 Pale Yellow

moLightYellow 8454143 Light Yellow

moYellow 65535 Yellow

moLimeGreen 12639424 Lime Green

moTeal 8421440 Teal

moDarkGreen 16384 Dark Green

moMaroon 128 Maroon

moPurple 8388736 Purple

moOrange 33023 Orange

moKhaki 7051175 Khaki

moOlive 32896 Olive

moBrown 4210816 Brown

moNavy 8404992 Navy

ProgrammersReference.pmd 105 10/28/2004, 10:00 AM


106 MapObjects Programmers Reference

See Also Symbol Object

Color Property
Applies To Symbol Object, TextSymbol Object, ChartRenderer Object

Description Returns or sets the color of an object.

See Also Symbol Object, TextSymbol Object, Map Object

Syntax object.Color [= color]

The Color property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

color A value or constant that determines the color of an object.

Settings The settings of the Color property are ColorConstants

Example This example uses the Color property to control the color of the symbol used to render a
MapLayer. To try this example, paste the code into the Declarations section of a form contain-
ing a CommonDialog control, a CommandButton named Command1 and a Map named Map1
that contains one MapLayer with polygon features. Press F5 and click Command1. The first
time you click the button, you can make a selection from the Color dialog and click OK.
Subsequent clicks on the button illustrate different ways to set Color in code.
Option Explicit

Private Sub Command1_Click()


Dim fRed As Double, fGreen As Double, fBlue As Double
Static lNumClicks As Long

With Map1.Layers(0).Symbol
Select Case lNumClicks
Case 0
CommonDialog1.ShowColor
.Color = CommonDialog1.Color
Case 1
fRed = 255 * Rnd
fGreen = 255 * Rnd
fBlue = 255 * Rnd
.Color = RGB(fRed, fGreen, fBlue) random

ProgrammersReference.pmd 106 10/28/2004, 10:00 AM


MapObjects Programmers Reference 107

Case 2
.Color = QBColor(10) light green
Case 3
.Color = vbActiveTitleBar
Case 4
.Color = moOrange
Case Else
MsgBox No more examples. Thanks anyway!, vbInformation
End Select
lNumClicks = lNumClicks + 1
End With
If lNumClicks < 6 Then Map1.Refresh
End Sub

CommitTransaction Method
Applies To Recordset Object

Description Causes all operations that have occurred since the StartTransaction request to be committed
to the server.

Syntax object.CommitTransaction

The CommitTransaction method syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object that has an open
transaction.

Remarks The CommitTransaction method is used at the end of a single edit, or series of edits, on an
open Recordset, i.e. one that has previously had the StartTransaction method called.

If the edits are not required the RollbackTransaction request can be used to save the
Recordset to the server as it was before the transaction began.

See Also GeoDataset Object, RollbackTransaction Method

Example This example demonstrates how you might connect to and perform a transaction on a dataset
stored in SDE. A useful function is included to return a string based on the LastError of a
DataConnection. To try this example, paste the code into the Declarations section of a new
Form which has three CommandButtons named Command1, COmmand2 and Command3, a
Map named Map1, and a ListBox named List1. Edit the properties of the DataConnection as
appropriate for your SDE instance, using the name of an SDE layer containing Line features in
the FindGeoDataset method. Then press F5, and click Connect. When connected to SDE,

ProgrammersReference.pmd 107 10/28/2004, 10:00 AM


108 MapObjects Programmers Reference

click Start transaction, and then track a line on the Map. Press End Transaction. To see the
results of the transaction, you can press the last CommandButton to remove and re-load the
same MapLayer.
Option Explicit
Dim dc As New MapObjects2.DataConnection
Dim lyr As New MapObjects2.MapLayer
Dim recs As New MapObjects2.Recordset
Dim reportCnt As Integer
Dim sym As New MapObjects2.Symbol

Private Sub Command1_Click()


CONNECT TO SDE AND LOAD LAYER
You should edit the Server, User, Password and Database strings
as appropriate
for your own SDE instance.
The FindGeoDataset method should also be editied - use the
name of a dataset
containing line features.
Screen.MousePointer = vbHourglass

dc.Server = drfinlay
dc.User = sde_user
dc.Password = sde_user
dc.Database = esri_sde

If Not dc.Connect Then End

Set lyr.GeoDataset = dc.FindGeoDataset(SDE_USER.TIREE.SHAPE.Lines)


Map1.Layers.Add lyr
Set recs = lyr.Records

Screen.MousePointer = vbDefault
End Sub

Private Sub Command2_Click()


START TRANSACTION
If recs.SupportsTransactions Then
recs.StartTransaction
End If
ReportOut
End Sub

Private Sub Command3_Click()


END TRANSACTION
Dim Result As Integer

ProgrammersReference.pmd 108 10/28/2004, 10:00 AM


MapObjects Programmers Reference 109

Screen.MousePointer = vbHourglass
Result = MsgBox(Do you want to Commit this Transaction? _
, vbYesNoCancel, Commit Transaction)

If Result = vbYes Then


recs.CommitTransaction
ReportOut
ElseIf Result = vbNo Then
recs.RollbackTransaction
ReportOut
ElseIf Result = vbCancel Then
ReportOut
Exit Sub
End If

Map1.Refresh
Command4.Enabled = True
Screen.MousePointer = vbDefault
End Sub

Private Sub Command4_Click()


REMOVE AND RE_LOAD LAYER
Map1.Layers.Remove (0)
Map1.TrackingLayer.ClearEvents
MsgBox MapLayer removed, vbInformation

Screen.MousePointer = vbHourglass

Command1_Click
Command4.Enabled = False
Screen.MousePointer = vbDefault
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
ADD FEATURES TO RECORDSET
On Error GoTo SDEErrors

Dim NewLine As MapObjects2.Line


Set NewLine = Map1.TrackLine
Screen.MousePointer = vbHourglass

Dim geo As MapObjects2.GeoEvent


Set geo = Map1.TrackingLayer.AddEvent(NewLine, 0)
Map1.TrackingLayer.Refresh False

ProgrammersReference.pmd 109 10/28/2004, 10:00 AM


110 MapObjects Programmers Reference

ReportOut

recs.AddNew
recs.Fields(Shape).Value = NewLine
ReportOut
recs.Update
ReportOut

Map1.Refresh
Screen.MousePointer = vbDefault
Exit Sub

SDEErrors:
MsgBox Error in Carrying out Editing on SDE: & vbNewLine _
& Connect Error: & dc.ConnectError & vbNewLine & ExtendedError _
: & dc.ExtendedError & vbNewLine & dc.ExtendedErrorString
ReportOut
Screen.MousePointer = vbDefault
End Sub

Private Sub Form_Load()


Command1.Caption = Connect
Command2.Caption = Start Transaction
Command3.Caption = End Transaction
Command4.Caption = Remove and Re-Add Layer to Map
Command4.Enabled = False
With Map1.TrackingLayer.Symbol(0)
.SymbolType = moLineSymbol
.Color = moYellow
.Size = 3
End With
End Sub

Private Sub ReportOut()


REPORT ON ERRORS/SDE STATUS
Dim EditModeString As String
Dim ConnStr As String

reportCnt = reportCnt + 1

If Not recs Is Nothing Then


EditModeString = [ & lyr.Name & ] & _
EditModeStr(recs.EditMode)
Else
EditModeString = No Edit Records set
End If

ProgrammersReference.pmd 110 10/28/2004, 10:00 AM


MapObjects Programmers Reference 111

ConnStr = ConnectErrorMsg(dc.ConnectError)
dc.ClearConnectError

List1.AddItem reportCnt & ) EditMode: & EditModeString & _


| & DC Error: & ConnStr
List1.ListIndex = List1.ListCount - 1
End Sub

Public Function EditModeStr(EditModeEnum As Integer) As String


SELECT STRING FOR ON CURRENT EDIT MODE
Select Case EditModeEnum
Case moEditNone: EditModeStr = EditModeEnum & : No Editing
Case moEditInProgress: EditModeStr = EditModeEnum & _
: Edit in progress
Case moEditAdd: EditModeStr = EditModeEnum & _
: Adding in progress
End Select
End Function

Public Function ConnectErrorMsg(errNum As Integer) As String


SELECT STRING FOR CURRENT SDE ERROR
For Details of this function, see the online help
End Function

Connect Method
Applies To DataConnection Object

Description Makes a connection to the Database specified in a DataConnection object.

Syntax Set variable = object.Connect

The Connect method syntax has these parts:

Part Description

variable A boolean expression that indicates whether a connection was made.

object An object expression that evaluates to a DataConnection object.

Remarks To successfully connect to a DataConnection object, you should ensure that the
DataConnections Database property specifies a source of a supported vector data. The
Connect method returns a Boolean value indicating whether or not MapObjects was able to
create the connection.

ProgrammersReference.pmd 111 10/28/2004, 10:00 AM


112 MapObjects Programmers Reference

You can also check the status of the DataConnection using the Connected property, after the
Connect method has been attempted, or to check the current status of a previously used
DataConnection object.

In order to establish a successful connection with an SDE database, the Server, User and
Password properties of the DataConnection object must be set with appropriate values for
the database.

The ConnectError property provides more information should the connection fail. If your
application is attempting to connect to SDE, the ExtendedError and ExtendedErrorString
properties will return any error messages from the database. A useful function is provided in
the Connection property example code, providing error string reporting for each of the SDE
errors supported by MapObjects as ConnectionErrorConstants.

See Also ConnectError Property, Connected Property

Example This example uses the Connect method to establish a connection to a folder containing
GeoDatasets. If Connect returns True, the code adds a MapLayer based on a GeoDataset to the
collection of MapLayers. In this case, Database is a path name to a directory. To try this
example, paste the code into the Declarations section of a form containing a Map named
Map1. Substitute an appropriate pathname for the DataConnection objects Database property
and specify the name of a valid GeoDataset as an argument to FindGeoDataset. Press F5.
Option Explicit

Private Sub Form_Load()

Dim lyr As New MapLayer


Dim dc As New MapObjects2.DataConnection

dc.Database = C:\Program Files\ESRI\MapObjects2\ _


Samples\Data\Redlands

If dc.Connect Then
Set lyr.GeoDataset = dc.FindGeoDataset(Redlands)
Map1.Layers.Add lyr
Else
MsgBox Connection failed
End If

End Sub

Connected Property
Applies To DataConnection Object

ProgrammersReference.pmd 112 10/28/2004, 10:00 AM


MapObjects Programmers Reference 113

Description Returns a value indicating whether the DataConnection object has a current valid connection.

Syntax object.Connected

The Connected property syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

Return Values The returned values for the Connected property are:

Setting Description

True A connection to a DataConnection has been made.

False A connection to a DataConnection has not been made.

See Also ConnectError Property

Example This example demonstrates the use of the Connected Property and the Disconnect method. To
try this example, paste the code into the Declarations section of a form containing a Map
control, a DriveList control named Drive1, a DirListBox control named Dir1, and two
CommandButton controls named Command1 and Command2. Press F5 and navigate through
the file system. Disconnect from the Database by clicking Command1. Check the status by
clicking Command2.
Option Explicit
Dim dc As New MapObjects2.DataConnection

Private Sub Command1_Click()


dc.Disconnect
Command1.Enabled = False
End Sub

Private Sub Command2_Click()


Dim sTitle As String

If dc.Connected Then
sTitle = DataConnection Status
MsgBox Connected, vbInformation, sTitle
Else
MsgBox Disconnected, vbExclamation, sTitle
End If

End Sub

ProgrammersReference.pmd 113 10/28/2004, 10:00 AM


114 MapObjects Programmers Reference

Private Sub dir1_Change()

dc.Database = Dir1.path
If dc.Connect Then
Command1.Enabled = True
End If

End Sub

Private Sub Drive1_Change()


Dir1.path = Drive1.Drive Set directory path.
End Sub

Private Sub Form_Load()


Command1.Enabled = False
Command1.Caption = Disconnect
Command2.Caption = Status
End Sub

ConnectError Property
Applies To DataConnection Object

Description Returns a value that specifies the type of error that caused an unsuccessful DataConnection
connection.

Syntax value = object.ConnectError

The ConnectError property syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

Return Values Return values from the ConnectError property are ConnectionErrorConstants.

Remarks If you have used the ConnectError property to report on the last DataConnection error, you
should then call the ClearConnectError method.

A useful function is provided in the Connection property example code, providing error string
reporting for each of the SDE errors supported by MapObjects as
ConnectionErrorConstants.

See Also Connection Property, Connected Property, Connect Method

ProgrammersReference.pmd 114 10/28/2004, 10:00 AM


MapObjects Programmers Reference 115

Example See ClearConnectError method

Connection Property
Applies To DataConnection Object

Description Returns the handle to a successful SDE Connection.

Syntax variable = object.Connection

The Connection property syntax has these parts:

Part Description

variable A variable that has been declared to be a long data type

object An object expression that evaluates to a DataConnection object.

Return Values If the object is a connection to a non-SDE data source, or there is no connection to the SDE
server made, the Connection property will be zero.

For more information on SDE handles and the SDE API, see your SDE documentation.

Remarks For an SDE database, the Connection property will return a handle to the database connec-
tion. The Connection property exposes the results of the SDE SE_connection_create function.
This connection can be used if your application needs to make direct calls to the SDE API. All
operations performed using this connection are executed as the user named in the User
property.

The connection will be valid as long as the DataConnection exists. You can create multiple
SDE connections, by repeating the Connect process on a new DataConnection object.

If appropriate, when the DataConnection object goes out of scope, the database connection
will be freed. If your application makes use of the database Connection, it is important that it
does not try to free the connection itself, the Disconnect method should always be used to
disconnect from an SDE server before the application ends.

See Also Connection Property, Connected Property, Connect Method

Example See the online help for example code

ProgrammersReference.pmd 115 10/28/2004, 10:00 AM


116 MapObjects Programmers Reference

ConnectionError Constants
MapObjects defines the following Error code constants for DataConnection connections.

Constant Value Description

moNoError 0 No Error

moUnknownError 1 Unknown Error

moAccessDenied 2 Access Denied

moInvalidUser 3 Invalid User

moNetworkTimeout 4 Network Timeout

moInvalidDatabase 5 Invalid Database

moTasksExceeded 6 Tasks Exceeded

moFileNotFound 7 File Not Found

moInvalidDirectory 8 Invalid Directory

moHostUnknown 9 Host Unknown

moSE_FAILURE -1 Failed to connect to SDE

moSE_INVALID_LAYERINFO_OBJECT -2 LAYERINFO pointer not


initialized

moSE_NO_ANNOTATION -3 The given shape has no


annotation

moSE_FINISHED -4 Stream loading of shapes has


finished

moSE_SDE_NOT_STARTED -5 SDE is not started, cannot


perform function

moSE_UNCHANGED -6 Specified shape was left


unchanged

moSE_CONNECTIONS_EXCEEDED -7 Number of tasks on the server


is at a maximum

ProgrammersReference.pmd 116 10/28/2004, 10:00 AM


MapObjects Programmers Reference 117

moSE_LOGIN_NOT_ALLOWED -8 Number of connections to the


server is at a maximum

moSE_INVALID_USER -9 Specified user and password


cannot be validated

moSE_NET_FAILURE -10 Network I/O operation failed

moSE_NET_TIMEOUT -11 Network I/O timeout

moSE_OUT_OF_SVMEM -12 Server task cannot allocate the


memory it requires

moSE_OUT_OF_CLMEM -13 Client task cannot allocate the


memory it requires

moSE_OUT_OF_CONTEXT -14 The function call is out of


context

moSE_NO_ACCESS -15 No access to object

moSE_TOO_MANY_LAYERS -16 Exceeded max_layers in


giomgr.defs

moSE_NO_LAYER_SPECIFIED -17 Layer specification missing

moSE_LAYER_LOCKED -18 Specified layer is locked

moSE_LAYER_EXISTS -19 Specified layer already exists

moSE_LAYER_NOEXIST -20 Specified layer does not exist

moSE_LAYER_INUSE -21 Specifies layer is in use

moSE_FID_NOEXIST -22 Specified shape (LAYER:FID)


does not exist

moSE_FID_EXISTS -23 Specified shape (LAYER:FID)


exists

moSE_LAYER_MISMATCH -24 Both layers must be the same

moSE_NO_PERMISSIONS -25 No permission to perform the


operation

moSE_INVALID_NOT_NULL -26 Column has a Not Null


constraint

ProgrammersReference.pmd 117 10/28/2004, 10:00 AM


118 MapObjects Programmers Reference

moSE_INVALID_SHAPE -27 Invalid shape, cannot be


verified

moSE_INVALID_LAYER_NUMBER -28 MapLayer number is out of


range

moSE_INVALID_ENTITY_TYPE -29 Invalid entity type

moSE_INVALID_SEARCH_METHOD -30 Invalid search method

moSE_INVALID_ETYPE_MASK -31 Invalid entity type mask

moSE_BIND_CONFLICT -32 Bind/set/get/ mismatch

moSE_INVALID_GRIDSIZE -33 Invalid grid size

moSE_INVALID_LOCK_MODE -34 Invalid lock mode

moSE_ETYPE_NOT_ALLOWED -35 Enityt type of shape is not


allowed in the layer

moSE_TOO_MANY_POINTS -36 Exceeded the max points


specified.

moSE_TABLE_NOEXIST -37 The DMBS table does not exist

moSE_ATTR_NOEXIST -38 Specified attribute column


does not exist

moSE_LICENSE_FAILURE -39 Underlying license manager


problem.

moSE_OUT_OF_LICENSES -40 No more SDE licenses


available.

moSE_INVALID_COLUMN_VALUE -41 Value exceeds valid range

moSE_INVALID_WHERE -42 User-specified where clause


is invalid

moSE_INVALID_SQL -42 User-specified SQL clause is


invalid

moSE_LOG_NOEXIST -43 Specified log file does not


existT

ProgrammersReference.pmd 118 10/28/2004, 10:00 AM


MapObjects Programmers Reference 119

moSE_LOG_NOACCESS -44 Unable to access the specified


logfile

moSE_LOG_NOTOPEN -45 Specified logfile is unavailable


for I/O

moSE_LOG_IO_ERROR -46 I/O error using the logfile

moSE_NO_SHAPES -47 No shapes selected or used in


the operation

moSE_NO_LOCKS -48 No locks defined

moSE_LOCK_CONFLICT -49 Lock request conflicts with


another lock request

moSE_OUT_OF_LOCKS -50 Maximum number of locks


allowed by the system are in
use

moSE_DB_IO_ERROR -51 Database-level I/O error


occurred

moSE_STREAM_IN_PROGRESS -52 Shape/FID stream not finished

moSE_INVALID_COLUMN_TYPE -53 Invalid column data type

moSE_TOPO_ERROR -54 Topological integrity error

moSE_ATTR_CONV_ERROR -55 Attribute conversion error

moSE_INVALID_COLUMN_DEF -56 Invalid column definition

moSE_INVALID_SHAPE_BUF_SIZE -57 Invalid shape array buffer size

moSE_INVALID_ENVELOPE -58 Envelope is Null, has negative


values, or Min > Max

moSE_TEMP_IO_ERROR -59 Temp file I/O error, cant open


temp file, or ran out of disk
space

moSE_GSIZE_TOO_SMALL -60 Spatial index grid size is too


small

moSE_LICENSE_EXPIRED -61 SDE run-time license has


expired, cannot login

ProgrammersReference.pmd 119 10/28/2004, 10:00 AM


120 MapObjects Programmers Reference

moSE_TABLE_EXISTS -62 DBMS table exists

moSE_INDEX_EXISTS -63 Index with the specified name


already exists

moSE_INDEX_NOEXIST -64 Index with the specified name


does not exist

moSE_INVALID_POINTER -65 Specified pointer value is null


or invalid

moSE_INVALID_PARAM_VALUE -66 Specified parameter value is


invlaid

moSE_ALL_SLIVERS -67 Sliver factor caused alll results


to be slivers

moSE_TRANS_IN_PROGRESS -68 User-specifie transaction is in


progress

moSE_IOMGR_NO_DBMS_CONNECT -69 I/O manager has lost its


connection to the underlying
DBMS

moSE_DUPLICATE_ARC -70 ARC (startpt,midpt,endpt)


already exists

moSE_INVALID_ANNO_OBJECT -71 SE_ANNO pointer not


initialized.

moSE_PT_NO_EXIST -72 Specified point does not exist


in the feature

moSE_PTS_NOT_ADJACENT -73 Specified points must be


adjacent

moSE_INVALID_MID_PT -74 Specified midpoint is invalid

moSE_INVALID_END_PT -75 Specified endpoint is invalid

moSE_INVALID_RADIUS -76 Specified radius is invalid

moSE_LOAD_ONLY_LAYER -77 MapLayer has LoadOnly


mode, operation is not allowed

moSE_LAYERS_NOT_FOUND -78 Layer table does not exist

ProgrammersReference.pmd 120 10/28/2004, 10:00 AM


MapObjects Programmers Reference 121

moSE_FILE_IO_ERROR -79 Error writing or creating an


output text file

moSE_BLOB_SIZE_TOO_LARGE -80 Maximum blob size exceeded

moSE_CORRIDOR_OUT_OF_BOUNDS -81 Resulting corridor exceeds the


valid coordinate range

moSE_SHAPE_INTEGRITY_ERROR -82 Model integrity error

moSE_NOT_IMPLEMENTED_YET -83 Function or option is not yet


implememted

moSE_CAD_EXISTS -84 This shape has a CAD

moSE_INVALID_TRANSID -85 Invalid internal SDE transac-


tion ID

moSE_INVALID_LAYER_NAME -86 MapLayer name must not be


empty

moSE_INVALID_LAYER_KEYWORD -87 Invalid Layer configuration


keyword used

moSE_INVALID_RELEASE -88 Invalid release/version of SDE


server

moSE_VERSION_TBL_EXISTS -89 Version table exists

moSE_COLUMN_NOT_BOUND -90 Column has not been bound

moSE_INVALID_INDICATOR_VALUE -91 Indicator variable contains an


invalid value

moSE_INVALID_CONNECTION -92 The connection handle is


NULL, connection is closed, or
the wrong object has been used

moSE_INVALID_DBA_PASSWORD -93 The DBA password is incorrect

moSE_PATH_NOT_FOUND -94 Coord path not found the shape


edit operation

moSE_SDEHOME_NOT_SET -95 No $SDEHOME variable has


been set

moSE_NOT_TABLE_OWNER -96 User must be the table owner

ProgrammersReference.pmd 121 10/28/2004, 10:00 AM


122 MapObjects Programmers Reference

moSE_PROCESS_NOT_FOUND -97 The process ID specified does


not correspond on an SDE
server

moSE_INVALID_DBMS_LOGIN -98 DBMS did not accept user/


password

moSE_PASSWORD_TIMEOUT -99 Password received was sent


more than MAXTIMEDIFF
second before

moSE_INVALID_SERVER -100 Server machine was not found

moSE_IOMGR_NOT_AVAILABLE -101 IO Manager task not started on


server

moSE_SERVICE_NOT_FOUND -102 No SDE entry in /etc/services


file

moSE_INVALID_STATS_TYPE -103 Tried statistics on a non-


numeric value

moSE_INVALID_DISTINCT_TYPE -104 Distinct stats on invalid type

moSE_INVALID_GRANT_REVOKE -105 Invalid use of grant/revoke


function

moSE_INVALID_SDEHOME -106 The supplied SDEHOME path


is invalid or NULL

moSE_INVALID_STREAM -107 Stream does not exist

moSE_TOO_MANY_STREAMS -108 Max number of streams


exceeded

moSE_OUT_OF_MUTEXES -109 Exceeded systems maximum


number of mutexs

moSE_CONNECTION_LOCKED -110 This connection is locked to a


different thread

moSE_CONNECTION_IN_USE -111 This connection is being used


at the moment by a different
thread

moSE_NOT_A_SELECT_STATEMENT -112 The SQL statement was not a


select

ProgrammersReference.pmd 122 10/28/2004, 10:00 AM


MapObjects Programmers Reference 123

moSE_FUNCTION_SEQUENCE_ERROR -113 Function called out of se-


quence

moSE_WRONG_COLUMN_TYPE -114 Get request on wrong column


type

moSE_PTABLE_LOCKED -115 This pTable is locked to a


different thread

moSE_PTABLE_IN_USE -116 This pTable is being used at


the moment by a different
thread

moSE_STABLE_LOCKED -117 This sTable is locked to a


different thread

moSE_STABLE_IN_USE -118 This sTable is being used at the


moment by a different thread

moSE_INVALID_FILTER_TYPE -119 Unrecognized spatial filter type

moSE_NO_CAD -120 The given shape has no CAD

moSE_INSTANCE_NOT_AVAILABLE -121 No instance running on server

moSE_INSTANCE_TOO_EARLY -122 Instance is a version previous


to 2.0

moSE_INVALID_SYSTEM_UNITS -123 System units smaller than 1 or


greater than 21474836467

moSE_INVALID_UNITS -124 Feet, meters, decimal degrees


or other

moSE_INVALID_CAD_OBJECT -125 SE_CAD pointer not initialized

moSE_INVALID_NUM_OF_PTS -126 No longer issued

moSE_INVALID_SPATIAL_CONSTRAINT -127 Spatial filters invalid for search

moSE_INVALID_STREAM_TYPE -128 Invalid operation for the given


stream

moSE_INVALID_SPATIAL_COLUMN -129 Column contains NOT NULL


values during
SE_Layer_create()

ProgrammersReference.pmd 123 10/28/2004, 10:00 AM


124 MapObjects Programmers Reference

moSE_NO_SPATIAL_MASKS -130 No spatial masks available

moSE_IOMGR_NOT_FOUND -131 IO manager program not found

moSE_SYSTEM_IS_CLIENT_ONLY -132 Operation cannot run on this


system, server required

moSE_MULTIPLE_SPATIAL_COLS -133 Only one spatial column


allowed

moSE_INVALID_SHAPE_OBJECT -134 The given shape object handle


is invalid

moSE_INVALID_PARTNUM -135 Specified shape part number


does not exist

moSE_INCOMPATIBLE_SHAPES -136 Given shapes are of incompat-


ible types

moSE_INVALID_PART_OFFSET -137 Specifies part offset is invalid

moSE_INCOMPATIBLE_COORDREFS -138 Given coordinate references


are incompatible

moSE_COORD_OUT_OF_BOUNDS -139 Specified coordinate exceeds


the valid coordinate range

moSE_LAYER_CACHE_FULL -140 Max layers exceeded in cache

moSE_INVALID_COORDREF_OBJECT -141 Given coordinate reference


object handle is invalid

moSE_INVALID_COORDSYS_ID -142 Coordinate system identifier is


invalid

moSE_INVALID_COORDSYS_DESC -143 Coordinate system description


is invalid

moSE_INVALID_ROW_ID_LAYER -144 SE_ROW_ID owner.table does


not match the layer

moSE_PROJECTION_ERROR -145 Error projecting shape points

moSE_ARRAY_BYTES_EXCEEDED -146 Max array bytes exceeded

moSE_POLY_SHELLS_OVERLAP -147 2 donuts or 2 outer shells


overlap

ProgrammersReference.pmd 124 10/28/2004, 10:00 AM


MapObjects Programmers Reference 125

moSE_TOO_FEW_POINTS -148 Number of points is less than


required for feature

moSE_INVALID_PART_SEPARATOR -149 Part seperator in the wrong


position

moSE_INVALID_POLYGON_CLOSURE -150 Polygon does not close


correctly

moSE_INVALID_OUTER_SHELL -151 A polygon outer shell does not


completely enclose all donuts
for the part

moSE_ZERO_AREA_POLYGON -152 Polygon shell has no area

moSE_POLYGON_HAS_VERTICAL_LINE -153 Polygon shell contains a


vertical line

moSE_OUTER_SHELLS_OVERLAP -154 Multipart area has overlapping


parts

moSE_SELF_INTERSECTING -155 Linestring or polygon bound-


ary is self-intersecting

moSE_INVALID_EXPORT_FILE -156 Export file is invalid

moSE_READ_ONLY_SHAPE -157 Attempted to modify or free a


read-only shape from an sTable

moSE_INVALID_DATA_SOURCE -158 Invalid data source

moSE_INVALID_STREAM_SPEC -159 Stream spec parameter exceeds


giomgr default

moSE_INVALID_ALTER_OPERATION -160 Tried to remove cad or anno

moSE_INVALID_SPATIAL_COL_NAME -161 Spatial column same as table


name

moSE_INVALID_DATABASE -162 Invalid database name

moSE_SPATIAL_SQL_NOT_INSTALLED -163 Spatial SQL extension not


present in underlying DBMS

moSE_NORM_DIM_INFO_NOT_FOUND -164 Dimension parameters for


SDO DIM table is not found in
the dbTune file

ProgrammersReference.pmd 125 10/28/2004, 10:00 AM


126 MapObjects Programmers Reference

moSE_NORM_DIM_TAB_VALUE_NOT_FOUND-165 Dimension parameters in the


SDO DIM table is corrupted or
missing

moSE_UNSUPPORTED_NORMALIZED_OPERATION -166 Current operation is


not supported for
Normalized layers

moSE_INVALID_REGISTERED_LAYER_OPTION -167 Invalid operation:


Registered layers do
not allow this opera-
tion

moSE_READ_ONLY -168 User has read only access to


SE_ROW_ID

moSE_SDE_WARNING -1000 Base number for warning


codes

moSE_ETYPE_CHANGED -1001 Function changed entity type


of feature

moSE_AUTOCOMMITTED -1002 This store/replace triggered an


autocommit

moSE_TOO_MANY_DISTINCTS -1003 Too many distinct values in


stats

moSE_NULL_VALUE -1004 Request column value is


NULL

moSE_NO_ROWS_UPDATED -1005 No rows were updated

moSE_NO_CPGCVT -1006 No codepage conversion

moSE_NO_CPGHOME -1007 Cannot find codepage directory

moSE_DBMS_DOES_NOT_SUPPORT -1008 DBMS does not support this


function

moSE_NO_TRIGGERS_CREATED -1009 DBMS does not support


multiple triggers. Do not create
over existing business table
trigger

See Also DataConnection Object

ProgrammersReference.pmd 126 10/28/2004, 10:00 AM


MapObjects Programmers Reference 127

CoordinateSystem Property
Applies To MapLayer Object, Map Object

Description Returns or sets the coordinate system for a Map or a MapLayer object.

Syntax object.CoordinateSystem [= coordSys ]

The CoordinateSystem property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

coordSys A coordinate system object (either a GeoCoordSys or a ProjCoordSys).

Remarks The coordinate system referenced by coordsys may be of type GeoCoordSys or


ProjCoordSys. If the type is previously unknown, the coordsys may be declared as a variant
data type, and the IsProjected property can then be checked.

See Also GeoCoordSys Object, ProjCoordSys Object

Example This example uses the CoordinateSystem property to hide each MapLayer which does not
have a coordinate system set. To try this example, paste the code into the Declarations section
of a form containing a Map named Map1 that has more then one MapLayer (some of which
should have corresponding .prj files), and a ListBox called List1. Press F5 to run the example.
Option Explicit

Private Sub Form_Load()


Dim curLayer As MapObjects2.MapLayer

For Each curLayer In Map1.Layers


If Not curLayer.CoordinateSystem Is Nothing Then
List1.AddItem curLayer.name & : & _
curLayer.CoordinateSystem.name
Map1.Layers(curLayer.name).Visible = True
Else
List1.AddItem curLayer.name & : Coordinate System not set
Map1.Layers(curLayer.name).Visible = False
End If
Next curLayer

Now set the maps coordinate system to be the same as that


of the first layer in the map controls layer collection

ProgrammersReference.pmd 127 10/28/2004, 10:00 AM


128 MapObjects Programmers Reference

If Map1.CoordinateSystem Is Nothing Then


If Map1.Layers(0).CoordinateSystem.IsProjected Then
Dim mapPCS As New MapObjects2.ProjCoordSys
mapPCS.Type = Map1.Layers(0).CoordinateSystem.Type
Map1.CoordinateSystem = mapPCS
ElseIf Not Map1.Layers(0).CoordinateSystem.IsProjected Then
Dim mapGCS As New MapObjects2.GeoCoordSys
mapGCS.Type = Map1.Layers(0).CoordinateSystem.Type
Map1.CoordinateSystem = mapGCS
End If
End If
List1.AddItem Map Control: & Map1.CoordinateSystem.name
End Sub

CopyMap Method
Applies To Map Object

Description Copies the visible extent of the Map to the Clipboard in enhanced and standard metafile
format.

Syntax object.CopyMap scaleFactor

The CopyMap method syntax has the following parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

scaleFactor A value that determines the output resolution. An output resolution of 1


represents the same number of pixels in the bitmap image of the Map as on
the screen; an output resolution of 10 is ten times the original number of
pixels in the image, both in the horizontal and the vertical direction.

Remarks CopyMap does not support VisibleRegion or Transparent properties. If RotationAngle is


not zero, any ImageLayers in the Map controls Layers collection will not be visible. If any
ImageLayers in the Map controls Layers collection have their Transparent property set to
True, then these too will not be visible.

See Also OutputMap Method, ExportMap Method, PrintMap Method

Example This example uses the CopyMap method to copy the visible extent of a Map to the Clipboard
in enhanced and standard metafile format. To try this example, paste the code into the Declara-
tions section of a form that contains a CommandButton named Command1 and a Map named

ProgrammersReference.pmd 128 10/28/2004, 10:00 AM


MapObjects Programmers Reference 129

Map1 that contains at least one MapLayer, and then press F5; click Command1 and then paste
the contents of the Clipboard into another application.
Option Explicit
Private Sub Command1_Click()
Map1.CopyMap 1
End Sub

Count Property
Applies To Fields Collection, GeoDatasets Collection, GroupRenderer Object, Layers Collection,
Parts Collection, Points Object, Strings Object, Recordset Object, Statistics Object

Description Returns the number of objects in a collection. For Recordset objects, if the number of records
is unknown, the property returns -1.

Syntax object.Count [= total]

The Count method syntax has the following parts:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

total An integer data type variable, indicating the number of objects in a collec-
tion.

Remarks You can use this property with a For...Next statement to carry out an operation on the mem-
bers of a collection. For example, the following code adds the names of all layers in a map to
a list:
For I = 0 To Form1.Map1.Layers.Count - 1
List1.Additem Form1.Map1.Layers(I).Name
Next I
The Count property may return a value of -1 when the object is a Recordset derived from
sources which do not contain header information such as:

an SDE layer

a Table object

a SearchExpression

ProgrammersReference.pmd 129 10/28/2004, 10:00 AM


130 MapObjects Programmers Reference

In these cases, to obtain the correct Count of the Recordset, a Statistics object should be
created from the Recordset, and the number of records taken from the Count property of this
Statistics object.

See Also Item Property, Add Method

Example This example uses the Count property to report on how many layers constitute the Map, and
the number of events in the tracking layer. To try this example, paste the code into the Declara-
tions section of a form containing a Label named Label1 and a Map named Map1 that contains
at least one MapLayer, and some GeoEvents. Press F5
Private Sub Form_Load()
Label1.Caption = Map1.Layers.Count & layers in the map, and _
& Map1.TrackingLayer.EventCount & events in the tracking layer
End Sub

Custom Property
Applies To Symbol Object, Projection Object

Description Returns or sets a reference to a custom Symbol or customized Projection object.

Syntax object.Custom [= customObj ]

The Custom property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

customObj An object declared as a user -defined Symbol or Projection.

Remarks The Custom property is used to set a reference to a user-defined custom Symbol or Projec-
tion object, for example:
Dim myMarker as New MySymbols.MarkerSymbol
myLayer.Symbol.Custom = myMarker
Custom Symbols and Projections are created by using the ICustom Interface. For example, in
Visual Basic you can create your own DLL using the ICustom interface by adding a reference
to the AFCust2.0.tlb Type Library.

You can also create a custom renderer object, allowing the developer to render a MapLayer
to exact specifications.

See Also IsCustom Property

ProgrammersReference.pmd 130 10/28/2004, 10:00 AM


MapObjects Programmers Reference 131

Database Property
Applies To DataConnection Object, Table Object

Description Returns or sets the Database name for an SDE connection, an ODBC connection, a Microsoft
Jet database engindatabase, an installable ISAM database, an INFO database, or an ARC/
INFO or PC ARC/INFO workspace. In addition, you can use the pathname to a directory
containing ESRI shapefiles(SHP files), creating an ODBC DataConnection automatically.

Syntax object.Database [=dbName]

The Database property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

dbName A string expression that evaluates to an SDE or an ODBC Database name,


Microsoft Jet database engine database, an installable ISAM database, an
INFO database, an ARC/INFO or PC ARC/INFO workspace, or a pathname
to a directory containing ESRI shapefiles (SHP files).

Remarks The Database property should not be used on a Table object to connect to a table in SDE.
When connecting to SDE you should use the Database, Server, User and Password proper-
ties of the DataConnection object.

For certain vector data sources, a suffix should be specified before the dbName expression.

See Also User Property

Example See Connect method

DataConnection Object
A DataConnection represents a connection to a source of geographic data. Sources that
MapObjects can connect to are: folders containing Shapefiles or CAD files, SDE database
instances, ARC/INFO workspaces and VPF data sources. A DataConnection can return a
GeoDatasets collection. Each member of the collection, referred to as a GeoDataset, repre-
sents a discrete set of geographic data that can be retrieved from the data source. You can use
the FindGeoDataset method to return a specific GeoDataset by name. You can delete a
GeoDataset from a DataConnection object using DeleteGeoDataset, and you can make use
of the geographic data in a GeoDataset by assigning it to the GeoDatset property of a new
MapLayer object. You can also find CoordinateSystem information about your

ProgrammersReference.pmd 131 10/28/2004, 10:00 AM


132 MapObjects Programmers Reference

GeoDatasets by using the methods FindArcInfoCoordinateSystem and


FindCoordinateSystem.

The Connect method of the DataConnection object will attempt to connect to the data source
specified in the Database property. This method will return True if the connection was
successful. You can later verify a connections status by using the Connected property. For an
SDE database, the Connection property will return a handle to the database connection. This
connection can be used if your application needs to make direct calls to the SDE API.

The DataConnection object also allows error catching. The ConnectError property will
return the last error raised while trying to Connect to a database. The ExtendedError and
ExtendedErrorString properties will return a value and description of the last error raised by
the database while trying to access an SDE layer.

See Also GeoDataset Object, TableDesc Object, MapLayer Object

Properties

Connected Database GeoDatasets User

ConnectError ExtendedError Passwords

Connection ExtendedErrorString Server

Methods

AddGeoDataset DeleteGeoDataset FindCoordinateSystem

ClearConnectError Disconnect FindGeoDataset

Connect FindArcInfoCoordinateSystem

Datum Constants
MapObjects defines over 200 constants for use with the Type property of a Datum object. See
the online help for details.

The default Datum is moDatum_AuthalicSphere, value 6035.

See Also Datum Object, Type Property

ProgrammersReference.pmd 132 10/28/2004, 10:00 AM


MapObjects Programmers Reference 133

Datum Object
The Datum object is used to define the datum upon which a geographical coordinate system is
based.

A Datum objects properties can be specified by using a pre-defined datum, by setting the
Type property to equal one of over 200 DatumConstants. Alternatively, a user-defined
Datum can be specified by reference to a Spheroid object.

See Also Datum Constants, GeoCoordSys Object, PrimeMeridian Object, Spheroid Object, Unit
Object

Properties

Name Spheroid Type

Datum Property
Applies To GeoCoordSys Object

Description Sets or returns a value that identifies the datum upon which a GeoCoordSys object is based.

Syntax object. Datum [= datum ]

The GeoCoordSys property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

datum An object expression that evaluates to a Datum object

See Also Datum Object

Example This example uses the Datum property to check MapLayers with geographic coordinate
systems. MapLayers which are not projected, or have the same datum as that chosen by the
user in the ComboBox, remain visible. MapLayers having a geographic coordinate system
with the same datum as that chosen in the ComboBox are made invisible. To try this example,
paste the code into the Declarations section of a form containing a Map named Map1 that
contains at least one MapLayer, and a ComboBox named Combo1. MapLayers should have
their CoordinateSystem property set. Press F5, and choose a datum from the ComboBox.
Option Explicit

ProgrammersReference.pmd 133 10/28/2004, 10:00 AM


134 MapObjects Programmers Reference

Private Sub Combo1_Click()

Dim datype As Integer


datype = stripProjection(Combo1.List(Combo1.ListIndex))
Dim curLayer As MapObjects2.MapLayer
For Each curLayer In Map1.Layers
If Not curLayer.CoordinateSystem.IsProjected Then
If curLayer.CoordinateSystem.Datum.Type = datype Then
curLayer.Visible = True
Else
curLayer.Visible = False
End If
End If
Next curLayer

Map1.Refresh
End Sub

Private Function stripProjection(theProjection As String) As Integer


Strip the projection object type number from the selected string
Dim openB As Integer
openB = InStr(theProjection, [)
stripProjection = Int(Left(Right(theProjection, Len(theProjection) _
- openB), Len(theProjection) - openB - 1))
End Function

Private Sub Form_Load()

Dim datums As New MapObjects2.Strings


Dim theDat As Variant

datums.PopulateWithDatums
For Each theDat In datums
Combo1.AddItem theDat
Next theDat

This code can be used to apply two GeoCoordSys objects, having


two different datums, to two MapLayers.
You may wish to use your own projection objects which are
appropriate for your datasets.

Dim gcs1 As New MapObjects2.GeoCoordSys
Dim gcs2 As New MapObjects2.GeoCoordSys
Dim dat1 As New MapObjects2.Datum
Dim dat2 As New MapObjects2.Datum

ProgrammersReference.pmd 134 10/28/2004, 10:00 AM


MapObjects Programmers Reference 135

dat1.Type = moDatum_WGS1984
dat2.Type = moDatum_AGD1984
gcs1.Datum = dat1
gcs2.Datum = dat2
Set Map1.Layers(0).CoordinateSystem = gcs1
Set Map1.Layers(1).CoordinateSystem = gcs2

End Sub

DblClick Event
Applies To Map Object

Description The DblClick event is a standard ActiveX control event, which occurs when the user presses
and then releases a mouse button over the map twice in rapid succession.

Syntax Private Sub object_DblClick()

The DblClick event syntax has one part:

Part Description

object An object expression that evaluates to a Map control.

Remarks For more information about the DblClick event, see the Visual Basic online.

See Also Map events

DefaultSymbol Property
Applies To LabelPlacer Object, EventRenderer Object, ValueMapRenderer Object

Description Returns a reference to the Symbol used to draw the MapLayer features that do not have an
explicitly assigned symbol.

Syntax object.DefaultSymbol

The Database property syntax has these parts:

Part Description

object An object expression that evaluates to a Symbol object.

See Also Symbol Object, UseDefault Property

ProgrammersReference.pmd 135 10/28/2004, 10:00 AM


136 MapObjects Programmers Reference

Example This example demonstrates the role of the DefaultSymbol and UseDefault properties of a
ValueMapRenderer. The example controls whether all unique values in a specified Field draw
with a unique symbol or whether the values that fall outside a range of specified values draw
with a default symbol. To try this example, paste the code into the Declarations section of a
form containing a CheckBox named Check1, a ListBox named List1, and a Map named Map1
that contains at least one MapLayer with polygon features; press F5 and double-click a field
name in the list whose unique values to display. Use the check box to toggle whether or not to
use the default symbol for values outside the specified range.
Option Explicit
Dim moRecset As MapObjects2.Recordset

Private Sub Form_Load()

Dim oField As MapObjects2.Field

Set moRecset = Map1.Layers(0).Records


For Each oField In moRecset.Fields
If VarType(oField.Value) > vbNull And VarType(oField.Value) _
<= moString Then
List1.AddItem oField.name
End If
Next
Check1.Caption = Use Default Value
End Sub

Private Sub List1_DblClick()


Dim strs As New MapObjects2.Strings
Dim sFldname As String
Dim oRenderer As New MapObjects2.ValueMapRenderer
Dim oSym As New MapObjects2.Symbol
Dim i As Integer

Set moRecset = Map1.Layers(0).Records


sFldname = List1.List(List1.ListIndex)

iterate through the records and accumulate values


Do While Not moRecset.EOF
strs.Add moRecset(sFldname).ValueAsString
moRecset.MoveNext
Loop

set up a ValueMap renderer


Set Map1.Layers(0).Renderer = oRenderer
oRenderer.Field = sFldname
oRenderer.UseDefault = Check1.Value toggle

ProgrammersReference.pmd 136 10/28/2004, 10:00 AM


MapObjects Programmers Reference 137

set the number of values for which to render a unique symbol


simulates values that might be considered in an other
category
If oRenderer.UseDefault Then
If strs.Count > 1 Then
arbitrarily specify that only half the values will get _
a unique symbol
oRenderer.ValueCount = strs.Count / 2
Else
oRenderer.ValueCount = 1
End If
Else one symbol for each unique value
oRenderer.ValueCount = strs.Count
End If

this is the symbol to use if UseDefault is True


Set oSym = oRenderer.DefaultSymbol
oSym.Color = moPaleYellow

set the values for the renderer


For i = 0 To oRenderer.ValueCount - 1
oRenderer.Value(i) = strs(i)
Next i

Map1.Refresh
Set oRenderer = Nothing
Set strs = Nothing
Set moRecset = Nothing
End Sub

Private Sub Check1_Click()


If List1.ListIndex <> -1 Then List1_DblClick
End Sub

Delete Method
Applies To Recordset Object

Description Deletes the current record in an open Recordset object.

Syntax object.Delete

The Delete method syntax has these parts:

ProgrammersReference.pmd 137 10/28/2004, 10:00 AM


138 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to a Recordset object.

Remarks When you delete records from a Recordset, there must be a current record in object before
you use Delete, otherwise an error will occur.

Delete removes the current record and makes it inaccessible. Although you cannot edit or use
the deleted record, it remains current. Once you move to another record, the deleted records
becomes permanently irretrievable.

See Also Edit Method, Update Method, Delete Method, EditMode Property

Example This example uses the Delete method to delete the first record in a Recordset. To try this
example, paste the code into the Declarations section of a form that contains a
CommandButton named Command1 and a Map named Map1 that has at least one MapLayer;
then press F5. Click the CommandButton to delete the record.
Option Explicit

Private Sub Command1_Click()


Dim recset As MapObjects2.Recordset
Dim ans As Variant
Set recset = Map1.Layers(0).Records
recset.MoveFirst
Map1.FlashShape recset.Fields(shape).Value, 4
ans = MsgBox(Are you sure you want to delete this record?, _
vbYesNo, MapObjects)
If ans = vbYes Then
recset.Edit
recset.Delete
recset.StopEditing
Map1.Refresh
End If
End Sub

Private Sub Form_Load()


Command1.Caption = Delete
End Sub

DeleteGeoDataset Method
Applies To DataConnection Object

Description Deletes a GeoDataset object from a DataConnection (shapefiles only).

ProgrammersReference.pmd 138 10/28/2004, 10:00 AM


MapObjects Programmers Reference 139

Syntax object.DeleteGeoDataset name [=return]

The DeleteGeoDataset method syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

name A string expression that evaluates to the name of the GeoDataset object to
delete.

return A boolean expression that indicates the status of the DeleteGeoDataset


method call.

Return Values The DeleteGeoDataset method return values are:

Part Description

false Either the method has failed to remove one or more of the files constituting
a shapefile, or the GeoDataset specified in the name variable does not
derive from a shapefile.

true The specified shapefile was removed.

See Also GeoDataset Object, TableDesc Object

Remarks The DeleteGeoDataset method will try to delete the .shp, .dbf, and .shx files as specified. If
each deletion is successful, the method will also search for and attempt to delete .sbn, .sbx and
.prj files. If each deletion is successful, the method will return True.

If any deletion is unsuccessful, the method will return False, therefore care should be taken
when using this method, as some files may remain. The method may fail, for example, due to
files having a read-only status, insufficient file privileges of the user, or the file may already be
open by another application or process.

Example This example demonstrates how you can use the DeleteGeoDataset method to remove a
GeoDataset from a DataConnection. To try this example, paste the code into the Declarations
section of a form that contains a DirListBox named Dir1, a ListBox named List1, a
CommandButton named Command1; then press F5. Navigate to a folder that contains
GeoDatasets and double-click the folders name to display its GeoDatasets. In the ListBox,
click the name of the GeoDataset to delete and press Command1.
Option Explicit
Dim dc As New MapObjects2.DataConnection

Private Sub Command1_Click()


With dc

ProgrammersReference.pmd 139 10/28/2004, 10:00 AM


140 MapObjects Programmers Reference

.Database = Dir1.path
If .Connect Then

If Not .FindGeoDataset(List1.List(List1.ListIndex)) Is _
Nothing Then
.DeleteGeoDataset List1.List(List1.ListIndex)
End If

List1.Clear
dir1_Change

End If
End With
End Sub

Private Sub dir1_Change()


Dim oDataset As MapObjects2.GeoDataset

With dc
.Database = Dir1.path

If .Connect Then
List1.Clear
If .GeoDatasets.Count > 0 Then
For Each oDataset In .GeoDatasets
List1.AddItem oDataset.Name
Next
End If
End If
.Disconnect
End With

End Sub

Private Sub Form_Load()


Command1.Caption = &Delete GeoDataset
End Sub

DensificationTolerance Property
Applies To MapLayer Object

Description Returns or sets the densification tolerance for a MapLayer object. This property works in
conjunction with the MapLayers GeographicTransformation property for on-the-fly
projection of the MapLayer.

ProgrammersReference.pmd 140 10/28/2004, 10:00 AM


MapObjects Programmers Reference 141

Syntax object.DensificationTolerance [=tolerance].

The DensificationTolerance property syntax has these parts:

Part Description

object An object expression that evaluates to a MapLayer.

tolerance A numeric expression, which sets the frequency at which points are inserted
into the MapLayers features, in Map Units.

Remarks When a MapLayer has its GeographicTransformation property set, MapObjects will re-
project the MapLayer, on the fly, according to that geographic transformation. You must also
set a CoordinateSystem on the Map and on the MapLayer.

MapLayers that do not have a CoordinateSystem set will be displayed unprojected.

See Also Rectangle Object, Extent Property

Example This example sets the DensificationTolerance property of a MapLayer relative to its units. To
try this example, paste the code into the Declarations section of a form containing a Map
named Map1 that has at least one MapLayer, and a ListBox called List1. Press F5 to run the
example.
Option Explicit

Private Sub Form_Load()

Dim PCS As New MapObjects2.ProjCoordSys


PCS.Type = 32630
Map1.Layers(0).CoordinateSystem = PCS

If Map1.Layers(0).CoordinateSystem.Type > 0 Then


Label1.Caption = Map Layer Units: & _
Map1.Layers(0).CoordinateSystem.Unit.Name
Map1.Layers(0).DensificationTolerance = 0.5
Label2.Caption = Deinsification Tolerance: & _
Map1.Layers(0).DensificationTolerance
End If

End Sub

Depth Property
Applies To Rectangle Object

ProgrammersReference.pmd 141 10/28/2004, 10:00 AM


142 MapObjects Programmers Reference

Description Returns the difference between the Ceiling and Floor coordinates of a Rectangle object.

Syntax Set variable = object.Depth

The Depth property syntax has these parts:

Part Description

variable A numeric expression that contains the depth of the Rectangle

object An object expression that evaluates to an object in the Applies To list.

Remarks The Depth property to represents the dimension of the rectangle along the Z-axis. By default,
a Rectangle object will have a Depth of zero.

See Also Ceiling Property, Floor Property

Example See Ceiling property

Difference Method
Applies To Point Object, Points Collection, Line Object, Polygon Object, Rectangle Object, Ellipse
Object

Description Returns a shape that represents the geometric Difference of two shape objects of the same
dimension.

Syntax Set resultShape = object.Difference (subtractShape [,extent])

The Difference method syntax has these parts:

Part Description

resultShape An object expression that evaluates to a shape object. (See Remarks). Will
contain the resulting shape after the difference operation.

object An object expression that evaluates to an object in the Applies To list. This
is the shape whose dimensions will be reduced by subtractShape.

subtractShape An object expression that evaluates to an object in the Applies To list. This
is the shape that represents the amount by which object will be reduced.(See
Remarks).

extent An object expression that evaluates to a Rectangle object. This Rectangle


should entirely contain the objects extent, and is used internally.

ProgrammersReference.pmd 142 10/28/2004, 10:00 AM


MapObjects Programmers Reference 143

Remarks If the two Shapes do not have a valid Difference, the resultShape will be nil.

Only certain combinations of shape are valid, and the return result will be a different object
type depending on the nature of the objects processed. The following table summarizes the
valid combinations and possible return results.

Type of object subtractShapes Possible resultShapes

Point Point, Point

Points Object Points Object

Points Object Point, Point

Points Object Points Object

Line Line Line

Rectangle Rectangle Rectangle

Polygon Polygon

Ellipse

Polygon Rectangle Rectangle

Polygon Polygon

Ellipse

Ellipse Rectangle Rectangle

Polygon Polygon

Ellipse

An exception will be raised if an incompatible shape type is passed as an argument for


subtractShape.

Where the resultShape could be more than one object type (e.g. Rectangle or Polygon), then
use an interim Object and then test the result using its ShapeType property to see what type of
object it is.

The Difference method is not commutative, therefore the order of object and subtractShape
arguments is significant to the result, i.e. shapeA.Difference(shapeB) could be different to
shapeB.Difference(shapeA).

ProgrammersReference.pmd 143 10/28/2004, 10:00 AM


144 MapObjects Programmers Reference

You cannot use the Difference method with a self-intersecting Polygon. If you do, an excep-
tion is raised in Visual Basic, specifying Error 5000, Valid Object expected as argument. You
can however use a self-intersecting Line.

See Also Buffer Method, GetCrossings Method, Intersect Method, Union Method, XOr Method

Example This example uses the Difference method to allow the user to perform Difference operations
on polygons. The polygons and the new shape generated by the Difference operation are
added to the tracking layer as GeoEvents. To try this example, paste the code into the Declara-
tions section of a form containing a Map named Map1 that has at least one MapLayer, press
F5, and then click on the map to track two polygons.
Option Explicit
Dim shape1 As Object
Dim shape2 As Object
Dim diff As Boolean

Private Sub doDifference(shape As Object)


If Not diff Then
Set shape1 = shape
diff = True
ElseIf diff Then

Dim diffShape As Object


Dim diffEvent As New MapObjects2.GeoEvent
Set shape2 = shape
Set diffShape = shape1.Difference(shape2, Map1.FullExtent)
Set diffEvent = Map1.TrackingLayer.AddEvent(diffShape, 1)

Set shape1 = Nothing


diff = False
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
If Button = 2 Then
Dim r As New MapObjects2.Rectangle
Set r = Map1.TrackRectangle
Map1.Extent = r
Exit Sub
End If

Line difference
Dim poly As New MapObjects2.Polygon
Dim eventLine As New MapObjects2.GeoEvent

ProgrammersReference.pmd 144 10/28/2004, 10:00 AM


MapObjects Programmers Reference 145

Set poly = Map1.TrackPolygon


Set eventLine = Map1.TrackingLayer.AddEvent(poly, 0)
Call doDifference(poly)
End Sub

Private Sub Form_Load()


diff = False

Map1.TrackingLayer.SymbolCount = 2
With Map1.TrackingLayer.Symbol(0)
.SymbolType = moFillSymbol
.Style = moGrayFill
.Color = moGreen
.OutlineColor = moGreen
End With
With Map1.TrackingLayer.Symbol(1)
.SymbolType = moFillSymbol
.Style = moGrayFill
.Color = moBlue
.OutlineColor = moBlue
End With
End Sub

Direction Constants
MapObjects defines the following Direction constants to describe the direction in which a
geographic transformation is performed.

Constant Value Description

moDirection_Forward 1 When using a pre-defined transformation, the


transformation will occur in the direction implied
by the Name of the
GeoTransformationConstants. If a
SecondType is used then by default the direction
of the second stage transformation will be
reverse, that is, opposite to what the
SecondName states.

When using a user-defined transformation, the


transformation will go from the GeoCoordSys
defined by the FromGeoCoordSys property to
that defined in the ToGeoCoordSys property.

ProgrammersReference.pmd 145 10/28/2004, 10:00 AM


146 MapObjects Programmers Reference

moDirection_Reverse 0 When using a pre-defined transformation, the


transformation will occur in the opposite
direction to that implied by the Name or
SecondName of the
GeoTransformationConstants.

It should not be necessary to specify a direction


of Reverse when using a user-defined transforma-
tion, but it is possible to do so.

See Also GeoTransformation Object

Direction Property
Applies To GeoTransformation Object

Description Sets or returns a value that identifies the Direction of the GeoTransformation.

Syntax object.Direction [= dirConstant ]

The Direction property syntax has these parts:

Part Description

object An object expression that evaluates to a GeoTransformation object.

dirConstant A numeric expression that specifies the Direction of the


GeoTransformation, as described in Settings

Settings The settings for dirConstant are DirectionConstants.

Remarks If you are using only one GeoTransformation Type, you should set the Direction property to
the appropriate direction for the transformation you require.

If you are using two different Types on the GeoTransformation, (i.e. you have set both Type
and SecondType) you should set both the Direction and SecondDirection properties appro-
priately. By default, the Direction property is forward and the SecondDirection is reverse.

See Also GeoCoordSys Object

Example This example demonstrates the Direction property of the GeoTransformation object. To try
this example, paste the code into the Declarations section of a new Form which has two Map
controls named Map1 and Map2. Each Map should contain a MapLayer with geographical
locations in common. Ensure the coordinate systems of each MapLayer are set appropriately.

ProgrammersReference.pmd 146 10/28/2004, 10:00 AM


MapObjects Programmers Reference 147

Then press F5, and click on either Map. The point will be transformed to the other maps
coordinate system, and displayed on both maps.
Option Explicit
Dim fromPt As New MapObjects2.Point
Dim toPt As New MapObjects2.Point
Dim curMap As Integer
Dim sym As New MapObjects2.Symbol

Private Function transformPoint(direction As MapObjects2. _


DirectionConstants, ptIn As MapObjects2.Point) As Point
Here, an appropriate GeoTransformation is created for transforming
the selected Point. This should be changed appropriately for the
CoordinateSystem of your Map2 MapLayer.
Dim myGT As New MapObjects2.GeoTransformation
myGT.Type = moGeoTransformation_OSGB1936_To_WGS1984_1

Set the appropriate direction, FromGeoCoordSys and ToGeoCoordSys


myGT.direction = direction

A CoordinateSystem may be either ProjCoordSys or GeoCoordSys.


We need to check if the type before assigning the FromGeoCoordSys
and ToGeoCoordSys
Dim map1Projected As Boolean
Dim map2Projected As Boolean

If Map1.CoordinateSystem.IsProjected Then
map1Projected = True
Else
map1Projected = False
End If

If Map2.CoordinateSystem.IsProjected Then
map2Projected = True
Else
map2Projected = False
End If

If changing from WGS1984 to other datum


If direction = moDirection_Forward Then
If map1Projected Then
myGT.FromGeoCoordSys = Map1.CoordinateSystem.GeoCoordSys
Else
myGT.FromGeoCoordSys = Map1.CoordinateSystem
End If
If map2Projected Then

ProgrammersReference.pmd 147 10/28/2004, 10:00 AM


148 MapObjects Programmers Reference

myGT.ToGeoCoordSys = Map2.CoordinateSystem.GeoCoordSys
Else
myGT.ToGeoCoordSys = Map2.CoordinateSystem
End If
Set transformPoint = Map2.CoordinateSystem.Transform _
(Map1.CoordinateSystem, fromPt, , myGT)

ElseIf direction = moDirection_Reverse Then


If map1Projected Then
myGT.ToGeoCoordSys = Map1.CoordinateSystem.GeoCoordSys
Else
myGT.ToGeoCoordSys = Map1.CoordinateSystem
End If
If map2Projected Then
myGT.FromGeoCoordSys = Map2.CoordinateSystem.GeoCoordSys
Else
myGT.FromGeoCoordSys = Map2.CoordinateSystem
End If

Set transformPoint = Map1.CoordinateSystem.Transform( _


Map2.CoordinateSystem, fromPt, , myGT)
End If

End Function

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If (Not fromPt Is Nothing) And curMap = 1 Then
sym.Color = moBlue
Map1.DrawShape fromPt, sym
End If
If (Not toPt Is Nothing) And curMap = 2 Then
sym.Color = moRed
Map1.DrawShape toPt, sym
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Set fromPt = Map1.ToMapPoint(X, Y)
Set toPt = transformPoint(moDirection_Forward, fromPt)
curMap = 1
Map1.TrackingLayer.Refresh (True)
Map2.TrackingLayer.Refresh (True)
End Sub

ProgrammersReference.pmd 148 10/28/2004, 10:00 AM


MapObjects Programmers Reference 149

Private Sub Map2_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If (Not fromPt Is Nothing) And curMap = 2 Then
sym.Color = moBlue
Map2.DrawShape fromPt, sym
End If
If (Not toPt Is Nothing) And curMap = 1 Then
sym.Color = moRed
Map2.DrawShape toPt, sym
End If
End Sub

Private Sub Map2_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Set fromPt = Map2.ToMapPoint(X, Y)
Set toPt = transformPoint(moDirection_Reverse, fromPt)
curMap = 2
Map1.TrackingLayer.Refresh (True)
Map2.TrackingLayer.Refresh (True)
End Sub

Private Sub Form_Load()


Map1 should contain a MapLayer based on the WGS1984 Datum,
for example the World Countries sample dataset.
Map2 should contain a MapLayer based on a different Datum
You should ensure the CoordinateSystem of both layers is set
correctly.
Dim pcs As New MapObjects2.ProjCoordSys
pcs.Type = moProjCS_BritishNationalGrid
Map2.Layers(0).CoordinateSystem = pcs

Dim gcs As New MapObjects2.GeoCoordSys


gcs.Type = moGeoCS_WGS1984
Map1.Layers(0).CoordinateSystem = gcs

Here the CoordinateSystem of each map is set to the


CoordinateSystem of its MapLayer
Map1.CoordinateSystem = Map1.Layers(0).CoordinateSystem
Map2.CoordinateSystem = Map2.Layers(0).CoordinateSystem

With sym
.SymbolType = moPointSymbol
.Size = 4
.Outline = False
.Style = moTriangleMarker
End With

ProgrammersReference.pmd 149 10/28/2004, 10:00 AM


150 MapObjects Programmers Reference

Arrange controls
Map1.Move 60, 60, 5000, 5000
Map2.Move Map1.Left + Map1.Width + 100, Map1.Top, Map1.Width, _
Map1.Height
Form1.Width = Map2.Left + Map2.Width + 60
Form1.Height = Map2.Top + Map2.Height + 60
End Sub

Disconnect Method
Applies To DataConnection Object

Description Terminates a connection to a DataConnection.

Syntax object.Disconnect

The Disconnect method syntax has these parts:

Part Description

object An object expression that evaluates to a DataConnection object.

Remarks The Disconnect method should always be used to Disconnect from an SDE server before the
application ends.

See Also Connect Method, Connected Property

Example See Connected property

DistanceTo Method
Applies To Point Object, Points Collection, Line Object, Polygon Object, Rectangle Object

Description Returns the distance in map units between two objects.

Syntax object.DistanceTo( shape)

The DistanceTo method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 150 10/28/2004, 10:00 AM


MapObjects Programmers Reference 151

shape An object expression that evaluates to a Point, Points, Line, Polygon, or


Rectangle object.

Remarks The DistanceTo method will return true 3D distances between shapes that support Z values,
except for Polygon objects, for which the shortest distance from the other shape to the nearest
edge of the Polygon is returned instead.

See Also DistanceToSegment Method

Example This example uses the DistanceTo method to measure the distance between the center of the
Map and the first GeoEvent on the Map objects TrackingLayer. To try this example, paste the
code into the Declarations section of a form containing a CommandButton named Command1
and a Map named Map1 that contains at least one MapLayer, and then press F5 and click the
Map to add a GeoEvent. A left-click will add a point event, and a right-click will allow the
user to track a polygon, and add this polygon as an event. To determine the distance, click
Command1.
Option Explicit
Private Sub Command1_Click()
Dim lDist As Long
Dim oMypt As Point

If Map1.TrackingLayer.EventCount > 0 Then


With Map1.TrackingLayer.Event(0)
Dim oMypt As New MapObjects2.Point
oMypt.X = .X
oMypt.Y = .Y
lDist = Map1.Extent.Center.DistanceTo(oMypt)
MsgBox Its & Str(lDist) & units from the center of the _
map to the first GeoEvent.
End With
Else
MsgBox There are curently no events in your tracking layer. _
& Chr(13) & Please click on the map to add a geoevent.
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)

If Button = 1 Then
Dim oPoint As MapObjects2.Point
Set oPoint = Map1.ToMapPoint(X, Y)
Map1.TrackingLayer.AddEvent oPoint, 0

ElseIf Button = 2 Then

ProgrammersReference.pmd 151 10/28/2004, 10:00 AM


152 MapObjects Programmers Reference

Dim poly As New MapObjects2.Polygon


Set poly = Map1.TrackPolygon
Map1.TrackingLayer.AddEvent poly, 1
End If

End Sub

Private Sub Form_Load()


Map1.TrackingLayer.SymbolCount = 2
With Map1.TrackingLayer.Symbol(0)
.SymbolType = moPointSymbol
.Color = moRed
.Size = 8
End With
With Map1.TrackingLayer.Symbol(1)
.SymbolType = moFillSymbol
.Color = moRed
.Style = moGrayFill
End With
End Sub

DistanceToSegment Method
Applies To Point Object

Description Returns the distance in map units from one Point to two other Point objects that represent a
line segment.

Syntax object.DistanceToSegment( Point1, Point2)

The DistanceToSegment method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

Point1 An object expression that evaluates to a Point object.

Point2 An object expression that evaluates to a Point object.

See Also Line Object, Points Property

Example This example uses the DistanceToSegment method to return the distance from a Point to two
points that constitute a line segment. To try this example, paste the code into the Declarations

ProgrammersReference.pmd 152 10/28/2004, 10:00 AM


MapObjects Programmers Reference 153

section of a form containing a Map named Map1, then press F5 and click the Map to position
a point. The code reports the distance to the line segment.
Option Explicit
Dim moLine As New MapObjects2.line
Dim moPoints As New MapObjects2.Points
Dim moPoint As MapObjects2.Point

Private Sub Form_Load()


Dim oRect As New Rectangle
Dim oPoint1 As New MapObjects2.Point
Dim oPoint2 As New MapObjects2.Point

oRect.Left = 0: oRect.Bottom = 0: oRect.Right = 100: oRect.Top = 100


Map1.Extent = oRect

oPoint1.X = oRect.Left
oPoint1.Y = oRect.Bottom
oPoint2.X = oRect.Right
oPoint2.Y = oRect.Top
moPoints.Add oPoint1
moPoints.Add oPoint2
moLine.Parts.Add moPoints

End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
Dim oLnSym As New MapObjects2.Symbol
Dim oPtSym As New MapObjects2.Symbol

If Not moLine Is Nothing Then


oLnSym.SymbolType = moLineSymbol
oLnSym.Color = moRed
Map1.DrawShape moLine, oLnSym
End If

If Not moPoint Is Nothing Then


oPtSym.SymbolType = moPointSymbol
oPtSym.Color = moBlue
oPtSym.Style = moCircleMarker
Map1.DrawShape moPoint, oPtSym
End If

End Sub

ProgrammersReference.pmd 153 10/28/2004, 10:00 AM


154 MapObjects Programmers Reference

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
Dim fDist As Double

Set moPoint = Map1.ToMapPoint(X, Y)


fDist = moPoint.DistanceToSegment(moPoints(0), moPoints(1))
Map1.TrackingLayer.Refresh True
MsgBox Format(fDist, fixed) & units to the segment

End Sub

DotColor Property
Applies To DotDensityRenderer Object

Description Returns or sets the color of each of dot of a DotDensityRenderer object.

Syntax object.DotColor [= color]

The DotColor property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

color A value or constant that determines the color of the dots used by the
renderer.

Settings For more information on color settings, see ColorConstants.

See Also DotSize Property, DotValue Property

Example This example uses the DotColor property to control the color of the dots in a Dot Density map.
To try this example, paste the code into the Declarations section of a form containing a
CommonDialog control, a CommandButton named Command1, a Label named Label1, a
ListBox named List1, a TextBox named Text1, and a Map named Map1 that contains one
MapLayer with polygon features. Press F5 and click the button.
Option Explicit

Private Sub Command1_Click()


Dim oDotRend As New MapObjects2.DotDensityRenderer
Dim oStats As MapObjects2.Statistics

With Map1.Layers(0)
Set .Renderer = oDotRend

ProgrammersReference.pmd 154 10/28/2004, 10:00 AM


MapObjects Programmers Reference 155

Set oStats = .Records.CalculateStatistics _


(List1.List(List1.ListIndex))
Text1.Text = (oStats.Min + (oStats.Max - oStats.Min) / 2) / 20
End With

CommonDialog1.ShowColor get the DotColor from the Color dialog

With oDotRend
.Field = List1.List(List1.ListIndex)
.DotSize = 4
.DotColor = CommonDialog1.Color
.DotValue = Text1.Text
.DrawBackground = True
End With
Map1.Refresh
Set oDotRend = Nothing disassociate object
End Sub

Private Sub Form_Load()


Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field

Set oRecset = Map1.Layers(0).Records

For Each oField In oRecset.Fields


If oField.Type < moDate Then numeric fields
List1.AddItem oField.Name
End If
Next

With Text1
.Text =
.Locked = True
End With

With Label1
.Caption = 1 dot equals this many units:
.AutoSize = True
.Left = Text1.Left
.Top = Text1.Top - Label1.Height
End With

With Command1
.Caption = Draw Dots
.Left = Text1.Left
.Top = Text1.Top + Text1.Height * 1.5

ProgrammersReference.pmd 155 10/28/2004, 10:00 AM


156 MapObjects Programmers Reference

.Enabled = False
End With
End Sub

Private Sub List1_Click()


Command1.Enabled = True
End Sub

DotDensityRenderer Object
A DotDensityRenderer is an object that represents a way of symbolizing features by drawing
dots on a feature. Each dot represents a uniform, specified value in the Field property of the
DotDensityRenderer as specified in its DotValue property. You can set the color of the dots
with DotColor and the size of the dots in points with DotSize.

A DotDensityRenderer is a creatable object in MapObjects. In Visual Basic, heres one way


to create a DotDensityRenderer:
Set Map1.Layers(0).Renderer = New MapObjects2.DotDensityRenderer
See Also ChartRenderer Object, ClassBreaksRenderer Object, ValueMapRenderer Object

Properties

DotColor DotValue Field

DotSize DrawBackground Tag

DotSize Property
Applies To DotDensityRenderer Object

Description Returns or sets the size of each dot of a DotDensityRenderer object.

Syntax object.DotSize [= value]

The DotSize property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression that specifies the size in points to draw the dots.

See Also DotColor Property, DotValue Property

ProgrammersReference.pmd 156 10/28/2004, 10:00 AM


MapObjects Programmers Reference 157

Example This example uses the DotSize property to control the size of the dots in a Dot Density map.
To try this example, paste the code into the Declarations section of a form containing a
TextBox control named Text1, a CommandButton named Command1 and a Map named Map1
that contains one MapLayer with polygon features. You may want to change the Field property
from Pop1990 to the name of a numeric field appropriate to your data and change the
DotValue to a value appropriate to your data. Press F5, enter a new value for the DotSize, and
click the button.
Option Explicit
Private Sub Command1_Click()
With Map1
.Layers(0).Renderer.DotSize = Text1.Text
.Refresh
End With

End Sub

Private Sub Form_Load()


Set Map1.Layers(0).Renderer = New MapObjects2.DotDensityRenderer
Map1.Layers(0).Symbol.Color = moPaleYellow

With Map1.Layers(0).Renderer
.Field = Pop1990
.DotSize = 4
.DotColor = moRed
.DotValue = 100000
.DrawBackground = True
End With

Me.Show must do this in order to use SetFocus in Load


With Text1
.Text = 4
.SetFocus
.SelLength = 1
End With

End Sub

DotValue Property
Applies To DotDensityRenderer Object

Description Returns or sets the value in the Field associated with a DotDensityRenderer that one dot
represents.

ProgrammersReference.pmd 157 10/28/2004, 10:00 AM


158 MapObjects Programmers Reference

Syntax object.DotValue [= value]

The DotValue property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression that specifies the value in the DotDensityRenderer


objects Field property that one dot represents.

See Also DotColor Property, DotSize Property

Example This example uses the DotValue property to control the value one dot represents in a Dot
Density map. To try this example, paste the code into the Declarations section of a form
containing a TextBox control named Text1, a CommandButton named Command1 and a Map
named Map1 that contains one MapLayer with polygon features. You may want to change the
Field property from Pop1990 to the name of a numeric field appropriate to your data. Press
F5, enter a new value for the DotValue, and click the button.
Option Explicit
Private Sub Command1_Click()
With Map1
.Layers(0).Renderer.DotValue = Text1.Text
.Refresh
End With

End Sub

Private Sub Form_Load()

Text1.Text = 100000
With Map1
Set .Layers(0).Renderer = New MapObjects2.DotDensityRenderer
.Layers(0).Symbol.Color = moPaleYellow

With .Layers(0).Renderer
.Field = Pop1990
.DotSize = 4
.DotColor = moRed
.DotValue = Text1.Text
.DrawBackground = True
End With
End With

Me.Show must do this in order to use SetFocus in Load


With Text1

ProgrammersReference.pmd 158 10/28/2004, 10:00 AM


MapObjects Programmers Reference 159

.SetFocus
.SelLength = Len(Text1.Text)
End With

End Sub

DragDrop Event
Applies To Map Object

Description The DragDrop event is a standard ActiveX control event, which occurs when an object is
dragged over a Map control and the mouse button is released.

Syntax Private Sub object_DragDrop(source As Control, x As Single, y As Single)

The DragDrop event syntax has these parts:

Part Description

object An object expression that evaluates to a Map control.

source The object being dragged.

X A value of Single data type, specifying the X coordinate of the mouse click,
in control units.

Y A value of Single data type, specifying the Y coordinate of the mouse click,
in control units.

Remarks For more information about the DragDrop event, see the Visual Basic online reference

Note that the DragDrop event is not supported for Map controls with a WindowMode of
Windowless Opaque or Windowless Transparent.

See Also DragFiles Event, ToMapPoint Method

DragFiles Event
Applies To Map Object

Description Occurs when a drag-and-drop operation of filenames is in progress. You can use this event to
monitor the mouse pointer as it enters, leaves, or rests directly over a valid target. The mouse
pointer position determines the target object that receives this event.

ProgrammersReference.pmd 159 10/28/2004, 10:00 AM


160 MapObjects Programmers Reference

See Also DragDrop Event, DropFiles Event, Strings Collection

Syntax Private Sub object_DragFiles(ByVal fileNames As Object, ByVal x As Single, ByVal y As


Single, ByVal state As Integer, dropValid As Boolean)

The DragFiles event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

fileNames An object expression that evaluates to a Strings collection whose members


represent the names of the files that are being dragged.

x, y A number that specifies the current horizontal (x) and vertical (y) position of
the mouse pointer within the target object.

state An integer value or constant that indicates the transition state of the
filenames being dragged in relation to the target Map as indicated in
Settings.

dropValid A boolean expression that indicates whether the target is valid.

Settings The settings for state are DragStateConstants.

Remarks In order for the corresponding DropFiles event to occur, dropValid must be set to True when
appropriate. The DragFiles event should be used for dragging the names of valid
GeoDatasets onto the Map control, which may then be added programmatically to the Layers
collection.

Note that the DragFiles event is not supported for Map controls with a WindowMode of
Windowless Opaque or Windowless Transparent.

Example This example demonstrates how to add one or more MapLayer objects to a Map by dragging
shapefile entries listed in the Windows Explorer and dropping them directly onto the Map. To
try this example, paste the code into the Declarations section of a form containing a Map
named Map1. Press F5 and then click-drag one or more shapefiles from Windows Explorer
onto the Map. After you release the mouse, the code adds the shapefiles as MapLayer objects,
sorted by ShapeType.
Option Explicit
Private Sub Map1_DragFiles(ByVal fileNames As Object, ByVal X _
As Single, ByVal Y As Single, ByVal state As Integer, dropValid _
As Boolean)
If fileNames.Count > 0 Then
dropValid = True
End If

ProgrammersReference.pmd 160 10/28/2004, 10:00 AM


MapObjects Programmers Reference 161

End Sub

Private Sub Map1_DropFiles(ByVal fileNames As Object, ByVal X _


As Single, ByVal Y As Single)
Dim dcx As New MapObjects2.DataConnection
Dim shpfile As Variant
Dim i As Integer
Dim ml As MapObjects2.MapLayer
Dim p As MapObjects2.MapLayer
Dim l As MapObjects2.MapLayer

shpfile = (Dir(fileNames.Item(0), vbDirectory))


shpfile = CStr(Left(shpfile, Len(shpfile) - 4))
dcx.Database = Left(fileNames.Item(0), Len(fileNames.Item(0)) _
- Len(shpfile) - 5)
If dcx.Connect Then
For i = 0 To fileNames.Count - 1
Set ml = New MapObjects2.MapLayer
shpfile = Dir(fileNames.Item(i), vbDirectory)
shpfile = CStr(Left(shpfile, Len(shpfile) - 4))
ml.GeoDataset = dcx.FindGeoDataset(shpfile)
Map1.Layers.Add ml
Next i

prepare collections to sort layers


Dim ptcoll As New Collection
Dim linecoll As New Collection
Dim polycoll As New Collection
Dim imgcoll As New Collection
For i = 0 To Map1.Layers.Count - 1
Check if its a MapLayer or Imagelayer
If Map1.Layers(i).LayerType = moMapLayer Then
Select Case Map1.Layers(i).shapeType
Case 21 point features
ptcoll.Add Map1.Layers(i)
Case 22 line features
linecoll.Add Map1.Layers(i)
Case 23 polygon features
polycoll.Add Map1.Layers(i)
End Select
Else
imgcoll.Add Map1.Layers(i)
End If
Next i
Map1.Layers.Clear

ProgrammersReference.pmd 161 10/28/2004, 10:00 AM


162 MapObjects Programmers Reference

add all the layers back in sorted by type


Dim il, pol, ln, pt As Object
For Each il In imgcoll
Map1.Layers.Add il
Next il
For Each pol In polycoll
Map1.Layers.Add pol
Next pol
For Each ln In linecoll
Map1.Layers.Add ln
Next ln
For Each pt In ptcoll
Map1.Layers.Add pt
Next pt
End If
Map1.Extent = Map1.FullExtent
Map1.Refresh

End Sub

DragOver Event
Applies To Map Object

Description The DragOver event is a standard ActiveX control event, which occurs when an object is
dragged over a Map control.

Syntax Private Sub object_DragOver(source As Control, x As Single, y As Single, state As


Integer)

The DragOver event syntax has these parts:

Part Description

object An object expression that evaluates to a Map control.

source The control being dragged.

X A value of Single data type, specifying the X coordinate of the mouse click,
in control units.

Y A value of Single data type, specifying the Y coordinate of the mouse click,
in control units.

ProgrammersReference.pmd 162 10/28/2004, 10:00 AM


MapObjects Programmers Reference 163

state A value that corresponds to the transition state of the control being dragged
in relation to a target form or control, see Values below.

Values The state parameter may have the following values:

Value Action Description

0 Enter source control is being dragged within the range of a target

1 Leave source control is being dragged out of the range of a target

2 Over source control has moved from one position in the target to
another

Remarks For more information about the DragOver event, see the Visual Basic online reference.

Note that the DragOver event is not supported for Map controls with a WindowMode of
Windowless Opaque or Windowless Transparent.

See Also DragFiles Event, DropFiles Event, ToMapPoint Method

DragState Constants
MapObjects defines the following constants for use with the Map objects DragFiles event.

Constant Value Description

moDragEnter 0 Enter (fileNames are being dragged within the range of the
Map).

moDragLeave 1 Leave (fileNames are being dragged out of the range of the
Map).

moDragOver 2 Over (fileNames have moved from one position in the Map to
another).

See Also DragFiles Event, Map Object

DrawBackground Property
Applies To DotDensityRenderer Object, EventRenderer Object, GroupRenderer Object, LabelPlacer
Object, LabelRenderer Object

ProgrammersReference.pmd 163 10/28/2004, 10:00 AM


164 MapObjects Programmers Reference

Description Returns or sets a value indicating whether a renderer displays a maps background fill and
polygon outline.

Syntax object.DrawBackground [= value]

The DrawBackground property syntax has these parts:

Part Description

object An object expression that evaluates to a renderer object.

value A boolean expression that determines whether the back color and polygon
outline display, as described in Settings.

Settings The settings for value are:

Setting Description

True The renderer objects back color and polygon outline display.

False The renderer objects back color and polygon outline do not display.

Remarks The DrawBackground method is implemented by all renderers, and is used to indicate
whether the features of a layer should be drawn on the Map before the renderer itself draws to
the Map. You may wish to make use of this property when using a custom renderer, as when
the DrawBackground property is True, the Map will take care of drawing features.

See Also Symbol Object

Example This example uses the DrawBackground property to control the background of a Dot Density
map. To try this example, paste the code into the Declarations section of a form containing a
Label named Label1, a ListBox named List1, a CheckBox named Check1, a TextBox named
Text1, and a Map named Map1 that contains one MapLayer with polygon features that have
statistical data associated with them. Press F5 and click the name of a field. You can toggle the
DrawBackground property with the CheckBox.
Option Explicit

Private Sub List1_Click()


Dim oStats As MapObjects2.Statistics
Dim oRenderer As New MapObjects2.DotDensityRenderer

Set Map1.Layers(0).Renderer = oRenderer


Map1.Layers(0).Symbol.Color = moPaleYellow

Set oStats = Map1.Layers(0).Records.CalculateStatistics _


(List1.List(List1.ListIndex))

ProgrammersReference.pmd 164 10/28/2004, 10:00 AM


MapObjects Programmers Reference 165

Text1.Text = (oStats.Min + (oStats.Max - oStats.Min) / 2) / 20

With oRenderer
.Field = List1.List(List1.ListIndex)
.DotSize = 4
.DotColor = moRed
.DotValue = Text1.Text
.DrawBackground = Check1.Value
End With
Map1.Refresh
End Sub

Private Sub Check1_Click()


If List1.ListIndex <> -1 Then set a field first
List1_Click
End If
End Sub

Private Sub Form_Load()


Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field
Set oRecset = Map1.Layers(0).Records

For Each oField In oRecset.Fields


If oField.Type < moDate Then numeric fields
List1.AddItem oField.name
End If
Next oField

With Text1
.Locked = True
.Text =
End With

With Label1
.Caption = 1 dot equals this many units:
.AutoSize = True
.Left = Text1.Left
.Top = Text1.Top - Label1.Height
End With

With Check1
.Left = Text1.Left
.Top = Text1.Top + Text1.Height
.Caption = Draw background
.Value = 1 initialize DrawBackground to True

ProgrammersReference.pmd 165 10/28/2004, 10:00 AM


166 MapObjects Programmers Reference

End With
End Sub

DrawError Event
Applies To Map Object

Description Occurs when a Map cannot draw the specified MapLayer.

Syntax Private Sub object_DrawError(ByVal index As Integer)

The DrawError event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

index An integer that uniquely identifies the member of the MapLayers collection
that can not be drawn.

See Also AfterLayerDraw Event, AfterTrackingLayerDraw Event, BeforeLayerDraw Event,


BeforeTrackingLayerDraw Event

Example This example demonstrates one way to use the DrawError event if the application cant draw
the specified MapLayer because another application has opened the associated Recordset for
writing. To try this example, paste the code into the Declarations section of a form containing
a Map named Map1 that contains a MapLayer. Create an executable that edits the same
GeoDataset as the one associated with the MapLayer. Run the editing application and then run
this example.
Option Explicit

Private Sub Map1_DrawError(ByVal index As Integer)


Dim fnt As New StdFont
fnt.Name = Times
fnt.Size = 14
Dim s As New TextSymbol
Set s.Font = fnt

Map1.DrawText Data Unavailable for & Map1.Layers(index).Name _


& , Map1.Extent, s
End Sub

ProgrammersReference.pmd 166 10/28/2004, 10:00 AM


MapObjects Programmers Reference 167

DrawingCanceled Event
Applies To Map Object

Description Occurs after you perform a CancelAction on a Map or a MapLayer.

Syntax Private Sub object_DrawingCanceled()

The object placeholder represents an object expression that evaluates to a Map.

See Also AfterLayerDraw Event, AfterTrackingLayerDraw Event, BeforeLayerDraw Event,


BeforeTrackingLayerDraw Event

Example This example demonstrates the role of the DrawingCanceled event if the user presses ESC
while the map is drawing. To try this example, paste the code into the Declarations section of a
form containing a CommandButton named Command1 and a Map named Map1 that contains
at least one MapLayer, and then press F5. While the map is drawing, press the ESC key. You
can use Command1 to zoom to the full extent of the map.
Option Explicit

Private Sub Map1_DrawingCanceled()


Dim response As Variant
response = MsgBox(The map is in an incomplete state. _
Zoom in?, vbYesNo)
If response = vbYes Then
Dim rect As New MapObjects2.Rectangle
Set rect = Map1.Extent
rect.ScaleRectangle 0.1
Map1.Extent = rect
End If
End Sub

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

DrawShape Method
Applies To Map Object

Description Draws a shape on a Map.

Syntax object.DrawShape shape, symbol

ProgrammersReference.pmd 167 10/28/2004, 10:00 AM


168 MapObjects Programmers Reference

The DrawShape syntax has the following object qualifier and arguments:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

shape An object expression that evaluates to a geometric shape (Point, Points,


Line, Rectangle, Polygon or Ellipse) or a Recordset object. The
Recordset must be derived from a GeoDataset, not from a Table object.

symbol An object expression that evaluates to a Symbol object.

Remarks Invoke the DrawShape method in a Layer or TrackingLayer drawing event, otherwise
MapObjects returns an error.

If you specify a Recordset as the shape argument for DrawShape, the method positions the
Recordset at the first record and then draws each feature stored in the Shape field. At the end
of the call, DrawShape positions the Recordset at the first record again.

See Also Point Object, Points Object, Line Object, Rectangle Object, Ellipse Object, Polygon Object

Example This example uses the DrawShape method to draw a shape on the Map. To try this example,
paste the code into the Declarations section of a form containing a Map named Map1. Press
F5 and then click-drag a rectangle on the map.
Option Explicit
Dim rect As MapObjects2.Rectangle

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
Dim sym As New MapObjects2.Symbol
If Not rect Is Nothing Then
sym.SymbolType = moFillSymbol
sym.Style = moDiagonalCrossFill
sym.Color = moBlue
Map1.DrawShape rect, sym
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Set rect = Map1.TrackRectangle
Map1.TrackingLayer.Refresh True
End Sub

ProgrammersReference.pmd 168 10/28/2004, 10:00 AM


MapObjects Programmers Reference 169

DrawText Method
Applies To Map Object

Description Draws text on a Map.

Syntax object.DrawText text, shape, symbol

The DrawText syntax has the following object qualifier and arguments:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

text A string expression specifying the text to draw.

shape An object expression that evaluates to a Point object, a Line object, a


Rectangle object or a Points object.

symbol An object expression that evaluates to a TextSymbol object.

Remarks If shape is a Line object, DrawText splines the text, using the coordinates of the Line as a
guide. If shape is a Point object, MapObjects centers the text on the point. If shape is a
Rectangle object, MapObjects ignores the VerticalAlignment property and aligns the text
horizontally with the center point of the Rectangle. If shape is a Points object, then the text
will be positioned at the center of the extent of all points in the collection.

Invoke the DrawText method in a Layer or TrackingLayer drawing event, otherwise


MapObjects returns an error.

See Also TextSymbol Object

Example This example uses the DrawText method to draw some text on the Map. To try this example,
paste the code into the Declarations section of a form containing a Map named Map1 that
contains at least one MapLayer, and then press F5. Note that the height parameter for
DrawText is set to 0; therefore the code will draw the text using the Size property of the
TextSymbol objects Font.
Option Explicit
Dim textsym As New MapObjects2.TextSymbol

Private Sub Form_Load()


Dim fnt As New StdFont
fnt.Name = Arial

ProgrammersReference.pmd 169 10/28/2004, 10:00 AM


170 MapObjects Programmers Reference

fnt.Size = 36
Set textsym.Font = fnt
With textsym
.Color = moLightGray
.Height = 0 use font size (36 points in this case)
.VerticalAlignment = moAlignBaseline
End With
End Sub

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As stdole.OLE_HANDLE)
Map1.DrawText MapObjects, Map1.Extent.Center, textsym
End Sub

DropFiles Event
Applies To Map Object

Description Occurs when you complete a drag-and-drop operation as a result of dragging the source files
over a Map and releasing the mouse button over a valid position on the target.

Syntax Private Sub object_DropFiles(ByVal fileNames As Object, ByVal x As Single, ByVal y As


Single)

The DropFiles event syntax has these parts:

Part Description

object An object expression that evaluates to a Map.

fileNames An object expression that evaluates to a Strings collection whose members


represent the names of the files that are being dragged.

x, y A number that specifies the current horizontal (x) and vertical (y) position of
the mouse pointer within the target object.

Remarks In order for the DropFiles event to occur, dropValid must be set to True in the DragFiles
event when appropriate.

Note that the DropFiles event is not supported for Map controls with a WindowMode of
Windowless Opaque or Windowless Transparent.

See Also AfterLayerDraw Event, AfterTrackingLayerDraw Event, BeforeLayerDraw Event,


BeforeTrackingLayerDraw Event, Strings Collection

ProgrammersReference.pmd 170 10/28/2004, 10:00 AM


MapObjects Programmers Reference 171

Example See DragFiles Event

Edit Method
Applies To Recordset Object

Description Allows edits for the current record.

See Also Update Method, Delete Method, EditMode Property

Syntax object.Edit

The Edit method syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

Remarks Your application should check the Updatable property before calling Edit to determine
whether changes can be made to the Recordset.

When you call the Edit method, the EditMode property changes to moEditInProgress. This
can be used by your application to determine whether changes are being made to a Recordset.

Make sure that any editing operations your program carries out are made to the same
Recordset object for which you called the Edit method. The safest approach is to create a
local Recordset object, on which all the editing operations are carried out. The following
Visual Basic example shows how this can be done for a given MapLayer, called new_layer:
Dim recs As MapObjects2.Recordset
Set recs = new_layer.Records

If recs.Updatable Then
recs.Edit
If recs.EditMode = moEditInProgress Then
Edit feature and attributes
recs.Update
Else
MsgBox Edit failed.
End If
End If
Example See CancelUpdate Method

ProgrammersReference.pmd 171 10/28/2004, 10:00 AM


172 MapObjects Programmers Reference

EditMode Constants
MapObjects defines the following constants for use with the Recordset objects EditMode
property.

Constant Value Description

moEditNone 0 No editing operation is in progress.

moEditInProgress 1 Edit method has been invoked, and the current


record is in the copy buffer.

moEditAdd 2 AddNew method has been invoked, and the


current record in the copy buffer is a new record
that has not been saved in the database.

See Also Field Object, Recordset Object

Example See CancelUpdate Method

EditMode Property
Applies To Recordset Object

Description Returns a value that indicates the state of editing for the current record

Syntax object.EditMode

The EditMode property syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

Return Values The EditMode property returns EditModeConstants

See Also Edit Method, Update Method, Delete Method, EditMode Property

Example See CancelUpdate Method

ProgrammersReference.pmd 172 10/28/2004, 10:00 AM


MapObjects Programmers Reference 173

Ellipse Object
An Ellipse object represents an elliptical geometric shape. The Center of an Ellipse object is
a Point that is the center of the bounding Rectangle that defines its Extent. The MapLayer
objects TrackCircle method returns an Ellipse.

You can create an Ellipse object in Visual Basic with code like this:
Set el = New MapObjects2.Ellipse

Properties

Bottom Height Right Top

Center Left ShapeType Width

Extent

Methods

Buffer Inset IsPointIn Union

Difference Intersect Offset XOr

See Also TrackCircle Method

Enabled Property
Applies To Map Object

Description Returns or sets a value that determines whether an object can respond to user-generated
events.

Syntax object.Enabled [= boolean]

The Enabled property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

boolean A boolean expression specifying whether object can respond to user-


generated events, as described in Settings.

ProgrammersReference.pmd 173 10/28/2004, 10:00 AM


174 MapObjects Programmers Reference

Settings The settings for boolean are:

Setting Description

True (Default) Allows object to respond to events.

False Prevents object from responding to events.

Remarks The Enabled property allows a Map to be enabled or disabled at run time. For example, you
can disable a Map that does not apply to the current state of the application.

See Also Visible Property

EnableGIF Method
Applies To Map Object

Description Enables use of GIF reading when supplied with a valid license code.

Syntax object.EnableGIF (licenseCode)

The EnableGIF method syntax has the following parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

licenseCode A string expression evaluating to the license code for GIF reading

Remarks In order to use a GIF image as an ImageLayer, you must invoke the EnableGIF method at
the start of your application code, such as in the Initialize or Load event of a form
(Form_Initialize or Form_Load in Visual Basic).

Follow the procedures included with your product packaging for obtaining a valid license
code.

Here is how you would invoke EnableGIF:

Private Sub Form_Load()


Map1.EnableGIF ABC1234567 invalid code - for illustration only
End Sub
See Also ImageLayer Object

ProgrammersReference.pmd 174 10/28/2004, 10:00 AM


MapObjects Programmers Reference 175

EnableTIFFLZW Method
Applies To Map Object

Description Enables use of TIFF LZW compression for image layers when supplied with a valid license
code.

Syntax object.EnableTIFFLZW (licenseCode)

The EnableTIFFLZW method syntax has the following parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

licenseCode A string expression evaluating to the license code for TIF LZW compression
for image layers

Remarks In order to use a TIFF LZW compressed image as an ImageLayer, you must invoke the
EnableTIFFLZW method at the start of your application code, such as in the Initialize or
Load event of a form (Form_Initialize or Form_Load in Visual Basic).

Follow the procedures included with your product packaging for obtaining a valid license
code.

Here is how you would invoke EnableTIFFLZW:

Private Sub Form_Load()


Map1.EnableTIFFLZW ABC1234567 invalid code-for illustration only
End Sub
See Also ImageLayer Object

EndMeasureField Property
Applies To EventRenderer Object

Description Returns or sets the field which specifies at which Measure value, along a Line feature, an
event ends.

Syntax object.EndMeasureField [= fieldname]

The EndMeasureField property syntax has these parts:

ProgrammersReference.pmd 175 10/28/2004, 10:00 AM


176 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to a EventRenderer.

value A string expression evaluating to the Field property of the EventTable of an


EventRenderer which defines the measure at which an event ends.

Remarks The EndMeasureField property is only used for rendering Line events. If you have specified
SymbolType to be moPointSymbol, the EndMeasureField is ignored.

See Also StartMeasureField Property, EventRouteIDField Property, FeatureRouteIDField Property

Example See EventRenderer Object

EnhancedGeocodingError Constants
MapObjects defines the following constants for use with the Geocoder and Standardizer
objects LastError property.

Constant Value Description

mgErrorNone 0 No error

mgErrorUnknown 1 Unknown error

mgErrorInternal 2 Internal error

mgErrorMatchRulesUnspecified 3 Match rules unspecified

mgErrorIntersectionMatchRulesUnspecified 4 Intersection match rules


unspecified

mgErrorStandardizerUnspecified 5 Standardizer unspecified

mgErrorStreetTableUnspecified 6 Street table unspecified

mgErrorStandardizationRulesUnspecified 7 Standardization rules


unspecified

mgErrorStandardizerInvalid 8 Specified Standardizer is


invalid

mgErrorCannotOpenMatchRules 9 Cannot open match rules

ProgrammersReference.pmd 176 10/28/2004, 10:00 AM


MapObjects Programmers Reference 177

mgErrorNoMatchVariables 10 Cannot find match


variables

mgErrorOutOfMemory 11 Out of memory

mgErrorMatchRulesSyntax 12 Error in match rules syntax

mgErrorMatchRulesWarningsTriggered 13 Match rules warnings


triggered

mgErrorNoCandidates 14 No candidates

mgErrorTooManyHandlesAllocated 15 Too many handles


allocated

mgErrorNoAddressStandardized 16 No address standardized

mgErrorCannotAccessDatabase 17 Cannot access database

mgErrorCannotOpenStandardizationRules 18 Cannot open standardiza-


tion rules

mgErrorStandardizationRulesProcessing 19 Error processing standard-


ization rules

mgErrorCannotReadStandardizationRules 20 Cannot read standardiza-


tion rules

mgErrorCannotAccessAddressFile 21 Cannot access address file

mgErrorCannotWriteOutputDatabase 22 Cannot write to output


database

mgErrorMatchVariableKeyFieldUnspecified 23 Match variable key field


are unspecified

mgErrorStreetTableIndexMissing 24 Street table is missing a


geocoding index

mgErrorRecordCountMismatch 25 Record count mismatch in


building the indices

mgErrorNoIndicesSpecified 26 No indices were specified


to build

mgErrorTooManyIndicesSpecified 27 Too many indices speci-


fied (the maximum is 10)

ProgrammersReference.pmd 177 10/28/2004, 10:00 AM


178 MapObjects Programmers Reference

mgErrorCorruptMetadataInformation 28 Corrupt metadata informa-


tion

mgErrorMetadataTooLong 29 Metadata string is too


long, key information is
too complex

mgErrorKeyFieldNotFoundInDatabase 30 Could not find specified


key field in database

mgErrorQueryTooComplex 31 The query is too complex,


use less keys (or Soundex
searches)

mgErrorNoQueries 32 No search queries given

mgErrorOutOfDiskSpace 33 Out of disk space

See Also Geocoder Object, Standardizer Object, LastError Property

EOF Property
Applies To Recordset Object

Description Returns a value that indicates whether the current record position is after the last record in a
Recordset.

See Also MoveFirst Method, MoveLast Method, MovePrevious Method

Syntax object.EOF [=isEnd]

The EOF property syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

isEnd A boolean expression indicating the status of the current record, see Return
Values.

Return Values The EOF return values are:

Value Description

True The current record position is after the last record.

ProgrammersReference.pmd 178 10/28/2004, 10:00 AM


MapObjects Programmers Reference 179

False The current record position is on or before the last record.

Remarks The MoveNext method should not be called when the EOF property is True.

Example See CancelUpdate Method

EraseIndices Method
Applies To Geocoder Object

Description Removes the geocoding index file associated with a Geocoder object if the file is not read-
only.

See Also BuildIndices Method, IndexStatus Method

Syntax object.EraseIndices = [erased]

The EraseIndices method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

erased A variable declared to be of the boolean data type.

Return Values The EraseIndices method return values are:

Part Description

True The index file is removed successfully.

False The index file cannot be removed due to an error. Use the LastError
property to check the type of error.

Remarks You can use the Geocoder objects IndexStatus method to check if a valid geocoding file
exists before you attempt to remove it.

Example See AddIndex Method

Event Property
Applies To TrackingLayer Object

Description Returns a reference to a GeoEvent object on the TrackingLayer.

ProgrammersReference.pmd 179 10/28/2004, 10:00 AM


180 MapObjects Programmers Reference

Syntax object.Event( index)

The Event method syntax has these parts:

Part Description

object An object expression that evaluates to a TrackingLayer object.

index An Integer data type index that indicates which GeoEvent to reference.

See Also GeoEvent Object

Example This example uses the Event property to iterate throughout the GeoEvents of a Maps
TrackingLayer in order to determine whether a GeoEvent falls within a selection rectangle. To
try this example, paste the code into the Declarations section of a form containing a Map
named Map1 that contains at least one MapLayer, and then press F5 and click the map to add
GeoEvents. Then hold down Shift and select some of the GeoEvents.
Option Explicit

Private Sub Form_Load()


Dim fnt As New StdFont
fnt.Name = Wingdings
fnt.Bold = False
Map1.TrackingLayer.SymbolCount = 2
With Map1.TrackingLayer.Symbol(0)
.Color = moGreen
.Style = moTrueTypeMarker
.Font = fnt
.Size = 16
.CharacterIndex = 108
End With

With Map1.TrackingLayer.Symbol(1)
.Color = moRed
.Style = moTrueTypeMarker
.Font = fnt
.Size = 16
.CharacterIndex = 108
End With
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Dim r As MapObjects2.Rectangle
Dim nEventCount As Long, i As Long
If Shift = 0 Then

ProgrammersReference.pmd 180 10/28/2004, 10:00 AM


MapObjects Programmers Reference 181

Dim pt As MapObjects2.Point
Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.AddEvent pt, 0
Else
Set r = Map1.TrackRectangle
nEventCount = Map1.TrackingLayer.EventCount
Dim testPt As New MapObjects2.Point
Dim evt As MapObjects2.GeoEvent
For i = 0 To nEventCount - 1
Set evt = Map1.TrackingLayer.Event(i)
testPt.x = evt.x
testPt.y = evt.y
If r.IsPointIn(testPt) Then
evt.SymbolIndex = 1
Else
evt.SymbolIndex = 0
End If
Next i
Map1.Refresh
End If
End Sub

EventCount Property
Applies To TrackingLayer Object

Description Returns the number of GeoEvent objects currently on the TrackingLayer.

Syntax object.EventCount [= count]

The EventCount property syntax has these parts:

Part Description

object An object expression that evaluates to a TrackingLayer object.

count An Integer data type variable that represents the number of GeoEvents on
the TrackingLayer.

See Also GeoEvent Object

Example This example uses the EventCount property to keep a running count of the number of
GeoEvents on the TrackingLayer of a Map. As you add GeoEvents to the TrackingLayer by
clicking on the Map, a Label displays the current count. To try this example, paste the code

ProgrammersReference.pmd 181 10/28/2004, 10:00 AM


182 MapObjects Programmers Reference

into the Declarations section of a form containing a Label named Label1 and a Map named
Map1 that contains at least one MapLayer, and then press F5 and click the map.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Dim pt As MapObjects2.Point
Set pt = Map1.ToMapPoint(x, y)
Map1.TrackingLayer.AddEvent pt, 0
Label1.Caption = Map1.TrackingLayer.EventCount
End Sub

Private Sub Form_Load()


Label1.Caption = 0
End Sub

EventRenderer Object
An EventRenderer is an object that represents a way of symbolizing events that occur on
features of a MapLayer, by drawing a Symbol for each event found. Events are only gener-
ated on Line objects, therefore an EventRenderer can only be applied to a MapLayer
consisting of shapes with the Line ShapeType.

You can specify the type of event that the EventRenderer will symbolize by setting the
SymbolType property. For point events this should be set to the moPointSymbol constant
and for linear events, moLineSymbol. The type of event to be rendered will depend on the
information contained in the EventTable.

The renderer displays the events in the EventTable by matching the route Id value of each
event against the features in the MapLayer. The FeatureRouteIDField property specifies the
field in the MapLayers Recordset that contains route ID values and the EventRouteIDField
property specifies the field containing route ID values in the EventTables Recordset.

The measure values for an event determine where it will be displayed on the matching feature
in the MapLayer. An event in an EventTable is specified by values in the
StartMeasureField and EndMeasureField properties. When rendering point events, only
values contained in the StartMeasureField are used, the event is rendered at that measure.
When rendering line events, the event begins at the measure value in StartMeasureField and
continues until the measure value in EndMeasureField.

The symbols used to display events can be based on values held in the EventTable. The
SymbolField property specifies the field that contains a numeric value to match against the
renderers symbol array. By setting its ValueCount property you can determine how many
values of its SymbolField property the EventRenderer will provide a symbol for.

ProgrammersReference.pmd 182 10/28/2004, 10:00 AM


MapObjects Programmers Reference 183

You should then set the properties of each Symbol in the symbol array. In addition, you should
specify which value in the SymbolField corresponds to which Symbol in the symbol array by
setting the value array. For example, if you wish to render events with a value of 75 in the
SymbolField with the first Symbol in the symbol array (Symbol(0)), you should set the first
value in the Value array to equal 75 (Value(0) = 75).

For events in the EventTable which do not have a value in the SymbolField, the
DefaultSymbol will be used if the UseDefault property is True. If the SymbolField property
is not set, or the field cannot be found, then all symbols will be rendered with the
DefaultSymbol.

When using large datasets with large numbers of events, displaying the MapLayer with an
EventRenderer may become a time consuming operation. In order to manage the rendering of
large numbers of events more efficiently, you can use the IndexEvents and IndexExtent
properties, and the InvalidateIndex method. You can control the way in which the
EventRenderer accesses the Event information, decreasing the time your MapLayer takes to
draw.

An EventRenderer is a creatable object in MapObjects. In Visual Basic, heres one way to


create an EventRenderer:
Set Map1.Layers(0).Renderer = New MapObjects2.EventRenderer

Properties

DefaultSymbol EventTable StartMeasureField UseDefault

DrawBackground FeatureRouteIDField Symbol Value

EndMeasureField IndexEvents SymbolField ValueCount

EventRouteIDField IndexExtent Tag

Methods

InvalidateIndex

See Also MapLayer Object, Symbol Object, Line Object

Example This example demonstrates the use of the EventRenderer and its properties. To try this
example, paste the code into the Declarations section of a form containing a Map control
named Map1 containing one MapLayer with lines which have measure values, and a Com-
mand Button named Command1. This example uses an EventTable from Excel 97 with Fields
called ROUTE, EVENT1, EVENT2 and SYMBOL. You should change the Fields,
Values, fName and Database as appropriate for your EventTable. Press F5 and click Com-
mand1.

ProgrammersReference.pmd 183 10/28/2004, 10:00 AM


184 MapObjects Programmers Reference

Option Explicit

Private Sub Command1_Click()

Screen.MousePointer = moHourglass

Dim evRend As New MapObjects2.EventRenderer


Dim evTab As New MapObjects2.Table
Dim fName As String
Dim database As String

Set Map1.Layers(0).Renderer = evRend

The fName and database strings should be changed as appropriate


for your data
fName = rt_zmEventTable.xls
database = C:\Program Files\ESRI\MapObjects2\Samples\Data

This example uses an Excel spreadsheet for its EventTable


See the Accessing Data pages in the online help - you should
have a reference to the appropriate type library in your project.
evTab.database = EXCEL 8.0; DATABASE= & database & & fName
evTab.Name = points$

With evRend
.DrawBackground = True
.ValueCount = 3
.SymbolType = moLineSymbol
.DefaultSymbol.SymbolType = moLineSymbol
.DefaultSymbol.Style = moDashLine
.DefaultSymbol.Color = moRed
.DefaultSymbol.Size = 1

Change this value as appropriate


.Value(0) = 0
With .Symbol(0)
.Style = moSolidLine
.Size = 2
.Color = moBlue
End With

Change this value as appropriate


.Value(1) = 1
With .Symbol(1)
.Style = moSolidLine
.Size = 2

ProgrammersReference.pmd 184 10/28/2004, 10:00 AM


MapObjects Programmers Reference 185

.Color = moCyan
End With

Change this value as appropriate


.Value(2) = 2
With .Symbol(2)
.Style = moSolidLine
.Size = 2
.Color = moGreen
End With

.EventTable = evTab

Fields should be changed as appropriate for your event table


.FeatureRouteIDField = ROUTE
.EventRouteIDField = ROUTE
.StartMeasureField = EVENT1
.EndMeasureField = EVENT2
.SymbolField = SYMBOL
End With

Map1.Refresh
Screen.MousePointer = moDefault
End Sub

Private Sub Form_Load()


Command1.Caption = Render Events
End Sub

EventRouteIDField Property
Applies To EventRenderer Object

Description Returns or sets the EventRouteIDField property of the EventRenderer object.

Syntax object. EventRouteIDField [= fieldname]

The EventRouteIDField property syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

value A string expression evaluating to the Field property of the EventTable of an


EventRenderer which defines the route ID field.

ProgrammersReference.pmd 185 10/28/2004, 10:00 AM


186 MapObjects Programmers Reference

Remarks The EventRouteIDField property is used to specify which Field in the EventTable contains
route ID information. The EventRouteIDField and FeatureRouteIDField should contain
similar values.

If the EventRouteIDField property contains a value which does not match with any value in
the FeatureRouteIDField, no event will be rendered.

See Also StartMeasureField Property, EndMeasureField Property, FeatureRouteIDField Property

Example See EventRenderer Object

EventTable Property
Applies To EventRenderer Object

Description Returns a reference to the EventTable used to draw the events on a MapLayer which has an
EventRenderer set. The EventTable property references a MapObjects2 Table object.

Syntax object.EventTable [= table]

The EventTable property syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

table A Table object containing event information, as described in Remarks.

Remarks The EventTable of an EventRenderer should contain at least two fields, an


EventRouteIDField containing route IDs, and a StartMeasureField containing measure
values on the route. If rendering line events, the EventTable should also contain an
EndMeasureField. A SymbolField can also be used to specify the Symbol which should be
used to render each event.

See Also Symbol Object, EndMeasureField Property, StartMeasureField Property,


FeatureRouteIDField Property, EventRouteIDField Property

Example See EventRenderer Object

Export Method
Applies To Recordset Object, GeoCoordSys Object, ProjCoordSys Object

ProgrammersReference.pmd 186 10/28/2004, 10:00 AM


MapObjects Programmers Reference 187

Description For Recordset objects, the Export method writes the Recordset to a GeoDataset, creating a
Shapefile. For GeoCoordSys or ProjCoordSys objects, the Export method writes a .prj file
that describes the coordinate system itself.

Syntax For a GeoCoordSys or ProjCoordSys

object.Export ( outName )

Syntax For a Recordset

object.Export ( outName, [outCoordSys] )

The Export method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

outName A string expression that evaluates to the full path and file name on disk for
the exported file.

outCoordSys Optional. Used with Recordset objects only. If this parameter is used, the
Recordset is exported into the coordinate system defined. May be of type
GeoCoordSys or ProjCoordSys.

Remarks ProjCoordSys and GeoCoordSys Objects

When used with ProjCoordSys or GeoCoordSys objects, the Export method makes it
possible to store the details of how a shapefile or SDE layer should be projected when added
as a MapLayer in MapObjects. For shapefiles, this information can be stored separately in a
Projection file (.prj) alongside the GeoDataset on disk. The prj file should have the same
filename as the shapefile, and the .prj extension. When MapObjects reads a GeoDataset based
on a shapefile with a prj file present, the GeoDataset will be held transformed into that
coordinate system.

For SDE layers, the projection information is stored in the layers definition table. The
projection files used with shapefiles and SDE layers are the only form of projection metadata
which can be written by MapObjects. Projection files used with coverages must be generated
using ARC/INFO, not using the MapObjects Export method.

Recordset Objects

When exporting a Recordset, the Shapefile created will support Z and Measure values only if
the GeoDataset that underlies the Recordset itself has support for Z and Measure values.
Your program can check this using the HasZ and HasMeasure properties of the GeoDataset
object. Shapefiles with support for Z and Measure values are only fully supported as of

ProgrammersReference.pmd 187 10/28/2004, 10:00 AM


188 MapObjects Programmers Reference

ArcView 3.1 and MapObjects 2.0. In some cases, older applications may not be able to read
such Shapefiles. If you intend to use geographic data transformed in MapObjects with older
applications, an alternative is to use the AddGeoDataset method to create a new GeoDataset
with the required Z and Measure support and then to copy features to it, transforming them if
required.

See Also GeoDataset Object, ReturnDescription Method, AddGeoDataset Method, Transform


Method

Example This example uses the Export method of the Recordset object to export a MapLayer to a
shapefile, transformed to a different coordinate system. The exported MapLayer is added to
the Map for comparison with the untransformed MapLayer. To try this example, paste the code
into the Declarations section of a form containing a CommandButton named Command1, a
CommonDialog control named CommonDialog1, a Combo Box named Combo1 and a Map
named Map1, containing one MapLayer which has a coordinate system set. Press F5, and then
click Command1.
Option Explicit
Dim newLayer As New MapObjects2.MapLayer
Dim coordSys As New MapObjects2.ProjCoordSys

Private Sub Command1_Click()


Dim name As String

CommonDialog1.ShowSave
name = Combo1.List(Combo1.ListIndex)
coordSys.Type = stripProj(name)

newLayer.GeoDataset = Map1.Layers(0).Records.Export _
(CommonDialog1.FileName, coordSys)
With newLayer.Symbol
.Style = moLightGrayFill
.Color = moYellow
End With

If newLayer.Valid Then
Map1.Layers.Add newLayer
Map1.Extent = Map1.FullExtent
Else
MsgBox New maplayer is not valid, vbExclamation, _
Invalid MapLayer
End If
End Sub

Private Sub Form_Load()


Command1.Caption = Export

ProgrammersReference.pmd 188 10/28/2004, 10:00 AM


MapObjects Programmers Reference 189

CommonDialog1.InitDir = App.Path
CommonDialog1.DialogTitle = Export Projected Shapefile
CommonDialog1.Filter = Shapefiles (.shp)|*.shp

Dim projCoord As New MapObjects2.Strings


projCoord.PopulateWithProjectedCoordSys
Dim i As Variant
For Each i In projCoord
Combo1.AddItem ProjCoordSys: & i
Next i
Combo1.ListIndex = 0

With Map1.Layers(0).Symbol
.Style = moSolidFill
.Color = moDarkGreen
End With
End Sub

Function stripProj(theProjection As String) As Variant


Get position of open bracket
Dim openB As Integer
openB = InStr(theProjection, [)
stripProj = Left(Right(theProjection, Len(theProjection) - openB), _
Len(theProjection) - openB - 1)
End Function

ExportMap Constants
MapObjects defines the following constants for use with the Map objects ExportMap
method to specify what type of file to export.

Constant Value Description

moExportEMF 0 ExportMap creates a Windows Enhanced Metafile


(EMF) file.

moExportBMP 1 ExportMap creates a Windows Bitmap (BMP) file.

moExportClipboardEMF 2 ExportMap places a metafile (CF_ENHMETAFILE)


on the clipboard.

moExportClipboardBMP 3 ExportMap places a bitmap (CF_DIB) on the


clipboard.

See Also Map Object, ExportMap Method

ProgrammersReference.pmd 189 10/28/2004, 10:00 AM


190 MapObjects Programmers Reference

ExportMap Method
Applies To Map Object

Description Writes the visible extent of the Map to the specified file in Windows Bitmap or enhanced
metafile format.

Syntax object.ExportMap format, formatData, scaleFactor

The ExportMap method syntax has the following parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

format A value or constant that determines the format of the exported file, as
described in Settings.

formatData A string expression that evaluates to the full path and file name on disk for
export files. For Clipboard formats, indicates whether or not to clear the
Clipboard. True clears the Clipboard, False prevents the clear.

scaleFactor A value that determines the output resolution. An output resolution of 1


represents the same number of pixels in the bitmap image of the Map as on
the screen, an output resolution of 10 is ten times the original number of
pixels in the image, both in the horizontal and the vertical direction.

Settings The settings for format are ExportMapConstants.

Remarks ExportMap does not support VisibleRegion or Transparent properties. If RotationAngle is


not zero, any ImageLayers in the Map controls Layers collection will not be visible. If any
ImageLayers in the Map controls Layers collection have their Transparent property set to
True, then these too will not be visible.

See Also CopyMap Method, ExportMap2 Method, OutputMap Method, OutputMap2 Method,
PrintMap Method

Example This example uses the ExportMap method to export the visible extent of a Map to the speci-
fied file in enhanced metafile format. To try this example, paste the code into the Declarations
section of a form that contains a CommonDialog control named CommonDialog1, a
CommandButton named Command1, and a Map named Map1 that contains at least one
MapLayer, and then press F5; click Command1. Specify the folder and name of the file where
you want to export the Map. Note: If the Map you want to export contains any ImageLayer

ProgrammersReference.pmd 190 10/28/2004, 10:00 AM


MapObjects Programmers Reference 191

that has an image depth greater than 8 bits per pixel, and you want to honor its palette, use
ExportMap2 and set its useSourceDepth parameter to True.
Option Explicit
Private Sub Command1_Click()
CommonDialog1.DefaultExt = *.emf
CommonDialog1.Filter = Enhanced Metafile (*.emf)|*.emf
CommonDialog1.FileName = map1.emf
CommonDialog1.CancelError = True
On Error Resume Next
CommonDialog1.ShowSave
If Err.Number = cdlCancel Then Cancel button pressed
Err.Clear
Exit Sub
End If
Map1.ExportMap moExportEMF, CommonDialog1.FileName, 2
End Sub

ExportMap2 Method
Applies To Map Object

Description Writes the visible extent of the Map to the specified file in Windows Bitmap or enhanced
metafile format, and allows an output source depth to be specified.

Syntax object.ExportMap2 format, formatData, scaleFactor, useSourceDepth

The ExportMap2 method syntax has the following parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

format A value or constant that determines the format of the exported file, as
described in Settings.

formatData A string expression that evaluates to either:

Exporting to a file: the full path and file name on disk for export files.

Exporting to Clipboard: indicates whether or not to clear the Clipboard.


True clears the Clipboard, False prevents the clear.

scaleFactor A value that determines the output resolution. An output resolution of 1


represents the same number of pixels in the bitmap image of the Map as

ProgrammersReference.pmd 191 10/28/2004, 10:00 AM


192 MapObjects Programmers Reference

on the screen, an output resolution of 10 is ten times the original number


of pixels in the image, both in the horizontal and the vertical direction.

useSourceDepth Optional. A boolean expression that indicates whether to search through


the ImageLayers of the Map to determine whether the palette of any of
the source images is greater than 8 bits per pixel. If so, ExportMap2 will
honor the source palette. Default value is False.

Settings The settings for format are ExportMapConstants.

Remarks ExportMap2 gives you the ability to export 16 and 24-bit truecolor bitmaps. When using the
WebLink object (supplied with MapObjects Internet Map Server) it should be noted that only
8 bit color bitmaps can be converted a JPEG with the Bmp2JPEG method.

ExportMap2 does not support VisibleRegion or Transparent properties. If RotationAngle


is not zero, any ImageLayers in the Map controls Layers collection will not be visible. If
any ImageLayers in the Map controls Layers collection have their Transparent property set
to True, then these too will not be visible.

See Also CopyMap Method, ExportMap Method, ExportMap2 Method, OutputMap Method,
OutputMap2 Method, PrintMap Method

ExtendedError Property
Applies To DataConnection Object

Description Returns a value that represents any ExtendedErrors returned from an RDBMS while access-
ing SDE layers.

Syntax variable = object.ExtendedError

The ExtendedError property syntax has these parts:

Part Description

variable A variable that has been declared to be a long data type

object An object expression that evaluates to a DataConnection object.

Return Values The value that is returned for this property is that raised by the Relational Database Manage-
ment System underlying your SDE instance. You should check your RDBMS manuals for
more information about the exact cause and meaning of the returned value.

See Also Connect Method, Connected Property, ConnectError Property, Disconnect Method,
ExtendedErrorString Property

ProgrammersReference.pmd 192 10/28/2004, 10:00 AM


MapObjects Programmers Reference 193

Example See ClearConnectError Property

ExtendedErrorString Property
Applies To DataConnection Object

Description Returns a value that represents any ExtendedErrorString returned from an RDBMS while
accessing SDE layers.

Syntax variable = object.ExtendedErrorString

The ExtendedErrorString property syntax has these parts:

Part Description

variable A variable that has been declared to be a String data type

object An object expression that evaluates to a DataConnection object.

Return Values The descriptive string that is returned for this property is that raised by the Relational Data-
base Management System underlying your SDE instance. You should check your RDBMS
manuals for more information about the exact cause and meaning of the returned description.

See Also Connect Method, Connected Property, ConnectError Property, Disconnect Method,
ExtendedError Property

Example See ClearConnectError Property

Extent Property
Applies To Ellipse Object, ImageLayer Object, Line Object, Points Object, Map Object, MapLayer
Object, Polygon Object

Description Returns or sets the spatial extent of an object. The property is read-only for all objects to
which it applies, with the exception of the Map object and MapLayers derived from SDE.

Syntax object.Extent [= rectangle]

The Extent property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 193 10/28/2004, 10:00 AM


194 MapObjects Programmers Reference

rectangle An ActiveX Automation object of type Rectangle that MapObjects exposes.

Remarks In Visual Basic you may wish to use the Extent property to zoom in on a map. Below, a code
fragment shows you how you might do this in the Maps MouseDown event:
Dim r as New MapObjects2.Rectangle
Set r = Map1.TrackRectangle
Set Map1.Extent = r
You should bear in mind that you cannot set a Maps Extent to be outside its FullExtent. If
you are setting the Map.Extent properties e.g. ,
Set Map.Extent = Rectangle)
you should be sure that the Left, Right, Top and Bottom properties of your Rectangle are
within the Maps FullExtent. If at least one of the properties lies outside of the FullExtent,
then the Map.Extent change will not be successful, and none of the Map.Extent.Left,
Map.Extent.Right, Map.Extent.Top, or Map.Extent.Bottom will change.

See Also Rectangle Object

Example The following example uses the Extent property to set what portion of the Map is visible.
When you run the code, the ScaleRectangle method scales the Rectangle that defines the
Extent of the Map and the code resets the Extent accordingly. To try this example, paste the
code into the Declarations section of a form containing a CommandButton named Command1
and a Map named Map1 that contains at least one MapLayer or ImageLayer. Press F5 and then
click Command1.
Option Explicit

Private Sub Command1_Click()

Dim oRect As MapObjects2.Rectangle


Set oRect = Map1.Extent
oRect.ScaleRectangle (0.25)
Map1.Extent = oRect

End Sub

Factor Property
Applies To Unit Object

Description Sets or returns a value that specifies the conversion Factor between meters and the Unit
specified by the Type property. For example, the Foot Unit has a factor of 0.3048.

Syntax object.Factor [= value ]

ProgrammersReference.pmd 194 10/28/2004, 10:00 AM


MapObjects Programmers Reference 195

The Factor property syntax has these parts:

Part Description

object An object expression that evaluates to a Unit object.

value A numeric expression that specifies the conversion Factor.

See Also Spheroid Object

Example This example uses the factor property of different unit objects to build a chart. To try this
example, paste the following code into the Decalrations section of a new project, which
contains an MS Chart control. Press F5 to see a bar-chart displaying the different Factors of
the pre-defined Unit objects. Try changing the Maximum Y Axis value of the Chart to see
more detail.
Option Explicit

Private Sub Command1_Click()


MSChart1.Plot.Axis(VtChAxisIdY, 0).ValueScale.Maximum = Text1.Text
MSChart1.Refresh
End Sub

Private Sub Form_Load()

Dim unitObjs As New MapObjects2.Strings


Dim aUnit As Variant
Dim i As Integer
Dim arrChart(1 To 30, 1 To 2) As String

Build a collection of Unit names and factors


unitObjs.PopulateWithUnits
For i = 0 To unitObjs.Count - 1
Dim theUnit As New MapObjects2.Unit
theUnit.Type = stripProj(unitObjs(i))
arrChart(i + 1, 1) = theUnit.Name
arrChart(i + 1, 2) = theUnit.factor
Next i

Put data into chart


Dim j As Integer
With MSChart1
.Repaint = True
.RowCount = 1
.RowLabel = Units
.ColumnCount = unitObjs.Count

ProgrammersReference.pmd 195 10/28/2004, 10:00 AM


196 MapObjects Programmers Reference

.ColumnLabelCount = unitObjs.Count
.ShowLegend = False
.Plot.Axis(VtChAxisIdY).AxisScale.Type = VtChScaleTypeLinear
For j = 0 To unitObjs.Count - 1
.Column = j + 1
.Data = arrChart(j + 1, 2)
.ColumnLabel = arrChart(j + 1, 1)
Next j
.ShowLegend = True
End With
End Sub

Function stripProj(theProjection As String) As Variant


Get position of open bracket
Dim openB As Integer
openB = InStr(theProjection, [)
stripProj = Left(Right(theProjection, Len(theProjection) - openB), _
Len(theProjection) - openB - 1)
End Function

FeatureRouteIDField Property
Applies To EventRenderer Object

Description Returns or sets the FeatureRouteIDField property of the EventRenderer object.

Syntax object. FeatureRouteIDField [= fieldname]

The FeatureRouteIDField property syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

value A string object evaluating to the Field property of the EventTable of an


EventRenderer which defines the route ID field.

Remarks The FeatureRouteIDField property is used to specify which Field in the MapLayers
GeoDataset contains route ID information. The EventRouteIDField and
FeatureRouteIDField should contain similar values.

If the FeatureRouteIDField property contains a value which does not match with any value in
the EventRouteIDField, the event will be rendered with the DefaultSymbol if the
UseDefault property is True.

ProgrammersReference.pmd 196 10/28/2004, 10:00 AM


MapObjects Programmers Reference 197

See Also StartMeasureField Property, EventRouteIDField Property, EndMeasureField Property.

Example See EventRenderer Object

Field Object
A Field object represents a column of data within a Recordset with a common data type and a
common set of properties. Each Field has a Name, which is the default property for a Field
object. The Type property returns a value representing what type of data the field contains:
string, long, double, Boolean, date, empty, point, line, and polygon.

You can return the contents of a Field as a Variant for a particular Record with the Value
property or return the value of the Field, regardless of its type, as a String with ValueAsString
property.

Remarks To distinguish a MapObjects Field from a Visual Basic Field, fully qualify the class name in
declarations, for example:
Dim fld as MapObjects2.Field

Properties

Name Value ValueAsString

Type

See Also Fields Collection, FieldType Constants, Recordset Object

Field Property
Applies To ChartRenderer Object, ClassBreaksRenderer Object, DotDensityRenderer Object,
LabelPlacer Object, LabelRenderer Object, ValueMapRenderer Object

Description Returns or sets a field which is used by a MapLayers Renderer.

Syntax For a ClassBreaksRenderer, DotDensityRenderer, LabelPlacer, LabelRenderer or


ValueMapRenderer Object

object.Field [= value]

The Field property syntax has these parts:

ProgrammersReference.pmd 197 10/28/2004, 10:00 AM


198 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A string expression that specifies a name of a field in the Recordset of the
MapLayer on which the renderer is set. Each renderer in the Applies To list
makes use of the value of the specified field.

Syntax For a ChartRenderer Object

object.Field (index) [= value]

The Field property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index An integer that specifies the position of a member of a group of Values.


Index must be a number from 0 to a number that is one less than the
ValueCount property of the EventRenderer, LabelPlacer or
ValueMapRenderer object.

value A string expression that evaluates to the required value for the renderer.

Remarks The Field property sets the Fields of the MapLayers Recordset which are used by the
renderer to determine how each feature in the MapLayer is displayed.

If object is a ClassBreaksRenderer object, the Field property contains an array of Fields,


each of which represents on bar in a bar chart, or one slice in a pie chart. Each string must
represent a field name that contains continuous numeric data.

See Also FieldType Property

Example This example demonstrates the use of the Field property in association with a
ClassBreaksRenderer object to create a graduated symbol map. To try this example, paste the
code into the Declarations section of a form containing a ComboBox named Combo1 and a
Map named Map1 that has a MapLayer that represents point features. Press F5 and then select
a numeric field.
Option Explicit

Private Sub Combo1_Click()


Dim i As Integer
Dim oStats As MapObjects2.Statistics
Dim oRenderer As New MapObjects2.ClassBreaksRenderer
Dim sFieldName As String

ProgrammersReference.pmd 198 10/28/2004, 10:00 AM


MapObjects Programmers Reference 199

If Combo1.ListIndex <> -1 Then


sFieldName = Combo1.List(Combo1.ListIndex)
Set oStats = Map1.Layers(0).Records.CalculateStatistics(sFieldName)

With oRenderer
.Field = sFieldName
.SymbolType = moPointSymbol
.BreakCount = 2
For i = 0 To oRenderer.BreakCount
.Symbol(i).Style = moCircleMarker
.Symbol(i).Color = moRed
Next i
.Break(0) = oStats.Mean
.Break(1) = oStats.Max - oStats.Mean * 0.5
.SizeSymbols 4, 18
End With

Map1.Layers(0).Renderer = oRenderer
Map1.Refresh
End If
End Sub

Private Sub Form_Load()


Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field

Set oRecset = Map1.Layers(0).Records


For Each oField In oRecset.Fields
If oField.Type < moString Then
Combo1.AddItem oField.name
End If
Next

Combo1.ListIndex = -1
Combo1.Text =
End Sub

FieldCount Property
Applies To ChartRenderer Object, TableDesc Object, Standardizer Object

ProgrammersReference.pmd 199 10/28/2004, 10:00 AM


200 MapObjects Programmers Reference

Description Returns or sets the number of Field objects described in a TableDesc object, or returns the
number of FieldNames found in the standardization rule file associated with the
StandardizingRules or IntersectionStandardizingRules properties of the Standardizer
object.

Syntax object.FieldCount [= value]

The FieldCount property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression that specifies the number of fields.

Remarks The number of FieldNames in the rule file set to the StandardizingRules property can be
different from the rule file set to the IntersectionStandardizingRules property. When a
regular address is standardized using the StandardizeAddress method, the
StandardizingRules will be used. When a street intersection address is standardized, the
IntersectionStandardizingRules will then be used. The FieldCount value changes at run
time depending on what addresses are assigned to the StandardizeAddress method.

See Also Recordset Object, Field Object, FieldName Property, FieldValue Property

Example See AddGeoDataset Method or StandardizeAddress Method

FieldLength Property
Applies To TableDesc Object

Description Returns or sets the field length of a string or character Field described by a TableDesc object
associated with a Recordset.

Syntax object.FieldLength( index) [= value]

The FieldLength property syntax has these parts:

Part Description

object An object expression that evaluates to a TableDesc.

index A numeric expression that specifies the relative position of a member of the
group of FieldLength values associated with the TableDesc object. Index
must be a number from 0 to a number that is one less than the value of the
TableDesc objects FieldCount property.

ProgrammersReference.pmd 200 10/28/2004, 10:00 AM


MapObjects Programmers Reference 201

value A numeric expression that specifies the length of a string or character Field
in a Recordset.

Remarks For character data, the FieldLength does not include the null termination byte. Note that the
length of a column may be different than the number of bytes required to store the data on the
data source.

Note also that dBASE files (.dbf) limit field names to 10 characters. Fields with longer names
will be truncated.

See Also Recordset Object, Field Object

Example See AddGeoDataset Method

FieldName Property
Applies To TableDesc Object, Standardizer Object

Description Returns or sets a user-defined name for a Field described by a TableDesc object associated
with a Recordset, or returns the name of the match key field found in the standardization rule
file associated with the StandardizingRules or IntersectionStandardizingRules properties
of the Standardizer object.

Syntax object.FieldName( index) [= value]

The FieldName property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index A numeric expression that specifies the relative position of a member of the
group of FieldName values associated with the TableDesc or Standardizer
object. Index must be a number from 0 to a number that is one less than the
value of the TableDesc or Standardizer objects FieldCount property.

value A string expression that specifies the name of the Field in a Recordset.

Remarks For Standardizer objects, the field names are associated with the standardization rule files.
Each name is a unique two letter word such as HN. They were defined in the standardization
rule .dct file. By convention, HN stands for house number and SN for street name.

See Also Recordset Object, Field Object, FieldCount Property, FieldValue Property

Example See AddGeoDataset Method, StandardizeAddress Method

ProgrammersReference.pmd 201 10/28/2004, 10:00 AM


202 MapObjects Programmers Reference

FieldPrecision Property
Applies To TableDesc Object

Description Returns or sets the maximum number of digits used by the data type of a Field described by a
TableDesc object associated with a Recordset.

Syntax object.FieldPrecision( index) [= value]

The FieldPrecision property syntax has these parts:

Part Description

object An object expression that evaluates to a TableDesc.

index A numeric expression that specifies the relative position of a member of the
group of FieldPrecision values associated with the TableDesc object. Index
must be a number from 0 to a number that is one less than the value of the
TableDesc objects FieldCount property.

value A numeric expression that specifies the numeric precision of a Field in a


Recordset.

Remarks The precision of a numeric Field refers to the maximum number of digits used by its data type.
The precision of a nonnumeric field generally refers to either the maximum length or the
defined length of the field. The maximum FieldPrecision allowable is 19.

See Also Recordset Object, Field Object, FieldType Constants

Example See AddGeoDataset Method

Fields Collection
A Fields object contains a collection of each Field object in a Recordset object. To access a
particular Field in the collection, use the default property, Item, for example:
aString = Records.Fields.Item(Name).ValueAsString
or,
aString = Records.Fields(Name).ValueAsString
Remarks To distinguish a MapObjects Fields collection from a Visual Basic Fields collection, fully
qualify the class name, for example:
Dim flds as MapObjects2.Fields

ProgrammersReference.pmd 202 10/28/2004, 10:00 AM


MapObjects Programmers Reference 203

See Also FieldType Constants, Recordset Object

Fields Property
Applies To Recordset Object

Description Returns all stored Field objects of the Fields collection of a Recordset.

Syntax object.Fields

The Fields property syntax has these parts:

Part Description

object An object expression that evaluates to a Recordset object.

See Also Field Object

Example This example uses the Fields Property to list the names of the fields associated with a
MapLayers Recordset. To try this example, paste the code into the Declarations section of a
form containing a CommandButton named Command1, a ListBox named List1, and a Map
named Map1 that has at least one MapLayer. Press F5 and then click Command1 to see the list
of field names.
Option Explicit

Private Sub Command1_Click()


Dim recset As MapObjects2.Recordset
Dim f As MapObjects2.Field
Set recset = Map1.Layers(0).Records
For Each f In recset.Fields
List1.AddItem f.Name
Next f
End Sub

FieldScale Property
Applies To TableDesc Object

Description Returns or sets the maximum number of digits to the right of the decimal point of a numeric
Field described by a TableDesc object associated with a Recordset.

Syntax object.FieldScale( index) [= value]

ProgrammersReference.pmd 203 10/28/2004, 10:00 AM


204 MapObjects Programmers Reference

The FieldScale property syntax has these parts:

Part Description

object An object expression that evaluates to a TableDesc.

index A numeric expression that specifies the relative position of a member of the
group of FieldScale values associated with the TableDesc object. Index
must be a number from 0 to a number that is one less than the value of the
TableDesc objects FieldCount property.

value A numeric expression that specifies the maximum number of digits to the
right of the decimal point of a numeric Field in a Recordset.

Remarks For approximate floating point number fields, the FieldScale is undefined, since the number of
digits to the right of the decimal point is not fixed. For the SQL_DECIMAL and
SQL_NUMERIC data types, the maximum scale is generally the same as the maximum
precision. However, some data sources impose a separate limit on the maximum scale.

See Also Recordset Object, Field Object

Example See AddGeoDataset Method

FieldType Constants
MapObjects defines the following type constants for use with the Field objects Type property
and the TableDesc objects FieldType property

Constant Value Description

moNone 0 None

moLong 3 Long

moDouble 5 Double

moDate 7 Date

moString 8 String

moBoolean 11 Boolean

moPoint 21 Point

moLine 22 Line

ProgrammersReference.pmd 204 10/28/2004, 10:00 AM


MapObjects Programmers Reference 205

moPolygon 23 Polygon

moPoints 24 Points collection

See Also Field Object

FieldType Property
Applies To TableDesc Object

Description Returns or sets the type of Field described by a TableDesc object associated with a
Recordset.

Syntax object.FieldType( index) [= value]

The FieldType property syntax has these parts:

Part Description

object An object expression that evaluates to a TableDesc.

index A numeric expression that specifies the relative position of a member of the
group of FieldType values associated with the TableDesc object. Index
must be a number from 0 to a number that is one less than the value of the
TableDesc objects FieldCount property.

value An integer or constant that indicates an operational or data type, as de-


scribed in Settings.

Settings The settings for value are FieldTypeConstants.

See Also Recordset Object, Field Object

Example This example uses the MapObjects FieldTypeConstants, and creates a list of details from a
MapLayers Recordset. To try this example, paste the code into the Declarations section of a
form that contains a ListBox named List1, and change the path of the database, and the
FindGeoDataset method. Then press F5.
Option Explicit

Private Sub Form_Load()

Dim dc As New MapObjects2.DataConnection


Change the line below to point to a folder containing shapefiles
dc.Database = App.Path & ...Files

ProgrammersReference.pmd 205 10/28/2004, 10:00 AM


206 MapObjects Programmers Reference

dc.Connect

If Not dc.Connected Then


MsgBox Could not connect to database, vbOKOnly, Connect Error
Else

Dim layer As New MapObjects2.MapLayer


Change the line below to a name of a shapefile
layer.GeoDataset = dc.FindGeoDataset(states)
List1.Clear

Dim i As Integer
Dim field As MapObjects2.field
Dim fldString As String

List1.AddItem Field Name & Chr(9) & Field Type & Chr(9) & _
Constant

For Each field In layer.Records.Fields


Dim tblDesc As MapObjects2.TableDesc
Set tblDesc = layer.Records.TableDesc
For i = 0 To tblDesc.FieldCount - 1
fldString = tblDesc.FieldName(i)
If Len(fldString) < 7 Then
fldString = fldString & Chr(9)
End If
fldString = fldString & Chr(9) & tblDesc.FieldType(i)
Select Case tblDesc.FieldType(i)
Case moBoolean
fldString = fldString & Chr(9) & Chr(9) & Boolean
Case moDate
fldString = fldString & Chr(9) & Chr(9) & Date
Case moDouble
fldString = fldString & Chr(9) & Chr(9) & Double
Case moLine
fldString = fldString & Chr(9) & Chr(9) & Line
Case moLong
fldString = fldString & Chr(9) & Chr(9) & Long
Case moNone
fldString = fldString & Chr(9) & Chr(9) & None
Case moPoint
fldString = fldString & Chr(9) & Chr(9) & Point

ProgrammersReference.pmd 206 10/28/2004, 10:00 AM


MapObjects Programmers Reference 207

Case moPoints
fldString = fldString & Chr(9) & Chr(9) & Points
Case moPolygon
fldString = fldString & Chr(9) & Chr(9) & Polygon
Case moString
fldString = fldString & Chr(9) & Chr(9) & String
End Select
List1.AddItem fldString
Next i
End If

End Sub

FieldValue Property
Applies To Standardizer Object

Description Returns or sets the values in the FieldName properties of a Standardizer, after an address is
standardized.

Syntax object.FieldValue (FieldName) [ = value]

The FieldValue property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

FieldName A string expression that specifies the Standardizers FieldName, as defined


in the .dct standardization file.

value A string expression that specifies the value in the field name.

Remarks The Standardizer objects FieldName property returns the names of the match key fields, the
FieldValue returns a standardized values of an address for each FieldName. When searching
a Geocoder objects StreetTable, the FieldName is used as a search key. FieldName values
can be read at run time from a valid Standardizer, or found in the appropriate .dct file.

You can override the values returned by the Standardizer by setting new values to the match
key fields if you wish to.

For example, the StandardizeAddress method of the Standardizer object will only parse an
address 270 North Main Avenue into the HN, PD, PT, SN, ST, and SD, as no zip code is

ProgrammersReference.pmd 207 10/28/2004, 10:00 AM


208 MapObjects Programmers Reference

present in the address. If you wish the address to contain a zone, you would manually specify
the value for a field named ZN using the objects FieldValue property, for example,
stan.FieldValue(ZN) = 53702
Similarly, you can override the FieldValue of existing FieldNames which are the result of
standardization by setting a new value to the field. For example, the Standardizer may return
Ave for the street type (ST) field. You can change it to Av if you prefer by setting the new
value to the FieldValue (ST) property.

See Also FieldCount Property, FieldName Property

Example See StandardizeAddress Method

File Property
Applies To ImageLayer Object

Description Returns or sets the path and filename of an image file displayed by an ImageLayer.

Syntax object.File [= pathname]

The File property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

pathname A string expression that specifies the path and filename associated with an
ImageLayer.

See Also Valid Property

Example This example uses the File Property to specify the file associated with an ImageLayer. In this
case, the code displays the Common FileDialog to set the File associated with the image to
add. To try this example, paste the code into the Declarations section of a form containing a
CommonDialog Control and a Map named Map1 that has at least one MapLayer located in the
same geographic coordinate space as the image to be added. Press F5, then specify the image
to add. Make sure that the image has an associated world file.
Option Explicit

Private Sub Form_Load()


Dim iLayer As New ImageLayer

CommonDialog1.Filter = Windows Bitmap (*.bmp)|*.bmp|TIFF _

ProgrammersReference.pmd 208 10/28/2004, 10:00 AM


MapObjects Programmers Reference 209

Image(*.tif)|*.tif
CommonDialog1.FilterIndex = 1
CommonDialog1.ShowOpen

If CommonDialog1.FileName <> Then


iLayer.File = CommonDialog1.FileName

move the existing layer to the top


If Map1.Layers.Add(iLayer) Then
Map1.Layers.MoveToTop 1
End If

End If
End Sub

FillStyle Constants
MapObjects defines the following constants for use with fill symbols.

Constant Value Description

moSolidFill 0 Solid

moTransparentFill 1 Transparent

moHorizontalFill 2 Horizontal

moVerticalFill 3 Vertical

moUpwardDiagonalFill 4 Upward Diagonal

moDownwardDiagonalFill 5 Downward Diagonal

moCrossFill 6 Cross

moDiagonalCrossFill 7 Diagonal Cross

moLightGrayFill 8 Light Gray Fill

moGrayFill 9 Gray Fill

moDarkGrayFill 10 DarkGray Fill

See Also Polygon Object, Symbol Object

ProgrammersReference.pmd 209 10/28/2004, 10:00 AM


210 MapObjects Programmers Reference

FilterExpression Property
Applies To MapLayer Object

Description This property sets or returns an SQL statement to limit the amount of information that is
returned from an SDE layer.

Syntax object.FilterExpression [= filter ]

The FilterExpression property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

filter A string expression that specifies the filter expression to be used with the
MapLayer.

Remarks FilterExpression is intended for use with SDE, where much of the processing may be carried
out on the server, although the filter will also work with MapLayers based on shapefiles. It
can be used to limit the amount of information being returned from the SDE server, improving
the performance of your application.

When using a FilterExpression, the Count property may no longer be used on the MapLayer
objects Recordset, as there is no header information available to determine the correct record
Count. In these cases, to obtain the correct Count of the Recordset, a Statistics object should
be created from the Recordset, and the number of records taken from the Count property of
this Statistics object.

See Also FilterFields Property, FilterOperator Property, FilterOrder Property

Example This example sets the FilterExpression property to limit which features of the MapLayer are
visible. The FilterFields property is used to limit the fields which are available to perform the
FilterExpression on. To try this example, paste the code into the Declarations section of a form
containing three OptionButtons named Option1, Option2, and Option3, a ListBox named
List1, a TextBox named Text1, a CommandButton named Command1 and two CheckBoxes
named Check1 and Check2. Ensure that the properties of the DataConnection are set correctly
for your SDE instance, and that a points layer is available. Now press F5. Selecting and
deselecting the Filter Strings checkbox will limit the fields listed in the ListBox to non-string
types. Click on a Field, select an operator, and enter a value in the TextBox, then press the
CommandButton.
Option Explicit

Dim dc As New MapObjects2.DataConnection

ProgrammersReference.pmd 210 10/28/2004, 10:00 AM


MapObjects Programmers Reference 211

Dim useFields As New MapObjects2.Strings

Private Sub Check1_Click()


With Map1.Layers(0)
If Check1 Then
.FilterOrder 3
Else
.FilterOrder 1
End If
End With
Map1.Refresh
End Sub

Private Sub Check2_Click()


Screen.MousePointer = vbHourglass
If Check2 Then
Set Map1.Layers(0).FilterFields = useFields
Else
Dim noStrings As New MapObjects2.Strings
Set Map1.Layers(0).FilterFields = noStrings
End If

Map1.Refresh
listFields Map1.Layers(0).Records
Screen.MousePointer = vbDefault
End Sub

Private Sub Command1_Click()

Dim exp As String

exp = List1.List(List1.ListIndex)
If Option1 Then
exp = exp & Option1.Caption
ElseIf Option2 Then
exp = exp & Option2.Caption
ElseIf Option3 Then
exp = exp & Option3.Caption
End If
exp = exp & Text1.Text

Map1.Layers(0).FilterExpression = exp
Map1.Refresh
End Sub

ProgrammersReference.pmd 211 10/28/2004, 10:00 AM


212 MapObjects Programmers Reference

Private Sub Form_Load()

The values for Server, User, Database, and Password will


need to be changed for your particular sde connection
dc.Server = server
dc.User = user
dc.Password = userpass
dc.Database = sde1

Check1.Caption = Allow SDE to optimize Filter Order


Check2.Caption = Filter String Fields
Check2.Value = 0
Option1.Caption = >
Option2.Caption = =
Option3.Caption = <
Text1.Text =
Command1.Caption = Filter Layer

If dc.Connect Then
Dim gs As Object
For Each gs In dc.GeoDatasets

Here, the first Point dataset found is added to the map as a


layer.
Dim dataName As String
Dim i As Integer
i = InStrL(gs.Name, .)
dataName = Right(gs.Name, Len(gs.Name) - i)

If dataName = Points Then


Dim layer As New MapObjects2.MapLayer
Dim rs As MapObjects2.Recordset
Dim f As MapObjects2.field
layer.GeoDataset = gs

Set rs = layer.Records
List is created of all Fields, for use in FilterExpression
listFields rs
All strings fields are added to a list for us in FilterFields
filterStrings rs

Map1.Layers.Add layer
Exit For

ProgrammersReference.pmd 212 10/28/2004, 10:00 AM


MapObjects Programmers Reference 213

End If
Next gs
Else
MsgBox Connection Error
End If

End Sub

Private Sub listFields(recs As MapObjects2.Recordset)


List1.Clear
Dim field As Object
For Each field In recs.Fields
Put all numeric fields in the ListBox
If field.Type = 5 Then
List1.AddItem field.Name
End If
Next field
End Sub

Private Sub filterStrings(recs As MapObjects2.Recordset)


Dim field As Object
For Each field In recs.Fields
Put all non-string fields in a strings collection which
may be used to set FilterFields property
If field.Type <> 8 Then
useFields.Add field.Name
End If
Next field
End Sub

Returns the character position of the last occurrence


of srchString in inString.
Private Function InStrL(inString As String, srchString As String) _
As Integer
Dim iLastPos As Integer Set to 0 on initialization

Check srchString a 0-length string will match every time


If Len(srchString) Then
Set iLastPos to the last matching position
Dim iCurPos As Integer
Do
iLastPos = iCurPos
iCurPos = InStr(iCurPos + 1, inString, srchString, vbTextCompare)

ProgrammersReference.pmd 213 10/28/2004, 10:00 AM


214 MapObjects Programmers Reference

Loop Until iCurPos = 0


End If

InStrL = iLastPos
End Function

FilterFields Property
Applies To MapLayer Object

Description This property returns or sets a Strings object that contains the name of a number of Fields.
When this property is set, only the Fields in the Strings object will be returned from SDE.

Syntax object.FilterFields [=fields ]

The FilterFields property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

fields A object expression that evaluates to a Strings object, listing the Fields to
filter on for the MapLayer.

Remarks FilterFields only works with a SDE layers. It can be used to limit the amount of information
being returned from the SDE server, improving the performance of your application.

See Also FilterExpression Property, FilterOperator Property, FilterOrder Property, Strings Object

Example See FilterExpression Property

FilterOperator Property
Applies To MapLayer Object

Description This property works in conjunction with the FilterShape property, and returns or sets the type
of FilterShape operation used in the filter.

Syntax object.FilterOperator [=opType ]

The FilterOperator property syntax has these parts:

ProgrammersReference.pmd 214 10/28/2004, 10:00 AM


MapObjects Programmers Reference 215

Part Description

object An object expression that evaluates to an object in the Applies To list.

opType One of the SearchMethodConstants listed in settings below

Settings The settings for opType are SearchMethodConstants

Remarks FilterOperator and FilterShape are intended for use with SDE, where much of the process-
ing may be carried out on the server, although the filter will also work with MapLayers based
on shapefiles.

The default FilterOperator is moExtentOverlap

See Also SearchMethod Constants, FilterFields Property, FilterExpression Property, FilterOrder


Property

Example This example sets the FilterShape and FilterOperator properties to limit which features of the
MapLayer are visible. To try this example, paste the code into the Declarations section of a
form containing a Map named Map1 and four OptionButtons named Option1, Option2,
Option3 and Option4. Ensure that the properties of the DataConnection are set correctly for
your SDE instance. Press F5, and track a polygon onto the map. Try clicking different
OptionButtons to use different FilterOperator constants in the Filter.
Option Explicit

Dim poly As New MapObjects2.Polygon


Dim operator As Integer
Dim dc As New MapObjects2.DataConnection

Private Sub Form_Load()

The values for Server, User, Database, and Password will


need to be changed for your particular sde connection
dc.Server = server
dc.User = user
dc.Password = password
dc.Database = sde

If dc.Connect Then
Dim gs As Object
For Each gs In dc.GeoDatasets
Here, the first Polygon dataset found is added to the map as _
a layer.
Dim dataName As String
Dim i As Integer

ProgrammersReference.pmd 215 10/28/2004, 10:00 AM


216 MapObjects Programmers Reference

i = InStrL(gs.Name, .)
dataName = Right(gs.Name, Len(gs.Name) - i)
If dataName = Points Then
Dim layer As New MapObjects2.MapLayer
layer.GeoDataset = gs
Map1.Layers.Add layer
Exit For
End If
Next gs
Else
MsgBox Connection Error
End If

Option1.Value = True
Option1.Caption = Method: Area Intersect
Option2.Caption = Method: Contained By
Option3.Caption = Method: Containing
Option4.Caption = Method: Extent Overlap
End Sub

Private Function InStrL(inString As String, srchString As String) _


As Integer
Dim iLastPos As Integer Set to 0 on initialization

Check srchString a 0-length string will match every time


If Len(srchString) Then
Set iLastPos to the last matching position
Dim iCurPos As Integer
Do
iLastPos = iCurPos
iCurPos = InStr(iCurPos + 1, inString, srchString, vbTextCompare)
Loop Until iCurPos = 0
End If

InStrL = iLastPos
End Function

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)

Set poly = Map1.TrackPolygon


If Not poly Is Nothing Then
Set Map1.Layers(0).FilterShape = poly
End If

ProgrammersReference.pmd 216 10/28/2004, 10:00 AM


MapObjects Programmers Reference 217

If Option1.Value Then
operator = 6
ElseIf Option2.Value Then
operator = 8
ElseIf Option3.Value Then
operator = 9
ElseIf Option4.Value Then
operator = 0
End If

Map1.Layers(0).FilterOperator = operator
Map1.Refresh

End Sub

FilterOrder Constants
MapObjects defines the following constants for defining the filter order when defining filters
on MapLayers.

Constant Value Description

moAttributeFirst 1 Applies the FilterExpression first

moShapeFirst 2 Applies the FilterShape first

moOptimize 3 Allows SDE to optimize the filter order

See Also MapLayer Object, FilterOrder Property, FilterExpression Property, FilterShape Property

FilterOrder Property
Applies To MapLayer Object

Description This property returns or sets the order that filter operations are carried out by SDE.

Syntax object.FilterOrder [= order]

The FilterOrder property syntax has these parts:

ProgrammersReference.pmd 217 10/28/2004, 10:00 AM


218 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

order One of the FilterOrder constants listed in Settings below

Settings The settings for order are FilterOrderConstants.

Remarks This property will only affect a MapLayer that is an SDE layer with more than one filter set
on it. You should set the property to optimize the filter performance. For example, if your layer
has a FilterExpression set which eliminates the majority of the layer, then you can ensure this
expression is applied before the FilterShape is applied, by using the moAttributeFirst
FilterOrder Constant.

See Also FilterFields Property, FilterExpression Property, FilterOperator Property

Example See FilterExpression Property

FilterShape Property
Applies To MapLayer Object

Description This property returns or sets the FilterShape on a MapLayer.

Syntax object.FilterShape [= filterShape]

The FilterShape property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

filterShape A variant expression that specifies a shape to use as a filter for the
MapLayer

Remarks When setting a FilterShape on a MapLayer, you should first set the FilterOperator to the
appropriate SearchMethodConstants.

FilterOperator and FilterShape are intended for use with SDE, where much of the process-
ing may be carried out on the server, although the filter will also work with MapLayers based
on shapefiles. It can be used to limit the amount of information being returned from the SDE
server, improving the performance of your application.

If your MapLayer contains features with Z values, you can use a three-dimensional Rect-
angle as your filter shape. Features are filtered based on their Z coordinates, in addition to

ProgrammersReference.pmd 218 10/28/2004, 10:00 AM


MapObjects Programmers Reference 219

their X and Y coordinates. Note that moExtentOverlap is the only SearchMethodConstants


that allows three-dimensional filtering.

See Also Valid Property, FilterOperator Property

Example See FilterOperator Property

Find Method
Applies To Strings Collection

Description Returns the index of a string in a Strings collection.

Syntax Set variable = object.Find ( itemName, [ startpos])

The Find method syntax has these parts:

Part Description

variable A variable declared as an Integer or Long that evaluates to the index


position of itemName in the Strings collection.

object An object expression that evaluates to an object in the Applies To list.

itemName A string expression whose index position in the collection to return.

startpos An optional numeric expression that indicates the index position from which
to start the search. If startpos is omitted, Find starts at the first index
position.

Remarks If itemName is not in the Strings collection or no more instances of itemName are in the
collection from startpos to the last member of the collection, Find returns -1.

You can use startpos to find the next instance of itemName in the collection.

See Also Add Method

Example This example uses the Find method to count how many instances of a string are in a Strings
collection. Find returns the index position of the string and may be used for a variety of
purposes in MapObjects, perhaps most usefully for determining the position of an argument.
To try this example, paste the code into the Declarations section of a Form that contains a Map
named Map1. Press F5.
Option Explicit

Private Sub Form_Load()

ProgrammersReference.pmd 219 10/28/2004, 10:00 AM


220 MapObjects Programmers Reference

Dim sMyStrs As New MapObjects2.Strings


Dim iNumFound As Integer
Dim idx As Integer

With sMyStrs
.Unique = False allows multiple instances to be added

.Add pears
.Add apples
.Add peaches
.Add bananas
.Add apples
.Add guavas
.Add plums
.Add apricots
End With

iNumFound = 0
idx = sMyStrs.Find(apples) start at the beginning of the
collection

Do While idx <> -1


iNumFound = iNumFound + 1
idx = sMyStrs.Find(apples, idx + 1)
Loop

MsgBox Found & iNumFound & instances of the string in _


the collection
End Sub

FindAllPlaceNames Method
Applies To PlaceLocator Object

Description Finds all place names that begin with the specified characters and returns them in upper case
as members of a Strings collection.

See Also FindApproximateMatches Method, Locate Method, PlaceNameTable Property

Syntax Set variable = object.FindAllPlaceNames( prefix)

The FindAllPlaceNames method syntax has these parts:

ProgrammersReference.pmd 220 10/28/2004, 10:00 AM


MapObjects Programmers Reference 221

Part Description

variable An object expression that evaluates to a Strings collection.

object An object expression that evaluates to an object in the Applies To list.

prefix A string expression that specifies the first characters in the place names to
search for.

Remarks You may wish to use the FindAllPlaceNames method if the first characters of a place name
are known but the remainder of the names spelling is unsure, and the
FindApproximateMatches method does not return any successful matches.

Passing an empty string to FindAllPlaceNames will return an empty Strings collection.

Example This example uses the Locate method and the FindAllPlaceNames method to locate place
names. You will need to change the GeoDataset name, the field name on which to build the
index, and the path for the DataConnection to point to the correct locations and names for your
data. To try this example, paste the code into the Declarations section of a form that contains a
Map with a MapLayer containing a place name field, a TextBox named Text1, a
CommandButton named Command1, a CheckBox named Check1, and a ListBox named List1
(set the Multi-Select property to 2). Press F5 and try typing an exact placename, or the first
few characters, in Text1 and press the CommandButton. Red point symbols are drawn at the
matched place locations. Matches display in the ListBox; double-click on a name in the list to
flash it on the map, or select several names from the list and then double-click.
Option Explicit
Dim pl As New Mapobjects2.PlaceLocator
Dim pts As Mapobjects2.Points
Dim gdname As String
Dim fldname As String
Public places As New Collection

Private Sub Command1_Click()


Dim p As Mapobjects2.Point
Dim strs As New Mapobjects2.Strings
Dim i As Integer
Dim s As Variant
Set places = Nothing

List1.Clear
attempt an exact match of the place name
Set pts = pl.Locate(Text1.Text)

If weve found one or many exact matches, add then to the List
If pts.Count > 0 Then

ProgrammersReference.pmd 221 10/28/2004, 10:00 AM


222 MapObjects Programmers Reference

For Each p In pts


places.Add p
Next p
strs.Add Text1.Text
Else
otherwise, find all places starting with text specified
If Check1.Value = 0 Then
Set strs = pl.FindAllPlaceNames(Text1.Text)
Else
or find approximate matches for text entered
Set strs = pl.FindApproximateMatches(Text1.Text)
If strs.Count = 0 Then
MsgBox No approximate matches found, vbInformation
End If
End If

If strs.Count > 0 Then


Set places = Nothing
List1.Clear
For i = 0 To strs.Count - 1
Set pts = pl.Locate(strs(i))
For Each p In pts
places.Add p
Next p
Next i
End If
End If

populate the list with place names


For Each s In strs
List1.AddItem s
Next s

draw place name locations


Map1.TrackingLayer.Refresh True

End Sub

Private Sub Form_Load()

Dim dc As New DataConnection


gdname = counties
fldname = name

ProgrammersReference.pmd 222 10/28/2004, 10:00 AM


MapObjects Programmers Reference 223

Change the paths below to ones appropriate for your data


dc.Database = C:\Program Files\ESRI\MapObjects2\Samples\Data\USA
dc.Connect
Set pl.PlaceNameTable = dc.FindGeoDataset(gdname)

If Not pl.BuildIndex(fldname, False) Then


MsgBox Couldnt build index
End If

Dim layer As New MapLayer


layer.GeoDataset = dc.FindGeoDataset(gdname)
Map1.Layers.Add layer
layer.Symbol.Color = moPaleYellow

Command1.Caption = Locate
Text1.Text =
Check1.Caption = Approximate match
Check1.Value = 0

End Sub

Private Sub List1_Click()

Dim result As Mapobjects2.Recordset

If List1.ListCount > 1 Then wild card returned multiple matches


Set result = Map1.Layers(0).SearchShape _
(places(List1.ListIndex + 1), moPointInPolygon, )
Map1.FlashShape result.Fields(shape).Value, 4

Else exact match or multiple places with same name


Dim i As Integer

For i = 1 To places.Count - 1
Set result = Map1.Layers(0).SearchShape(places(i), _
moPointInPolygon, )
Map1.FlashShape result.Fields(shape).Value, 4
If places.Count > 1 Then
Dim res As Integer
res = MsgBox(Flash another place?, vbYesNo, MapObjects)
If res = vbNo Then
Exit For
End If
End If

ProgrammersReference.pmd 223 10/28/2004, 10:00 AM


224 MapObjects Programmers Reference

Next i

End If
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
If Not places Is Nothing Then
Call DrawPlaces(places)
End If
End Sub

Sub DrawPlaces(places As Collection)


Dim sym As New Mapobjects2.Symbol
Dim p As Mapobjects2.Point
sym.SymbolType = moPointSymbol
sym.Style = moCircleMarker
sym.Color = moRed
sym.Size = 7

For Each p In places


Map1.DrawShape p, sym
Next p
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
If Shift = vbShiftMask Then
Map1.Extent = Map1.FullExtent
Else
Map1.Extent = Map1.TrackRectangle
End If
End Sub

Private Sub Text1_Change()


List1.Clear
End Sub

Private Sub Text1_KeyDown(KeyCode As Integer, Shift As Integer)


If KeyCode = vbKeyReturn Then
Command1_Click
End If
End Sub

ProgrammersReference.pmd 224 10/28/2004, 10:00 AM


MapObjects Programmers Reference 225

FindApproximateMatches Method
Applies To PlaceLocator Object

Description Finds approximate matches for the specified name and returns the results in upper case as a
Strings collection.

Syntax Set variable = object.FindApproximateMatches( name)

The FindApproximateMatches method syntax has these parts:

Part Description

variable An object expression that evaluates to a Strings collection that contains the
results of the methods action.

object An object expression that evaluates to an object in the Applies To list.

name A string expression that specifies the street name or place name to find
approximate matches for.

See Also FindAllPlaceNames Method

Example See FindAllPlaceNames Method

FindArcInfoCoordinateSystem Method
Applies To DataConnection Object

Description Locates an ARC/INFO Coordinate System and creates either a GeoCoordSys or


ProjCoordSys object.

Syntax variable = object.FindArcInfoCoordinateSystem (name)

The FindArcInfoCoordinateSystem method syntax has these parts:

Part Description

variable A variable previously declared as an object.

object An object expression that evaluates to a DataConnection object.

name A string expression that evaluates to the name of an ARC/INFO projection


file.

ProgrammersReference.pmd 225 10/28/2004, 10:00 AM


226 MapObjects Programmers Reference

Remarks ARC/INFO stores information about a coverages coordinate system in a PRJ file within the
workspace directory. The file is an ASCII text file, and contains parameters describing the
projection, units and projection-specific parameters of the coordinate system. The file may
also contain optional parameters describing the datum, spheroid or z units of the coordinate
system (among others).

For example, a PRJ file may contain the following information:


Projection GEOGRAPHIC
Zunits NO
Units DD
Spheroid CLARKE1866
Xshift 0.000000000
Yshift 0.000000000
Parameters
Once set, the returned variable may be interrogated like any other GeoCoordSys or
ProjCoordSys. You can use the IsProjected property on the variable to discover which type
of coordinate system has been returned.

See Also FindCoordinateSystem Method

Example This example uses the FindArcInfoCoordinateSystem method. To try this example, paste the
code into the Declarations section of a form containing a DirListBox control Dir1, a
CommandButton named Command1 and a Label named Label1. Press F5 and then navigate
through the folders in the Directory list to a folder that contains a coverage with projection
information.
Option Explicit

Private Sub Command1_Click()

Dim path As String


Dim dc As New MapObjects2.DataConnection
Dim foundProj As Object

path = Dir1.path

dc.Database = path &


If Not dc.Connect Then
MsgBox Could not connect to database & Chr(13) & dc.ConnectError
Else
Label1.Caption =
Set foundProj = dc.FindArcInfoCoordinateSystem(prj.adf)
If foundProj Is Nothing Then
Label1.Caption = No projections found in current folder
Else

ProgrammersReference.pmd 226 10/28/2004, 10:00 AM


MapObjects Programmers Reference 227

Label1.Caption = Name: & foundProj.Name & vbNewLine & Type: _


& foundProj.Type
End If
End If
End Sub

Private Sub Form_Load()


Label1.Caption =
Command1.Caption = Find Arc/Info Coordinate System
End Sub

FindCoordinateSystem Method
Applies To DataConnection Object

Description Locates a coordinate system, and creates either a GeoCoordSys or ProjCoordSys object.

Syntax variable = object.FindCoordinateSystem name

The FindCoordinateSystem method syntax has these parts:

Part Description

variable A variable previously declared as an object.

object An object expression that evaluates to a DataConnection object.

name A string expression that evaluates to the name of a coordinate system (.prj)
file, situated in the DataConnections Database location.

Remarks Coordinate system information for a shapefile is stored in a separate file, in the same location
as the shapefile. The metadata file has the same file name as the shapefile, with a .prj exten-
sion. If the FindCoordinateSystem method finds a prj file of the specified name, the prj file
is read and a ProjCoordSys or GeoCoordSys object is created. To determine the type of
coordinate system that has been returned, you can check the IsProjected property of the
returned variable. If no coordinate system is found, the variable is not set.

See Also FindArcInfoCoordinateSystem Method

Example This example uses the FindCoordinateSystem method. To try this example, paste the code into
the Declarations section of a form containing a Common Dialog control named
CommonDialog1, a ListBox named List1 and CommandButton named Command1. Press F5,
click Command1, and then navigate through the folders in the Dialog Box to find a prj file.
Select the required prj file and press Open.

ProgrammersReference.pmd 227 10/28/2004, 10:00 AM


228 MapObjects Programmers Reference

Option Explicit

Private Sub Command1_Click()

CommonDialog1.ShowOpen

Dim path As String


Dim dc As New MapObjects2.DataConnection
Dim foundProj As Object

path = Left(CommonDialog1.FileName, Len(CommonDialog1.FileName) _


- Len(CommonDialog1.FileTitle) - 1)
Debug.Print path

dc.Database = path
If Not dc.Connect Then
MsgBox Could not connect to database & Chr(13) & dc.ConnectError
Else
List1.Clear
Set foundProj = dc.FindCoordinateSystem(CommonDialog1.FileTitle)
If foundProj Is Nothing Then
List1.AddItem No projections of that name found
Else
List1.AddItem foundProj.Name
List1.AddItem foundProj.Type
End If

End If
End Sub

Private Sub Form_Load()


CommonDialog1.Filter = ESRI Projection files|*.prj
End Sub

FindEvent Method
Applies To TrackingLayer Object

Description Finds a GeoEvent object on the TrackingLayer using its Tag property value

Syntax object.FindEvent (tag)

The FindEvent method syntax has these parts:

ProgrammersReference.pmd 228 10/28/2004, 10:00 AM


MapObjects Programmers Reference 229

Part Description

object An object expression that evaluates to a TrackingLayer object.

tag The tag value of the GeoEvent required

See Also RemoveEvent Method, AddEvent Method

FindGeoDataset Method
Applies To DataConnection Object

Description Locates a GeoDataset object by name.

Syntax Set variable = object.FindGeoDataset( name)

The FindGeoDataset method syntax has these parts:

Part Description

variable A variable that has been declared as a GeoDataset.

object An object expression that evaluates to an object in the Applies To list.

name A string expression that evaluates to a name of a GeoDataset.

Remarks If you call FindGeoDataset and the DataConnection is not connected, MapObjects will
automatically attempt to Connect first. However, it is recommended that the Connect method
is called first, to allow the application to handle potential connection errors. If no GeoDataset
is found, the variable is not set.

See Also GeoDataset Object

Example This example uses the DataConnection objects FindGeoDataset method to associate a
GeoDataset with a MapLayer. The code then adds the MapLayer to a Map. To try this ex-
ample, paste the code into the Declarations section of a form containing a CommonDialog
control, a CommandButton named Command1 and a Map named Map1. Press F5 and then
click Command1. In the Open dialog that displays, navigate to a folder that contains shapefiles
and select one.
Option Explicit

Private Sub Command1_Click()


Dim strFileTitle As String, sDataSetName As String
Dim sFileDirectory As String

ProgrammersReference.pmd 229 10/28/2004, 10:00 AM


230 MapObjects Programmers Reference

Dim dc As New MapObjects2.DataConnection


Dim lyr As New MapObjects2.MapLayer

CommonDialog1.Filter = Shapefiles (*.shp)|*.shp


CommonDialog1.ShowOpen

strFileTitle = CommonDialog1.FileTitle just the name with the _


shp extension

If strFileTitle <> Then

With CommonDialog1
sFileDirectory = Left$(.FileName, InStr(.FileName, .FileTitle) - 1)
End With

With dc
.Database = sFileDirectory the directory containing the
selected file

If .Connect Then
sDataSetName = Mid(strFileTitle, 1, Len(strFileTitle) - 4)
remove the extension
Set lyr.GeoDataset = dc.FindGeoDataset(sDataSetName)
Map1.Layers.Add lyr
Else
MsgBox Data Connection error # & dc.ConnectError, vbExclamation
End If
End With

End If

Set dc = Nothing
Set lyr = Nothing

End Sub

Fitted Property
Applies To TextSymbol Object

Description Returns or sets a value indicating whether to adjust the gap between characters of a
TextSymbol object so that it fits between two points of a Line.

ProgrammersReference.pmd 230 10/28/2004, 10:00 AM


MapObjects Programmers Reference 231

Syntax object.Fitted [= boolean]

The Fitted property syntax has these parts:

Part Description

object An object expression that evaluates to a TextSymbol object.

boolean A boolean expression specifying whether to adjust the gap between charac-
ters of a TextSymbol object so that it fits between two points of a Line, as
described in Settings.

Settings The settings for boolean are:

Setting Description

True MapObjects will adjust the gap between characters of the TextSymbol
object to fit it between a two-point Line specified by DrawText or the two-
point Line associated with the text drawn by a LabelRenderer.

False (Default) MapObjects will not adjust the gap between characters of the
TextSymbol object.

Remarks If the width of the character string is less than the distance between the points, MapObjects
will increase the gap between characters.

Fitted does not affect the height and width of the text. It only adjusts the gap between charac-
ters.

See Also LabelRenderer Object, FittedField Property

Example This example uses the Fitted property of the TextSymbol to control whether or not to adjust
the gap between characters of a text string positioned in relation to a two-point line. To try this
example, paste the code into the Declarations section of a form containing a CheckBox named
Check1 and a Map named Map1. Press F5 and then track a two-point line on the Map. Toggle
the CheckBox to see the effect of the property.
Option Explicit
Dim oLine As MapObjects2.Line
Dim oTSym As New MapObjects2.TextSymbol

Private Sub check1_Click()


Map1.TrackingLayer.Refresh True
End Sub

Private Sub Form_Load()


Check1.Caption = Fitted

ProgrammersReference.pmd 231 10/28/2004, 10:00 AM


232 MapObjects Programmers Reference

End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
Dim oFont As New StdFont

If Not oLine Is Nothing Then


oFont.Name = Arial
oFont.Size = 36
Set oTSym.Font = oFont
oTSym.Height = 0
oTSym.Color = moRed
If Check1.Value = 0 Then
oTSym.Fitted = False
ElseIf Check1.Value = 1 Then
oTSym.Fitted = True
End If
Map1.DrawText Map, oLine, oTSym
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Set oLine = Map1.TrackLine
Map1.TrackingLayer.Refresh True
End Sub

FittedField Property
Applies To LabelRenderer Object

Description Returns or sets the Field that contains information for whether or not to fit text between two-
point Line features for a LabelRenderer object.

Syntax object.FittedField [= value]

The FittedField property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A string expression that specifies a name of a Field in a Recordset. If


specified, the LabelRenderer makes use of the value contained in the Field

ProgrammersReference.pmd 232 10/28/2004, 10:00 AM


MapObjects Programmers Reference 233

to determine whether to fit label text between a two-point Line associated


with the feature.

Remarks The property is especially useful when rendering ARC/INFO annotation features. See the
ARC/INFO documentation for the ANNOFIT command and the $FIT pseudo item.

The FittedField of a LabelRenderer always takes precedence over the setting of the Fitted
property of its Symbol collection.

See Also TextSymbol Object, Fitted Property

Example This example uses the XOffsetField property, the YOffsetField property, and the FittedField
property to determine the characteristics of the labels of a LabelRenderer associated with a
MapLayer. Each of the properties specifies the name of a field in the Recordset associated
with the MapLayer. The field contains a value for each record that provides information for
the LabelRenderer. Commonly, this technique is useful when working with ARC/INFO
coverages that have annotation features. This example assumes that the GeoDataset associated
with the MapLayer is an ARC/INFO coverage that contains annotation features and has
appropriate fields. To try this example, paste the code into the Declarations section of a form
containing a Map named Map1 that contains a MapLayer based on a GeoDataset that is an
ARC/INFO coverage with annotation features (although you can use other kinds of
GeoDatasets as well), three ComboBox controls named Combo1, Combo2, Combo3, and a
CommandButton named Command1. The Form_Load event code will set the caption of the
CommandButton to Label. Press F5. In each combo box, select the name of the field
described. You dont have to select all three fields, if your data doesnt have appropriate fields.
Click the Label button to display the text.
Option Explicit

Private Sub combo1_Click()


If Combo1.ListIndex <> -1 Then Command1.Enabled = True
End Sub

Private Sub combo2_Click()


If Combo2.ListIndex <> -1 Then Command1.Enabled = True
End Sub

Private Sub combo3_Click()


If Combo3.ListIndex <> -1 Then Command1.Enabled = True
End Sub

Private Sub Command1_Click()

Dim oRenderer As New MapObjects2.LabelRenderer

Set Map1.Layers(0).Renderer = oRenderer

ProgrammersReference.pmd 233 10/28/2004, 10:00 AM


234 MapObjects Programmers Reference

With oRenderer
.Field = name
.AllowDuplicates = False
If Combo1.ListIndex <> -1 Then .XOffsetField = Combo1.Text
If Combo2.ListIndex <> -1 Then .YOffsetField = Combo2.Text
If Combo3.ListIndex <> -1 Then .FittedField = Combo3.Text
End With

Map1.Refresh

End Sub

Private Sub Form_Load()


Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field

Set oRecset = Map1.Layers(0).Records

For Each oField In oRecset.Fields


Combo1.AddItem oField.Name
Combo2.AddItem oField.Name
Combo3.AddItem oField.Name
Next

Combo1.Text = <choose XOffsetField>


Combo2.Text = <choose YOffsetField>
Combo3.Text = <choose FittedField>

Combo1.ListIndex = -1
Combo2.ListIndex = -1
Combo3.ListIndex = -1

Command1.Caption = Label
Command1.Enabled = False
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Extent = Map1.FullExtent
End If
End Sub

ProgrammersReference.pmd 234 10/28/2004, 10:00 AM


MapObjects Programmers Reference 235

FlashShape Method
Applies To Map Object

Description Flashes a shape on a Map.

Syntax object.FlashShape shape, nTimes

The FlashShape method syntax has the following object qualifier and arguments:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

shape Required. A reference to the shape to flash. Point, Points, Line, Rectangle,
Ellipse or Polygon objects are supported.

nTimes Required. A numeric expression that evaluates to the number of times to


flash the shape. Each flash represents approximately 0.25 seconds.

See Also Symbol Object, MapLayer Object

Example This example uses the FlashShape method to flash the first shape in a map four times. To try
this example, paste the code into the Declarations section of a form containing a
CommandButton named Command1 and a Map named Map1 that contains at least one
MapLayer, and then press F5 and click the button.
Option Explicit

Private Sub Command1_Click()


Dim recs As MapObjects2.Recordset
Set recs = Map1.Layers(0).Records
Map1.FlashShape recs.Fields(Shape).Value, 4
End Sub

Flattening Property
Applies To Spheroid Object

Description Sets or returns a value that identifies the Flattening parameter upon which the Spheroid is
based.

Syntax object.Flattening [= value ]

ProgrammersReference.pmd 235 10/28/2004, 10:00 AM


236 MapObjects Programmers Reference

The Flattening property syntax has these parts:

Part Description

object An object expression that evaluates to a Spheroid object.

value A numeric expression that specifies the flattening parameter, f.

Remarks The flattening, f, of a spheroid can be calculated by use of the following formulae, where a is
the length of the semimajor axis, and b is the length of the semiminor axis.

f = (a - b) / a

The f of the earth is approximately 0.003353. The value of f is a very small number, so you
may often find the quantity is expressed in terms of 1/f.

See Also Datum Object

Example See Axis Property

Flip Property
Applies To LabelRenderer Object

Description Returns or sets a value indicating whether a LabelRenderer object will flip text labels so that
they appear right-side up.

Syntax object.Flip [= boolean]

The Flip property syntax has these parts:

Part Description

object An object expression that evaluates to a LabelRenderer object.

boolean A boolean expression specifying whether the LabelRenderer object will


flip text labels so that they appear right-side up, as described in Settings.

Settings The settings for boolean are:

Setting Description

True (Default) The LabelRenderer object will flip text labels.

False The LabelRenderer object will not flip text labels.

ProgrammersReference.pmd 236 10/28/2004, 10:00 AM


MapObjects Programmers Reference 237

Remarks The Flip property applies to all the labels in a LabelRenderer, and therefore may not solve all
of the labeling problems. In many, but not all cases, it will enhance the appearance of splined
text. If the general direction of the Line upon which the direction of splined text is based reads
from right-to-left, then the Flip property reverses the direction to be left-to-right. When
SplinedText is False, setting Flip to True has no effect.

See Also TextSymbol Object

Example This example uses the Flip property to control whether the LabelRenderer will flip labels so
that they appear right-side up. To try this example, paste the code into the Declarations section
of a form containing a Map named Map1 that contains a MapLayer that displays line features,
a ListBox named List1, a CheckBox control named Check1, and a CommandButton named
Command1. Press F5. Click the name of a Field that will serve as the source for the text and
then press Command1. Toggle the check box control to see the effect of the Flip property.
Option Explicit
Dim fldname As String

Private Sub Check1_Click()


Command1_Click
End Sub

Private Sub Command1_Click()

Dim oRenderer As New MapObjects2.LabelRenderer


Dim oFnt As New StdFont

If List1.ListIndex <> -1 Then

oFnt.Name = Arial
oFnt.Size = 6

Set Map1.Layers(0).Renderer = oRenderer


With oRenderer
Symbol property returns a reference to a TextSymbol
.Symbol(0).Font = oFnt
.Symbol(0).Height = 0 use Size of fnt
.Field = List1.List(List1.ListIndex)
.AllowDuplicates = False
.SplinedText = True
.Flip = Check1.Value
End With
End If
Map1.Refresh

ProgrammersReference.pmd 237 10/28/2004, 10:00 AM


238 MapObjects Programmers Reference

End Sub

Private Sub Form_Load()


Dim oRect As MapObjects2.Rectangle
Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field

zoom in at the start


Set oRect = Map1.FullExtent
oRect.ScaleRectangle (0.25)
Map1.Extent = oRect

Set oRecset = Map1.Layers(0).Records


For Each oField In oRecset.Fields
If oField.Type = moString Then
List1.AddItem oField.Name
End If
Next

Check1.Caption = Flip
Command1.Caption = Label
Check1.Value = 1

End Sub

Private Sub List1_Click()


fldname = List1.List(List1.ListIndex)
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Map1.Extent = Map1.TrackRectangle
End Sub

Floor Property
Applies To Rectangle Object

Description Return or set the bottom height coordinate of a Rectangle object.

Syntax object.Floor [= value]

The Floor property syntax has these parts:

ProgrammersReference.pmd 238 10/28/2004, 10:00 AM


MapObjects Programmers Reference 239

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression specifying a height coordinate.

See Also Line Object

Example See Ceiling Property

Font Property
Applies To Symbol Object, TextSymbol Object

Description Returns a reference to a Font object.

Syntax object.Font

The Font property syntax has the following object qualifier and part:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

Remarks See Visual Basic Helps Font object topic for more information about Fonts.

See Also LabelRenderer Object

Example This example lets you set a TextSymbol objects Font property by displaying the Font Dialog.
To try this example, paste the code into the Declarations section of a form containing a
CommonDialog control, a CommandButton named Command1, and a Map named Map1.
Press F5 and then click Command1 to set the font and other font effects.
Option Explicit
Dim oTextsymbol As New MapObjects2.TextSymbol

Private Sub Command1_Click()


Dim oFont As New StdFont
With CommonDialog1
.Flags = cdlCFBoth Or cdlCFEffects
.ShowFont
oFont.name = .FontName
oFont.Size = .FontSize
oFont.Bold = .FontBold

ProgrammersReference.pmd 239 10/28/2004, 10:00 AM


240 MapObjects Programmers Reference

oFont.Italic = .FontItalic
oFont.Strikethrough = .FontStrikethru
oFont.Underline = .FontUnderline
End With

Set oTextsymbol.Font = oFont set the TextSymbol objects font


oTextsymbol.Color = CommonDialog1.Color
Map1.TrackingLayer.Refresh True
End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)
Static bTextDrawn As Boolean

If bTextDrawn Then
Map1.DrawText MapObjects2, Map1.Extent.Center, oTextsymbol
End If
bTextDrawn = True
End Sub

FromGeoCoordSys Property
Applies To GeoTransformation Object

Description Sets or returns an object that identifies the source GeoCoordSys in a GeoTransformation
object.

Syntax object.FromGeoCoordSys [= fromCoordSys ]

The FromGeoCoordSys property syntax has these parts:

Part Description

object An object expression that evaluates to a GeoTransformation object.

fromCoordSys An object expression that evaluates to a GeoCoordSys object.

See Also GeoCoordSys Object, ToGeoCoordSys Property, Direction Property

Example See Direction Property

ProgrammersReference.pmd 240 10/28/2004, 10:00 AM


MapObjects Programmers Reference 241

FromMapDistance Method
Applies To Map Object

Description Converts a linear measurement in map coordinates to a distance in control space.

Syntax object.FromMapDistance distance

The FromMapDistance method syntax has the following object qualifier and argument:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

distance The linear measurement in map units.

Remarks The FromMapDistance method performs the opposite function to the ToMapDistance
method, taking a distance in map units, and converting this to a distance on control coordi-
nates. The control coordinates are sensitive to the ScaleMode of the container. For example, if
the Form containing a Map control has a ScaleMode of centimeters, using the
FromMapDistance method will return the distance value in centimeters.

See Also FromMapPoint Method, ToMapDistance Method, ToMapPoint Method

Example This example uses the TrackLine and FromMapDistance methods convert a distance from map
units to control units. To try this example, paste the code into the Declarations section of a
form containing a Map named Map1 that contains at least one MapLayer, and then press F5
and click-drag a polygon on the map.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim ln As MapObjects2.Line
Dim report As String

report = Line is
Set ln = Map1.TrackLine
report = report & Round(ln.Length, 3) & map units, and & _
vbNewLine & Round(Map1.FromMapDistance(ln.Length), 3) & _
control units long.

MsgBox report, vbInformation, Distance Measured


End Sub

ProgrammersReference.pmd 241 10/28/2004, 10:00 AM


242 MapObjects Programmers Reference

FromMapPoint Method
Applies To Map Object

Description Converts a Point in map coordinates to coordinates in control space.

Syntax object.FromMapPoint MapPoint, xControl, yControl

The FromMapPoint method syntax has the following object qualifier and arguments:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

MapPoint An object expression that evaluates to a Point.

xControl An object expression declared to be of single data type. Contains the X


coordinate of the MapPoint in control coordinates.

yControl An object expression declared to be of single data type. Contains the Y


coordinate of MapPoint in control coordinates.

Remarks The FromMapPoint method performs the opposite function to the ToMapPoint method,
taking a Point in map units, and populating two variables with the equivalent control coordi-
nates. The control coordinates are sensitive to the ScaleMode of the container. For example, if
the Form containing a Map control has a ScaleMode of centimeters, using the
FromMapPoint method will return the yControl and xControl values in centimeters.

See Also FromMapDistance Method, ToMapDistance Method, ToMapPoint Method

Example The following example uses the FromMapPoint method to illustrate how to derive the location
in control units of a point on the map, when that point is not directly passed in a Map event. To
try this example, paste the code into the Declarations section of a form containing a Map
named Map1 that contains at least one MapLayer, and then press F5 and click-drag on the
Map.
Option Explicit
Dim rect As MapObjects2.Rectangle
Dim Loc As New MapObjects2.Point

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim newX As Single
Dim newY As Single

ProgrammersReference.pmd 242 10/28/2004, 10:00 AM


MapObjects Programmers Reference 243

Dim report As String

report = Event coordinates (map units): & vbNewLine


Set rect = Map1.TrackRectangle
Set Loc = rect.Center
Map1.FromMapPoint Loc, newX, newY
Map1.TrackingLayer.Refresh True draw the Rectangle and its center

report = report & Round(Loc.X, 0) & , & vbTab & Round(Loc.Y, 0) _


& vbNewLine & vbNewLine & Derived coordinates (control units): _
& vbNewLine & Round(newX, 0) & , & vbTab & Round(newY, 0)

MsgBox report, vbInformation, Coordinate Information


End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If Not rect Is Nothing Then
Dim sym As New MapObjects2.Symbol
sym.Style = moTransparentFill
sym.OutlineColor = moBlue
Map1.DrawShape rect, sym

sym.SymbolType = moPointSymbol
sym.Style = moCircleMarker
sym.Color = moRed
Map1.DrawShape Loc, sym
End If
End Sub

FullExtent Property
Applies To Map Object

Description Returns or sets a Rectangle object that represents the bounding box of a Map.

Syntax object.FullExtent [= rectangle]

The FullExtent property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 243 10/28/2004, 10:00 AM


244 MapObjects Programmers Reference

rectangle An object of type Rectangle that MapObjects exposes.

See Also Rectangle Object

Example This example uses the FullExtent property to set the Extent of a Map to its FullExtent. To try
this example, paste the code into the Declarations section of a form containing a
CommandButton named Command1 and a Map named Map1 that contains at least one
MapLayer, and then press F5; drag a rectangle to zoom in on the map and then click Com-
mand1 to zoom back to the full extent of the map.
Option Explicit
Private Sub Command1_Click()
Map1.Extent = Map1.FullExtent
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim Rectangle As MapObjects2.Rectangle
If Shift = 0 Then
Set Rectangle = Map1.TrackRectangle
If Not Rectangle Is Nothing Then Map1.Extent = Rectangle
Else
Map1.Pan
End If
End Sub

FullRedrawOnPan Property
Applies To Map Object

Description Returns or sets a value that determines whether to redraw a Map object completely after a
scroll or pan event.

Syntax object.FullRedrawOnPan [= boolean]

The FullRedrawOnPan property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

boolean A boolean expression specifying whether to redraw the map after a scroll or
pan event, as described in Settings.

Settings The settings for boolean are:

ProgrammersReference.pmd 244 10/28/2004, 10:00 AM


MapObjects Programmers Reference 245

Setting Description

True Redraws the Map completely after a scroll or pan event.

False (Default) The Map does not redraw completely after a scroll or pan event.

Remarks The FullRedrawOnPan property provides specialized applications the ability to control
whether or not to use MapObjects default display optimizations after a scroll or pan. You
should only consider using FullRedrawOnPan when using certain types of custom symbols
or specialized renderers.

In order to dramatically increase drawing speeds, MapObjects makes certain assumptions


about which areas of the display need to be redrawn during a pan or scroll event. Custom
symbols that are large or whose geographic position may change during scrolling or panning
may result in a display in which they appear distorted or only partially drawn. In your code,
you can keep track of when the conditions are probable for this type of problem, and at that
point, set FullRedrawOnPan to True. This will force the Map control to perform a complete
redraw, guaranteeing the legibility of your custom symbols. For instance, you might choose to
set this property to True programmatically only when zoomed to a small extent. In this way,
symbols which happen to be very large at this extent would be drawn correctly when the map
is panned. Additionally, Recordsets at small extents are conversely small and optimizations
are of lesser importance. As a zoom out occurs, the extent could again be used to determine
when to turn the optimizations back on to provide the best possible drawing speed.

See Also Pan Method, Refresh Method

Example This example uses the FullRedrawOnPan property to control whether to redraw the map
completely after a scroll or pan event. See the Remarks section of the help topic associated
with FullRedrawOnPan for more information. To try this example, paste the code into the
Declarations section of a form containing a CheckBox named Check1 and a Map named Map1
that contains at least one MapLayer, and then press F5; drag a rectangle to zoom in on the map
and then use the right button of the mouse to pan. Toggle the CheckBox to see the effect of the
property.
Option Explicit

Private Sub Check1_Click()


If Check1.Value = 0 Then
Map1.FullRedrawOnPan = False
ElseIf Check1.Value = 1 Then
Map1.FullRedrawOnPan = True
End If
End Sub

Private Sub Form_Load()


Check1.Value = 0

ProgrammersReference.pmd 245 10/28/2004, 10:00 AM


246 MapObjects Programmers Reference

Check1.Caption = FullRedrawOnPan
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

GenerateCandidates Method
Applies To Geocoder Object

Description Generates possible matching candidate addresses, and returns a GeocodeSuccess constant
indicating the status of the candidates associated with the Geocoder object. The objects
CandidateCount property indicates how many candidates are found. The number of candi-
dates found can be varied based on the objects SpellingSensitivity properties.

Syntax object.GenerateCandidates = [success]

The GenerateCandidates method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

success A variable declared to be of integer data type.

Return Values The GenerateCandidates method returns GeocodeSuccessConstants.

See Also Candidate Property, CandidateCount Property, SpellingSensitivity Property,


LocateCandidate Method

Example See Candidate Property

Geocoder Object
An Geocoder object lets you specify an individual address or street intersection, or supply a
table of addresses to match against a street network. A street network is assigned to the
Geocoder object by setting the StreetTable property with a suitable GeoDataset . A suitable

ProgrammersReference.pmd 246 10/28/2004, 10:00 AM


MapObjects Programmers Reference 247

GeoDataset may consist of either a line shapefile attributed with road names, or an ARC/
INFO coverages containing point or polygon features attributed with land parcel information.

An address needs to be standardized before matching. You must set a Standardizer objects
properties, and associate it with the Geocoder objects Standardizer property before you can
geocode an address.

Matching different types of addresses are supported in MapObjects; you select the appropriate
matching rules by specifying the MatchRules and IntersectionMatchRules properties. You
can find the following matching rule files in the Georules folder of the MapObjects installation
folder:

US addresses with zone information (us_addr1.mat)

US intersections with zone information (us_intsc1.mat)

US addresses without zone information (us_addr2.mat)

US intersections without zone information (us_intsc2.mat)

US addresses with zone information, StreetTables with single house range (us_srng1.mat)

US addresses without zone information, StreetTables with single house range (us_srng2.mat)

US addresses with zone information, StreetTables with Polygon or Point information


(us_snum1.mat)

US addresses without zone information, StreetTables with Polygon or Point information


(us_snum2.mat)

US 5 digit ZIP codes, StreetTables with 5 digit ZIP centroids (zip.mat)

US 9 digit ZIP codes, StreetTables with ZIP+4 centroids (zip4.mat)

US 9 digit ZIP codes, StreetTables with ZIP+4 centroids (zip4rng.mat)

The first time you work with the StreetTable, use the AddIndex and BuildIndices methods to
create a geocoding index for the StreetTable. You can verify that an index exists for the
GeoDataset with the IndexStatus method. An index is searched based on the queries defined
in the SearchQueries property. To verify that the Geocoder has a valid StreetTable and that
the fields specified are valid, you can test the value of the Valid property. If it is not Valid, you
can examine the LastError property to check the type of error.

Given a string with either a street address or an intersection (two streets delimited with an &
symbol), you can invoke the GenerateCandidates method to get the possible matching

ProgrammersReference.pmd 247 10/28/2004, 10:00 AM


248 MapObjects Programmers Reference

candidates. You can then match the address against the best candidate with the
LocateCandidate method, which returns an AddressLocation object.

If you have address data in a Table you can use the BatchMatch method to perform address
matching on each record, creating a new shapefile containing the results of the matching.

During the batch matching process, you can control the sensitivity of the matching process by
adjusting the values in the MatchWhenAmbiguous and MinimumMatchScore properties.
You can also set other geocoding preferences that apply to both interactive and batch matching
with the SpellingSensitivity, Offset, and SqueezeFactor properties.

You can create Geocoder objects in Visual Basic like this:


Dim geo as New MapObjects2.Geocoder
Remarks MapObjects supports foreign language (8-bit) geocoding.

Properties

BatchMatchVariableField MatchVariable Offset

Candidate MatchVariableCount SearchQueries

CandidateCount MatchVariableField Standardizer

IntersectionMatchRules MatchVariableIntersectionLink

IntersectionMatchVariableCount SpellingSensitivity SqueezeFactor

LastError MatchWhenAmbigous Valid

MatchRules MinimumMatchScore

Methods

AddIndex EraseIndices ListIndices

BatchMatch GenerateCandidates LocateCandidate

BuildIndices IndexStatus

See Also AddressLocation Object, Standardizer Object

Example To try this example, paste the code into the Declarations section of a form that contains a Map
named Map1, a CommandButton named Command1, and two TextBoxes named Text1 and
Text2. Substitute appropriate values for the data paths and then press F5.

ProgrammersReference.pmd 248 10/28/2004, 10:00 AM


MapObjects Programmers Reference 249

Option Explicit

Dim geo As New MapObjects2.Geocoder


Dim stan As New MapObjects2.Standardizer

Set global variables with field names in the StreetTable


Modify if fields names in StreetTable are different
If a field is not available, set it with an empty string
Private Const m_FromLeft = L_f_add
Private Const m_FromRight = R_f_add
Private Const m_ToLeft = L_t_add
Private Const m_ToRight = R_t_add
Private Const m_PreDir = Prefix
Private Const m_PreType = Pre_type
Private Const m_StreetName = Name
Private Const m_StreetType = Type
Private Const m_SufDir = Suffix
Private Const m_LeftZone = Zipl
Private Const m_RightZone = ZipR

Private Sub Command1_Click()

Locate an address to its best candidate


Dim foundLoc As MapObjects2.AddressLocation

If stan.StandardizeAddress(Text1.Text) Then
stan.FieldValue(ZN) = Text2.Text
geo.GenerateCandidates
If geo.CandidateCount > 0 Then
Set foundLoc = geo.LocateCandidate(0)
Map1.FlashShape foundLoc.location, 3
End If
End If

End Sub

Private Sub Form_Load()

Dim dc As New MapObjects2.DataConnection


Dim gd As Object
Dim lyr As New MapObjects2.MapLayer
Dim f, i As Integer
Dim name As String

Set up Standardizer
stan.StandardizingRules = C:\Program Files\ESRI\MapObjects2\ _

ProgrammersReference.pmd 249 10/28/2004, 10:00 AM


250 MapObjects Programmers Reference

GeoRules\us_addr.stn
stan.IntersectionStandardizingRules = C:\Program Files\ _
ESRI\MapObjects2\GeoRules\us_intsc.stn
geo.Standardizer = stan

dc.Database = C:\Program Files\ESRI\MapObjects2\ _


Samples\Data\Redlands
dc.Connect
If Not dc.Connected Then
MsgBox dc.connected error
End
End If

Set up the StreetTable


Set gd = dc.FindGeoDataset(redlands)
lyr.GeoDataset = gd
lyr.Symbol.Color = moBlue
Map1.Layers.Add lyr
geo.StreetTable = gd

Set up the match rules and variables


geo.MatchRules = C:\Program Files\ESRI\MapObjects2 _
\GeoRules\us_addr1.mat
geo.IntersectionMatchRules = C:\Program Files _
\ESRI\MapObjects2\GeoRules\us_intsc1.mat

Link the Match Variables to fields in the StreetTable


geo.MatchVariableField(FromLeft) = m_FromLeft
geo.MatchVariableField(FromRight) = m_FromRight
geo.MatchVariableField(ToLeft) = m_ToLeft
geo.MatchVariableField(ToRight) = m_ToRight
geo.MatchVariableField(PreDir) = m_PreDir
geo.MatchVariableField(PreType) = m_PreType
geo.MatchVariableField(StreetName) = m_StreetName
geo.MatchVariableField(StreetType) = m_StreetType
geo.MatchVariableField(SufDir) = m_SufDir
geo.MatchVariableField(LeftZone) = m_LeftZone
geo.MatchVariableField(RightZone) = m_RightZone

Link the intersection group 1 variables


geo.MatchVariableIntersectionLink(PreDir, mgLinkPrimary) = PreDir1
geo.MatchVariableIntersectionLink(PreType, mgLinkPrimary) _
= PreType1
geo.MatchVariableIntersectionLink(StreetName, mgLinkPrimary) _
= StreetName1
geo.MatchVariableIntersectionLink(StreetType, mgLinkPrimary) _

ProgrammersReference.pmd 250 10/28/2004, 10:00 AM


MapObjects Programmers Reference 251

= StreetType1
geo.MatchVariableIntersectionLink(SufDir, mgLinkPrimary) _
= SufDir1
geo.MatchVariableIntersectionLink(LeftZone, mgLinkPrimary) _
= LeftZone1_

geo.MatchVariableIntersectionLink(RightZone, mgLinkPrimary) _
= RightZone1

Link up intersection group 2 variables


geo.MatchVariableIntersectionLink(PreDir, mgLinkSecondary) _
= PreDir2
geo.MatchVariableIntersectionLink(PreType, mgLinkSecondary) _
= PreType2
geo.MatchVariableIntersectionLink(StreetName, mgLinkSecondary) _
= StreetName2
geo.MatchVariableIntersectionLink(StreetType, mgLinkSecondary) _
= StreetType2
geo.MatchVariableIntersectionLink(SufDir, mgLinkSecondary) _
= SufDir2
geo.MatchVariableIntersectionLink(LeftZone, mgLinkSecondary) _
= LeftZone2
geo.MatchVariableIntersectionLink(RightZone, mgLinkSecondary) _
= RightZone2

Build indices if havent


If Not geo.IndexStatus = MapObjects2.IndexStatusConstants. _
mgIndexExists Then
If Not geo.AddIndex(m_StreetName, , mgIndexTypeSoundex) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.AddIndex(m_LeftZone, m_RightZone, mgIndexTypeNormal) Then
MsgBox Cannot build geocoding index., vbCritical
End
End If
If Not geo.BuildIndices(True) Then
MsgBox Cannot build geocoding index., vbCritical
End
Else
MsgBox Indices are built.
End If
End If

ProgrammersReference.pmd 251 10/28/2004, 10:00 AM


252 MapObjects Programmers Reference

Set search queries


Dim queries As New MapObjects2.Strings
queries.Add SN? & ZN
queries.Add SN?
Set geo.SearchQueries = queries

Command1.Caption = Locate Address


Text1.Text = 260 Cajon St
Text2.Text = 92373

End Sub

GeocodeSuccess Constants
MapObjects defines the following constants for use with the Geocoder objects
GenerateCandidates method.

Constant Value Description

mgGeocodeFailed 0 Geocode failed. No candidates were


found.

mgGeocodeSuccessSingleBest 1 Successful match, with one best candi-


date.

mgGeocodeSuccessMultipleBest 2 Successful match, with multiple best


candidates.

mgGeocodeSuccessPartial 3 Geocode was partially successful, but no


candidates greater or equal to the
minimum match score.

See Also Geocoder Object, MatchCode Property

GeoCoordSys Object
A geographic coordinate system describes positions on the earth using a coordinate system
based on latitude-longitude coordinates. A geographic coordinate system is based on a datum,
defined in the Datum property. The line of zero longitude is named the prime meridian, which
is defined in the PrimeMeridian property. The units of the coordinate system are defined in
the Unit property.

ProgrammersReference.pmd 252 10/28/2004, 10:00 AM


MapObjects Programmers Reference 253

A standard geographic coordinate system can be created by setting the Type property with a
GeographicCoordSysConstants, which include over two-hundred and fifty pre-defined
geographic coordinate systems.

Alternatively, a user-defined geographic coordinate system can be defined by setting the


Datum, PrimeMeridian and Unit properties of a GeoCoordSys object to specific objects.

A GeoCoordSys can be applied to a MapLayer or Map Control via the CoordinateSystem


property of these objects. An individual shape can be projected to another ProjCoordSys or
GeoCoordSys, using the GeoCoordSys objects Transform method. Coordinate system
metadata can be stored on disk for later retrieval using the GeoCoordSys objects Export
method.

Properties

Datum Name Type Unit

IsProjected PrimeMeridian

Methods

Export ReturnDescription Transform

See Also Map Object, MapLayer Object, Projection Object, ProjCoordsys Object

GeoCoordSys Property
Applies To ProjCoordSys Object

Description Sets or returns a value that identifies the geographic coordinate system (GeoCoordSys) upon
which a ProjCoordSys object is based.

Syntax object.GeoCoordSys [= geoCoordSys ]

The GeoCoordSys property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

geoCoordSys An object expression that evaluates to a GeoCoordSys object

Remarks The GeoCoordSys property contains a GeoCoordSys object defining the geographical
coordinate system from which the ProjCoordSys is projected.

ProgrammersReference.pmd 253 10/28/2004, 10:00 AM


254 MapObjects Programmers Reference

See Also GeoCoordSys Object

Example This example uses the GeoCoordSys property of a ProjCoordSys object to summarize the
geographic coordinate systems applied to projected layers. To try this example, paste the code
into the Declarations section of a form containing a Map named Map1, a command button
named Command1 and a ListView named ListView1. Map1 should contain more than one
MapLayer, each having a coordinate system set. Press F5, and click the command button.
Option Explicit
Dim symPCS As New MapObjects2.Symbol
Dim symGCS As New MapObjects2.Symbol

Private Sub Command1_Click()

Dim itmX As ListItem


Dim curLayer As MapObjects2.MapLayer
For Each curLayer In Map1.Layers
If curLayer.CoordinateSystem.IsProjected Then
Set itmX = ListView1.ListItems.Add(, , curLayer.Name)
itmX.SubItems(1) = curLayer.CoordinateSystem.Name
itmX.SubItems(2) = curLayer.CoordinateSystem.GeoCoordSys.Name
ElseIf Not curLayer.CoordinateSystem.IsProjected Then
Set itmX = ListView1.ListItems.Add(, , curLayer.Name)
itmX.SubItems(1) = <Layer not projected>
itmX.SubItems(2) = curLayer.CoordinateSystem.Name
End If
Next curLayer

End Sub

Private Sub Form_Load()

Command1.Caption = Summarise CS
ListView1.View = lvwReport

Dim lvwHead1 As ColumnHeader


Set lvwHead1 = ListView1.ColumnHeaders.Add(1, , Layer)
Set lvwHead1 = ListView1.ColumnHeaders.Add(2, , Projected CS)
Set lvwHead1 = ListView1.ColumnHeaders.Add(3, , Geographic CS)

End Sub

ProgrammersReference.pmd 254 10/28/2004, 10:00 AM


MapObjects Programmers Reference 255

GeoDataset Object
A GeoDataset object represents a layer of geographic data. The GeoDataset object is
associated with the MapLayer object in order to display the data in a Map. This geographic
data may be held in any of the vector data formats supported by MapObjects.

Name is the default property for a GeoDataset object. To share the GeoDataset with other
applications for reading and writing (while you are not editing it) set AllowSharing to True.
Use the HasZ and HasMeasure properties to test whether the GeoDataset supports Z values
or Measures.

Properties

AllowSharing HasMeasure HasZ Name

See Also DataConnection Object, GeoDatasets Property

GeoDatasets Collection
A GeoDatasets collection contains all GeoDataset objects found in a DataConnection.

A DataConnection objects Database property includes a data source specific suffix for
certain data sources, which will determine which GeoDatasets are returned.

Properties

Count

Methods

Item

See Also DataConnection Object, Database Property

GeoDatasets Property
Applies To DataConnection Object

Description Returns a reference to the collection of GeoDatasets in a DataConnection.

Syntax Set variable = object.GeoDatasets

ProgrammersReference.pmd 255 10/28/2004, 10:00 AM


256 MapObjects Programmers Reference

The GeoDatasets property syntax has these parts:

Part Description

variable A variable that has been declared as a collection of GeoDatasets.

object An object expression that evaluates to an object in the Applies To list.

Remarks A DataConnection objects Database property includes a data source specific suffix for
certain data sources, which will determine which GeoDatasets are returned to the
GeoDatasets collection.

Note: if used with a CAD DataConnection, i.e. the Database property begins with [CAD],
the GeoDatasets property will return a collection containing all files in the directory. Be
careful to select the correct GeoDataset, as errors will occur if you set a MapLayers
GeoDataset with an unsupported file format.

See Also GeoDataset Object, TableDesc Object, MapLayer Object

Example This example uses the GeoDatasets property to list all the Shapefile, VPF and Coverage
GeoDatasets in a DataConnection objects Database. To try this example, paste the code into
the Declarations section of a form containing a DirListBox control named Dir1, and a ListBox
named List1. Press F5 and then navigate through the folders in the Directory list to a folder
that represents a Database that contains GeoDatasets.
Option Explicit
Dim dbSuffix(0 To 3) As String

Private Sub dir1_Change()


Dim i As Integer
List1.Clear

For each type of database connection


For i = 0 To 2
searchDir (i)
Next i
End Sub

Private Sub searchDir(Index As Integer)


Dim dc As New MapObjects2.DataConnection
Dim oDataset As MapObjects2.GeoDataset

Check for Geodatasets in current database


With dc
.Database = dbSuffix(Index) & Dir1.path
If .Connect Then

ProgrammersReference.pmd 256 10/28/2004, 10:00 AM


MapObjects Programmers Reference 257

If .GeoDatasets.Count > 0 Then


For Each oDataset In .GeoDatasets
List1.AddItem oDataset.Name
Next
End If
End If
End With

End Sub

Private Sub Form_Load()


dbSuffix(0) =
dbSuffix(1) = [ARC]
dbSuffix(2) = [VPF]

Dim path As String


path = Dir(C:\Program Files\ESRI\MapObjects2\Mo20.ocx)

If Len(path) <> 0 Then


Dir1.path = path
Else
Dir1.path = C:\
End If
End Sub

GeoEvent Object
A GeoEvent object represents a geographically referenced phenomenon whose position may
change. A GeoEvent displays on a Map objects TrackingLayer, and may be a Point, Points,
Line, Rectangle, Polygon or Ellipse. Each GeoEvent is depicted with a Symbol, identified
by its by SymbolIndex.

You can return the location of GeoEvent using its X and Y properties. You can move a
GeoEvent with the Move or MoveTo methods. The read-only Index property returns the
GeoEvent objects current position on the TrackingLayer. You can use the Index property
with the TrackingLayer objects Event property and RemoveEvent method.

Properties

Index Shape SymbolIndex Tag

Methods

ProgrammersReference.pmd 257 10/28/2004, 10:00 AM


258 MapObjects Programmers Reference

Move MoveTo

See Also TrackingLayer Object

GeographicCoordSys Constants
MapObjects defines over one hundred and fifty constants for use with the Type property of a
GeoCoordSys object. See the online help for a full list of GeographicCoordSysConstants.

See Also GeoCoordSys Object, Type Property

GeographicTransformation Constants
MapObjects defines over one hundred and fifty constants for use with the Type property of a
GeoTransformation object. See the online help for a full list of
GeographicTransformationConstants.

See Also GeoTransformation Object, Type Property

GeographicTransformation Property
Applies To MapLayer Object

Description Returns or set the GeographicTransformation of a MapLayer. This property is used for on-
the-fly projection of a MapLayer.

Syntax object.GeographicTransformation [= trans]

The GeographicTransformation property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

trans A variant expression which equals a valid GeoTransformation object.

Remarks When a MapLayer has its GeographicTransformation property set, MapObjects will re-
project the MapLayer, on the fly, according to that geographic transformation. You must also
set a CoordinateSystem on the Map and on the MapLayer.

MapLayers that do not have a CoordinateSystem set will be displayed unprojected.

ProgrammersReference.pmd 258 10/28/2004, 10:00 AM


MapObjects Programmers Reference 259

See Also Valid Property, Type Property, Name Property

Example This example demonstrates the use of a GeoTransformation object which is set as the
GeographicTransformation property on a MapLayer. To try this example, paste the code into
the Declarations section of a new Form which has a Map named Map1 containing two
MapLayers. Then press F5, and zoom in on a small area of the Map. Now try running the code
with the indicated GeographicTransformation property line commented out to see the differ-
ence. This code sample assumes the following: (1) You have two Geographic map layers
loaded in your control (2) One layer is based on the NAD 1927 datum (3) The second layer
is based on the NAD 1983 datum
Option Explicit

Private Sub Form_Load()


You will need to modify the code for the specific
GeoCoordSys or ProjCoordSys that your data is based upon.

Define two geographic coordinate systems


Dim gcs_nad27 As New MapObjects2.GeoCoordSys
Dim gcs_nad83 As New MapObjects2.GeoCoordSys

and set them - in this case we are using datasets that are
based on NAD27 and NAD83 datum
gcs_nad27.Type = moGeoCS_NAD1927
gcs_nad83.Type = moGeoCS_NAD1983

Create a GeoTransformation object and set it to the


pre-defined type
NAD27_To_NAD83_CONUS
Using this geotransformation will take us from NAD27 to NAD83
as we have used the default direction forward.
Dim m_GT As New MapObjects2.GeoTransformation
m_GT.Type = moGeoTransformation_NAD27_To_NAD83_CONUS

Define two map layers


Dim lyA As MapObjects2.MapLayer
Dim lyB As MapObjects2.MapLayer

... and set them appropriately


this layer contains the NAD27 based dataset
Set lyA = Map1.Layers(1)
this layer contains the NAD83 based dataset
Set lyB = Map1.Layers(0)

Set each layer to have the appropriate geographic


coordinate system

ProgrammersReference.pmd 259 10/28/2004, 10:00 AM


260 MapObjects Programmers Reference

lyA.CoordinateSystem = gcs_nad27
lyB.CoordinateSystem = gcs_nad83

...and set the NAD27 based layer to use the NAD27_to_NAD83


GeoTransformation to see the difference between the accuracy
of the transformation without using the GeoTransformation object
comment this line out
lyA.GeographicTransformation = m_GT

... finally, set the map control to display using the NAD83
geographic coordinate System
Map1.CoordinateSystem = gcs_nad83

Set the MapLayer symbols so we can see both layers


With lyA.Symbol
.Style = moUpwardDiagonalFill
.Color = moRed
.Outline = True
.OutlineColor = moMaroon
.Size = 2
End With
With lyB.Symbol
.Style = moTransparentFill
.Outline = True
.OutlineColor = moBlue
.Size = 1
End With
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
Map1.Extent = Map1.TrackRectangle
End Sub

GeoTransformation Object
When converting vector data from one coordinate system to another, it is possible to use a
GeoTransformation object to perform a geographic transformation or datum shift.

MapObjects implements industry standard geographic transformations. These can be created


by setting the Type property with an appropriate GeographicTransformationConstants;
which include nearly one thousand pre-defined geographic transformations. The majority of
these pre-defined geographic transformations define transformations from a range of datum to
the WGS1984 datum. Transformations can be defined in both forward and reverse directions

ProgrammersReference.pmd 260 10/28/2004, 10:00 AM


MapObjects Programmers Reference 261

by setting the Direction property, therefore transformations can also be specified from the
WGS1984 datum to an alternative datum.

Many situations require a transformation between two coordinate systems, neither of which is
based on the WGS1984 datum. You can use the SecondType and SecondDirection properties
to create a two-stage transformation, allowing for the change in datum between the coordinate
systems.

Alternatively, a user-defined geographic transformation can be defined by setting the


ToGeoCoordSys, FromGeoCoordSys and Method properties of a GeoTransformation
object to specific objects. Use the FromGeoCoordSys and ToGeoCoordSys properties to
define the GeoCoordSys that the transformation starts from and transforms to. Set the
Method property with a MethodConstant to specify which mathematical methodology is
used to transform the geographic coordinates. Each parameter of the transformation Method
can be set using the SetParameter method. Use GetParameter to read these parameters.

The GetParameter, Method, Name, ToGeoCoordSys and FromGeoCoordSys methods and


properties will return values and objects that have also been set using the Type property.

NB. The Z values on all the points of a shape will be modified appropriately.

Restrictions:

It is not possible to extract information, other than the name and direction, about the second
stage of a two stage predefined transformation.

It is not possible to set up a two stage user-defined transformation.

It is not possible for one stage of a two stage transformation to be predefined and the other
stage user-defined.

Properties

Direction Name SecondName ToGeoCoordSys

FromGeoCoordSys SecondDirection SecondType Type

Method

Methods

GetParameter SetParameter

See Also Projection Object, GeoCoordSys Object

ProgrammersReference.pmd 261 10/28/2004, 10:00 AM


262 MapObjects Programmers Reference

Example This example demonstrates the Direction property of the GeoTransformation object. To try
this example, paste the code into the Declarations section of a new Form which has two Map
controls named Map1 and Map2. Each Map should contain a MapLayer with geographical
locations in common. Ensure the coordinate systems of each MapLayer are set appropriately.
Then press F5, and click on either Map. The point will be transformed to the other maps
coordinate system, and displayed on both maps.
Option Explicit
Dim fromPt As New MapObjects2.Point
Dim toPt As New MapObjects2.Point
Dim curMap As Integer
Dim sym As New MapObjects2.Symbol

Private Function transformPoint(direction As _


MapObjects2.DirectionConstants, ptIn As MapObjects2.Point) As Point
Here, an appropriate GeoTransformation is created for transforming
the selected Point. This should be changed appropriately for the
CoordinateSystem of your Map2 MapLayer.
Dim myGT As New MapObjects2.GeoTransformation
myGT.Type = moGeoTransformation_OSGB1936_To_WGS1984_1

Set the appropriate direction, FromGeoCoordSys and ToGeoCoordSys


myGT.direction = direction

A CoordinateSystem may be either ProjCoordSys or GeoCoordSys.


We need to check if the type before assigning the
FromGeoCoordSys and ToGeoCoordSys
Dim map1Projected As Boolean
Dim map2Projected As Boolean

If Map1.CoordinateSystem.IsProjected Then
map1Projected = True
Else
map1Projected = False
End If

If Map2.CoordinateSystem.IsProjected Then
map2Projected = True
Else
map2Projected = False
End If

If changing from WGS1984 to other datum


If direction = moDirection_Forward Then
If map1Projected Then

ProgrammersReference.pmd 262 10/28/2004, 10:00 AM


MapObjects Programmers Reference 263

myGT.FromGeoCoordSys = Map1.CoordinateSystem.GeoCoordSys
Else
myGT.FromGeoCoordSys = Map1.CoordinateSystem
End If
If map2Projected Then
myGT.ToGeoCoordSys = Map2.CoordinateSystem.GeoCoordSys
Else
myGT.ToGeoCoordSys = Map2.CoordinateSystem
End If
Set transformPoint = Map2.CoordinateSystem.Transform _
(Map1.CoordinateSystem, fromPt, , myGT)

ElseIf direction = moDirection_Reverse Then


If map1Projected Then
myGT.ToGeoCoordSys = Map1.CoordinateSystem.GeoCoordSys
Else
myGT.ToGeoCoordSys = Map1.CoordinateSystem
End If
If map2Projected Then
myGT.FromGeoCoordSys = Map2.CoordinateSystem.GeoCoordSys
Else
myGT.FromGeoCoordSys = Map2.CoordinateSystem
End If

Set transformPoint = Map1.CoordinateSystem.Transform _


(Map2.CoordinateSystem, fromPt, , myGT)
End If

End Function

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If (Not fromPt Is Nothing) And curMap = 1 Then
sym.Color = moBlue
Map1.DrawShape fromPt, sym
End If
If (Not toPt Is Nothing) And curMap = 2 Then
sym.Color = moRed
Map1.DrawShape toPt, sym
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _

ProgrammersReference.pmd 263 10/28/2004, 10:00 AM


264 MapObjects Programmers Reference

As Single, Y As Single)
Set fromPt = Map1.ToMapPoint(X, Y)
Set toPt = transformPoint(moDirection_Forward, fromPt)
curMap = 1
Map1.TrackingLayer.Refresh (True)
Map2.TrackingLayer.Refresh (True)
End Sub

Private Sub Map2_AfterTrackingLayerDraw(ByVal hDC As _


stdole.OLE_HANDLE)
If (Not fromPt Is Nothing) And curMap = 2 Then
sym.Color = moBlue
Map2.DrawShape fromPt, sym
End If
If (Not toPt Is Nothing) And curMap = 1 Then
sym.Color = moRed
Map2.DrawShape toPt, sym
End If
End Sub

Private Sub Map2_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
Set fromPt = Map2.ToMapPoint(X, Y)
Set toPt = transformPoint(moDirection_Reverse, fromPt)
curMap = 2
Map1.TrackingLayer.Refresh (True)
Map2.TrackingLayer.Refresh (True)
End Sub

Private Sub Form_Load()


Map1 should contain a MapLayer based on the WGS1984 Datum, for
example the World Countries sample dataset.
Map2 should contain a MapLayer based on a different Datum
You should ensure the CoordinateSystem of both layers is set
correctly.
Dim pcs As New MapObjects2.ProjCoordSys
pcs.Type = moProjCS_BritishNationalGrid
Map2.Layers(0).CoordinateSystem = pcs

Dim gcs As New MapObjects2.GeoCoordSys


gcs.Type = moGeoCS_WGS1984
Map1.Layers(0).CoordinateSystem = gcs

Here the CoordinateSystem of each map is set to the


CoordinateSystem of its MapLayer

ProgrammersReference.pmd 264 10/28/2004, 10:00 AM


MapObjects Programmers Reference 265

Map1.CoordinateSystem = Map1.Layers(0).CoordinateSystem
Map2.CoordinateSystem = Map2.Layers(0).CoordinateSystem

With sym
.SymbolType = moPointSymbol
.Size = 4
.Outline = False
.Style = moTriangleMarker
End With
Arrange controls
Map1.Move 60, 60, 5000, 5000
Map2.Move Map1.Left + Map1.Width + 100, _
Map1.Top, Map1.Width, Map1.Height
Form1.Width = Map2.Left + Map2.Width + 60
Form1.Height = Map2.Top + Map2.Height + 60
End Sub

GetCrossings Method
Applies To Point Object, Points Collection, Line Object, Polygon Object, Rectangle Object

Description Returns a Points collection whose members represent the points at which two objects cross.

Syntax Set variable = object.GetCrossings( shape)

The GetCrossings method syntax has these parts:

Part Description

variable An object expression that evaluates to a Points object.

object An object expression that evaluates to an object in the Applies To list.

shape An object expression that evaluates to a Point, Points, Line, Polygon or


Rectangle object.

See Also Intersect Method

Example This example uses the GetCrossings method to return a Points collection whose members
represent the points at which two objects cross. To try this example, paste the code into the
Declarations section of a form containing a Map named Map1. Press F5 and then drag at least
two polygons that cross on the Map.
Option Explicit
Private moPolys As New Collection

ProgrammersReference.pmd 265 10/28/2004, 10:00 AM


266 MapObjects Programmers Reference

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As _


Stdole.OLE_HANDLE)

Dim oSymbol As New MapObjects2.Symbol


Dim oSymbol2 As New MapObjects2.Symbol
Dim oPolygon As MapObjects2.Polygon
Dim oPoint As MapObjects2.Point
Dim oCrossings As MapObjects2.Points

symbol for polygons


With oSymbol
.Style = moTransparentFill
.OutlineColor = moRed
End With

symbol for crossing points


With oSymbol2
.SymbolType = moPointSymbol
.Style = moCircleMarker
.Color = moBlue
End With
For Each oPolygon In moPolys
Map1.DrawShape oPolygon, oSymbol
Next

If moPolys.Count = 2 Then
Set oCrossings = moPolys(1).GetCrossings(moPolys(2))
For Each oPoint In oCrossings
Map1.DrawShape oPoint, oSymbol2
Next
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Dim oPolygon As New MapObjects2.Polygon
Set oPolygon = Map1.TrackPolygon

If moPolys.Count = 2 Then
moPolys.Remove 2
End If
moPolys.Add oPolygon
Map1.TrackingLayer.Refresh True
End Sub

ProgrammersReference.pmd 266 10/28/2004, 10:00 AM


MapObjects Programmers Reference 267

GetParameter Method
Applies To ProjCoordSys Object, GeoTransformation Object

Description Returns a value that has been set for a specific coordinate transformation parameter on a
ProjCoordSys or a GeoTransformation object.

Syntax Set variable = object.GetParameter paramType

The GetParameter method syntax has the following object qualifier and arguments:

Part Description

variable A numeric expression that represents the value that has been set for the
parameter specified

object An object expression that evaluates to an object in the Applies To list.

paramType A value or constant that identifies which parameters value is to be read, as


specified in Settings

Settings The settings for paramType are ParameterTypeConstants

Remarks If the specified parameter is unset for the object, GetParameter will return a value of zero. A
value of zero is also a valid value for certain objects. If in doubt, read the ParameterType
Constants page to check if a certain parameter is used.

See Also SetParameter Method, ParameterTypeConstants

Example This example uses the GetParameter and SetParameter methods of a ProjCoordSys object to
demonstrate how a user might alter projection parameters during run time. To try this example,
paste the code into the Declarations section of a form containing a ComboBox named
Combo1, a ListBox named List1, a Label named Label1, a TextBox named Text1, and a
CommandButton named Command1. Press F5 and choose a Projected Coordinate System
from the ComboBox. Its available parameters will be listed in the ListBox, along with their
values. Click on a parameter, enter a new value in the TextBox and click the CommandButton
to create a new ProjCoordSys object having the same parameters, but with the new value. This
object could then be applied to a MapLayer or Map.
Option Explicit
Dim choice As String
Dim newPCS As New MapObjects2.ProjCoordSys
Dim PCS As New MapObjects2.ProjCoordSys

Private Sub Combo1_Click()

ProgrammersReference.pmd 267 10/28/2004, 10:00 AM


268 MapObjects Programmers Reference

Dim getParam As String


Dim pcsParams As New MapObjects2.Strings

choice = Combo1.List(Combo1.ListIndex)
getParam = stripProj(choice)
PCS.Type = getParam
pcsParams.PopulateWithParameters PCS.Projection.Type

Dim p As Variant
List1.Clear
For Each p In pcsParams
Dim ps As String
ps = p
List1.AddItem Parameter: & p & Chr(9) & = & Chr(9) & _
PCS.GetParameter(stripProj(ps))
Next p

End Sub

Private Sub Command1_Click()

Dim val As Double


val = Text1.Text
choice = Combo1.List(Combo1.ListIndex)

New PCS Object is defined here


Dim proj As New MapObjects2.Projection
proj.Type = PCS.Projection.Type

Dim currParam As String


currParam = stripProj(choice)
newPCS.Type = PCS.Type
newPCS.SetParameter currParam, val
As the PCS is now Custom (type = -1) we cannot access its
properties as before
Label1.Caption = New custom PCS set
End Sub

Private Sub Form_Load()

Combo1.Clear
Text1.Text =
List1.Clear
Command1.Caption = Set Parameter
Label1.Caption = No custom PCS

ProgrammersReference.pmd 268 10/28/2004, 10:00 AM


MapObjects Programmers Reference 269

Dim projCoord As New MapObjects2.Strings


projCoord.PopulateWithProjectedCoordSys
Dim i As Variant
For Each i In projCoord
Combo1.AddItem ProjCoordSys: & i
Next i
Combo1.ListIndex = 0

End Sub

Function stripProj(theProjection As String) As Variant


Get position of open bracket
Dim openB As Integer
openB = InStr(theProjection, [)
stripProj = Left(Right(theProjection, Len(theProjection) - openB), _
Len(theProjection) - openB - 1)
End Function

GotFocus Event
Applies To Map Object

Description The GotFocus event is a standard ActiveX control event, which occurs when the user clicks
on the Map, or the Map control receives focus programmatically.

Syntax Private Sub object_GotFocus()

The GotFocus event syntax has one part:

Part Description

object An object expression that evaluates to a Map control.

Remarks For more information about the GotFocus event, see the Visual Basic online reference.

See Also Click Event, DblClick Event, KeyPress Event, KeyDown Event, LostFocus Event,
MouseMove Event, MouseDown Event

GroupRenderer Object
A GroupRenderer object provides a way to associate more than one renderer with a
MapLayer. One example of this is a situation in which you want to render some features of
the same MapLayer with one renderer and other features of the layer with a different ren-

ProgrammersReference.pmd 269 10/28/2004, 10:00 AM


270 MapObjects Programmers Reference

derer. Another example might be a situation in which you want to apply two renderers to the
same feature; for example, a thematic map based on class breaks for one attribute and a pie
chart for other attributes.

Use the Add method to add the specified renderer to the group of renderers. Use Count to
return the number of renderers, and use Remove to delete a renderer from the group. To
access a specific renderer, use the Renderer property.

Properties

Count DrawBackground Renderer

Methods

Add Remove

See Also ChartRenderer Object, ClassBreaksRenderer Object, DotDensityRenderer Object,


LabelRenderer Object

Example This example uses a GroupRenderer to apply two renderers to the same MapLayer. It assumes
that the USA sample data States shapefile is a MapLayer of the Map. To try this example,
paste the code into the Declarations section of a form that contains a Map named Map1 and a
CommandButton named Command1. Press F5. The code includes a standard pan and zoom on
MouseDown, as well as a FullExtent button to return to the full extent.
Option Explicit
Dim gr As New MapObjects2.GroupRenderer
Dim cr As New MapObjects2.ChartRenderer
Dim vmr As New MapObjects2.ValueMapRenderer

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

Private Sub Form_Load()


establish the ChartRenderers properties
With cr
.ChartType = moPie
.FieldCount = 5
.Field(0) = married
.Color(0) = moKhaki
.Field(1) = divorced
.Color(1) = moGreen
.Field(2) = separated
.Color(2) = moOrange

ProgrammersReference.pmd 270 10/28/2004, 10:00 AM


MapObjects Programmers Reference 271

.Field(3) = nevermarry
.Color(3) = mogrey
.Field(4) = widowed
.Color(4) = moOlive
.MinPieSize = 8
.MaxPieSize = 24
.SizeField = pop1990
.NormalizationField = area
End With

strings collection to hold unique values


Dim strs As New MapObjects2.Strings
strs.Unique = True
Dim recset As MapObjects2.Recordset
Set recset = Map1.Layers.Item(states).Records
Do While Not recset.EOF
strs.Add recset.Fields(sub_region).ValueAsString
recset.MoveNext
Loop

establish the properties of the ValueMapRenderer


With vmr
.UseDefault = True
.SymbolType = moFillSymbol
.Field = sub_region
.ValueCount = strs.Count
Dim s As Variant
Dim i As Integer
set the values for the renderer
i = 0
For Each s In strs
.Value(i) = s
.Symbol(i).Color = QBColor(i + 1)
i = i + 1
Next s
End With

add the two renderers to the GroupRenderer


note that the last one added is the last one drawn

gr.Add vmr
gr.Add cr

ProgrammersReference.pmd 271 10/28/2004, 10:00 AM


272 MapObjects Programmers Reference

assign the GroupRenderer as the MapLayers renderer


Map1.Layers.Item(states).Renderer = gr
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

HasMeasure Property
Applies To GeoDataset Object

Description Returns a value indicating whether the GeoDataset object has the ability to support measures.

Syntax object.HasMeasure [= hasM]

The HasMeasure property syntax has these parts:

Part Description

object An object expression that evaluates to a GeoDataset object.

hasM A boolean expression specifying whether the dataset has measures. See
Return Values.

Return Values The HasMeasure return values are:

Value Description

True The GeoDataset supports measures

False The GeoDataset does not support measures

Remarks Not all types of data source that can be used with MapObjects support the storage of measure
information. If the data source does not support measures (e.g. a shapefile that contains a non-
measured shape type or an SDE layer without support for measures) then any measure values
your application sets for feature vertices will be lost when they are written to the GeoDataset.
Use this property before adding features to a GeoDataset to test that measure values will be
preserved. Features read from GeoDatasets that do not support measure values have their
measure values set to the no data value.

ProgrammersReference.pmd 272 10/28/2004, 10:00 AM


MapObjects Programmers Reference 273

See Also Recordset Object, Table Object

HasZ Property
Applies To GeoDataset Object

Description Returns a value indicating whether the GeoDataset object supports Z values.

Syntax object.HasZ [= hasZ]

The HasZ property syntax has these parts:

Part Description

object An object expression that evaluates to a GeoDataset object.

hasZ A boolean expression specifying whether the dataset has Z values. See
Return Values.

Return Values The HasZ return values are:

Value Description

True The GeoDataset supports height (Z) values.

False The GeoDataset does not support height (Z) values.

Remarks Not all types of data source that can be used with MapObjects support the storage of Z values.
If the data source does not support Z values (e.g. a shapefile that contains a non-Z shape type
or an SDE layer without support for Z coordinates) then any Z values your application sets for
feature vertices will be lost when they are written to the GeoDataset. Use this property before
adding features to a GeoDataset to test that Z values will be preserved. Features read from
GeoDatasets that do not support Z values have their Z coordinates set to zero.

See Also Recordset Object, Table Object

Example This example uses the HasZ method to give the user a list of GeoDatasets in any given
directory, and to report whether or not each dataset supports Z values. To try this example,
paste the code into the Declarations section of a form that contains a CommandButton named
Command1, a ListBox named List1 and a TextBox named Text1. Then press F5, and enter a
directory with datasets into the Text1, then press Command1.
Option Explicit

Private Sub Command1_Click()

ProgrammersReference.pmd 273 10/28/2004, 10:00 AM


274 MapObjects Programmers Reference

Dim oConnection As New MapObjects2.DataConnection


Dim theGDS As New MapObjects2.GeoDataset
Dim oDataset As MapObjects2.GeoDataset

List1.Clear
load data into the map

With oConnection
.Database = Text1.Text
If .Connect Then
Screen.MousePointer = vbHourglass
If .GeoDatasets.Count > 0 Then
For Each oDataset In .GeoDatasets
List1.AddItem oDataset.Name & : & oDataset.HasZ
Next
Else
List1.AddItem <No geodatasets in current directory>
End If
Screen.MousePointer = vbDefault
End If
End With
If Not oConnection.Connect Then Exit Sub

End Sub

Private Sub Form_Load()


Change the file location as appropriate
Text1.Text = C:\Files\Testing
End Sub

Height Property
Applies To Ellipse Object, Map Object, Rectangle Object, TextSymbol Object

Description Returns or sets the vertical dimensions of an object. Read-only for Ellipse and Rectangle
objects.

Syntax object.Height [= number]

The Height property syntax has these parts:

ProgrammersReference.pmd 274 10/28/2004, 10:00 AM


MapObjects Programmers Reference 275

Part Description

object An object expression that evaluates to an object in the Applies To list.

number A numeric expression specifying the dimensions of an object. Measure-


ments are from the center of the objects border so that objects with different
border widths align correctly. These properties use the scale units of the
objects container. If object is a TextSymbol, then number is a numeric
expression in map units specifying the height to draw the text. If number is
set to zero (0.0), DrawText will use the Size property of the Font of the
TextSymbol object.

See Also Bottom Property, Top Property, Width Property

Example This example uses the Height property to provide information about what clicking on the Map
does. If the user clicks on the map, a MsgBox containing information about a MouseDown
event appears. To try this example, paste the code into the Declarations section of a form
containing a Map named Map1 that contains at least one MapLayer. Press F5 and click the
map. Dismiss the MsgBox and drag a rectangle to zoom in.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
Dim oRectangle As MapObjects2.Rectangle
Set oRectangle = Map1.TrackRectangle

If oRectangle.Height = 0 Then
MsgBox Drag a box to zoom in, vbInformation
Else
Map1.Extent = oRectangle
End If
End Sub

HeightField Property
Applies To LabelRenderer Object

Description Returns or sets the Field that contains height information for a LabelRenderer object.

Syntax object.HeightField [= value]

The HeightField property syntax has these parts:

ProgrammersReference.pmd 275 10/28/2004, 10:00 AM


276 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A string expression that specifies a name of a Field in a Recordset. If


specified, the LabelRenderer makes use of the value of the specified Field
to set the height of the label. The Field specified by HeightField stores the
height to render the label in Map control units.

Remarks If you set the HeightField property, you will override the Size property of the TextSymbol
objects Font.

See Also TextSymbol Object

Example This example uses the HeightField property to control the height of the text displayed by the
LabelRenderer. The HeightField property specifies the name of a field in the Recordset
associated with the MapLayer. The field contains a height value in map units for each record.
The Field property names the field that will serve as the source for the text. To try this
example, paste the code into the Declarations section of a form containing a Map named Map1
that contains a MapLayer , two ComboBox controls named Combo1 and Combo2, two Label
controls named Label1 and Label2, and a CommandButton named Command1. The
Form_Load event code will position all the controls except the Map. Press F5. Select the name
of the field that will serve as the HeightField and then select the name of the field whose
values will provide the source of the text for the LabelRenderer. Click Command1 to display
the text.
Option Explicit
Dim moRecset As MapObjects2.Recordset

Private Sub Command1_Click()


Dim oLayer As New MapObjects2.LabelRenderer
Dim oFont As New StdFont

If Combo1.ListIndex <> -1 And Combo2.ListIndex <> -1 Then


oFont.Name = Arial
With oLayer
.HeightField = Combo1.List(Combo1.ListIndex)
.Field = Combo2.List(Combo2.ListIndex)
.SymbolCount = 1
Set .Symbol(0).Font = oFont
End With

Map1.Layers(0).Renderer = oLayer
Map1.Refresh
End If

ProgrammersReference.pmd 276 10/28/2004, 10:00 AM


MapObjects Programmers Reference 277

End Sub

Private Sub Form_Load()

Dim oRecset As MapObjects2.Recordset


Dim oField As MapObjects2.Field

Set oRecset = Map1.Layers(0).Records

For Each oField In oRecset.Fields


If oField.Type < moString Then
Combo1.AddItem oField.Name
End If
Combo2.AddItem oField.Name
Next

Label1.Caption = Height Field


Label2.Caption = Text Field
Label1.AutoSize = True
Label2.AutoSize = True
Label1.Left = Map1.Left
Label2.Left = Map1.Left
Label1.Top = Map1.Top + Map1.Height + (Label1.Height * 2)
Label2.Top = Label1.Top + (Label2.Height * 2)
Combo1.Left = Label1.Left + (Label1.Width * 1.5)
Combo2.Left = Combo1.Left
Combo1.Top = Label1.Top
Combo2.Top = Label2.Top
Combo1.Text =
Combo2.Text =
Combo1.ListIndex = -1
Combo2.ListIndex = -1
Command1.Left = Combo1.Left + Combo1.Width * 1.25
Command1.Top = Label1.Top
Command1.Caption = Label
End Sub

HorizontalAlignment Property
Applies To TextSymbol Object

Description Returns or sets a value that determines the horizontal alignment of text for a TextSymbol
object.

ProgrammersReference.pmd 277 10/28/2004, 10:00 AM


278 MapObjects Programmers Reference

Syntax object.HorizontalAlignment [= value]

The HorizontalAlignment property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A value or constant that determines the horizontal alignment as described in


Settings.

Settings The settings for value are AlignmentConstants.

Note that only the Left, Right and Center AlignmentConstants are valid for
HorizontalAlignment.

See Also VerticalAlignment Property

Example This example uses the HorizontalAlignment and VerticalAlignment properties of the
TextSymbol object associated with a LabelRenderer to control the label positions of the
features of a MapLayer. Once the Map draws, you can try out the various text alignment
combinations. To try this example, paste the code into the Declarations section of a form
containing two Frame controls named Frame1 and Frame2, two OptionButton controls named
Option1 and Option2, a ComboBox named Combo1 and a Map named Map1 that contains one
MapLayer. For each OptionButton, set its Index to 0 in the Control Properties dialog box to
create a control array of one element. Once youve created the OptionButtons and the Frames,
cut Option1 and paste it into Frame1 and cut Option2 and paste it into Frame2. Select Press F5
and choose the field in Combo1 whose values will serve as the text for the labels. Click the
option buttons to alter the alignment properties.
Option Explicit
Dim oRenderer As MapObjects2.LabelRenderer

Private Sub Combo1_Click()


With oRenderer
.Field = Combo1.List(Combo1.ListIndex)
.Symbol(0).HorizontalAlignment = moAlignCenter
.Symbol(0).VerticalAlignment = moAlignCenter
End With
Map1.Refresh
End Sub

Private Sub Option1_Click(Index As Integer)


vertical alignment
If Combo1.ListIndex <> -1 Then
Select Case Index

ProgrammersReference.pmd 278 10/28/2004, 10:00 AM


MapObjects Programmers Reference 279

Case 0
oRenderer.Symbol(0).VerticalAlignment = moAlignTop
Case 1
oRenderer.Symbol(0).VerticalAlignment = moAlignCenter
Case 2
oRenderer.Symbol(0).VerticalAlignment = moAlignBottom
Case 3
oRenderer.Symbol(0).VerticalAlignment = moAlignBaseline
End Select
Map1.Refresh
End If
End Sub

Private Sub Option2_Click(Index As Integer)


horizontal alignment
If Combo1.ListIndex <> -1 Then
Select Case Index
Case 0
oRenderer.Symbol(0).HorizontalAlignment = moAlignLeft
Case 1
oRenderer.Symbol(0).HorizontalAlignment = moAlignCenter
Case 2
oRenderer.Symbol(0).HorizontalAlignment = moAlignRight
End Select
Map1.Refresh
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x _


As Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Extent = Map1.FullExtent different than the usual example
End If
End Sub

Private Sub Form_Load()


Dim I As Integer
Dim iBorder As Integer
Dim ofield As MapObjects2.Field

iBorder = 1000

ProgrammersReference.pmd 279 10/28/2004, 10:00 AM


280 MapObjects Programmers Reference

establish the renderer for the MapLayer


Set Map1.Layers(0).Renderer = New MapObjects2.LabelRenderer
Set oRenderer = Map1.Layers(0).Renderer

size and position the map


Map1.Left = iBorder - 800
Map1.Top = iBorder - 400
Map1.Height = 3800
Map1.Width = 5000

size the form


Me.Width = iBorder + Map1.Width + iBorder
Me.Height = iBorder + Map1.Height + iBorder

setup the frames


Frame1.Caption = Vertical Alignment
Frame2.Caption = Horizontal Alignment
Frame1.Width = 1500
Frame1.Height = Map1.Height
Frame2.Width = Map1.Width
Frame1.Top = Map1.Top
Frame1.Left = Map1.Left + Map1.Width + 40
Frame2.Left = Map1.Left
Frame2.Top = Map1.Top + Map1.Height + 40
Frame2.Height = Option2(0).Height + 300

position the first option button


Option1(0).Top = 300
Option1(0).Left = 100

position the second option button


Option2(0).Left = 100
Option2(0).Top = 200

For I = 1 To 3 Create three more instances of Option1.


Load Option1(I)
Set the location of the new option button.
Option1(I).Top = Option1(I - 1).Top + Option1(0).Height + 40
Option1(I).Visible = True
Next I

set labels for vertical options


Option1(0).Caption = Top
Option1(1).Caption = Center
Option1(2).Caption = Bottom

ProgrammersReference.pmd 280 10/28/2004, 10:00 AM


MapObjects Programmers Reference 281

Option1(3).Caption = Baseline

For I = 1 To 2 Create two more instances of Option2.


Load Option2(I)
Set the location of the new option button.
Option2(I).Left = Option2(I - 1).Left + Option2(0).Width + 40
Option2(I).Visible = True
Next I

set labels for horizontal options


Option2(0).Caption = Left
Option2(1).Caption = Center
Option2(2).Caption = Right

position and size the combo box


Combo1.Left = Map1.Left
Combo1.Top = Map1.Top - Combo1.Height - 40
Combo1.Width = Map1.Width * 0.5

intialize the Center option buttons to be the default


Option1(1).Value = True
Option2(1).Value = True

create a list of string fields


For Each ofield In Map1.Layers(0).Records.Fields
If ofield.Type = moString Then
Combo1.AddItem ofield.Name
End If
Next

Combo1.Text = <Choose a field name>


End Sub

hWnd Property
Applies To Map Object

Description The hWnd property is a standard ActiveX property that returns a handle to a control.

Syntax object.hWnd [= handle]

The hWnd property syntax has these parts:

ProgrammersReference.pmd 281 10/28/2004, 10:00 AM


282 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

handle A value of Long data type specifying the Windows API handle of the object.

Remarks For more information about the hWnd property, set the Visual Basic online reference.

See Also Map Object

Example This example uses the hWnd property to draw a rectangle on a Map using Windows API calls.
To try this example, paste the code into the Declarations section of a form containing a Map
named Map1 that contains at least one MapLayer, and then press F5. Once the Map displays,
click and drag the Rectangle over the Map.
Option Explicit

Private Declare Function Rectangle Lib gdi32 (ByVal hDC As Long, _


ByVal X1 As Long, ByVal Y1 As Long, ByVal X2 As Long, ByVal Y2 As _
Long) As Long
Private Declare Function GetDC Lib user32 (ByVal hwnd As Long) As _
Long
Private Declare Function ReleaseDC Lib user32 (ByVal hwnd As Long, _
ByVal hDC As Long) As Long
Private Declare Function SetROP2 Lib gdi32 (ByVal hDC As Long, _
ByVal nDrawMode As Long) As Long
Private Const R2_NOTXORPEN = 10
Private Const R2_NOT = 6

Dim g_hdc As Long


Dim g_hwnd As Long
Dim dragging As Boolean
Dim xs As Integer, ys As Integer

Private Sub Form_Load()


dragging = False
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
dragging = True
g_hwnd = Map1.hwnd
g_hdc = GetDC(g_hwnd)
SetROP2 g_hdc, R2_NOTXORPEN

xs = ScaleX(X, vbTwips, vbPixels)


ys = ScaleY(Y, vbTwips, vbPixels)

ProgrammersReference.pmd 282 10/28/2004, 10:00 AM


MapObjects Programmers Reference 283

Rectangle g_hdc, xs - 10, ys - 10, xs + 10, ys + 10

End Sub

Private Sub Map1_MouseMove(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
If dragging Then
Rectangle g_hdc, xs - 10, ys - 10, xs + 10, ys + 10
xs = ScaleX(X, vbTwips, vbPixels)
ys = ScaleY(Y, vbTwips, vbPixels)
Rectangle g_hdc, xs - 10, ys - 10, xs + 10, ys + 10
End If
End Sub

Private Sub Map1_MouseUp(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
Rectangle g_hdc, xs - 10, ys - 10, xs + 10, ys + 10
ReleaseDC g_hwnd, g_hdc
dragging = False
End Sub

ImageLayer Object
An ImageLayer represents a layer that is based on geo-referenced raster data stored in an
image file. Each ImageLayer objects File property represents the name of the file on disk.
Most image files should have an associated file called a world file that contains the transfor-
mation parameters needed to display the image simultaneously with MapLayer objects. To
find out which image files should have a world file, see the individual image format descrip-
tions in the online help.

The Layers collection includes a MapLayer or an ImageLayer object for each layer defined
for a map. Using the Valid property, you can determine whether a layer is valid before adding
it to the collection. Use the Layers property of a Map object to retrieve its Layers collection.
You can access members of the Layers collection either by numeric index or by the Name of
the ImageLayer.

You can create ImageLayer objects in Visual Basic with code like this:
Dim ilyr as New MapObjects2.ImageLayer

Properties

Extent Tag UpdateWhileDrawing

ProgrammersReference.pmd 283 10/28/2004, 10:00 AM


284 MapObjects Programmers Reference

File Transparent Valid

LayerName TransparentColor Visible

See Also Map Object, MapLayer Object, TrackingLayer Object

Index Property
Applies To GeoEvent Object

Description Returns the current Index of the GeoEvent.

Syntax object.Index

The Index property syntax has these parts:

Part Description

object An object expression that evaluates to a GeoEvent object.

Remarks The current index is the internal index of the GeoEvent. The index represents the GeoEvent
objects current position in the collection of events on the TrackingLayer. GeoEvents can be
added at a specified Index, MapObjects renumbers the Index of all subsequent events if your
application removes an event.

See Also TrackingLayer Object

Example This example uses the Index property to reference a GeoEvent on the TrackingLayer. To try
this example, paste the code into the Declarations section of a form containing a Map named
Map1 that contains at least one MapLayer, a ListBox named List1, and a Label named Label1,
then press F5. Remove events by clicking the event in the list box. Note that MapObjects
reassigns a new index value to remaining events automatically. If the referenced events Index
value is -1, it means the event has been removed.
Option Explicit

Global list of TrackingLayer events


Private moEventList() As MapObjects2.GeoEvent

Private Sub Form_Load()


Dim oFont As New StdFont
Dim oTopLeft As MapObjects2.Point, oBotRight As MapObjects2.Point
Dim fXSpace As Double, fYSpace As Double
Dim i As Integer
Dim oEventPoint As New MapObjects2.Point

ProgrammersReference.pmd 284 10/28/2004, 10:00 AM


MapObjects Programmers Reference 285

The map must be displayed in order


for ToMapMoint to work correctly
Me.Show

Use ESRI font


oFont.Name = ESRI Environmental & Icons

Figure out event spacing


Set oTopLeft = Map1.ToMapPoint(0, 0)
Set oBotRight = Map1.ToMapPoint(Map1.Width - Map1.Left, Map1. _
Height - Map1.Top)
fXSpace = (oBotRight.x - oTopLeft.x) 5
fYSpace = (oBotRight.y - oTopLeft.y) 5

Add events
Map1.TrackingLayer.SymbolCount = 4

For i = 0 To 3
With Map1.TrackingLayer
With .Symbol(i)
.Color = moBlue
.Style = moTrueTypeMarker
.Font = oFont
.Size = 36
.CharacterIndex = 74 + i
End With

Create the event and place it on the Map


oEventPoint.x = oTopLeft.x + (i + 1) * fXSpace
oEventPoint.y = oTopLeft.y + (i + 1) * fYSpace
.AddEvent oEventPoint, i

Add event to global list


ReDim Preserve moEventList(i)
Set moEventList(i) = .Event(i)
End With
Next

ListEvents

Label1.Caption = Click event in list box to remove it (-1 = _

ProgrammersReference.pmd 285 10/28/2004, 10:00 AM


286 MapObjects Programmers Reference

removed)
End Sub

Private Sub List1_Click()

Dim iEvent As Integer

iEvent = moEventList(List1.ListIndex).Index
If iEvent > -1 Then
Map1.TrackingLayer.RemoveEvent iEvent
ListEvents
Else
MsgBox This event has already been removed., vbExclamation, _
Remove Event
End If

End Sub

Sub ListEvents()

Dim i As Integer

List1.Clear

For i = 0 To UBound(moEventList)
List1.List(i) = gEventList( & i & ).Index = & _
moEventList(i).Index
Next

End Sub

Indexed Property
Applies To PlaceLocator Object

Description Returns a value that indicates whether an index exists for an object.

Syntax object.Indexed

The object placeholder is an object expression that evaluates to an object in the Applies To
list.

Return Values The Indexed property return values are:

ProgrammersReference.pmd 286 10/28/2004, 10:00 AM


MapObjects Programmers Reference 287

Value Description

True An index exists for the object.

False An index does not exist for the object.

Remarks In the object is a MapLayer object, the index is a spatial index.

If the object is a PlaceLocator object, the index is a searchable index for string searching
index.

See Also StreetTable Property, PlaceNameTable Property, BuildIndex Method

Example See Geocoder Object

IndexEvents Property
Applies To EventRenderer Object

Description Returns or sets a value indicating whether or not an index is created for the events in a
MapLayer.

Syntax object.IndexEvents [= boolean]

The IndexEvents property syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

boolean A boolean expression specifying whether or not an index is created on the


events in a MapLayer when an EventRenderer is assigned to it.

Remarks The default setting of the boolean value is False, by default no indexing of events in the
MapLayer takes place.

When a MapLayer is drawn using an EventRenderer, an index is created on the events in the
EventTable. For large datasets this process may take some time, and therefore slow down the
drawing of a MapLayer with an EventRenderer. However, you can create an index of the
events in your MapLayer before drawing takes place, which will speed up the drawing time.
This index is created only once, not each time the MapLayer is drawn. The same index is
therefore used every time your MapLayer is drawn with the EventRenderer.

If you wish to index all of the events in your MapLayer prior to its display, you should create
an EventRenderer and set its IndexEvents property to True, and then assign the

ProgrammersReference.pmd 287 10/28/2004, 10:00 AM


288 MapObjects Programmers Reference

EventRenderer to a MapLayer. An index of events is created at this point, which is used


later on when your MapLayer is drawn, for example when you Refresh your Map.

If you set the IndexEvents property to true when the EventRenderer is already assigned to a
MapLayer, events will be indexed at draw time as features are drawn. Therefore if the user is
zoomed in on a MapLayer when IndexEvents is set to True, only events on features within
that extent will be indexed. As more features are displayed, for example if the user pans across
the MapLayer, events on those features which become visible will also be indexed.

If you only wish to display a small area of the whole MapLayer, you can also set the
IndexExtent property. Only features lying within, or partially within, the specified Extent are
indexed, which will increase the speed of the indexing operation.

If your EventTable is a dataset shared between many users, the events contained in the dataset
may change periodically. In this case, the index MapObjects created on the events assigned to
the MapLayer will be outdated. You can use the InvalidateIndex method to refresh the
index on any particular route.

See Also IndexExtent Property, InvalidateIndex Method

Example This example demonstrates indexing of events when displaying a MapLayer with an
EventRenderer. To try this example, paste the code into the Declarations section of a form
containing a Map control named Map1 containing one MapLayer with lines which have
measure values, and a Command Button named Command1. Also add two OptionButtons
named Option1 and Option2. This example uses the Highways sample shapefile, alter the path
to this folder if required. Press F5, and the MapLayer will display with an EventRenderer
displaying the point events contained in the Accidents dbf file. Only the events within the Map
Extent are indexed. Right-Click to pan about the map, and more events will be indexed as you
pan. Click the pavements option and the MapLayer is displayed with an EventRenderer
showing the line events contained in the pavements dbf file.
Option Explicit
Dim dc As New MapObjects2.DataConnection
Dim ptRend As New MapObjects2.EventRenderer
Dim lnRend As New MapObjects2.EventRenderer
Dim lyr As New MapObjects2.MapLayer

Private Sub setupEventRenderer()

Now set up the EventRenderers


Screen.MousePointer = vbHourglass

Dim accTbl As New MapObjects2.Table


accTbl.database = dBASE IV;DATABASE= _
C:\Program Files\ESRI\MapObject2\Samples\Data\Events
accTbl.Name = Accident

ProgrammersReference.pmd 288 10/28/2004, 10:00 AM


MapObjects Programmers Reference 289

With ptRend
.DrawBackground = True
.IndexEvents = True
.SymbolType = moPointSymbol
.EventTable = accTbl
.StartMeasureField = MILE
.DefaultSymbol.SymbolType = moPointSymbol
.DefaultSymbol.Style = moCircleMarker
.DefaultSymbol.Color = moPurple
.DefaultSymbol.Size = 4
.UseDefault = True
.FeatureRouteIDField = RKEY
.EventRouteIDField = RKEY
.StartMeasureField = MILE
End With

Dim paveTbl As New MapObjects2.Table


paveTbl.database = dBASE IV;DATABASE=C:\ _
Program Files\ESRI\MapObjects2\Samples\Data\Events
paveTbl.Name = Pavement

With lnRend
.DrawBackground = True
.IndexEvents = True
.SymbolType = moLineSymbol
.EventTable = paveTbl
.FeatureRouteIDField = rkey
.EventRouteIDField = rkey
.StartMeasureField = fmp
.EndMeasureField = tmp
.SymbolField = rideq
.ValueCount = 3
.Value(0) = L
.Symbol(0).Style = moSolidLine
.Symbol(0).Size = 2
.Symbol(0).Color = moGreen
.Value(1) = M
.Symbol(1).Style = moSolidLine
.Symbol(1).Size = 2
.Symbol(1).Color = moYellow
.Value(2) = N

ProgrammersReference.pmd 289 10/28/2004, 10:00 AM


290 MapObjects Programmers Reference

.Symbol(2).Style = moSolidLine
.Symbol(2).Size = 2
.Symbol(2).Color = moBlue
End With

Screen.MousePointer = vbDefault

End Sub

Private Sub Option1_Click()


Screen.MousePointer = vbHourglass
lyr.Renderer = ptRend
Map1.Refresh
Screen.MousePointer = vbDefault
End Sub

Private Sub Option2_Click()


Screen.MousePointer = vbHourglass
lyr.Renderer = lnRend
Map1.Refresh
Screen.MousePointer = vbDefault
End Sub

Private Sub Form_Load()

dc.database = C:\Program Files\ESRI\MapObjects2 _


Samples\Data\Events
If Not dc.Connect Then End

Set lyr.GeoDataset = dc.FindGeoDataset(Highway)


If lyr.Valid Then Map1.Layers.Add lyr

lyr.Symbol.Color = moRed
lyr.Symbol.Size = 3
Option1.Caption = Render accidents
Option2.Caption = Render pavements
Option1.Value = 1
Option2.Value = 0
Map1.ScrollBars = False

Dim ext As New MapObjects2.Rectangle


ext.Left = 1654104.03468352
ext.Right = 1665961.92190812
ext.Top = 1544924.54782958
ext.Bottom = 1534984.37821543
Set Map1.Extent = ext

ProgrammersReference.pmd 290 10/28/2004, 10:00 AM


MapObjects Programmers Reference 291

setupEventRenderer

End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)
If Button = vbLeftButton Then
Map1.Extent = Map1.TrackRectangle
ElseIf Button = vbRightButton Then
Map1.Pan
End If
End Sub

IndexExtent Property
Applies To EventRenderer Object

Description Returns or sets a value indicating an extent of a MapLayer for which events in the
EventRenderers EventTable should be indexed.

Syntax object.IndexEvents [= rect]

The IndexEvents property syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

rect An object expression that evaluates to a Rectangle object, specifying the


extent which contains the features for which events should be indexed.

Remarks If you only wish to display a small area of a MapLayer, you can set the IndexExtent prop-
erty. Only features lying within, or partially within, the specified Extent are indexed, which
will increase the speed of the indexing operation.

If you set the IndexEvents property to true when the EventRenderer is already assigned to a
MapLayer, events will be indexed at draw time as features are drawn. Therefore if the user is
zoomed in on a MapLayer when IndexEvents is set to True, only events on features within
that extent will be indexed. As more features are displayed, for example if the user pans across
the MapLayer, events on those features which become visible will also be indexed. If there
are a considerable amount of new events to be indexed, this may slow down the drawing of the
Map.

ProgrammersReference.pmd 291 10/28/2004, 10:00 AM


292 MapObjects Programmers Reference

You can use the IndexExtent property in this situation to index the whole area which the user
may display. Setting the IndexExtent property appropriately would prevent the indexing
occurring at draw time while the user pans about the Map.

See Also IndexEvents Property, InvalidateIndex Method

Example See IndexEvents Property

IndexStatus Constants
MapObjects defines the following constants for use with the Geocoder objects IndexStatus
method.

Constant Value Description

mgIndexNonexistant 0 The index does not exist.

mgIndexInvalid 1 The index is invalid or corrupted.

mgIndexUnreadable 2 The index is not readable.

mgIndexExists 3 The index exists and is usable.

See Also Geocoder Object, IndexStatus Method

IndexStatus Method
Applies To Returns an IndexStatusConstant indicating the current status of the index associated with the
Geocoder Object.

Description Geocoder Object

Syntax object. IndexStatus [= status]

The IndexStatus method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

status A variable declared to be of integer data type.

Return Values The IndexStatus method returns GeocodeSuccessConstants.

ProgrammersReference.pmd 292 10/28/2004, 10:00 AM


MapObjects Programmers Reference 293

See Also AddIndex Method, EraseIndex Method, BuildIndices Method

Example See AddIndex Method

IndexType Constants
MapObjects defines the following constants for use with the Geocoder objects AddIndex
method.

Constant Value Description

mgIndexTypeSoundex 0 Soundex hash index

mgIndexTypeNormal 1 Normal (random hash) index

See Also Geocoder Object, AddIndex Method

Insert Method
Applies To Points Collection, Parts Collection

Description Inserts a new Points collection at the specified position in a Parts collection or inserts a new
Point object at the specified position in a Points collection.

Syntax object.Insert( index, Point)

The Insert method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index An integer that represents the position of the member in the Parts or Points
collection.

Point An object expression that evaluates to a Point or Points object.

See Also Set Method, Remove Method

Example This example uses the Insert method to insert a new Point into a collection of Points. To try
this example, paste the code into the Declarations section of a form containing a Map named
Map1, and then press F5. Track a polygon on the Map and then use the right mouse button to
select the vertex in front of which to insert the new point.

ProgrammersReference.pmd 293 10/28/2004, 10:00 AM


294 MapObjects Programmers Reference

Option Explicit
Dim moPoly As MapObjects2.Polygon

Sub InsertVertex(vertex As Integer, poly As Polygon)


Dim oPoint As New MapObjects2.Point
Dim oPoints As New MapObjects2.Points
Dim fOffset As Double

If vertex >= 0 Then


Set oPoints = moPoly.Parts(0)
If vertex = 0 Then vertex = moPoly.Parts(0).Count - 1

create the point to be inserted at the midpoint of the


selected vertex and the previous vertex
oPoint.X = (moPoly.Parts(0).Item(vertex).X + _
moPoly.Parts(0).Item(vertex - 1).X) / 2
oPoint.Y = (moPoly.Parts(0).Item(vertex).Y + _
moPoly.Parts(0).Item(vertex - 1).Y) / 2
oPoints.Insert vertex, oPoint
End If

End Sub

Function SelectVertex(oPoint As MapObjects2.Point, oPoly As _


Polygon) As Integer
Dim fTol As Double
Dim oPoints As MapObjects2.Points
Dim i As Integer

fTol = Map1.ToMapDistance(100)
Set oPoints = oPoly.Parts(0)
For i = 0 To oPoints.Count - 2
If oPoints(i).DistanceTo(oPoint) < fTol Then
SelectVertex = i
Exit Function
End If
Next

SelectVertex = -1
End Function

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)

Dim iVertex As Integer

ProgrammersReference.pmd 294 10/28/2004, 10:00 AM


MapObjects Programmers Reference 295

If Button = 1 Then
Set moPoly = Map1.TrackPolygon
ElseIf Not moPoly Is Nothing Then
iVertex = SelectVertex(Map1.ToMapPoint(X, Y), moPoly)
If iVertex <> -1 Then
InsertVertex iVertex, moPoly
End If
End If

Map1.TrackingLayer.Refresh True

End Sub

Private Sub Map1_AfterTrackingLayerDraw(ByVal hDC As


Stdole.OLE_HANDLE)_

Dim oPoint As MapObjects2.Point


Dim oSym As New MapObjects2.Symbol
Dim oPtSym As New MapObjects2.Symbol

If Not moPoly Is Nothing Then


oSym.Color = moPaleYellow
oPtSym.SymbolType = moPointSymbol
oPtSym.Color = moRed
Map1.DrawShape moPoly, oSym
For Each oPoint In moPoly.Parts(0)
Map1.DrawShape oPoint, oPtSym
Next
End If

End Sub

Private Sub Form_Load()


Dim oRect As New Rectangle
oRect.Left = 0: oRect.Bottom = 0: oRect.Right = 100: oRect.Top = 100
Map1.Extent = oRect
End Sub

Inset Method
Applies To Ellipse Object, Rectangle Object

Description Decreases the width and height of an object.

ProgrammersReference.pmd 295 10/28/2004, 10:00 AM


296 MapObjects Programmers Reference

Syntax object.Inset deltaX, deltaY

The Inset method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

deltaX A numeric expression that represents the distance in the X direction to


decrease the width of the object.

deltaY A numeric expression that represents the distance in the Y direction to


decrease the height of the object.

Remarks The Inset method decreases the object by deltaX at both the left and the right of the object and
decreases the object by deltaY at both the top and the bottom.

See Also Intersect Method, Offset Method

Example This example uses the Inset method to draw a Rectangle inset from the Extent of the map. The
Maps extent is shaded with a red fill pattern, the inset rectangle is shaded with a green fill
pattern. To try this example, paste the code into the Declarations section of a form containing a
Map named Map1 containing at least one MapLayer and then press F5 and click the Map.
Option Explicit

Dim moRectangle As MapObjects2.Rectangle

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As Stdole.OLE_HANDLE)
Dim oSymbol As New MapObjects2.Symbol
If Not moRectangle Is Nothing Then
With oSymbol
.SymbolType = moFillSymbol
.Style = moDownwardDiagonalFill
.Color = moRed
.Size = 0
End With
Map1.DrawShape moRectangle, oSymbol

With moRectangle
.Inset .Width * 0.1, .Height * 0.1
End With
With oSymbol
.Style = moUpwardDiagonalFill

ProgrammersReference.pmd 296 10/28/2004, 10:00 AM


MapObjects Programmers Reference 297

.Color = moGreen
End With
Map1.DrawShape moRectangle, oSymbol
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x As _


Single, y As Single)
Set moRectangle = Map1.Extent
Map1.Refresh
End Sub

Intersect Method
Applies To Point Object, Points Collection, Line Object, Polygon Object, Rectangle Object, Ellipse
Object

Description Returns a shape that represents the geometric intersection of one shape object with another
shape object.

Syntax Set resultShape = object.Intersect (intersectShape [,extent])

The Intersect method syntax has these parts:

Part Description

resultShape An object expression that evaluates to a shape object. (See Remarks). Will
contain the resulting shape after the intersection operation.

object An object expression that evaluates to an object in the Applies To list. This
is the first of the two shape objects whose intersection is to be calculated.

intersectShape An object expression that evaluates to an object in the Applies To list. This
is second of the two shape objects whose intersection is to be calculated.

extent An object expression that evaluates to a Rectangle object. This Rectangle


should entirely contain the objects extent, and is used internally.

Remarks If the two Shapes do not have a valid Intersect, the resultShape will be Nothing.

For a list of which shapes may result from an Intesect operation, see the online help.

Where the resultShape could be more than one object type (e.g. Rectangle or Polygon), then
use an interim Object and then test the result using its ShapeType property to see what type of
object it is.

ProgrammersReference.pmd 297 10/28/2004, 10:00 AM


298 MapObjects Programmers Reference

You cannot use the Intersect method with a self-intersecting Polygon. If you do, an exception
is raised in Visual Basic, specifying Error 5000, Valid Object expected as argument. You can
however use a self-intersecting Line.

See Also Buffer Method, Difference Method, Union Method, XOr Method

Example This example uses the Intersect method to allow the user to perform intersect operations lines.
The line and the new shape generated by the Intersect operation are added to the tracking layer
as GeoEvents. Note, an intersection of two lines may be a point, many points, or a line. Care
must be taken to add events to the tracking layer using the appropriate symbol for the resultant
shape type, which is checked here by reading the ShapeType property of the returned shape.
To try this example, paste the code into the Declarations section of a form containing a Map
named Map1 that has at least one MapLayer, press F5, and then click on the map to track two
lines.
Option Explicit
Dim shape1 As Object
Dim shape2 As Object
Dim inter As Boolean

Private Sub doIntersect(shape As Object)

If Not inter Then


Set shape1 = shape
inter = True
ElseIf inter Then

Dim interShape As Object MapObjects2.line


Dim interEvent As New MapObjects2.GeoEvent
Set shape2 = shape
Set interShape = shape1.Intersect(shape2, Map1.FullExtent)

If Not interShape Is Nothing Then


Result could be a point, points, or a line
If interShape.shapeType = (moShapeTypePoint Or _
moShapeTypeMultipoint) Then
Set interEvent = Map1.TrackingLayer.AddEvent(interShape, 2)
ElseIf interShape.shapeType = moShapeTypeLine Then
Set interEvent = Map1.TrackingLayer.AddEvent(interShape, 3)
End If
End If

Set shape1 = Nothing


inter = False

ProgrammersReference.pmd 298 10/28/2004, 10:00 AM


MapObjects Programmers Reference 299

End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x As _


Single, y As Single)
If Button = 2 Then
Dim r As New MapObjects2.Rectangle
Set r = Map1.TrackRectangle
Map1.Extent = r
Exit Sub

ElseIf Button = 1 Then


Line intersect
Dim line As New MapObjects2.line
Dim eventLine As New MapObjects2.GeoEvent
Set line = Map1.TrackLine
Set eventLine = Map1.TrackingLayer.AddEvent(line, 1)
Call doIntersect(line)
End If
End Sub

Private Sub Form_Load()


inter = False
Map1.TrackingLayer.SymbolCount = 4
With Map1.TrackingLayer.Symbol(1)
.SymbolType = moLineSymbol
.Style = moSolidLine
.Color = moBlue
.Size = 3
End With
With Map1.TrackingLayer.Symbol(2)
.SymbolType = moPointSymbol
.Style = moTriangleMarker
.Color = moRed
.Size = 4
End With
With Map1.TrackingLayer.Symbol(3)
.SymbolType = moLineSymbol
.Style = moDashLine
.Color = moRed
.Size = 3
End With
End Sub

ProgrammersReference.pmd 299 10/28/2004, 10:00 AM


300 MapObjects Programmers Reference

IntersectionMatchRules Property
Applies To Geocoder Object

Description Returns or sets the intersection match rule file name associated with the Geocoder object.

Syntax object.IntersectionMatchRules [= rule filename]

The IntersectionMatchRules property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

rule filename A string expression that specifies the path of the Intersection Match rule file
name.

Remarks MapObjects provides a set of intersection match rules. Select the one that is suitable to the
type of address you want to match.

See Also MatchRule Property, IntersectionMatchVariable Property,


IntersectionMatchVariableCount Property, MatchVariableIntersectionLink Property

Example See MatchRules Property

IntersectionMatchVariable Property
Applies To Geocoder Object

Description Returns the name of variables defined in the intersection match rules associated with the
IntersectionMatchRules property of the Geocoder object.

Syntax object.IntersectionMatchVariable (index) [=intName]

The IntersectionMatchVariable property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

index A numeric expression that specifies the relative position of a member of the
group of IntersectionMatchVariable names associated with the Geocoder
object. Index must be a number from 0 to a number that is one less than the

ProgrammersReference.pmd 300 10/28/2004, 10:00 AM


MapObjects Programmers Reference 301

value of the Geocoder objects IntersectionMatchVariableCount prop-


erty.

intName An object declared as a string data type that evaluates to the returned
variable name.

Remarks Use this property to return details of the intersection match variables which have been set on a
Geocoder object. The intersection match variables are defined in the .mat file specified in the
IntersectionMatchRules property.

See Also MatchVariable Property, IntersectionMatchRules Property,


IntersectionMatchVariableCount Property, MatchVariableIntersectionLink Property

Example See MatchRules Property

IntersectionMatchVariableCount Property
Applies To Geocoder Object

Description Returns the number of intersection match variables defined in the IntersectionMatchRules
property associated with the Geocoder object.

Syntax object.IntersectionMatchVariableCount [=count]

The IntersectionMatchVariableCount property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

count A variable declared to be of integer data type.

See Also IntersectionMatchRules Property, IntersectionMatchVariable Property,


MatchVariableIntersectionLink Property

Example See MatchRules Property

IntersectionStandardizingRules Property
Applies To Standardizer Object

Description Returns or sets the intersection standardization rule command file associated with the
Standardizer object.

ProgrammersReference.pmd 301 10/28/2004, 10:00 AM


302 MapObjects Programmers Reference

Syntax object.IntersectionStandardizingRules [= rule filename]

The IntersectionStandardizingRules property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

rule filename A string expression that specifies the Intersection Standardization rule
command file path and name.

Remarks An intersection is delimited by using an address string containing the symbol &. If a
Standardizer object is has both StandardizationRules and
IntersectionStandardizationRules properties set, the Standardizer will check if the address
string contains an ampersand symbol (&). It will automatically apply the appropriate
standardization rule and return the standardized FieldValues. For this reason, you should
avoid using an & in an address string if it is not an intersection.

MapObjects provides standardizing rule files for street intersection addresses. You can find the
following Intersection Standardization rule command file in the Georules folder:

Intersection Standardization RuleCommand File Name/Description

us_intsc.stn Standardizes U.S. street intersection addresses,

e.g., N Main St & First Ave.

See Also StandardizingRules Property, StandardizeAddress Method

Example See Standardizer Object

Intersects Method
Applies To Rectangle Object

Description Returns a value that indicates whether a Rectangle object intersects another Rectangle.

Syntax object.Intersects rectangle

The Intersects method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

ProgrammersReference.pmd 302 10/28/2004, 10:00 AM


MapObjects Programmers Reference 303

rectangle An object expression that evaluates to a Rectangle object.

Return Values

The Intersects method returns these values:

Value Description

True The rectangles intersect.

False The rectangles do not intersect.

See Also Buffer Method, Difference Method, GetCrossings Method, Intersect Method, Union
Method, XOr Method

Example This example uses the Intersects method to test whether a newly constructed rectangle
intersects the rectangle representing the original extent of a map. If it does, the code uses the
rectangle to pan the map; otherwise, the extent reverts to the original extent. To try this
example, paste the code into the Declarations section of a form containing a CommandButton
named Command1 and a Map named Map1 that contains at least one MapLayer. Press F5 and
then click Command1.
Option Explicit
Dim OrigExtent As MapObjects2.Rectangle

Private Sub Command1_Click()


Dim Rect As MapObjects2.Rectangle
Dim deltaX, deltaY As Double
Set Rect = Map1.Extent

deltaX = Map1.Extent.Height * 0.1


deltaY = Map1.Extent.Width * 0.1

Rect.Offset deltaX, deltaY offset the extent

If OrigExtent.Intersects(Rect) Then
Map1.Extent = Rect
Else
Map1.Extent = OrigExtent
End If
End Sub

Private Sub Form_Load()


Dim Rect As MapObjects2.Rectangle
Set Rect = Map1.Extent
Rect.ScaleRectangle (0.75)

ProgrammersReference.pmd 303 10/28/2004, 10:00 AM


304 MapObjects Programmers Reference

Map1.Extent = Rect
Set OrigExtent = Map1.Extent
End Sub

InvalidateIndex Method
Applies To EventRenderer Object

Description Causes the index of events on a particular RouteID to be refreshed.

Syntax object.InvalidateIndex (RouteIDKey)

The InvalidateIndex method syntax has these parts:

Part Description

object An object expression that evaluates to a EventRenderer.

boolean A string evaluating to the RouteID of the feature for which the events index
should be refreshed, from the EventRenderers EventTable.

Remarks If your EventTable is a dataset shared between many users, the events contained in the dataset
may change periodically. In this case, the index MapObjects created on the events assigned to
the MapLayer will be outdated.

You can use the InvalidateIndex method to refresh the index on any particular route. The
index of events currently stored for that RouteID will be removed, and a new index of events
for that RouteID will be created from the current EventTable.

See Also IndexExtent Property, InvalidateIndex Method

Example See IndexEvents Property

IsCustom Property
Applies To Projection Object

Description Returns a value that indicates whether a Projection object has been user-defined, using the
Custom property.

Syntax object.IsCustom [= custom]

The IsCustom property syntax has these parts:

ProgrammersReference.pmd 304 10/28/2004, 10:00 AM


MapObjects Programmers Reference 305

Part Description

object An object expression that evaluates to an object in the Applies To list.

custom An boolean expression that indicates if a projection is custom or not, see


Return Values.

Return Values The IsCustom property returns these values:

Value Description

True The projection is user-customized.

False The projection is one of the ProjectionConstants.

See Also Custom Property, Type Property

Example This example demonstrates the use of the IsCustom property of the Projection object, and also
demonstrates the setting of a new Projection object as a property of a ProjCoordSys object. To
try this example, paste the code into the Declarations section of a form which has a Label
named Label1, a Combo Box named Combo1, a Command Button named Command1, and
Map named Map1 containing one MapLayer which has a ProjCoordSys set. Then press F5.
The IsCustom property is read to determine if the existing projection set on the MapLayer is a
Custom one. Now select a new projection type from the ComboBox, and click the
CommandButton to set this projection as a property of the MapLayers CoordinateSystem.
Option Explicit

Private Sub Command1_Click()

Dim PCS As New MapObjects2.ProjCoordSys


Dim newProj As New MapObjects2.Projection

newProj.Type = stripProj(Combo1.List(Combo1.ListIndex))
PCS.Type = Map1.Layers(0).CoordinateSystem.Type
PCS.Projection = newProj

Map1.Layers(0).CoordinateSystem = PCS

End Sub

Private Sub Form_Load()

Dim proj As New MapObjects2.Strings


Dim item As Variant

ProgrammersReference.pmd 305 10/28/2004, 10:00 AM


306 MapObjects Programmers Reference

Combo1.Clear
proj.PopulateWithProjections
For Each item In proj
Combo1.AddItem item
Next item
Combo1.AddItem <Select new projection>, 1
Combo1.ListIndex = 1

Command1.Caption = Set Projection

If Map1.Layers(0).CoordinateSystem.Projection.IsCustom Then
Label1.Caption = Custom Projection Object
Else
Label1.Caption = Pre-Defined Projection Object
End If

End Sub

Function stripProj(theProjection As String) As Variant


Get position of open bracket
Dim openB As Integer
openB = InStr(theProjection, [)
stripProj = Left(Right(theProjection, Len(theProjection) - openB), _
Len(theProjection) - openB - 1)
End Function

IsFullyMeasured Property
Applies To Line Object

Description Returns a value indicating whether all vertices of a Line object have a non-null measure value.

Syntax object.IsFullyMeasured [= boolean]

The IsFullyMeasured property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

boolean A boolean indicating if the object is fully measured, See Return Values

Return Values The IsFullyMeasured property return values are:

ProgrammersReference.pmd 306 10/28/2004, 10:00 AM


MapObjects Programmers Reference 307

Value Description

True All vertices of the Line have a Measure value set against them.

False Not all vertices of the Line have a Measure value set.

See Also Point Object, Measure Property

Example This example makes use of the IsFullyMeasured property to draw lines on a map with appro-
priate symbols. The UpdateMeasures method can also be applied if lines in the Recordset are
not already fully measured. To try this example, copy the code into the Declarations section of
a form that contains a CheckBox named Check1, a CommandButton named Command1, and
Map named Map1 with a MapLayer containing line features, some of which are fully mea-
sured. Press F5 and click on a line. Fully measured lines will be drawn with a solid blue line,
whereas lines not fully measured will be drawn with a red dotted line.
Option Explicit
Public symIs As New MapObjects2.Symbol
Public symIsNot As New MapObjects2.Symbol

Private Sub Command1_Click()


Map1.Refresh
End Sub

Private Sub Map1_AfterLayerDraw(ByVal index As Integer, ByVal _


canceled As Boolean, ByVal hDC As stdole.OLE_HANDLE)
Dim recs As New MapObjects2.Recordset
Set recs = Map1.Layers(0).Records

recs.MoveFirst
While Not recs.EOF
Dim gLine As New MapObjects2.Line
Set gLine = recs(Shape).Value

If (Check1.Value) And (Not gLine.IsFullyMeasured) Then


gLine.UpdateMeasures
End If

If gLine.IsFullyMeasured Then
Map1.DrawShape gLine, symIs
Else
Map1.DrawShape gLine, symIsNot
End If
recs.MoveNext
Wend

ProgrammersReference.pmd 307 10/28/2004, 10:00 AM


308 MapObjects Programmers Reference

End Sub

Private Sub Form_Load()


Check1.Caption = Update Measures
Command1.Caption = Refresh Map
With symIs
.SymbolType = moLineSymbol
.Color = moBlue
.Style = moSolidLine
.Size = 2
End With
With symIsNot
.SymbolType = moLineSymbol
.Color = moRed
.Style = moDotLine
.Size = 2
End With
End Sub

IsPointIn Method
Applies To Ellipse Object, Polygon Object, Rectangle Object

Description Returns a value that indicates whether a Point falls within an object.

Syntax object.IsPointIn point

The IsPointIn method syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

point An object expression that evaluates to a Point object

Return Values The IsPointIn method returns these values:

Value Description

True The point is located within the boundary of object.

False The point is located outside the boundary of object.

See Also Intersects Method, SearchShape Method

ProgrammersReference.pmd 308 10/28/2004, 10:00 AM


MapObjects Programmers Reference 309

Example This example uses the IsPointIn method to identify features on a map. To try this example,
paste the code into the Declarations section of a form containing a Map named Map1 that
contains one MapLayer with polygon features. You may want to change the name of the field
from State_Name to the name of a field appropriate to your data. Press F5 and click the
button. Clicking the map with the left mouse button zooms in, clicking with the right mouse
button identifies the feature.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x As _


Single, y As Single)
Dim oRectangle As MapObjects2.Rectangle
Dim oPoint As MapObjects2.Point
Dim oRecset As MapObjects2.Recordset
Dim oShape As MapObjects2.Polygon

Select Case Button

Case vbLeftButton
Set oRectangle = Map1.Extent
oRectangle.ScaleRectangle (0.5)
Map1.Extent = oRectangle

Case vbRightButton
Set oPoint = Map1.ToMapPoint(x, y)
Set oRecset = Map1.Layers(0).Records
Do While Not oRecset.EOF
Set oShape = oRecset.Fields(shape).Value
If oShape.IsPointIn(oPoint) Then
change field name in next line to reflect your data
MsgBox prompt:=oRecset(state_name), Title:=Identify
Exit Do
End If
oRecset.MoveNext
Loop

Case Else
Dont respond
End Select
End Sub

ProgrammersReference.pmd 309 10/28/2004, 10:00 AM


310 MapObjects Programmers Reference

IsProjected Property
Applies To GeoCoordSys Object, ProjCoordSys Object

Description Returns a value that indicates whether a coordinate system is projected. This property can be
used to distinguish an object of type GeoCoordSys from one of type ProjCoordSys.

Syntax object.IsProjected

The IsProjected property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

Return Values The IsProjected property returns these values:

Value Description

True The coordinate system is projected, and is therefore of type ProjCoordSys.

False The coordinate system is not projected, and is therefore of type


GeoCoordSys.

See Also Projection Object

Example See IsCustom Property

Item Method
Applies To Layers Collection, Parts Collection, Points Collection, Strings Collection, Fields Collection,
GeoDatasets Collection

Description Returns a specific member of a collection, by position.

Syntax object.Item( index)

The Item method syntax has the following object qualifier and part:

Part Description

object Required. An object expression that evaluates to an object in the Applies To


list.

ProgrammersReference.pmd 310 10/28/2004, 10:00 AM


MapObjects Programmers Reference 311

index Required. A numeric expression that specifies the position or string expres-
sion that specifies the name of a member of the collection. Index must be a
number from 0 to a number that is one less than the value of the collections
Count property or a valid name.

Remarks In the case of the following objects, Item returns a reference to the member of the collection:
GeoDatasets, Layers, and Parts.

If the value provided as index does not match any existing member of the collection, an error
occurs.

The Item method is the default method for most MapObjects collections. Therefore, the
following lines of code are equivalent. All lines return the extent of the first layer in the map,
assuming roads is the first layer:
Map1.Extent = Map1.Layers.Item(0).Extent
Map1.Extent = Map1.Layers(0).Extent
Map1.Extent = Map1.Layers(roads).Extent
Note that you can refer to a layer by name as well as by index. The string matching for the
name is not case-sensitive. The following table summarizes which objects you can access by
numeric expression and which you can access by string expression:

numeric access string access

GeoDatasets Fields

Layers Layers

Parts

Points

Strings

See Also Count Property

Example This example uses the Item method to iterate through the Layers collection of a Map to list
each layers name. To try this example, paste the code into the Declarations section of a form
containing a ListBox named List1 and a Map named Map1 that contains at least one
MapLayer. Press F5.
Option Explicit

Private Sub Form_Load()


Dim oLayers As MapObjects2.Layers
Dim iLayer As Integer

ProgrammersReference.pmd 311 10/28/2004, 10:00 AM


312 MapObjects Programmers Reference

List1.Clear
Set oLayers = Map1.Layers
For iLayer = 0 To oLayers.Count - 1
List1.AddItem oLayers.Item(iLayer).name
Next
End Sub

KeyDown Event
Applies To Map Object

Description The KeyDown event is a standard ActiveX control event, which occurs when the user clicks
on the map. The KeyPress event occurs after the KeyDown event.

Syntax Private Sub object_KeyDown(keyCode As Integer, shift As Integer)

The KeyDown event syntax has these parts:

Part Description

object An object expression that evaluates to a Map control.

keyCode An integer specifying a key code corresponding to the Key which was
pressed. For a list of keycode constants, see the Visual Basic online refer-
ence.

shift An integer specifying the status of the Shift key, as described in Values.

Values The value of shift evaluates to a Visual Basic constant, and may have the following values

Constant Value Description

vbShiftMask 1 The SHIFT key is pressed

vbCtrlMask 2 The CTRL key is pressed

vbAltMask 4 The ALT key is pressed

The value of keyCode evaluates to a keycode constant.

See Also Click Event, DblClick Event, KeyPress Event, KeyDown Event, LostFocus Event,
MouseMove Event, MouseDown Event

ProgrammersReference.pmd 312 10/28/2004, 10:00 AM


MapObjects Programmers Reference 313

KeyPress Event
Applies To Map Object

Description The KeyPress event is a standard ActiveX control event, which occurs when the user clicks on
the map. The KeyPress event occurs after the KeyDown event.

Syntax Private Sub object_KeyPress(keyAscii As Integer)

The KeyPress event syntax has these parts:

Part Description

object An object expression that evaluates to a Map control.

keyAscii An integer corresponding to a standard numeric ASCII keycode, as de-


scribed in Values. An integer that returns a standard numeric ANSI keycode.

Remarks For more information about the KeyPress event, see the Visual Basic online reference).

See Also Click Event, DblClick Event, KeyPress Event, KeyDown Event, LostFocus Event,
MouseMove Event, MouseDown Event

LabelPlacer Object
A LabelPlacer is an object that symbolizes features, by drawing a string text on each feature
in a MapLayer. The text strings which are used to symbolize each feature are stored in a
Field in the MapLayers Recordset. The Field property specifies which Field should be used
for the label text.

A LabelPlacer gives the option of using a range of TextSymbols to display label text, using
the Symbol, Value, ValueCount and ValueField properties. The ValueField property
specifies which Field in the MapLayers Recordset contains a value indicating which
TextSymbol from the Symbol array is used to draw the labels.

By setting the ValueCount property you can determine how many values of its ValueField
property the LabelPlacer will provide a Symbol for. You should then set a TextSymbol for
each Symbol in the symbol array. In addition, you should specify which value in the
ValueField corresponds to which Symbol in the symbol array by setting the value array. For
example, if you wish to label features with a value of Road in the SymbolField with the first
Symbol in the symbol array (Symbol(0)), you should set the first Value in the value array to
equal Road, e.g:

ProgrammersReference.pmd 313 10/28/2004, 10:00 AM


314 MapObjects Programmers Reference

Value(0) = Road
The DefaultSymbol property contains a TextSymbol object which is used to draw the label of
any feature which does not have a value in the ValueField, or for which a corresponding
Value is not set.

By setting the PlaceAbove, PlaceOn, and PlaceBelow properties, you can determine the
position of the label relative to the feature with which it is associated. Use SymbolHeight and
SymbolWidth to establish the space occupied by a Point features Symbol so the label does
not conflict with the Symbol .

You can control whether or not to draw the features in the MapLayer in addition to the labels
by setting the DrawBackground property, in addition you can specify a
BackgroundRenderer property to determine how those features are displayed . You can
control whether or not to draw duplicate labels on the MapLayer with the AllowDuplicates
property. You can determine whether or not to mask the labels by setting MaskLabels
property. In addition, you set the color of the mask with MaskColor.

A LabelPlacer differs from a LabelRenderer in that it can detect conflicts between labels and
it positions labels in such a way as to provide a more aesthetic appearance.

A LabelPlacer is a creatable object in MapObjects, for example;


Dim placer as New MapObjects2.LabelPlacer
See Also ChartRenderer Object, ClassBreaksRenderer Object, DotDensityRenderer Object,
LabelRenderer Object, ValueMapRenderer Object

Properties

AllowDuplicates MaskLabels SymbolWidth

BackgroundRenderer PlaceAbove UseDefault

DefaultSymbol PlaceBelow Value

DrawBackground PlaceOn ValueCount

Field Symbol ValueField

MaskColor SymbolHeight

Example This example uses the properties and methods of the LabelPlacer to render a street network.
To try this example, paste the code into the Declarations section of a form that contains a
CommandButton named Command1, two CheckBox controls named Check1 and Check2, and
a Map control named Map1 that contains a MapLayer with line features. The example assumes
the MapLayer is based on the Redlands shapefile in the sample data. Press F5. You can click-
drag to zoom in or use the right-mouse button to pan.

ProgrammersReference.pmd 314 10/28/2004, 10:00 AM


MapObjects Programmers Reference 315

Option Explicit

Dim LabelPlacer As New MapObjects2.LabelPlacer

Private Sub Check1_Click()


If Check1.Value = vbChecked Then
LabelPlacer.AllowDuplicates = True
ElseIf Check1.Value = vbUnchecked Then
LabelPlacer.AllowDuplicates = False
End If
Map1.Refresh
End Sub

Private Sub Check2_Click()


If Check1.Value = vbChecked Then
LabelPlacer.DrawBackground = True
ElseIf Check2.Value = vbUnchecked Then
LabelPlacer.DrawBackground = False
End If
Map1.Refresh
End Sub

Private Sub Command1_Click()


Map1.Extent = Map1.FullExtent
End Sub

Private Sub Form_Load()


Check1.Caption = Allow Duplicates
Check2.Caption = DrawBackground
Command1.Caption = Full Extent
set an initial extent
Dim r As New Rectangle
r.Left = -117.183964079772
r.Right = -117.160018438746
r.Top = 34.047951088234
r.Bottom = 34.0285801368372
r.ScaleRectangle 0.75

Set Map1.Extent = r

default color for the layer


Map1.Layers(0).Symbol.Color = moNavy

create a font to be used by the LabelPlacer


Dim fnt As New StdFont

ProgrammersReference.pmd 315 10/28/2004, 10:00 AM


316 MapObjects Programmers Reference

fnt.Name = Times
fnt.Bold = False

Set Map1.Layers(0).Renderer = LabelPlacer

LabelPlacer.Field = NAME

Check2.Value = Checked DrawBackground control


LabelPlacer.DrawBackground = True

default symbol
LabelPlacer.DefaultSymbol.Height = Map1.FullExtent.Height / 150
Set LabelPlacer.DefaultSymbol.Font = fnt

LabelPlacer.AllowDuplicates = False
Check1.Value = vbUnchecked AllowDuplicates control

add a specific value for major roads


LabelPlacer.ValueField = CFCC
LabelPlacer.ValueCount = 1
LabelPlacer.Value(0) = A31
fnt.Bold = True
Set LabelPlacer.Symbol(0).Font = fnt
LabelPlacer.Symbol(0).Height = Map1.FullExtent.Height / 100

mask the labels


LabelPlacer.MaskLabels = True
LabelPlacer.MaskColor = Map1.BackColor

End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, x As _


Single, y As Single)
If Button = 1 Then
Map1.Extent = Map1.TrackRectangle
Else
Map1.Pan
End If
End Sub

LabelRenderer Object
A LabelRenderer is an object that represents a way of symbolizing features by drawing text
on a feature. The Field property is the name of the Field in the Recordset that stores the text

ProgrammersReference.pmd 316 10/28/2004, 10:00 AM


MapObjects Programmers Reference 317

values to use as labels. The Symbol property returns the TextSymbol that you use to draw the
text. The SymbolCount property contains the number of symbols associated with the
LabelRenderer.

You can toggle several properties to control the appearance of the renderer. You can control
whether or not to draw the features in addition to the labels by setting the DrawBackground
property; you can control whether or not to draw duplicate labels on the MapLayer with the
AllowDuplicates property; and you can determine whether or not to spline text along line
features with the SplinedText property. Since splined text follows the order of Points of a
Line, you may need to set the Flip property to True in order to enhance the appearance of
splined text.

In addition to its Field property, the LabelRenderer provides several field-based properties
that let you drive how and even whether, labels display on the Map. You can set the Field that
specifies the height in map units of each label with the HeightField. You can set the rotation
angle of each label by specifying a RotationField that contains the angle to rotate each label.
The values stored in the Field specified as the SymbolField provide an index for each label
into the array of TextSymbol objects associated with the LabelRenderer through the Symbol
property. You can set the Field that specifies the horizontal offset distance with the
XOffsetField property and the vertical offset distance with the YOffsetField property. You
can also set the Field that specifies whether or not to fit labels between two-point line features
with the FittedField property. Finally, you can assign a level value to each label in the Field
specified by the LevelField property. Using the labels level value in concert with the
MaxLevel and MinLevel properties, you can control which levels the LabelRenderer will
draw.

Developers familiar with ARC/INFO annotation feature classes will recognize that many of
these properties map well onto the pseudo items associated with annotation. If you base the
MapLayer youre working with on an ARC/INFO coverage, you can set a property and refer
to the coverages pseudo items using the name of the pseudo item without the preceding dollar
sign ($), for example $OFFSETY should be referenced as OFFSETY.

A LabelRenderer is a creatable object in MapObjects. In Visual Basic, heres one way to


create a LabelRenderer:
Set Map1.Layers(0).Renderer = New MapObjects2.LabelRenderer
RemarksThe LabelRenderer by default places labels at the centroid of the feature which is
labeled.

See Also ChartRenderer Object, ClassBreaksRenderer Object, DotDensityRenderer Object,


LabelPlacer Object, ValueMapRenderer Object

Properties

AllowDuplicates MinLevel SymbolField

ProgrammersReference.pmd 317 10/28/2004, 10:00 AM


318 MapObjects Programmers Reference

DrawBackground MaxLevel UseDefault

Field RotationField Tag

HeightField SplinedText XOffsetField

LevelField Symbol YOffsetField

MaxLevel SymbolCount

LastError Property
Applies To Geocoder Object, PlaceLocator Object

Description Returns a value that specifies the type of error that exists in the Geocoder or Standardizer
objects.

Syntax object.LastError [= Value]

The LastError property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value An integer that indicates the last error (See return Values).

Return Values The return values for the LastError property are EnhancedGeocodingErrorConstants.

See Also StandardizeAddress Method, LocateCandidate Method, BatchMatch Method

Example This example checks if a Geocoder or Standardizer object is valid or not and uses the
LastError property to return messages about problems encountered in a Geocoder or
Standardizer object. If a problem exists, the code returns a message about the type of error. To
try this example, paste the code into the Declarations section of a form containing a Map
named Map1. Substitute appropriate values for the data paths. Press F5. You should find that
your Standardizer is Valid, but your Geocoder does not have any MatchVariableField proper-
ties set.
Option Explicit

Sub ReportError(obj As Object, info As String)


Dim msg As String

If Not obj.Valid Then


MsgBox The object is not valid., vbCritical, info

ProgrammersReference.pmd 318 10/28/2004, 10:00 AM


MapObjects Programmers Reference 319

End If

If obj.LastError = mgErrorNone Then


MsgBox No error, vbInformation, info
Else
Select Case obj.LastError
Case 1
msg = Unknown error
Case 2
msg = Internal error
Case 3
msg = Match rules unspecified
Case 4
msg = Intersection match rules unspecified
Case 5
msg = Standardizer unspecified
Case 6
msg = Street table unspecified
Case 7
msg = Standardization rules unspecified
Case 8
msg = Specified standardizer is invalid
Case 9
msg = Cannot open match rules
Case 10
msg = Cannot find match variables
Case 11
msg = Out of memory
Case 12
msg = Error in match rules syntax
Case 13
msg = Match rules warnings triggered
Case 14
msg = No candidates
Case 15
msg = Too many handles allocated
Case 16
msg = No address standardized
Case 17
msg = Cannot access database
Case 18
msg = Cannot open standardization rules

ProgrammersReference.pmd 319 10/28/2004, 10:00 AM


320 MapObjects Programmers Reference

Case 19
msg = Error processing standardization rules
Case 20
msg = Cannot read standardization rules
Case 21
msg = Cannot access address file
Case 22
msg = Cannot write to output database
Case 23
msg = Match variable key field are unspecified
Case 24
msg = Street table is missing a geocoding index
Case 25
msg = Record count mismatch in building the indices
Case 26
msg = No indices were specified to build
Case 27
msg = Too many indices specified (the maximum is 10)
Case 28
msg = Corrupt metadata information
Case 29
msg = Metadata string is too long; key information is _
too complex
Case 30
msg = Could not find specified key field in database
Case 31
msg = The query is too complex, use less keys (or _
soundex searches)
Case 32
msg = No search queries given
Case 33
msg = Out of disk space
End Select
MsgBox Error: & msg, vbCritical, info
End If
End Sub

Private Sub Form_Load()

Dim geo As New MapObjects2.Geocoder


Dim stan As New MapObjects2.Standardizer
Dim dc As New MapObjects2.DataConnection
Dim lyr As New MapObjects2.MapLayer

ProgrammersReference.pmd 320 10/28/2004, 10:00 AM


MapObjects Programmers Reference 321

Dim gd As Object

Change the paths below to ones appropriate for your data


stan.StandardizingRules = C:\Program Files _
\ESRI\MapObjects2\GeoRules\us_addr.stn
stan.IntersectionStandardizingRules = C:\Program Files _
\ESRI\MapObjects2\GeoRules\us_intsc.stn

ReportError stan, Check Error for Standardarizer

Change the paths below to ones appropriate for your data


dc.Database = C:\Program Files _
\ESRI\MapObjects2\Samples\Data\Redlands
dc.Connect
If Not dc.Connected Then
MsgBox dc.connected error
End
End If

Set gd = dc.FindGeoDataset(redlands)
lyr.GeoDataset = gd
lyr.Symbol.Color = moBlue

Map1.Layers.Add lyr

geo.Standardizer = stan
geo.StreetTable = gd

Change the paths below to ones appropriate for your data


geo.MatchRules = C:\Program Files\ESRI\ _
MapObjects2\GeoRules\us_addr1.mat
geo.IntersectionMatchRules = C:\Program Files\ _
ESRI\MapObjects2\GeoRules\us_intsc1.mat

ReportError geo, Check Error for Geocoder


If geo.LastError = mgErrorMatchVariableKeyFieldUnspecified Then
MsgBox The match variable fields have not been set here. Check _
the sample of the Geocoder Objects MatchVariableField _
property., vbInformation
End If
End Sub

ProgrammersReference.pmd 321 10/28/2004, 10:00 AM


322 MapObjects Programmers Reference

Layers Collection
A Layers collection object represents the collection of geographical data layers defined for a
Map. Each layer in the collection may either consist of vector data, in which case it is refer-
enced by a MapLayer object or it may consist of geographically referenced raster image data,
in which case it is referenced by an ImageLayer object. A MapLayer or an ImageLayer
represents a kind of spatial information - either human or natural phenomena; for example,
political boundaries, cities, highways, well sites, locations of customers, or soil types, rivers,
and lakes, etc. Using the Valid property, you can determine whether a MapLayer or an
ImageLayer is valid before adding it to the collection.

Use the Layers property of a Map object to retrieve its Layers collection. The default
property of Layers is Item. You can access members of the Layers collection either by
numeric index or by the Name of the MapLayer.

Properties

Count

Methods

Add Item MoveToBottom Remove

Clear MoveTo MoveToTop

See Also Map Object, MapLayer Object, TrackingLayer Object

Layers Property
Applies To Map Object

Description Returns a reference to the collection of MapLayer or ImageLayer objects belonging to a


Map control.

Syntax object.Layers [= lyrCollection]

The Layers property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

lyrCollection An object expression that evaluating to a MapObjects Layers collection.

ProgrammersReference.pmd 322 10/28/2004, 10:00 AM


MapObjects Programmers Reference 323

Remarks You can manipulate members of the Layers collection using standard collection methods (for
example, the Add and Remove methods). Each element in the collection can be accessed by
its index.

See Also MapLayer Object, Layers Collection

Example This example uses the Layers property to iterate through all the Layers of a Map, adding the
name of each MapLayer to a List. To try this example, paste the code into the Declarations
section of a form containing a CommandButton named Command1, a ListBox named List1,
and a Map named Map1 that contains at least one MapLayer, and then press F5. Once the Map
displays, click Command1.
Option Explicit
Private Sub Command1_Click()
Dim l As MapObjects2.MapLayer
For Each l In Map1.Layers
List1.AddItem l.Name
Next l
End Sub

LayerType Constants
MapObjects defines the following LayerType constants to describe the layers in a Map.

Constant Value Description

moMapLayer 0 The layer represents a MapLayer

moImageLayer 1 The layer represents an ImageLayer

See Also MapLayer Object

LayerType Property
Applies To MapLayer Object, ImageLayer Object

Description Returns a value that indicates whether the layer is an ImageLayer displaying raster data, or
MapLayer displaying vector data.

Syntax object.LayerType [= lyrType]

The LayerType property syntax has these parts:

ProgrammersReference.pmd 323 10/28/2004, 10:00 AM


324 MapObjects Programmers Reference

Part Description

object An object expression that evaluates to an object in the Applies To list.

lyrType A LayerTypeConstant.

Return Values The return values for the LayerType property are LayerTypeConstants.

See Also ShapeType Property, Valid Property

Example This example uses the LayerType property to determine whether the most recently added layer
in the MapLayers collection represents a MapLayer or an ImageLayer; if it is a MapLayer, the
code reports on some of the layers properties, if the layer is an ImageLayer, its added to the
bottom of the list of layers and others layers will be drawn on top of it. To try this example
paste the code into the Declarations section of a form containing a CommandButton named
Command1, a ListBox named List1, and a Map named Map1 that has at least one MapLayer.
Press F5 and click Command1.
Option Explicit
Private Sub Command1_Click()
Dim num As Integer
Dim f As MapObjects2.field
With Map1.Layers(0)
If .LayerType = moMapLayer Then
List1.AddItem Name: & .Name
List1.AddItem Visible: & Str(.Visible)
List1.AddItem Symbol color: & Str(.Symbol.color)
num = 1
For Each f In .Records.Fields
List1.AddItem Field & num & : & f.Name
num = num + 1
Next f
ElseIf .LayerType = moImageLayer Then
Map1.Layers.MoveToBottom 0
Map1.Refresh
End If
End With
End Sub

Left Property
Applies To Ellipse Object, Rectangle Object

ProgrammersReference.pmd 324 10/28/2004, 10:00 AM


MapObjects Programmers Reference 325

Description Returns or sets the distance between the internal left edge of an object and the left edge of its
container.

Syntax object.Left [= value]

The Left property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A numeric expression specifying distance.

See Also Top Property

Example This example uses the Left property to set a border around a Map. When you resize the form,
the code maintains the dimensions of the border around the Map. To try this example, paste
the code into the Declarations section of a form containing a Map named Map1 that contains
at least one MapLayer. Press F5; then resize the form by dragging one of its corners.
Option Explicit

Private Sub Form_Resize()


Dim lBorder As Long
lBorder = Map1.Left
Map1.Move lBorder, lBorder, ScaleWidth - (lBorder * 2), _
ScaleHeight - (lBorder * 2)
End Sub

Length Property
Applies To Line Object

Description Returns the length of a Line object in map units.

Syntax object.Length [= distance]

The Length property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

distance A double indicating the length of the object. Read only.

See Also Area Property, Perimeter Property

ProgrammersReference.pmd 325 10/28/2004, 10:00 AM


326 MapObjects Programmers Reference

Example This example makes use of the Length property to report back the length of a Line segment
you select. To try this example, copy the code into the Declarations section of a form that
contains a Map named Map1 that contains a MapLayer with Line features. Press F5 and click
on a line.
Option Explicit

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X _


As Single, Y As Single)
Dim oRecset As MapObjects2.Recordset
Dim oPoint As MapObjects2.Point
Dim oField As MapObjects2.Field

Set oPoint = Map1.ToMapPoint(X, Y)


Set oRecset = Map1.Layers(0).SearchByDistance(oPoint, Map1. _
ToMapDistance(100), )

If Not oRecset.EOF Then


Set oField = oRecset(shape)
oRecset.MoveFirst reset the cursor
report the results
MsgBox Length: & oField.Value.Length
End If
End Sub

LevelField Property
Applies To LabelRenderer Object

Description Returns or sets the Field that contains level information for a LabelRenderer object.

Syntax object.LevelField [= value]

The LevelField property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list.

value A string expression that specifies a name of a Field in a Recordset. If


specified, the LabelRenderer makes use of the value of the specified Field
to control whether it will draw a label for a feature.

Remarks You can use levels to control whether a label for a feature draws on a Map. Levels are stored
in the LevelField associated with a LabelRenderer. If you set a LevelField and its value for

ProgrammersReference.pmd 326 10/28/2004, 10:00 AM


MapObjects Programmers Reference 327

the feature is outside the range of MinLevel and MaxLevel, the label for the feature will not
draw.

See Also TextSymbol Object

Example This example demonstrates how to set the LevelField property of a LabelRenderer and how to
control which levels the LabelRenderer draws by setting its MaxLevel property. To try this
example, paste the code into the Declarations section of a form containing a Map named Map1
that contains a MapLayer , two ComboBox controls named Combo1 and Combo2, a Slider
control named Slider1, and three Label controls named Label1, Label2, and Label3. The
Form_Load event code will position all the controls except the Map. Press F5. Select the name
of Field containing integer values that will serve as the LevelField and then select the name of
a Field whose values will provide the source of the text for the LabelRenderer. You can use the
slider to change the MaxLevel property.
Option Explicit

Private Sub combo2_Click()


Dim oRenderer As New MapObjects2.LabelRenderer

If Combo1.ListIndex <> -1 Then


Map1.Layers(0).Renderer = oRenderer
With oRenderer
.Field = Combo2.List(Combo2.ListIndex)
.LevelField = Combo1.List(Combo1.ListIndex)
.MinLevel = Slider1.Min
.MaxLevel = Slider1.Value
MsgBox Min = & Slider1.Min & max= & Slider1.Value
End With
Map1.Refresh
End If
End Sub

Private Sub Map1_MouseDown(Button As Integer, Shift As Integer, X As _


Single, Y As Single)

Dim oRect As Rectangle


Set oRect = Map1.TrackRectangle
Set Map1.Extent = oRect

End Sub

Private Sub Slider1_Click()


combo2_Click
End Sub

ProgrammersReference.pmd 327 10/28/2004, 10:00 AM


328 MapObjects Programmers Reference

Private Sub Form_Load()


Dim oRecset As MapObjects2.Recordset
Dim oField As MapObjects2.Field

Set oRecset = Map1.Layers(0).Records

For Each oField In oRecset.Fields


If oField.Type < moString Then
Combo1.AddItem oField.Name
End If
Combo2.AddItem oField.Name
Next

Label1.Caption = Level field


Label2.Caption = Text field
Label3.Caption = Level
Label1.AutoSize = True
Label2.AutoSize = True
Label3.AutoSize = True

Combo1.ListIndex = -1
Combo2.ListIndex = -1
Combo1.Text =
Combo2.Text =

Slider1.Min = 0
Slider1.Max = 3
Slider1.Value = 1
Slider1.LargeChange = Slider1.SmallChange

Label1.Left = Map1.Left
Label1.Top = Map1.Top + Map1.Height + Label1.Height * 1.5
Combo1.Left = Map1.Left + Label1.Width * 1.5
Combo1.Top = Label1.Top
Label2.Left = Map1.Left
Label2.Top = Label1.Top + Label1.Height * 2.5
Combo2.Left = Combo1.Left
Combo2.Top = Label2.Top
Label3.Left = Map1.Left
Label3.Top = Label2.Top + Label2.Height * 2.5
Slider1.Left = Combo1.Left
Slider1.Top = Label3.Top

End Sub

ProgrammersReference.pmd 328 10/28/2004, 10:00 AM


MapObjects Programmers Reference 329

Line Object
A Line object represents a geometric shape that has two or more vertices. A Line may have
one or many discontinuous Parts; a Line with two or more Parts is a multi-part Line. Each
member of the Parts collection is a Points object, which represent the vertices of that part of
the Line. A multi-part Line acts as a single shape for methods such as SearchShape.

You can retrieve the bounding rectangle of a line with its Extent property. In addition, you can
return the length of a Line with the read-only Length property. You can use the DistanceTo
method to return the distance in map units to another Point, Points, Line, Polygon, or
Rectangle object. The geometric methods Buffer, Difference, Intersect, XOr and Union are
supported for Lines. To return the set of Points at which another object crosses the Line, use
the GetCrossings method.

The Line object supports Linear Referencing, which makes it possible to record relative
positions on or along Lines using measures. You can test whether a Line object has measure
values for all of its vertices using the IsFullyMeasured property, and you can update the
measure values using the MultiplyMeasures, OffsetMeasures, SetMeasures,
SetMeasuresAsLength and UpdateMeasures methods. You can get and set the individual
measure values along the Line using the Measure property of the Point objects that make up
its vertices. The ReturnMeasure method can be used to calculate measure values along a
Line. You can also return Point and Line events using the ReturnLineEvent and
ReturnPointEvents methods.

You can create Line objects in Visual Basic with code like this:
Dim myLine as New MapObjects2.Line
Note that in order to add points that represent vertices to a new Line object you must first
create a Points object, which represents the vertices of a part of the Line. Each vertex of the
part should be added using a Point object. Once you have built up the part, add the Points
object to the Parts collection of the Line. This can be done in Visual Basic with code like this:
Dim new_line as New MapObjects2.Line
Dim pts As New MapObjects2.Points
Dim pt As New MapObjects2.Point

pt.X = 100
pt.Y = 100
pts.Add pt

pt.X = 200
pt.Y = 200
pts.Add pt

ProgrammersReference.pmd 329 10/28/2004, 10:00 AM


330 MapObjects Programmers Reference

pt.X = 300
pt.Y = 300
pts.Add pt

new_line.Parts.Add pts
See Also Points Object, TrackLine Method

Properties

Extent Length ShapeType

IsFullyMeasured Parts

Methods

Buffer Offset SetMeasuresAsLength

Difference OffsetMeasures Union

DistanceTo ReturnLineEvent UpdateMeasures

GetCrossings ReturnMeasure XOr

Intersect ReturnPointEvents

MultiplyMeasures SetMeasures

LineStyle Constants
MapObjects defines the following constants for use with line symbols.

Constant Value Description

moSolidLine 0 Solid line


moDashLine 1 Dash line
moDotLine 2 Dot line
moDashDotLine 3 Dash Dot line
moDashDotDotLine 4 Dash Dot Dot line
See Also Line Object, Symbol Object

ProgrammersReference.pmd 330 10/28/2004, 10:00 AM


MapObjects Programmers Reference 331

LinkGroup Constants
MapObjects defines the following constants for use with the Geocoder objects
MatchVariableIntersectionLink property.

Constant Value Description

mgLinkPrimary 0 Primary street link variable.

mgLinkSecondary 1 Secondary street link variable.

See Also Geocoder Object, MatchVariableIntersectionLink Property

ListIndices Method
Applies To Geocoder Object

Description Returns the logical indices associated with the Geocoder object as a MapObjects Strings
object.

Syntax Set variable = object.ListIndices

The ListIndices method syntax has these parts:

Part Description

variable A MapObjects Strings collection that stores the index definitions defined by
the Geocoder objects AddIndex method.

object An object expression that evaluates to an object in the Applies To list.

See Also AddIndex Method, BuildIndices Method, SearchQueries Property

Example See AddIndex Method

Locate Method
Applies To PlaceLocator Object

Description Locates place names that match a specified string and returns their geographic locations as a
Points collection

ProgrammersReference.pmd 331 10/28/2004, 10:00 AM


332 MapObjects Programmers Reference

Syntax Set variable = object.Locate( placeName)

The Locate method syntax has these parts:

Part Description

variable An object expression that evaluates to a Points collection.

object An object expression that evaluates to an object in the Applies To list.

placeName A string expression that specifies the place name to find.

Remarks Each Point in the Points collection represents the centroid of the feature which the placeName
was matched to. If MapObjects can not find the placeName, the Points collection will be
empty.

See Also Buildndex Method, FindAllPlaceNames Method, Indexed Property, PlaceNameTable


Property

Example See FindAllPlaceNames Method

LocateCandidate Method
Applies To Geocoder Object

Description Matches the specified address against a candidate address, and returns the corresponding
AddressLocation.

Syntax Set variable = object.LocateCandidate ( index)

The LocateCandidate method syntax has these parts.

Part Description

variable An object expression that evaluates to an AddressLocation.

object An object expression that evaluates to an object in the Applies To list.

index A numeric expression that specifies the relative position of a member of the
candidate group associated with the Geocoder object.

Remarks The Geocoder objects GenerateCandidates method generates a list of candidates for
matching. The candidates in the list are ranked by their score, with the first candidate in the list
being the one with the highest score. If GenerateCandidates returns
mgGeocodeSuccessMultipleBest as a GeocodeSuccessConstant, more than one candidate in

ProgrammersReference.pmd 332 10/28/2004, 10:00 AM


MapObjects Programmers Reference 333

the list have the same highest score. You can review the score of each candidate by examining
the objects Candidate property.

See Also AddressLocation Object, StreetTable Property, GenerateCandidates Method,


MatchVariableCount Property, IntersectionMatchVariableCount Property

Example See Geocoder Object

Location Property
Applies To AddressLocation Object

Description Returns the location of the match as a Point object.

See Also MatchScore Property, StreetSide Property

Syntax Set variable = object.Locati