Preface: An Introduction to MapX

MapInfo MapX

Developer Guide
v4.5

MapInfo Corporation
Troy, NY
2 MapInfo MapX Developer Guide v4.5
Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor
or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or
mechanical, including photocopying without the written permission of MapInfo Corporation, One Global View, Troy, New York
12180–8399.
©1992–2000 MapInfo Corporation. ALL RIGHTS RESERVED.
MapInfo Help ©1992–2000 MapInfo Corporation. ALL RIGHTS RESERVED.
MapInfo, MapInfo Professional, MapBasic, MapXtreme, MapInfo MapX, and the MapInfo Logo are registered trademarks of
MapInfo Corporation. All other marks used herein are the property of their respective owners.
Contact MapInfo Corporation on the Internet at: http://www.mapinfo.com
MapInfo Corporate Headquarters: MapInfo Europe Headquarters: Germany:

Voice: (518) 285-6000 Voice: +44 (0)1753 848 200 Voice: +49 (0)6142-203-400

Fax: (518) 285-6060 Fax: +44 (0)1753 621 140 Fax: +49 (0)6142-203-444

Sales Info Hotline: (800) 327-8627 email: uk@mapinfo.com email: germany@mapinfo.com

Federal Sales: (800) 619-2333

Technical Support Hotline: (518) 285-7283 Toll-free telephone support is available in the U.S. and Canada. Contact
Technical Support Fax: (518) 285-6080 your MapInfo sales representative for details. For international custom-
ers, please use the Technical Support Fax number.

WARNING: This software uses patented LZW technology for .GIF image compression and/or decompression. (Unisys United
States patent No. 4,558,302 and corresponding patents in Canada, France, Germany, Italy, Japan and the United Kingdom). GIF
images compressed or decompressed for transmission via the Internet or via any other on–line communication capability may
not be sold or licensed for revenue, or used by an Internet Service Provider or in paid advertisements unless the user first enters
into a written license agreement with Unisys. For information concerning licensing, please contact: Unisys Corporation Welch
Licensing Department C1SW19 Township Line & Union Meeting Roads P.O. Box 500 Blue Bell PA 19424 Fax: 215–986–3090
Portions of the data are the proprietary information of Roadnet Technologies, Inc., a United Parcel Service Company, and are
Copyright 1993. Roadnet Technologies, Inc. Portions of the software are derived from the Standard C Library, and are Copyright
1992, by P.J. Plauger, published by Prentice-Hall, and are used with permission.
This documentation reflects the contributions of almost all of the women and men who work for MapInfo Corporation. It was
specifically produced by Max Morton. Colleen Cox, Editor. Juliette Funiciello-Vunk, Associate Editor. These members of the
Documentation Department are indebted to MapInfo’s Quality Assurance Department and, of course, to all the members of the
Engineering team who labored on this project.
MapInfo welcomes your comments and suggestions.
MapInfo MapX v4.5
June 2000
4 MapInfo MapX Developer Guide v4.5
 Table of Contents
Preface: An Introduction to MapX
Welcome... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
About MapInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
New in MapInfo MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
New in MapX v4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
New in MapX v4.0 & 4.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Enhancements and Additions to MapX v3.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Enhancements and Additions to MapX v3.5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Enhancements and Additions to MapX v3.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Upgrading MapX v2.0 Applications to MapX Version 3 . . . . . . . . . . . . . . . . . . . . 18

Part I:
The MapX User Guide
Mapping at a Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Making MapX Work for You. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Overview of Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Learning About MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 2: MapX Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Creatable Objects in MapXMap Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Property Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
GeoSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Creatable Objects in MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 3: Mapping Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Organizing Your Data and Maps: An Overview of Tables. . . . . . . . . . . . . . . . . . . 42
What Are GeoSets? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Geosets Available with MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Map Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Putting Your Data on the Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The Power of MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter 4: Getting Started With MapX . . . . . . . . . . . . . . . . . . . . . . . . 53

 What Is MapX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Before Installing MapX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Installing MapX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Adding the Map Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Upgrading Visual Basic Applications From an Earlier Version of MapX . . . . . . 59
Upgrading C++ Applications From an Earlier Version of MapX . . . . . . . . . . . . . 60
Getting Started with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Getting Started with Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Getting Started with PowerBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Getting Started With Delphi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Getting Started with Lotus Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
MapX Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Where to Go Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 5: Mapping in Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Drawing LayersMaps as Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
The Layers Collection: Building Blocks of Your Map . . . . . . . . . . . . . . . . . . . . . . . 74
Some Properties of the Layers Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Some Methods of the Layers Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
The Layer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Layer Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Examining Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Checking a Layer’s Feature Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Zoom Layering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Generating Labels for a Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Raster Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Animation Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Drawing Layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Chapter 6: Putting Your Data on the Map . . . . . . . . . . . . . . . . . . . . . 95

What Is Data Binding? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
The Power of Adding Your Data to a Ma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
How to Add Your Data to a Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Dataset Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Datasets Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Using the Datasets.Add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

2 MapInfo MapX Developer Guide v4.5

 Table of Contents

Using the Fields Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Using the Fields.Add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Displaying Your Data as a Layer of Points (BindLayer) . . . . . . . . . . . . . . . . . . . 105
Making Your New Layer of Points a Permanent Layer . . . . . . . . . . . . . . . . . . . . 108
How Data Binding Uses the GeoDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
The Different Types of Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 7: Features and Selections . . . . . . . . . . . . . . . . . . . . . . . . . 115

What Is a Map Feature? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
What Is a Features Collection? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
What Is a Selection Collection? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Using the Features Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Understanding the Selection Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Feature Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Chapter 8: Thematic Mapping and Analysis . . . . . . . . . . . . . . . . . . 127

What Is Thematic Mapping? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Planning Your Thematic Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Types of Thematic Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Manipulating a Theme Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Customizing a Thematic Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Chapter 9: Finding Features on a Map . . . . . . . . . . . . . . . . . . . . . . . 151

Using the Find Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using theFindFeature Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Chapter 10: Using Drilldown Layers . . . . . . . . . . . . . . . . . . . . . . . . . 155

What Is a Drilldown Layer?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Terms and Concepts You Should Know . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
How to Develop a Drilldown Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Preparing a Drilldown Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Creating a Drilldown Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Resetting the Drilldown Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Drilldown Layer Limitations and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 165
For More Information... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Chapter 11: Accessing Data from a DBMS. . . . . . . . . . . . . . . . . . . . 167

Accessing Remote Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

MapInfo MapX Developer Guide v4.5 3

 Using the Layers.Add Method with a LayerInfo Object. . . . . . . . . . . . . . . . . . . . 169
Accessing Remote Tables through a .tab File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Mapping DBMS Data with X/Y Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Oracle Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
DBMS LayerInfo Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
DBMS Connection String Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
A MapX DBMS Layer Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Accessing Attribute Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Performance Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Caching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
The MapInfo Map Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Making a DBMS Table Mappable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Chapter 12: Using Coordinate Systems . . . . . . . . . . . . . . . . . . . . . 191

Basic Concepts of Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Obtaining a Coordinate System Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Querying the Properties of a CoordSys Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Displaying a Map in a Different CoordSys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Specifying X-Y Coordinates in a Different CoordSys . . . . . . . . . . . . . . . . . . . . . . 195
Displaying the Choose Projection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Summary of Parameters Used by Coordinate Systems . . . . . . . . . . . . . . . . . . . . 198
Using Settings from MAPINFOW.PRJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Applying an Affine Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Defining Custom Datums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Datum Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
For More Information... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Chapter 13: Working With Visual C++ . . . . . . . . . . . . . . . . . . . . . . . 209

Creating a Map in a C++ DialogUnderstanding the Sample Application . . . . . 210
Upgrading C++ Applications from an Earlier Version of MapX . . . . . . . . . . . . 211
Accessing MapX Properties and Methods in C++ . . . . . . . . . . . . . . . . . . . . . . . . . 212
Including MapX.cpp in Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Creating a MapX Control Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Creating Menu Items Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Handling MapX Events Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Using Custom Tools (C++ Example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

4 MapInfo MapX Developer Guide v4.5

 Table of Contents

Data Binding Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Adding a Shortcut Menu Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Using the Built-In Helper Dialogs from C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Handling MapX Exceptions Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Creating a Map in a C++ Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Chapter 14: MapX Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Creating Polygon Drawing Tools (Polytools)Overview of Standard Tools . . . . 232
Object Editing Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Node Selecting and Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Creating a Custom Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Creating Polygon Drawing Tools (Polytools) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Chapter 15: Exporting Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Methods for Exporting Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
ExportSelection Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Printing Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Chapter 16: Distributing Your MapX Application . . . . . . . . . . . . . . 249

MapX Customer Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Installing the MapX OCX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Installing Support for Spatial Server Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Installing Raster Format Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Installing Maps and Geosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Adding Keys to the Windows Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Passing in the MapX License String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Redistributing Your MapX Application with MrSID . . . . . . . . . . . . . . . . . . . . . . 264

Part II:
The MapX Objects
Affine Transform object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Annotation Object and Annotations Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 269
BindLayer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
BitmapSymbol Object and BitmapSymbols Collection . . . . . . . . . . . . . . . . . . . . . 281
CoordSys Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Dataset object and Datasets collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Datum Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

MapInfo MapX Developer Guide v4.5 5

 Feature Object and Features Collection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
FeatureFactory Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Field object and Fields collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Find object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
FindFeature object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
FindMatch Object and FindMatches Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 359
FindResult Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Geoset Object and Geosets Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Graphic Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
IndividualValueCategory object and IndividualValueCategories collection. . 369
LabelProperties Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Layer Object and Layers Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
LayerInfo Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Legend Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
LegendText Object and LegendTexts Collection . . . . . . . . . . . . . . . . . . . . . . . . 429
Map object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
MultivarCategory Object and MultivarCategories Collection. . . . . . . . . . . . . . . 467
NotesQueryInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
NotesViewInfo Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
ODBC QueryInfo Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Parts Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Point Object and Points Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
RangeCategory Object and RangeCategories Collection . . . . . . . . . . . . . . . . . . . 483
Rectangle Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
ResolveObject Object and ResolveObjects Collection . . . . . . . . . . . . . . . . . . . . . . 491
RowValue Object and RowValues Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Selection Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
SourceRow Object and SourceRows Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Style Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Theme Object and Themes Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
ThemeProperties Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Title Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Variable object and Variables collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Part III:
MapX Reference Informatio
tMapX Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

6 MapInfo MapX Developer Guide v4.5

 Table of Contents

MapX Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
Creating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Geoset Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
OLE_COLOR Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
IDispatch Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Managing MapX Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Using the Geoset Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Using the Geodictionary Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Command Line OptionsThe Geodictionary File . . . . . . . . . . . . . . . . . . . . . . . . . . 720
User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Command Line Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Custom Dataset Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

MapInfo MapX Developer Guide v4.5 7

8 MapInfo MapX Developer Guide v4.5
Welcome...
to the MapInfo MapX Developer’s Guide! This book is organized into three parts:

• Part I: The MapX User’s Guide

• Part II: The MapX Objects
• Part III: MapX Reference Information.
In previous versions of MapInfo MapX we had printed two books: (1) "The MapX
Developer’s Guide", and (2) "The MapX Reference Guide". For the sake of usability and
efficiency, we have decided to streamline the books by eliminating printed code samples and
redundancies between the two books, then merge them into a single, more useful document.

Note: Code samples for MapInfo MapX are still available in the MapX Online Help
System. In fact, the reasoning behind the decision to remove them from the printed
manual was that since we’ve added such a significant number of examples in three
different languages (Visual Basic, C++, & Delphi), printing them made the
documentation overly cumbersome to use.
Part I: The MapX User’s Guide, is a narrative on mapping concepts and information on how
to effectively use the of functionality within MapInfo MapX.

Part II: The MapX Objects, is an alphabetically organized reference that describes the objects,
properties, methods, and events associated with MapInfo MapX. Most entries includes a
purpose, syntax, remarks, and cross-references to other entries (if necessary). In previous
releases of MapInfo MapX, we had printed example code for a few methods and properties.
Now, example code has been written in Visual Basic, C++, and Delphi for more than 75% of all
methods & properties of MapX. Because of this exponentially expanding page count, we have
decided to make most code samples available exclusively in the MapX Online Help System.
Part III: MapX Reference Information contains many useful topics. There are topics on MapX
Events, a complete listing of MapX error codes and descriptions of each, Constants,
Expressions, Geoset Key information, OLE_Color values, IDispatch, topics on the Geoset and
Geodictionary Managers, and Custom Dataset Support. Much of the information in this
section is new to MapX documentation.
The material in this book reflects the information available at the time of publication and is
essentially the same as the information contained in the MapX Online Help System. However,
in some cases, more up-to-date information may become avail able and will appear in the
MapX Online Help before the actual release of the next version of MapInfo MapX. Be sure to
visit www.MapX.com to download the most current version of the Help System.

The MapInfo Documentation department welcomes all comments and suggestions. You may
eMail them to MapXDocs@MapInfo.com.
 Document Conventions
The MapInfo MapX Developer Guide uses some of the typographic conventions in its syntax
descriptions similar to those found in the Visual Basic documentation. Consult the
Microsoft Visual Basic Programmer’s Guide or the Microsoft Visual Basic Language
Reference for a listing of these conventions.

In the entries for methods, you will find a syntax section. For this version of MapInfo
MapX, we have standardized the convention used for displaying syntax as follows:

[ Return Value= ]OBJECT.Method (parameter, [optional parameter])

Part Description
[ Return Value= ] The return value of a property (if there is one) will always be on
the outer left of the syntax line in brackets with the assignment
operator on the right.
OBJECT This represents the object that the method is being used for.
Method This represents the method.
(parameter) Parameters will be in parentheses.
[optional parameter] Optional parameters will be in brackets within the parameter
parentheses.

About MapInfo
MapInfo MapX is produced by MapInfo Corporation. MapInfo makes and sells a full line of
mapping software and data products.

If you need information on other mapping solutions or data products, contact us at the
phone and fax numbers listed below, or visit our web sites.

Note: The MapX web site (www.mapx.com) offers developers the latest sample
applications and versions of the MapX Online Help System, plus a bulletin board
to collaborate with other MapX developers.
If you need assistance working with MapInfo MapX, our technical support specialists can
help. Technical support for MapX includes referrals to documentation, assistance with error
messages and suggestions for causes of error messages. (Telephone technical support for

2 MapInfo MapX Developer Guide v4.5

 About MapInfo

MapX is limited to customers who have purchased MapX.) You can also arrange for MapX
training, or obtain customized assistance from MapInfo's Developer Services.

Contact Information for MapInfo Corporate Headquarters

• MapX Web Site: http://www.mapx.com
• MapInfo Web Site: http://www.mapinfo.co
• Main Phone: 518.285.6000
• Main Fax: 518.285.6060
• Sales Information Order Hotline: 800.327.8627
• Federal Sales: 800.619.2333
• Sales Fax: 518.285.6070
• MapX Sales e-mail: mapx.sales@mapinfo.com
• Technical Support Hotline: 518.285.7283
• Technical Support Fax: 518.285.6080
• Training e-mail: training@mapinfo.com
• Training Phone: 800.552.2511
• Developer Services e-mail: devservices@mapinfo.com
• Developer Services Phone: 518.285.7175

MapInfo MapX Developer Guide v4.5 3

 New in MapInfo MapX
This section summarizes the improvements and enhancements made to MapX for versions
4.5, 4.01, 4.0, 3.5.1, 3.5, and 3.0. If you are upgrading from MapX version 2, you will want
pay close attention to the features added in version 3.0, and how to upgrade your existing
MapX version 2 applications.

New in MapX v4.5

• Oracle 8.16 support: MapX provides support for accessing, mapping, and
updating Oracle Spatial data in Oracle 8.16. It also supports prefetch code for
Oracle via OCI. This optimizes the fetching of rows, by reading a number of rows at
a time.
• DAO 3.6 Support: MapX now supports this datatype. Also, please see the
improved Datasets.Add help topic for expanded code samples.
• Date columns support in datasets: MapX now supports a Date datatype for fields,
in addition to Numeric and String. That is, when you import a dataset from an
external source, the date field will now import as a date column rather than a string,
or not import at all. Please see Datasets.Add.
• Layer creation: With the addition of two new parameters in the LayerInfo object
and an expanded Fields collection, developers can create new native tables or a
temporary table (i.e the ablility to create tab files from within mapx).
Click here for an showing how this is done.
• New functions: The additional functions are to provide more flexibility in
expressions for Layer.Search method and Datasets.Addfield method.
The new function are:
• Buffer
• DeformatNumber$
• Format$
• FormatDate$
• FormatNumber$
• StringCompare
• StringCompareIntl
• StringToDate
• ObjectType

4 MapInfo MapX Developer Guide v4.5

 New in MapX v4.5

• Variable Substitution in Layer.Search: An expression will now be able to contain

references to variable names. A collection of variables will be passed to the
Layer.Search method as a new optional parameter.
• Variable object andVariables collection : MapX supports variable substitution in
expressions. The new Variable object and Variables collection are key components
in MapX’s ability to mix attribute and geographic criteria in expressions.
• Node Editing and Selecting: MapX provides programmers with the ability to
select and edit noded objects on a map. Also see the Map.FeatureEditMode
property
• Date Field Support: We fully support date fields in ranged and individual value
themes.
• Delphi 5 Support: MapX incliudes Delphi 5 dataset support.
• Map.MatcheNumericFields property: This property has nbeen enhanced to not
only control matching on numeric fields, but DATE fields as well.

MapInfo MapX Developer Guide v4.5 5

 New in MapX v4.0 & 4.0.1
New in 4.0.1
• CustomCursor support: The miInfoCursor (27) changed from white to black to be
more visible. The old info cursor is now miInfoCursorOld (39). miCustomCursor
was changed from 39 to 40. See: Map.MouseIcon property & the
Map.MousePointer property.

New Features for 4.0

• Grid Display & Transparent Rasters: MapX opens grids and 24-bit transparent
rasters.
• Raster Auto Registration: MapX can open a raster file (not a .tab file) directly and
auto-register it using the info stored in the raster file. MapX can open a *.tif (Geotiff
format) raster image directly and auto-register it using the image tag information
stored within the Geotiff raster file itself. A Geotiff image does not use an
associated *.tfw file. See LayerInfo object.
• ADO & RDO Support: MapX supports both ADO & RDO as data sources for
databinding.
• True color support: MapX uses 24-bit color by default.
• DB2 Support: MapX supports the opening of remote layers from DB2 databases.
• ESRI shape file support: Open ESRI *.shp format files directly using Layer Info
object.
• Faster Layer Access: Performance has been improved for repeated layer and dataset
operations.
• Vector Symbol Support: MapX now displays vector symbols (MapInfo 3.0
compatible).
• Object Creation and Editing Tools: The select tool now allows for dragging,
resizing, and deleting features in editable layers. Four new creation tools added.
They are:
(1) miAddPointTool
(2) miAddLineTool
(3) miAddPolylineTool
(4) miAddRegionTool.
• Oracle 8i Database support: MapX supports Oracle 8i Data.

6 MapInfo MapX Developer Guide v4.5

 New in MapX v4.0 & 4.0.1

Feature Enhancements for 4.0

• User-Defined Cursors for Custom Tools : Now in MapX, a programmer can use
Map.CreateCustomTool to associate his Tooled with a built-in drawing behavior
and a built-in cursor. Optionally, a programmer can specify cursors to use when the
shift or control keys are held down while the tool is being used. If the
ControlCursor or ShiftCursor is not specified, the DefaultCursor will be used
(whether it is stock or custom).
• Remove Requirement for the Geodictionary: MapX now isolates the use of the
Geodictionary so that it is only required for automatching.
The Geodictionary key in the registry now:
(1) Could contain a full file spec for the Geodictionary file. The effect is that the
data directory is set to be the path leading to the Geodictionary file named by this
key. The in-memory geodictionary is initialized from the Geodictionary file and
layers contained in the Geodictionary can be automatically matched against it too.
Layers added to the map are still added to the in-memory geodictionary so they can
be auto matched against.
(2) Could contain just a path specification. The data directory is set to be the path
named by this key. The in-memory geodictionary is initialized empty. Layers
added to the map are still added to the in-memory geodictionary so they can be
auto matched against.
(3) Could not exist at all. The in-memory geodictionary is initialized empty. Layers
added to the map are still added to the in-memory geodictionary so they may be
auto matched.
• Faster access to a features Nodes data: MapX exposes the node data in such a way
that the user can query for all the nodes in an object with one pass, then have them
returned in a SafeArray containing the node data (See Feature.Nodes).
• Path handling: MapX is more consistent in the way that it handles file paths.

Enhancements to Properties, Methods, and Events for 4.0

• AddFeatureToolUsed Event: This event is called whenever the user uses one of the
standard object creation tools (miAddPointTool, miAddLineTool, miAddPolylineTool, or
miAddRegionTool). The behavior of this event is similar to the PolyToolUsed Event.
• Feature.CenterX & Feature.CenterY This now returns the true center of a text
feature.
• Layer.AddFeature: Now, there is a new optional parameter called RowValues that
specifies the attributes to update. Attributes can be from any datasets bound to the
layer. The Source Parameter can also be a feature object of type miFeatureTypeNull
which will set the object column to a null feature object.

MapInfo MapX Developer Guide v4.5 7

 • Layer.DeleteFeature: The first parameter now accepts a FeatureKey. FeatureID, the
previous first parameter still works as it did before, but it is recommended that you use the
new FeatureKey parameter for the sake of expedience and clarity in your code.
• Layer.UpdateFeature: Now, there is a new optional parameter called RowValues
that specifies the attributes to update. Attributes can be from any datasets bound to
the layer. The Source Parameter can also be a feature object of type
miFeatureTypeNull which will set the object column to a null feature object.
• Layers.Add: Now, the first parameter is aVARIANT which can be either a
LayerInfo object or a string. See LayerInfo object.
Note: AddServerLayer is no longer the preferred way of opening a remote layer via
Layers.Add. Calling the LayerInfo object is more efficient.
• Map.InfotipPopupDelay: This allows the programmer to specify the duration of
time the user needs to have the mouse icon over an object before the InfoTip (if
specified) appears.
• Map.InfoTipSupport: This allows the programer to specify whether or not MapX
should display pop-up InfoTips.
• Map.MouseIcon: This lets the programer specify a custom cursor to use as the
default mouse cursor in MapX. (See the Map.MousePointer property)
• MapDraw event: This event will be called once before a draw, and once after a draw is
completed. There is one parameter which states whether a draw is beginning or ending.
• ResolveDataBindEx event: This event has the same function as the ResolveDataBind
event, but it passes a collection of ResolveObjects instead of a string array.

Additional Objects for 4.0

• FindResult object: This will return information about the FindRC in the form of
properties to make it easier to access the result of the find.
Note: This object was renamed from FindResults object.
• LayerInfo object: The LayerInfo object stores parameters to be passed to the Layers.Add
method, and specifies type from the LayerInfoTypeConstants.
Note: AddServerLayer is no longer the preferred way of opening a remote layer via
Layers.Add. Calling the LayerInfo object is more efficient.
• RowValue object and RowValues collection: The RowValue object represents a single
value for a field in a dataset. RowValues collection is a group of RowValue objects. These
objects are used with Layer.InsertFeature, Layer.UpdateFeature, Feature.Update, and
Dataset.RowValues to read/update attribute fields in a MapInfo table.

Additional Properties for 4.0

• BindLayer.ReferenceLayerField: This specifies what field (by number, starting at 1) in
the mapinfo table to bind to. If not specified, MapX will sample the source data for the
column and choose the column with the highest match rate. If none match, then the first
column is chosen.

8 MapInfo MapX Developer Guide v4.5

 New in MapX v4.0 & 4.0.1

• Dataset.RowValues: Determines what a row can be: long row ID, string serialized
key, or feature object to get key from.
• Feature.FeatureKey: Returns the Key of the feature. Each feature in a layer contains a
unique key within the layer. This is a string value and is read-only. This is a replacement for
Feature.FeatureID (which still works as it did before, but it is recommended that you use the
new FeatureKey property).
• Feature.Nodes: This read-only property exposes the node data in such a way that
the user can query for all the nodes in an object with one pass, then have them
returned in a single, contiguous block of memory
• Find.CloseMatchMax: This returns the maximum number of close matches loaded in
FindResult from SearchEx.
• LabelProperties.PartialSegments: Setting this value to true enables MapX to label
polylines, even if only a small part of the polyline is currently visible. However, this
will not work for other features/objects, as it only applies to autolabels.
• Layer.DataSets: This read-only property is a DataSets collection that is bound to
the map layer it is associated with. This collection is a subset of the full DataSets
collection (Map.DataSets). The objects within Layer.DataSets are the same as the
objects within Map.DataSets.
• Layer.Editable: This property allows a selection in the layer to be edited (moved, resized,
or deleted).
• Layer.ShowCentroids: This read/write property draws object centroids (regions
only) when set to true.
• Layer.ShowLineDirection: This read/write property draws an arrow indicating
line direction (lines and poly lines only) when set true.
• Layer.ShowNodes: This read/write property draws a small box around the node of
an object when true.
• Layers.InsertionLayer: This read only property specifies what layer new objects
will be inserted into by the built-in object editing tools.
• LayerInfo.Type : This is a read/write property whose value is one of the
LayerTypeConstants.
• Map.MatchThreshhold: This is the minimum threshold percentage required for matching
a map layer with a data source. It is used to control auto-matching during Datasets.Add.
• Map.PanAnimationLayer: This property controls whether the animation layer (if there is
one) is drawn into the backing store when the pan tool is in use so that the contents of the
layer are dragged around with the rest of the map. The default is FALSE.
• RowValue.Dataset: This property is used to specify which dataset the value is for.
• RowValue.Field: This property is used to specify the field in the dataset that the
value is for.
• RowValue.ReadOnly: This property determines whether or not the properties can
be set on the object.
• RowValue.Value: This property is used to specify the value for the field.

MapInfo MapX Developer Guide v4.5 9

 • RowValues.Count: This read-only property specifies the number of rows in the
RowValues collection.
• RowValues.ReadOnly: This read-only property specifies whether or not properties can be
set on the collection.
• Style.MaxVectorSymbolCharacter: This read-only property returns the maximum
valid code for a vector symbol.
• Style.MinVectorSymbolCharacter: This read-only property returns the minimum
valid code for a vector symbol.
• Style.SymbolVectorColor: This method determines the color of the vector symbol.
• Style.SymbolVectorSize: This method determines the point size of the vector
symbol.
• ThemeProperties.ApplyAttribute: This controls which of the theme category’s
style attributes are actually applied to the theme. It can be used to selectively
modify either the color or the size of the categories of the theme, without affecting
the other’s appearance.
• ThemeProperties.BarFramed: This boolean property is set to false and specifies
whether the bar objects are drawn with frames.
• ThemeProperties.BarFrameStyle: The style of the frame of the bar chart.
• ThemeProperties.BarGraduatedStack: Specifies if the stacked bars should be
graduated.
• ThemeProperties.BarIndependentScale: This property replaces the
ThemeProperties.Independent property.
• ThemeProperties.BarStacked: Specifies whether to draw stacked bar charts.
• ThemeProperties.BarWidth: This property replaces the ThemeProperties.Width
• ThemeProperties.BorderStyle: The style of the border of a pie or bar chart.
• ThemeProperties.ColorMethod: This specifies the method used to interpolate
between the top and bottom range colors to get the colors of the intermediate
ranges.
• ThemeProperties.DotColor: The color of the dots in a dot density theme.
• ThemeProperties.GraduateSizeBy: Controls the graduation method used for
graduated pies, bars, or symbols.
• ThemeProperties.InflectionColor: This is an OLE_COLOR value. It indicates the
color of the inflected range.
• ThemeProperties.InflectionRange: This controls which range takes on the color
specified in InflectionColor. The ranges above and below the InflectionRange will
have a mixture of InflectionColor and the top and bottom range colors,
respectively.
• ThemeProperties.InflectRanges: In a ranged theme, an inflection point can be
used to separate the ranges into two sections. When InflectRanges is true, the colors

10 MapInfo MapX Developer Guide v4.5

 New in MapX v4.0 & 4.0.1

in the ranged theme will spread from the top range color to the InflectionColor, then
from the InflectionColor to the bottom range color.
• ThemeProperties.NegativeSymbolStyle: The style of the negative symbol in a
graduated symbol theme.
• ThemeProperties.PieClockwise: Controls whether the pie wedges are drawn in
clockwise order
• ThemeProperties.PieGraduated: This property replaces the
ThemeProperties.Graduated property.
• ThemeProperties.PieHalfPies: Specifies whether to draw half pies instead of
whole pies.
• ThemeProperties.PieStartAngle: The start angle that the first pie wedge is drawn.
• ThemeProperties.PositiveSymbolStyle: This property replaces the
ThemeProperties.SymbolStyle property.
• ThemeProperties.RoundBy: This specifies the interval to round the ranges to.
• ThemeProperties.RoundRanges: This controls whether the boundaries of the ranges are
rounded off.
• ThemeProperties.ShowNegativeValues: This property specifies whether to show
negative values in the graduated symbol theme.

Additional Methods for 4.0

• Coordsys.Clone: This returns a copy of a CoordSys object.
• DataSet.AddField: This allows a field ('column') to be added to a dataset that is an
expression containing functions, operators, and datasets fields (from the current dataset
only).
• Features.Clone: This returns a copy of a features collection.
• Find.SearchEx: This extends the functionality of the search method. It enables the search
engine to look for the closest matches returned in a collection.
• Layer.BeginAccess: This method will open and lock the table for read or write
access. This improves the performance for repeated layer and dataset operations.
You must call EndAccess once for each call to BeginAccess method.
• Layer.EndAccess: This method unlocks map tables. You must call EndAccess once
for each call to BeginAccess method.
• Layer.Refresh: This method flushes the cache from the layer. This is useful for server
layers that have caching turned on.
• Layer.Search: This method exposes the power of SQL queries. The expression (the
"where-clause" portion of the statement) is evaluated for each row in the Layers
table, and a Features collection is returned.
• LayerInfo.AddParameter: Is the set of parameters required for a given call to the
Layers.Add method, and is determined by the type of LayerInfo object passed.

MapInfo MapX Developer Guide v4.5 11

 • RowValues.Add: This property adds a RowValue object to a specified RowValues
collection.
• RowValues.Clone: This method clones specified row values from a dataset and returns a
new RowValues object. The clone is not read-only or read/write.
• RowValues.Item: This returns a specific RowValue object from the RowValues
collection.
• RowValues.Remove: This method removes a specified RowValue object from the
collection.
• RowValues.RemoveAll: This method removes all RowValue objects from a
RowValues collection.

Enhancements and Additions to MapX v3.5.1

• Write capability, inserts and updates, directly to SpatialWare layers: If you have
added a SpatialWare layer through the AddServerLayer method, any edits or
changes to that map layer will be committed to the SpatialWare table. See
Feature.Update, Layer.UpdateFeature, Layers.AddFeature, and Accessing Remote
Spatial Data.
• Export Style Samples: The Style object has four new methods that allow you to
export symbol, region, line and text style samples. The methods are
ExportSymbolSample, ExportRegionSample, ExportLineSample, and
ExportTextSample.
• Rotating Text objects: The new TextFontRotation property of the Style object allows
you to control the number of degrees to rotate (clockwise) a Text object. Currently
valid only for Feature objects.
• AllOthers Range Category: The new AllOthersCategory property of the
RangeCategories collection and the new AllOthersCategory property of the
IndividualValueCategories collection allow you to define a category for all ranges
not in a ranged or individual categories theme. The text that appears in the legend
for the AllOthersCategory range category object can be set with the
LegendTexts.AllOthersText property.
• Returning the Feature Id From a Feature Name: Given a name, the new
FeatureIDFromFeatureName property of the Layer object returns the ID of the
feature with that name.
• Select a Feature by FeatureID: The new SelectByID method of the Selection
collection allows you to select a feature by FeatureID.
• Add a Feature by FeatureID: The new AddlByID method of the Features collection
allows you to a add a Feature object with the specified FeatureID to the Features
collection.

12 MapInfo MapX Developer Guide v4.5

 Enhancements and Additions to MapX v3.5

• Remove a Feature by FeatureID: The new RemoveByID method of the Features

collection allows you to a remove a Feature object with the specified FeatureID from
the Features collection.
• Control the Wait Cursor: The new WaitCursorEnabled property of the Map object
allows you to turn the Wait Cursor on or off manually.
• Added New Parameter to Layers.AddServerLayer: Takes a LayerCacheConstants
value. MiLayerCacheOn, which is the default, will keep attributes and objects that
have been read in memory; if you zoom in they do not need to be fetched from the
database. Since MapX looks in memory for a record, you will not see the latest
updates. If MiLayerCacheOff, all data will be fetched from the database; it will give
the most up to date data but will be less efficient.
• Added a new Dataset type, the safe array dataset: It is a COM dataset (needs to be
registered via regsvr32.exe before it can be used) that implements only
IMMapXStaticDataset (it does not do dynamic binding). A new
DatasetTypeConstant has been added, miDataSetSafeArray =9. To use this dataset,
the data reference (SourceData parameter to the Datasets.Add method) should be a
VARIANT that contains a safearray full of the data to be bound.

Enhancements and Additions to MapX v3.5

The following overview summarizes the improvements made to MapX for version 3.5.

Performance Enhancements
• Improved XY and PointRef Binding speed.
• Improved speed of the Lotus Notes datasets.
• Improved map drawing speed.
• Support for more raster import formats including GIF, JPEG, and PNG.
• New Delphi Native Dataset for Delphi 3.0.

Feature Enhancements
• Create Themes Faster for Server and Drilldown Layers: When creating a theme
with Themes.Add, computing ranges for layers with large numbers of rows, such as
drilldown or server layers, can take some time. The new ComputeTheme parameter
of the Add method lets you create a non-compute theme for any theme type. A non-
compute theme gives you the ability to create a theme without having the ranges
automatically calculated for you. You can then create the ranges yourself. This is a
faster way for drilldown and server layers. See Themes.Add, DataMin, DataMax,
ComputeTheme, and Value. This feature also works in conjunction with
IndividualValueCategories, MultivarCategories, and RangeCategories.

MapInfo MapX Developer Guide v4.5 13

 • NADCON Support: Beginning with MapX 3.5, the NADCON algorithm is used to
convert coordinates between NAD 27 and NAD 83 if those coordinates lie within
the areas covered by NADCON (United States, Puerto Rico, and the Virgin Islands).
If the coordinates lie outside those areas, or if they use datums other than NAD 27
or NAD 83, MapX uses the Molodensky or Bursa-Wolfe conversion methods. See
Datum Conversion.
• Intellimouse Support: The Intellimouse provides a wheel as a third (middle) button
on the Microsoft mouse. The Mousewheel will zoom the map when rolled, scroll the
map up and down when the wheel is rolled with the control key down, and
”AutoScroll” when the middle button is held down and moved away from the
mouse click point. A property,MouseWheelSupport, will describe the level of
Intellimouse support: None, Zoom/Scroll only (no AutoScroll), or Full. A
MouseWheel event allows you to override the built-in behavior. Note that for use in
Visual Basic for Windows 95, you need to have a third party .OCX in order to get the
mouse events on a Visual Basic form.
• Incremental Drawing of Map: Currently, the map is drawn to an offscreen bitmap;
when the offscreen map is complete, it is bit block transferred to the screen. The
Map.RedrawInterval property determines how often to transfer the map to screen
as is it being drawn in memory.
• Matching on Numeric columns: This property controls matching on numeric fields.
This property appears on the Data (design time) property page. If
MatchNumericFields is true, then numeric fields are considered candidate keys
(along with the alphanumeric fields) when MapX is auto matching. If it is false, then
numeric columns are not considered when doing auto matching. See Data Binding
overview.
• Interleaved Line Styles: The ability to create intersections on your maps that really
look like intersections and specify Line Widths in measured units, rather than
pixels. This makes it much easier to determine what your printed maps will look
like. See the Style.LineInterleaved property.
• Pen Styles: New mapx.pen file contains many new pen styles.
• Node Limit: The maximum number of nodes for regions and polylines has been
increased to 1,048,572 nodes for a single polygon region or polyline. The limit drops
by seven nodes for every two additional polygons. If an object with more than 32K
nodes is saved and the table is read in a version of MapX prior to version 3.5, the
object(s) will not be visible. Objects in the table that do not exceed the 32K limit will
be visible.
• Support for spatial predicates and functions in SQL queries submitted to
SpatialWare:
Previously, you were limited to non-spatial SQL as in:

SELECT SW_GEOMETRY, SW_MEMBER, CUSTOMER_NAME FROM CUSTOMER

WHERE CUST_ID > 100000;
Now, you can include spatial operates as in:

14 MapInfo MapX Developer Guide v4.5

 Enhancements and Additions to MapX v3.5

SELECT SW_GEOMETRY, CUST_ID, ST_AREA (SW_GEOMETRY)

FROM CUSTOMER, ZIPCODE
WHERE ST_OVERLAPS(CUSTOMER.SW_GEOMETRY, ZIPCODE.SW_GEOMETRY)
AND ZIPCODE = ’12345’;

Enhancements to Properties, Methods, and Events

• The new ComputeTheme parameter of the Theme.Add method lets you create a
non-compute theme. A non-compute theme gives you the ability to create a theme
without having the ranges automatically calculated for you. You can then create the
ranges yourself. This is a faster way for drilldown and server layers. See also
DataMin, DataMax, and ComputeTheme.
• There are new ColorConstants for system colors such as
miColorWindowBackground.
• The DLG option of the ConnectString property controls the display of the
connection dialog box:
• You can now pass a Rectangle object to the CreateRegion method which creates a
region using the four corners of the rectangle.

Additional Properties, Methods, and Events

• The ActiveAnnotation method returns the currently selected annotation (or NULL
if no annotation is selected).
• The BackColor property controls what color the background of the map is ’erased’
with before drawing the map.
• The Border property controls whether or not to draw the title’s border.
• The ComputeTheme, DataMin, and DataMax properties control whether themes
are computed and the minimum and maximum values to set the range for
computed themes.
• The DrawLabelsAfter property allows for better control over where labels are in the
drawing order.
• The LineInterleaved property is used to make a pen style interleaved if that pen
style supports being interleaved with the LineSupportsInterleave property.
• The LineSupportsInterleave property is a read-only boolean property which
denotes whether a given pen style supports interleave or not.
• The LineWidthUnit property controls the unit of measurement for the line width.
The width is specified in either pixels (default) or tenths of points, by specifying a
StyleUnitConstants value.
• The MapInitialized event is called immediately after map initialization is complete.
It serves to notify the container application of the best time to do any necessary run-
time configuration.

MapInfo MapX Developer Guide v4.5 15

 • The MapScreenWidth and MapScreenHeight properties make it easier to position
legends.
• The MouseWheelSupport property controls the level of Intellimouse support:
None, Zoom/Scroll only (no AutoScroll), or Full.
• The PaperHeight and PaperWidth properties contain the paper height and width of
the legend in Map.PaperUnit units.
• The PrintLegend method prints the legend in the specified rectangle to the
specified device context.
• The RegionBorderWidthUnit property controls the unit of measurement for the
region border width. The width is specified in either pixels (default) or tenths of
points, by specifying a StyleUnitConstants value.
• The Datasets.RemoveAll method removes all Dataset objects from the collection.
• The Fields.RemoveAll method removes all Field objects from the collection.
• The Layers.RemoveAll method removes all Layer objects from the collection.
• The Parts.RemoveAll method removes all Parts objects from the collection.
• The Points.RemoveAll method removes all Point objects from the collection.
• The Themes.RemoveAll method removes all Theme objects from the collection.
• The SearchPath property allows the user to set the Search Path dynamically. This
property is available at run-time only.
• The ShowCount property controls whether or not to show on the legend the count
portion of the ranges.
• The Value property gets or sets the value used in an individual value theme.
• The Visible property controls whether ranges are visible for the legend.
Note: The following section summarizes the improvements made to MapX for version
3.0. If you are upgrading directly from MapX version 1, you also might want to
read about features added in version 2.

Enhancements and Additions to MapX v3.0

The following overview summarizes the improvements made to MapX for version 3.0.

• MapX now provides support for coordinate systems and map projections, including
support for custom datums and affine transformations. For details, see the
discussion of Coordinate Systems.
• A new type of map layer, the Drilldown layer, allows users to explore the map by
pointing and clicking. If you want to see more detail about a particular region, click
on that region; the region is replaced by smaller, more detailed features.

16 MapInfo MapX Developer Guide v4.5

 Enhancements and Additions to MapX v3.0

• Spatial Server Access (SSA) is a powerful new feature that allows developers to
connect to live data stored in spatial servers, such as MapInfo's SpatialWare running
on Oracle and Informix databases. Spatial servers allow companies to host their
map data in their enterprise database for central management and security. Spatial
servers like SpatialWare offer advanced query processing and increased
performance on the server for an organization's spatial data. For details, see
Accessing Remote Spatial Data.
• A new Dynamic Data Binding feature improves performance when you use ODBC
to access live data on a large database server. Ordinarily, when you bind data, MapX
makes a static copy of data when the database is opened. A new, optional argument
of the Datasets.Add method lets you specify that the data binding should be
dynamic, in which case MapX grabs data in a live mode, only copying data as it is
needed. Dynamic data binding is also supported if you develop your own custom
dataset support.
• New object processing capabilities allow you to combine, buffer, intersect, or erase
point, line and region features. For details, see the new FeatureFactory object.
• The list of standard tools now includes a polygon select tool. This tool allows the
user to draw a polygon, and then selects features inside the polygon. Also, the
CreateCustomTool method now takes additional, optional parameters, allowing
you to specify different cursors that should be used if the user holds down SHIFT or
CTRL while using the tool.
• You now can display point features using either TrueType font symbols (as in earlier
versions of MapX) or bitmap symbols. TrueType font symbols now support a new
Style.SymbolFontRotation property, which allows you to rotate symbols. Also, the
Style object now supports a new LineStyleCount property, and a new
RegionTransparent property that lets you create transparent fill patterns.
• MapX now includes a new utility, GeosetManager.exe, which makes it easier to
create your own geosets. You can run this utility from the Start menu.
Note: MapX 3.0 also provides source code for a sample Visual Basic 5 project called
GeosetManager, which provides functionality very similar to GeosetManager.exe.
However, you do not need to install this sample VB project to run the
GeosetManager.exe utility.
• The BindLayer object has several new properties: The CoordSys property specifies a
coordinate system when you create a layer in xy or pointref binding. The Filespec
property allows you to create a permanent layer instead of a temporary one. The
KeyLength property specifies the length of the character column in the resulting
layer.
• A new Bounds property returns a rectangle that represents the minimum bounding
rectangle. Several objects—the Map object, Layers collection, Layer object, Features
collection, and Feature object—all support the Bounds property. The Bounds
property is useful when you need to determine the geographic extents of one or
more features on the map (e.g. so you can zoom out far enough to see all of the
features). For an example see Zooming to Show an Entire Layer.

MapInfo MapX Developer Guide v4.5 17

 • The Map object supports a new SaveMapAsGeoset method, which creates a new
Geoset based on the current status of the map (layer settings, zoom level, etc.).
• The Theme object supports a new Fields property, which returns a Fields collection.
• Thematic ranges can be calculated using two new methods: Natural Break and
Standard Deviation. See ThemeProperties.DistMethod.
• Two new properties —ThemeProperties.AllowEmptyRanges and
Legend.ShowEmptyRanges — give you more control over "empty" ranges (ranges
that do not contain any features).
• Two new properties — Map.SelectionStyle and Map.ExportSelection — allow you
to control the display and exporting of the selection highlighting style.
• Even if you cannot access your data sources through the standard MapX data
binding techniques, you can create your own custom dataset support. MapX
version 3 provides a run-time extensible architecture, allowing you to plug in
custom dataset types through a COM based dataset interface. See Custom Dataset
Support.
• Enhancements to the Layer object: A new GetFeatureByID method retrieves a
feature, given its ID. The SearchWithinFeature method can now search within a
stand-alone feature. The SearchWithinDistance method now allows you to specify
either a Point object or a Feature object as the starting location for the search; earlier
versions did not allow you to specify a Feature object.
• The Layers property page now includes additional buttons—Add, Remove, Up and
Down—that allow you to add, remove, or change the order of the layers in the map.
• The Feature object's Bounds, Length, Perimeter, and Area properties can now work
on stand-alone features.
• If a MapInfo table contains an arc, circle, rectangle, or rounded rectangle feature,
and a MapX application modifies that feature, MapX automatically converts the
feature into a line or region when updating the feature. See Automatic Conversion
of Special Features. Users can press the ESC key to interrupt the drawing of the map
(provided that the application in which MapX is embedded has the focus).

Upgrading MapX v2.0 Applications to MapX

Version 3
Some of the changes in MapX 3.0 might interfere with applications that were written using
version 2. If your MapX version 2 application does not run correctly under version 3, try the
following:

• In version 2, the standard labeling tool (miLabelTool) had a value of 1010. In version
3, the labeling tool's new value is 1011; the new miPolygonSelectTool has the value

18 MapInfo MapX Developer Guide v4.5

 Upgrading MapX v2.0 Applications to MapX Version 3

1010. If you used the label tool's literal value (1010) instead of its define, you will
need to update your code to use the new value.
• The PolyToolUsed event now takes additional parameters (added to provide
support for modifier keys, and to allow you to cancel a tool's action).
• The DrawUserLayer event now takes an additional parameter (added to address
problems when drawing to a metafile).
• The SearchWithinDistance method now expects an additional Units parameter,
which explicitly specifies the map units that apply to the search distance.
• Stand-alone features must be "attached to the map," so that a coordinate system is
associated with the feature. You can explicitly attach a feature to the map through
the new Feature.Attach method. Note that you do not need to use the Attach
method with objects that were created through the new FeatureFactory object;
FeatureFactory methods create features that are already attached to the map.
• The Map.MBR property has been renamed to Map.Bounds, and the Feature.MBR
property has been renamed to Feature.Bounds.
• If you modify a feature in a layer (not a stand-alone feature), and you have not yet
performed an Update to save the changes, then the Feature object's Bounds, Length,
Perimeter and Area properties return values that are based on the "modified"
version of the object (the object as it exists in memory). In earlier versions of MapX,
the values returned by these properties did not reflect modifications made to the
feature.
• The Title.Position and Graphic.Position properties behave differently in version 3;
as a result, titles and text annotations may be positioned differently than they were
in version 2. For example, suppose you assign the value miPositionTL ("Top Left")
to the Graphic.Position property. MapX version 3 positions the text annotation so
that the text is above and to the left of the anchor location; MapX version 2 used the
opposite orientation (placing the anchor location at the top left corner of the text).
Also, changing the Position property on the title (or an annotation) will keep the
object's (X, Y) properties constant and reposition the object using the new position
value. (In version 2, MapX left the object in place, and changed (X,Y) to reflect the
new position value.)
• The ODBC library used in version 2 (mideodbc.dll) has been replaced by a new
library: MODBCDataset.dll. ODBC access also requires a new library:
MMapXColumnInfo.dll.
• The Lotus Notes library used in version 2 (midenote.dll) has been replaced by a new
library: MNotesDataset.dll. Lotus Notes access also requires a new library:
MMapXColumnInfo.dll.
• MapX version 3 includes an updated set of DLLs that provide support for exporting
images. The new DLLs have slightly different names to reflect the new version (e.g.
the GIF export DLL has been renamed from lfgif60n.dll to lfgif70n.dll).
• If you have created your own installer to install MapX version 2, you may need to
modify the part of the installation script that creates registry keys. Instead of

MapInfo MapX Developer Guide v4.5 19

 registry keys that end in "2.0", MapX version 3 uses registry keys that end in "3.0".
See Distributing Your MapX Application.
• If you wrote a Delphi, PowerBuilder or LotusScript application using MapX version
2, and your application creates stand-alone, creatable objects, you may need to
modify your syntax to make your application work with MapX version 3. For
example, you might need to change "MapX.Style.2" to read "MapX.Style.3". See
Creatable Objects.
• The ThemeCategories object has been replaced by three new collection objects:
RangeCategories, IndividualValueCategories, and MultivarCategories. For
example, in version 2, you might have written code like this:
DIM categories AS ThemeCategories
SET categories =
Map1.Datasets(1).Themes(1).ThemeProperties.RangeCategories
With MapX version 3, you would modify the code to use the new object name, like this:

DIM categories AS RangeCategories

SET categories =
Map1.Datasets(1).Themes(1).ThemeProperties.RangeCategories

20 MapInfo MapX Developer Guide v4.5

 Part I:
The MapX User Guide
22 MapInfo MapX Developer Guide v4.5
 Mapping at a Glance

Chapter 1: Introduction to MapX

Welcome to the MapInfo family of products. As the field of enterprise mapping continues to
expand, MapInfo leads the way with new products that are designed to fulfill users’
desktop and enterprise mapping needs from our flagship product, MapInfo Professional, to
the most specialized with MapMarker, our premier address-matching product.

MapInfo MapX is a mapping ActiveX (OCX) control that lets you easily add powerful
mapping capabilities to your applications. With maps, you can display information in a
format that's easy for everyone to understand. Maps are more informative than simple
charts and graphs, and can be interpreted more quickly and easily than spreadsheets.
MapX is based on the same mapping technology used in other MapInfo products, such as
MapInfo Professional and Microsoft Map. If you have created or purchased MapInfo map
data (tables) for use with MapInfo Professional or Microsoft Map, you can use those same
files with MapX.

Mapping at a Glance
Huge quantities of information are available today, far more than ever before. Data abounds
in spreadsheets, sales records, and marketing files. Paper and disks store masses of
information on customers, stores, personnel, equipment, and resources.

MapInfo MapX Developer Guide v4.5 23

 Nearly all of it has a geographic component. An estimated 85 percent of all databases
contain some sort of geographic information such as street addresses, cities, states, ZIP
Codes, or even telephone numbers with area codes and exchange numbers.

MapX can help you sort through all of this information, and, using the geographic
components in your data, display your results on a map. This lets you see patterns and
relationships in the mass of information quickly and easily without having to pore over
your database.

Making MapX Work for You

With MapX, the power to add powerful mapping capabilities to your applications is at your
complete disposal. You can display your data as points, as thematically shaded regions, as
pie or bar charts, etc. Unleash MapX’s analytical features by grouping and organizing data,

24 MapInfo MapX Developer Guide v4.5

 Overview of Key Features

performing searches, or selecting map features within a specific radius, rectangle, or specific
points.
For example, MapX can show which branch store is the closest to your biggest customers. It
can calculate the distances between customers and stores; it can show you the customers
who spent the most last year; it can color-code the store symbols by sales volume. What
makes it all come together is a visual display of your data on the map.

Overview of Key Features

MapX is much more than a "map viewer." With MapX, you can analyze and visualize your
business data, create or edit map features, and display the results geographically.Key
features of MapX are listed below.

• Thematic mapping Visualize your data with thematic mapping. Associate data
with each feature on the map, then use color-coding (or other styles) to present your
data visually. With thematic mapping, you can see your data, using any of six
different styles (colored ranges, dot-density,individual values, graduated symbols,
pie charts, or bar charts).
• Drill-down mapping Explore your data with point-and-click simplicity. For
OLAP/DSS, you can allow the user to drill down into a region on the map by
pointing and clicking.
• Data binding Your map can incorporate data from the container in which the OCX
is embedded, an ODBC, or a DAO data source such as MSAccess. MapX provides
several different types of data binding, including ZIP Code-level geocoding.
• Annotations Provide orientation, highlight specific data, and make your map more
informative by adding text, symbols, and labels.
• Layering Display and control the display of a map layer so it displays only when a
map's zoom level falls within a preset distance. Also use or create a seamless map
layer to treat a group of base tables as if they were one. Special types of applications
are supported by special layer types, such as Animation Layer (for real-time
tracking) and UserDraw layer (for drawing special map elements, such as logos, on
top of the map).
• Raster Images Include a raster image underlay to give your map an attractive,
detailed background.
• Automatic Labeling Add labels to your maps automatically, as well as control their
attributes and display.
• Selections Unleash MapX’s analytical features by grouping and organizing data.
Select map features within a specific radius, rectangle or specific points.

MapInfo MapX Developer Guide v4.5 25

 • Feature Factory The FeatureFactory object allows you to create, combine, buffer, or
erase point, line, and region features.
• Tools Your users interact with the map directly, by clicking and dragging. Use
MapX's built-in navigation, selection, and labeling tools, or create custom tools
tailored to suit your own application.
• Map Editing You can give your users the power to add, modify, or delete features
on the map.
• Projections and Coordinate Systems With full support of coordinate systems and
map projections, MapX allows you to fine-tune the map's display and process X-Y
data in native coordinates.
• Remote Spatial Server Connectivity Connect to live data stored in Oracle8i Spatial
and MapInfo SpatialWare running on Oracle 8.0.5, Informix, or other supported
SpatialWare databases. Spatial servers allow companies to host their map data in
their enterprise databases for central management and security. Spatial servers like
SpatialWare and Oracle8i Spatial offer advanced query processing, and increased
performance on the server for an organization’s spatial data. Storing spatial data in
an RDBMS is also necessary for applications that will require a great deal of map
editing and deals with large data sets.

26 MapInfo MapX Developer Guide v4.5

 Learning About MapX

Learning About MapX

This book is written for anyone who wants to easily add mapping capabilities to their
applications using MapX and object-oriented programming languages, such as Visual Basic,
Visual C++, PowerBuilder, or Delphi, or into Lotus Notes using LotusScript.

If you are upgrading from an earlier version of MapX, see : "New in MapX ".
If you are using MapX for the first time, here are some pointers for how to learn about
MapX:

• Read chapter: "Getting Started With MapX ".

• Examine the sample applications and use them as a template for your own
creations. When you install MapX, sample applications are installed on your
computer; look under <Path to MapX>\ Samples40.
Note: The MapX CD provides additional sample programs that are not automatically
installed on your computer. Look for those sample programs on the CD, under
the \Samples directory. You can also find the latest sample applications on the
MapX web site <http://www.mapx.com>.

MapInfo MapX Developer Guide v4.5 27

28 MapInfo MapX Developer Guide v4.5
Chapter 2: MapX Basics

MapX Basics
1
Chapter

➤ Map Object
In the Getting Started chapter, we created a simple
➤ Property Page
MapX map using the MapInfo MapX Control, and
in the previous chapter we introduced you to some ➤ Layers
MapX mapping concepts. This chapter is an ➤ GeoSets
overview of the major components behind MapX
➤ Datasets
map creation and manipulation within an
application. Selected topics will be discussed in ➤ Annotations
detail in subsequent chapters. ➤ Creatable Objects in MapX
• Map Object
• Property Page
• Layers
• GeoSets
• Datasets
• Annotations
Chapter 2: MapX Basics

Creatable Objects in MapX Map Object

Looking at the MapX object hierarchy on the MapX Object Model (see the object model
poster or click the object model button on the online help window), you see that the map
object itself is at the top. Every MapX object, property, and method is derived from the Map
object. Every property and method shown underneath the map object will somehow
contribute to building the overall Map object. Primarily DatasetsDatasets, Layers, and
Annotations objects define each Map object.

The following table shows some of the Map object properties that are represented by
numeric values. These properties may be changed at design time, or at runtime using the
following code samples:

Property Description Code Sample

Zoom Sets the number of miles (default unit of measure) Map1.Zoom = 500
displayed in the map.
Rotation Rotates the map a specified number of degrees. Map1.Rotation = 179
CenterX Sets the x and y coordinates which may be Map1.CenterX = -
Longitude or Latitude. This is dependent upon 79.4458
the projection of the map.
CenterY Sets the x and y coordinates which may be Map1.CenterY = 44.9932
Longitude or Latitude. This is dependent upon
the projection of the map.

With the Map object, you can control how a map is displayed by manipulating several
methods and properties of the map. There are some properties represented by other objects.
For instance, when you see a MapX map, you are seeing a collection of individual layers,
represented by the Layers collection. The Layers collection is a property of the Map object.
Now let’s take a look at altering the properties of our map. The Property Page allows us to
manipulate many properties of the map object.

30 MapInfo MapX Developer Guide v4.5

 Property Page

Property Page
The Property Page is an extremely useful place to alter the properties of the map while you
are designing and testing an application. To access the Property Page in your Visual Basic
project:
1. Select View > Properties Windowlick on (Custom) from the Properties Window.

2. Click the button on the (Custom) row.

Additionally, the Property Page can be accessed during design time by right clicking on the
Map object within the form and selecting "Properties..."

MapInfo MapX Developer Guide v4.5 31

Chapter 2: MapX Basics

You may also view the Property Pages during run time. To do this, add the following code
to the Map.MouseUp event.

If Button = 2 Then Map1.PropertyPage

This will test to see if the user clicked the right mouse button and then show the Property
Page at runtime. Use the right mouse button, as it will not interfere with the normal use of
tools (left button).

Note: You should only use this code during designing and testing as it may give the
user too much control over the map. However, if you want your finished product
to display a dialog box for your end users, you may want to use the
Layers.LayersDlg method instead of the PropertyPage method, because the
LayersDlg dialog is more user-friendly.

32 MapInfo MapX Developer Guide v4.5

 Layers

Layers
Let’s consider a database of points on a map represented by black stars. By itself, this map
is not very useful, but when you overlay the point map on top of a line map and a region
map, you have a very useful map. Each individual map is referred to as a layer, and MapX
stores a map as a collection of layers.

MapInfo MapX Developer Guide v4.5 33

Chapter 2: MapX Basics

The layers may be altered at design-time through the MapX Properties dialog box, or
programmatically during run-time. The Properties dialog box allows the designer to
manipulate the layers simply by changing the settings. In "Mapping in Layers", we will
take a look at the code that can be used to change the layers properties and methods at any
time within the program. Adding new layers, removing layers, and changing the visibility
or style of a layer are among some of the actions you can perform on a layer.

Layers Collection
The Layers collection is made up of (0 - n) Layer objects. The Layer object is made up of a
collection of features, with each feature having its own properties and styles. A collection of
features is made up of Feature objects, which correspond to a feature on the map such as a
point, line, or region.You can create stand-alone Feature objects, or you can obtain a
collection of Feature objects. Features will be discussed in "Features and Selections".

34 MapInfo MapX Developer Guide v4.5

 GeoSets

GeoSets
A GeoSet is a collection of map layers and their settings. The GeoSet determines the
collection of MapInfo table(s) used within a Map object and their settings. A GeoSet can be
specified at design time. If this is set during run time, it will first remove all loaded layers
and Datasets, then load the new GeoSet. The default GeoSet that is loaded is US.GST. If you
are familiar with MapInfo Professional, a workspace is similar to a GeoSet in MapX.
Specifying an alternative GeoSet to load at run-time, adding a layer to the map object, or
manipulating the look of a layer can be done through the Property Page, as discussed
earlier, or through the MapX Geoset Manager program that ships with MapX and is found
in the MapX Program Group.
Below is a map of the United Kingdom with specified Geosets.

When you are satisfied with your map, you may save it. This will write the GeoSet (*.GST)
file to your drive. When you open that GeoSet file, all of your map layers and settings will

MapInfo MapX Developer Guide v4.5 35

Chapter 2: MapX Basics

be returned as you have saved them. The GeoSet Manager lets you modify layers, manage
zoom levels, labels, and other properties.

GeoDictionary
The GeoDictionary is used when trying to match a data source and a map layer for
databinding or creating a theme map. The GeoDictionary is a file (typically named
geodict.dct) that maintains information about which map layers can be matched, and which
fields can be used as match fields. Files need to be registered in the Geodictionary if you
wish to take advantage of automatching/autobinding. For example, if you have data that
has sales by state, the GeoDictionary may determine that that data should be matched
against the “USA” map layer.

You can specify programatically or explicitly the column(s) to match from the map against
which column in your data file/table, or you can let MapX reference the GeoDictionary to
try and find a match.

Modifying the GeoDictionary

Registering a MapInfo table in the GeoDictionary is necessary if you wish to take advantage
of automatching when doing data binding. Data binding will be covered in "Putting Data
on the Map". The MapX GeoDictionary Program ships with MapX and allows you to
register a new MapInfo table into the GeoDictionary. Additionally, within the MapX GeoSet
Manager there are options under the Tools menu.

Within the MapX

GeoDictionary, click
on the Register button,
and simply select the
table you wish to
register, set the table
properties and enter a
description for the
table. If you wish to
automatically load the
table to a GeoSet, click

36 MapInfo MapX Developer Guide v4.5

 Datasets

the Add button and select the existing GeoSet you wish to add the table to.

If the path for the new table you have registered is not listed within the MapX search path,
the Map Manager program will then ask if you wish to copy the data into the MapX data
directory or simply add the path to MapX’s search path.
Something to keep in mind when distributing your application and associated data is that
there are copyright laws involving many types of data. Make sure that you have the rights
to distribute the data. If you are not sure, contact your data provider

For more information on the GeoDictionary, see "Using the GeoDictionary Manager".

Datasets
Datasets enable you to bind data to your maps. For example, if you have an MSAccess
database of sales by county and a map of counties you could bind that data to the county
map and spot trends in sales patterns by county not easily highlighted in the tabular data.
As indicated above, if MapX is required to specify the match between your data and a map,
the match is determined through a process called automatching/autobinding. You must
first register the map into the GeoDictionary to take advantage of automatching/
autobinding.
Once the data is bound to the map, you can view pertinent information geographically. The
visual representation of data enables the creation of a theme map. A theme is the color-
coding of the map to geographically represent trends in data. Data Binding is discussed in
chapter: "Putting Your Data on the Map". Theme mapping is discussed in chapter, "Theme
Mapping and Analysis".

MapInfo MapX Developer Guide v4.5 37

Chapter 2: MapX Basics

Annotations
The Annotations collection is an easy way to get text and symbols onto a map. The
annotations sit “on top” of all other layers and are not linked to any data. If you are familiar
with MapInfo software, the annotations are similar in purpose to a map’s cosmetic layer.

Listed below are methods and properties for the Annotations collection object:

Annotations Collection Methods

Method Description Code Sample
AddSymbol Adds a symbol to the Annotation Map1.Annotations.AddSymbol
collection. A default style is used (as X, Y
specified in Map.DefaultStyle).
AddText Adds text to the Annotation collection. Map1.Annotations.AddText _
The fourth parameter is the initial “Developer Services”, _
position of the text relative to the 79.44, 46.8889, _
coordinates given. miPositionTL
Remove Removes a specific Annotation from the Map1.Annotations.Remove 1
collection.
RemoveAll Removes all Annotations from the Map1. Annotations.RemoveAll
collection.

Annotation Collection Properties

Property Description Code Sample

Editable Specifies whether or not the Map1.Annotations.Editable _

annotation will be editable. = True
Type Specifies the Annotation If Map1.Annotations(2).Type_
object type. = miTextAnnotation Then _ Print “It is text”
Graphic This contains a Graphic
object, which has properties
for the Annotation. See the
Graphic object description in
the Online Help.

Notice that there is no property for position, symbol style, or text in the annotation object.
The annotation’s graphic property contains a graphic object containing this information. To
modify the annotation, modify the annotation’s graphic object.

38 MapInfo MapX Developer Guide v4.5

 Creatable Objects in MapX

The following code adds a symbol to a specified location:

'Add a symbol at location

Map1.Annotations.AddSymbol X1, Y1

Creatable Objects in MapX

In the MapX object model, the following objects are creatable. In other words, you can create
stand-alone objects with these object classes.

AffineTransform BindLayer BitmapSymbols CoordSys

Datum Feature Fields LayerInfo
Map ODBCQueryInfo Parts Point
Points Rectangle RowValue RowValues
Style Variables NotesQueryInfo NotesViewInfo

The following examples show how to create a stand-alone style object, display a style-
selection dialog box, and use the new style to set the override style of a layer. Note that
programming languages like Visual Basic, Delphi and PowerBuilder require you to specify
the MapX version number after the object name (e.g. "MapX.Style.4").

Note: In Visual Basic, specifying the MapX version number is only required if you do
not have MapX Object embedded in your form.

C++ Example
CMapXStyle style;
style.CreateDispatch(style.GetClsid());
// can also use style.CreateDispatch("MapX.Style.3"),
// but above is more portable between versions of MapX
style.PickRegion();
m_ctrlMapX.GetLayers().Item(1).SetStyle(style);

Delphi Example

Var
s : variant;
begin
s := CreateOleObject('MapX.Style.3');
s.PickRegion;

MapInfo MapX Developer Guide v4.5 39

Chapter 2: MapX Basics

MapObject.Layers.Item(1).Style := s;
end

PowerBuilder Example

OLEObject s
long oleStatus

s = CREATE OLEObject

oleStatus = s.ConnectToNewObject("MapX.Style.3")
ole_1.Object.Layers.Item(1).Style = s

Visual Basic Example

If you have the MapX Object embedded in a Visual Basic form…

Dim s as new MapXLib.Style

s.PickRegion
Map1.Layers(1).OverrideStyle = True
set Map1.Layers(1).Style = s

If you do not have the Mapx Object embedded in a form…

Dim objStyle as new object

Set objStyle = CreateObject(“MapX.Style.4)
Map1.Layers(1).OverrideStyle = True
objStyle.PickRegion
set objMap.Layers(1).Style = objStyle

40 MapInfo MapX Developer Guide v4.5

Chapter 3: Mapping Concepts

Mapping Concepts
2
Chapter

Now that you have installed MapX and been ➤ Organizing Your Data and
enticed by the wide variety of features and
Maps: An Overview of
Tables
functionality in the What’s New chapter, you are
probably anxious to get mapping. But, first, take a ➤ What Are GeoSets?
few minutes to read this chapter, especially if you ➤ Map Features
are new to MapX. This chapter gives you a solid
➤ Putting Your Data on the
understanding of the concepts for successful Map
mapping with MapX.
➤ The Power of MapX
Chapter 3: Mapping Concepts

Organizing Your Data and Maps: An Overview

of Tables
To use MapX, you need the files that contain your records and maps that come from
MapInfo. MapX organizes all its underlying information in the form of MapInfo tables; each
table is a group of MapInfo files that is used to build a layer in a map.

How Files Make Up a Table

All MapInfo tables will have the following files:

• <Somefile>.tab: This file describes the structure of the MapInfo table. It is a small
text file describing the format of the file containing the data.
• <Somefile>.dat(.mdb, .aid, or .dbf): These files contain the tabular data.
• <Somefile>.map: This file describes the graphic objects (will not exist if the table has
no map objects).
• <Somefile>.id: This file is a cross reference file that links the data with the objects
(will not exist if the table has no map objects).
• <Somefile>.ind: This is an index file. The index file allows you to search for map
objects using the Find object.

MapInfo Tables and MapX Layers

Each mappable MapInfo table can be displayed as a layer in a map. For example, you can
display a table of customers, a table of streets, and a table of county boundaries.

Think of these layers as transparencies where each layer contains a different part of the map.
The layers are stacked one on top of the other and allow you to see all aspects of the map at
the same time.

42 MapInfo MapX Developer Guide v4.5

 What Are GeoSets?

What Are GeoSets?

A geoset keeps a collection of map layers and their settings easily available to you. Geosets
are data sets made up of standard MapInfo format map files (.tab) of the same geographic
region, hence the name geoset. Geosets help you to avoid the time consuming task of
opening and displaying layers individually each time you want to work with them as a
sample map. The extension for a geoset is .gst. A .gst is a text file that contains several
metadata keys that tell MapX what tables to display and how to display them.

When a geoset is opened, it automatically opens all of the files included in the geoset to a
default display. The developer can change the default display to meet their individual
needs. A geoset's settings include projection, default zoom, auto-labeling of objects, zoom
layering and whether the table is visible when opened. MapX will also open any single (.tab)
map file the developer specifies. Geosets are provided for convenience and are not required
for MapX to function.

MapX will not open a MapInfo workspace (.wor file type).

MapInfo MapX Developer Guide v4.5 43

Chapter 3: Mapping Concepts

Geosets Available with MapX

Geosets Layers in Geoset

Argentina Geoset Argentina Major Cities

Argentina Cities
Argentina Country Boundary
South America Country Boundaries
World Ocean (Lat/Long)

Asia Geoset Asia

Asia Major Cities
Asia Capitals
World Ocean (for Asia)
European Country Boundaries

Australia Geoset Australia State Boundaries

Australia State Capital Cities
Australia Major Cities
Australia Cities
Australia Highways
World Ocean (Lat / Long)

Brazil Geoset Brazil Major Cities

Brazil Cities
Brazil Country Boundary
South America Country Boundaries
World Ocean (Lat / Long)

Canada Geoset Canadian Province Boundaries

Canadian Province Capital Cities
Canada Major Cities
Canada Cities
Canada Highways
World Ocean (Lat / Long)
US State Boundaries

China Geoset China Major Cities

China Cities
China Country Bdy
China Highways
World Ocean (for Asia)
Asia Major Cities
Asia Country Boundaries

44 MapInfo MapX Developer Guide v4.5

 Geosets Available with MapX

Geosets Layers in Geoset

Dallas, TX Geoset Dallas Major Highways A

Dallas Major Highways B
Dallas Streets A
Dallas Streets B
Dallas Streets C
Dallas City Boundary A
Dallas City Boundary B
Dallas Water Rivers
Dallas Water Bodies
Dallas, TX Raster
Dallas Locations
Crime Demo Map
Crime County Map

DC Geoset DC Landmarks
DC Roads
DC State Roads
DC Interstate Roads
DC Highways
DC Zips
Dc Area Landmarks
Dc Water Layer
Dc City Boundaries

Europe Geoset European Country Boundaries

European NUTS 1 Level Boundaries
European NUTS 2 Level Boundaries
European Capitals
European Highways
European Major Cities
European Cities
World Ocean (Lat / Long)
Asia

France Geoset France NUTS 2 Level Administrative Boundaries

France Major Cities
France Cities
France Highway Map
World Ocean (Lat / Long)
European Country Boundaries

MapInfo MapX Developer Guide v4.5 45

Chapter 3: Mapping Concepts

Geosets Layers in Geoset

Germany Geoset Germany NUTS 2 Level Bdys

Germany Major Cities
Germany Cities
Germany Highways
World Ocean (Lat / Long)
European Country Boundaries

India Geoset India State Bdys

India District Bdys
India Minor Cities
India Major Cities
India Capital Cities
Asia
World Ocean (for Asia)

Israel Geoset Israel Major Cities

Israel Cities
Israel Country Boundary
World Ocean (Lat / Long)
Africa Country Boundary
Asia

Italy Geoset Italy Major Cities

Italy Cities
Italy Highways
Italy NUTS 2 Level Bdys
World Ocean (Lat / Long)
European Country Boundaries

Japan Geoset Japan Country background

Japan Cities
Japan Major Cities
Japan Cased Roads
Japan Highways
Japan Rivers and Lakes
World Ocean (Lat / Long)

Mexico Geoset Mexico State Boundaries

Mexico Cities
Mexico State Capital Cities
Mexico Highways
Mexico Major Cities
World Ocean (Lat / Long)
US State Boundaries

46 MapInfo MapX Developer Guide v4.5

 Geosets Available with MapX

Mid-Atlantic Geoset Mid-Atlantic Capitals

Mid-Atlantic Counties
Mid-Atlantic Highway
Mid-Atlantic Major Cities

MapInfo MapX Developer Guide v4.5 47

Chapter 3: Mapping Concepts

Geosets Layers in Geoset

UK Geoset United Kingdom Cities

United Kingdom Standard Regions
United Kingdom Class A Roads
United Kingdom Motorways
World Ocean (Lat / Long)
European Country Boundaries

US Detail Geoset US Cities

US top 20 Cities
US Major Cities
US Highways
US State Boundaries
US State Capitals
World Ocean (Lat / Long)
Mexico State Boundaries
Canadian Province Boundaries
US County Boundaries
US Zipcode Boundaries
Landmark Map

US Geoset US Cities
US top 20 Cities
US Major Cities
US Highways
US State Boundaries
US State Capitals
World Ocean (Lat / Long)
Mexico State Boundaries
Canadian Province Boundaries
US County Boundaries

World Detail Geoset World Countries

World Capitals
World Top 25 Cities
World Ocean (Robinson)
World Graticule
World Major Cities
World Minor Cities

World Geoset World Countries

World Capitals
World Top 25 Cities
World Ocean (Robinson)
World Graticule

48 MapInfo MapX Developer Guide v4.5

 Geosets Available with MapX

Geosets Layers in Geoset

Other Files US 5-Digit Zipcode Points

US 5-Digit Zipcode Points (compressed point file)
Dallas Major Highways from MapXsite Streets 1.0
Dallas Streets from MapXsite Streets 1.0
Dallas City Boundary from MapXsite Streets 1.0
Dallas Water Rivers from MapXsite Streets 1.0
Dallas Water Bodies from MapXsite Streets 1.0

The MapStats.mdb
This is not a geoset, rather, an access database containing demographic information that
matches many of the geosets that in MapX.

MapStats.mdb • Demographics for Australia

• Demographics for Asia
• Demographics for the World
• Demographics for DC
• Demographics for Mid-Atlantic States
• Demographics for US
• US Customer Database
• US County Age Demographics
• US County Age Demographics by Gender
• US County Household demographics by Age, Income
• US County Household demographics
• US County Household Income
• US County Housing Values
• US County Population Demographics

MapInfo MapX Developer Guide v4.5 49

Chapter 3: Mapping Concepts

Map Features
We mentioned earlier that maps in MapX are made up of layers of map objects. These map
objects are accessed in MapX through the Feature object. There are four basic types of
features:

• Regions: closed objects that cover a given area. These include polygons, ellipses,
and rectangles. For example, country boundaries, postal code boundaries, sales
territories.
• Point objects: represent single locations of data. For example, customer locations,
restaurants, parking meters.
• Line objects: open objects that cover a given distance. These include lines, polylines,
and arcs. Examples are streets, rivers, power lines.
• Text objects: text that describes a map or another object, such as labels and titles.
You can have each type of object in a separate layer (most common), or you can combine
objects in the same layer. MapX lets you create, edit, customize, and display these objects to
make maps that meet your needs.

Putting Your Data on the Map

Datasets enable you to bind data your maps. For example, if you have a Microsoft Access
database of sales by county, you could bind that data and display it on a counties map in
order to spot trends in sales patterns by county that are not easily identified in the tabular
data alone.

There are many different types of databases in businesses today; therefore, MapX lets you
bind to several different types of DataSources. The first argument to the Datasets.Add
method lets you specify a DatasetTypeConstants value, which dictates the type of data
binding you wish to perform. Types of data sources you can bind to include:

Datasource Description
ADO This type of databinding uses the MS Active data objects ADO
recordset.
DAO A DAO Recordset object. You can get one from a Visual Basic
data control, an Access form, or by creating one in Visual Basic,
Access, or C++.
Delphi This type uses the Borland BDE datasources.

50 MapInfo MapX Developer Guide v4.5

 Putting Your Data on the Map

Datasource Description

Global Handle This type of data binding lets you pass in a block of tab-
delimited data.
Layer This type of data binding lets you create a dataset that uses
fields from a MapInfo table.
Notes View/NotesQuery These types of data binding deal specifically with Lotus Notes.
ODBC MapX can use ODBC to retrieve data from any ODBC data
source.
OLE Data This is for containers such as PowerBuilder.
Oracle Express Objects This allows access to the datacube as a dataset.
RDO This uses MS Remote Data Objects and RDO Resultset object.
SafeArray A COM dataset that allows static binding of data from a
safearray.
Unbound If you cannot support one of the other formats, MapX provides a
‘back door’. With this type of data binding, you can set up an
event loop whereby MapX asks the container for data values,
one cell at a time.

Tools to Get the Job Done

Most mapping applications provide an assortment of toolbar buttons (tools) to aid with
common drawing tasks (such as drawing a line on the map) and navigation tasks (such as
zooming in). MapX provides several common mapping tools, plus you can also create your
own custom tools.

Standard Tools
With MapX, you can easily incorporate common tools into your application, without re-
inventing the wheel. MapX provides built-in support for several common mapping tools,
including:
• Navigation tools (Zoom-In, Zoom-Out, Pan, Center) that let the user change the
scale and placement of the map.
• A Labeling tool that lets the user click a map feature to label it.
• A set of Selection tools that give the user various ways to select map features.
• Annotations (symbols and text).

MapInfo MapX Developer Guide v4.5 51

Chapter 3: Mapping Concepts

Custom Tools
If you need a type of toolbar button that MapX does not provide, you can simply create a
custom tool by using the CreateCustomTool method.

The Power of MapX

Now that you have an overview of tables, layers, geosets, map features, datasets and tools,
you are ready to bring the full capabilities of MapX into play. With MapX, you can search a
layer in a map and locate a specific feature within the layer. For instance, you could use it to
find the closest dealer to Lackawaxen, PA. Or, you can calculate distances between health
care providers and their patients, then get counts on how many patients live within a given
radius of a particular hospital. Or, you could shade boundaries (counties, towns, states,
countries) according to the total number of customers in each one or according to the
number of customers who purchased within the last year. MapX refers to this as thematic
mapping.

As you become better acquainted with MapX, you will find that its applications are limited
only by your imagination.

52 MapInfo MapX Developer Guide v4.5

 3
Chapter 4: Getting Started With MapX

Getting Started With MapX

Chapter
This chapter presents the information you need to
install MapX successfully and gives you a quick
➤ What Is MapX?
overview of MapX. First-time users should read
this chapter. ➤ Before Installing MapX
➤ Installing MapX
➤ Adding the Map Control
➤ Upgrading Visual Basic
Applications From an
Earlier Version of MapX
➤ Upgrading C++
Applications From an
Earlier Version of MapX
➤ Getting Started with Visual
Basic
➤ Getting Started with Visual
C++
➤ Getting Started with
PowerBuilder
➤ Getting Started With Delphi
➤ Getting Started with Lotus
Notes
➤ MapX Documentation Set
➤ Where to Go Next
Chapter 4: Getting Started With MapX

What Is MapX?
MapX is a tool for application developers. It offers the easiest, most cost-effective way to
embed mapping functionality into new and existing applications. MapX is an OCX
component that can be quickly integrated into client applications using object-oriented
languages such as Visual Basic, PowerBuilder, Delphi, Visual C++, and Lotus Script with
Lotus Notes v4.5.

System Requirements
Because MapX is a 32-bit OCX, it requires a 32-bit version of Windows (Windows 95/98/
2000 or Windows NT 4.0). MapX applications cannot run on Windows 3.1.

MapX works with object-oriented programming languages (such as Visual Basic, Visual
C++, PowerBuilder, or Delphi) or with Lotus Notes using Lotus Script.

What's Included With MapX

The MapX software package includes the components listed below.

Note: If you clear options when installing MapX, some of these files will not be
installed on your system. By default, files are installed within or underneath the
folder: Program Files\MapInfo\MapX 4.0

MapX Contents
Program Files
The MapX OCX, along with an assortment of DLLs and other support files.

Sample Maps
A collection of map files (in MapInfo table format) of different regions around the
world. The number of sample maps included with MapX depends on which version of
MapX you install; the full version of MapX includes more maps than the 30-day
evaluation software.

Sample Data
A Microsoft Access database containing sample demographic data.

54 MapInfo MapX Developer Guide v4.5

 What Is MapX?

Sample Applications
Program examples in various languages, showing you MapX in action. For the latest
sample programs, visit the MapX web site: http://www.mapx.com

Utilities
The MapInfo Geodictionary Manager (GeoDictionaryManager40.exe), which allows
you to register tables for use with MapX, and the GeosetManager, which allows you to
easily create Geosets.

MapX Documentation
Customers who purchase MapX receive the MapX Developer’s Guide. It is a detailed
work on mapping concepts and how to use MapX effectively. (Not included with 30-day
evaluation copy of software.)
MapX’s comprehensive Online Help system is essentially an electronic version of "The
MapX Developer’s Guide" with the addition of numerous code samples in the "MapX
Objects" book.

Note: Although MapInfo has made every effort to test the sample code that appears in
the online help for accuracy and usability, it is conceivable that for one reason or
another, some of the code samples may not work as designed in your MapX
applications. Minor adjustment or "tweaking" may need to be made to the
existing code in order for it to work properly.

Spatial Server Access

With Spatial Server Access, you can display map data from remote data sources, such as
Oracle and Informix.

MapInfo MapX Developer Guide v4.5 55

Chapter 4: Getting Started With MapX

Before Installing MapX

Before installing MapX, you should record your serial number in an easy-to-remember
place, such as a manual title page. Be sure to fill out the postage-paid registration card
provided and return it to MapInfo Corporation.

Note: We strongly recommend that you remove all previous versions of MapX and exit
from all Windows programs before beginning the installation.

Uninstalling Older Versions of MapX

Uninstalling an older version of MapX is a relatively simple procedure. The steps are:
1. Select Start > Programs > MapInfo MapX v.X > Uninstall MapX v.X
2. The Uninstall Shield screen will appear and a dialog will confirm that you would
like to remove MapX and all of its components. Click OK.

Installing MapX
The MapX installation procedure is described below.

If your Windows configuration does not have a MapX program group, the installation
process will create such a group. If your Windows configuration already has a MapX
program group, the installation process will create a new MapX icon within that group.

To install MapX:
1. Place the MapX CD in the CD drive (such as D:). Click on the Windows Start button
and select Run.
2. Type or select [ CD Drive Letter ]\Setup.exe (e.g., D:\Setup.exe) in the Open drop-
down list and click OK.
The Welcome screen displays. Choose Next to continue the installation process.
3. The Software License screen displays. Choose YES to accept the terms of the
agreement and to continue the installation process.
4. The Choose Destination Location screen displays. Specify the directory where
MapX will be installed. If you do not have MapX currently installed, the default
location is: Program Files\MapInfo\MapX 4.0
If you already have MapX installed, the default is the current installation directory.

Note: We strongly recommend that you remove all previous versions of MapX and exit

56 MapInfo MapX Developer Guide v4.5

 Installing MapX

from all Windows programs before beginning the installation.

To designate a different location, choose the Browse button, and specify the
destination. Click Next to continue the installation process.
5. Specify the product components you want to install. Disk space requirements for
selected components display. When you select a component, a description of that
component displays. If the Change button is enabled, the component has sub-
components. Click the Change button to display a list of those components and
their space requirements. Check the sub-components you wish to install. For
example, if you select the Exporting/Importing Formats component, five sub-
components display (GIF, JPG, TIF, PSD, and PNG) with the disk space required for
each. You can choose to install any or all of these sub-components.
If you want to install support for Lotus Notes databases, make sure the Lotus Notes
option is checked when you install MapX. (The Lotus Notes option is a sub-
component, within the Data Drivers option.) For additional information, see
"Installing and Setting Up Visual Basic drivers for Lotus Notes".
6. The Select Program Folder screen displays; designate the program folder.
7. The Start Copying Files screen displays. Check the information presented. If it is
correct, choose Next to install MapX. A progress bar indicates the status of the
installation. If you want to change information, choose Back to return to previous
screens.

MapInfo MapX Developer Guide v4.5 57

Chapter 4: Getting Started With MapX

Adding the Map Control

After installing MapX, you may need to add the Map control.

For Visual Basic Users

Install the Map control on the Visual Basic toolbox. Do the following with an open
Visual Basic project:

If you are using Visual Basic 4:

1. Right-click on the Visual Basic toolbox, and choose Custom Controls from the
shortcut menu.
2. In the Custom Control dialog, look for "MapInfo MapX V4" in the list. If this item is
not checked, check it. Click OK.
If you are using Visual Basic 5 or later:
1. Right-click on the Visual Basic toolbox, and choose Components from the shortcut
menu.
2. In the Components dialog, click on the Controls tab and look for "MapInfo MapX
V4" in the list. If this item is not checked, check it. Click OK.
The Map control appears on the toolbox. To place a map on your Visual Basic form, select
the Map control and draw a box on the form.

If you save your project, the next time you re-load your project the Map icon will appear in
the toolbox automatically.

For C++ Users

You will want to include MapX.cpp and MapX.h in your project. They contain the class
definitions and method implementations for access to the MapX control. The MapX.h and
MapX.cpp files can be found in the Samples40\CPP subdirectory where MapX is installed.

Using Visual C++ Version 4

From the Insert menu, choose Files Into Project. Choose MapX.cpp as the file to insert.

Note: Do not choose the Insert > Component command. Doing so would create a .cpp
file, but it would be incomplete.

58 MapInfo MapX Developer Guide v4.5

 Upgrading Visual Basic Applications From an Earlier Version of MapX

Using Visual C++ version 5 and 6

From the Project menu, choose AddTo Project > Files. Choose MapX.cpp as the file to add.

Note: Do not choose Project > Components And Controls command. Doing so would
create a .cpp file, but it would be incomplete.

Upgrading Visual Basic Applications From an

Earlier Version of MapX
If your Visual Basic project uses an earlier version of MapX, use the following procedure to
convert your application to the current version.
1. Open the project of the application you want to upgrade to the current version.
2. Delete the map object from the form. Make a note of the name of the map control
and of any map properties that may have been modified from their defaults.
3. From the Tools menu, choose Custom Controls.
4. In the Available Controls list, uncheck the MapInfo MapX Control and click OK.
5. Go back into the Tools > Custom Controls dialog and check the MapInfo MapX
Version x Control (where x is the number of the current version) and click OK.
6. Place the new MapX Map control on your form, and give it the same name (e.g.
"Map1") that you used with your earlier version’s control.
After the new OCX is added into the project, you will need to restore any custom
properties.

MapInfo MapX Developer Guide v4.5 59

Chapter 4: Getting Started With MapX

Upgrading C++ Applications From an Earlier

Version of MapX
If you wrote a C++ application using an earlier version of MapX, you will need to use the
new MapX wrapper classes (mapx.h and mapx.cpp) to upgrade your application to the
current version of MapX.

You may need to modify the strings that you pass to CreateDispatch. With an earlier version
of MapX , you may have used a string to specify an object name; for example:

Flds.CreateDispatch("MapX.Fields")
With the current version of MapX, you need to specify a different string:

Flds.CreateDispatch("MapX.Fields.4")
To make your code more compatible with future versions of MapX, you may want to use
GetClsid instead of a string. The result returned by GetClsid will work in current and future
versions of MapX. For example:

Flds.CreateDispatch(Flds.GetClsid())

Getting Started with Visual Basic

Creating a Simple Map
With MapX, it's easy to add a map to your application. In fact, you can add a working map
to a Visual Basic form without writing a single line of code.

1. Select the Map control from the Visual Basic toolbox. (If the Map control does
not appear on the toolbox, see Adding the Map Control in this chapter.
2. Draw a box on your form, representing the area where you want the map to appear.
MapX displays a preview of your map.
3. Right-click on the Map control, and choose Properties from the shortcut menu. The
MapInfo MapX Properties dialog box appears.

60 MapInfo MapX Developer Guide v4.5

 Getting Started with Visual Basic

4. Locate the Current Tool option, which is near the bottom of the General tab. Set the
Current Tool to "1003 - Zoom In" and click OK.
5. Run your program to view the map. Notice that whenever the cursor is over the
map, it changes to a magnifying glass with a plus sign.
6. Click on the map. MapX zooms in on the map location where you clicked. You can
click repeatedly, to zoom in more and more. You can also draw a marquee to specify
the exact area that you want to zoom in on.
As you zoom in closer and closer, you will notice that more map features become
visible. This is because individual map layers have been set up with Zoom Layering
(a feature that automatically displays map layers within a preset zoom range ).
To zoom back out, hold down the CTRL key and click the map again. Note that while you're
holding down the CTRL key, the cursor changes to a magnifying glass with a minus sign.

One way to learn MapX is to study sample applications. Look for sample applications in the
folder: \Program Files\MapInfo\MapX 4.0\Samples40

MapInfo MapX Developer Guide v4.5 61

Chapter 4: Getting Started With MapX

Understanding ASIA.VBP (Visual Basic 4 project)

This project displays a simple form with a map. Buttons on the map allow the user to select
various tools—a Select tool, a Pan tool, Zoom In and Zoom Out tools. A TextBox at the
upper right lets the user read or set the map's zoom distance.

Highlights
The Main form contains a Map object (Map1). This object was placed on the form using
the Map control.
If the Visual Basic toolbox does not show you this control, you need to add the control to
the toolbox.
This application displays Asian data because the programmer chose the "Asia" geoset.
You choose the geoset at design-time, by right-clicking the Map object and choosing
Properties. The Properties dialog also allows you to set many other map properties.

62 MapInfo MapX Developer Guide v4.5

 Getting Started with Visual Basic

When the user clicks one of the buttons at the upper left, the application uses the
Map.CurrentTool property to change which tool is in use. For example:
Private Sub Command4_Click()
map1.CurrentTool = miSelectTool
End Sub
The text box at the upper right allows the user to type in a desired zoom distance
(distance across the map), in miles. The application uses the Map.Zoom property to
apply the new zoom distance:
Private Sub Text1_LostFocus()
map1.Zoom = Text1.Text
End Sub
When the user zooms in or out (using the Zoom In or Zoom Out buttons), the map's
zoom distance changes. The application automatically updates the text at the upper
right by using the MapViewChanged event.
Private Sub map1_MapViewChanged()
Text1.Text = map1.Zoom
End Sub

Understanding VBsample.VBP (Visual Basic 5 project)

This project displays another simple form with a map. However, it will only run if you are
using Visual Basic 5 or 6 with MapX. This map defaults to United States data, but it is
designed to handle any specified geoset. You may select a different geoset at design-time by
right-clicking the map object and selecting properties.

MapInfo MapX Developer Guide v4.5 63

Chapter 4: Getting Started With MapX

This project uses three types of data binding. They are:

• Point Reference
• XY Coordinate
• Normal
If you choose Point Reference or XY, a layer will be created. For more information on
layers, see chapter: "Mapping in Layers."

Tools
The tool bar is located on the left side of the screen. Drag the cursor over an icon to
identify what it is and click the desired tool. You may also access tools using the Tools
menu.

64 MapInfo MapX Developer Guide v4.5

 Getting Started with Visual Basic

Arrow tool: Acts as the default pointer/cursor tool.

Zoom In: Gets a closer area view of the map.
Zoom Out: Gets a wider area view of the map.
Pan: Repositions the map within the window
Ruler: Measures distance between two defined points.
Select: Selects objects on the map.
Select Rectangle: Selects objects within a given rectangle.
Select Radius: Selects objects within a given circular region.
Select Polygon: Selects objects within a given region.
Label: Labels objects with information from a given database.
Annotation Tool: Places point symbols on the map.
Add Text Annotation: Adds titles or labels to the map.

Insert Data and Themes

You can insert data in this map using the the Insert Data feature in the Map menu.
When selected, the Add Dataset dialog appears. Choose the data you wish to add.
To create or modify a theme, select Create or Modify Theme in the Map menu and their
respective dialog boxes will appear. For more information on thematic mapping, see:
"Theme Mapping and Analysis".

Find Feature
The Find Feature command is located in the Map menu. When selected, the Find
Dialog appears. The user will define which layer, object, and value of object to use in
the search. Optional refinements are available. For more information on the Find
feature, see: "Finding Features on a Map".

Select Within Distance

To select within distance, the user must first use one of the select tools to select the area
he wishes to search. Then he must choose Select Within Distance from the Map menu.
The Select Within Distance dialog appears. The user will specify which layers, the
distance, the units of measure, and the feature(s) to select. For more information on the
Select Within Distance feature, see: "Features and Selections".

MapInfo MapX Developer Guide v4.5 65

Chapter 4: Getting Started With MapX

Query Selection
Use a selection tool to select the area for query. The Query Selection feature can access
data associated with a map. It is located in the Map menu.

Getting Started with Visual C++

One way to learn MapX is to study sample applications. Look for sample applications in the
folder:

MapInfo\MapX 4.0\Samples40
As you study the sample C++ application mapxsamp.cpp, refer to"Working With Visual
C++, to help you understand how to use MapX with C++.

Note: These topics assume that you are using Microsoft’s Document/View model
(standard MFC AppWizard app.) The sample application can be built in
Developer Studio with mapxsamp.mdp.

Getting Started with PowerBuilder

Creating a Simple Map
These steps will create a new project and place a Map control into the application.
1. Create a new application to hold your Map by opening the Application Painter and
choosing New from the File menu. Pick a file for the Application Library and a
name for the new application. Choose Yes when asked whether to generate an
Application Template.
2. Open the main document window (for the Application Template, it is called
w_genapp_sheet). Select it in the Application Painter and click the return key to
open the Window Painter.
3. Select OLE from the Controls menu.
4. Select the Insert Controls tab from the Insert Object dialog, and pick MapInfo MapX
V4 from the list box. Click OK to return to the Window Painter
5. Click in the document window to insert a new Map object.

66 MapInfo MapX Developer Guide v4.5

 Getting Started With Delphi

Getting Started With Delphi

Adding the Map Control
These steps install MapX into a Delphi package. This process only needs to be done once.
1. Open Delphi with a new, empty project.
2. Select Import ActiveX Control from the Components menu.
3. Select MapInfo MapX V4 from the list box, and click Install. In the Install dialog
box, install into the default package, which should be Borland User’s Components.
Press Yes to recompile the package, then close and save the Package window. The
MapX icon should appear in the Controls palette, under the ActiveX tab.
4. Close the Delphi program. In Windows, locate the file
MapInfo\MapX 4.0\Samples40\Delphi\DelphiWrappers\DelphiFix.exe. Run this
executable to correct several errors in the MapX source files generated by Delphi.

Creating a Simple Map

These steps can be used to create a new project which includes MapX.

1. Select the MapX icon from theTools palette, under the ActiveX tab.
2. Draw a box on the form representing where you want the Map to appear. Delphi
will then show a preview of the Map on the form.
3. Select Run from the Run menu to run the new application.

Getting Started with Lotus Notes

Introduction
To embed a MapX control into Lotus Notes, you need the Notes client version 4.5 or later.

Notes client applications cannot call Datasets.Add with type miDataSetUnbound. This
restriction is due to a bug in Notes 4.5 (related to type conversion for booleans) which
prohibits using the MapX RequestData method for unbound data sets through LotusScript.
Lotus plans to fix this problem in an upcoming release of Notes.

MapInfo MapX Developer Guide v4.5 67

Chapter 4: Getting Started With MapX

Installing and Setting Up Drivers for Lotus Notes

If you want to install support for Lotus Notes databases, make sure the Lotus Notes option
is checked when you install MapX. (The Lotus Notes option is a sub-component, within the
Data Drivers Install option.)

MapX accesses Lotus Notes by using the support files MNotesDataset.dll and
MMapXColumnInfo.dll, which are stored in the MapX Program directory. If you check the
Lotus Notes Data Driver option at install time, the MapX installer attempts to register these
dlls. Note: If the file nnotes.dll (which is part of Lotus Notes) is not in your path, the MapX
installer will not be able to register these dlls, and an error message will be displayed during
installation.
To correct this error, modify your SYSTEMPATH to include your Lotus Notes directory.
Then register the dlls manually (by running regsvr32.exe) or re-run the MapX installer with
the Lotus Notes data driver option checked.

Note: To access a database on a Notes server, there must be at least one database from
that server located on your Notes desktop (desktop.dsk).

Accessing Data through a Notes View

Access to a Notes View is provided using a NotesViewInfo object. This object has three
properties: Server, Database, and View

• The Server property specifies the name of the Notes server. If the file is being
accessed locally, this can be set to the null string.
• The Database property is used to specify the path to the database file. On a Server,
this path would be relative to the Notes data directory; locally, this would be a full
path beginning with a drive letter. NOTE: Because UNC path specifications are not
supported by the Notes API, drive mappings must be used for accessing a database
across a network.
• The View property represents the name of the Notes View being referenced.
Notes View will typically be used with a MapX Fields object to define specifically which
columns of the View are to be used. The MapX Fields object is used in the normal way,
although it is important to note that column title references are case specific.

68 MapInfo MapX Developer Guide v4.5

 MapX Documentation Set

Accessing Notes through a Notes Function Query

Accessing Notes data through a function query is accomplished using a NotesQueryInfo
object. The NotesQueryInfo object has Server and Database properties which behave
exactly as described for the NotesViewInfo object. In addition, the NotesQueryInfo object
has a third property named Query which represents the text of a query to be performed. The
syntax of this query is that of a standard Notes formula.
Notes function queries are generally used in conjunction with MapX Fields objects to define
specifically which fields of the database record are to be used. Unlike Notes View column
titles, references to record field names are not case-sensitive.

MapX Documentation Set

MapX documentation includes a printed book entitled The MapX Developer Guide and an
Online Help system.

The MapX Online Help System

MapX’s comprehensive Online Help system provides the information you need to learn and
use MapX more effectively. Essentially, it is an electronic version of the printed manual with
the addition of sample code written in Microsoft Visual Basic, C++, and Delphi. Cut and
paste these samples into your own MapX applications to expedite your application’s
development process.

Note: Although MapInfo has made every effort to test the sample code that appears in
the online help for accuracy and usability, it is conceivable that for one reason or
another, some of the code samples may not work as designed in your MapX
applications. Minor adjustment or "tweaking" may need to be made to the
existing code in order for it to work properly.
You can reach the information in several ways:

• Use the Help Contents screen to choose topics from books. Click on a book to
display its topics, and choose a topic from the list.
• Use the Find feature to search on a specific word. Select: Start menu > Programs >
MapInfo MapX > MapX Online Help. Then, click index and go to the Find Tab.
Type the word you want to search for, and click Rebuild. MapX displays a list of
words to help narrow your search. Click on a word, and a list of topics displays that
contain the selected word. Double-click on the topic you want or click Display to

MapInfo MapX Developer Guide v4.5 69

Chapter 4: Getting Started With MapX

display the topic. You my customize your search by clicking Options to make your
find more specific.
• Use the Index feature to find a topic quickly. Type the first few letters of the word
you are looking for. The topic that most closely matches what you typed is
highlighted. Click the index entry you wish to display
• See Also information: Click on the green underlined text in any Help window to
bring up information on related tasks or key words and phrases.
Online Help has been designed to display in part of your window so that you can view your
maps, Browser windows, and dialogs alongside the Help window. Of course, you can
always change the size of the Help window to work the way you are most comfortable.
Choose Help > Always On Top to keep the Help window on your screen so you can
continue to work in MapX. Or use Alt–Tab to toggle between the Help screen and the MapX
desktop.

Tips on Using Online Help

Using Code Examples
You can easily copy code examples from the Help window. To copy text, highlight the text,
and press CTRL-C; to paste the text into your development environment, press CTRL-V. You
can also use Drag and Drop to drag highlighted text from Help into other applications.

Note: Although MapInfo has made every effort to test the sample code that appears in
the online help for accuracy and usability, it is conceivable that for one reason or
another, some of the code samples may not work as designed in your MapX
applications. Minor adjustment or "tweaking" may need to be made to the
existing code in order for it to work properly.

Download the Latest Help Files

MapInfo Corporation regularly updates the MapX Online Help. To download the latest
version of this Help file, visit the MapX web site at: http://www.mapx.com/mapx/html/
mapx_docs.html.

The MapX web site also provides sample applications, as well as a Discussion Area where
you can post questions and interact with other MapX users.

Note: When using MapX with Visual Basic, you will find properties/methods in the
MapX Library that do not have help topics associated with them. These
properties/methods are inherited from Visual Basic. Consult Visual Basic
documentation for information regarding these properties.

70 MapInfo MapX Developer Guide v4.5

 Where to Go Next

Where to Go Next
This chapter has provided a very quick overview of MapX. Other sections of this
documentation describe specific features of MapX in greater detail.
Before you read any further, take a moment to view the MapX Object Model Diagram. This
poster is included with MapX and is useful for giving you the "big picture". Use it as a
reference as you learn about MapX.

MapInfo MapX Developer Guide v4.5 71

Chapter 4: Getting Started With MapX

72 MapInfo MapX Developer Guide v4.5

Chapter 5: Mapping in Layers
4
Chapter

➤ Maps as Layers
Mapping in Layers ➤ The Layers Collection:
Building Blocks of Your
This chapter presents the relationship between Map
tables and maps, and shows how they are layered ➤ Properties of the Layers
to create the level of detail you want. Collection
• Maps as Layers ➤ Methods of the Layers
• The Layers Collection: Building Blocks of Collection
Your Map ➤ The Layer Object
• Some Properties of the Layers Collection
➤ Layer Order
• Some Methods of the Layers Collection
• The Layer Object ➤ Examining Layers
• Layer Order ➤ Checking a Layer’s Feature
• Examining Layers Type
• Checking a Layer’s Feature Type
➤ Zoom Layering
• Zoom Layering
• Generating Labels for a Layer
➤ Generating Labels for a
Layer
• Annotations
• Raster Images ➤ Annotations
• Animation Layers ➤ Raster Images
➤ Animation Layers
➤ Drawing Layers
Chapter 5: Mapping in Layers

Drawing Layers Maps as Layers

You have already been introduced to the concept of
computer maps as a collection of layers in the
previous chapter. Each MapInfo table that contains
graphic objects can be displayed as a layer in a Map
window. For example, you can display a table of
customers, a table of streets, and a table of county
boundaries.

Think of these layers as transparencies where each

layer contains a different part of the map. The
layers are stacked one on top of the other and allow
you to see all aspects of the map at the same time. For example, one layer may contain
country boundaries, a second layer may have symbols that represent capitals, and a third
layer might consist of highways. Laying these transparencies one on top of the other builds
a complete map.

Now let’s get into the specifics of creating a map.

The Layers Collection: Building Blocks of Your

Map
The Layers collection is a property of the Map control and contains Layer objects. These
Layer objects, which are built from MapInfo tables, make up your map. Each layer contains
different map features, such as regions, points, lines or text. The Layers collection has
properties and methods used to perform operations such as adding and removing Layer
object(s) from the collection.

74 MapInfo MapX Developer Guide v4.5

 The Layers Collection: Building Blocks of Your Map

How to Get a Layers Collection

One way to get a Layers collection is to load a geoset at design-time. As we said in the
previous chapter, a geoset defines a collection of map layers and their settings.When you
add a Map contol to a form, by default MapX loads the United States Geoset (US.GST). In
other words, you start with the Layers collection as defined in the United States Geoset.

Let’s say you want to write an application that begins with a map of World Countries, that
is, a collection of Layers that together make up a map of the World.You can do this by
specifying the World Countries Geoset at design time:

1. Click Geoset from the Properties Window.

2. Click the drop-down arrow found on the Geoset row.
3. Select World Countries from the list of available Geosets.
The Layers collection as defined in the World Countries Geoset will be loaded when you run
your application. The World Countries map will appear in your Map control.

MapInfo MapX Developer Guide v4.5 75

Chapter 5: Mapping in Layers

The Property Page

A quick way at design-time to see all the Layer objects that comprise a Layer collection is
through the Property Page. The Property Page is an extremely useful place to alter the
properties of a map while you are designing and testing an application. In this case, we will
use it to see the Layers in the World Countries collection.
1. Click Custom from the Properties Window.

2. Click found in the Custom row. The Property Page will appear.
3. Click on the Layers tab to view a list of the Layers in the collection.

You can use this page to modify many properties of Layer objects in the collection, reorder
Layers, or add and remove Layers in the collection.

For example, you can make a layer of the map invisible when the map is displayed by
highlighting the layer and clearing the Visible check box. When the map is displayed, that
layer will not be visible. Of course, you can reset the layer to visible programmatically
during run-time, for example:

Map1.Layers.Item(2).Visible = True
We’ll work a lot more with layers programmatically, in the following section.

76 MapInfo MapX Developer Guide v4.5

 Some Properties of the Layers Collection

Some Properties of the Layers Collection

Each Map has a collection of layers. The Layers collection is made up of Layer objects. The
Layers collection has methods and properties used to add and remove Layer objects from
the collection.

Note: The "MapX Objects" section has a complete listing of Layers Collection methods
and properties.

Get the Number of Layers in a Collectio

A very useful property of any collection is the Count property. This will tell you the number
of items, in this case the number of layers, in a collection. This is used if you want to cycle
through each item in the collection, for example, getting the names of each item:

Dim x as integer
For x = 1 to Map1.Layers.Count
Print Map1.Layers(x).Name
Next

Get a Layer from the Collection

The Item property gets a specific Layer object from the collection. The Item property returns
one of the layers as an object and is the default method for the Layers collection. You can
reference layers by index value, such as 1, 2, and so on, but you can also reference layers by
their names, such as Highways or Cities:

Dim lyr as Layer

Set lyr = Map1.Layers.Item(“Highways”)
-or-
Dim lyr as Layer
Set lyr = Map1.Layers.Item(3)
In your application you will be frequently referencing objects, properties, and methods
through the Layers collection. You can use the fact that Item is the default method to
abbreviate your code.

For example, each of these lines of code makes an identical assignment.

Map1.Layers.Item(3)Visible = False
Map1.Layers(3).Visible = False
Map1.Layers.Item(“Highways”).Visible = False
Map1.Layers(“Highways”).Visible = False

MapInfo MapX Developer Guide v4.5 77

Chapter 5: Mapping in Layers

Get the Geographic Extent of a Collection

The Bounds property returns a Rectangle object representing the geographic extents of all
layers in the collection (except the UserDraw layer). This property is useful if you want to
zoom the map out far enough to show all objects in all layers:

'This sets the map bounds to the geographic extents of all layers
in 'the collection effectively bringing the entire map into view.
On Error Resume Next
Set Map1.Bounds = Map1.Layers.Bounds
End Sub

Some Methods of the Layers Collection

The Layers Collection has several methods that control which layers are in the collection
and how they are displayed. There is also a method that will enable the user to call the Layer
Control dialog allowing users to manipulate the methods and features of a layer. The
methods may also be set at design-time using the Property Page, as discussed earlier in this
chapter.

Note: The "MapX Objects" section has a complete listing of Layers Collection methods
and properties.

Using the Layer Control Dialog

The LayersDlg method presents a dialog where the user can add layers, remove layers,
change layer ordering, and change layer properties.

78 MapInfo MapX Developer Guide v4.5

 Some Methods of the Layers Collection

If the user clicks OK, the changes made within the dialog will immediately be applied to the
map.

Map1.Layers.LayersDlg

Display Options of the Layer Control Dialo

The Display Options dialog enables you to customize the display for each layer in a Map
window. In Layer Control, the user can select a layer and click on the Display button to
bring up the Display Properties dialog. There, the user can change the default styles for the
layer and set the zoom at which a layer displays For example:

MapInfo MapX Developer Guide v4.5 79

Chapter 5: Mapping in Layers

Display Mode
When a user first opens a map, boundaries, lines, points, and text are all displayed using
defaults in the map’s Geoset file. The user can change how objects display by using the
Display Mode section of the Display Options dialog.

For example, the user wants to change the display of streets to a dashed red line. In Layer
Control the user would choose the street layer and click the Display button. This brings up
the Display Options dialog. The user would check the Style Override box to activate the
Style Override button (large gray button). MapX displays the override buttons that are
appropriate for the type of objects in the layer. For example, if the layer contains streets, a
line style override button displays. Clicking on it to will access the Line Style dialog where
the user can change the width, style, and color of the streets.

For boundary layers, the style override button brings up the Region Style dialog where the
user can change both the fill and borders of boundaries. The Symbol Style dialog displays
when the user wants to override the style for layers containing symbols or points. The Style

80 MapInfo MapX Developer Guide v4.5

 Some Methods of the Layers Collection

Override is only in effect during the current work session, as are the other display settings.
To make them permanent,you would have to modify the geoset.

Create a Layer
Allows you to create a new temporary or permanent MapInfo table layer. The method
returns a Layer object—the Layer object that was added to the collection.

dim lyr as layer

set lyr = Map1.Layers.CreateLayer (“Temporary”)

Add a Layer
Adds an existing layer to the collection and displays it on the map.

When adding a layer, you can specify the position of the layer in the collection with the
optional Position parameter. If no Position parameter is specified, the layer is positioned
automatically with respect to other layers in the map. For example, a layer with points is
placed above a layer with regions.

Map1.Layers.Add “C:\Data\Counties.tab”
-or-
Private Sub mnuAddLayers_Click()
'This uses the common dialog to open a MapInfo Table and add
it
as a layer.
Dim sFile As String
With dlgCommonDialog
.DialogTitle = "Add Layer"
.Filter = "MapInfo Tables (*.tab)|*.tab"
.ShowOpen
If Len(.filename) = 0 Then
Exit Sub
End If
sFile = .filename
End With
On Error Resume Next
Map1.Layers.Add sFile
End Sub

Remove a Layer
The Remove method removes a specified layer from the map.

Map1.Layers.Remove 3

MapInfo MapX Developer Guide v4.5 81

Chapter 5: Mapping in Layers

Remove All Layers

The RemoveAll method removes all layers from the map.

Private Sub btnLayersRemoveAll_Click()

Dim nLayers As Integer
nLayers = Map1.Layers.Count
' remove all of the layers
Map1.Layers.RemoveAll
nLayers = Map1.Layers.Count

Reposition a Layer
The Move method repositions a layer in the Layers collection. The first parameter is From
position (the top layer = 1) and the second parameter is the To position.

Map1.Layers.Move 1,2

The Layer Object

The Layer object represents vector mapping data in the form of a collection of map features
having a predominant feature type, such as regions, lines or symbols. Typically, a Layer
object corresponds to the geographic objects from one MapInfo table. Each of the Layer
objects in a Layer collection behaves independently of the others. Their styles may be
changed, their zoom layering altered, etc., on an individual basis, without affecting any of
the other layers.

You may manipulate the layer object at any time within a program. You can also use the
Property Page to set layer properties at design-time, as discussed above. The Layer object
has many properties and methods. The methods used to get features from a Layer are
discussed in "Features and Selections".

Some Layer Properties

Note: For a complete listing of the Layer object methods and properties, see The Layer
object and collection in "The MapX Objects" section.

AutoLabel
Controls whether the layer is automatically labeled.
Map1.Layers(“States”).AutoLabel = True

82 MapInfo MapX Developer Guide v4.5

 The Layer Object

Name
Name of the layer.
MsgBox Map1.Layers(4).Name

OverrideStyle
Whether to override this layer’s default display characteristics.
Map1.Layers(9).OverrideStyle = True

Selectable
Sets MapX to recognize when a user clicks on this layer.
Map1.Layers(“States”).Selectable = True

Style
The layer style to use if OverrideStyle is True.
Map1.Layers(9).Style = newstyleobject

Visible
Whether or not a layer is visible.
Map1.Layers.Item(2).Visible = False

ZoomLayer
Sets zoom layering on or off.
Map1.Layers(“States”).ZoomLayer = True

ZoomMax
Sets the maximum zoom level at which a layer will be visible.
Map1.Layers(“States”).ZoomMin = 580

ZoomMin
Sets the minimum zoom level at which a layer will be visible.
Map1.Layers(“States”).ZoomMin = 45
See "The MapX Objects" section of this book or on-line help system for a complete list of
Layer properties.

MapInfo MapX Developer Guide v4.5 83

Chapter 5: Mapping in Layers

Layer Order
Map layers in a Layers collection display in increasing index order (i.e., Layers(1) is the top
layer, Layers(2) is the layer underneath Layer(1), etc.), with the bottom layer drawn first and
the top layer drawn last. It is important to order your layers correctly.

For example, suppose that you have a layer of customer points and a layer of census tracts.
If the layers are incorrectly ordered in the Layers collection, MapX will draw the customer
points first and then display the census tract layer second. Your points would be obscured
by the census tract layer.

You can reorder how layers are displayed in a Map at design time. From the Layers tab of
the Property Page, select the layer(s) you want to reorder and choose either the Up or Down
button to move the layer(s) to a position above or below its current position.

To allow the user to reorder layers at runtime, use the LayersDlg method to present the
Layer Control dialog, as discussed elsewhere.

Layer order is also important when you use the Select tool. The Select tool selects objects
from the topmost Selectable layer. If you have several objects at the same location, it is
difficult to select the exact one you want. You can reorder your layers so that the layer you
want to select from is the new topmost layer. Tools are discussed in "Tools".

Examining Layers
There are many instances where you might want to examine layers in a collection. Here’s a
simple code fragment to iterate through a Layers collection to determine what types of
layers are present, and to display a message in a dialog box indicating the layer type.

Dim lyr as Layer

For Each lyr in Map1.Layers
Select Case lyr.Type
Case miLayerTypeNormal
MsgBox “Layer ” & lyr.Name & “ is a normal layer”
Case miLayerTypeRaster
MsgBox “Layer ” & lyr.Name & “ is a raster layer”
Case miLayerTypeSeamless
MsgBox “Layer ” & lyr.Name & “ is a seamless layer”
Case miLayerTypeUnknown
MsgBox “Layer ” & lyr.Name & “ is an unknown layer”
Case miLayerTypeUserDraw
MsgBox “Layer ” & lyr.Name & “ is a user draw layer”
Case miLayerTypeDrilldown

84 MapInfo MapX Developer Guide v4.5

 Checking a Layer’s Feature Type

MsgBox “Layer ” & lyr.Name & “ is a drilldown layer”

Next
In the code fragment we are using MapX-defined constants for all the layer types. These
constants are collectively known as LayerTypeConstants.

Checking a Layer’s Feature Type

This code fragment iterates through the Layers collection by index. It examines each Layer
object in the collection and determines the type of features present in the layer.

Dim i as Integer
For i = 1 To Map1.Layers.Count
Select Case Map1.Layers(i).PredominantFeatureType
Case miFeatureTypeRegion
MsgBox “Layer ” & lyr.Name & “ contains regions”
Case miFeatureTypeLine
MsgBox “Layer ” & lyr.Name & “ contains lines”
Case miFeatureTypeSymbol
MsgBox “Layer ” & lyr.Name & “ contains symbols”
Case miFeatureTypeMixed
MsgBox “Layer ” & lyr.Name & “ contains mixed
features”
Case miFeatureTypeUnknown
MsgBox “Layer ” & lyr.Name & “ contains unknown _
features”
Case miFeatureTypeText
MsgBox “Layer ” & lyr.Name & “contains text features”
Next
The Layers collection has a one based index, so we iterate from an index value of one
through the count of the Layers collection. We also evaluated the PredominantFeatureType
property of each layer in the collection, using the FeatureType constants for evaluating the
PredominantFeatureType.

MapInfo MapX Developer Guide v4.5 85

Chapter 5: Mapping in Layers

Zoom Layering
Sometimes you want a map layer to display only at certain zoom levels. Zoom layering
allows you to view a map layer when the map's zoom level falls within a preset distance.
You can set a different zoom layering level for each layer.

For example, if your map includes a street map layer, you may find that the streets become
illegible when the user zooms out too far.

Using zoom layering, you might set up your map so that MapX automatically hides the
streets whenever the user zooms out to show an area larger than 5 miles.

86 MapInfo MapX Developer Guide v4.5

 Zoom Layering

The follwing sample code adds a layer to the map using the Layers collection Add method
and sets up zoom layering by modifying the Layer object’s properties.

Dim lyrStreets As Layer `Creates the layer object

`Sets the Streets table as the layer object and orders the layer
in `the map as number 3.
Set lyrStreets = Map1.Layers.Add(“Streets.tab”, 3)
lyrStreets.ZoomLayer = True `Sets zoom layering to true
lyrStreets.ZoomMin = 0 `Sets minimum zoom to 0 miles
lyrStreets.ZoomMax = 5 `Sets maximum zoom to 5 miles
Once you set zoom layering for a layer, when you zoom within the minimum and maximum
zoom levels, the layer will display on the map.You can zoom in on your map with the zoom
tools or the ZoomTo method of the Map object. With the ZoomTo method you specifiy a
zoom level and the x and y coordinates to center the map.

Map1.ZoomTo 3, -70.26, 44.05

Since the zoom value of 3 miles is within the the minimum and maximum zoom levels, the
Streets layer will center around the point -70.26, 44.05 and display 3 miles of the map across
the width of the map control.

MapInfo MapX Developer Guide v4.5 87

Chapter 5: Mapping in Layers

Different layers in the same Map window can be displayed at different zoom levels. For
example, you have a layer of streets, a layer of county boundaries, and a layer of state
boundaries. You want the streets layer to be visible only when the zoom level is less than
eight miles. You want the county boundary layer to display when the zoom level falls
between 20 miles and 200 miles. You want the states boundary layer to be visible only when
the zoom level is greater than 100 miles. You can set a different zoom level for every layer in
your map.

Generating Labels for a Layer

MapX provides many ways to label attributes of geographic objects in a map layer. Their
drawn location is based on the location of the geographic object’s centroid and additional
information such as anchor point and offset.

As attributes, labels are dynamically connected to their map objects. If the layer is closed or
is made invisible, the labels no longer display. If the data or geographic information
changes, the labels change. If you create an expression for your labels and change the
expression, the current labels are dynamically replaced with new ones.

88 MapInfo MapX Developer Guide v4.5

 Generating Labels for a Layer

Whether you label your map automatically, or interactively using the Label tool or the
LabelAtPoint method, the content of the label is determined by the data associated with the
geographic object.

In addition to label content, you control the position, display, and look of automatic labels
by using properties in the LabelProperties object. You can set conditions for displaying
labels, in the style in which will display, and in what position for all the objects in the layer.

For additional information, see topic "Controlling Label Display".

Controlling Label Display

To automatically generate labels for a layer, set the layer's AutoLabel property to True.

Each Layer object has a LabelProperties object, which controls many aspects of labels. For
example, to hide all of a layer's labels, set the LabelProperties.Visible property to False. To
specify the maximum number of labels you want to display on your map, set the LabelMax
property. The Duplicate property controls whether features with the same name can have
separate labels on the map simultaneously. The Overlap property controls whether labels
are allowed to overlap; setting Overlap to True can cause more features to be labeled, but
you may find that overlapping labels are harder to read.

Zoom-layering Labels
You can configure labels to display only within a specific zoom range, much the same
way that you display map layers within a certain zoom range. To specify a zoom range
for labels, set the LabelZoom, LabelZoomMax, and LabelZoomMin properties of the
LabelProperties for the layer.

Label Position
To control label positions, set the Position property (which controls whether labels are
above, below, or to the side of the feature's centroid), and the Offset property (which
controls how far the label is offset from the feature).
The default anchor point depends on the layer's predominant feature type. For example,
a layer of region features defaults to having labels centered over region centroids.
For line/polyline features (such as street maps), you can make labels run parallel to the
line features—set the Parallel property to True.

MapInfo MapX Developer Guide v4.5 89

Chapter 5: Mapping in Layers

Creating Callouts
Callouts are labels with lines pointing to the objects they are labeling. They are very
useful when there are many labels in a relatively small area. For example, you are
labeling a map of Asia. There are many small countries that are relatively close together.
If you tried to label all the countries, the labels would overlap and be difficult to read.
To display callout lines, set the LabelProperties.LineType property to
miLineTypeSimple (1) or miLineTypeArrow (2) for the layer that you want to label.

Label Styles
To make style changes for all the labels set the Style.
You can also set the appropriate style options. Make the style changes you want. When
you return to the map, the selected labels display with the style changes you specified.
There are also background options. Set the appropriate options to have no background,
or halo to create a halo effect around the text. This puts the text into relief from whatever
it covers (e.g., part of a region, or a street, etc.).

Interactive Labeling
Although you will probably do most of your labeling automatically, in some cases you
may want to create labels one at a time, using a Label tool. The Label tool is one of the
standard tools built into MapX. To activate the tool, set the Map.CurrentTool property
to miLabelTool (1010); the user will be able to label a map feature by clicking on the
feature.
The easiest way to remove all labels in a layer is to use the Visibility setting. It will
disable the display of all the labels in that layer, both automatic and custom labels. To
clear only the custom labels (those labels placed using the Label tool), use the
ClearCustomLabels method.
Dim DS As Object
Dim DB As Object
Dim RS As Object
Dim Temp As Object
Set DB = Workspaces(0).OpenDatabase("Mapstats.mdb")
Set RS = DB.OpenRecordset("USA")
Set DS = Map1.Datasets.Add(miDataSetDAO, RS)
Set Map1.Layers("usa").LabelProperties.Dataset = DS
Set Temp = DS.Fields("GEONAME")
Set Map1.Layers("usa").LabelProperties.DataField = Temp

90 MapInfo MapX Developer Guide v4.5

 Annotations

Annotations
Although the labeling feature takes care of most of your text needs, you may still need to
create text objects to annotate your map. Unlike labels, text annotations are not connected to
data— you can place an annotation anywhere on the map, even if there are no features at
that location.

To add text or symbol annotations to your map, use the methods and properties in the
Annotations collection and object.

Each Map has a collection of Annotations (Map.Annotations property). Annotations are

either symbol or text objects, and are drawn on top of the map
Annotations are typically used to add text messages to a map, or to put symbols on a map.
These annotations scale with the map as you zoom in and out. Annotations are not tied to a
particular map layer. Annotations are always on top.

Note that the Annotation object has no properties for setting the position, symbol style, or
text. To control these aspects of an annotation, you use the Annotation.Graphic property to
obtain a Graphic object, then modify the Graphic object.

Raster Images
Raster images are a type of computerized picture consisting of row after row of tiny dots
(pixels). Raster images are sometimes known as bitmaps. Aerial photographs and satellite
imagery are common types of raster data found in GIS.

Displaying Raster Images as Map Layers

With MapX you can display raster images (bitmaps) as backdrops to the maps you
create.However, the raster image must first be part of a MapInfo table. You then can overlay
additional data, such as street maps and customer locations, on top of the image.

MapInfo MapX Developer Guide v4.5 91

Chapter 5: Mapping in Layers

Although a raster image can be a picture of a map, the image cannot have data attached to it.
The image is for viewing, as a backdrop or "underlay."

How to Display a Raster Image

Each raster image must have a corresponding '.TAB' file which stores the image's
geographic coordinates. The .TAB file is created by using MapInfo Professional to 'register'
the image.

Note: When you display a raster image as a map layer, MapX automatically sets the rotation
and projection of all the vector map layers, so that they match the rotation and projection of
the raster image.

Animation Layers
The Animation layer is useful where map features need to be updated frequently, such as in
real-time applications. For example, you can develop a fleet-management application that
represents each vehicle as a point object. You can receive current vehicle coordinates by
using GPS (Global Positioning Satellite) technology, and then update the point objects to
show the current vehicle locations on the map. In this type of application, where map
objects are constantly changing, the map redraws much more quickly if the objects being
updated are stored in the animation layer instead of a conventional layer.

92 MapInfo MapX Developer Guide v4.5

 Drawing Layers

Initially AnimationLayer is set to null. You can assign a Layer object to the property to make
that Layer the animation layer (it can be a regular layer or user draw layer). When a layer is
assigned to the AnimationLayer property, it is drawn on top of all layers, including the
Annotations layer and selections. The layer is still in the same position in the Layers
collection. Floating objects like legends are still displayed on top of the animation layer,
although they don't have to be re-drawn each time because they are clipped out. If a normal
layer is used as the animation layer, selections and labeling will still work.

Example
Set Map.Layers.AnimationLayer = Layers(3)
The property can be used to identify what layer is currently the animation layer (if any):
for each lyr in Map.Layers
if Map.Layers.AnimationLayer = lyr the ...
end if
next
To turn off the animation layer, you assign null to it:

Set Map.Layers.AnimationLayer = nothing

This turns the layer back into a normal layer, which is still positioned in the same place in
the layer list.

Drawing Layers
The AddUserDraw Layer method of the Layers collection gives developers the ability to
draw layers on a map. It is used in conjunction with the DrawUserLayer event, which is
fired when the layer needs to get drawn. The method returns a newly created Layer object.
There can be any number of user draw layers.

MapInfo MapX Developer Guide v4.5 93

Chapter 5: Mapping in Layers

How It Works
First, you add a user draw layer to your layers collection:

' this sets the UserDraw Layer to “My Layer”

Dim lyr as Layer
Set lyr = Map1.Layers.AddUserDrawLayer("My Layer", 1)
Then you put the code to do the drawing on the layer in the DrawUser Layer event. When
the application creates a UserDraw layer using the AddUserDrawLayer method of the
Layers collection, an event is fired to the application when the window needs updating.

94 MapInfo MapX Developer Guide v4.5

Chapter 6: Putting Your Data on the Map
5
Chapter

➤ What is Data Binding?

Putting Your Data On The ➤ The Power of Adding Your
Data to a Map
Map
➤ How to Add Your Data to a
Map
Datasets enable you to bind user data to your maps.
For example, if you have a Microsoft access ➤ Dataset Object
database of sales by county and you had a Lotus ➤ Datasets Collection
Notes database of the location of your sales force,
➤ Using the Datasets.Add
you could bind that data to a map and spot trends
Method
or notice correlations between the two sets of data.
➤ Using the Fields Collection
➤ Using the Fields.Add
Method
➤ Displaying Your Data as a
Layer of Points
(BindLayer)
➤ Making Your New Layer of
Points a Permanent Layer
➤ How Data Binding Uses the
GeoDictionary
➤ The Different Types of Data
Sources
Chapter 6: Putting Your Data on the Map

What Is Data Binding?

Data binding is the process of bringing data from a data source into MapX.

There are many different types of databases in businesses today; therefore, MapX lets you
bind to several different types of DataSources. In MapX, the data is represented as a Dataset
object. The first argument to the Datasets.Add method lets you specify a
DatasetTypeConstants value, which dictates the type of data binding you wish to perform.
Types of data sources you can bind to include:

Data Source Description

ADO This type of databinding uses the MS Active data objects ADO
recordset.
DAO A DAO Recordset object. You can get one from a Visual Basic data
control, an Access form, or by creating one in Visual Basic, Access,
or C++.
Delphi This type uses the Borland BDE datasources.
Global Handle This type of data binding lets you pass in a block of tab-delimited
data.
Layer This type of data binding lets you create a Dataset that uses fields
from a MapInfo table.
Notes View/ These types of data binding deal specifically with Lotus Notes.
NotesQuery
ODBC MapX can use ODBC to retrieve data from any ODBC data source.
OLE Data This is for containers such as PowerBuilder.
Oracle Express This allows access to the datacube as a Dataset.
Objects
RDO This uses MS Remote Data Objects and RDO Resultset object.
SafeArray A COM Dataset that allows static binding of data from a safe-
array.
Unbound If you cannot support one of the other formats, MapX provides a
‘back door’. With this type of data binding, you can set up an
event loop whereby MapX asks the container for data values, one
cell at a time.

These custom, user-created types of data binding are discussed in detail, later in the chapter.

96 MapInfo MapX Developer Guide v4.5

 The Power of Adding Your Data to a Map

The Power of Adding Your Data to a Map

There are two major advantages to binding your own data to a map:

• You can view the data as features on a map. Let’s say you have a Microsoft Access
table of your sales office locations for the United States. Through data binding you
can add your table as a Dataset with the Datasets.Add method using a BindLayer
object as one of the parameters. This will create a new layer in your map and
display each sales location as a point on the United States map. Once you add the
data to the map, you can use MapX to easily create an application that finds the
nearest sales location to an address entered by a customer. Finding features on a
map is discussed in "Finding Features on a Map".
• You can bind your attribute data to a map and then use it to create a thematically
shaded map based on your data. Let’s say your Microsoft Access table of sales
locations also contains a column of total sales volume for each location. Using the
Datasets.Add method you can add the column containing total sales volume to
your United States map. Once you add the data to the map, you can create a theme
shading sales volume by state. Theme mapping is discussed in "Theme Mapping
and Analysis".

How to Add Your Data to a Map

Data binding can be done two ways:

• If you have Visual Basic for bound data controls, at design time you can use the
Dataset property of the Map object.
-or-
• Bind data programmatically by using the Datasets.Add method. With this method,
you can tell MapX which data source to use, some information about it, and which
map layer to bind it to. Alternately, the Add method allows you to bind data
without explicitly specifying the nature of the data; in this case, MapX analyzes
your data and automatically determines the best way of binding your data to the
map.
The binding process results in the creation of a Dataset object. This Dataset, which is added
to the Datasets collection, contains computed values for features in the map layer that the
data is bound to. For example, if data is bound to US States map, each state would have a
new data value that could then be used to control how the states are drawn. If the data
source had multiple records for a state, the values could be summed, averaged, or counted.
The Dataset has a Value property you can use to access the computed value for each row
(that is, feature) of the map.

MapInfo MapX Developer Guide v4.5 97

Chapter 6: Putting Your Data on the Map

With most types of data binding, the DataSource (the second parameter for Dataset) is
actually an OLE interface. MapX uses the interface to access the data directly from the data
source. The data isn’t actually passed to Datasets.Add.

Dataset Object
The Dataset Object is the result of binding data from a data source into MapX.

A Dataset contains computed values for features in the map layer to which the data is
bound. The data sources may be a DAO Recordset, ODBC data source, Global Handle (this
is a way to pass in a block of tab delimited data), OLE Data (this is for containers such as
PowerBuilder), and Unbound Data (where MapX asks the container for data values, a cell at
a time).

Datasets Collection
The Datasets collection is an object representing all of the Datasets for a map. The Datasets
collection has methods and properties used to add, remove, or work with existing Dataset
objects in the collection.

Adding a Dataset Object or removing a Dataset object from a specified collection is

accomplished using the methods listed below:

Method Description Code Sample

Add Creates a specified Dataset and Set ds = Map1.Datasets.Add_
adds it to the collection. (miDatasetDAO, rs)
Remove Removes a specified Dataset object Map1.Datasets.Remove 2
from the Datasets collection.

Using the Datasets.Add Method

With the Datasets.Add method, you can bind data from a data source into MapX. This will
tie data from an external data source to a map. The Datasets.Add method allows you to

98 MapInfo MapX Developer Guide v4.5

 Using the Datasets.Add Method

designate a specific Dataset and add it to a collection of Datasets. Let’s look at the syntax of
the Datasets.Add method.

Note: Optional parameters are in [square brackets].

Datasets.Add Type, SourceData, [Name], [Geofield], [SecondaryGeofield], [BindLayer],
[Fields], [Dynamic]

Type Parameter
This parameter is the type of Dataset being added. This parameter takes a
DatasetTypeConstants value.

DatasetType Constants
Type Description

miDatasetADO ADO
miDatasetDAO Data Access Object
miDatasetDelphi Borland Delphi Native
miDatasetDelphi4 Borland Delphi4
miDatasetDrelphi5 Borland Delphi 5
miDatasetGlobalHandle Tab delimited data
miDatasetLayer MapInfo Table
miDatasetNotesQuery Lotus Notes Query
miDatasetNotesView Lotus Notes View
miDatasetODBC ODBC Database
miDatasetOEO Oracle Express Objects
miDatasetOLEData OLE datasource
miDatasetRDO RDO
miDatasetSafeArray Safe Array
miDatasetUnbound MapX requests data from container.

SourceData Parameter
This parameter is a reference to the data, and is different depending on the Dataset Type.
With most types of data binding, the DataSource (the second parameter for Datasets.Add) is

MapInfo MapX Developer Guide v4.5 99

Chapter 6: Putting Your Data on the Map

actually an OLE interface. MapX uses the interface to access the data directly from the data
source. The data isn’t actually passed to Datasets.Add.
Here are valid data sources for each of Dataset type:

Dataset Type Valid Source Data

miDatasetADO ADO table

miDatasetDAO A DAO Recordset object.
miDatasetDelphi Delphi Native
miDatasetDelphi4 Delphi4 recordset
miDatasetDelphi5 Delphi5 recordset
miDatasetGlobalHandle A variant with type of VT_I4 and the lVal equal to the
global memory handle.
miDatasetLayer A MapInfo table.
miDatasetNotesQuery Lotus Notes Query
miDatasetNotesView Lotus Notes View
miDatasetODBC An ODBCQueryInfo object.
miDatasetOLEData Ignored by Datasets.Add.
miDatasetRDO RDO table
miDatasetSafeArray Safe Array
miDatasetUnbound Nothing (instead, use the RequestData event to access
data whose format is known only to the programmer).

Name Parameter
This parameter is a string that uniquely identifies the Dataset. This is an optional parameter,
and if not specified, a name in the form of DatasetN is used where N is a unique number.

Geofield Parameter
This parameter is the name or index of the column in the data source that contains the
geographic information. If this parameter is not specified, MapX searches the fields to
determine which column in the data source contains the geographic information as
specified in the GeoDictionary. This will not necessarily be a geographic data field, as it
could be a unique key column such as zip codes. However, if you know which column in
the data source contains the geographic information, you should specify it.

100 MapInfo MapX Developer Guide v4.5

 Using the Datasets.Add Method

If you plan to view the data as features on a map, the GeoField column in your data source
must be unique. The GeoField column will be used to name the features in the new point
layer. Non-unique values will result in a single point being added to the new point layer for
the first occurrence of the duplicate key value, and data values in the duplicate rows will be
aggregated.
If a Fields collection is specified, the Geofield parameter refers to columns in the Fields
collection rather than in the source data.

MapInfo MapX Developer Guide v4.5 101

Chapter 6: Putting Your Data on the Map

Secondary Geofield Parameter

This parameter is only required when the layer that a Dataset is being bound to has a key
column that is not unique. For example, using the MapInfo table “United States Counties”
to bind data against requires a secondary geofield parameter because county names are not
unique to one state. Multiple states in the table have counties named “Warren” or
“Washington”, among others. Thus, more information is needed to resolve the potential
ambiguity during the data binding process. When do we want to bind our data to Warren,
New York and when to Warren, New Jersey? By specifying the “County” column as the
Geofield and the “State” column as Secondary Geofield, MapX can figure out which data
gets bound to Warren, New York and which data gets bound to Warren, New Jersey by
refining the data binding process to counties within each state. This concept is identical to
the Refining Boundary when creating a Find object. For additional information, see
"Finding Features on a Map".

If a Fields collection is specified, the SecondaryGeofield parameter refers to columns in the

Fields collection rather than in the source data.

BindLayer Parameter
This parameter specifies the map layer to attach your data to if you are binding attribute
data, or, a BindLayer Object if incoming data is to be georeferenced to a point reference file
(such as Zip Codes) or contains Long/Lat values. This is an optional parameter, and if not
specified, MapX searches layers in the GeoDictionary to attach to.

If you know which map layer should be bound to, you should specify it for performance
reasons. When doing BindLayer matching, the Geofields must be unique. Only the first item
of a non-unique set of data will be matched. The rest are ignored. The BindLayer is
discussed in more detail later in this chapter.

Fields Parameter
This parameter is a Fields object that is a collection of Field objects. The Field objects are
used to describe which fields from the data source to bring in, and which aggregation
function to use if more than one record for the data source matches a particular map feature.
This will set up a collection of fields (columns) you wish to bind to the map. This is an
optional parameter, and if not specified, all columns are brought in, and the data values are
summed if more than one record is encountered per feature. The Fields collection is
discussed in more detail later in this chapter.

102 MapInfo MapX Developer Guide v4.5

 Using the Fields Collection

If a Fields collection is specified, the Geofield and SecondaryGeofield parameters refer to

columns in the Fields collection rather than in the source data.

Dynamic Parameter
This parameter is a boolean value that controls whether the data binding is dynamic. It is
optional; if omitted, it will default to False, meaning that the binding is static (i.e., MapX will
copy needed data when the database is opened). If you specify True, MapX accesses data in
a live manner, only as data is needed (e.g., when labeling). If you specify True but the
Dataset does not support dynamic columns, an exception will be thrown.

Using the Fields Collection

A data source may have many columns of data. MapX has overhead for each column of
data that is bound, so you should only bind data that is needed in the map (such as data you
want to thematically map or label with). Use the fields parameter of Datasets.Add to set up
a Fields collection of the fields (columns) you want to bind to the map.

Note: When declaring a fields variable, declare it as "MapXLib.Fields". This is to

prevent conflicts with the DAO "Fields" object.
Dim flds As New MapXLib.Fields
You can access a Dataset’s Fields collection through the Dataset.Fields property.

Method Description Code Sample

Add Adds a field to a Fields collection. flds.Add “Sales”, “Sum_of_Sales” _

, miAggregationSum
Remove Removes a field from a Fields flds.Remove 3
collection.
RemoveAll Removes all Field objects from the flds.RemoveAll
collection.

Using the Fields.Add Method

The Fields.Add method enables you to add a column of data from your data source as a
field to the Fields collection. The Fields collection is built to use with the Datasets.Add

MapInfo MapX Developer Guide v4.5 103

Chapter 6: Putting Your Data on the Map

method (or with the Themes.Add method; see "Thematic Mapping and Analysis"). The
Fields parameter of Datasets.Add takes a Fields collection, and is built using this Add
method. The Add method cannot be used on a Dataset’s Fields collection once the Dataset
has been created.

For an in depth look at the Fields.Add method, see the reference entry for Fields.Add in the
"The MapX Objects" section.

Data Aggregation
The Aggregate Function parameter of the Fields.Add method determines how MapX
computes the Field value when multiple matches are found.

For example, if the data looked like the following:

STATE SALES
CA 120
NY 100
CA 50
CA 110

Here there are three sales in California, and since only one data value will be attached to
California, we need to tell MapX to either sum the sales, average the sales, or count the sales.

The Aggregate Function parameter of the Fields.Add method defaults to

miAggregationIndividual for string columns, and miAggregationSum for numeric columns.

The following are the aggregates used to handle multiple matches:

Aggregation Function Constants

Here is a list and brief description of the Aggregation Function Constants.

Constant Description

miAggregationAuto Automates MapX’s selection of aggregation method

based on the data in use.
miAggregationSum Sums up the data.
miAggregationAverage Takes an average of the data.
miAggregationIndividual Pulls in each individual record.
miAggregationCount Counts the records.

104 MapInfo MapX Developer Guide v4.5

 Displaying Your Data as a Layer of Points (BindLayer)

Displaying Your Data as a Layer of Points

(BindLayer)
BindLayer data binding is a type of data binding where source data is used to create a new
layer of points at the locations specified by your data. This happens in two cases:

• When your data contains x and y coordinates (such as longitude and latitude).
Points are created at the specified location. See "Displaying Your X / Y Data as a
Layer of Points on a Map".
• When your data contains reference information, such as Zip Codes.
Points are created at the Zip Code location (approximate location). See "Displaying
Your ZIP Code Data as a Layer of Points on a Map".
The BindLayer object is required when binding data that has X/Y coordinates or point
information such as Zip Codes, and you want to see points created in a new or existing layer
at the locations specified by your data.

When you add the Dataset using a BindLayerObject, the points automatically show up on
the map. This is not the case when adding a Dataset without the BindLayerObject. Only
BindLayer Objects have this behavior.
The points will be brought in as gray stars. If you wish to change the style, you must set the
Layer.OverrideStyle property equal to True and change the style properties. The style
changes will not show up unless Layer.OverrideStyle is set to True.

BindLayer Object Properties

Property Description Values
LayerType Specifies the layer type that the A BindLayerTypeConstant:
data is being bound to. • MiBindLayerTypeNormal
• MiBindLayerTypeXY
• MiBindLayerTypePointRef
CoordSys Specifies the coordinate system in A CoordSys Object
which the layer will be created.
FileSpec Allows you to specify the name A text string that identifies a file
and location of a file, so that the path and file name.
Datasets.Add method can create a
permanent layer instead of a
temporary layer.

MapInfo MapX Developer Guide v4.5 105

Chapter 6: Putting Your Data on the Map

Property Description Values

KeyLength A positive number, representing A numeric value (1-254).

the desired size of the character
column in the resulting layer.
LayerName Specifies the name of the layer A string value.
which to bind the data to if
LayerType is
miBindLayerTypeNormal. It is
the name of the newly created
layer if LayerType is
miBindLayerTypeXY or
miBindLayerTypePointRef.
RefColumn1 The field containing the longitude A string or integer referencing a
when LayerType is column (one-based index).
miBindLayerTypeXY, or the field
containing the reference value
(such as ZIP Code) if LayerType is
miBindLayerTypePointRef.
RefColumn2 Specifies the field containing the A string or integer referencing a
latitude when LayerType is column (one-based index).
miBindLayerTypeXY.
ReferenceLayer Specifies the name of the reference A string.
file to use if BindLayer.LayerType
is miBindLayerTypePointRef.

106 MapInfo MapX Developer Guide v4.5

 Displaying Your Data as a Layer of Points (BindLayer)

The order of operations for using a BindLayer object is as follows:

1. Create a BindLayer object.
2. Use this object when adding the Dataset by passing it as the BindLayer parameter in
the Datasets.Add method.
How to create a BindLayer object and display your X / Y or point reference data are shown
below.

Displaying Your X / Y Data as a Layer of Points on a Map

If your data contains X / Y coordinates, you can create and display a layer of point features
through data binding. Use a BindLayer object, and set :

• Its LayerType property to be miBindLayerTypeXY.

• Its RefColumn1 property to be the name or index (one-based) of the column
containing the X coordinate values.
• Its RefColumn2 property to be the name or index (one-based) of the column
containing the Y coordinate values.

Displaying Your ZIP Code Data as a Layer of Points on a Map

If you have a table of data that has no X / Y coordinates but it has point reference
information such as ZIP Codes, you can still display your data as points on a map. A process
known as point reference binding allows you to data bind against a separate reference layer
containing X / Y coordinates for your ZIP Code-based table of data. You do this by
specifying the reference layer in the BindLayer object when setting up the BindLayer object,
as shown below.

MapX supplies a table called Us_zips.tab in the \MapInfo\MapX 4.0\Maps directory which
you can use as your reference layer for US ZIP Codes. Us_zips.tab also has a “friendly
name” (the description that is assigned to the layer through the geodictionary) which is “US
5 Digit ZIP Code Centers.”

Note: In previous versions of MapX MapInfo shipped a file for ZIP Code binding called
Zipcodes.cpf. We no longer ship that file. In place of Zipcodes.cpf we ship
Us_zips.tab

MapInfo MapX Developer Guide v4.5 107

Chapter 6: Putting Your Data on the Map

To create and display a layer of point features through ZIP Code data binding, use a
BindLayer object, and set :
• Its LayerType property to be miBindLayerTypePointRef.
• Its RefColumn1 property to be the name or index(zero-based) of the column in your
table containing the zip code (or other point reference) data.
• Its ReferenceLayer as the name of the reference file to use. A reference file contains
the x and y coordinates that the data binding process will use to determine the
geographical location for your ZIP Code data on the map. The ReferenceLayer
property can be set to a layer's filename (a full file specification) or set to the layer's
"friendly name" (the description that is assigned to the layer through the
geodictionary).
Note: The reference layer does not need to be displayed in the map, but it must be
installed in your geodictionary.
The RefColumn2 property is not used in ZIP Code data binding because US ZIP Codes are
unique.

Making Your New Layer of Points a Permanent

Layer
It’s easy to make your new layer of points, created with a BindLayer object, a permanent
MapInfo table. Use the BindLayer.Filespec property or specify the name and location of a
file, so that the Datasets.Add method can create a permanent layer instead of a temporary
layer. If you do not assign this property, the layer is temporary. This property applies to both
X / Y data binding and point reference (zip code) data binding.

108 MapInfo MapX Developer Guide v4.5

 How Data Binding Uses the GeoDictionary

How Data Binding Uses the GeoDictionary

MapX uses a GeoDictionary file (named GEODICT.DCT by default) to keeps track of
information related to data binding. MapX comes with a utility—
GeoDictionaryManager40.EXE—which helps you manage the GeoDictionary.

When you use the Datasets.Add method, MapX can analyze your data to determine how the
data might be bound to the map. Specifically, the method has these automated behaviors:

• Determines which column in the data source contains geographic information.

• Determines which map layer to bind to.
Both of these behaviors are optional. There are parameters so that you can explicitly specify
which column in the data source contains the geographic information, as well as which map
layer should be bound to. If you know either of these values, you should specify them
explicitly to improve performance.
For MapX to be able to bind data to a map layer, the following things need to be true:
1. The map’s geographic key column needs to be indexed.
Most maps come with indexed key columns when they are installed, but it is up to
the map maker to decide which columns are key columns. For example, the United
States table could have at least 3 key columns: state name (“New York”), state
abbreviation (“NY”), and FIPS code (36). The United States map that MapInfo ships
has the first two as key columns, thus requiring data from the data source to also
have either state name or abbreviation.
2. The map and its key columns must be specified in the GeoDictionar .
Some key columns from the map layer might not contain unique values. An
example of this is United States county names: multiple states have counties named
“Warren” or “Washington”. Thus, when a row of data has the county name
"Washington," MapX needs more information to resolve the ambiguity. For the
United States Counties example, State is used to resolve ambiguity. The parameter
SecondaryGeoColumn is used to specify the column in the data source that contains
the information needed to resolve the ambiguity. The GeoDictionary contains
information about which maps have non-unique keys and what their refining map
is.

MapInfo MapX Developer Guide v4.5 109

Chapter 6: Putting Your Data on the Map

MapX Events Used by Data Binding

Once a column is defined as the geographic column from the data source, and a map layer
to bind to is determined, binding begins. Each row of the data source is ‘matched’ to a
feature and the data is brought in. If a row contains a geographic column that doesn’t match
a feature (perhaps a typo [“NA” instead of “MA”] or simply a data value that’s not on the
map [“Puerto Rico”]), a DataMismatch event is fired to notify the container. You can ignore
the DataMismatch event, in which case MapX simply ignores the row

During automatic data binding, MapX calls the ResolveDataBind event if the data is
ambiguous.

During "unbound" data binding, you use the RequestData event to set up a loop, so that the
container provides data to MapX one cell at a time.

Refreshing Datasets
Since the data from the data source is aggregated and stored in MapX, when the data
changes in the data source, MapX does not reflect the change. The Dataset.Refresh method
can be used to have MapX reread the source data and re-aggregate and store it. This,
however, can be time consuming. Dataset.Refresh does not work for Datasets that create
new point layers. A workaround is to simply remove the layer and re-add the Dataset, or to
perform the following steps:
1. Create a new point layer using Datasets.Add with a BindLayer of type
miBindLayerTypeX . Create the new layer with only the X and Y columns by
passing a Fields object, with only those two columns specified, in the Datasets.Add
method.
2. Bind the rest of the data to this newly created layer. Use Datasets.Add with normal
binding, using the X field for the Geofield parameter and the Y field as the
SecondaryGeofield parameter. This second Dataset can be refreshed.
Note: This method will not add new features to the layer when new rows are added to
the data source.

110 MapInfo MapX Developer Guide v4.5

 The Different Types of Data Sources

The Different Types of Data Sources

MapX lets you bind to several different types of DataSources. The first argument to the
Datasets.Add method lets you specify a DatasetTypeConstants value, which dictates the
type of data binding you wish to perform.

• miDatasetADO (ActiveX Data Objects)

• miDatasetDAO (Data Access Object Recordset)
• miDatasetDelphi4 & miDatasetDelphi5 (Delphi DataSource Objects)
• miDatasetGlobalHandle (tab-delimited data)
• miDatasetLayer (MapInfo table)
• miDatasetNotesView, miDatasetNotesQuery (Lotus Notes)
• miDatasetODBC (Open DataBase Connectivity data source)
• miDatasetOLEData (PowerBuilder)
• miDatasetRDO (Remote Data Objects)
• miDatasetSafeArray (SafeArray)

miDatasetUnbound (alternate method)miDatasetADO (ActiveX Data

Objects)
The SourceData parameter to Datasets.Add must be a ADO Recordset object. An ADO
Recordset object is creatable and the Source property of the Recordset object may be set to a
simple text command (such as a directory name for a file system provider or an SQL
statement for a DBMS-type provider). ADO is implemented with a small footprint, minimal
network traffic in key Internet scenarios, and a minimal number of layers between the front-
end and data source-all to provide a lightweight, high-performance interface.

miDatasetDAO (Data Access Object Recordset)

The SourceData parameter to Datasets.Add must be a DAO Recordset object.You can get
one from a Visual Basic data control, an Access form, or by creating one in Visual Basic,
Access, or C++.

Note: MapX supports DAO data up to v3.6.

MapInfo MapX Developer Guide v4.5 111

Chapter 6: Putting Your Data on the Map

miDatasetDelphi4 & miDatasetDelphi5 (Delphi DataSource

Object)

miDatasetGlobalHandle (tab-delimited data)

This type of data binding lets you pass in a block of tab-delimited data. The SourceData
parameter to Datasets.Add must be a variant with type of VT_I4 and the lVal equal to the
global memory handle. The format of each row of data in the block of global memory is:

Field TAB Field TAB Field CRLF

Field TAB Field TAB Field CRLF
. . .
where Field is a string value in quotes, or a numeric value without quotes; TAB is character
0x09; and CRLF is a carriage-return line-feed sequence: 0x0D 0x0A.

miDatasetLayer (MapInfo table)

This type of data binding lets you create a Dataset that uses fields from a MapInfo table.

miDatasetNotesView, miDatasetNotesQuery (Lotus Notes)

These types of data binding deal specifically with Lotus Notes. For details, see "Getting
Started With MapX".

miDatasetODBC (Open DataBase Connectivity data source)

MapX can use ODBC to retrieve data from any ODBC data source. You need to specify the
connection string, the data source name, and the SQL string to execute by using the
ODBCQueryInfo object.

The ODBCQueryInfo.ConnectString property sets the connect string to connect with an

ODBC data source. For example, specify “ODBC;”. You can also include “uid=” , “pwd=”,
or DLG=. If necessary information is missing, the ODBC driver for the DataSource will
prompt the user.
“DLG=” controls the display of the connection dialog box: DLG=0 means never put up a
dialog, DLG=1 means always put one up, DLG=2 displays the connection dialog, but only if
needed (i.e., if not all required information was provided).

112 MapInfo MapX Developer Guide v4.5

 The Different Types of Data Sources

miDatasetOLEData (PowerBuilder)
This is for containers such as PowerBuilder, that pass data to MapX in the format described
in miDataGlobalHandle when initializing the MapX control. Then a call to Datasets.Add
with miDatasetOLEData as the type tells MapX to build a Dataset using the previously
passed in data.

miDatasetRDO (Remote Data Objects)

The SourceData parameter to Datasets.Add must be a RDO. RDO offers a set of objects that
enable one to connect to a database, execute queries and stored procedures, manipulate
results, and commit changes to a server.

miDatasetSafeArray (SafeArray)
This type of data binding lets you create a Dataset that uses fields from an array of data.

miDatasetUnbound (alternate method)

If you cannot support one of the other formats, MapX provides a an alternative approach to
data binding that allows you to set up an event loop whereby MapX asks the container for
data values, one cell at a time. MapX will send the RequestData event, with the row and
column number of the data value wanted. You can then use any method of getting the data
and feeding it through this event back to MapX.

MapInfo MapX Developer Guide v4.5 113

Chapter 6: Putting Your Data on the Map

114 MapInfo MapX Developer Guide v4.5

Chapter 7: Features and Selections

Features and Selections

6
Chapter
The methods of the Selections and Features objects
➤ What Is a Map Feature?
allow you to “mark” or choose features that meet
certain criteria. A point on a map representing ➤ What Is a Features
Collection?
New York City is an example of a Feature object.
Say you need to find all of the potential clients ➤ What Is a Selection
within 5 miles of Sheep’s HeadBay, Brooklyn.
Collection?
Once you create this collection of data, you may ➤ Using the Features
cycle through the collected data, print it out, take Collection
averages, count how many met that criteria, save ➤ Understanding the
them to a file, or perform other tasks. In this Selection Collection
chapter we will take a detailed look at features and ➤ Feature Editing
selections.
Chapter 7: Features and Selections

What Is a Map Feature?

A map feature is a geographic object on a map such as a point, line or region. For example, a
map of the United States could contain regions as states, lines as highways, and points as
cities. In MapX, a map feature is represented as a Feature object. For example, New York
state could be a Feature object of type region, interstate 95 a Feature object of type line, and
New York City a Feature object of type point.

What Is a Features Collection?

In MapX, the different layers that make up your map usually have the same feature type
within each layer. For example, the “US States” layer has region features to represent each
state, the “US Highways” layer has line features to represent major U.S. highways, and the
“US Capitols” layer has point features to represent each state capitol city. In MapX, all the
features in a map layer or any subset of all the features in a map layer is represented as a
Features collection. Many Layer object methods return a Features collection from a layer.
The features in a Features collection are not highlighted on your map. For this, you use a
Selection collection.

What Is a Selection Collection?

Like the Features collection, the Selection collection is also a collection of Feature objects.
However, the Selection collection represents the Feature objects that are currently selected
(either selected when the user clicks on the map with a selection tool, or selected by means
of the various Select methods listed below). Each Layer object has its own Selection
collection (Layer.Selection). MapX automatically highlights all the features in a Selection
collection, considering them selected features.

116 MapInfo MapX Developer Guide v4.5

 Using the Features Collection

Using the Features Collection

The Features collection is similar to the Selection collection, in that both collections are
collections of Feature objects. However, the Features collection has a different set of methods
and properties than the Selection collection, and the two collection types behave differently.
Selected features are automatically highlighted and features in a Features collection are not.

Getting Features in a Layer

Before you can do anything to a Features collection, you must first create the collection. The
Layer object methods create a collection of Feature objects.

The Following methods of the Layers collection provide various ways to get a Features
collection.

Code Sample (Dim fs as Features

Method Description ‘this creates a collection of
Features)

AllFeatures Returns a Features collection Set fs = Map1.Layers(2) _

with all features from the .AllFeatures
layer.
NoFeatures Returns an empty Features Set fs = Map1.Layers(9).NoFeatures
collection for the layer.
SearchWithinDistance Returns a Features collection Set fs = Map1.Layers(3). _
made up of features within a SearchWithinDistance (objPoint, _
specified distance of a point 36.5, miUnitMile, _
object. miSearchTypeCentroidWithin)
SearchWithinFeature Returns features collection Set fs = Map1.Layers(3). _
made up of features within SearchWithinFeature _
another specified region (ftr, miUnitMile, _
feature. miSearchTypeCentroidWithin)
SearchWithinRectangle Returns features collection Set fs = Map1.Layers(3). _
within bounds of specified SearchWithinRectangle(miRect, _
rectangle. miUnitMile, _
miSearchTypePartiallyWithin)
SearchAtPoint Returns features collection Set fs = Map1.Layers(3)
made up of features at .SearchAtPoint(objPoint)
specified point.

MapInfo MapX Developer Guide v4.5 117

Chapter 7: Features and Selections

SearchTypeConstants
Search Constant Description

MiSearchTypeCentroidWithin Include in search if the feature’s centroid is within the

region.
MiSearchTypeEntirelyWithin Include in search if the feature is contained by the region.
MiSearchTypePartiallyWithin Include in search if any part of the feature is within the
region.

Manipulating a Features Collectio

The following methods allow you to manipulate the Features collection by adding,
removing, cloning, etc. a feature object to the collection:

Method Description

Add Add a Feature object or an entire Features collection into the

collection.
Clone Make a copy of the collection as another Features collection object.
Common Combine this collection and another Features collection so that
this collection contains only features that are in both (INTERSECT
set operation).
Remove Remove a Feature object or all features from a Features collection
from this collection (SUBTRACT set operation).
Replace Replace the contents of the collection with a Feature object or all
features from a Selection collection object.

Feature Object
A Features collection is made up of a collection of Feature objects. A Feature object
corresponds to a feature on a map like a symbol, line, or region.

A Feature object corresponds to features (actual entities) in a layer, such as New York,
Chicago, Louisiana, Cortland County, or Highway I-10.

118 MapInfo MapX Developer Guide v4.5

 Understanding the Selection Collection

Stand-Alone Features
The Feature object methods allow you to create and manipulate stand-alone feature objects.
When you create a stand-alone feature object, you must attach that feature object to the map
before you reference any of its methods or properties. Attaching a feature to the map associ-
ates the map's coordinate system with the feature.

Feature Object Properties

The following properties define a feature object:

Property Description Code Sample

CenterX Contains the X centroid of the feature. Print ftr.CenterX
CenterY Contains the Y centroid of the feature. MsgBox ftr.CenterY
FeatureID Contains the ID of the feature. Each IVar = ftr.FeatureID
feature in a layer contains a unique ID
within the layer. This is an Integer
value.
Length Contains the length of the feature. Print ftr.Length
Perimeter The length is the perimeter of the If ftr.Perimeter > 500 Then
feature. Print “Too Long”
End If
Name Contains the name of the feature. MsgBox ftr.name
Type Contains the type of the feature (point, ftr.Type = miFeatureTypeSymbol
line, etc.).

Understanding the Selection Collection

A fundamental function of MapX is selecting features on the map, so that you can perform
additional tasks on them. Users can click on the map to select one or more features (points,
lines, regions, etc.). MapX highlights all selected features.

To examine the list of selected features, use the Selection collection, which is a collection of
Feature objects. The Selection collection also provides various methods (such as
SelectByRadius) that allow you to perform various types of selection, for example, selecting
all of the features within a certain radius of a city. The selected features will show up

MapInfo MapX Developer Guide v4.5 119

Chapter 7: Features and Selections

highlighted on the map. Each layer has a collection of selected feature objects
(Layer.Selection).
The Selection collection has methods to add and remove features to and from the collection.
Also, if you have an existing Selection or Features collection, you may append, remove,
copy, or find the intersection of the two collections.

The following table lists some of the Selection collection methods. For a complete listing,
see the Object Model Diagram:

Method Description Code Sample

ClearSelection Unselects all features in this layer. Map1.Layers(“SalesReps1997”)
Use Layers.ClearSelection to clear .Selection.ClearSelection
the selection from all layers.
Clone Make a copy of the collection as Map1.Layers(2).Selection.Clone
another Selection collection ftrs
object.
Common Combine this collection and Map1.Layers(2).Selection.Common
another Selection object so that Map1.Layers(4).Selection
this collection contains only
features that are in both
(INTERSECT set operation).
Remove Remove a Feature object or all Map1.Layers(2).Selection.Remove fs
features from a Selection object
from this collection (SUBTRACT
set operation).
Replace Replace the contents of the Map1.Layers(“Boston”).Selection.Rep
collection with a Feature object or lace lyr.AllFeatures
all features from a Selection
collection object.
SelectAll Selects all features within a layer. Map1.Layers(“Cargo”).Selection.Sele
ctAll
SelectByPoint Selects the feature at a specified Map1.Layers(5).Selection.SelectByPoi
point within the layer. nt 75.14, 42.9, miSelectionAppend
SelectByRadius Selects features from the layer Map1.Layers(4).
within a specified radius around Selection.SelectByRadius X, Y,
a point. Radius, miSelectionnew
SelectByRectangle Selects features from the layer Map1.Layers(5).Selection.SelectByRec
within a rectangle. tangle –98.7, 31.56, -75.14, 42.9,
miSelectionRemove

120 MapInfo MapX Developer Guide v4.5

 Understanding the Selection Collection

Method Description Code Sample

SelectByRegion Selects features from the layer Selection.SelectByRegion Layer,

within a region. FeatureID, Flag

SelectionTypeConstants
The following constants determine what to do with the results of your selection.

Selection Constant Description

MiSelectionNew Creates a new selection.

MiSelectionAppend Adds to the current selection.
MiSelectionRemove Removes from the current selection.

The following code creates a new selection at a specific point:

Private Sub Command1_Click()

Map1.Layers(5).Selection.SelectByPoint -98, 31.56,
miSelectionNew
End Sub

SelectionChanged Event
This event is called whenever the selection changes. It enables the container to react to a
selection made on the map. The selection can change as a result of a user using a selection
tool, or by using one of the Selection methods from the Layer object.

MapInfo MapX Developer Guide v4.5 121

Chapter 7: Features and Selections

Feature Editing
MapX allows you to create, modify, or delete the features (points, lines, regions, etc.) that
make up a map layer. Any layer that is based on an ordinary MapInfo table (.tab) file can be
edited.

Note: MapX does not provide transaction support. In other words, when you update
the feature, after you add/delete/change a feature, it happens immediately. You
don't need to save any changes later, and you can't undo the operation.
• How to Create New Map Features
• Allocating a New Feature Object
• FeatureFactory Methods
• How to Modify Existing Features
• How to Delete Existing Features
• How to Obtain a Feature to Edit
• Examining the Parts of a Region or Line

Setting Font AttributesHow to Create New Map Features

There are two ways to create new map features. You can create a feature by allocating a new
Feature object, or create features by performing operations (such as buffering) on existing
features by using the methods of the FeatureFactory property of the Map object. These types
of features are called stand-alone features. Stand-alone features have some restrictions: they
can't be added to any collections, and only the methods and properties that are used to
define the feature are allowed. For example, you cannot use the Area property on a stand-
alone feature, and a stand-alone feature has no value for the Feature.Layer property

A feature that comes from a layer is not a stand-alone feature, and all properties and
methods work on it.

FeatureFactory Methods
The methods of the FeatureFactory object let you create new map features, or create features
by performing operations (such as buffering) on existing features.
These are the methods of the FeatureFactory object:

• BufferFeatures
• CombineFeatures
• CreateArc

122 MapInfo MapX Developer Guide v4.5

 Feature Editing

• CreateCircularRegion
• CreateEllipticalRegion
• CreateLine
• CreateRegion
• CreateSymbol
• CreateText
• EraseFeature
• IntersectFeatures
• IntersectionPoints
• IntersectionTest
Most of these methods return stand-alone feature objects. These feature objects are
automatically attached to the map (i.e., they already have an associated coordinate system).
In other words, you do not need to use the Attach method on the features returned by these
methods.

To obtain a FeatureFactory object, reference the Map.FeatureFactory property.

The Online Help and Reference Guide provide extensive instructions on how to use the
various FeatureFactory methods.

How to Modify Existing Features

When you have a pointer to a Feature object, it represents a real feature in a layer; a feature
that comes from a layer is not a stand-alone feature, and all properties and methods work on
it. Any properties and methods you read reflect the value of the feature in the layer.

Once you start modifying a feature by setting its style or points or location, your changes do
not take effect until you 'update' the feature. This arrangement allows you to make many
changes to a feature without waiting for the database to update and the screen to redraw
after each change. As a side effect, the MBR, area, length, etc. are not changed until you
update the feature.

To update a feature, do one of the following:

• If you have modified a feature and want to commit the changes, use the
Feature.Update method.
• If you want to replace a feature with another feature, use the Layer.UpdateFeature
method.
• When a feature is updated, both the old MBR and the new MBR are invalidated so
that the screen redraws correctly.

MapInfo MapX Developer Guide v4.5 123

Chapter 7: Features and Selections

How to Delete Existing Features

To delete a feature, use the Layer.DeleteFeature method. The feature and the row it
represents will be deleted from the MapInfo table immediately.

How to Obtain a Feature to Edit

You can allow the user to click on a feature to select it. Then, to access the selection, your
program can use the Layer's Selection collection. The Selection collection also provides
various methods, such as SelectByPoint, that allow you to add features to the collection.

The Layer object has various methods (described above), such as SearchAtPoint, that allow
you to obtain a Features collection.
You can use the Find.Search method to perform a query that returns a FindFeature object (a
super class of the Feature object).

Examining the Parts of a Region or Line

A line feature or region feature in MapX is made up of many collections of Point objects.
These collections of Points collections are accessed through the Feature.Parts collection of
the feature.

Setting Font Attributes

Properties of the Style object let you control the appearance of features on the map. For
example, you can change a symbol's color by setting the Style.SymbolFontColor property.

Note that the Style object does not provide a "Size" property, nor does it provide "Bold" or
"Italic" properties. If you need to set a symbol's font size, bold or italic settings, you must
obtain and modify a Font object, as follows:
1. Reference the Style.SymbolFont property to obtain a Font object.
2. Modify properties of the Font object to control the appearance of the symbol.
The Font object is not a part of the MapX object model; instead, it is a standard object
(OLE_FONT, IFontDispatch).

Setting a text feature's font properties is very similar, except that you reference
Style.TextFont instead of Style.SymbolFont.

Note: Make sure you spell the font's name correctly if you assign the Name property.
Any misspelling of a font name—even specifying a lowercase letter where an
uppercase letter is needed—can cause problems.

124 MapInfo MapX Developer Guide v4.5

 Feature Editing

MapInfo MapX Developer Guide v4.5 125

Chapter 7: Features and Selections

126 MapInfo MapX Developer Guide v4.5

Chapter 8: Thematic Mapping and Analysis
7
Chapter

➤ What Is Thematic
Thematic Mapping and Mapping?
➤ Planning Your Thematic
Analysis Map
➤ Types of Thematic
Thematic mapping is a powerful way to analyze
Mapping
and visualize your data. You give graphic form to
your data so that you can see it on a map. Patterns ➤ Manipulating a Theme
Map
and trends that are almost impossible to detect in
lists of data reveal themselves clearly when you use ➤ Customizing a Thematic
thematic shading to display data on a map.
Legend

With MapX, you can create applications with

thematic maps using the following thematic types:
ranges of values, graduated symbols, dot density,
individual values, and bar and pie charts.
Chapter 8: Thematic Mapping and Analysis

What Is Thematic Mapping?

Thematic mapping is the process of shading your map according to a particular theme. The
theme is usually some piece or pieces of your data, which is obtained from a dataset.
Themes present your data visually with shades of color, fill patterns, symbols, or bar and pie
charts. You create different thematic maps by assigning these colors, patterns, or symbols to
map objects according to specific values in your data. Bar and pie charts allow you to make
data comparisons for each record in your dataset.

There are many ways that thematic maps can illustrate your data. The most commonly
known example of a thematic map is a weather map. Where you see red, you know it is hot
(high number of degrees); where you see blue, it is cold (low number of degrees). Thematic
mapping also allows you to discover trends in data that would be difficult to see through
tabular data.

Using the properties and methods in the Themes collection, Theme object, and the Theme-
Properties object, you can create and define your own thematic shading. A Legend object
holds the theme’s key,describing what the theme’s colors, shapes, and sizes represent.

128 MapInfo MapX Developer Guide v4.5

 Planning Your Thematic Map

Planning Your Thematic Map

Before you create a thematic map, it is important know about the elements that make up a
thematic map and how they are put together. This section will discuss thematic variables,
where you can obtain your data, particularly using data from another table, and the
arrangement and display of thematic layers.

Thematic Variables
The data that you display on your thematic map is called the thematic variable. Depending
on the type of thematic analysis you are performing, your map can show one or more
thematic variables. Ranges of values, grid shading, graduated symbols, dot density, and
individual values maps all examine one variable. With bar or pie charts, you can display
more than one thematic variable at a time.

MapInfo MapX Developer Guide v4.5 129

Chapter 8: Thematic Mapping and Analysis

You can also create bivariate thematic maps, where one map object, such as a symbol,
represents two different pieces of data. The symbol color, for example, can represent one
thematic variable, and the symbol size can represent another.

Where to Obtain the Data

Before you begin your thematic map, you need to decide what information you want to
display and locate where that information resides. The data you use to create a theme comes
from a Field object or Field collection from your dataset. These field(s) are passed as the
Fields parameter of the Themes.Add method of the Themes collection.

Themes Collectio
Each dataset has a collection of themes. A Themes collection creates, counts, adds, or
removes a Theme object from a collection of themes.

Methods Description Code Sample

Add Creates a theme and adds it to the Map1.Datasets(1).Themes.Add _

Themes collection for a particular miThemeRanges “TotPop”, “My _
dataset Ranges Theme”
Remove Removes a specified theme from Map1.Datasets(1).Themes.Remove “My
the collection. _
Ranges Theme”
RemoveAll Removes all themes from the Map1.Datasets(1).Themes.RemoveAll
collection

Creating a Theme
If you want to thematically shade a map using data from a dataset, you create a Theme
object for the dataset with the Themes.Add method. Once a dataset is added to your map,
creating the theme can be done with one line of code:

Map1.Datasets(1).Themes.Add miThemeRanges “TotPop”, _

“My Ranges Theme”
This creates a ranged theme for the first dataset in the Datasets collection using the field
“TotPop” .

The Themes.Add method is described below. Optional parameters are in [brackets].

130 MapInfo MapX Developer Guide v4.5

 Planning Your Thematic Map

Syntax
Themes.Add [Type], [Field], [Name]

Part Description
Type Specifies the type of thematic map to create. This takes a
ThemeTypeConstants. This is an optional parameter, and if not
specified (or specified as miThemeAuto), MapX will attempt to
choose a good default based on the number of fields passed in as
well as what other theme types are already being displayed. If
MapX cannot choose a default theme type, an error is generated.
Field(s) Specifies the field or fields to use in the thematic map. A field
can be specified by name, index, or by a Field object. If you are
creating a theme using multiple variables, pass in an array of
field names, indexes or Field objects. This is an optional
parameter, and if not specified, MapX uses the first numeric
field of the DataSet.
Name Specifies the name of the thematic map. This is a String
parameter. This is an optional parameter, and if not specified,
MapX generates a name such as StatesBySales.

How MapX Selects a Default Theme

If the Type parameter of the Themes.Add method is not specified (or specified as
miThemeAuto), MapX will attempt to choose a good default theme based on the number of
fields passed in as well as what other theme types are already being displayed, as described
below.

No. Fields Layer Type Algorithm

greater than 1 Points, Lines, Regions Default theme type is pie charts. If a multi-
variable theme already exists, try to create a
single-variable theme using the first field in the
collection of fields provided (see algorithms
below).

MapInfo MapX Developer Guide v4.5 131

Chapter 8: Thematic Mapping and Analysis

No. Fields Layer Type Algorithm

1 Points If the bound field is aggregated by individual

value, try to create an individual value theme. If
a ranged or individual value theme already
exist, cannot create a default theme. If the
bound field is not aggregated by individual
value, try to create a graduated symbol theme.
If an object thematic already exists, try create a
ranged theme. If a ranged or individual value
theme already exist, cannot create a default
theme.
1 Lines If the bound field is aggregated by individual
value, try to create an individual value theme. If
a ranged or individual value theme already
exist, cannot create a default theme. If the
bound field is not aggregated by individual
value, try to create a ranged theme. If a ranged
or individual value theme already exist, try to
create a graduated symbol theme. If an object
thematic already exists, cannot create a default
theme.
1 Regions If the bound field is aggregated by individual
value, try to create an individual value theme. If
a ranged or individual value theme already
exist, cannot create a default theme. If the
bound field is not aggregated by individual
value, try to create a ranged theme. If a ranged
or individual value theme already exist, try to
create a dot density theme. If a dot density
theme already exists, try to create a graduated
symbol theme. If an object thematic already
exists, cannot create a default theme.
Note: Pies, Bars, and Graduated Symbols are all object thematics.
Determination of a default theme type is layer specific. In other words, themes on Layer A
are not considered when attempting to determine a default theme type for a new theme on
Layer B.

132 MapInfo MapX Developer Guide v4.5

 Planning Your Thematic Map

Theme Type Constants

These are the types of themes you can create:

Type Description
miThemeRanged Ranges Theme
miThemeBarChart Bar Chart Theme
miThemePieChart Pie Chart Theme
miThemeGradSymbol Graduated Symbol Theme
miThemeDotDensity Dot Density Theme
miThemeIndividualValue Individual Values Theme
miThemeAuto MapX “best guess” Theme

Each has its own purpose and unique attributes. For example, using miThemeRanged, you
could thematically shade a map of the world according to population density. You could
shade the countries with graduated shades of red, the darkest red representing the most
densely populated countries, and the palest red representing the least densely populated
countries. At a glance you can see the distribution of the world’s population.

You are not limited to representing numeric values with thematic mapping. Nominal values
also may be shaded thematically. For example, you have a dataset of underground cables.
Those cables that haven’t been serviced in the past six months are labeled priority status.
Using miThemeIndividualValue, you can shade the cables according to their repair status.
All records with the same value will be shaded the same color. See the individual sections
later in this chapter for more information on each type of thematic map.
Once the Theme is added to a specified collection, the Theme object is created and you may
manipulate the properties of the object.

Theme Object
The Theme object sets the properties of the theme within the Themes collection. Modifying
the Theme object methods and properties determines how a theme is viewed, the type of
theme, etc.

Properties Description
AutoRecompute Controls when theme ranges are recomputed when theme
properties are changed (i.e., number of ranges). Defaults to True.

MapInfo MapX Developer Guide v4.5 133

Chapter 8: Thematic Mapping and Analysis

ComputeTheme Controls whether themes are computed. Defaults to True.

A True value will calculate the theme from the raw data. If the
value is set to False, an invisible Theme object will be created
with 20 ranges for IndividualValue themes and 5 ranges for
Ranged themes. You can then set the minimum and maximum
values to define the theme.
DataMax Determines the maximum value to set the theme ranges or
calculates equal size ranges for ranged themes when
ComputeTheme is set to False.
DataMin Determines the minimum value to set the theme ranges or
calculates equal size ranges for ranged themes when
ComputeTheme is set to False.
Fields Returns a read-only Fields collection representing the set of
fields used by the dataset that this theme is based on.
Layers Read-only property that returns a Layer object, representing the
layer that the theme is based on.
Legend Each Theme object has a Legend object (Theme.Legend). The
legend object contains properties to control the display of a
theme’s legend. Each ThemeCategory object (RangeCategory,
IndividualCategory or MultiVarCategory) has an entry in the
legend contained in a LegendText object.
Name The name of a theme. Must be unique within a Themes
collection. This is a read/write property, and is either specified
as a parameter to the Themes.Add method or generated by
MapX when the theme is created. This is the default property for
the Theme object.
ThemeProperties The ThemeProperties object contains the information defining a
theme (range definitions, display style settings, etc.).
Type The type of theme for a Theme object. This is a

134 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

Types of Thematic Mapping

Individual Values Maps
Individual Value maps show points, lines, or boundaries that are shaded by individual
values contained in a particular field of a dataset. You can use both numerical and nominal
values in individual values maps. MapX gives each unique value its own color or symbol.
When an individual values map uses symbol types, the symbols are taken from the default
style of the map.

For example, a soft drink distributor maintains a table of the supermarkets that buy soft
drinks from him by Zip Code in Washington D.C. Each supermarket sells the distributor’s
brand of soft drink for a different price. If the distributor shades the Zip Code boundaries by
price, using individual values, all stores that sell the soft drink for 49 cents are shaded one
color, all stores that sell the soft drink for 51 cents are shaded another color, and so on. Each

MapInfo MapX Developer Guide v4.5 135

Chapter 8: Thematic Mapping and Analysis

unique value is assigned its own color. The distributor is able to see the price distribution
among the supermarkets and can determine where he should increase his sales volume,
based on the price.

If you are shading your points, lines, or boundaries using nominal data, you can shade only
by individual values. Nominal data is either non–numerical data (e.g., name, type of cuisine
served, or brand of automobile sold) or numeric data where the numbers represent non–
numeric data. Dates are considered numeric data and can be used in both ranged and
individual values maps.

For example, you have the results from a consumer survey. One question on the survey
reads “What is your favorite Sunday afternoon activity?” The possible responses are:
1. Sleeping
2. Watching TV
3. Taking a drive
4. Reading
5. Playing or watching sports
6. Visiting museums or art galleries
7. Going to the movies
You want to shade each consumer point with the response for the favorite Sunday activity.
The SUNDAY field of your dataset contains the number that corresponds to the consumer’s
favorite activity. However, the numbers in this column do not represent quantitative values.
Going to the movies is not greater than playing or watching sports even though 7 > 5. When
numbers are used as names instead of values, you must shade your objects by individual
values. The numbers are only used to reference the pastimes so a color can be assigned to it.

An individual values thematic map's settings are exposed through the

IndividualValueCategories collection, which is a collection of IndividualValueCategory
objects—one object for each unique value in the theme. To obtain an
IndividualValueCategories collection, reference the
ThemeProperties.IndividualValueCategories property.

136 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

Ranged Maps
When you create a ranged thematic map, MapX groups all dataset rows into ranges and
assigns each row’s object the color, symbol, or line for its corresponding range. For example,
you have a dataset of weather stations for your television viewing area, and you want to
shade the locations according to their reported snowfall amounts.

With the Ranged map feature, MapX groups the snowfall amounts into ranges. For instance
all weather stations that received between zero and five inches of snowfall in the past month
are grouped into one range. Stations receiving between five and 10 inches are in a separate
range. Sites that received between 10 and 15 inches are in a third range, while those stations
reporting greater than 15 inch snowfall amounts are in a fourth range.

All records in the dataset are assigned to a range and then assigned a color based on that
range. For instance the weather stations reporting the 15 plus inches of snow are shaded red.
The other ranges are shaded in lighter shades of red with the last range in gray (default
colors). When you display the map, the colors make it readily apparent which locations
received the most and least snow accumulation.

MapInfo MapX Developer Guide v4.5 137

Chapter 8: Thematic Mapping and Analysis

Ranges are also useful when the size of the region is not directly related to the magnitude of
the data values.

Types of Ranged Values

MapX can create ranges automatically using five distribution methods: Equal Count, Equal
Ranges, Natural Break, Standard Deviation, and Quantile. Ranges are set by the DistMeth
property of the ThemeProperties object. The DistMeth property can be set to any of the
following DistribMethodConstants.

DistribMethodConstants
Equal Count (miEqualCountPerRange) has the same number of records in each range. If
you want MapX to group 100 records into 4 ranges using Equal Count, MapX computes the
ranges so that approximately 25 records fall into each range, depending on the rounding
factor you set.

When using Equal Count (or any other range method), it’s important to watch out for any
extreme data values that might affect your thematic map (in statistics, these values are
referred to as outliers). For example, if you shade according to Equal Count with this
database:

John 5000 Andrea 7000

Penny 6000 Kyle 5500

Miguel 4500 Angela 7500

Linda 5000 Elroy 6000

Ben 100 Mark 7000

Ben and Miguel are grouped in the same range (since they have the two lowest values). This
may not produce the results you want since the value for Ben is so much lower than any of
the other values.

Equal Ranges (miEqualRangeSize) divides records across ranges of equal size. For example,
you have a field in your table with data values ranging from 1 to 100. You want to create a
thematic map with four equal size ranges. MapX produces ranges 1–25, 26–50, 51–75, and
76–100.

138 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

Keep in mind that MapX may create ranges with no data records, depending on the
distribution of your data. For example, if you shade the following database according to
Equal Ranges:

John 100 Andrea 90

Penny 6 Kyle 1

Miguel 4 Angela 92

Linda 95 Elroy 89

Ben 10 Mark 10

MapX creates four ranges (1–25, 26–50, 51–75, and 76–100). Notice, however, that only two
of those ranges (1–25 and 76–100) actually contain records.

Natural Break and Quantile are two ways to show data that is not evenly distributed.

Natural Break (miNaturalBreak) creates ranges according to an algorithm that uses the
average of each range to distribute the data more evenly across the ranges. It distributes the
values so that the average of each range is as close as possible to each of the range values in
that range. This ensures that the ranges are well–represented by their averages, and that
data values within each of the ranges are fairly close together.

When you create ranges using Standard Deviation (miStandardDeviation), the middle
range breaks at the mean of your values, and the ranges above and below the middle range
are one standard deviation above or below the mean.

You can also define your own ranges using Custom (miCustomRanges). You specify your
own ranges in the RangeCategories collection (and MapX won’t compute ranges).

MapInfo MapX Developer Guide v4.5 139

Chapter 8: Thematic Mapping and Analysis

Graduated Symbol Maps

Graduated symbol maps use symbols to represent different values. You can use graduated
symbols regardless of the type of data with which you are working. For instance, use
graduated symbols to show sales orders across states. With the graduated symbols theme,
MapX varies the size of each symbol according to the value in the sales order field.

Or you can represent how much interest each customer has expressed in a given product by
assigning a symbol whose size is proportional to the customer’s interest.

Graduated symbols maps work best when you use numeric data. If you are working with a
table of restaurants, it makes no sense to create graduated symbols based on the type of
cuisine each restaurant serves. However, graduated symbols is appropriate when you want
to show the number of hamburgers sold at 20 different fast food restaurants.

There are two theme properties you can customize on a graduated symbols map: the
DataValue and SymbolStyle. The SymbolStyle property controls the symbol that is used, as

140 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

well as the size of the symbol drawn at the value specified by the DataValue property. All
values between the high value and zero have interpolated point sizes. The SymbolStyle
property is a Style object which controls all the stylistic aspects of the symbol such as color,
font, rotation, etc. You can also supply your own bitmap to be used as the symbol.

The Style object has a symbol picker (Style.PickSymbol) which displays the Symbol Style
dialog. The dialog enables a user to choose symbol style properties. The Style object is
updated with the new properties when the user clicks OK in the dialog.

Dot Density Maps

Dot density maps use dots to represent the data value associated with a boundary or region.
The total number of dots in a region represents that region’s data value. If you have 10,000
senior citizens in a county, and each dot represents 100 senior citizens, there would be 100
dots in the county boundary.

MapInfo MapX Developer Guide v4.5 141

Chapter 8: Thematic Mapping and Analysis

Dot density is particularly useful for showing raw data where one dot represents a large
number of something: population, number of fast food restaurants, number of distributors
who carry a brand of soda, etc.

For example, if you have a table of population broken down into county boundaries, you
could use the dot density option to show the concentration of people in each county
boundary. There are two theme properties you control for dot density maps. You can specify
the value of one dot. For example, you have a table of population statistics, broken down by
county. There are 20,000 high school students in Rensselaer County, New York. If you shade
Rensselaer County according to the number of high school students using the dot density
method, each dot could represent 200 students. In that case, there would be 100 dots in
Rensselaer County.

When you increase the value each dot represents, you decrease the number of dots that
display on the map. You could modify your dot density map so that one dot represents 400
students. In that case, there would only be 50 dots in Rensselaer County.

Map1.Datasets(1).Themes(“My DotDensity _
Theme”).ThemeProperties.ValuePerDot = 400
A second option is to change the size of the dots according to your needs. If you are working
with large populations, or large counts of something, make the dot size smaller so that the
distribution of dots is easier to see. Conversely, if your working with a small data set,
making the dot size larger might illustrate your analysis more clearly

Map1.Datasets(1).Themes(“My DotDensity _
Theme”).ThemeProperties.DotSize = miDotSizeLarge
Note: Distribution of dots is random within the region. For example, if you shade states
according to population, the dots for NewYork are spread throughout the state;
they are not concentrated in New York City, where the majority of the state’s
population lives.

142 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

Bar Chart Maps

Unlike one variable thematic maps such as ranges of values or graduated symbols, a
thematic bar chart map allows you to examine more than one variable per row at a time. A
bar chart is built for every map object (feature) at the centroid of the object, enabling you to
analyze the thematic variables in a particular chart by comparing the height of the bars. You
can also examine the same variable across all the charts in your map.
For example, you have a table of U.S. state boundaries containing female and male
population. Using bar charts, you can create a thematic map that displays a two–bar chart
for each state: one bar representing female, and the other representing male population. You
can compare the population differences of each state, or you can examine several states and
compare one state’s population or population differences to another’s. For best results, use
no more than four to six bars per bar chart in your analysis.

There are five theme properties you control for bar charts: DataValue, Size, Independent,
MultiVarCategories, and Width.

MapInfo MapX Developer Guide v4.5 143

Chapter 8: Thematic Mapping and Analysis

The DataValue property works in conjunction with the Size property to control how big the
thematic graphics are at particular values. The default value for this property is set to the
largest data value of the mapped features.

The Size property works in conjunction with the DataValue property to control how big the
thematic graphics are at particular values. It specifies the height of the thematic graphic in
Paper units (PaperUnit). This is a Double value, and defaults to .25 inches.

The Width property specifies the width of each bar of a Bar theme in Paper units
(Map.PaperUnit). This is a Double value, and defaults to .25 inches.

The Independent property controls whether the data values for the bars should be treated
independently (not comparable values such as Population and Avg Income). This is a
Boolean value, and the default is False. The developer should set this to True for multi-
value Bar themes where the data for each bar of a single feature is unrelated to a bar for a
different field of the theme, or the maximum values for a field of data differ greatly. An
example of this would be a population bar theme where one bar may represent the
population of a state and another may be a ranking in exports. The population data would
be in the millions and the ranking would only be between 1 and 50. If the Independent
property is set to True, then the highest populated state’s population bar would be equal in
height to the highest ranking state in exports export bar. Were the Independent property left
False, it would be difficult to obtain any meaning from the export ranking bar because the
state ranked first would have an export bar the size of a state’s population bar if that state
had 1 person in it.

A bar chart thematic map is exposed to OLE through the MultivarCategories collection,
which is a collection of MultivarCategory objects. The collection contains one object for each
bar in the bar chart.

144 MapInfo MapX Developer Guide v4.5

 Types of Thematic Mapping

Pie Chart Maps

Thematic mapping using pie charts also enables you to examine more than one variable per
row at a time. Like comparing the height of the bars in bar charts, in pie charts you compare
the wedges in a single pie, or examine a particular pie wedge across all of the pies. Pie charts
also enable you to compare parts of a whole.

Both pie and bar charts are particularly useful for analyzing demographic data. For
example, you have a dataset of demographic information for the United States. Your dataset
shows the populations of several major demographic groups. Using pie charts, you can
show the population of each demographic group, and see what fraction of the pie it makes
up in each pie. This enables you to see the distribution of demographic groups on a per state
basis, or across the entire United States.You can also look at one demographic group and see
how the population of the group varies in different states. For best results, use no more than
four to six pie wedges per pie chart in your analysis.

There are four theme properties you control for bar charts: DataValue, Size, Graduated and
MultiVarCategories.

MapInfo MapX Developer Guide v4.5 145

Chapter 8: Thematic Mapping and Analysis

The DataValue property works in conjunction with the Size property to control how big the
thematic graphics are at particular values. The default value for this property is set to the
largest data value of the mapped features.

The Size property works in conjunction with the DataValue property to control how big the
thematic graphics are at particular values. It specifies the height of the thematic graphic in
Paper units (PaperUnit).This is a Double value, and defaults to .25 inches.

The Graduated property controls whether the size of the Pie charts are graduated based on
the total value of the Pie. This is a Boolean value, and defaults to True.

A pie chart map is exposed to OLE through the MultivarCategories collection, which is a
collection of MultivarCategory objects. The collection contains one object for each wedge in
the pie chart.

Bivariate Thematic Mapping

Bivariate thematic mapping uses point or line objects to represent two thematic variables.
For example, a star can represent one variable, such as the number of teenagers, while a blue
fill for the star represents their annual purchase amounts.

To create a bivariate map in MapX, you create two thematic maps, and layer one over the
other so that the objects display two variables.

Types of Maps and Variables

The only types of thematic maps suitable for bivariate mapping are ranged and individual
values maps. You can choose between two combinations for a bivariate map, depending on
your data:

• two ranged maps

• one ranged map and one individual values map
If you have a non-numeric variable, one of your maps must be an individual values map.
You cannot create a bivariate map with two non-numeric variables.

146 MapInfo MapX Developer Guide v4.5

 Manipulating a Theme Map

Displaying Attributes
To display two variables within one symbol, it is important to choose a different symbol
attribute for each variable. For example, you cannot choose color for both variables because
one color will overwrite the other. Choose from the following combinations:

• color and symbol type

• color and size
• size and symbol type
Symbol type should only be used for nominal or non-numeric data, as there is no inherent
association between a symbol type and a quantity.

Manipulating a Theme Map

All of the theme’s properties can be adjusted at run-time. There are two ways to do this:

• Theme.ThemeDlg method.
• ThemeProperties object of a theme.

ThemeDlg Method
The theme object has a method, ThemeDlg, which displays a dialog allowing a user to
modify the theme. The following line of code shows how simple it is.

Map1.Datasets(1).Themes(1).ThemeDlg
You will get a dialog box with the ability to change parameters appropriate for the type of
theme from which it was called.

There are two possible drawbacks to using this method. First, you’re stuck with the design.
If these dialogs don’t fit in with your color schemes, or you don’t like how they are laid out,
you can’t change them. Another problem to using these methods is that sometimes they ar
too powerful. Perhaps you only want the user to change the color of the top range of a
ranges theme or you want to keep the colors, but not let the user choose the number of
ranges. Using the ThemeDlg method, the user can change any (and all) parts of the theme.

MapInfo MapX Developer Guide v4.5 147

Chapter 8: Thematic Mapping and Analysis

ThemeProperties Object
You also have the ability to change just the property of the theme by manipulating the
ThemeProperties object. This is easy to implement and gives you more control of what the
user can and cannot change.

The ThemeProperties object is stored in the Themes collection. The ThemeProperties object
properties are used to define the thematic map’s appearance (colors, symbols, etc).

The ThemeProperties object actually contains the information about how the theme should
look. Some of the ThemeProperties object’s properties are represented by other objects.

Property Description
AllowEmptyRanges Controls whether empty ranges are allowed in a ranged
theme.
DataValue Applies to graduated symbol, pie, and bar themes. This
is the value at which the thematic graphic is drawn at
the size specified by the Size property.
DistMethod Controls how ranges are created when a Theme object is
recomputed. This is a DistribMethodConstants value
and defaults to MiEqualCountPerRange. Other method
constants are miEqualRangeSize, MiCustomRanges,
miNaturalBreakRange, miStandardDeviation.
DotSize Controls the dot size used by dot density thematic
maps.
Graduated Controls whether the size of the pie charts is graduated
based on the total value of the pie.
IndividualValueCategory IndividualValueCategory collection.
Independent Controls whether the data values for the bars charts
should be treated independently.
MultivarCategories There is one MultiVarcategory object per variable or
field mapped in a pie or bar theme.
NumRanges Controls the number of ranges for a ranged thematic
map.
RangeCategories A ranged thematic map has a collection of
RangeCategory objects.
Size Works in conjunction with the DataValue property to
control how big the thematic graphics are at particular
values in pie and bar themes.

148 MapInfo MapX Developer Guide v4.5

 Manipulating a Theme Map

Property Description

SpreadBy Controls how autospreading is done for ranged

thematic maps.
SymbolStyle Style object controlling the symbol used for graduated
symbol themes.
ValuePerDot This property applies to dot density themes. This
specifies that value a dot represents.
Width Specifies the width of all the bars in a bar themes.
Several of the properties above are actually other objects. Those objects include the
RangeCategory object, IndividualValue object, MultiVar object and the Style object. Look at
the next chart to see the properties of the RangeCategory object. The other theme-related
objects behave similarly.

Property Description Code Sample

Max Sets the maximum value for a Map1.Datasets(1).Themes(1).
range in a ranged theme. Properties.RangeCategories(3).Max = 625
Min Sets the minimum value for a Map1.DataSets(1).Themes(1).
range in a ranged theme. Properties.RangeCategories(3).Min = 595
NumItems Shows the number of items in Print Map1.DataSets(1).Themes(1).
a range. Properties.RangeCategories(1).NumItems
Style A style object representing Map1.Datasets(1).Themes.Item(1).Propertie
the style of that range. s.RangeCategories.Item(1).Style.PickRegion

A ranged thematic map has a collection of RangeCategory objects, one for each range sorted
in ascending order. The ThemeProperties.RangeCategories property stores the collection.
If ThemeProperties.DistMethod is MiCustomRanges, MapX will assume that you have set
this value yourself, and will use the ranges that you have defined when grouping data
values. An error is generated if there are ranges that overlap when the theme is
recomputed.

MapInfo MapX Developer Guide v4.5 149

Chapter 8: Thematic Mapping and Analysis

Customizing a Thematic Legend

When you create a thematic map, MapX automatically creates a legend that explains what
the colors, symbols, or sizes represent.

Legend Object
Each theme has a Legend object (Theme.Legend). The Legend object contains properties to
control the display of the legend.

It is easily modified using the LegendDlg method from the Legend object. See the following
sample and the dialog that it will bring up.

Map1.Datasets(1).Themes(1).Legend.LegendDlg

150 MapInfo MapX Developer Guide v4.5

Chapter 9: Finding Features on a Map

Finding Features on a Map

8
Chapter

➤ Find Object
The Find method of the Layer object allows you to
➤ FindFeature Object
search a layer in a map object and locate a specific
feature within the layer.
Chapter 9: Finding Features on a Map

Using the Find Object

A Find Object allows you to locate features on a map. You may find a line, symbol or region
feature. The layer you are searching must have an indexed field in order to utilize the Find
method. See, Using the Geodictionary Manager for information about indexing fields in
your table.

For instance, if you wish to locate the city of Albany within NY state, you can use the Find
Object Search method to search a city layer and a state layer for the specified feature.

The Find Object properties allow you to specify the parameters of your find. For a complete
listing of all methods and properties associated with the Find object, please see the Find
Object topic in the MapX Objects section.

Refining Boundary
A refining boundary in your Find.Search is used to distinguish between mulitple features
with the same name. For example, if you travel to Albany, you might end up in New York,
California, or Georgia. The State would be the refining boundary when you say “Albany,
New York”

Using theFindFeature Object

The Find.Search method returns the feature it finds in the form of a FindFeature object. A
FindFeature object stores the properties of the Feature object found as its own properties. In
addition, the FindFeature has a FindRC property which stores the result code of the Find
operation. The FindFeature object is a super class of the Feature with the addition of a
closest match string to be returned. The FindRC property is a numeric value that indicates
why the feature was or was not found.

152 MapInfo MapX Developer Guide v4.5

 Using theFindFeature Object

Result Codes
Returns information on the Find Object such as why it was or was not found. This is a
numeric result code. The chart below describes the numeric result codes.

Digit Values Meaning

**Ones Place**
xx1 Exact match.
xx2 A substitution from the abbreviations file used.
xx3 ( - ) Exact match not found.
xx4 ( - ) No object name specified; match not found.
**Tens Place**
x1x Side of street undetermined.
x2x ( + / - ) Address number was within min/max range.
x3x ( + / - ) Address number was not within min/max range.
x4x ( + / - ) Address number was not specified.
x5x ( - ) Streets do not intersect.
x6x ( - ) The row matched does not have a map object.
** Hundreds Place **
1xx ( + / - ) Name found in only one region other than specified region.
2xx ( - ) Name found in more than one region other than the specified
region.
3xx ( + / - ) No refining region was specified, and one match was found.
4xx ( - ) No region was specified, and multiple matches were found.
5xx ( + ) Name found more than once in the specified region.

Once the result code is determined, you can use the results for selected cases as shown in the
example below. The user input from a text box indicates a city and state to locate. The input
is brought into the Find.Search method. Once the city is located from the major or minor
city table, an annotation is added to the map and the map is re-centered at the location in
which the feature was found.

MapInfo MapX Developer Guide v4.5 153

Chapter 9: Finding Features on a Map

154 MapInfo MapX Developer Guide v4.5

Chapter 10: Using Drilldown Layers
9
Chapter

➤ What Is a Drilldown
Using Drilldown Layers Layer?
➤ Terms and Concepts You
In this chapter, you'll learn about a special type of Should Know
map layer, known as a Drilldown layer, that lets the ➤ How To Develop a
user perform "drill-down" analysis and exploration. Drilldown Application
If your map includes a Drilldown layer, your user
➤ Preparing a Drilldown
can point and click on part of the map to see more Layer
detail about that region. Drilldown layers provide
➤ Creating a Drilldown Tool
an intuitive, easy to use interface that allows users
to explore data by pointing and clicking. ➤ Resetting the Drilldown
Layer
➤ Drilldown Layer
Limitations and
Requirements
➤ For More Information...
Chapter 10: Using Drilldown Layers

What Is a Drilldown Layer?

A Drilldown layer is a map layer with

special behavior built-in. Drilldown
layers allow the user to explore the
map in a hierarchical manner, by
pointing and clicking on the part of the
map where more detail is needed.

When a map first appears on the

screen, the Drilldown layer looks like
an ordinary map layer. For example,
this Drilldown layer shows sales
territories.

If theuser selects a Drilldown tool and

clicks on a feature in the map, that
feature is replaced by numerous
smaller regions. For example, if you
click on a sales territory, the territory
feature is replaced by the state
boundaries that make up the territory. Clicking is basically a way of requesting, "Show me
more detail about this part of the map."

156 MapInfo MapX Developer Guide v4.5

 What Is a Drilldown Layer?

Depending on how the application

and the Drilldown layer were set up,
the user might be able to drill down
repeatedly. With each successive click,
the map can display more detail about
the area where the user clicked.
Clicking on a state boundary might
reveal the county boundaries that make
up the state.

To reduce the amount of detail

displayed, the user can select a
different tool (a "roll up" tool), and click on the detailed area. The smaller, detailed regions
are replaced with a larger region—essentially, undoing the drill-down action.

A Drilldown layer is built from a set of tables. You need to provide one table for each "level"
in the drill-down hierarchy, plus one special table that defines how the various levels are
related hierarchically. However, the complexity of a Drilldown layer is hidden from the user.
The Drilldown layer appears in a MapX map as a single layer. If the user displays the Layer
Control dialog box, a Drilldown Layer appears as a single item in the list of layers.

MapInfo MapX Developer Guide v4.5 157

Chapter 10: Using Drilldown Layers

Terms and Concepts You Should Know

To understand the rest of this chapter, you'll need to understand some of the terminology
and basic concepts of Drilldown mapping.
• To support drill-down mapping, the map must include a Drilldown layer. This is a
special layer, composed of two or more separate tables. A Drilldown layer displays
objects from different tables as one layer in the map.
• For a Drilldown layer to be useful, it must contain at least two levels, which form a
hierarchy. For example, suppose a Drilldown layer presents state boundaries, and
the user can click on a state to show all the county boundaries for that state. In the
preceding example, the state boundaries represent one level, and the county
boundaries represent another level. The levels form a hierarchy. Each state contains
a number of counties. In this example, we say that the state boundary is a parent
feature, and each county boundary is a child feature.
• Typically, the user drills down on a part of the map by selecting a Drilldown tool,
then clicking on a part of the map where more detail is needed. To implement a
drilldown tool, use the CreateCustomTool method to create a custom tool.
• Using the Drilldown tool triggers the ToolUsed event. Within this event, you handle
the user's drill-down action by expanding the feature that the user clicked on.
Expanding a feature is a two-step process: First, you obtain a list of child features
that will replace the feature the user clicked on, and add the child features to the
layer (by calling the Layer.DrilldownAddFeatures method). Then, you remove the
original feature that the user clicked on. In other words, a feature is replaced by its
child features.
• Any Drilldown application requires a hierarchy manager, which is a software
component that understands the hierarchical relationship between the various
levels in the Drilldown layer. When the user clicks a feature to expand that feature,
the hierarchy manager is the part of the program that decides which child features
need to be added.
• The ToolUsed event procedure is a simple example of a hierarchy manager. When
the user uses your custom Drilldown tool to click on the map, the click event is
handled by the ToolUsed event procedure; the code executed within this procedure
determines which features are added to expand the map feature.
• You can set up the Drilldown layer so that there are two or more alternate tables that
can be used at a given level in the hierarchy. For example, suppose that for each
state boundary, you have two alternate sets of child features: A state can be
expanded to show a set of county boundaries, or the state can be expanded to show
a set of telephone exchange numbers. Such a Drilldown layer would still be
considered to have two levels—one parent level, and one child level. However, at
the child level, there is a choice between two alternate sets of features (counties vs.
telephone exchanges). With this arrangement, your application must determine
which child level to display, perhaps by prompting the user.

158 MapInfo MapX Developer Guide v4.5

 How to Develop a Drilldown Application

How to Develop a Drilldown Application

Drill-down applications require a considerable amount of setup and preparation. The major
steps can be summarized as follows (with more detail on each step provided later in this
chapter).
1. Obtain the various tables that you will use to build your multi-level Drilldown
layer. Tables can be created using MapInfo Professional, or purchased from MapInfo
Corporation or from third-party vendors.
2. Create a new, empty drilldown table (a .tab file) with special columns and special
metadata. The metadata assigns a level name to each component table, and also
identifies important columns in the component tables — the ID column and the
caption column.
3. Include your Drilldown table in your map (e.g., include the Drilldown table in the
Geoset(s) you are using, or add the Drilldown table to your map through a method
such as Layers.Add).
4. Add a user interface element (such as a toolbar button) to your application, so that
the user can select a Drilldown tool and click on the map to drill down.
5. Add code to your application that responds to the user's use of the drill-down tool
(in other words, write a hierarchy manager). This code needs to detect which
feature the user selected; determine which child features should replace the feature;
and invoke various methods (DrilldownRemoveFeatures, DrilldownAddFeatures)
to expand or contract the map features.

MapInfo MapX Developer Guide v4.5 159

Chapter 10: Using Drilldown Layers

Preparing a Drilldown Layer

To build a Drilldown layer, you need to provide a set of two or more MapInfo tables.
Specifically, you need:
• One MapInfo table for each level of detail in your Drilldown layer. These are known
as component tables.
• An additional, empty table which contains special metadata that describes the
component tables. This is known as the Drilldown table.
For example, suppose you want to display state boundaries, but allow the user to click a
state to display that state's county boundaries—a two-level Drilldown layer. You would
need three tables: A (component) table of state boundaries, a (component) table of county
boundaries, and a Drilldown table.

Note: The Drilldown table is "empty" in that it contains no permanent data of its own
(except for metadata). When you display a Drilldown layer in a map, MapX
creates a temporary table, and then copies features from the component table(s)
into the temporary table. The features that appear in a Drilldown layer are
actually copies of features in the component table(s). When the MapX application
terminates, the temporary table is discarded, and all that remains of the
Drilldown table is the .tab file.
• Requirements for the Component Tables
• Requirements for the Drilldown Table
• Component Table Metadata Keys
• Sample Drilldown Table

Creating a RollUp Tool Requirements for the Component Tables

Each feature in a Drilldown layer must have an identifying key (possibly a string such as
"New York"). All keys within a single level must be unique; for example, a state boundaries
level can only contain one state known as "Washington". However, a feature's identifying
key does not need to be unique across all other levels in the Drilldown layer. For example, if
you Drilldown layer includes state boundaries and county boundaries, you could have a
"Washington" state and a "Washington" county.

Requirements for the Drilldown Table

A typical MapInfo table consists of a set of files; for example, the World table consists of the
files World.tab, World.map, World.id, World.ind, and World.dat. The Drilldown table is
different from other tables, in that it consists of a single file: filename.tab.

160 MapInfo MapX Developer Guide v4.5

 Preparing a Drilldown Layer

The .tab file is a text file, which you can view or edit in any text editor.

The Drilldown table's .tab file must define specific columns and metadata keys, as described
below. As you read the following requirements, please refer to the “Sample Drilldown
Table” for an example.
The Drilldown table must define three standard columns: Key, Level, and Label. All three
columns are character (string) columns, 32 characters wide.

The Drilldown table must contain a set of metadata keys. Metadata key syntax is as follows:

• The keyword begin_metadata marks the beginning of the metadata portion of the
.tab file.
• Each line of metadata has two elements: a key, and a value. For example, the key
"\IsDrilldown" has the value "True". All keys and values are enclosed within double
quotation marks.
• The Drilldown table must include the \IsDrilldown key, and this key's value must
be True.
• Every key begins with the character "\" (backslash).
• Metadata keys can be nested hierarchically. Each level in the hierarchy is marked by
a backslash (\) character. Key values are limited to 239 characters.
• The Drilldown table includes a \DDMap\ComponentMaps\ key hierarchy. Within
this hierarchy, you specify four metadata keys for each component table:

MapInfo MapX Developer Guide v4.5 161

Chapter 10: Using Drilldown Layers

Component Table Metadata Keys

Key Description

File A required key that identifies the path and filename of a

component table.
LevelID A required key that defines an identifier for this component
table.
Example: You might use "States" as the key value if this table
contains state boundaries. When calling a method such as
DrilldownReset, pass "States" as the level argument.
FeatureIDCol Identifies the number of the column in the component table that
contains unique drill-down keys. Optional key; if omitted,
column number 1 is used.
FeatureCaptionCol Identifies the number of the column in the component table
which should be used for labeling. Optional key; if omitted,
column number 1 is used.

For example, the “Sample Drilldown Table” includes key hierarchies such as
"\DDMap\ComponentMaps\One\LevelID" and
"\DDMap\ComponentMaps\Twox\LevelID". Note that DDMap, ComponentMaps, and
LevelID are standard, required portions of the key hierarchy, while One and Twox are
customizable. You can use any key names you like instead of One, Twox, Twoxx, etc.; those
key names serve no purpose other than to differentiate each component table's set of keys.
Within the \DDMap\HierarchyManager\ key hierarchy, there are three additional keys:

Key Description
IsDLL Not used in version 4; reserved for future use. Boolean indicator;
"TRUE" means that this Drilldown layer uses a DLL as the
hierarchy manager.
ID Not used in version 4; reserved for future use. The name of the
DLL, or the GUID to CoCreate.
InitialLevel The initial component table to display when first loading/
displaying the Drilldown layer. Optional key; it is acceptable to
have an empty Drilldown layer.

162 MapInfo MapX Developer Guide v4.5

 Creating a Drilldown Tool

Creating a Drilldown Tool

Your application's user interface should give the user a way to drill down on part of the
map. Typically, the user drills down by selecting a Drilldown tool (e.g., a toolbar button),
then clicking on the map.

You can implement a Drilldown tool by using the CreateCustomTool method. The set of
CursorConstants includes two cursors provided specifically for Drilldown applications:
miDrilldownExpandCursor and miDrilldownContractCursor. For example:

' Drilldown Expand Tool

Map1.CreateCustomTool 1, miToolTypePoint,
miDrilldownExpandCursor, miDrilldownContractCursor,
miDrilldownContractCursor
This example creates a single tool that can be used for both Drilldown and RollUp actions.
By default, the tool acts as a Drilldown tool, which displays an "expand" cursor (a cursor
with a + sign). If the user holds down the SHIFT or CTRL key while clicking, the cursor
changes to a "contract" cursor (a cursor with a - sign). This arrangement lets the user switch
tools without having to move the cursor all the way to the toolbar; the built-in ZoomIn and
ZoomOut tools have the same behavior.

Once you have created the custom tool, you can make the tool active by setting the
CurrentTool property.

Map1.CurrentTool = 1
Each use of the custom Drilldown tool will trigger the ToolUsed event. Within the ToolUsed
event procedure, you will need to execute code that causes the drill-down behavior. This is
basically a four-step process:
1. Determine which map feature the user clicked on, using methods such as
SelectByPoint or SearchAtPoint.
2. Determine which set of child features should replace the feature the user clicked on.
For example, you might use one or more nested Case statements to determine
which child features replace the chosen parent feature.
3. Call the DrilldownAddFeatures method to add the child features to the map.
4. Call the DrilldownRemoveFeatures method to remove the parent feature (the
feature that the user clicked on) from the map.

Note: These add/remove actions do not modify the component tables in any way; you
are not "editing" the tables. When you use the DrilldownAddFeatures method to
add features, the only effect is that the features are copied into the set of features

MapInfo MapX Developer Guide v4.5 163

Chapter 10: Using Drilldown Layers

that are currently visible.

Creating a RollUp Tool

Once you have implemented a Drilldown tool, you will probably want to give the user a
Roll-up tool—a tool that has the opposite effect of the Drilldown tool.

You can create a Roll-Up tool in much the same way that you create a Drilldown tool. You
will need to use the same methods (DrilldownAddFeatures and
DrilldownRemoveFeatures). The difference is that instead of adding child features and
removing parent features, you'll do the opposite — you'll add parent features and remove
child features.

164 MapInfo MapX Developer Guide v4.5

 Resetting the Drilldown Layer

Resetting the Drilldown Layer

You can "reset" a Drilldown layer by calling the DrilldownReset method. Resetting the
Drilldown layer clears the entire layer, then re-initializes the layer using features from one of
the component tables.

For example, you might include a "Reset button" in your user interface. When the user clicks
the button, you could call the DrilldownReset method to restore the original state of the
Drilldown layer.

Including a reset button is a good idea, because it gives your users a quick, easy way of
restoring the drilldown layer to a homogeneous state.

Drilldown Layer Limitations and Requirements

Some restrictions apply to Drilldown layers, as summarized in the following list.

• Each feature in a Drilldown layer must contain an ID that is unique within that
component table (although the ID does not need to be unique among all of the
component tables that make up the Drilldown layer).
• You cannot use a raster image underlay table in a Drilldown layer.
• When creating a theme with Themes.Add, computing ranges for layers with large
numbers of rows, such as drilldown or server layers, can take some time. The
ComputeTheme parameter of the Add method lets you create a non-compute
theme for any theme type. A non-compute theme gives you the ability to create a
theme without having the ranges automatically calculated for you. You can then
create the ranges yourself. This is a faster way for drilldown and server layers.
• A Drilldown layer does not "remember" the status of the various drill-down levels
(which features have been expanded, etc.). If you want your application to restore
the precise status of the map's last use, you will need to write code to store the
map's drill-down settings when exiting, and restore the drill-down settings when
starting.
• Although you can edit the features in a Drilldown layer, the edits are not saved, and
the component tables are not affected by your edits. When you edit a feature in a
Drilldown layer, you are not modifying the component table, you are modifying a
temporary copy of a feature from a component table.

MapInfo MapX Developer Guide v4.5 165

Chapter 10: Using Drilldown Layers

For More Information...

For more information about Drilldown layers, see the following.

Related Methods and Properties

The Layer.DrilldownAddFeatures method adds features to a Drilldown layer.

The Layer.DrilldownRemoveFeatures method removes features from a Drilldown layer.

The Layer.DrilldownReset method clears an entire Drilldown layer, then shows only one
level of detail from the layer.

The Layer.GetDrilldownFeaturesByID method retrieves Features given their IDs.

To determine whether a layer is a Drilldown layer, test whether the Layer.Type property
returns the value miLayerTypeDrilldown (value: 7).

Related Constants
The set of CursorConstants includes two constants (miDrilldownExpandCursor and
miDrilldownContractCursor) specifically designed for Drilldown/RollUp tools. Use these
constants with the Map.CreateCustomTool method.

166 MapInfo MapX Developer Guide v4.5

Chapter 11: Accessing Data from a DBMS
10 Chapter

➤ Accessing Remote Spatial

Accessing Data from a Data
DBMS ➤ Using the Layers.Add
Method with a LayerInfo
MapX provides Spatial Server Access. This is a
Object
powerful feature that allows developers to connect ➤ Accessing Remote Tables
to live data stored in spatial servers, such as through a .tab File
MapInfo's SpatialWare running on Oracle, ➤ Mapping DBMS Data with X/
Informix, DB2 databases, or the Oracle8i Spatial Y Columns
databases. Spatial servers allow companies to host ➤ Oracle Support
their map data in their enterprise database for
➤ DBMS LayerInfo
central management and security. Spatial servers
Parameters
like SpatialWare offer advanced query processing
and increased performance on the server for an
➤ DBMS Connection String
Format
organization's spatial data.
➤ A MapX DBMS Layer Query
➤ Accessing Attribute Data
➤ Performance Issues
➤ Caching
➤ The MapInfo Map Catalog
➤ Making a DBMS Table
Mappable
➤ Troubleshooting
Chapter 11: Accessing Data from a DBMS

Accessing Remote Spatial Data

You can access data as a map layer data using MapX with different DBMS servers. The
servers include:
• MS Access/SQL Server/other ODBC data sources .
• Spatial servers like SpatialWare for Oracle, SpatialWare Informix DataBlade, and
SpatialWare DB2 Extender.
• The MapInfo Geocoding DataBlades for Informix.
• Oracle8i Spatial.
You can add a layer from data in a DBMS using the Layers.Add method. There are two
techniques:

• Use the Layers.Add method with the LayerInfo object when the query needs to be
calculated dynamically at run time. This would be appropriate for a case with
newly entered data. For example, you have an application that determines locations
of stores that have generated a user-entered amount of revenue. The revenue value
entered via the application could not be known at design time and, therefore, can
only be added to the query at run time. This replaces the previous AddServerLayer
method.
• Use the Layers.Add with a .tab file when the query is known at design time. For
example, if an application requires a display of all of the fire hydrants that are in
service, the query can be set to select all hydrants where the in-service condition is
true. This can be set at design time. A .tab file can be placed directly into a geoset,
ensuring that the file is loaded when any application using that geoset is initialized.
The details of each technique for adding spatial data are included in the following sections.
Once you have decided how to handle your data, follow the instructions in the appropriate
section.

Note: MapX 4.0 does not support opening SpatialWare 3.0 or lower tables.

168 MapInfo MapX Developer Guide v4.5

 Using the Layers.Add Method with a LayerInfo Object

Using the Layers.Add Method with a LayerInfo

Object
If your Layers.Add succeeds but your DBMS layer data does not display on the map, check
the layer order. The layer may have been drawn and hidden by another layer. You can
specify the layer order using the LayerInfo property. If the DBMS layer is the first or only
layer in the Map window, the default zoom level is set too far out to see the data. You can
adjust the server layers default zoom level in the MapInfo_MapCatalog by running a
MapBasic tool (misetmbr.mbx).

Dim lInfo As Object

Dim lStr As String
Set lInfo = CreateObject("mapx.layerinfo.4")
lInfo.Type = 4 ' layer type is RDB
lInfo.AddParameter "NAME", "city_125"' layer name
lInfo.AddParameter "TOOLKIT", "ODBC" ' use "ORAINET" for
oracle direct access
lInfo.AddParameter "CONNECTSTRING", "DRIVER={SpatialWare 32 Bit
Driver4.00};HOST=Champagne;UUID=oracle;UPWD=secret;UID=GEORGETOW
N;PWD=secret;OSID=DB1;DLG=0"
lInfo.AddParameter "QUERY", "SELECT * FROM CITY_125"
lInfo.AddParameter "CACHE", "ON"
lInfo.AddParameter "MBRSEARCH", "ON"
g_map.Layers.Add lInfo
Set lInfo = Nothing
Note: MapX does not do record locking on the feature when it is selected and updated.
The last update on the feature will be the one that is stored. In a multi-user
application, an application implemented long transaction method/locking or
business practices should be implemented to prevent undesireable update
collisions.

MapInfo MapX Developer Guide v4.5 169

Chapter 11: Accessing Data from a DBMS

Accessing Remote Tables through a .tab File

MapX can access DBMS data "live", or can open a MapInfo Professional linked table.
However, the linked table will be read only and cannot be refreshed by MapX. The data is
actually from the remote database and does not reflect the data in the local linked version.

You can create a .tab file to provide access to remote maps. To generate a .tab file using
MapInfo Professional, choose File -> Open a DBMS table.

The .tab file is a text file; you can create a .tab file using any text editor. Once you have
created the .tab file, you can access it the way you access any other MapInfo .tab file
programmatically through the Layers.Add method or through the Geoset Manager.

Mapping DBMS Data with X/Y Columns

You can add a layer from a DBMS table that has X/Y coordinates. You need to create a Map
Catalog and register the tables as SpatialType 4.0 and specify two column containers as the
coordinates. The columns should be indexed on the table. Connect to the DBMS via ODBC
and specify the new columns as "Object" in your query.

lInfo.AddParameter "toolkit", "ODBC"GetDYou may upload a MapInfo point

table like CITY_125 to MSAccess or SQL Server using MapInfo Professional in the MI
Upload MBX (located in the Tools directory of MapInfo Professional).

170 MapInfo MapX Developer Guide v4.5

 Oracle Support

Oracle Support
You can install Oracle8i Spatial in addition to the MapX ODBC Connectivity component.
Oracle8i Spatial is a relatively new implementation of a spatial database from Oracle
Corporation. Although it has some similarities to the previous Oracle SDO implementation,
it is significantly different. Oracle8i Spatial maintains the Oracle SDO implementation via a
relational schema. However, MapInfo does not support the Oracle SDO relational schema.
MapX does support simultaneous connections to Oracle8i via OCI and to other databases
through ODBC. MapX does not support Oracle8i spatial geometry tables via ODBC using
the current ODBC drivers from Merant.

Oracle v8.15 and v8.16 Support

To connect to Oracle8i within MapInfo, you must have the Oracle8i client installed. See your
Oracle documentation for detailed information.

Note: If Oracle 8.16 is Installed, all inserts/updates to any Oracle Spatial table will be in
Oracle 8.16 format. Therefore, all tables should be migrated to version 8.16 format
using the Oracle 8.16 Spatial data migration utility before any MapX 4.02 edits are
made.

Geometry Conversion
The table below describes the translation from MapInfo Spatial Objects to Oracle8i Spatial
(SDO_Geometry).

From MapInfo To Oracle 8i

NULL geometry NULL
Point 1 POIN
Line 2 LINESTRING Geometry contains one line string
Region 3 POLYGON Geometry contains one polygon.
Polyline 6 MULTILINESTRING Geometry has multiple line
strings.
Region with multiple polygons 7 MULTIPOLYGON Geometry has multiple
polygons.
Ellipse NULL
Arc NULL
Rectangle NULL

MapInfo MapX Developer Guide v4.5 171

Chapter 11: Accessing Data from a DBMS

From MapInfo To Oracle 8i

Text Object NULL

Rounded Rectangle NULL
PieChart, Barchart NULL
The table below describes the translation from Oracle8i (GTYPES) to MapInfo Spatial
objects.

From Oracle 8i GTYPES To MapInfo

0 UNKNOWN_GEOMETRY (Spatial ignores this geometry.) Point

1 POINT Geometry contains one point. Point
2 LINESTRING Geometry contains one line string. Line or Polyline
3 POLYGON Geometry contains one polygon. Region
4 Collection Geometry is a heterogeneous collection of elements. Point
5 MULTIPOINT Geometry has multiple points. Point
6 MULTILINESTRING Geometry has multiple line strings. Polyline
7 MULTIPOLYGON Geometry has multiple polygons (more than Region
one exterior boundary).

Multi Dimension Geometry Support (Greater than 2 Dimensions)

MapX can read these data and map them as layers for SDO_GEOMETRY columns
containing geometries defined in more then 2 dimensions. That is, only the first 2
dimensions are used as the x and y

SDO_GEOMETRY Arc and Circle Translation

Circles and circular arcs can be resolved to polylines with a resolution of 25 segments
per 360 degree circle.

172 MapInfo MapX Developer Guide v4.5

 Oracle Support

Visualization of Non-translatable Oracle Objects

Oracle Spatial Objects that MapX is unable to translate will produce a Point object with
a default style (a black star) at the location of the SDO_Spatial point, or the first
SDO_Spatial ordinate in the ordinate array. This is to enable a visual representation of
the non-translatable object in the proper geographic area it belongs. Examples of non-
translatable objects are User defined objects GTypes 0,4,5, or invalid sdo_geometries
containing unrecognized GTypes, ETypes, or interpretations. The second class should
also fail using sdo_validate_geometry().

Centroid Support
MapX will use the SDO_POINT as the centroid value for polygons. This centroid
feature is used to position labels, and also affects the tool selection of the object. The
Oracle SDO_GEOMETRY.SDO_POINT_TYPE field (if not NULL) will be interpreted as
the feature centroid if the point exists inside the region. If the point exists outside of the
region, its centroid will be calculated as always.
Note: There is currently no method or tool in MapX to set the centroid of a region
feature, but one may read and use a stored centroid.

Additional Information
The following sdo_geometry values are not translateable to/from MapInfo objects
format without data loss and therefore some geometry details can be lost if updated.
• GTYPE 0 - User defined/unknown geometry
• GTYPE4 - heterogenous collection of elements
• GTYPE 5 - Multi Point
These types are interpreted(when possible) as single point SDO_POINTTYPE values if
not already NULL. They "grab" the first point in the ordered array which would be
interpreted as a NULL geometry.
Note: Any other SDO_GEOMETRY values that contain circles or arc components are
translated into line strings contaning 25 lines per 360 degrees.

Oracle Sparial Reference Support (SRID)

An Oracle 8.16 SDO_GEOMETRY column may be defined with a Spatial referencing system.
This is done by providing the Oracle SR_ID in the USER_SDO_GEOM_METADATA and
also by assigning that SR_ID in the stored SDO_GEOMETRY values. If a table contains an
Oracle 8.16 Spatial column with as assigned SR_ID, MapX will be able to query and
properly interpret the data. The MapInfo_MapCatalog must contain the same MapInfo

MapInfo MapX Developer Guide v4.5 173

Chapter 11: Accessing Data from a DBMS

Professional Coordsys string as indicated in the SR_ID of the data, since it is the Coordsys
in the MapInfo_MapCatalog that is currently used to interpret and update the data.
If the Spatial column does NOT contyain an SR_ID value, (the value is NULL), MapX will
also be able to interpret the data via the MapInfo Professional Coordsys defined in the
MapCatalog.

Connection Dialog Workaround

For Oracle8i, there is no connection dialog that will display if you do not specify the
complete connection string. The DLG= option has no affect. If you do not provide the
userID and password, the connection will fail. Since DBMS table .tab files created by
MapInfo Professional do not contain passwords, (for security reasons), this causes the open
on the tab files to fail.

A way around this is to write a simple connect dialog that gets the password from the user
and does a Layers.Add for a DBMS layer using layerinfo with a connection string using the
userID/password for the database you wish to access. An Oracle connection string should
be specified as follows:

"SRVR=superior;UID=user1;PWD=secret;"
Add a temporary layer. This will also add the connection desired to the connection pool.
That connection will be used by all tab files opened on the same database with the same
userid since the password has already been authenticated. Thus the .tab files will be opened
successfully.

For these tab files to work in a geoset, you may have to put this login in the application
startup. You can connect to/login to multiple servers in this way and tables opened from
them will succeed.

174 MapInfo MapX Developer Guide v4.5

 DBMS LayerInfo Parameters

DBMS LayerInfo Parameters

Both the .tab file and the LayerInfo object accept the same parameters. However, the
naming conventions for the parameter names are slightly different.

Parameter Description

Name This is a required string to provide a name/alias for this layer.

ToolKit Values "ODBC"/" "ORAINET", Default is "ODBC"
This specifies the DBMS access components required to connect to
the server database. For Oracle direct, specify ORAINET and use
an ORAINET connection string. For others, specify ODBC.
ConnectionString This is the information that is necessary to connect to the DBMS.
For ODBC, the Connection clause specifies an ODBC connection
string. If you specify a complete connection string, the connection
is established without a dialog box. If no connection string is
provided, a default string of "DLG=0" is used, and an ODBC Data
Source dialog box appears.
For Oracle Spatial, you must specify a complete connection string
with userID and password. The DLG keyword does not apply and
a connect dialog will not appear. The Oracle direct connection
string looks like this:
"SRVR=superior;UID=mapx;PWD=secret"
Note: Full connection strings are recommended for actual
applications so that connections may be shared.
Query This is the backend DBMS query that determines the contents of
the table. For the table to be mappable, you must select the spatial
object column (or the pseudo column OBJECT).
SpatialWare users can specify a GISSQL/Server specific SQL
string/statement that will return a spatial object. Also,
SpatialWare users should include the SW_GEOMETRY and
SW_MEMBER columns, which are used by SpatialWare to store
geographic objects and IDs.
Note: If your table name is case sensitive and your database
requires you to quote it, and if the identifier quote character is a
double quotation mark ("), then you must repeat the double
quotation marks. For example:
"select * from ""tableowner"".""tablename"""
Cache Values "ON"/"OFF", Default is on. This controls whether the data
fetched when the layer is drawn is cached. Caching helps improve
the performance for subsequent redraws, pans/zoom (within the
cached region), labeling and thematics. Caching on too many large
layers can use all available memory and lose the value of the
cache.

MapInfo MapX Developer Guide v4.5 175

Chapter 11: Accessing Data from a DBMS

Parameter Description

MBRSearch Values "ON"/"OFF", default is ON

When MapX does a map draw, it fetches from the layer for the
dataInside the map boundaries. To do this for dbms layers, a
spatial predicate is appended to the table definition query. For
some types of queries, or on layers that have a problem with their
Spatial index, this predicate can slow down or cause the query to
fail. This option allows you to turn off that spatial predicate.

176 MapInfo MapX Developer Guide v4.5

 DBMS Connection String Format

DBMS Connection String Format

ODBC Connection String Format
The format of the ODBC connection string is the same as in MapInfo Professional ODBC/
Linked tables. The string is defined by several clauses separated by semicolons (;). Each
clause has the form Key=Value. Important keys are listed below

Keyword Description

DLG= A number that controls the display of the connection dialog box:
0 – Suppresses the connection dialog (required for MapX Theme).
1 – Displays the connection dialog.
2 – Displays the connection dialog, but only if needed (i.e., if not
all required information was provided) [default].
Note: Does not apply to Oracle Spatial
DSN= Specifies the ODBC data source name.
Caution: If you use the DSN= syntax key, the name that you
specify must match the data source name in use on the user’s
system. Note that different users might use different names to
refer to the same data source. If you cannot know in advance what
data source name to use, use the DRIVER= syntax key instead of
the DSN= syntax key.
Note: Does not apply to Oracle Spatial
DRIVER= Specifies the exact driver name of the installed SpatialWare or
IUS/UDO driver. Used instead of the DSN= syntax key. Examples:
DRIVER={SpatialWare 32 Bit Driver}
Note: Informix 2.80.0861 does NOT support DRIVER=.
Also, it does not apply to Oracle Spatial.
UID= Specifies the desired UserId for the data source, if required.
PWD= Specifies the user’s password for the data source, if required.

Passwords do not need to be in the connection string for the two strings to match. If two
tables are in the same database, the connection string will be the same.

Note: Connection attributes/parameters no longer have to be in order and one may use
a dialog to get a connection from an existing connection pool to avoid redundant
connections. That is, in previous versions of MapX, if you used a dialog each time
to connect to the same database, or if you did not order the connection keywords
in the connection string in the documented order, the connection would not be
shared and you would get multiple connections.

MapInfo MapX Developer Guide v4.5 177

Chapter 11: Accessing Data from a DBMS

Oracle Spatial Connection String Format

These are the Oracle Spatial keywords. The string is defined by several clauses separated by
semicolons (;). Each clause has the form Key=Value. Important keys are listed below

Keyword Description

SRVR= Reflects a value the service name for the server set in the Oracle8i
Net8 EasyConfig utility. This is required for Oracle8i connectivity,
but does not apply to ODBC connections.
UID= Specifies the desired UserId for the data source, if required.
PWD= Specifies the user’s password for the data source, if required.

Sample Connection Strings

Here are sample connection strings for the Oracle Spatial IUS/UDO, SpatialWare ODBC
drivers.

Oracle Spatial connection string:

UID=george;PWD=password;SRVR=ontario

IUS/UDO connection string:

DRIVER={INFORMIX 2.80 32
BIT};UID=informix;PWD=secret;DATABASE=sw;HOST=adak;SERVER=adak_t
li;SERVICE=sqlexec;PROTOCOL=onsoctcp;

SpatialWare connection string:

DRIVER={SpatialWare 32 Bit
Driver3.50};HOST=fire;UUID=oracle;UPWD=secret;UID=GEORGETOWN;PWD
=GEORGETOWN;OSID=QASW1

178 MapInfo MapX Developer Guide v4.5

 A MapX DBMS Layer Query

A MapX DBMS Layer Query

The query you specify for a DBMS layer defines the result set of data from your DBMS that
will represent the data in the layer being added. You can formulate a fairly complex query
to do powerful server size analysis that defines a mappable layer in mapx. MapX will use
this query internally to access the data.

MapX generates several internal queries based on your query to access the data in the
mapper as well as selection/key based queries. The table from which the object column is
selected from MUST be registered in the MapInfo Mapcatalog on the server. MapX requires
this to obtain certain metadata about the geometry column such as the coordinate system,
storage format, and default styles used to draw the layer.
In order for a query to succeed in adding a new layer, the query must contain both a
geometry column and a key column. Sometimes for more complex queries on small sets of
data (where the spatial indexing or spatial predicate cause the query to fail), you can turn
the predicate off specifying MBRSEARCH “OFF” to enable the results to be mapped.

The Geometry Column

If you do not specify a geometry column that MapX can recognize, the AddLayer will fail.
MapX will determine the geometry column of the table by looking it up in the Mapcatalog
and by examining the result set datatype of the column. You can reference the geometry
column generically via the pseudo column name “OBJECT”, or you may refer to the
geometry column using its specific column name. This form is requred to reference the
geometry column for an X/Y mappable layer. You can specify a geometry column via any
server supported geometry function/expression.

Example
Select OBJECT from rdbsdata
Select sw_geometry from rdbsdata
select sw_member, ST_Buffer(geometry, 66.0, 0.1) from rdbsdata ⇓
a geometry function
Select st_geometry(st_point(72.5, 42.5.)) from rdbsdata ⇓ a
geometry constructor

Spatialware function examples:

select sw_member, ST_Buffer(geometry, 66.0, 0.1) from rdbsdata

MapInfo MapX Developer Guide v4.5 179

Chapter 11: Accessing Data from a DBMS

select ST_Overlap(flood100.sw_geometry, lake.sw_geometry) from

flood100, lake where ST_Overlaps(flood100.sw_geometry,
lake.sw_geometry)

Spatialware constructor examples:

select 1 “prinx”, st_geometry(st_point(72, 42)) from dual

Oracle sdo_buffer example:

Select prinx, mdsys.sdo_geom.sdo_buffer(geoloc, (select diminfo
from sdo_geom_metadata where table_name = 'ALINE'), 20) from
aline where prinx = 1

Oracle constructor example:

Select 1 "prinx",
mdsys.sdo_geometry(3,null,null,mdsys.sdo_elem_info_array(1,3,3),
mdsys.sdo_ordinate_array(-79.919909,40.553465,-
71.060457,45.363657)) from dual

The Key Column(s)

A key column(s) must be returned in the query to enable it to be mapped as a layer. This is
what enables MapX to identify each row in the result set to perform shading, selection, and
label operations on the layer.

Note: The key column does not need to be specified in the query in most cases.
MapX will look up and determine the best key column(s) to use in order to uniquely
reference a row in the result set, and then add them to the query if they are not present. In
most cases. This will be the primary key/unique index.

Note: For Oracle spatial layers, the ROWID is used.

For some queries, it is not possible for MapX to identify the key. This is the case in a query
on a view or a synonym. The view or synonym must appear in the mapinfo mapcatalog.
They also must be registered as required with the underlying Spatial index system in most
cases. Since MapX can not determine the key on these, a mechanism is provided to allow the
application developer/query write to identify the key column in the result set. The key
must be a single column and must be a distinct value in the result set. To identify the column
that is to be used as the key column, you can specify column alias of prinx.

Example
Select customer_id prinx, object, from customer_view

180 MapInfo MapX Developer Guide v4.5

 Accessing Attribute Data

The column alias “prinx” is used to identify and use the customer_id column as the key
column for the layer. You can alternately alis the desired key column in the create view
statement to identify the key column automatically for any query on that view.

Example
Create view customer_view as select customer_id prinx, geloc from
customer
In general, if a column name or column alias of prinx, or mi_prinx is found in the result set,
that column is used as the key column for the layer. This enables the application/query
writer to specify the key column they desire.

Accessing Attribute Data

To use all available data columns, specify a query such as "Select * From tablename".You are
not required to specify * (asterisk); instead, you can designate specifically which columns
you want to use. For the best performance, limit your query so that it retrieves only the
needed columns.

To access the attribute data selected in the query with the spatial object in a DBMS layer, use
the datasets.add method with dataset type midatasetlayer (to get the attributes from the
existing layer).
When you add a DBMS layer, for performance sake, you should only specify the columns in
the query that you intend to use in your application. These are the spatial column, the key
column(s), which are added automatically if you do not specify them, and columns you
want to label with, or create a theme from. You may use the pseudo columns "OBJECT" for
any mappable table to refer to the column(s) containing the spatial data. This is required for
a table using the MapMarker MDIGEOADDRESS column on a table with an X/Y column.

Note: You can use any server side expression/function to specify a column. Also,
avoid select * from tab in a real application.
The following code example will open a MapInfo *.tab file, then access the remote data and
tie it to the layer.You now can label or place themes based on the columns.

Dim Lay As Layer

Dim dsname As String
Set Lay = Map1.Layers.Add(filename)
dsname = Lay.Name

MapInfo MapX Developer Guide v4.5 181

Chapter 11: Accessing Data from a DBMS

Map1.Datasets.Add miDataSetLayer, Lay, dsname

Performance Issues
Establishing a connection with the database server may take several seconds. This is a one-
time cost, incurred when the table is first opened.

An ’open’ operation may take several seconds as well. This one-time cost is incurred every
time a new table is opened.

The map-display speed depends on how much data is retrieved from the server. In some
cases, displaying a map from a server is noticeably slower than displaying a map from a
local file. Speed also depends on whether MapX has already cached the map features that
are being displayed.

Caching
A DBMS layer can be cached to improve performance if your application specifies redraws,
themes, and labeling (CACHE ON is the default). It requires significant amounts of
memory to cache all of the layer data in the map, so be selective about which layers you
create.

ODBC layer data is cached internally as it is read and drawn to the MapX Map window. All
subsequent redraws will read from this cache instead of going to the server database for the
same data. The cache is able to offer significant redraw performance improvement.

If you pan or zoom out of the region loaded in the cache as defined by the MBR of the Map
window, the cache will automatically be flushed and reloaded with the data from the server
database within the new MBR.

If you want to reload the cache from the database without panning or zooming out to obtain
a fresh view of potentially modified data within that geographic area, use the Layer.Refresh
method.

A good strategy for harnessing the full power of the cache is to try to load as much data as
possible in your initial view and have all subsequent options zoom in and pan around
within the cache.

182 MapInfo MapX Developer Guide v4.5

 The MapInfo Map Catalog

Note: If you try to cache too much data or too many layers, virtual memory usage may
be forced, and performance gain would in turn be lost.

The MapInfo Map Catalog

If a MapX application needs to access remote spatial data, a special table must exist in the
DBMS, known as the MapInfo Map Catalog. One catalog must be created per database
before any tables in that database can be viewed as a map layer in MapX. The Map Catalog
must contain information about the spatial columns in each of the mappable tables you
want to access from the database.

Note: RDB layers get their style from from the MapCatalog. There is no individual
feature style to set. That is, attempting to change a feature style with the
Feature.Update method will not change style properties for RDB Layers. The
entire RDB layer is represented by the style property which MUST be set in the
MapInfo catalog.
Your MapX application can use a Map Catalog that already exists on the server. (This same
catalog is shared by various MapInfo client applications, including MapInfo Professional.) If
there is no Map Catalog on the server, you will need to create it.

Using MapInfo Professional to Manage a Map Catalog

If you are a MapInfo Professional user, you can create and manage the Map Catalog using
MapInfo Professional. MapInfo Professional includes MapBasic utilities, such as
MIODBCAT.MBX, to assist you in creating and managing the Map Catalog.

A Map Catalog that was created by MapInfo Professional can be used by MapX
applications. For example, in a corporate setting, one user—a database administrator,
perhaps—can use MapInfo Professional to create the Map Catalog, and then numerous end
users can run MapX applications that read from that Map Catalog.

Loading Spatial Data to DBMS

If you have spatial data in the form of a MapInfo table, you can import that data into your
DBMS database.

• To load data into SpatialWare for Oracle, use the MISWUP32.MBX utility that is
provided with MapInfo Professional (located in the SpatialWare client install
directory).

MapInfo MapX Developer Guide v4.5 183

Chapter 11: Accessing Data from a DBMS

• To load data into DB2 SpatialWare, IUS/UDO SpatialWare, and Oracle Spatial, use
The MapInfo EasyLoader, that is distributed with MapInfo Professional and also
available for download from www.mapinfo.com.(For DB2 and IUS/UDO you must
have the SpatialWare extender/cartridge installed on the server)
• To load non-mappable tables, or Point-only tables, into any DBMS, use
MIUPLOAD.MBX utility provided with MapInfo professional in the tools directory.
This will store the Point object coordinates in separate x/y numeric columns.You
may map these tables by registering them in the MapCatalog as "X/Y Schema"
tables.

Manually Creating a MapInfo Map Catalog

If you are not a MapInfo Professional user, you will need to create the Map Catalog (or have
your database administrator create the Map Catalog) manually, as described below. You
only have to create the Map Catalog once per server/database.
1. Create the user MAPINFO in the specific database where the mappable tables are
located.
2. Create the table MAPINFO_MAPCATALOG in the database. The Create Table
statement needs to be equivalent to the following SQL Create Table statement:
Create Table MAPINFO_MAPCATALOG (
SPATIALTYPE Float,
TABLENAME Char(32),
OWNERNAME Char(32),
SPATIALCOLUMN Char(32),
DB_X_LL Float,
DB_Y_LL Float,
DB_X_UR Float,
DB_Y_UR Float,
COORDINATESYSTEM Char(254),
SYMBOL Char(254),
XCOLUMNNAME Char(32),
YCOLUMNNAME Char(32)
)
Note: It is important that the structure of the table is exactly like this statement. The
only substitution that can be made is for databases that support varchar or text
data types; these data types can be substituted for the Char data type.
3. Create a unique index on the TABLENAME and the OWNERNAME, so only one
table for each owner can be made mappable.

create unique index mapcat_i1

on mapinfo.mapinfo_catalog (OwnerName,TableName)

184 MapInfo MapX Developer Guide v4.5

 The MapInfo Map Catalog

4. Grant Select, Update, and Insert privileges on the MAPINFO_MAPCATALOG. This

allows users to make tables mappable. The delete privilege should be reserved for
database administrators.

grant select, insert, update on mapinfo.mapinfo_mapcatalog

to public

MapInfo MapX Developer Guide v4.5 185

Chapter 11: Accessing Data from a DBMS

Making a DBMS Table Mappable

For each spatial table that you want to access from MapX, you need to add a row to the
MAPINFO_MAPCATALOG table. If you do not use MapInfo Professional to manage the
Map Catalog, you will have to add rows to the MAPINFO_MAPCATALOG table manually.
The following table describes the syntax and meaning of each column:

Column Name Values to Assign Examples

SPATIALTYPE NOTE: This columns describes the Spatial 5.3

Object Format of how the data is stored and
indexed and the Spatial Object type(s)
supported and not supported in the column.
The digits to the left of the decimal point are the
Spatial Object Format. The digits to the right
represent the type of Spatial ObjectType that
can be stored in the column.

MapInfo Spatial Object Format

1.x: Point layer in X/Y columns indexed with
micode (a serialized quadtree key)
2.x: Oracle MD/SDO version 1 HHCODE_ -
Not Supported
3.x: Oracle MD/SDO version 1
HHCODE_PARTIONED - Not Supported
4.x: Point layer in X/Y columns
5.x: SpatialWare for Oracle
6.x: Ingres SOL - Not Supported
7.x: Sybase SQS - Not Supported
8.x: Oracle SDO version 2 - Not Supported
9.x: MapInfo Geocoding DataBlade SpatialWare
Point Module
10.x: MapInfo Geocoding DataBlade XY
Module
11.x: SpatialWare IDS/UDO datablade
12.x: SpatialWare Extender for DB2
13.x: Oracle Spatial

Spatial Object Type

x.0: Points only
x.1: Lines only
x.2: Regions only
x.3: All types supported
TABLENAME The name of the table. DRAINAGE

186 MapInfo MapX Developer Guide v4.5

 Making a DBMS Table Mappable

Column Name Values to Assign Examples

OWNERNAME The owner name of the table. GEORGETOWN

SPATIALCOLUMN The name of the column, if any, containing SW_GEOMETRY
spatial features:
SW_GEOMETRY (mappable using SpatialWare
Type/IDS/UDO)
NO_COLUMN (mappable using X–Y)
MI_SQL_MICODE (mappable using MI Code)
Or the name of the IDS/UDO, DB2, or Oracle
column that is ST_SPATIAL datatype.
Name of the Oracle 8i SDO_GEOMETRY
column.
DB_X_LL The X coordinate of the lower left corner of the –360
layer’s bounding rectangle, in units that ar
indicated by the COORDINATESYSTEM (see
below).
DB_Y_LL The lower left bounding Y value. –90
DB_X_UR The upper right bounding X value. 360
DB_Y_UR The upper right bounding Y value. 90
COORDINATESYST A string representing a MapInfo CoordSys Earth Projection 1, 0
EM clause (but without the keyword "CoordSys" at
the very start), which specifies a map projection,
coordinate units, etc. For simple Lon/Lat maps,
specify "Earth Projection 1, 0".
SYMBOL A MapInfo Symbol clause (if the layer contains Symbol(35,0,12)
only points); or a Symbol clause followed by a Pen(1,2,0) Pen(1,2,0)
Pen clause (indicating styles for linear features) Brush(2,255,255)
followed by another Pen clause (indicating
styles for the borders of regions) followed by a
Brush clause.
XCOLUMNNAME For the X/Y mappable tables, specify the name NO_COLUMN
of the column containing X–coordinates. If there
is no such column (i.e., if this table uses a single
spatial column instead of a pair of X–Y
columns) then specify NO_COLUMN or leave
empty.
YCOLUMNNAME For the X/Y mappable tables, specify the name NO_COLUMN
of the column containing Y–coordinates, or
specify NO_COLUMN.

MapInfo MapX Developer Guide v4.5 187

Chapter 11: Accessing Data from a DBMS

Symbol, Pen, Brush Clause Syntax

If you are manually creating a MAPINFO_MAPCATALOG table to provide support for a
remote spatial database, you will need to specify a symbol style, and possibly line and fill
styles as well.

Specifying Point Styles

Use a Symbol clause to specify point styles. There are three types of Symbol clauses: one
for specifying MapInfo 3.0-style symbols; one for specifying TrueType font symbols;
and one for specifying bitmap symbols.

Symbol Syntax Example

Symbol(shape, color, size) Symbol(35,0,12)

or Symbol(64,255,12,"MapInfo Weather" ,17,0)
Symbol(shape,color,size,font,fontstyle,rotation) Symbol("sign.bmp", 255, 18, 0)
or
Symbol(bitmapname,color,size,customstyle)

Specifying Line Styles

Use a Pen clause to specify line styles. In a Map Catalog, you may need to specify two
pen clauses: one to specify the appearance of linear features, and another to specify the
appearance of region borders.

Pen Syntax Example

Pen(thickness, pattern, Pen(1, 2, 0)

color)

Specifying Fill Styles

Use a Brush clause to specify the style for closed features (regions).

Brush Syntax Example

Brush(pattern,color,backgroundcolor) Brush(2, 255, 65535)

188 MapInfo MapX Developer Guide v4.5

 Troubleshooting

Troubleshooting
If you encounter problems with your MapX SpatialWare applications, use the following
table to help analyze and solve the problem.

Problem Description Possible Cause Solution

The MapX "Layer is not Data binding was Data binding is not currently
matchable." attempted against a supported for SpatialWare layers.
SpatialWare layer.
No object was found using A query was made against a Check that the table name is
the index that you specified. table that does not exist. correct and in the proper case.
No spatial object is Also, the table may need to be
contained in the result of mappable.
the spatial query. Use the EasyLoader Upload utility
A query was made against a to make the table a mappable
non-spatial table. table.
Check the query for possible
syntax errors. Also make sure that
the result of the query includes the
field specified in the spatial
column in the
MapInfo_MapCatalog.
MapX datasets.rowcount The dataset was created MapX datasets.rowcount will
has the value of zero. from a DBMS server. always have a value of zero for
datasets created from a DBMS
server. When iterating through a
dataset, a trappable error is
generated when you exceed
dataset bounds. Use this trappable
error as a flag for iteration.
Map appears to have The MBR for a DBMS layer Edit the extents (DB_X_LL,
incorrect zoom level. For is determined by the DB_X_UR, DB_Y_LL, DB_Y_UR)
example, the map may be MapInfo_MapCatalog table. in the MapInfo_MapCatalog
zoomed out too far to The table extents in the using the MapInfo Professional
identify any geography. MapCatalog result in a MDX tool, MISETMBR.MDX.
different zoom level than
the one you desire for your
output.

MapInfo MapX Developer Guide v4.5 189

Chapter 11: Accessing Data from a DBMS

190 MapInfo MapX Developer Guide v4.5

Chapter 12: Using Coordinate Systems
11 Chapter

➤ Basic Concepts of
Using Coordinate Systems Coordinate Systems
➤ Obtaining a Coordinate
In this chapter, you'll learn how to use Coordinate System Object
Systems (sometimes called "map projections") to ➤ Querying the Properties of
change the appearance of a map, or to change the a CoordSys Object
units in which map coordinates are processed by
➤ Displaying a Map in a
MapX. Different CoordSys
➤ Specifying X-Y Coordinates
in a Different CoordSys
➤ Displaying the Choose
Projection Dialog
➤ Using Settings From
MAPINFOW.PRJ
➤ Applying an Affine
Transformation
➤ Defining Custom Datums
➤ Datum Conversion
➤ For More Information...
Chapter 12: Using Coordinate Systems

Basic Concepts of Coordinate Systems

Every map has a coordinate system, which affects mapping software in various ways:

The coordinate system affects how X-Y coordinates are processed. For example, a location
can be expressed in terms of degrees longitude/latitude, or it can be expressed in terms of
other units, such as meters.

The coordinate system affects the appearance of the map. Changing a map's coordinate
system can make the map appear stretched or distorted. Coordinate systems represent a
complex, advanced area of computer mapping. This discussion assumes that you are
already familiar with concepts of mapping, such as false eastings and map projections.

Obtaining a Coordinate System Object

The MapX object model exposes coordinate system information through the CoordSys
object. This object's properties tell you everything you need to know about a coordinate
system.

There are several ways to obtain a CoordSys object. Which technique you use depends on
what you are trying to accomplish.

The Map.DisplayCoordSys property returns a read-write CoordSys object. You can use this
object to control the coordinate system and map projection used to display the map. For
details, see, "Displaying a Map in a Different CoordSys", later in this chapter"

The Map.NumericCoordSys property also returns a read-write CoordSys object. Use this
object to set the coordinate system that MapX uses to process X-Y coordinates. For details,
see "Specifying X-Y Coordinates in a Different CoordSys".

The Layer.CoordSys property returns a read-only CoordSys object, which tells you the
coordinate system used to store features in a specific map layer. If you set the
Map.DisplayCoordSys to match a Layer.CoordSys, you maximize the display speed of that
layer. (When the DisplayCoordSys is different than the CoordSys in which a layer was
saved, MapX converts features on the fly, which slows down the display.)

192 MapInfo MapX Developer Guide v4.5

 Querying the Properties of a CoordSys Object

Querying the Properties of a CoordSys Object

For each type of coordinate system, only some of the properties are applicable. For example,
if the CoordSys.Type property is miRobinson (12), only the Datum, Units, and
OriginLongitude properties are applicable. The Robinson map projection simply does not
use any of the other properties.

To see whether a property is used by a particular projection, see, "Summary of Parameters

Used by Coordinate Systems".

You can query all of the properties for any CoordSys object—even properties that are not
applicable for that type of coordinate system. If a property is not applicable given the
CoordSys Type, MapX returns a default value. If you need to persist a CoordSys object, you
can do so by querying and saving all of its properties, without worrying about whether each
property is applicable.

Displaying a Map in a Different CoordSys

There are two ways an application can specify the coordinate system (or "projection") in
which a map is displayed:

• Use the Map.DisplayCoordSys.Set method to set a new display CoordSys.

-or-
• Assign a new CoordSys object to the Map.DisplayCoordSys property.
Note: If a map includes one or more raster image layers, MapX automatically displays
the map in the projection specified by the most visible raster image. The
coordinate system could then change as the map view changes (due to zooming
or panning) if a different raster image with a different projection becomes the
most visible. In this case, you cannot change the map's display coordinate system.

MapInfo MapX Developer Guide v4.5 193

Chapter 12: Using Coordinate Systems

Displaying a Robinson Map

The following Visual Basic example
changes the map's DisplayCoordSys so
that the map is displayed with the
Robinson map projection, which looks
like this:

Dim iProjectionType As
Integer
Dim iDatumNumber As
Integer
Dim iUnits As Integer
Dim dOriginLongitude As Double
Initialize the variables to be used by coordsys.set.
' Values were obtained from the "Robinson" entry
' in the file MAPINFOW.PRJ, which looks like this:
' "Robinson", 12, 62, 7, 0
iProjectionType = miRobinson '(value: 12)
iDatumNumber = 62 'North American 1927 (NAD 27)
iUnits = miUnitMeter '(value: 7)
dOriginLongitude = 0
Map1.DisplayCoordSys.Set iProjectionType, iDatumNumber, _
iUnits, dOriginLongitude

194 MapInfo MapX Developer Guide v4.5

 Specifying X-Y Coordinates in a Different CoordSys

Specifying X-Y Coordinates in a Different

CoordSys
The Map object has a NumericCoordSys property, which represents the coordinate system
used to process numeric coordinates. This property affects both the input and the output of
X-Y coordinates, as follows:

• When you specify map coordinates (as object properties or method parameters),
MapX assumes the coordinates are in this coordinate system.
• When MapX returns map coordinates (as object properties or events), the
coordinates are in this coordinate system.
By default, the coordinate system is Longitude/Latitude WGS-84. In other words, if you do
not modify the NumericCoordSys, MapX assumes that map coordinates are in degrees
Longitude/Latitude.

There are two ways an application can specify the coordinate system used to process
numeric coordinates:

• Use the Map.NumericCoordSys.Set method to set a new numeric CoordSys.

-or-
• Assign a new CoordSys object to the Map.NumericCoordSys property.

Retrieving Coordinates in a Different CoordSys

The following Visual Basic example changes the map's NumericCoordSys so that the
coordinates are returned in a different coordinate system.
Dim iProjectionType As Integer
Dim iDatumNumber As Integer
Dim iUnits As Integer
Dim dOriginLongitude As Double

' Display map's center X-Y in original coordsys

Debug.Print "Original Center: " & Map1.CenterX & ", " & _
Map1.CenterY

' Initialize the variables to be used by coordsys.set.

' Values were obtained from the "Robinson" entry
' in the file MAPINFOW.PRJ, which looks like this:
' "Robinson", 12, 62, 7, 0

iProjectionType = miRobinson '(value: 12)

MapInfo MapX Developer Guide v4.5 195

Chapter 12: Using Coordinate Systems

iDatumNumber = 62 'North American 1927 (NAD 27)

iUnits = miUnitMeter '(value: 7)
dOriginLongitude = 0

Map1.NumericCoordSys.Set iProjectionType, iDatumNumber, _

iUnits, dOriginLongitude

' Display map's center X-Y in the new coordsys

Debug.Print "New Center: " & Map1.CenterX & ", " & Map1.CenterY

Displaying the Choose Projection Dialog

To display a dialog that lets the user choose a coordinate system, use the
CoordSys.PickCoordSys method.

The dialog is automatically initialized, so that the highlighted description describes the
CoordSys object. If the user clicks OK in the dialog, the method returns True, and the
CoordSys object is updated to match the coordinate system chosen by the user.

To display the dialog box at design time:

196 MapInfo MapX Developer Guide v4.5

 Displaying the Choose Projection Dialog

1. Right-click the Map control.

2. Choose Properties from the shortcut menu.
3. On the General tab, click the Projection button.
MapX displays the same Choose Projection dialog, which is invoked by the PickCoordSys
method.

Example (PickCoordSys)
The following statement displays the Choose Projection dialog at run time, allowing the
user to change the coordinate system in which the map is displayed.

Map1.DisplayCoordSys.PickCoordSys

MapInfo MapX Developer Guide v4.5 197

Chapter 12: Using Coordinate Systems

Summary of Parameters Used by Coordinate

Systems
The CoordSys object supports several parameters (Datum, Units, Origin Longitude, etc.).
However, each projection uses only some of the parameters. The following table shows
which parameters apply to which projections.

Projection Datum Units Origin Origin Std. Std. Azim. Scale False False Range
Long. Lat. Par. Par. Fact. East. Nor.
1 2

Albers Equal- X X X X X X X X
Area Conic

Azimuthal X X X X* X
Equidistant

Cylindrical X X X X
Equal Area

Eckert IV X X X

Eckert VI X X X

Equidistant X X X X X X X X
Conic

Gall X X X

Hotine X X X X X X X X
Oblique
Mercator

Lambert X X X X* X
Azimuthal
Equal–Area

Lambert X X X X X X X X
Conformal
Conic

Longitude– X
Latitude

Mercator X X X

Miller X X X

Mollweide X X X

New Zealand X X X X X X
Map Grid

Robinson X X X

Sinusoidal X X X

Stereographic X X X X X X X

198 MapInfo MapX Developer Guide v4.5

 Using Settings from MAPINFOW.PRJ

Projection Datum Units Origin Origin Std. Std. Azim. Scale False False Range
Long. Lat. Par. Par. Fact. East. Nor.
1 2

Swiss X X X X X X
Oblique
Mercator

Transverse X X X X X X X
Mercator

* MapX supports the Azimuthal Equidistant and Lambert Azimuth Equal-Area projections
in the polar aspect only. The Origin Latitude for these projections must be either 90 or -90.

Using Settings from MAPINFOW.PRJ

If you use MapInfo Professional, you will find a file called MAPINFOW.PRJ in the same
directory as the MapInfo executable. MAPINFOW.PRJ is a text file containing the
parameters that define MapInfo's coordinate systems. A copy of MAPINFOW.PRJ is
included with MapX.

Suppose you have used a specific projection in MapInfo—the Robinson projection, for
example—and you want to specify that projection in a MapX application. The
MAPINFOW.PRJ file gives you the information you need to fill in the various parameters to
MapX methods, such as CoordSys.Set.
Entries in MAPINFOW.PRJ have the following parameters. Parameters are separated by
commas.

Part Description

Description A string that describes the coordinate system. This description

appears in dialog boxes.
Type A number that usually matches one of the
CoordSysTypeConstants exactly. Users may have customized this
number in two ways: To specify an Affine Transformation, the user
adds 1000 to this number; to specify bounds, the user adds 2000 to
this number.
Datum A number representing one of the Datums supported by MapX, or
a special number (999 or 9999) indicating a custom datum.
Units [Set of 4 Custom Optional; applies only if the Datum number is 999.
Datum Arguments]

MapInfo MapX Developer Guide v4.5 199

Chapter 12: Using Coordinate Systems

Part Description

[Set of 9 Custom Optional; applies only if the Datum number is 9999.

Datum Arguments]
Set of Projection From zero to 8 parameters, depending on which Type is specified.
Parameters Refer to Summary of Parameters Used by Coordinate Systems",
to see which parameters are used by this Type.
[Set of 7 Affine Optional; applies only if the Type number is exactly 1000 or 3000
Transformation greater than a CoordSysTypeConstant.
Parameters]
[Set of 4 Bounds Optional; applies only if the Type number is exactly 2000 or 3000
Parameters] greater than a CoordSysTypeConstant.

MAPINFO.PRJ Example
Open MAPINFOW.PRJ in a text editor, or in a word processing package.
Note: MapX uses this file when interpreting and setting the map coordinate system.
Make a back up of this file prior to making any changes.
Within MAPINFOW.PRJ, search for the name of a MapInfo projection, such as
"Robinson". The line that you find contains the definition for the Robinson projection:
"Robinson", 12, 62, 7, 0
This line tells us several things about the Robinson coordinate system:
• The string at the start of the line is a description. The first number after the
description, 12 in this example, tells you what type of coordinate system applies.
Check the number 12 against the table of MapX CoordSysType constants, and you'll
see that type 12 matches the MapX constant, miRobinson. (In this case, the
description made it obvious that the coordinate system uses a Robinson projection;
but in other cases, the projection might not be obvious.)
• Refer to "Summary of Parameters Used by Coordinate Systems" to see which
parameters are used by Robinson maps. Robinson maps use only three parameters:
datum, units, and origin longitude. Now you know how to interpret the rest of the
numbers on the line: 62 is the datum number, 7 is the unit number, and 0 is the
Origin Longitude. From the list of datums supported by MapX, you can determine
that datum 62 represents NAD 27 for the continental US.
• From the table of MapUnit constants, you can determine that unit type number 7
matches the value of the MapX constant, miUnitMeter.
You can use this set of values (12, 62, 7, 0) as the parameters when calling the
CoordSys.Set method. For example:
objCoordSys.Set 12, 62, 7, 0

200 MapInfo MapX Developer Guide v4.5

 Using Settings from MAPINFOW.PRJ

How to Interpret Special Datum Numbers

MapInfo users can customize the MAPINFOW.PRJ file by creating custom datum
definitions. There are two types of custom datum definitions:
• A full custom datum definition consists of datum number 9999, immediately
followed by nine other custom datum parameters, separated by commas.
• A simplified custom datum definition consists of datum number 999, immediately
followed by four other custom datum parameters, separated by commas.
If a line in MAPINFOW.PRJ specifies datum number 999 or 9999, then the custom datum
parameters appear before the rest of the coordinate system parameters (units, origin
longitude, etc.). For more information on custom datum syntax, see the section Defining
Custom Datums later in this chapter.

How to Interpret Special CoordSys Type Numbers

The coordinate system type number that appears in MAPINFOW.PRJ (such as 12, in the
example above) might not match any of the MapX CoordSysType constant values. You may
need to subtract 1000, 2000, or 3000 from the number to obtain a number that represents a
valid MapX CoordSysType.

If a line from MAPINFOW.PRJ contains an affine transformation, then the coordinate

system type number will have 1000 added to it, and the seven affine transformation
parameters will be added to the end of the line.
If the line includes a bounds definition, then the projection type number will have 2000
added to it, and the four bounds parameters will be added to the end of the line.

For example, the following line from a hypothetical MAPINFOW.PRJ file represents a
coordinate system with both an affine transformation and a bounds definition. This
coordinate system uses UTM Zone 10 (coordinate system type: miTransverseMercator
which has a value of 8). However, because this coordinate system includes both an affine
transformation and a bounds description, the number following the description is 3008 (8 +
1000 + 2000).

"DCS", 3008, 74, 7, -123, 0, 0.9996, 500000, 0, 3, 1.57, -0.21,

_
84120.5, 0.19, 2.81, -20318.0, 70000, 0, 80000, 50000
Although the number 3008 is valid within MAPINFOW.PRJ, you must use the unaltered
number, 8, in MapX.
The "DCS" example above can be interpreted as follows:

MapInfo MapX Developer Guide v4.5 201

Chapter 12: Using Coordinate Systems

name,
CoordSysType + 3000,
the projection parameters (Transverse Mercator uses 7 _
parameters),
the 7 affine transformation parameters,
The 4 bounds parameters (in the order: xmin, ymin, xmax, ymax)

Applying an Affine Transformation

If you need to define rotated or skewed coordinate systems, you need to specify an affine
transformation. In MapX, you can define such a transformation by creating an
AffineTransform object, then passing the object to the CoordSys.Set method.

Note: If you simply want to rotate the map, you do not need to specify an affine
transformation. Instead, set the Map object's Rotation property.
An affine transformation has the following form:
x' = Ax + By + C
y' = Dx + Ey + F
In these equations, the base coordinates (x, y) are transformed to produce the derived
coordinates (x', y'). The six constants A through F determine the effect of the transformation,
as follows:

A Performs scaling or stretching along the X axis.

B Performs rotation or skewing along the X axis.
C Performs shifting along the X axis.
D Performs rotation or skewing along the Y axis.
E Performs scaling or stretching along the Y axis.
F Performs shifting along the Y axis.

Defining Custom Datums

Most coordinate systems use one of the standard datums supported by MapX. If you need
to use a datum that is not in the list, and you know the datum’s mathematical parameters,
then you can define the coordinate system using a custom datum.

202 MapInfo MapX Developer Guide v4.5

 Defining Custom Datums

This discussion provides examples for both MapX and MapInfo Professional, for the sake of
those users who use both products. If you have already gone through the process of creating
a custom datum in MapInfo, you should find it easy to adapt your datum to MapX. If you
do not use MapInfo Professional, you can simply ignore the MapInfo-specific examples.

What Is a Datum?
A datum is a mathematical description of the earth’s shape and orientation. Because the
earth’s shape is not uniform, there are many different local datums used in different parts of
the world. These local datums provide a close approximation to the earth’s surface in a
particular area.
Each Earth coordinate system uses a specific datum to approximate the earth’s surface. If
two coordinate systems use different datums, then mapping software must perform a
datum transformation when it converts coordinates from one coordinate system to the other.
MapX and MapInfo use the Bursa-Wolfe datum transformation method, which is generally
accurate to within 10 meters. (When MapInfo converts between two coordinate systems that
use the same datum, no datum transformation is performed, and the results are generally
accurate to within 0.1 meter.)

MapInfo MapX Developer Guide v4.5 203

Chapter 12: Using Coordinate Systems

The Parameters that Define a Datum

MapX and MapInfo Professional use the following information to define a datum:

• An ellipsoid, also called a spheroid. This is an ellipse rotated around its minor axis
to form a three-dimensional surface. The ellipsoid is described by two mathematical
parameters: the length, in meters, of its semi-major axis (denoted by the letter a)
and its degree of flattening (denoted by the letter f). Over 40 predefined ellipsoids
are supported; see Ellipsoids Supported by MapX.
• Three shift parameters specifying the distance, in meters, to shift the ellipsoid along
each of its axes. These parameters are usually denoted by dX, dY, and dZ. You may
also see them denoted by u,v, and w. The MapX Datum.Set method identifies these
parameters as ShiftX, ShiftY, and ShiftZ.
• Three rotation parameters specifying the angle, in arc-seconds, to rotate the
ellipsoid around each of its axes. These parameters are usually denoted by EX, EY,
and EZ. The Datum.Set method identifies these parameters as RotateX, RotateY, and
RotateZ.
• A scale correction factor specifying the amount, in parts per million, to adjust the
size of the ellipsoid. This parameter is denoted by the letter m.
• The longitude of the prime meridian, in degrees east of Greenwich. The prime
meridian specifies which location on earth is assigned longitude 0°. Most datums
use Greenwich as the prime meridian, so this parameter is usually zero. However,
some datums use a different location as the prime meridian. For example, the NTF
datum uses Paris as its prime meridian, which is 2.33722917 degrees east of
Greenwich. If you use the NTF datum in a coordinate system, all longitudes in that
coordinate system are relative to Paris instead of Greenwich.

Defining a Datum in MapInfo Professional

In MapInfo, you define a custom datum in a coordinate system by using datum number
9999 followed by the datum parameters, in this order:

9999, EllipsoidNumber, dX, dY, dZ, EX, EY, EZ, m, PrimeMeridian

Some datums specify only an ellipsoid and shift parameters (dX,dY, dZ), with no rotation
parameters, scale correction, or prime meridian. In those cases, you can use datum number
999 instead of 9999, to simplify the definition:

999, EllipsoidNumber, dX, dY, dZ

These sets of parameters are then copied into the file MAPINFOW.PRJ; see examples below.

204 MapInfo MapX Developer Guide v4.5

 Datum Conversion

Defining a Datum in MapX

In MapX, you define a custom datum by creating a Datum object, and using its Set method
to set the parameters. You then use this Datum object as one of the parameters to the
CoorsSys.Set method.

Common Mistakes, and How to Avoid Them

The shift and rotation parameters describe the ellipsoid’s orientation in space, as compared
to the WGS 84 datum. It’s important to make sure that these parameters have the correct
signs (positive or negative). Usually, a document describing a local datum will list the
parameters required to convert coordinates from the local datum to WGS 84. (This is the
same as saying that the parameters were derived by subtracting the local datum from WGS
84.) In that case, you can use the parameters exactly as they appear in the document.
However, if you have a document that lists parameters for converting coordinates in the
opposite direction — from WGS 84 to the local datum — then you must reverse the signs of
the shift, rotation, and scale correction parameters.

It’s also very important to list the parameters in the correct order. Some documents list the
rotation parameters with EZ first, like this: EZ, EY, EX. In those cases, you must reverse the
order of the rotation parameters when defining the custom datum. This is especially easy to
overlook when your document uses Greek letters to denote the parameters.

Datum Conversion
When converting coordinates from one datum to another, MapX has used the Molodensky
(3-parameter) and Bursa-Wolfe (7-parameter) methods. These are general-purpose methods
that can convert coordinates from any datum to any other datum.

After the NAD 83 datum was introduced, NOAA developed a program called NADCON,
which stands for North American Datum CONversion. This is a very specialized program
that converts coordinates only from NAD 27 to NAD 83 and vice versa. For this specialized
task, it’s much more accurate than the Molodensky general-purpose method; NADCON is
accurate to about 0.1 meter, and Molodensky is accurate to only 10-30 meters. Most U.S.
government agencies, including the Census Bureau, have standardized on NADCON for
converting between NAD 27 and NAD 83.

MapInfo MapX Developer Guide v4.5 205

Chapter 12: Using Coordinate Systems

Beginning with MapX 3.5, the NADCON algorithm is used to convert coordinates between
NAD 27 and NAD 83 if those coordinates lie within the areas covered by NADCON (United
States, Puerto Rico, and the Virgin Islands). If the coordinates lie outside those areas, or if
they use datums other than NAD 27 or NAD 83, MapX uses the Molodensky or Bursa-Wolfe
conversion methods.
Due to the file access required, the NADCON method can be slightly slower than the
Molodensky method. If you want to turn off the NADCON method, add a “NADCON”
entry to the registry. The registry entry should have this path:

• HKEY_LOCAL_MACHINE\Software\\MapInfo\\MapX\\3.0\NadCon
If this entry is set to zero, then the Molodensky conversion method will be used instead of
NADCON. To enable NADCON, set the entry to 1 (default). MapX reads this entry when it
is loaded, and all maps use the same setting. You can't turn NADCON on or off for a
particular map.

206 MapInfo MapX Developer Guide v4.5

 For More Information...

For More Information...

For more information about coordinate systems and map projections, review the following:

Related Pamphlets
• American Cartographic Association. Choosing a World Map—Attributes,
Distortions, Classes, Aspects. Falls Church, VA: American Congress on Surveying
and Mapping. Special Publication No. 2. 1988.
• American Cartographic Association. Matching the Map Projection to the Need. Falls
Church, VA: American Congress on Surveying and Mapping. Special Publication
No. 3. 1991.
• American Cartographic Association. Which Map is Best? Projections for World
Maps. Falls Church, VA: American Congress on Surveying and Mapping. Special
Publication No. 1. 1986.
To obtain these pamphlets, please contact:
American Congress on Surveying and Mapping
5410 Grosvenor Lane, Suite 100
Bethesda, MD 20814–2212
301–493–0200

Related Books
• John P. Snyder. Map Projections—A Working Manual. Washington: U.S. Geological
Survey Professional Paper 1395. 1987.
• John P. Snyder and Philip M.Voxland. An Album of Map Projections. Washington:
U.S. Geological Survey Professional Paper 1453. 1989.
To obtain these books, please contact:
Earth Science Information Center
U.S. Geological Survey
507 National Center
Reston, VA 20192
1.800.ASK.USGS -or- 1.703.648.6045

MapInfo MapX Developer Guide v4.5 207

Chapter 12: Using Coordinate Systems

208 MapInfo MapX Developer Guide v4.5

Chapter 13: Working With Visual C++
12 Chapter

➤ Understanding the Sample

Working with Visual C++ Application
➤ Upgrading C++
One way to learn MapX is to study sample Applications from an
applications. Look for sample applications in the Earlier Version of MapX
folder: MapInfo MapX 4.0\Samples40. ➤ Accessing MapX Properties
and Methods in C++
• Understanding the Sample Application
• Upgrading C++ Applications from an ➤ Including MapX.cpp in Your
Earlier Version of MapX Project
• Accessing MapX Properties and Methods ➤ Creating a MapX Control
in C++
• Including MapX.cpp in Your Project
➤ Creating Menu Items
• Creating a MapX Control Using C++ ➤ Handling MapX Events
• Creating Menu Items Using C++ ➤ Using Custom Tools
• Handling MapX Events Using C++
➤ Data Binding Using C++
• Using Custom Tools (C++ Example)
• Data Binding Using C++ ➤ Adding a Shortcut Menu
• Adding a Shortcut Menu Using C++ ➤ Using the Built-In Helper
• Using the Built-In Helper Dialogs from Dialogs from C++
C++
➤ Handling MapX Exceptions
• Handling MapX Exceptions Using C++
➤ Creating a Map in a C++
Dialog
Chapter 13: Working With Visual C++

Creating a Map in a C++ Dialog Understanding the Sample

Application
As you study the sample C++ application mapxsamp.cpp, the following topics will help you
understand MapX.

• Upgrading C++ applications from an earlier version of MapX

• Accessing MapX Methods and Properties in C++
• Including Mapx.cpp in your project
• Creating a MapX control
• Creating menu items
• Handling MapX events
• Using custom tools
• Data binding
• Adding a shortcut menu
• Using the built-in helper dialogs
• Handling MapX Exceptions in C++
• Creating a map in a C++ dialog
Note: These topics assume that you are using Microsoft’s Document/View model
(standard MFC AppWizard app.) The sample application can be built in
Developer Studio with mapxsamp.mdp.

Tips for C++ Developers

If you are using Visual C++ 5 or a later version, add the sample mapxsamp.cpp project to
your workspace. That gives you quick access to the sample files and Class Wizard, right next
to your own project files. You can delete the sample project from your workspace at any
time.

If you created a MapX application using an earlier version of MapX, see “Upgrading C++
Applications from an Earlier Version of MapX”

210 MapInfo MapX Developer Guide v4.5

 Upgrading C++ Applications from an Earlier Version of MapX

Upgrading C++ Applications from an Earlier

Version of MapX
If you wrote a C++ application using an earlier version of MapX, you will need to use the
new MapX wrapper classes (mapx.h and mapx.cpp) to upgrade your application to the
current version of MapX.

You may need to modify the strings that you pass to CreateDispatch. With an earlier version
of MapX , you may have used a string to specify an object name; for example:

Flds.CreateDispatch("MapX.Fields")
With the current version of MapX, you need to specify a different string:

Flds.CreateDispatch("MapX.Fields.4")
To make your code more compatible with future versions of MapX, you may want to use
GetClsid instead of a string. The result returned by GetClsid will work in current and future
versions of MapX. For example:

Flds.CreateDispatch(Flds.GetClsid())
This change applies to all objects that you create.

In the MapX object model, you can create stand-alone objects with these object classes:.

AffineTransform BindLayer BitmapSymols

CoordSys Datum Feature

Fields LayerInfo Map

ODBCQueryInfo Parts Point

Points Rectangle RowValue

RowValues Style Variables

MapInfo MapX Developer Guide v4.5 211

Chapter 13: Working With Visual C++

Accessing MapX Properties and Methods in

C++
Objects
Each MapX object is implemented by a C++ class in the files MapX.h and MapX.cpp. The
name of the C++ class is the same as the MapX object, prepended by 'CMapX'. For example,
the DataSet object has a class called CMapXDataset.

Properties
The Properties of a MapX object are implemented by member functions in the C++ classes.
A Read/write property like the 'Name' property of the Dataset object will have 2 member
functions in CMapXDataSet—one to set the property value, and one to get the value of the
property. The member function names will have 'Get' or 'Set' prepended to the property
name.

CString GetName();
void SetName(LPCTSTR);
A read-only property will only have a 'Get' member function, and not a 'Set' member
function.

Methods
The methods of a MapX object are implemented by a member function with the same name
as the MapX object's method. You will notice that the types of many of the parameters will
be 'const VARIANT &'. This means the member function is expecting a variable of type
VARIANT to be passed to it.

Optional Parameters
Many methods have parameters that are considered 'optional' in Visual Basic or other
scripting languages. In C++ all parameters must be specified when calling these methods.
All optional parameters are implemented asVARIANTs.To call a MapX method with an
optional parameter, you must set up the variant as follows:

VARIANT vtOptional;
vtOptional.vt = VT_ERROR;
vtOptional.scode = DISP_E_PARAMNOTFOUND;

212 MapInfo MapX Developer Guide v4.5

 Including MapX.cpp in Your Project

The MapX.h file includes a helper class COptionalVariant that does this in its constructor
You can use this whenever you want to call a method with an optional parameter.

Overload Member Functions

In order to make it easier to call methods using normal C++ types instead ofVARIANTS,
most of the MapX methods are overloaded with simpler parameters with default values that
construct VARIANTs and call the 'real' member functions. Since not all possible
combinations are handled, feel free to derive your own classes from the CMapX classes and
add your own overloaded member functions.

OLE Dispatch Driver

The C++ classes in MapX.h are derived from the MFC class COleDisplatchDriver. All
properties and methods ultimately end up calling IDispatch->Invoke() to tell the MapX ocx
what to do. COleDisplatchDriver usually handles calling Release() correctly on the
IDispatch pointers returned from properties or methods, but there are a few places where
you should be careful. When a MapX object is passed to an event via its IDispatch interface,
you must be sure not to release the pointer, because objects passed to events have not been
AddRef()'d by MapX.

Properties and Methods that Return Other Objects

You can assign the return value of methods or properties that return objects directly to a
variable of the same type.

Including MapX.cpp in Your Project

Include the MapX.cpp and .h files in your project. They contain the class definitions and
method implementations for access to the MapX control. The MapX.h and MapX.cpp files
can be found in the Samples40\CPP subdirectory where MapX is installed.

Using Visual C++ Version 4

From the Insert menu, choose Files Into Project. Choose MapX.cpp as the file to insert.

Note: Do not choose the Insert > Component command. Doing so would create a .cpp
file, but it would be incomplete.

MapInfo MapX Developer Guide v4.5 213

Chapter 13: Working With Visual C++

Using Visual C++ Version 5 or Later

From the Project menu, choose Add To Project > Files. Choose MapX.cpp as the file to add.

Caution! Do not choose Project > Components And Controls command. Doing so would
create a .cpp file, but it would be incomplete.

Creating a MapX Control Using C++

Include the control in the view that will contain it:

#include "MapX.h"
:
:
:
class CMapxSampleView : public CView
{
:
:
:
protected:
CMapX m_ctrlMapX;
:
:
}

To declare a constant to represent the control ID for MapX:

1. Go to View > Resource Symbols.
2. Click NEW.
3. Type "IDC_MAP" for the name.
To create handlers for the WM_SIZE and WM_CREATE messages in the class Wizard:
1. Go to View > ClassWizar
2. Select your View class from the class Name combo-box.
3. In the message box, click on "WM_CREATE", and click Add Function.
4. Still, in the message box, choose "WM_SIZE" and click Add Function.
5. Then, click Edit Code.
Create the control when the view is created. In CMapXSampView::OnCreate:

// create map with default size

// resize message will cause it to be

214 MapInfo MapX Developer Guide v4.5

 Creating Menu Items Using C++

// size to the client area of the view

if (!m_ctrlMapX.Create(NULL, WS_VISIBLE, CRect(0,0,100,100),
this,IDC_MAP))
return -1;

Keep the control's size in sync with the containing window:

// resize the map to be the same size as our client area
void CMapxSampleView::OnSize(UINT nType, int cx, int cy)
{
CView::OnSize(nType, cx, cy);
if (cx != 0 && cy != 0)
m_ctrlMapX.MoveWindow(0,0,cx,cy,TRUE);
}
Create a new message header for the WM_SETFOCUS message as you did for the
WM_CREATE message.

In our example, we want to make sure that MapX gets the focus whenever the window is
active:

void CMapxSampleView::OnSetFocus(CWnd* pOldWnd)

{
CView::OnSetFocus(pOldWnd);

m_ctrlMapX.SetFocus();
}

Creating Menu Items Using C++

You can expose MapX capabilities by creating a menu for the Doc/View that contains the
MapX control. Reference the menu where the doc template is created (mapxsamp.cpp):

CMultiDocTemplate* pDocTemplate;
pDocTemplate = new CMultiDocTemplate(
IDR_MAPXSATYPE, //Menu items to control MapX
RUNTIME_CLASS(CMapxSampleDoc),
RUNTIME_CLASS(CChildFrame), //custom MDI child frame
RUNTIME_CLASS(CMapxSampleView));

AddDocTemplate(pDocTemplate);
Add handlers for the MapX menu items. In the sample, these menu items are defined in the
menu section in mapxsamp.rc. Note that in this example, we use menu commands as a
quick demonstration of the map interaction tools (Zoom In tool, Radius Select tool, etc.). In a

MapInfo MapX Developer Guide v4.5 215

Chapter 13: Working With Visual C++

more polished application, you would probably use toolbar buttons as the user interface,
rather than menu commands.

"Previous &View", ID_CONTEXT_PREVIOUSVIEW

"View &Entire Map", ID_VIEW_VIEWENTIREMAP
SEPARATOR
"&Properties...", ID_VIEW_PROPERTIES

"&Layer Control...", ID_VIEW_LAYERCONTROL

SEPARATOR
"&Toolbar", ID_VIEW_TOOLBAR
"&Status Bar", ID_VIEW_STATUS_BAR

"&Arrow", ID_MAP_TOOL_ARROW
SEPARATOR
"Zoom &In", ID_MAP_TOOL_ZOOMIN
"Zoom &Out", ID_MAP_TOOL_ZOOMOUT
"&Pan", ID_MAP_TOOL_PAN
"&Center", ID_MAP_TOOL_CENTER
SEPARATOR
"&Select", ID_MAP_TOOL_SELECT
"&Radius Select", ID_MAP_TOOL_RADIUSSELECT
"R&ectangle Select", ID_MAP_TOOL_RECTANGLESELECT

Once these menu item IDs are defined, handlers can be added via Class Wizard. In your
class containing the MapX control, create handlers for ID_MAP_TOOL_ARROW,
ID_MAP_TOOL_ZOOMIN, etc.

// tell MapX what the current tool is

void CMapxSampleView::OnMapToolArrow()
{
m_ctrlMapX.SetCurrentTool(miArrowTool);
}
void CMapxSampleView::OnMapToolZoomin()
{
m_ctrlMapX.SetCurrentTool(miZoomInTool);
}
// switch to the previous view
void CMapxSampleView::OnContextPreviousview()
{
m_ctrlMapX.ZoomTo(m_dPrevZoom, m_dPrevX, m_dPrevY);
}

216 MapInfo MapX Developer Guide v4.5

 Handling MapX Events Using C++

Once the tool is selected, built-in MapX functionality handles the zooming, selecting, etc.

Handling MapX Events Using C++

To handle MapX events, you first need to build an eventsink map for the events you are
interested in. Constants for the event DISPATCH id’s are defined in MapX.h for MapX
custom events, and in <olectl.h> for OLE stock events.

// From MapX.h
#define MAPX_DISPID_SELECTION_CHANGED 0x1
#define MAPX_DISPID_RESOLVEDATABIND 0x2
#define MAPX_DISPID_TOOLUSED 0x3
#define MAPX_DISPID_REQUESTDATA 0x4
#define MAPX_DISPID_DATAMISMATCH 0x5
#define MAPX_DISPID_MAPVIEWCHANGED 0x6
#define MAPX_DISPID_ANNOTATIONADDED 0x7
#define MAPX_DISPID_ANNOTATIONCHANGED 0x8
#define MAPX_DISPID_THEMEMODIFYREQUESTED 0x9
#define MAPX_DISPID_DRAWUSERLAYER 0x0a
#define MAPX_DISPID_POLYTOOLUSED 0x0b
// From <olectl.h>
#define DISPID_CLICK (-600)
#define DISPID_DBLCLICK (-601)
#define DISPID_KEYDOWN (-602)
#define DISPID_KEYPRESS (-603)
#define DISPID_KEYUP (-604)
#define DISPID_MOUSEDOWN (-605)
#define DISPID_MOUSEMOVE (-606)
#define DISPID_MOUSEUP (-607)
#define DISPID_ERROREVENT (-608)

The ON_EVENT macro in the EVENT_SINK also specifies an ID for the MapX control
(IDC_MAP in the example), the parameters to the event, and the name of the event handler
method.

In the View header file (her, MapXSampView.h), put the line

"DECLARE_EVENTSINK_MAP ()" below the "DECLARE_MESSAGE_MAP" line.

MapInfo MapX Developer Guide v4.5 217

Chapter 13: Working With Visual C++

From mapxsampview.cpp:
BEGIN_EVENTSINK_MAP(CMapxSampleView, CView)
ON_EVENT(CMapxSampleView, IDC_MAP, DISPID_MOUSEMOVE,
OnMouseMoveInMap,VTS_I2 VTS_I2 VTS_XPOS_PIXELS
VTS_YPOS_PIXELS)
ON_EVENT(CMapxSampleView, IDC_MAP,
MAPX_DISPID_MAPVIEWCHANGED,
OnMapViewChanged, VTS_NONE)
ON_EVENT(CMapxSampleView, IDC_MAP, DISPID_MOUSEUP,
OnMouseUpInMap, VTS_I2 VTS_I2 VTS_XPOS_PIXELS VTS_YPOS_PIXELS)
ON_EVENT(CMapxSampleView, IDC_MAP, MAPX_DISPID_TOOLUSED,
OnToolUsed, VTS_I2 VTS_R8 VTS_R8 VTS_R8 VTS_R8 VTS_R8 VTS_BOOL
VTS_BOOL VTS_PBOOL)
ON_EVENT(CMapxSampleView, IDC_MAP,
MAPX_DISPID_THEMEMODIFYREQUESTED, OnThemeModifyRequested,
VTS_DISPATCH)
END_EVENTSINK_MAP()
The event handler code for the OnToolUsed event follows. The declaration, from
mapxsampview.h:

void OnToolUsed(short ToolNum, double X1, double Y1, double

X2,
double Y2, double Distance, BOOL Shift, BOOL Ctrl, BOOL*
EnableDefault);
…and the implementation from mapxsampview.cpp (we just output the parameters to the
debug window using the TRACE macro):

void CMapxSampleView::OnToolUsed(short ToolNum, double X1, double

Y1, double X2, double Y2, double Distance, BOOL Shift, BOOL Ctrl,
BOOL* EnableDefault)
{
CString str;
str.Format("Tool=%d, [%f,%f] [%f, %f], dist=%f, %s %s\n",
ToolNum, X1,Y1,X2,Y2,Distance,
(Shift)?"Shift":"",(Ctrl)?"Ctrl":"");
TRACE(str);
}

You would normally handle custom tools in this function, or override MapX's default
behavior for built-in tools. For an example, see “Using Custom Tools”.

Note: For events in which objects are passed as parameters, the event handler should
not change the reference count of the object. For an example, see," Handling
MapX Exceptions Using C++".

218 MapInfo MapX Developer Guide v4.5

 Using Custom Tools (C++ Example)

Using Custom Tools (C++ Example)

Once you have used the CreateCustomTool method to create custom tools, use the ToolUsed
event to carry out an action when the user uses the custom tool.
This example tests to see which tool is being used. Then, depending on which tool is in use,
this example either:

• Changes the style of the map feature underneath the cursor, or

• Places a new symbol where the user clicked.
void CMapxSampleView::OnToolUsed(short ToolNum, double X1,
double Y1, double X2, double Y2, double Distance,
BOOL Shift, BOOL Ctrl, BOOL* EnableDefault)
{
CString str;
CMapXPoint pnt;

str.Format("Tool=%d, [%f,%f] [%f, %f], dist=%f, %s %s\n",

ToolNum, X1,Y1,X2,Y2,Distance,
(Shift)?"Shift":"",(Ctrl)?"Ctrl":"");
TRACE(str);
// change the style of the feature under the cursor
if (ToolNum == MAP_TOOL_CHANGESTYLE) {
try {
// Need the dispatch to use the point
if (pnt.CreateDispatch(pnt.GetClsid())) {
pnt.Set(X1, Y1);
}
else {
// something went wrong, can't use the point...
AfxThrowOleException(CO_E_CLASS_CREATE_FAILED);
}

CMapXLayers layers = m_ctrlMapX.GetLayers();

// Get the USA feature under the cursor
CMapXFeatures ftrs =
layers.Item("USA").SearchAtPoint(LPDISPATCH(pnt));
// work on only the first feature
CMapXFeatureftr = ftrs.Item(1);
// get the style object from the feature
CMapXStylestyle = ftr.GetStyle();

MapInfo MapX Developer Guide v4.5 219

Chapter 13: Working With Visual C++

style.SetRegionBackColor(255);
// update the feature in the layer
ftr.Update();
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {
e->ReportError();
e->Delete();
}
}
// place a new symbol at the point clicked on
else if (ToolNum == MAP_TOOL_NEWPOINT) {
try {
CMapXLayers layers = m_ctrlMapX.GetLayers();
CMapXFeatureftr;
// Need the dispatch id to use the feature
if (ftr.CreateDispatch(ftr.GetClsid())) {
// Symbol feature
ftr.SetType(miFeatureTypeSymbol);
// Get the point object from the feature
// and call the Set method
ftr.GetPoint().Set(X1, Y1);
// Add it to the layer
layers.Item("USA").AddFeature(ftr);
}
else {
AfxThrowOleException(CO_E_CLASS_CREATE_FAILED);
}
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {
e->ReportError();
e->Delete();
}
}
}

220 MapInfo MapX Developer Guide v4.5

 Data Binding Using C++

Data Binding Using C++

The CMapXSample app has databinding examples for the following dataset types:
miDataSetDAO, miDataSetODBC, miDataSetUnbound, miDataSetGlobalHandle. The
examples also show how to use dynamic databinding, add a layer of XY points, ZIP Code
matching, and auto matching.

See the mapxsampview.cpp file to examine the examples. Below is one of the menu
command handlers for adding data from a file using the miDataSetGlobalHandle type. The
format of the data needs to be: quotes around strings, tabs between fields, and carriage
return/line feed at the end of the record. For example:

"\"NY\"\t105.34\t100\t1\r\n"
"\"MA\"\t245.19\t200\t2\r\n"
"\"NY\"\t195.0\t300\t3\r\n"
"\"AK\"\t195.0\t125\t4\r\n"
"\"CA\"\t56.453\t200\t5\r\n";
Note that this type of data binding (miDataSetGlobalHandle) is only one of several dataset
types that are supported.

The function CMapxSampleView::OnMapAdddata() handles a menu item on the Map

menu. It prompts for a filename containing data in the form specified above, reads the file,
and adds this to the map's collection of datasets.

void CMapxSampleView::OnMapAdddata()
{
:
:
CFileDialog dlgFile(TRUE, "*.txt", NULL, 0, szDataFilter,
this);

if (dlgFile.DoModal() == IDCANCEL) // User cancelled the

dialog
return;

// Read file into a string, and copy it to a global memory

buffer
:
:
// Allocate the memory buffer, copy the string into it
:
:
// Declare the variables that will be parameters to

MapInfo MapX Developer Guide v4.5 221

Chapter 13: Working With Visual C++

// DataSets.Add()
short Type;
VARIANT SourceData, Name, GeoField,
SecondaryGeoField, BindLayerName, Fields;
CString strName= "TestData";

// set up optional parameters; most will not be used

// Note: you could also use the line
//COptionalVariant SecondaryGeoField;
// instead
SecondaryGeoField.vt = VT_ERROR;
SecondaryGeoField.scode = DISP_E_PARAMNOTFOUND;

// let mapx auto detect geofield

GeoField.vt = VT_ERROR;
GeoField.scode = DISP_E_PARAMNOTFOUND;

// let mapx find which layer to bind to

BindLayerName.vt = VT_ERROR;
BindLayerName.scode = DISP_E_PARAMNOTFOUND;

// use all fields with defaults

Fields.vt = VT_ERROR;
Fields.scode = DISP_E_PARAMNOTFOUND;

// set the name of our dataset

Name.vt = VT_BSTR;
// Remember to SysAlloc() the string; it's going into a BSTR
Name.bstrVal = strName.AllocSysString();

// set up source data - no error checking on alloc

Type = miDataSetGlobalHandle;
SourceData.vt = VT_I4;
SourceData.lVal = (long)hGlobalData;
try {
// now add the dataset to the datasets collection
CMapXDataset ds = m_ctrlMapX.GetDatasets().Add(Type,
SourceData, Name, GeoField, SecondaryGeoField, BindLayerName,
Fields);
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
SysFreeString(Name.bstrVal)
}

222 MapInfo MapX Developer Guide v4.5

 Adding a Shortcut Menu Using C++

Adding a Shortcut Menu Using C++

The DISPID_MOUSEUP event allows us to add a shortcut (right mouse button) menu.
Create a menu resource for your shortcut menu (IDR_CONTEXTMENU in the sample app.)
The OnMouseUpInMap handler looks like this:

// if right mouse button, display the context menu

BOOL CMapxSampleView::OnMouseUpInMap(
short Button,short Shift,OLE_XPOS_PIXELS x,OLE_YPOS_PIXELS
y)
{
if (Button == 2) { // right button
CMenu menu; // top-level menu
CMenu *pMenu=NULL; // pop-up menu

// Load the menu resource.

menu.LoadMenu(IDR_CONTEXTMENU);

// TrackPopupMenu cannot display the top-level menu, so

get
// the handle of the first pop-up menu.
pMenu = menu.GetSubMenu(0);
if (!pMenu) {
return TRUE;
}

SetMenuDefaultItem(pMenu->m_hMenu, ID_VIEW_PROPERTIES,
FALSE);

// Display the floating pop-up menu. Track the right mouse

// button on the assumption that this function is called
// during WM_CONTEXTMENU processing.
POINT pt;
GetCursorPos(&pt);

pMenu->TrackPopupMenu(TPM_LEFTALIGN | TPM_RIGHTBUTTON,
pt.x, pt.y, this, NULL);
// Destroy the menu.
menu.DestroyMenu();
}
return TRUE;
}

MapInfo MapX Developer Guide v4.5 223

Chapter 13: Working With Visual C++

Using the Built-In Helper Dialogs from C++

Using built-in helper dialogs is easy. There is a menu item to call the MapX Properties
dialog. It can be hooked up to the handler with ClassWizard; here's what ClassWizard puts
into mapxsamp.cpp:

ON_COMMAND(ID_VIEW_PROPERTIES, OnViewProperties)
And the handler:

void CMapxSampleView::OnViewProperties()
{
// easiest way to bring up property page
try {
m_ctrlMapX.PropertyPage();
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {
e->ReportError();
e->Delete();
}
}
Note: It is not recommended that you include the property page in your finished
application. It is a great help when writing and debugging applications, but it is
not intended to be used by the end-user because it provides direct access to too
many properties and is not configurable. Use the stock dialogs (such as
LayersDlg) instead.
Similarly, the Layer Control Dialog:

void CMapxSampleView::OnViewLayercontrol()
{
try {
// mark as optional since we don't have a helpfile
COptionalVariant vHelpFile, vHelpID;

CMapXLayers layers = m_ctrlMapX.GetLayers();

layers.LayersDlg(vHelpFile, vHelpID);
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {

224 MapInfo MapX Developer Guide v4.5

 Handling MapX Exceptions Using C++

e->ReportError();
e->Delete();
}
}

Handling MapX Exceptions Using C++

MapX reports most errors by reporting (throwing) a COleDispatchException. It is important
that you catch the exceptions when calling MapX, because the default exception handler for
MFC does not catch them and your application will exit. It is also very useful to display the
description of the errors in a MessageBox. The text of the error message will help you to
determine if you are using a MapX feature improperly, or if some other problem has
occurred.
The COleDispatchException class also includes the error code in the public member
m_wCode, so that your program can identify and handle different types of errors. For a list
of error codes and their descriptions, see the MapX Error Codes.

If there is a general OLE error when trying to call MapX (as could happen if you are using an
out-of-date version of MapX.h or MapX.cpp) MFC throws a COleException. It is
recommended that you catch both exception types when calling MapX.

MapX can also (although rarely) pass errors in the Error event. This only happens if there is
some kind of error during asynchronous processing (like a redraw) that wasn’t directly
called from a MapX property or method.

Example of Exception Handling

In this example, in the Event handler of the ThemeModifyRequested event, we are
displaying the stock Theme property dialog to let the user change the theme colors, etc.
Note the exception handling.

// Note: in objects passed to events, the event handler

// does not change the reference count
// ie: do not call release on the object
void CMapxSampleView::OnThemeModifyRequested(LPDISPATCH Theme)
{
try {
CMapXTheme theme;
COptionalVariant vHelpFile, vHelpID;

MapInfo MapX Developer Guide v4.5 225

Chapter 13: Working With Visual C++

// mark as optional since we don't have a helpfile

theme.AttachDispatch(Theme, FALSE); // don't auto release

theme.ThemeDlg(vHelpFile, vHelpID);
// could decide to bring up legend dlg here instead
//CMapXLegend leg(theme.GetLegend());
//leg.LegendDlg(vHelpFile, vHelpID);
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {
e->ReportError();
e->Delete();
}
}

Creating a Map in a C++ Dialog

1. Insert MapX into the dialog.
• In the resource editor for the dialog template where you want to insert MapX,
right-click and choose ‘Insert OLE Control’ from the menu. Then choose
MapInfo MapX V4.
2. Create a CDialog derived class for the dialog.
• Highlight MapX and press Ctrl+W to bring up ClassWizard. Choose Create A
New Class if prompted, and enter a name for the dialog (the sample uses
‘CSampleDlg’). Press OK to create the SampleDlg.h and SampleDlg.cpp files.
3. Add CMapX as a member of the dialog class.
• First, #include "MapX.h" in the dialog’s header file, and then add a member
variable for MapX.
Note: Do not use Class Wizard-generated wrapper classes for MapX. They are
incomplete. Use the MapX.h and MapX.cpp files included with MapX in the
Sample40\CPP directory.

226 MapInfo MapX Developer Guide v4.5

 Creating a Map in a C++ Dialog

Create a Map in a C++ Dialog

#include "MapX.h"

/////////////////////////////////////////////////////////////
// CSampleDlg dialog

class CSampleDlg : public CDialog

{
// Construction
public:
CSampleDlg(CWnd* pParent = NULL); // standard constructor

// Dialog Data
//{{AFX_DATA(CSampleDlg)
enum { IDD = IDD_MAPXDLG };
//}}AFX_DATA
.
:
CMapX m_ctrlMapX;
.
:
};

Use DDX_Control to Link the Wrapper Class to the MapX

Control
Insert a line in the DoDataExchange method of the dialog class using DDX_Control as
follows:

void CSampleDlg::DoDataExchange(CDataExchange* pDX)

{
CDialog::DoDataExchange(pDX);
//{{AFX_DATA_MAP(CSampleDlg)
DDX_Text(pDX, IDC_STATICX, m_strX);
DDX_Text(pDX, IDC_STATICY, m_strY);
//}}AFX_DATA_MAP

// IDC_MAP1 is the ID given to the mapx control when it

// was inserted into the dialog template.
DDX_Control(pDX, IDC_MAP1, m_ctrlMapX);
}

MapInfo MapX Developer Guide v4.5 227

Chapter 13: Working With Visual C++

Use MapX Properties, Methods and Objects to Manipulate

the Map
// example use of mapx to create a temporary layer and create
// some custom mapx tools to be used later.
BOOL CSampleDlg::OnInitDialog()
{
CDialog::OnInitDialog();

try {
m_ctrlMapX.SetZoom(1000); // zoom in to 1000 miles

// create temporary layer on top for drawing on.

CMapXLayer layer =
m_ctrlMapX.GetLayers().CreateLayer("scratch
layer",NULL,1);

// make it the animation layer

m_ctrlMapX.GetLayers().SetAnimationLayer(layer);

// create some custom tools for object drawing

m_ctrlMapX.CreateCustomTool(MYTOOL_SYMBOL,
miToolTypePoint, miCrossCursor);
m_ctrlMapX.CreateCustomTool(MYTOOL_LINE, miToolTypePoly,
miCrossCursor);
m_ctrlMapX.CreateCustomTool(MYTOOL_REGION, miToolTypePoly,
miCrossCursor);
m_ctrlMapX.CreateCustomTool(MYTOOL_TEXT, miToolTypePoint,
miIBeamCursor);
m_ctrlMapX.SetCurrentTool(MYTOOL_REGION);
}
catch (COleDispatchException *e) {
e->ReportError();
e->Delete();
}
catch (COleException *e) {
e->ReportError();
e->Delete();
}
return TRUE; // return TRUE unless you set the focus to a
//control. EXCEPTION: OCX Property Pages should
// return FALSE
}

228 MapInfo MapX Developer Guide v4.5

 Creating a Map in a C++ Dialog

Use Class Wizard to Handle Events

Handling MapX events in a dialog is very easy. Just use the Class Wizard ‘Message Maps’
tab, highlight the ID for MapX (IDC_MAP1), and the Events are listed. Highlight an event
and press the ‘Add Function’ button, and Class Wizard adds the event handler and
EVENT_SINK entries to your dialog class automatically.

MapInfo MapX Developer Guide v4.5 229

Chapter 13: Working With Visual C++

230 MapInfo MapX Developer Guide v4.5

Chapter 14: MapX Tools

MapX Tools
13 Chapter

➤ Overview of Standard Tools

Most mapping applications provide an assortment
➤ Object Editing Tools
of tools to aid with common drawing tasks (such as
drawing a line on the map) and navigation tasks ➤ Node Selecting and Editing
(such as zooming in). MapX provides several ➤ Creating a Custom Tool
common mapping tools, plus you can also create
➤ Creating Polygon Drawing
your own custom tools.
Tools (Polytools)
• Overview of Standard Tools
• Object Editing Tools
• Node Selecting and Editing
• Creating a Custom Tool
Chapter 14: MapX Tools

Creating Polygon Drawing Tools (Polytools) Overview of Standard

Tools
Using Standard Tools
With MapX, you can easily incorporate common toolbar buttons into your application.
MapX provides built-in support for several common mapping tools, including:
• Navigation tools (Zoom-In, Zoom-Out, Pan, Center) that let the user change the
scale and/or position of the map.
• A Labeling tool that lets the user click a map feature to label it.
• A set of Selection tools that give the user various ways to select map features.
• Object Creation tools, which allow for the creation of new map features.
The selection tools provide built-in support for modifier keys (SHIFT key, CTRL key): Hold
down the SHIFT key while using a selection tool, and the tool de-selects features; hold down
CTRL while using a selection tool, and the tool adds features to the selection. MapX
automatically displays a different cursor whenever a modifier key is being pressed (a plus
or minus sign appears next to the cursor), so that the user will understand the effect of the
key.

Controlling Which Tool Is the Current Tool

To set which tool is being used, set the Map.CurrentTool property.

To activate one of the standard tools, set the property to one of the ToolConstants. For
example, to change the tool to the Zoom In tool:

Map1.CurrentTool = miZoomInTool
To activate a custom tool, use the ToolNumber value that you specified when you used the
CreateCustomTool method.

Map1.CurrentTool = 99

232 MapInfo MapX Developer Guide v4.5

 Creating Polygon Drawing Tools (Polytools)Overview of Standard Tools

Available Standard Tools

Different tools will enable the mouse to perform a variety of tasks. For example, if the cur-
rent tool is set to miLabelTool, when you click the mouse, it will place a label on that partic-
ular map object. The mouse cursor will change based on the tool you are using.
These are the standard tools available with MapX:

Tool Constant Description

Add Line miAddLineTool Adds a line feature to the insertion layer.

Add Point miAddPointTool Click to add a point feature to the
insertion layer.
Add Polyline miAddPolyLineTool Adds a poly-line feature to the insertion
layer.
Add Region miAddRegionTool Adds a region feature to the insertion
layer.
Arrow miArrowTool Click on title or annotations. Also, moves
or resizes selected features in editable
layers.
Center miCenterTool Click to re-center the map.
Label miLabelTool Click on a feature to label the feature.
Pan miPanTool Drag to re-center the map.
Polygon Select miPolygonSelectTool Click to draw a polygon; objects within
the polygon are selected.
Radius Select miRadiusSelectTool Drag to select features within radius.
Rect Select miRectSelectTool Drag to select features within rectangle.
Select Tool miSelectTool Click to select features.
Symbol miSymbolTool Place a symbol annotation.
Text miTextTool Place a text annotation.
Zoom In miZoomInTool Zoom In.
Zoom Out miZoomOutTool Zoom Out.

MapInfo MapX Developer Guide v4.5 233

Chapter 14: MapX Tools

Object Editing Tools

Object editing tools allow the user to create and modify features in a Map layer. There are
four standard object creation tools: Add Point, Add Line, Add Polyline, and Add Region.
These tools add the new feature to whichever layer is specified in the Layers.InsertionLayer
property. There can only be one insertion layer, and the default is none. Setting the current
tool to an object creation tool when there is no insertion layer results in an error.
MapX also supports modification of existing map features.To edit features, the
Layer.Editable property must be set to true for any layers that you wish to change. Then, the
built-in Arrow tool can be used to move or resize features in the current selection. To mov
the selected feature(s), simply click and drag in the selection. To resize the selected
feature(s), click and drag in the edit handles. To delete the selected feature(s), press the
Delete key.

Node Selecting and Editing

Node selecting and editing is functionality added to the Select Tool. This allows a user to
add, change, or delete nodes in a "noded object". That is, Node editing capabilities enable a
user to manipulate the shape of an object that has nodes.

Nodes can be selected from any selected, editable node object when the map is in "Node
Edit Mode". This includes multiple non-contiguous nodes, from multiple objects, on
multiple layers. By default, MapX is in "Feature Edit Mode". In order to select and edit
node objects, MapX must be set to "Node Edit Mode".

Note: Currently, there is NO TRANSACTION SUPPORT in node editing. Be very

careful not to unintentionally hit the delete key while nodes are selected. At this
time, there is no "Undo".

234 MapInfo MapX Developer Guide v4.5

 Node Selecting and Editing

The table below displays what objects work in Node Edit Mode:

Non-Noded objects (will

NOT work in Node Edit
Noded Objects Can Select Node Can Add Node Mode)
• point • point • line • arc
• line • line • polyline • ellipse / circle
• polyline • polyline • polygon • rectangle
• region • region • round rect
• text

Setting the Mode with the Map.FeatureEditMode property

A map object can be set to "Feature Edit Mode" or "Node Edit Mode" (it’s default is "Feature
Edit mode). In "Feature Edit Mode", selected editable objects are drawn with resize handles
(normally the 4 corners of the MBR of an object are highlighted). In "Node Edit Mode", the
nodes of objects selected for editing are drawn and only noded objects (points, lines,
polylines, regions) will display selectable nodes. Non-noded objects are simply
highlighted.
Below are the Visual Basic commands for setting the Map.FeatureEditMode propert .

Feature Edit Mode

Map1.FeatureEditMode = miEditModeFeature

Node Edit Mode

Map1.FeatureEditMode = miEditModeNode

Node Edit Mode with Move and Delete Duplicate Nodes

Map1.FeatureEditMode = miEditModeNode | miMoveDuplicateNodes |
miDeleteDuplicateNodes

Node Edit Mode and Add Node Mode

Map1.FeatureEditMode = miEditModeNode | miEditModeAddNode

MapInfo MapX Developer Guide v4.5 235

Chapter 14: MapX Tools

Node Selecting and Editing Criteria

To select nodes, the map must be in "Node Edit Mode", but not "Add Node Mode". Below
are the "rules" for selecting nodes using the Select Tool:
• Click on an unselected node to select that node. This will clear any nodes currently
selected. Alternatively, if you click on a currently selected node, other selected
nodes will not change.
• Ctrl-click to toggle between the states (selected and unselected) of the current node.
This will not affect any previously selected nodes. Use this to turn off individual
nodes, or to signal the start of a range of nodes (see "Selecting a Range of Nodes"
below).
• Shift-click specifies the end of a range of nodes. For a polygon, this would pick the
shortest range of nodes.
• Ctrl-Shift-click selects the longest range of nodes in a polygon or a region.
Note: This operation only applies to polygons of a region. It picks the range of nodes
opposite of Shift-click.
• An "Anchor Node" is defined when a user clicks or ctrl-clicks a node. That is, when
a range of nodes is selected, the current state of each node in that range is
determined by the state of the anchor node (i.e. the first node in a "path" of nodes). If
the anchor node is selected, all nodes in the range will be selected.

Selecting a Range of Nodes

This is how to select multiple ranges of nodes:
1. Click (or Ctrl-click) on a node in an object. This is the "Anchor Node" (i.e. starting
point) of the range.
2. Shift-click on another node in the object. This defines the end of the first range.
3. Ctrl-click on a third node in the object. This defines the starting, anchor node for the
second range.
4. Shift-click on a fourth node in the object. This completes the second range.
5. Repeat steps 1 & 2 for each additional range you wish to select.
In order to define a range of nodes, the start and end points must be in the same polygon or
polyline object. For poly-polygons/poly-polylines, the range can only be in a single
polygon/ polyline. Ranges can not span across objects or individual polylines/polygons
within a poly-object.

236 MapInfo MapX Developer Guide v4.5

 Node Selecting and Editing

Moving Nodes
When one or more nodes have been selected, they can be moved. To do this, click on a
previously selected node and drag it to a new location. While dragging, a dashed line
connecting all of the currently selected nodes in their new location is drawn. When the
mouse button is released, all of the selected nodes are moved to the new location. If ESC
is pressed during the dragging, the operation is aborted and all nodes return to their
original position.
After the move, all of the nodes that were moved remain selected.

Note: If any of the modified objects are poly-polygon and has it's polyids reordered, all
of the nodes will be deselected. For example, if the relative size of the polygons
change, then their order could change, which in turn will deselect all nodes.

Deleting Nodes
When one or more nodes have been selected, they may be deleted by pressing the
Delete key. After the nodes are deleted, there will not be any selected nodes. After nodes
have been deleted, if there are not enough nodes remaining to define an object of its
type, the object will be deleted. For example, a polygon requires 3 or more nodes. If 4
nodes are deleted from a polygon containing 6 nodes, that polygon will be deleted
because the 2 remaining nodes can not define a polygon.
A map must stay in "focus" in order to delete nodes. That is, if a user selects a noded
object from an editable layer while the map is in "Node Edit Mode" (one or more nodes
are selected) and then, the user clicks a control (such as a checkbox which toggles the
state of delete duplicate nodes), the map will lose focus. Therefore, when the user
presses the delete key (even though the select point tool is active and the node(s) are
selected), the node(s) will not be deleted. In order to make the delete key function
correctly, the application must set the focus to the map (call setFocus) AFTER the control
is activated.

Moving Duplicate Nodes

When moving nodes, one has the option of moving just the selected nodes, or the
selected nodes plus the duplicate nodes. (Duplicate nodes are nodes belonging to other
objects in the same layer.) When "Move Duplicate Nodes" is enabled, all nodes in the
neighboring objects in the same layer that exactly match the selected nodes will also be
moved.

MapInfo MapX Developer Guide v4.5 237

Chapter 14: MapX Tools

Deleting Duplicate Nodes

When deleting nodes, one has the option to delete just the selected nodes or the selected
nodes plus the duplicate nodes within the same layer. When "Delete Duplicate Nodes"
is enabled, all nodes in the neighboring objects in the same layer that exactly match the
selected nodes will also be deleted.

238 MapInfo MapX Developer Guide v4.5

 Creating a Custom Tool

Adding Nodes
To add nodes, the map must be in "Node Edit Mode" and "Add Node Mode". Nodes can
only be added to lines, polylines and polygons. If a node is added to a line, it is
automatically promoted to a polyline. A node can ONLY be added to a selected, editable
object. The user must click on the edge of a line, polyline or polygon object, between 2
nodes. The location of the mouse cursor when the mouse button is clicked determines
which two dashed lines the new node will be inserted between. The mouse move will
display two dashed lines representing the shape of the new object. The location of the
mouse cursor when the mouse button is released determines the location of the new
node. Pressing ESC during the dragging (before the mouse button is released) will abort
the operation and the node will not be added.

Creating a Custom Tool

Custom Tools
If you need a type of tool button that MapX does not provide, you can simply create a
custom tool by using the Map.CreateCustomTool method.

When you create a custom tool, you control which 'type' of tool you create -- in other words,
you choose whether this tool allows the user to click, or click and drag to draw a line, click
and drag to draw a rectangle, etc. You also choose which cursor appears when a custom tool
is in use.

When you create a custom tool for any application there are three generic steps:
1. Create the tool.
2. Write the tool handler (the code for what the tool actually does).
3. Use the tool (put the tool in the user’s hand).

MapInfo MapX Developer Guide v4.5 239

Chapter 14: MapX Tools

Create the Tool

To create a custom tool, call the CreateCustomTool method.

This example creates a custom Ruler tool. The purpose of the Ruler tool is to determine the
distance between two points on the map. First, we declare a constant RULERTOOLID equal
to 500 to represent our custom tool. Then, when we load the main form of the application we
create the tool.

Const RULERTOOLID = 500 ‘This goes in the General declarations.

Private Sub Form_Load()

Map1.CreateCustomTool RULERTOOLID, miToolTypeLine, miSizeCursor
End Sub
In the above call of CreateCustomTool, we specified three required parameters:
ToolNumber, Type, and Cursor. The ToolNumber is the RULERTOOLID constant we
created to represent the tool. The Type is a ToolTypeConstants value which determines the
behavior of the tool. In this case, it is miToolTypeLine which enables the user to click and
drag to draw a line using the tool. The Cursor is miSizeCursor, which means that when the
tool is selected it will appear as the size cursor.

CreateCustomTool has two optional parameters that also take a CursorConstants value.
The CursorConstants specify the cursors that you can use with a custom tool. They define
the cursor shape when your custom tool is the CurrentTool.
ShiftCursor specifies the the cursor shape of the tool when the <SHIFT> key is held down.
CtrlCursor specifies the Cursor shape when the <CTRL> key is held down. These are useful
if you want to give your tool behavior associated with those keys.

To make your custom tool the active tool, set the CurrentTool property. For example, you
could place a button on a Visual Basic form, and when the user clicks the button, you would
set the CurrentTool property.

240 MapInfo MapX Developer Guide v4.5

 Creating a Custom Tool

Available Custom Tool Types

The ToolTypeConstants describe the tool types that you can use when creating a custom
tool. They describe the tool’s behavior (e.g., miToolTypeLine lets the user draw a line;
miToolTypeCircle lets the user draw a circle; etc.).

Constant Behavior

miToolTypePoint Indicates a specific point.

miToolTypeLine Draws a line.
miToolTypeCircle Draws a circle.
miToolTypeMarquee Draws a marquee box which selects map objects
within the box.
miToolTypePoly Draws a polyline.
miToolTypePolygon Draws a polygon.

Now that the Ruler custom tool is created, we have to write the code for what the tool
actually does.

Write the Tool Handler

There are two different times at which the tool’s code may be executed: during the tool’s
use, or after the tool is used. For our custom Ruler tool we want to execute code during the
tool’s use because that’s when the work needs to be done.

The way the custom Ruler tool will operate is: when the user clicks with it on a map
location, the start point for the tool’s distance measurement will be marked. The user holds
the mouse button down and moves the mouse across the map, then stops the mouse at
another location. This will mark the end point of the tool’s distance measurement. The Ruler
tool calculates the distance between the two points. To do this, we need to execute code for
the Ruler tool when the user holds the mouse button down, and when the user moves the
mouse across the map and stops at another spot. To capture the start point when the user
clicks down, we write code in the MouseDown event:

Dim XDown As Double

Dim YDown As Double

Private Sub Map1_MouseDown(Button As Integer, _

Shift As Integer, X As Single, Y As Single)

If Map1.CurrentTool = RULERTOOLID And Button = vbLeftButton _

MapInfo MapX Developer Guide v4.5 241

Chapter 14: MapX Tools

Then
Map1.ConvertCoord X, Y, XDown, YDown, miScreenToMap
End If
End Sub
When the user clicks down on the mouse, the MouseDown event is fired. The code in the
MouseDown event takes the X,Y point where the user clicked, then converts it from screen
coordinates to map coordinates, and stores it in the global variable Xdown and Ydown.
Xdown and Ydown represent the start point of our distance measurement.

To capture the end point when the user moves the mouse across the map and stops at
another spot, we write code in the MouseMove event:

Private Sub Map1_MouseMove(Button As Integer, _

Shift As Integer, X As Single, Y As Single)

If Map1.CurrentTool = RULERTOOLID And Button = vbLeftButton _

Then
Dim MapCoordX As Double, MapCoordY As Double
Map1.MapUnit = miUnitMile
Map1.ConvertCoord X, Y, MapCoordX, _
MapCoordY, miScreenToMap
fMainForm.sbStatusBar.SimpleText = Map1.Distance(XDown, _
YDown, MapCoordX, MapCoordY) & " miles"
End If
End Sub
This code will continually execute until the user stops moving the mouse and releases the
mouse button. The last time this code executes is for the last point on the map before the
mouse stops moving, which is the end point of our distance measurement. We convert the
point from screen to map coordinates and then use the Distance method of the Map object to
calculate the distance between the two points. The result is displayed in the status bar of the
form.

ToolUsed Event
There are many times when you may want to execute a tool’s code after the tool is used. An
example of this is to allow the user to draw a circle and when the mouse button is released,
compute the number of customers inside that radius. If this is the functionality the tool
needs, use theToolUsed event of the Map object to place your code.

242 MapInfo MapX Developer Guide v4.5

 Creating Polygon Drawing Tools (Polytools)

Put the Tool in the User’s Hand

To "put the tool in the user’s hand", set the CurrentTool property of the Map object to the
tool:

Map1.CurrentTool = miZoomInTool
-or-

Map1.CurrentTool = 99

Creating Polygon Drawing Tools (Polytools)

A polytool is a tool that lets the user click repeatedly—for example, to draw a polygon or
polyline.

Standard Polytools
MapX provides a standard polygon selection tool. This tool allows the user to draw a
polygon, then selects all features whose centroids fall within the polygon. Only selectable
layers are searched. Seamless, Raster, and Userdraw layers are ignored.

To activate this tool, set the CurrentTool property to miPolygonSelectTool (value: 1010).
When this tool is used, the PolyToolUsed event is fired. If the user ends the polygon
(miPolyToolEnd) with a double-click, space, or return, the search is performed, and
miPolyToolEnd (1) is passed to the PolyToolUsed event. If the user ends the polygon with
the ESC key, the search is cancelled; miPolyToolEndEscaped (2) is passed to the PolyToolUsed
event. The user can delete all nodes of a line (backspace Delete). When the last node is
deleted, it will send a (2) flag.

Custom Polytools
To create a custom polytool, call the CreateCustomTool method, and specify a
ToolTypeConstants value of miToolTypePoly.

To make your custom polytool the active tool, set the CurrentTool property.

Whenever the user selects your custom polytool and uses it on the map, MapX calls the
PolyToolUsed event. Therefore, you need to add code to the PolyToolUsed event procedure
to make your tool have an effect.

MapInfo MapX Developer Guide v4.5 243

Chapter 14: MapX Tools

244 MapInfo MapX Developer Guide v4.5

Chapter 15: Exporting Maps
14 Chapter

➤ Methods for Exporting

Exporting Maps Maps
➤ ExportSelection Property
Often, the user may need to print out a map or
➤ Printing Maps
incorporate the visual image of the map in another
application. MapX has methods which allow you
to send the contents of a map to the clipboard, to
the printer, or to a graphics file.
Chapter 15: Exporting Maps

Methods for Exporting Maps

To export a map to a graphics file or copy a map’s contents to the clipboard, you would use
the ExportMap method.

Method Description Code Sample

ExportMap Exports a map to a Map1.ExportMap “C:\Map.TIF”,miFormatTIF

graphics file.
ExportMap Exports a map to the Map1.ExportMap “clipboard”
clipboard.

Note: Optional parameters are in [square brackets]

OBJECT.ExportMap (Location, Format, [W], [H])

Part Description

Location File specification of the place to put the output. If the keyword
‘CLIPBOARD’ is used, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value.
W Width of output. This is a double value, and specifies width in
terms of Paper Units (Map.PaperUnit). This is an optional
parameter, and if not specified, Map.MapPaperWidth is used.
H Height of output. This is a double value, and specifies height in
terms of Paper Units (Map.PaperUnit). This is an optional
parameter, and if not specified, Map.MapPaperHeight is used.

246 MapInfo MapX Developer Guide v4.5

 ExportSelection Property

Format Constants
Format Description

miFormatWMF Metafile
miFormatBMP Bitmap
miFormatJPEG JPEG image
miFormatTIF TIF
miFormatGIF GIF Image
miFormatPNG Portable Network Graphics
miFormatPSD PhotoShop

'This sample demonstrates the Map.ExportMap method. It uses

'the method to place a map in the clipboard as a BMP.
Map1.PaperUnit = miUnitCentimeter

'Export a 12 cm by 9 cm map to the clipboard in BMP Format

Map1.ExportMap "clipboard", miFormatBMP, 12, 9

ExportSelection Property
Utilizing the ExportSelection property of the map will allow you to control whether the
selection pattern will export with the map. Look at the code sample to how this property
property is used:

'Export a jpg image for display and include the selection

highlighting in the image
Map1.ExportSelection=True
Map1.ExportMap "c:\temp\map.jpg", miFormatJPEG

MapInfo MapX Developer Guide v4.5 247

Chapter 15: Exporting Maps

Printing Maps
To print a map, use the PrintMap method.

Note: The current map is drawn to fit the rectangle given. Best results are obtained
when the aspect ratio of width to height is maintained. This method only prints
out the contents of the MapX map; it doesn’t show any icons, toolbars, or menu
items. You may want to print the form that contains the MapX control if you need
to see additional controls on your output.

Method Description Code Sample

PrintMap Prints the map. Map1.PrintMap Printer.hDC, 0, 0, Map1.Width * 100,

Map1.Height * 100

OBJECT.PrintMap (hDC, x, y, w, h)

Parts Description

hDC Printer device context. Can be any device context.

x Upper left corner X in HIMETRIC units.
y Upper left corner Y in HIMETRIC units.
w Width in HIMETRIC units.
h Height in HIMETRIC units.

248 MapInfo MapX Developer Guide v4.5

Chapter 16: Distributing Your MapX Application
15 Chapter

➤ MapX Customer
Distributing Your MapX Installation
➤ Installing the MapX OCX
Application
➤ Installing Support for
Spatial Server Access
The MapX product you have purchased from
MapInfo is a developer's kit. It contains the MapX ➤ Installing Raster Format
OCX, sample programs, an on-line help system, Handlers
sample maps and geosets, and various utilities and ➤ Installing Maps and
other support files. This chapter deals with Geosets
distributing your MapX application(s) to your ➤ Adding Keys to the
customers. Please be reminded that you must Windows Registry
purchase a Use License (i.e., seat) as evidenced by a ➤ Passing in the MapX
MapInfo License certificate for each user of each license String
application that you distribute with MapX
➤ Redistributing Your MapX
functionality as described in the MapInfo Standard Application With MrSID
License/Development Environments, which is
included in your product packaging.
Chapter 16: Distributing Your MapX Application

MapX Customer Installation

Providing MapX Control (i.e. the piece of MapX that needs to be distributed within your
applications in order for them to work properly) in your MapX applications can be a
difficult task for the inexperienced programmer due to the high number of dependent files
and their complex structure. Therefore, MapInfo Corporation has begun automating the
distribution process. Basically, there are two methods of distributing the MapX Control with
your MapX applications. They are:

• Use the MapX OCX Installer that is provided on the MapX CD. This is the easiest
method of distribution as it entails very little effort on the part of a MapX developer
because certain procedures and tasks are automated.
• Integrate MapX control at runtime within the application you wish to distribute.
This method of distribution is labor intensive and requires a substantial level of
detail orientation, but provides programmers with the highest degree of control and
customizing capabilities possible.

Using the MapX OCX Installer to Distribute the MapX Control

Basically there are only two steps needed to provide Map Control via the OCX Installer.
They are:
1. Select the MapX OCX Installer files located in [CD]\MapXtras\MapXRuntime on.
This will automatically install the MapX mapping engine and the Geoset Manager.
The default installation location is: Program Files\Common Files\MapX Common.
2. Make sure all licensing agreements with MapInfo Corporation and data providers
are appropriately adhered to.

Example of Using the MapX OCX Installer

MapXOcxPath = SRCDISK ^ MAPX_OCX_CD_PATH;
// launch the MapXocx setup
if (Is(FILE_EXISTS, MapXOcxPath ^ "setup.exe")) then

// Display a message to the user about us setting up the

DAO
SdShowMsg (@MSG_OCX_MESSAGE, TRUE);

ChangeDirectory(MapXOcxPath );
LaunchAppAndWait(MapXOcxPath^"setup.exe","",WAIT)
// Done setting up, remove sessage
SdShowMsg (@MSG_OCX_MESSAGE, FALSE);
endif;

250 MapInfo MapX Developer Guide v4.5

 MapX Customer Installation

Files Installed Automatically with the Installer OCX

These files are automatically installed when the OCX Installer method of adding Map
Control is used. These files are installed to:
C:\Program Files\Common Files\MapInfo Shared\MapX Common\

mdatasetint.tlb MMapXColumnInfo.dll mirdbspatialRes.dll

AllTypeRes.dll ColLookupSystem.dll CommandProcessor.dll
CommandProcessorRes.dll COMPILER.DLL COORDSYS.DLL
CoordSysRes.dll CustomProperties.dll DAENGINE.DLL
DAEngineRes.dll DBINFO.DLL DBInfoRes.dll
DBLAYER.DLL DBLayerRes.dll ExprPacket.dll
ExprPacketCreator.dll ExprPacketCreatorRes.dll ExprPacketRes.dll
FcnInfoServer.dll FcnInfoServerres.dll GEO.DLL
GeoObject.dll GeoObjectRes.dll GEOSET.DLL
GeosetManager40.exe GeosetManagerIntl40.dll GeosetRes.dll
LEGEND.DLL LegendRes.dll LEXER.DLL
LEXERRES.DLL MapBasicInternalFcn.dll MapBasicInternalFcnres.dll
MAPINFOW.PRJ MAPPER.DLL MapperRes.dll
MAPX.ABB MAPX.PEN METADATA.DLL
MIDLG40.DLL MIDLIN40.DLL MIRDB.DLL
MIRDBRES.DLL mirdbspatial.dll ALLTYPE.DLL
PROGRAM.DLL ProgramRes.dll RASTER.DLL
RasterRes.dll REGSVR32.EXE RegTypLib.exe
STYLES.DLL TextFileReader.dll TextFileReaderRes.dll
Thematics.dll TOKENS.DLL UTILITY.DLL
UtilityRes.dll FIND.DLL FINDRES.DLL
GeoDictionaryManager40.e GeoDictionaryManagerIntl40.dll MIGEOREG.DLL
xe
Mapinfow.fnt Mxintl40.dll Tools.dll
ThematicsRes.dll RegisterDS4.exe GEORES.DLL
ALASKA.LAS ALASKA.LOS CONUS.LAS
CONUS.LOS HAWAII.LAS HAWAII.LOS

MapInfo MapX Developer Guide v4.5 251

Chapter 16: Distributing Your MapX Application

PRVI.LAS PRVI.LOS STGEORGE.LAS

STGEORGE.LOS STLRNC.LAS STLRNC.LOS
STPAUL.LAS STPAUL.LOS MAPX40.OCX
CUSTSYMB\ CUSTSYMB\YIEL2-32.BMP CUSTSYMB\BADG1-
32.BMP
CUSTSYMB\BADG2- CUSTSYMB\BANK1-32.BMP CUSTSYMB\BANK2-
32.BMP 32.BMP
CUSTSYMB\BOOK1- CUSTSYMB\CAMP1-32.BMP CUSTSYMB\CAR1-
32.BMP 32.BMP
CUSTSYMB\CAUT1- CUSTSYMB\CHUR1-32.BMP CUSTSYMB\COMP1-
32.BMP 32.BMP
CUSTSYMB\FARM1- CUSTSYMB\FAST1-32.BMP CUSTSYMB\FIRE1-
32.BMP 32.BMP
CUSTSYMB\GLOB1- CUSTSYMB\GOLF1-32.BMP CUSTSYMB\HOSP1-
32.BMP 32.BMP
CUSTSYMB\HOUS1- CUSTSYMB\HOUS2-32.BMP CUSTSYMB\HOUS3-
32.BMP 32.BMP
CUSTSYMB\HYDR1- CUSTSYMB\INTE1-32.BMP CUSTSYMB\LITE1-
32.BMP 32.BMP
CUSTSYMB\LITE2- CUSTSYMB\MAIL1-32.BMP CUSTSYMB\MBOX1-
32.BMP 32.BMP
CUSTSYMB\MBOX2- CUSTSYMB\MOSQ1-32.BMP CUSTSYMB\ONEW1-
32.BMP 32.BMP
CUSTSYMB\ONEW2- CUSTSYMB\PENC1-32.BMP CUSTSYMB\PIN1-32.BMP
32.BMP
CUSTSYMB\PIN2-32.BMP CUSTSYMB\PIN3-32.BMP CUSTSYMB\PIN4-32.BMP
CUSTSYMB\PIN5-32.BMP CUSTSYMB\PIN6-32.BMP CUSTSYMB\POLI1-
32.BMP
CUSTSYMB\RAIL1- CUSTSYMB\RAIL2-32.BMP CUSTSYMB\RAIL3-
32.BMP 32.BMP
CUSTSYMB\REST1- CUSTSYMB\STAT1-32.BMP CUSTSYMB\STOP1-
32.BMP 32.BMP
CUSTSYMB\SYNA1- CUSTSYMB\TARG1-32.BMP CUSTSYMB\TAXI1-
32.BMP 32.BMP
CUSTSYMB\TEMP1- CUSTSYMB\TOWE1-32.BMP CUSTSYMB\TOWE2-
32.BMP 32.BMP

252 MapInfo MapX Developer Guide v4.5

 MapX Customer Installation

CUSTSYMB\TRAF1- CUSTSYMB\TRUC1-32.BMP CUSTSYMB\TRUC2-

32.BMP 32.BMP
CUSTSYMB\YIEL1- CUSTSYMB\AMBU1-32.BMP
32.BMP

Integrating MapX into Applications at Runtime

When you deliver your application to customers, you will need to install:

• The software you created

• MapX Control (Either via the MapX OCX Installer –OR– your own, customized
version)
• Related support files
• Maps and geosets that are used by your application
Ideally you will incorporate the installation of MapX into your installation procedure, so
that your end user won’t need to perform a separate installation to install MapX.
There are four main steps to installing and distributing MapX applications:
1. Install the necessary files onto your user's computer.
2. Run utilities (such as regsvr32.exe) to register specific files on the user's system.
3. Add specific keys to the Windows registry
4. Pass in the MapX license string at application runtime.
Note: If you are using MapX in a dialog with Visual C++, VisualBasic, Delphi, or
PowerBuilder they will take care of creating MapX with the correct license string
and therefore you can skip this section. If you are creating the MapX control using
the CMapX::Create() method in Visual C++ you do need to take this extra step.
The files that are installed with MapX can be divided into the following categories:

Required files:

• MapX OCX and its dependent DLLs

• Windows system files: including fonts, MFC, and OLE dlls
Optional files:
• Dataset drivers (used for databinding)
• Import/Export raster handlers
• Maps and Geosets
The Installshield sample provided on the MapX Installation CD only illustrates how to
install the required files. This chapter will cover installation requirements for the required
files and the optional files.

MapInfo MapX Developer Guide v4.5 253

Chapter 16: Distributing Your MapX Application

Installing the MapX OCX

If you have installed MapX on your own computer, it’s easy to get a rough idea of how
many files are used by MapX. In previous versions of MapX, all of the files were installed
under the old MapX program directory (which defaults to \Program Files\MapInfo\MapX
4.0\Program). MapX v4.0 and later installs the program files under the following path
“\Program Files\Common Files\MapInfo Sharred\MapX Common”. This directory
should be used for the MapX required files, whereas all of the files necessary for your
application should go under a directory meaningful to the end-user and your specific
application.

Note: MapX uses some files that are not located in the MapX program directory. For
example, MapX uses MFC and OLE dlls that reside in the Windows System
directory.
We also recommend that the MapX common directory should be: \Program Files\Common
Files\MapInfo Sharred\MapXCommon.

The following table describes what files need to be installed and where they should be
installed to.

Where to Install
Other Special
Files Files
Requirements

Mfc42.dll, msvcp60.dll, msvcrt.dll \Windows\System Do a version check befor

replacing these files. If older
version, during replace files
may be in use and require a
reboot if that is the case.
Olepro32.dll, oleaut32.dll \Windows\System Must be registered using
regsvr32.exe
Mapx40.ocx MapX common Must be registered using
directory regsvr32.exe. Prior to
registering the OCX, make
sure the MapX dependent
files are installed.
MMapXColumnInfo.dll MapX common Must be registered using
directory regsvr32.exe
mdatasetint.tlb MapX common Must be registered using
directory regtyplib.exe

254 MapInfo MapX Developer Guide v4.5

 Installing the MapX OCX

Where to Install
Other Special
Files Files
Requirements

MapX dependent files: MapX common

ALLTYPE.DLL, AllTypeRes.dll, directory
ColLookupSystem.dll,
CommandProcessor.dll,
CommandProcessorRes.dll,
COMPILER.DLL, COORDSYS.DLL,
CoordSysRes.dll,
CustomProperties.dll,
DAENGINE.DLL, DAEngineRes.dll,
DBINFO.DLL, DBInfoRes.dll,
DBLAYER.DLL, DBLayerRes.dll,
ExprPacket.dll,
ExprPacketCreator.dll,
ExprPacketCreatorRes.dll,
ExprPacketRes.dll, FcnInfoServer.dll,
FcnInfoServerres.dll, FIND.DLL,
FINDRES.DLL, GEO.DLL,
GeoDictionaryManager40.exe,
GeoDictionaryManagerIntl40.dll,
GeoObject.dll, GeoObjectRes.dll,
GEOSET.DLL, GeosetManager40.exe,
GeosetManagerIntl40.dll,
GeosetRes.dll, LEGEND.DLL,
LegendRes.dll, LEXER.DLL,
LEXERRES.DLL,
MapBasicInternalFcn.dll,
MapBasicInternalFcnres.dll,
Mapinfow.fnt, MAPINFOW.PRJ,
MAPPER.DLL, MapperRes.dll,
MAPX.ABB, MAPX.PEN,
METADATA.DLL, MIDLG40.DLL,
MIDLIN40.DLL, MIRDBRES.DLL,
Mxintl40.dll, PROGRAM.DLL,
ProgramRes.dll, RASTER.DLL,
RasterRes.dll, REGSVR32.EXE,
RegTypLib.exe, STYLES.DLL,
TextFileReader.dll,
TextFileReaderRes.dll, Thematics.dll,
TOKENS.DLL, Tools.dll,
UTILITY.DLL, UtilityRes.dll,
ThematicsRes.dll, GeoRes.dll

MapInfo MapX Developer Guide v4.5 255

Chapter 16: Distributing Your MapX Application

Where to Install
Other Special
Files Files
Requirements

MapX font files; Windows\Fonts These fonts have to be

ARIAL.TTF, MAPIS___.TTF, directory installed and registered with
MAPSYM.TTF, TTMIAR__.TTF, the operating system. Please
TTMICG__.TTF, TTMIMI__.TTF, see below for
TTMIOG__.TTF, TTMIOS__.TTF, moreinformation.
TTMIRE__.TTF, TTMITC__.TTF,
TTMIWE__.TTF
Nadcon support files: MapX common Only required if using layers
ALASKA.LAS, ALASKA.LOS, directory with the NAD 27 and NAD
CONUS.LAS, CONUS.LOS, 83 coordinate systems.
HAWAII.LAS, HAWAII.LOS,
PRVI.LAS, PRVI.LOS,
STGEORGE.LAS, STGEORGE.LOS,
STLRNC.LAS, STLRNC.LOS,
STPAUL.LAS, STPAUL.LOS

256 MapInfo MapX Developer Guide v4.5

 Installing the MapX OCX

Where to Install
Other Special
Files Files
Requirements

Bitmap symbols: Underneath the Only required if using

TOWE1-32.BMP, POLI1-32.BMP, MapX common custom bitmap symbols.
MBOX2-32.BMP, GOLF1-32.BMP, directory, in a
TOWE2-32.BMP, RAIL1-32.BMP, directory called
MOSQ1-32.BMP,HOSP1-32.BMP, Custsymb. For
IEL2-32.BMP, RAIL2-32.BMP, example: \Program
ONEW1-32.BMP, HOUS1-32.BMP, Files\Common
ADG1-32.BMP, ONEW2-32.BMP, Files\MapInfo
HOUS2-32.BMP,ADG2-32.BMP, Shared\MapX
HOUS3-32.BMP,ANK1-32.BMP, Common\Custsymb
ANK2-32.BMP,OOK1-32.BMP,
AMP1-32.BMP, TRAF1-32.BMP, AR1-
32.BMP,TRUC1-32.BMP, RAIL3-
32.BMP,AUT1-32.BMP, TRUC2-
32.BMP,REST1-32.BMP, PENC1-
32.BMP,HUR1-32.BMP, YIEL1-
32.BMP,STAT1-32.BMP, PIN1-
32.BMP,HYDR1-32.BMP, AMBU1-
32.BMP,STOP1-32.BMP,PIN2-32.BMP
INTE1-32.BMP,COMP1-32.BMP,
SYNA1-32.BMP,PIN3-32.BMP, LITE1-
32.BMP,FARM1-32.BMP, TARG1-
32.BMP,PIN4-32.BMP, LITE2-32.BMP
FAST1-32.BMP,TAXI1-32.BMP, PIN5-
32.BMP,MAIL1-32.BMP, FIRE1-
32.BMP,TEMP1-32.BMP, PIN6-
32.BMP,MBOX1-32.BMP, GLOB1-
32.BMP
The sample Installshield program installs the above files. The sample can be found on the
MapX SDK CD.
MapX also uses some TrueType fonts. These font files (*.ttf) must be copied to Window’s
Font Folder.

MapInfo MapX Developer Guide v4.5 257

Chapter 16: Distributing Your MapX Application

Fonts must also be registered with Windows. If you are using a third-party software
package to create your installer, that package might handle font registration for you.
Otherwise, you can register fonts manually, by calling the Win32 AddFontResource routine.
Once a font is properly registered, the registry contains a corresponding key under:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts
or
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Fonts

Installing Support for Spatial Server Access

If accessing data in a spatially enabled RDBMS like SpatialWare for Oracle, Informix, or DB2
or Oracle 8i Spatial, then the drivers below are needed.

Spatial Server Dataset drivers Installation requirements

SpatialWare Miodbc.dll, mirdb.dll, Odbc32.dll must exist in system

MapInfo mirdbspatialres.dll, path
ODBC mirdbspatial.dll,
mirdbspatialres.dll
Oracle 8i Spatial Mioci.dll, mirdb.dll, Odbc32.dll must exist in system
mirdbspatialres.dll path

Registering Files and Installing Dataset Drivers

As mentioned in the preceding table, some files need to be ‘registered’. Most of the files that

need to be registered can be registered by running the utility regsvr32.exe:

• regsvr32 /s <filespec of mapx.ocx>
• regsvr32 /s <filespec of olepro32.dll>
• regsvr32 /s <filespec of oleaut32.dll>
If your application uses the ODBC data driver, you must register MODBCDataset.dll and
MMapXColumnInfo.dll. If your application uses the Notes data driver, you must register
MNotesDataset.dll and MMapXColumnInfo.dll. If your application uses either the ODBC or
the Notes data driver, you must register the type library as follows:

regtyplib <filespec of mdatasetint.tlb>

258 MapInfo MapX Developer Guide v4.5

 Installing Support for Spatial Server Access

MapX allows you to bind data to a map layer. Please see, "Putting Your Data on the Map"
for additional information.

Note: All of these dataset drivers should be installed in the same directory as the MapX
OCX, which is usually found in the MapX common directory: \Program
Files\Common Files\MapInfo Shared\MapX Common
This table illustrates the various options for data binding and what the installation
requirements are. All of the files below must be registered with ressup32.exe.

Dataset source type

Dataset drivers Installation requirements

Lotus Notes Mnotesdataset.dll Notes dataset driver requires

nnotes.dll to be locateable through
the system path.
ODBC Modbcdataset.dll Odbc32.dll must exist in system
path
Delphi v3 MgenDSetDrvr.dll, Delphimm.dll must exist in system
DSLIBP.DLL path
Delphi v4 MgenDSetDrvr.dll, Borlndmm.dll must exist in system
Dslibp4.dll path
Safe Array MsafeArrayDataset.dll
ADO v2.0 MapXADODS.dll, ATL.dll ADO must be installed.
RDO v2.0 MapXRDODS.dll, ATL.dll RDO must be instaled.

MapInfo MapX Developer Guide v4.5 259

Chapter 16: Distributing Your MapX Application

Installing Raster Format Handlers

MapX also allows the developer to incorporate raster images into their application. A MapX
application may open or write to various raster image types. The appropriate drivers must
be included when distributing your application.

MapX can use one of many different libraries to load a raster image. When a raster image is
loaded by MapX, it will search for these DLLs and ask them if the given file can be read by
that DLL. Once one answers yes, MapX knows which DLL will be doing format handling
for the file. The Format handlers will be named "xxxxxxxx.RHx". The base part of the name
is based on the format. The extension always begins with RH, but can end in any letter (A-
Z). When searching for a format handler, MapX starts with RHA, then RHB, and so forth
until RHZ. This allows MapX to prioritize which handlers are used. For example, SPOT
files need to be checked for before any other formats since they are just raw data that can be
confused with other formats. The SPOT handler's extension is RHD. The Halo format
handlers (the standard built in ones) are named RHV. The Lead Tools are named RHX.

The LEADTOOLS Win32 Pro provided by ©LEAD Technologies, Inc and HALO Imaging
libraries provided by Media Cybernetics are included with MapX.You may use either of
these to display most raster files in MapX. LeadTools will load the entire raster image into
memory at the time the image is referenced in MapX. This will mean that the image will
take longer to load, but panning and zooming will be faster. HALO will only load what it
needs to display into memory, so it will load the image faster, but panning and zooming will
be slower. By default, HALO will be attempted first. You may change this order by either
not including the HALO libraries when distributing your application, or by renaming the
LeadTools handler from a .rhx to a .rhu or anything else not used before the letter “x”. There
may also be some formats which are not supported by either library and therefore will have
their own separate library.

Note: All of these raster handlers should be installed in the same directory as the MapX
OCX, which is usually found in the MapX common directory: \Program
Files\Common Files\MapInfo Shared\MapX Common.

260 MapInfo MapX Developer Guide v4.5

 Installing Raster Format Handlers

Here is a list of handlers included with MapX:

Supported raster types

Format Handler Required files and DLL’s needed
All raster types Migeoreg.dll, MIRASTER.DLL
Lead Tools LTFIL70N.DLL, LTKRN70N.DLL, JPG-LFCMP70N.DLL,
leadtool.rhx GIF-LFGIF70N.DLL,
TIF-LFTIF70N.DLL,
LFFAX70N.DLL
PNG- LFPNG70N.DLL,
PSD- LFPSD70N.DLL,
WMF-LFWMF70N.DLL,
BMP-LFBMP70N.DLL
Halo Libraries Halo.rhv, mihiffl.dll BMP-miffbmp.dll,
GIF-miffgif.dll,
JPG-miffjpeg.dll,
PCX-miffpcx.dll,
TARGA-mifftga.dll,
TIF-mifftiff.dll
TIF TIFF.RHL Or you may use the TIF
library provided by Lead
Tools or Halo.
SPOT Spot.rhd
MRSID Mrsid.rhe SID-MRSID32.DLL
All Grid types MIGRID.DLL, MIRASTER.DLL
MapInfo GRID and MIG.GHL MIG-GRIDDLL.DLL
Hillshading

MapInfo MapX Developer Guide v4.5 261

Chapter 16: Distributing Your MapX Application

Installing Maps and Geosets

Registering a geoset is a convenient way of registering each MapInfo table associated with
that geoset into the GeoDictionary. By registering a MapInfo table in the GeoDictionary, that
table can be used for autobinding. To get more information regarding autobinding, please
see "Putting Your Data on the Map".

If it is determined that you need to use the GeoDictionary, when you register a geoset,
GeoDictionaryManager40.exe adds appropriate entries into the Geodictionary (geodict.dct).
If the Geodictionary does not exist, GeoDictionaryManager40.exe creates one.

This step must be done after all of the Geosets and associated tables are installed on the
user’s machine. Double check your geoset to see what the expected paths are for each table.
For example, if you created a geoset using MapInfo tables on different areas of your hard
drive, the geoset will specify the full path to anything not in the same directory as the
geoset. If redistributing this geoset, the tables will have to be found in the same paths as the
original geoset. To avoid this problem, copy all MapInfo tables into the same directory prior
to creating the geoset. Then create the geoset in that same directory.

262 MapInfo MapX Developer Guide v4.5

 Adding Keys to the Windows Registry

Adding Keys to the Windows Registry

MapX also uses the following three registry keys (which your installer must create on the
end-user's system, if they do not exist already). The MapX installer creates these three keys
when you install MapX on your system. Therefore, if you want to see what these registry
keys should look like, view your system's registry using a utility such as regedit.exe.

Key Description

HKEY_LOCAL_MACHINE\Software\_ String - The GeoDictionary key has the

MapInfo\MapX 4.0\GeoDictionary file specification for the geodictionary file.
Example: C:\Program
Files\myappdir\Maps\GeoDict.DCT
HKEY_LOCAL_MACHINE\Software\_ String - The SearchPaths key has
MapInfo\MapX 4.0 \SearchPaths semicolon-delimited file specifications of
where map files and geosets may exist; it
defaults to an empty string ("") other than
in the directory specified in the
GeoDictionary key.
HKEY_LOCAL_MACHINE\Software\_ String - Has the location of the folder
MapInfo\MapX 4.0\ CommonDLLDir where the OCX and support files are
Located. Example: \Program
Files\Common Files\MapInfo
Shared\MapX Common

Note: The GeoDictionary path is used when adding a geoset to the MapX object
without specifying the full path of the Geoset and when using autobinding. In
addition, the SearchPaths key is not necessary if not using the GeoDictionary. See
“Installing Maps and Geosets” to determine whether or not these keys are
necessary for your application.

MapInfo MapX Developer Guide v4.5 263

Chapter 16: Distributing Your MapX Application

Passing in the MapX License String

In order to instantiate a runtime version of MapX on your user’s computer, the license string
must be passed in at the time of object creation during the executing of your application.

Note: If you are using MapX in a dialog with Visual C++, VisualBasic, Delphi, or
PowerBuilder they will take care of creating MapX with the correct license string
and therefore you can skip this section. If you are creating the MapX control using
the CMapX::Create() method in Visual C++ you do need to take this extra step.

Visual C++
Again, if using MapX in a dialog in Visual C++, you do not need to perform this step.

In order to successfully create the MapX object, you must pass the license string as the
bstrLicKey parameter to CMapx::Create().

Redistributing Your MapX Application with

MrSID
In the event Licensee wishes to deploy an application which supports the MrSID file format
(*.sid), Licensee shall include the following text:

MrSID software (specifically the mrsid32.dll) is used under license and is Copyright ©
1995-99, LizardTech, Inc., 1008 Western Ave., Suite 200, Seattle, WA 98104. All rights
reserved. MrSID is protected by U.S. Patent No. 5,710,835. Foreign patents are pending.
Unauthorized use or duplication prohibited.
Patented technology in the Software was developed in part through a project at the Los
Alamos National Laboratory, funded by the U.S. Government and managed by the
University of California. The U.S. Government has reserved rights in the technology,
including a non-exclusive, nontransferable, irrevocable, paid-up license to practice or
have practiced throughout the world, for or on behalf of the United States, inventions
covered by the patent, and has other rights under 35 U.S.C. § 200-212 and applicable
implementing regulations. For further information, contact Lizardtech.

264 MapInfo MapX Developer Guide v4.5

 Part II:
The MapX Objects
266 MapInfo MapX Developer Guide v4.5
Affine Transform object

An AffineTransform object allows you to define rotated or skewed coordinate systems.

Object Properties
• AffineTransform.A, B, C, D, E, F properties
• AffineTransform.Units property

Object Methods
• AffineTransform.Set method

Remarks
All properties are read-only. To modify the AffineTransform object, use the Set method.

To obtain an AffineTransform object, reference the CoordSys object's AffineTransform

property, or declare a new, stand-alone Affine Transform object.

See Also
For an introduction to affine transformations, see"Using Coordinate Systems" .

AffineTransform.A, B, C, D, E, F properties (AffineTransform object)

Purpose
These are read-only properties, representing the parameters of an affine transformation;
return double values.

Remarks
An affine transformation has the following form:
x' = Ax + By + C
y' = Dx + Ey + F
In these equations, the base coordinates (x,y) are transformed to produce the derived
coordinates (x', y'). The six constants A through F determine the effect of the transformation,
as follows:

A Performs scaling or stretching along X axis.

B Performs rotation or skewing along X axis.
C Performs shifting along X axis.
D Performs rotation or skewing along Y axis.
E Performs scaling or stretching along Y axis.
F Performs shifting along Y axis.
These properties are all read-only; to set the properties, use the Set method.
Affine Transform object

AffineTransform.Set metho (AffineTransform object)

Purpose
This method sets the properties of an affine transformation.

Syntax
OBJECT.Set UNITS [A, B, C, D, E, F ]

Part Description

OBJECT An AffineTransform object.

UNITS A MapUnitConstants value, such as miUnitMeter (7).
A Double value; performs scaling or stretching along X axis.
B Double value; performs rotation or skewing along X axis.
C Double value; performs shifting along X axis.
D Double value; performs scaling or stretching along Y axis.
E Double value; performs rotation or skewing along Y axis.
F Double value; performs shifting along Y axis.

Remarks
All arguments are required.

An affine transformation has the following form:

x' = Ax + By + C
y' = Dx + Ey + F
In these equations, the base coordinates (x,y) are transformed to produce the derived
coordinates (x', y').

AffineTransform.Units property (AffineTransform object)

Purpose
This is a read-only property that specifies the map units used by an affine transformation. It
returns a short value matching one of the MapUnitConstants.

268 MapInfo MapX Developer Guide v4.5

Annotation Object and Annotations Collection

Each Map has a collection of Annotations (Map.Annotations property). Annotations are either
symbol or text objects, and are drawn on top of the map.
Annotations are typically used to add messages (text) to a map or to put symbols on a map.
These annotations will scale with the map as you zoom in and out. They are not necessarily
associated with a particular layer of the map and are always on top.

Note that the Annotation object has no properties for setting the position, symbol style, or text.
To control these aspects of an annotation, use the Annotation.Graphic property to obtain a
Graphic object, then modify it.

Object Properties
• Annotation.Graphic property
• Annotation.Type property

Collection Properties
• Annotations.Count property
• Annotations.Editable property
• Annotations.Item property

Collection Methods
• Annotations.ActiveAnnotation method
• Annotations.AddSymbol method
• Annotations.AddText method
• Annotations.Remove method
• Annotations.RemoveAll method

See Also
Map object

Annotation.Graphic property (Annotation object)

Purpose
This property contains a Graphic object, which contains the properties for the Annotation. See
Graphic object description.

See Also
Graphic object
Annotation Object and Annotations Collection

Annotation.Type property (Annotation object)

Purpose
This property specifies the annotation type. This is an AnnotationTypeConstants value, and
can be either miSymbolAnnotation or miTextAnnotation. This is a read-only property.

Annotations.ActiveAnnotation method (Annotations collection)

Purpose
This method returns the active (currently selected) annotation.

Syntax
OBJECT.ActiveAnnotation

Annotations.AddSymbol method (Annotations collection)

Purpose
This method adds a symbol to the Annotations collection. The default style is used (as
specified in Map.DefaultStyle).

Syntax
Annotations.AddSymbol [X, Y]

Part Description

X X coordinate of the symbol to add. This is a double value, and specifies the map
coordinate (longitude).
Y Y coordinate of the symbol to add. This is a double value, and specifies the map
coordinate (latitude).

See Also
Map.DefaultStyle property

Graphic.X property

Graphic.Y property

270 MapInfo MapX Developer Guide v4.5

 Annotations.Count property (Annotations collection)

Annotations.AddText metho (Annotations collection)

Purpose
This method adds a text annotation to the Annotations collection. A default style is used (as
specified in Map.DefaultStyle).

Syntax
OBJECT.AddText ( Text, X, Y, [Position] )

Part Description
OBJECT Represents a place holder for an Annotations object.
Text String value. Becomes the Caption of the new annotation.
X X coordinate to place the text. This is a double value, and specifies the map
coordinate (longitude).
Y Y coordinate to place the text. This is a double value, and specifies the map
coordinate (latitude).
Position Reference point to add text with respect to the x,y coordinates. This takes a
PositionConstants value.

See Also
Map.DefaultStyle property
Graphic.Caption property

Graphic.Position property

Graphic.X property

Graphic.Y property

Annotations.Count property (Annotations collection)

Purpose
This property specifies the number of Annotation objects in the collection. This is an integer
value, and is read-only

MapInfo MapX Developer Guide v4.5 271

Annotation Object and Annotations Collection

Annotations.Editable property (Annotations collection)

Purpose
This property controls whether the annotations are editable by the end user. An editable
annotation can be moved, resized and edited in place by the end user. This is a Boolean
value, and defaults to True.

Annotations.Item property (Annotations collection)

Purpose
This property gets an Annotation object from the collection. An index is used to specify
which Annotation to get. The index is an integer value from 1 to Annotations.Count. This is
the default property for the Annotations collection.

See Also
Annotations.Count property

Annotations.Remove method (Annotations collection)

Purpose
This method removes an Annotation object from the collection.

Note: If you remove an item, the collection indexes are renumbered to fill in the hole
left by the item removed.

Syntax
OBJECT.Remove (Index)

Part Description
OBJECT Represents a place holder for an Annotations object.
Index Index of the annotation to use. This is an Integer, between the values of 1
and AnnotationCount.

See Also
Annotations.Count property

272 MapInfo MapX Developer Guide v4.5

 Annotations.Remove method (Annotations collection)

Annotations.RemoveAll method (Annotations collection)

Purpose
Removes all annotation objects from the collection.

Syntax
OBJECT.RemoveAll

Part Description

OBJECT Represents a place holder for an Annotation object.

MapInfo MapX Developer Guide v4.5 273

Annotation Object and Annotations Collection

274 MapInfo MapX Developer Guide v4.5

BindLayer Object

The BindLayer object is used as a parameter to the Datasets.Add method. It is used to specify
information on how to perform the data binding. This is required when binding data that has
X and Y coordinates or data like ZIP codes, and you want points created at these locations in a
new layer.

Object Properties
• BindLayer.CoordSys property
• BindLayer.Filespec property
• BindLayer.KeyLength property
• BindLayer.LayerName property
• BindLayer.LayerType property
• BindLayer.RefColumn1 property
• BindLayer.RefColumn2 property
• BindLayer.ReferenceLayer property
• BindLayer.ReferenceLayerField property

See Also
Datasets.Add method

BindLayer.CoordSys property (BindLayer object)

Purpose
This property uses a CoordSys object that controls the coordinate system used when you
create a layer.

Remarks
When you perform x/y or pointref data binding to create a layer of points, the
BindLayer.CoordSys property specifies the coordinate system in which the layer will be
created. Furthermore, in the case of x/y data binding, MapX uses this coordinate system to
interpret the data source's x- and y-coordinates. For example, if you know that a data source
contains x- and y-coordinates in state plane coordinates, set the BindLayer.CoordSys to use a
state plane coordinate system.
If you do not set this property, the current Map.NumericCoordSys property is used as the
coordinate system.
BindLayer Object

BindLayer.Filespec property (BindLayer object)

Purpose
This property allows you to specify the name and location of a file, so that the Datasets.Add
method can create a permanent layer instead of a temporary layer. It is a string property
which should be set to the file path of the layer to create.

Remarks
This property applies to x/y data binding and pointref data binding (i.e. the
BindLayer.LayerType property is miBindLayerTypeXY or miBindLayerTypePointRef).

If you assign a file path and name to this property, the Datasets.Add method creates a
permanent layer, stored at the path that you specified. If you do not assign this property, the
layer is temporary

BindLayer.KeyLength property (BindLayer object)

Purpose
This is an integer property that specifies the length of the character column in the layer that
is produced by Datasets.Add.

Remarks
If you do not assign a value to this property, the default key length is 254. In other words,
the resulting layer will include a column 254 characters wide.

BindLayer.LayerName property (BindLayer object)

Purpose
This property specifies the name of the layer to bind data to if BindLayer.LayerType is
miBindLayerTypeNormal, or the name of the newly created layer if BindLayer.LayerType is
miBindLayerTypeXY or miBindLayerTypePointRef. This is a string value.

276 MapInfo MapX Developer Guide v4.5

 BindLayer.LayerType property (BindLayer object)

See Also
BindLayerTypeConstants

BindLayer.ReferenceLayer property

BindLayer.LayerType property

BindLayer.RefColumn1 property

BindLayer.RefColumn2 property

BindLayer.LayerType property (BindLayer object)

Purpose
This property specifies what layer type data is being bound to. Binding data refers to the
process of creating a Dataset, which is done using the Datasets.Add method. This property
takes a BindLayerTypeConstant value, as described below.

Discussion
If set to miBindLayerTypeNormal, that means you are binding (adding) data to a layer in
the GeoDictionary.

If set to miBindLayerTypeXY, this indicates that the data has X and Y coordinates in it, and
you want a new layer of points to be created. When this is used, you need to specify the
name of the newly created point layer (BindLayer.LayerName), the field in the data that
contains the X coordinate (BindLayer.RefColumn1), and the field that contains the Y
coordinate (BindLayer.RefColumn2).

If set to miBindLayerTypePointRef, this indicates that your data contains values that you
want to match to information in a point reference file. A new layer is created containing a
point for each row in the source data that matches an entry in the point reference file. For
example, if your source data contains ZIP Code information, and you have a point reference
file containing U.S ZIP Code Centers installed in your GeoDictionary, you can create a new
layer containing a point for each ZIP Code contained in your source data (or multiple points
if a ZIP Code appears more than once). When this is used, you need to specify the name of
the newly created point layer (BindLayer.LayerName), the field in the data that contains the
reference data, (BindLayer.RefColumn1), and the name of the point reference file—the file
that has the ZIP Code locations in the above example (BindLayer.ReferenceLayer). The point
reference file must be installed in the GeoDictionary.

MapInfo MapX Developer Guide v4.5 277

BindLayer Object

See Also
Datasets.Add method

BindLayerTypeConstants

BindLayer.ReferenceLayer property

BindLayer.LayerName property

BindLayer.RefColumn1 property

BindLayer.RefColumn2 property

BindLayer.RefColumn1 property (BindLayer object)

Purpose
This property specifies the field name or field number (starting at one) of either:

• the field containing the X value (longitude) when BindLayer.LayerType is

miBindLayerTypeXY.
• the field containing the reference value (such as ZIP Code) when
BindLayer.LayerType is miBindLayerTypePointRef.

See Also
BindLayer Object
BindLayerTypeConstants

BindLayer.RefColumn2 property (BindLayer object)

Purpose
This property specifies the field name or field number (starting at one) of the field
containing the Y value (latitude) when BindLayer.LayerType is miBindLayerTypeXY.

See Also
BindLayer.LayerType

BindLayerTypeConstants

278 MapInfo MapX Developer Guide v4.5

 BindLayer.ReferenceLayerField property (BindLayer object)

BindLayer.ReferenceLayer property (BindLayer object)

Purpose
This property specifies the name of the reference file to use if BindLayer.LayerType is
miBindLayerTypePointRef. A reference layer is used when doing reference binding. This
specifies the name of the reference file to use. A reference file contains the x and y
coordinates for items such as ZIP codes. MapX ships with the "US 5 Digit ZIP Code Centers"
layer which may be used for pointref binding at the ZIP Code level.

The ReferenceLayer property can be set to a layer's filename (a full file specification) or set
to the layer's "friendly name" (the description that is assigned to the layer through the
geodictionary).
PointReference binding (data binding of type miBindLayerTypePointRef), can be done
using any table as a reference layer, not just CPF files. Specify the reference layer as the
ReferenceLayer property of the BindLayer object provided to the Datasets.Add method
when doing a PointReference bind.

See Also
BindLayer.LayerType

BindLayerTypeConstants

BindLayer.ReferenceLayerField property (BindLayer object)

Purpose
This specifies what field (by number, starting at 1) in the MapInfo table to bind to. If not
specified, MapX will sample the source data for the column and choose the column with the
highest match rate. If none match, then the first column is chosen. A field must be indexed
before a bind using the specified field.

Remarks
This property is optional (does not need to be set). It is only valid for
BindLayerTypeNormal and is only valid when the layer to bind to is specified in the
LayerName property.

MapInfo MapX Developer Guide v4.5 279

BindLayer Object

280 MapInfo MapX Developer Guide v4.5

BitmapSymbol Object and BitmapSymbols
Collection

A BitmapSymbol object represents one of the bitmap symbols available on the user's system.

A BitmapSymbols collection represents the set of all bitmap symbols on the user's system.

Note: BitmapSymbols.Item is the default property for the BitmapSymbols collection.

Object Properties
• BitmapSymbol.Name property

Collection Properties
• BitmapSymbols.Count property
• BitmapSymbols.Item property

Collection Methods
• BitmapSymbols.Refresh method
• BitmapSymbols.Unload method

BitmapSymbol.Name property (BitmapSymbol object)

Purpose
This is a read-only string representing the file name (e.g. "filename.bmp") that identifies a
bitmap symbol.

Remarks
The Name property is read-only. Use this property to determine the name of a bitmap symbol
file (*.bmp); you can assign that name to a Style object's SymbolBitmapName property.

See Also
Bitmap symbols
BitmapSymbol Object and BitmapSymbols Collection

BitmapSymbols.Count property (BitmapSymbols collection)

Purpose
This read-only property returns the number of items in the collection (i.e. the number of
bitmaps available to be used as bitmap symbols).

See Also
Bitmap symbols

BitmapSymbols.Item property (BitmapSymbols collection)

Purpose
This read-only property returns a BitmapSymbol object from the collection—use a numeric
index only. This is the default property for the BitmapSymbols collection.

Syntax
[ BitmapSymbol= ]OBJECT.Item (index)

Part Description
OBJECT Represents a BitmapSymbols object.
index An integer indicating which BitmapSymbol object to return.

See Also
Bitmap symbols

BitmapSymbols.Refresh method (BitmapSymbols collection)

Purpose
This updates the BitmapSymbols collection, if necessary, to guarantee that the collection is
current.

Remarks
The BitmapSymbols collection represents the set of .bmp files found in the CUSTSYMB
directory. However, if you add .bmp files while MapX is running, MapX does not update the
collection automatically. To guarantee that the BitmapSymbols collection is current, use the
Refresh method.

282 MapInfo MapX Developer Guide v4.5

 BitmapSymbols.Unload method (BitmapSymbols collection)

Syntax
OBJECT.Refresh ()

See Also
Bitmap symbols

BitmapSymbols.Unload method (BitmapSymbols collection)

Purpose
Unloads all previously loaded .bmp files, and frees any associated resources.

Remarks
When the BitmapSymbols collection goes out of scope, resources are not freed automatically.
When you are done using a BitmapSymbols collection, use the Unload method to explicitly
free the associated resources.

If you do not use this method to explicitly free the collection's resources, the resources are
freed when MapX libraries are unloaded.

Syntax
OBJECT.Unload ()

See Also
Bitmap symbols

MapInfo MapX Developer Guide v4.5 283

BitmapSymbol Object and BitmapSymbols Collection

284 MapInfo MapX Developer Guide v4.5

CoordSys Object

A CoordSys object represents a coordinate system.

Object Properties
• CoordSys.AffineTransform property
• CoordSys.Azimuth property
• CoordSys.Bounds property
• CoordSys.Datum property
• CoordSys.FalseEasting and CoordSys.FalseNorthing properties
• CoordSys.OriginLatitude, OriginLongitude properties
• CoordSys.Range property
• CoordSys.ScaleFactor property
• CoordSys.StandardParallelOne, StandardParallelTwo properties
• CoordSys.Type property
• CoordSys.Units property

Object Methods
• CoordSys.Clone method
• CoordSys.PickCoordSys method
• CoordSys.Set method

Remarks
All properties are read-only. To modify a coordinate system, use the Set method or the
PickCoordSys method, or assign it to equal another CoordSys object.

To obtain a CoordSys object, reference the Map.DisplayCoordSys property,

Map.NumericCoordSys property, or Layer.CoordSys property.

See Also
Introduction to Using Coordinate Systems

CoordSys.AffineTransform property (CoordSys object)

Purpose
This is a read-only property that returns an AffineTransform object.

See Also
AffineTransform object
CoordSys Object

CoordSys.Azimuth property (CoordSys object)

Purpose
This is a read-only property that returns a double value representing the coordinate system's
azimuth.

CoordSys.Bounds property (CoordSys object)

Purpose
This is a read-only property that returns a rectangle object representing the bounds of the
coordinate system.

CoordSys.Clone method (CoordSys object)

Purpose
Makes a copy of this coordinate system as a new CoordSys object.

Syntax
[ CoordSys= ]OBJECT.Clone ()

CoordSys.Datum property (CoordSys object)

Purpose
This is a read-only property that returns a Datum object.

See Also
Datum object

CoordSys.FalseEasting and CoordSys.FalseNorthing properties

(CoordSys object)
Purpose
These are read-only properties that return double values, representing coordinate system's
false easting/false northing settings.

Remarks
The units are determined by the CoordSys.Unit property.

286 MapInfo MapX Developer Guide v4.5

 CoordSys.PickCoordSys method (CoordSys object)

CoordSys.OriginLatitude, OriginLongitude properties (CoordSys

object)
Purpose
This are read-only properties that return the coordinate system's origin latitude/origin
longitude settings, as double values.

CoordSys.PickCoordSys method (CoordSys object)

Purpose
This displays a dialog box that allows the user to select a coordinate system.

Syntax
[Boolean=]OBJECT.PickCoordSys ([HelpFile], [ID])

Part Description

OBJECT A CoordSys object.

HelpFile Variant: A string identifying the name and location of a Windows
Help file. Optional; if omitted, the dialog appears without Help
button.
HelpID Variant: An integer ID number that identifies which Help topic to
display. Optional; the dialog appears without a Help button.

Remarks
The dialog box is automatically initialized, so that the highlighted description matches the
CoordSys object.

If the user clicks OK on the dialog box, the method returns True, and the CoordSys object is
updated to match the coordinate system that the user chose. If the user clicks Cancel, the
method returns False, and the CoordSys object is left unchanged.

MapX initializes the list of available coordinate systems by reading the contents of the file
mapinfow.prj, which is located in the same directory as mapx40.ocx.

MapInfo MapX Developer Guide v4.5 287

CoordSys Object

CoordSys.Range property (CoordSys object)

Purpose
This is a read-only property that returns a double value, representing the coordinate
system's range (a number from 1 to 180, dictating how much of the earth will be visible).

288 MapInfo MapX Developer Guide v4.5

 CoordSys.Set method (CoordSys object)

CoordSys.ScaleFactor property (CoordSys object)

Purpose
This is a read-only property that returns a double value representing the coordinate system's
scale factor.

CoordSys.Set method (CoordSys object)

Purpose
This method sets the properties of a CoordSys object.

Syntax
OBJECT.Set (Type, [Datum], [Units], [OriginLongitude], [OriginLatitude],

[StandardParallelOne], [StandardParallelTwo], [Azimuth], [ScaleFactor],

[FalseEasting], [FalseNorthing], [Range], [Bounds], [AffineTransform] )

Part Description
OBJECT A CoordSys object.
Type A short CoordSysTypeConstants value, such as miRobinson (12).
Datum A Datum object or a supported datum number (such as 62 for the
“NAD 27” datum for the Continental US).
Units A MapUnitConstants value, such a miUnitMeter (7).
OriginLongitude Double values, indicating the standard parallels (in degrees of the
OriginLatitude latitude).
StandardParallelOne Double values, indicating the standard parallels (in degrees of
StandardParallelTwo latitude).
Azimuth Double value, representing the azimuth, in degrees.
ScaleFactor Double value, representing a scale factor.
FalseEasting Double values, representing Falseeasting and FalseNorthing (in
FalseNorthing Units specified by the Units argument).
Range Double value: Degrees of latitude from 1 to 180, indicating the
range (how what range of the earth will be visible).
Bounds A Rectangle object representing the outer bounds of the coordinate
system in Units specified by the Units argument. Required if Type
is miNonEarth; otherwise optional.
AffineTransformation An AffineTransform object; this argument is always optional.

MapInfo MapX Developer Guide v4.5 289

CoordSys Object

Remarks
The Type argument is always required. All other arguments are variants; these arguments
may be required, depending on which projection/coordinate system you select.

If an argument is not required, you may pass in any value or omit it entirely.

CoordSys.StandardParallelOne, StandardParallelTwo properties

(CoordSys object)
Purpose
This is a read-only property that returns the coordinate system's standard parallel settings,
as double values in degrees of latitude.

CoordSys.Type property (CoordSys object)

Purpose
This is a read-only property that returns a short value matching one of the
CoordSysTypeConstants .

CoordSys.Units property (CoordSys object)

Purpose
This is a read-only property that returns a short value matching one of the
MapUnitConstants.

290 MapInfo MapX Developer Guide v4.5

Dataset object and Datasets collection

Each Map has a collection of Datasets. The Datasets collection has methods and properties
used to add and remove Dataset objects from the collection. An overview of databinding is
provided below. For an in depth information on see chapter, "Putting your Data on the Map".

Data Binding
Data Binding is the process of bringing data from a data source into MapX. The data source
might be a Visual Basic data control, or an ODBC data source. In MapX, the data is represented
as a Dataset object.

Data binding can be done two ways. If you have Visual Basic for bound data controls, at
design time you can use the Dataset property of the Map object. Or, bind data
programmatically by using the Datasets.Add method. This method requires you to tell MapX
which data source to use, some information about it, and which map layer to bind it to.

The binding process results in the creation of a Dataset object. This Dataset, which is added to
the Datasets collection, contains computed values for features in the map layer that the data is
bound to. For example, if data is bound to US_States map, each state would have a new data
value that could then be used to control how the states are drawn. If the data source had
multiple records for a state, the values could be summed, averaged, or counted. The Dataset
has a Value method you can use to access the computed value for each row (or feature) of the
map.

A DataSource (the second parameter for Datasets.Add) is actually an OLE interface. MapX
uses the interface to access the data directly from the data source. The data isn't actually
passed to Datasets.Add. Types of data sources you can bind to include:

ADO This type of databinding uses the MS Active data objects ADO
recordset.

DAO A daoRecordset object. You can get one from a Visual Basic data
control, an Access form, or by creating one in Visual Basic,
Access, or C++.

Delphi This type uses the Borland BDE datasources.

Global Handle This type of data binding lets you pass in a block of tab-delimited
data.
Dataset object and Datasets collection

Layer This type of data binding lets you create a Dataset that uses fields
from a MapInfo table.

Notes View/ These types of data binding deal specifically with Lotus Notes.
NotesQuery

ODBC MapX can use ODBC to retrieve data from any ODBC data
source.

OLE Data This is for containers such as PowerBuilder.

RDO This uses MS Remote Data Objects and RDO Resultset object.

SafeArray A COM Dataset that allows static binding of data from a

safearray.

Unbound If you cannot support one of the other formats, MapX provides a
'back door’. With this type of data binding, you can set up an
event loop whereby MapX asks the container for data values, one
cell at a time.

For an in depth information on these datatypes, see topic "The Different Types of Data",
located in chapter, "Putting your Data on the Map".

Object Properties
• Dataset.Fields property
• Dataset.GeoField property
• Dataset.Layer property
• Dataset.Name property
• Dataset.ReadOnly property
• Dataset.RowCount property
• Dataset.RowValues property
• Dataset.SecondaryGeoField property
• Dataset.SourceRows property
• Dataset.Themes property
• Dataset.Type property

Object Methods
• Dataset.AddField method
• Dataset.Refresh method
• Dataset.Value method

292 MapInfo MapX Developer Guide v4.5

 Dataset.AddField method (Dataset object)

Collection Properties
• Datasets.BuildSourceRows property
• Datasets.Count property
• Datasets.Item property

Collection Methods
• Datasets.Add method
• Datasets.Remove method
• Datasets.RemoveAll method
• Datasets.Restore method

Dataset.AddField method (Dataset object)

Purpose
This allows a field ('column') to be added to a Dataset that is an expression containing
functions, operators, and Datasets fields (from the current Dataset only). This will add a
new field to the Dataset's field collection for labelling, thematics, etc.

Syntax
OBJECT.AddField (Name, Expression)

Part Description

OBJECT Represents a Dataset object.

Name The name of the new field.
Expression The created expression.

Remarks
The new field will have a type that is either miTypeNumeric or miTypeString depending on
the return type of the expression.

The new field will have an aggregation type of miAggregationSum for numeric fields and
miAggregationIndividual for string fields.
The field is added to the end of the fields collection for the Dataset and is temporary. That is,
when the application terminates, the field will disappear. Also, the added field is not
updateable. If you try to update the added field, an exception will NOT be thrown.

Exceptions are thrown for invalid expressions, an invalid name parameter, or a non-unique
field name.

MapInfo MapX Developer Guide v4.5 293

Dataset object and Datasets collection

See Also
Creating Expressions

Datasets.BuildSourceRows property (Datasets collection)

Purpose
Datasets created from a Datasets collection with this property set to TRUE, will support the
Dataset.SourceRows method. Those Datasets created from a Datasets collection with this
property set to FALSE will not, and calling Datasets.SourceRows on those Dataset objects
will result in an exception.

Remarks
A given Dataset either supports or does not support the Datasets.GetSourceRows method
throughout its lifetime. Changing the property on the Datasets collection will not effect
Dataset object(s) previously created from that Datasets collection.

Dataset.Fields property (Dataset object)

Purpose
Fields collection for the Dataset.

See Also
Field object and collection

Dataset.GeoField property (Dataset object)

Purpose
The column number of the geographic key column in the Fields collection. This is an Integer
value and a read-only property.

Dataset.Layer property (Dataset object)

Purpose
The Layer object this Dataset is bound to.

294 MapInfo MapX Developer Guide v4.5

 Dataset.Name property (Dataset object)

Remarks
When a Dataset is added, the data is always attached to a layer. This points to the layer.

A layer may have more than one Dataset bound to it. When a layer is deleted, any Datasets
bound to it are also deleted.

Dataset.Name property (Dataset object)

Purpose
The name of a Dataset. This is a String value.

Remarks
The name is a way to refer to this Dataset when using methods such as Datasets.Item or
Datasets.Remove. The name must be unique across all Datasets in the Dataset collection.

Dataset.Refresh method (Dataset object)

Purpose
Forces a re-read of the data from the data source.

Syntax
Dataset.Refresh

Remarks
This method is used to update the map if there are changes in the data.

When the Refresh method is invoked, the data is re-read from the original data source and
re-aggregated using the aggregation methods defined by the fields in the Dataset.
Any themes based on the Dataset will be updated to reflect the new data.

Note: This method will not work for Datasets of type miBindLayerTypeXY

Dataset.RowValues method (Dataset object)

Purpose
This method determines what a row can be: long row ID, string serialized key, or feature
object to get key from.

MapInfo MapX Developer Guide v4.5 295

Dataset object and Datasets collection

Syntax
[RowValues=]OBJECT.RowValues(Row)

Part Description

OBJECT Represents a Dataset object.

Row Variant: Can be the FeatureID (integer), the FeatureKey (String), or a
Feature object.

Dataset.RowCount property (Dataset object)

Purpose
This returns the number of rows in a Dataset. This is an Integer value. This is a read-only
property.

Remarks
Since this data is bound to a layer, RowCount actually returns the number of features in the
layer. Therefore, items in a Dataset can have NULL values if no data was bound to the
feature.

Dataset.ReadOnly property (Dataset object)

Purpose
This is a read-only property that indicates if the Dataset is updateable or not. Currently,
only miDatasetLayer Datasets are updateable. Datasets are updated using the
Layers.UpdateFeature or Feature.Update with a RowValues collection.

See Also
RowValue object and RowValues collection

Layer.UpdateFeature method

Feature.Update method

296 MapInfo MapX Developer Guide v4.5

 Dataset.SecondaryGeoField property (Dataset object)

Datasets.Restore method (Datasets collection)

Purpose
This method can be used to restore a Dataset from a map that has been stored to a file using
OLE serialization. Since Datasets rely on external data, the contents of the Datasets are not
serialized to the file along with the rest of the map's information. Datasets.Restore can be
used to restore a Dataset (and its themes) by pointing an unserialized map back to the
external data.

Syntax
[ Dataset = ]OBJECT.Restore ( Name, SourceData )

Part Description
OBJECT A Datasets collection.
Name A string parameter. This is the name of the Dataset to restore; it
should be the name of a Dataset that existed when the map was
serialized.
SourceData A variant. This should be the same parameter as when the stored
Dataset was added in the original Datasets.Add. This data source
is then used to restore the contents of the dataset.

See Also
Datasets.Add method

Dataset.SecondaryGeoField property (Dataset object)

Purpose
The column number of the secondary geographic key column in the Fields collection. The
value will be 0 if no SecondaryGeoField was specified when the data was added. This is an
Integer value and a read-only property.

Dataset.SourceRows property (Dataset object)

Purpose
The SourceRows collection of a Dataset contains the list of rows from the source data that
were matched to a specified row.

MapInfo MapX Developer Guide v4.5 297

Dataset object and Datasets collection

See Also
SourceRow object and SourceRows collection

Feature.FeatureKey property

Dataset.Themes property (Dataset object)

Purpose
Themes collection for the Dataset.

See Also
Theme object and Themes collection

Dataset.Type property (Dataset object)

Purpose
This is a read-only property that returns the type of dataset. The value of this property will
be one of the DatasetTypeConstants values.

Dataset.Value metho (Dataset object)

Purpose
This method retrieves values for a specified row and column in the Dataset. This is a default
property for the Dataset object.

Syntax
[value =] OBJECT.Value (Row, Column)

Part Description
OBJECT Represents a Dataset object.
Row Row in MapX to obtain value. Variant: can be one of:
*FeatureKey
*FeatureID
*Feature object
NOTE: If you are working with remote tables, you MUST use the
FeatureKey or Feature object. You may NOT use FeatureID.
Column Variant: can be column name or index.

298 MapInfo MapX Developer Guide v4.5

 Dataset.Value method (Dataset object)

Remarks
The values returned are from the MapX Dataset, not the original source data. Since the
original source data is aggregated and bound to a layer to form the MapX Dataset, the Row
numbers correspond to the features in the Layer, and not the original source row numbers.
Therefore, cells in the Dataset can have NULL values if no data was bound to the feature. A
NULL value is returned in the variant by setting the type of the variant to VT_NULL.

You can use a Feature object as the Row parameter, since a feature object uniquely identifies
a single row in the Layer that the dataset is bound to.

If you are working with remote tables, you MUST use the FeatureKey or Feature object. You
may NOT use FeatureID.

See Also
Feature.FeatureKey property

Feature.Name property

MapInfo MapX Developer Guide v4.5 299

Dataset object and Datasets collection

Datasets.Add method (Datasets collection)

Purpose
This method creates a specified Dataset and adds it to the collection.

Syntax
OBJECT.Add ( Type, SourceData, [Name], [Geofield], [SecondaryGeofield], [BindLayer],
[Fields], [Dynamic] )

Part Description

OBJECT This represents the Dataset object

Type Type of Dataset being added takes a DatasetTypeConstants
value.
SourceData This is a reference to the data, and is different depending on
the TYPE (i.e. IDAORecordset, ODBCQueryInfo, Layer object,
etc.).
Name This parameter is a string that uniquely identifies the Dataset.
This is an optional parameter, and if not specified, a name in
the form of DatasetN is used where N is a unique number.
Geofield This the name or index of the column that contains the
geographic information. This is an optional parameter, and if
not specified, MapX searches the fields to find one that
matches entries in the GeoDictionary.
See Also: Map.MatchNumericFields property.
SecondaryGeofield Name or index of the column that contains the refining
geographic information. This is an optional parameter.
BindLayer Specifies the Map layer to attach this data to, or, a
BindLayerObject if incoming data is to be georeferenced to a
point reference file (such as ZIP Codes) or contains Long/Lat
values. This is an optional parameter, and if not specified,
MapX searches layers in the GeoDictionary to attach to.
Fields This is a Field object which is in a collection of Field objects.
The field objects are used to describe which fields from the
data source to bring in, and which aggregation function to use
if more than one record for the data source matches a
particular map feature. This is an optional parameter, and if
not specified, all columns are brought in, and the data values
are summed if more than one record is encountered per
feature.

300 MapInfo MapX Developer Guide v4.5

 Datasets.Add method (Datasets collection)

Part Description

Dynamic Variant: A Boolean value that controls whether the data

binding is dynamic. Optional; if omitted, defaults to false,
meaning that the binding is static (i.e., MapX will copy needed
data when the database is opened). If you specify True, MapX
accesses data in a live manner, only data needed (e.g. when
labeling). If you specify True but the Dataset does not support
dynamic columns, an exception will be thrown.
Note: If ambiguity exists (like multiple geosets), the user can specify an event handler
to pick one. If no event handler is specified, MapX will pick the first one.
Note: Dataset type: miDatasetLayer—used to create a dataset that references fields
from a MapInfo table. The SourceData parameter is a Layer object.
Note: When doing BindLayer matching, the geofields must be unique. Only the first
item of a non-unique set of data will be matched. The rest are ignored.

MapInfo MapX Developer Guide v4.5 301

Dataset object and Datasets collection

Remarks
If the automatic detection logic is being used, more than one match may be found. If you
want to handle this case, you can implement the ResolveDataBind event handler.
Otherwise, MapX picks the first match.

A SecondaryGeofield is required when the layer that a Dataset is being bound to has a key
column that is not unique by itself. The secondary geofield is then used to uniquely match
an object (row) in the layer.

The GeoField column must be unique if a new layer of points is to be created

(BindLayer.LayerType is miBindLayerTypeXY or miBindLayerTypePointRef). The GeoField
column will be used to name the features in the new point layer. Non-unique values will
result in a single point being added to the new point layer for the first occurrence of the
duplicate key value, and data values in the duplicate rows will be aggregated.

If a Fields collection is specified, the Geofield and SecondaryGeofield parameters refer to

columns in the Fields collection rather than in the source data.

If dynamic data binding is being used, the Field.AggregationFunction property is ignored

for all field, and all fields are aggregated individually. In the case of multiple matching
records, the first will be taken.

See Also
Field object and Fields collection

Datasets.Count property (Datasets collection)

Purpose
The number of Dataset objects in the collection. This is a read-only property.

Datasets.Item property (Datasets collection)

Purpose
This property will retrieve a particular Dataset object from a collection. This is a Variant, and
you can specify the Dataset name or 1 based index number. This is the default property for
the Datasets collection.

302 MapInfo MapX Developer Guide v4.5

Datasets.Remove method (Datasets collection)
Purpose
Removes a specified Dataset object from the Datasets collection.

Note: If you remove an item, the collection indexes are renumbered to fill in the hole left
by the item removed.

Syntax
Datasets.Remove (index)

Part Description

index Dataset name or 1 based index number.

Remarks
All themes based off this Dataset are removed as well.

Datasets.RemoveAll method (Datasets collection)

Purpose
Removes all Dataset objects from the collection.

Syntax
Datasets.RemoveAll
Dataset object and Datasets collection

304 MapInfo MapX Developer Guide v4.5

 Datum.Eccentricity property (Datum object)

Datum Object

A Datum object represents the datum used by a CoordSys object. A datum is a singular
mathematical description of the earth's shape and orientation.

Object Methods
• Datum.Set method
• Datum.SetFromList method

Object Properties
• Datum.Eccentricity property
• Datum.Ellipsoid property
• Datum.Flattening property
• Datum.PrimeMeridian property
• Datum.RotateX, RotateY, RotateZ properties
• Datum.ScaleAdjust property
• Datum.SemiMajorAxis, SemiMinorAxis properties
• Datum.ShiftX, ShiftY, ShiftZ properties

Remarks
All properties are read-only. To modify a Datum object, use the Set method or the
SetFromList method.

To obtain a Datum object, reference a CoordSys object's Datum property.

Datum.Eccentricity property (Datum object)

Purpose
This is a read-only property that returns a double value representing the datum's
eccentricity.

Remarks
In equations, eccentricity is usually represented by the letter "e".

Datum.Ellipsoid property (Datum object)

Purpose
This is a read-only property that returns a short value that identifies the Datum's ellipsoid,
such as 28 for "WGS 84."

MapInfo MapX Developer Guide v4.5 305

Datum Object

Datum.Flattening property (Datum object)

Purpose
This is a read-only property that returns a double value representing the Datum's flattening.

Remarks
In equations, flattening is usually represented by the letter f.

Datum.PrimeMeridian property (Datum object)

Purpose
This is a read-only property that returns a double value representing the longitude of the
datum's prime meridian, in degrees east of Greenwich.

Remarks
The PrimeMeridian property is usually zero, because most datums use Greenwich as the
prime meridian. However, some datums use a different location as the prime meridian. For
example, the NTF datum uses Paris as its prime meridian, which is 2.33722917 degrees east
of Greenwich. If you use the NTF datum in a coordinate system, all longitudes in that
coordinate system are relative to Paris instead of Greenwich.

Datum.RotateX, RotateY, RotateZ properties (Datum object)

Purpose
This is a read-only properties; return double values representing the angle, in arc-seconds,
to rotate the datum's ellipsoid around each of its axes.

Datum.ScaleAdjust property (Datum object)

Purpose
This is a read-only property that returns a double value representing the datum's scale
correction factor (the amount, in parts per million, to adjust the size of the ellipsoid).

Remarks
In equations, the scale adjustment is usually represented by the letter m.

306 MapInfo MapX Developer Guide v4.5

Datum.SemiMajorAxis, SemiMinorAxis properties (Datum object)
Purpose
This is a read-only properties; return double values representing the datum's semi-major and
semi-minor axes. Length is in meters..

Remarks
In equations, semi-major axis is usually represented by the letter a, and semi-minor axis is
usually represented by the letter b.

Datum.Set metho (Datum object)

Purpose
This method sets the properties that make up a Datum object.

Syntax
OBJECT.Set (Ellipsoid, ShiftX, ShiftY, ShiftZ, RotateX, RotateY, RotateZ, ScaleAdjust,
PrimeMeridian)

Part Description

OBJECT A Datum object.

Ellipsoid A short value; must be one of the supported ellipsoid
numbers (such as 28 for the “WGS 84” ellipsoid).
ShifX, ShiftY,ShiftZ Double values, representing the distance (in meters) to shift
the ellipsoid along each of its axes.
RotateX, RotateY, RotateZ Double Values, representing the angle (in arc-seconds) to
rotate the ellipsoid around each of its axes.
ScaleAdjust Double value, representing a scale correction factor (the
amount, in parts per million, to adjust the size of the
ellipsoid).
PrimeMeridian Double value, representing the longitude of the prime
meridian. Usually zero; see the PrimeMeridian property.

Remarks
All arguments are required.

See Also
Datum.SetFromList method
Datum Object

Datum.SetFromList method (Datum object)

Purpose
This method sets all of the properties of a Datum object to match the values of one of the
datums in the list of datums.

Syntax
OBJECT.Set DatumNumber

Part Description
OBJECT A Datum object.
DatumNumber A short value; must be one of the supported datum numbers (such
as 62 for the “NAD 27” datum for the continental United States).

Datum.ShiftX, ShiftY, ShiftZ properties (Datum object)

Purpose
These read-only properties that return double values indicating the distance (in meters) to
shift the Datum's ellipsoid along each of its axes.

308 MapInfo MapX Developer Guide v4.5

 Datum.ShiftX, ShiftY, ShiftZ properties (Datum object)

Feature Object and Features Collection

Each Layer has a collection of selected Feature objects (Layer.Selection). Feature objects
correspond to features (actual entities) in a layer, such as New York or Chicago.

Note: If a map feature is selected that exists over another object in another layer that
also gets selected, the original feature does not appear to be selected. For example,
in the "World Countries" geoset, select the United States and then, holding down
the control key, select the ocean. The United States does not appear to be selected.
Both items, however, will be in the Selection collections for their respective layers.
The Features collection object represents a collection of Feature objects from a layer. All
features in a collection must be from the same layer.You can get a features object by calling
one of the Layer Search methods, which return a Features collection. The Features object
contains the features that were in the layer when the Search method was called. Adding or
removing features from the layer do not affect any Feature collections that you may already
have.

Object Properties
• Feature.Area property
• Feature.Bounds property
• Feature.Caption property
• Feature.CenterX property, CenterYproperty
• Feature.FeatureID property
• Feature.FeatureKey property
• Feature.KeyValue property
• Feature.LabelPoint property
• Feature.Layer property
• Feature.Length property
• Feature.Name property
• Feature.Nodes property
• Feature.Parts property
• Feature.Perimeter property
• Feature.Point property
• Feature.Smooth property
• Feature.Style property
• Feature.Type property

Object Methods
• Feature.Attach method
• Feature.Clone method
• Feature.Offset method
• Feature.Update method

MapInfo MapX Developer Guide v4.5 309

Feature Object and Features Collection

Collection Properties
• Features.Bounds property
• Features.Count property
• Features.Item property

Collection Methods
• Features.Add method
• Features.AddByID method
• Features.Clone method
• Features.Common method
• Features.Remove method
• Features.Replace method
• Features.RemoveByID method

See Also
Selection Collection

Layer.Search method

Feature.Area property (Feature object)

Purpose
A read-only property that returns the area of a region feature; it is not valid for other types
of features.

Remarks
To control the units in which the area is returned, set the Map.AreaUnit property.

This is valid for the Region. The value is in area units. If you modify a feature in a layer, and
you have not yet performed an Update to save the changes, then this property returns a
value based on the "modified" version of the object (the object as it exists in memory).

Feature.Attach metho (Feature object)

Purpose
Attaches a stand-alone feature to the map so that the map's coordinate system applies to the
feature.

310 MapInfo MapX Developer Guide v4.5

 Feature.Clone method (Feature object)

Syntax
OBJECT.Attach (Map)

Part Description

OBJECT A feature object.

Map A map object.

Remarks
When you create a stand-alone feature object, you must attach that feature object to the map
before you reference any of its methods or properties. Attaching a feature to the map
associates the map's coordinate system with the feature. However, if you create a stand-
alone feature by calling methods of the FeatureFactory object, you do not need to call the
Attach method.

Feature.Clone method (Feature object)

Purpose
Make a copy of the feature as a new, stand-alone Feature object.

Syntax
[=Feature]Feature.Clone

Feature.Bounds property (Feature object)

Purpose
This returns a Rectangle object representing the geographic extents of the feature (its
Minimum Bounding Rectangle).

Remarks
In earlier versions of MapX, this property was called MBR.

If you modify a feature in a layer, and you have not yet performed an Update to save the
changes, then this property returns a value based on the "modified" version of the object (the
object as it exists in memory).

MapInfo MapX Developer Guide v4.5 311

Feature Object and Features Collection

Feature.Caption property (Feature object)

Purpose
A read-write string value, representing the text string that makes up a Text feature.
Referencing this property causes an exception if the feature is not a Text feature.

Syntax
[= string] OBJECT.Caption

Part Description
OBJECT A Feature object.
string A text string, up to 255 characters long.

See Also
Feature Object

Feature.CenterX property, CenterYproperty (Feature object)

Purpose
These are read-only double values that indicate the X and Y map coordinates of the feature's
centroid.

Remarks
When you need to access a feature's centroid, you may find it easier to use the LabelPoint
property, instead of using CenterX and CenterY.

Feature.FeatureID property (Feature object)

Purpose
This property returns the ID of the feature. Each feature in a layer contains a unique ID
within the layer. This is an Integer value and is read-only. This is the default property for the
Feature object.

Note: Although this property is still a functional part of MapX, it is recommended that
you use the Feature.FeatureKey. The FeatureKey property is used to identify a
unique record in a table. In previous versions, the FeatureID property was used
for this purpose, but it did not work correctly for seamless and remote layers. The
FeatureKey property works for all layer types

312 MapInfo MapX Developer Guide v4.5

 Feature.KeyValue property (Feature object)

Feature.FeatureKey property (Feature object)

Purpose
This returns the Key of the feature. Each feature in a layer contains a unique key within the
layer. This is a string value and is read-only. This is a replacement for Feature.FeatureID
(which still works as it did before, but it is recommended that you use the FeatureKey
property).

Note: The Key of a feature can be used as a parameter wherever FeatureID could be
used. The FeatureKey property is used to identify a unique record in a table. In
previous versions, the FeatureID property was used for this purpose, but it did
not work correctly for seamless and remote layers. The FeatureKey property
works for all layer types.

See Also
Selection.SelectByRegion method

Dataset.Value

Dataset.Sourcerows

Layer.Updatefeature method (can be used in place of target feature)

Layer.Deletefeature method (can be used in place of target feature)

Features.AddbyID method

Features.RemovebyID method

Selection.SelectByID method

Feature.KeyValue property (Feature object)

Purpose
This read/write string property is used to update or set a column (field) in the MapInfo
table when adding or updating a feature or layer.

MapInfo MapX Developer Guide v4.5 313

Feature Object and Features Collection

Remarks
The field value that is set or retrieved is determined by the value of the KeyField property of
the Layer that the feature is from. Although the property is a string property, the string will
be converted to the proper type of the column when updating or inserting.

Only the most recent value of the KeyValue property is used when adding or updating a
feature. That is if you set the KeyValue, change the layer's keyfield property to a different
field and then set the keyvalue again, only the second value will be updated in the MapInfo
table for that feature.

See Also
Layer.KeyField

Layer object

Feature.LabelPoint property (Feature object)

Purpose
This is a Point object which is the location in map coordinates of the centroid (label point) of
a feature.

See Also
Point object

Feature.Layer property (Feature object)

Purpose
This is a read-only property that returns the Layer object the feature is from.

See Also
Layer object

Feature.Length property (Feature object)

Purpose
A read-only property that returns the length of a line feature, as a double. Not valid for
other types of features.

314 MapInfo MapX Developer Guide v4.5

 Feature.Name property (Feature object)

Remarks
To control the units in which the length is returned, set the Map.MapUnit property.

If you modify a feature in a layer, and you have not yet performed an Update to save the
changes, then this property returns a value based on the "modified" version of the object (the
object as it exists in memory).

See Also
Feature.Perimeter

Feature.Name property (Feature object)

Purpose
This is a read-only property that returns the feature name. The feature name is value of the
LabelProperties.DataField field (which also appears as the feature's label).

See Also
LabelProperties.DataField property

Feature.Nodes property (Feature object)

Purpose
This read-only property exposes the node data in such a way that the user can query for all
the nodes in an object with one pass, then have them returned in a single, contiguous block
of memory.

Syntax
[ SafeArray= ] OBJECT.Nodes ([CSys])

Part Description

OBJECT Represents a place holder for a Feature object.

CSys A CoordSys object which defines the Coordinate System that the node
data is returned in. The default is Map.NumericCoordSys.

MapInfo MapX Developer Guide v4.5 315

Feature Object and Features Collection

Feature.Offset metho (Feature object)

Purpose
Moves the feature relative to its current position.

Syntax
OBJECT.Offset (deltaX, deltaY)

Part Description

OBJECT Represents a place holder for a Feature object.

deltaX The map coordinates to move the point by
deltaY The map coordinates to move the point by

Feature.Parts property (Feature object)

Purpose
A read-only property that returns a Parts object. Valid for Lines or Regions.

See Also
Parts object

Feature.Perimeter property (Feature object)

Purpose
A read-only property that returns the perimeter of a region feature; and is not valid for other
types of features.

Remarks
To control the units in which the perimeter is returned, set the Map.MapUnit property.

If you modify a feature in a layer, and you have not yet performed an Update to save the
changes, then this property returns a value based on the "modified" version of the object (the
object as it exists in memory).

See Also
Feature.Length

316 MapInfo MapX Developer Guide v4.5

 Feature.Smooth property (Feature object)

Feature.Point property (Feature object)

Purpose
This read-only property returns a Point object. It is valid only for features of type point and
text.

See Also
Point object

Feature.Smooth property (Feature object)

Purpose
The Feature.Smooth object enables you to smooth a polyline, making it into a continuous
curve. To smooth a polyline set the property to True.

Feature.Style property (Feature object)

Purpose
This read/write property returns the style of the feature.

See Also
Style object

Remarks
Style object default is '0' for each property of style object.

Feature.Type property (Feature object)

Purpose
Contains the type of the feature. This is a FeatureTypeConstants value, and is read/write.

See Also
FeatureFactory.CreateText

MapInfo MapX Developer Guide v4.5 317

Feature Object and Features Collection

Feature.Update method (Feature object)

Purpose
This method updates the layer with changes made to the1n8(obje)F(e)67611.8Rpdat-1.5to theuobje0 0 Th80.81683

318 MapInfo MapX Developer Guide v4.5

 Features.Bounds property (Features collection)

Features.AddByID method (Features collection)

Purpose
Add a Feature object with the specified FeatureKey to the Features collection.

Syntax
OBJECT.AddByID(FeatureKey)

Part Description

OBJECT Represents a place holder for a Features object.

FeatureKey FeatureKey of the feature to add to the Features collection.

Note: Feature.FeatureKey is a replacement for Feature.FeatureID. FeatureID still works

as it did before, but it is recommended that you use the new FeatureKey property.
The FeatureKey is used to identify a unique record in a table. In previous
versions, the FeatureID property was used for this purpose, but it did not work
correctly for seamless and remote layers. The FeatureKey property works for all
layer types.

See Also
Feature.FeatureKey property

Features.Bounds property (Features collection)

Purpose
This returns a Rectangle object representing the geographic extents of all objects in the
collection (i.e. the minimum bounding rectangle).

Syntax
OBJECT.Bounds

The OBJECT placeholder represents a Features collection.

Remarks
This property is useful if you want to zoom the map out far enough to show all objects in the
collection.

Examples
• Example in Visual Basic
• Example in C++
• Example in Delphi

MapInfo MapX Developer Guide v4.5 319

Feature Object and Features Collection

Features.Clone metho (Features collection)

Purpose
This method makes a copy of the collection as another Features object.

Syntax
OBJECT.Clone (source)

Part Description

OBJECT Represents a place holder for a Features collection.

source This represents the set of features to be cloned with the collection, OBJECT.

Features.Common method (Features collection)

Purpose
Combine this collection and another Feature object so that this collection contains only
features that are in both. (INTERSECT set operation).

Syntax
OBJECT.Common (source)

Part Description
OBJECT Represents a place holder for a Features collection.
source This represents the set of features to be combined with the collection OBJECT

Features.Count property (Features collection)

Purpose
Number of items in the collection.

Features.Item property (Features collection)

Purpose
Return a Feature object from collection - currently only numeric indexes are supported. This
is a default property for the Features collection.

320 MapInfo MapX Developer Guide v4.5

Features.Remove method (Features collection)
Purpose
Remove a Feature object or all features from a Features object from this collection.
(SUBTRACT set operation).

Syntax
OBJECT.Remove (source)

Part Description

OBJECT Represents a place holder for a Features object.

source This represents the set of features to be removed from the collection, OBJECT

Features.RemoveByID method (Features collection)

Purpose
Remove a Feature object with the specified FeatureID from the Features collection.

Syntax
OBJECT.RemoveByID (*FeatureKey)

Part Description
OBJECT Represents a place holder for a Features object.
FeatureKey *FeatureKey of the feature to remove from the Features collection. This
is a replacement for FeatureID parameter. FeatureID still works as it
did before, but it is recommended that you use the new FeatureKey
parameter.
The FeatureKey is used to identify a unique record in a table. In
previous versions, the FeatureID property was used for this purpose,
but it did not work correctly for seamless and remote layers. The
FeatureKey property works for all layer types.
Feature Object and Features Collection

Features.Replace method (Features collection)

Purpose
This replaces the contents of the collection with a Feature object or all features from a
Features object.

Syntax
OBJECT.Replace (source)

Part Description
OBJECT Represents a place holder for a Features object.
source Represents a feature object or features collection, the contents of which
will replace the contents of "feature".

322 MapInfo MapX Developer Guide v4.5

 FeatureFactory.BufferFeatures method (FeatureFactory object)

FeatureFactory Object

This object lets you create new map features, or create features by performing operations
(such as buffering) on existing features.

Object Methods
• FeatureFactory.BufferFeatures method
• FeatureFactory.CombineFeatures method
• FeatureFactory.CreateArc method
• FeatureFactory.CreateCircularRegion method
• FeatureFactory.CreateEllipticalRegion method
• FeatureFactory.CreateLine method
• FeatureFactory.CreateRegion method
• FeatureFactory.CreateSymbol method
• FeatureFactory.CreateText method
• FeatureFactory.EraseFeature method
• FeatureFactory.IntersectFeatures method
• FeatureFactory.IntersectionPoints method
• FeatureFactory.IntersectionTest method

Remarks
Most of these methods return stand-alone feature objects. These feature objects are
automatically attached to the map (i.e. they already have an associated coordinate system).
In other words, you do not need to use the Attach method on the features returned by these
methods.

To obtain a FeatureFactory object, reference the Map.FeatureFactory property.

FeatureFactory.BufferFeatures metho (FeatureFactory object)

Purpose
This returns a stand-alone Feature object representing a buffer region.

Syntax
[Feature = ] OBJECT.BufferFeatures ( Source, Distance, [Units] , [Resolution] )

Part Description

OBJECT A FeatureFactory object.

MapInfo MapX Developer Guide v4.5 323

FeatureFactory Object

Part Description

Source A Feature object or a Features collection object. Point, line, text and
region features can be buffered.
Distance The size of the buffer, in units specified by the units argument. If the
distance is positive, the buffer region is larger than the source feature(s).
When buffering a region, you can specify a negative distance, which
produces a buffer region that is smaller than the source region.
Units Variant: A MapUnitConstants value, such as miUnitMile (0), that
identifies the unit of measure for the distance argument. If omitted, the
MapUnit property is used as the default.
Resolution Variant: A positive integer indicating the number of nodes used in
creating a buffer. This is the number of nodes per circle in a buffer
operation, not the total number of nodes for the entire region (see
below). If omitted, the resolution is controlled by the
DefaultConversionResolution property.

Remarks
This method returns a single buffer region, regardless of whether you base the buffer on one
Feature or a Features collection. If you want to create a separate buffer region for each
feature in the collection, you must loop through the collection and use the BufferFeatures
method on one feature at a time.

If you are creating a buffer for the sole purpose of performing a search within the buffer, you
can use the SearchWithinDistance method instead of the BufferFeatures method.

The resolution argument controls how many nodes

are in the buffer region. Resolution is specified in
terms of the number of nodes per circle; this is best
illustrated by example. This picture shows two
features: A black, L–shaped polyline, and a gray
buffer region. The region was produced by creating
a buffer around the polyline. In this illustration, a
small square marks the location of each node in the
buffer region. This buffer was produced using a
resolution of 12 nodes per circle. Note that each
end of the polyline is capped with a semi–circle,

324 MapInfo MapX Developer Guide v4.5

 FeatureFactory.CombineFeatures method (FeatureFactory object)

and each semi–circle consists of six segments. If a larger resolution had been used, there
would be more nodes in each semi–circle.
The resolution does not necessarily represent the total number of nodes in the feature.
Resolution is specified in terms of nodes per circle, and a given feature can contain many
semi–circles. For example, the buffer region shown above has more than 12 nodes, although
the resolution specified 12 nodes per circle. Specifying a large resolution produces a
smoother looking region, but it takes longer to generate, and the resulting object requires
more storage space.

A zero width buffer is allowed on closed objects: Region, Rect, RoundRect, IsEllipse, &Text.
An "error creating buffer" exception will be thrown for other object types.

See Also
FeatureFactory.CreateCircularRegion method

FeatureFactory.CombineFeatures method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object representing the combination (union) of multiple
line features or multiple region features.

Syntax
[Feature = ] OBJECT.CombineFeatures( feature1, [ feature2 ] )

Part Description
OBJECT A FeatureFactory object.
feature1 A Feature object or a Features collection object.
feature2 Variant: A Feature object or a Features collection object.

Remarks
If feature1 is a Features collection, then the feature2 argument is optional. If feature1 is a
Feature object, then the feature2 argument is required. You cannot combine a line feature
with a region feature. The following combinations are supported:

• You can combine two or more line features (features whose Type property is
miFeatureTypeLine), in which case the result is a line feature.
• You can combine two or more region features (type: miFeatureTypeRegion), in
which case the result is a region feature.

MapInfo MapX Developer Guide v4.5 325

FeatureFactory Object

FeatureFactory.CreateArc metho (FeatureFactory object)

Purpose
This creates a line feature shaped like an arc, and returns it as a stand-alone Feature object.

Syntax
[Feature = ] OBJECT.CreateArc( Point1, Point2, [Angle] , [Distance] , [Resolution] , [Style] )

Part Description

OBJECT A FeatureFactory object.

Point, Point2 Two Point objects, representing the starting and ending points of the
arc.
Angle Variant: An angle, in degrees. Optional; if omitted, the default angle is
90 degrees, producing a symmetric arc.
Distance Variant: The length of an offset line expressed as a number of “arc
units” (where one arc unit is the distance between Point1 and Point2).
The larger the value, the more bowed the arc appears. Specifying zero
would produce a flat arc. Optional; if omitted, defaults to a value of 1.
Resolution Variant: A positive integer indicating the number of nodes to use in
creating the ellipse; maximum number is 32,763. Optional; if omitted,
the defaultConversionResolution property controls the resolution.
Style Variant: A Style object that defines the appearance of the feature.
Optional; if omitted, no style is set.

Remarks
This method returns a line feature (a feature whose Type property is miFeatureTypeLine)
that is shaped like an arc. Note: If the current DisplayCoordSys does not match the current
NumericCoordSys, the arc may appear distorted.

To calculate the path of the arc, imagine a line that connects Point1 and Point2 (the horizontal
line in the diagram at the left).

Next, imagine a second line (the vertical line in the diagram) that begins at the center point
of the first line. The length of the second line is determined by the Offset argument, and its
angle relative to the first line is determined by the Angle argument. To make the second line
perpendicular, as shown in the diagram, specify 90 degrees or 270 degrees. A triangle is
defined by Point1, Point2, and the end point of the second line. This triangle acts as a
”control polygon” in that it controls the shape of the arc. The arc fits inside the triangle, and

326 MapInfo MapX Developer Guide v4.5

 FeatureFactory.CombineFeatures method (FeatureFactory object)

it is tangential to the sides of the triangle at Point1 and Point2. The arc falls on one side of

the line between Point1 and Point2. To make the arc fall on the opposite side of the line, use
a different Angle argument (e.g. instead of 90 degrees, specify 270 degrees). Each
combination of Angle and Offset values produces a unique, characteristic shape. If you
always use the same combination of Angle and Offset values, the arcs produced will always
have the same shape, regardless of the distance between Point1 and Point2. Some samples
are shown below:

Angle Offset Result

30 1

30 0.5

90 1

MapInfo MapX Developer Guide v4.5 327

FeatureFactory Object

Angle Offset Result

90 0.5

90 0.25

165 1

165 0.5

270 0.5

See Also
FeatureFactory.CreateEllipticalRegion method

FeatureFactory.CreateCircularRegion method (FeatureFactory

object)
Purpose
This creates a region feature shaped like a circle, and returns it as a stand-alone Feature
object. The feature can be added to a layer, used in searches, etc.

328 MapInfo MapX Developer Guide v4.5

 FeatureFactory.CreateCircularRegion method (FeatureFactory object)

Syntax
[Feature = ] OBJECT.CreateCircularRegion( Type, Point, Distance, [Units] , [Resolution] ,
[Style] )

Part Description

OBJECT A FeatureFactory object.

Type Short: A CircleTypeConstants value: Specify
miCircleTypeScreen(value:0)or miCircleTypeMap (1). (See below)
Point Point object: Represents the location to use as the center of the circle;
specified in the current numeric coordinate system.
Distance Double: The radius of the circle, in the units specified by the Units
argument.
Units Variant: A MapUnitConstants value, such as miUnitMile (0), that
identifies the unit of measure for the Distance argument. Optional; if
omitted, the MapUnit property controls the Units.
Resolution Variant: A positive integer indicating the number of nodes to use in
creating the circle; maximum number is 32,763. Optional; if omitted,
the DefaultConversionResolution property controls resolution.
Specifying a large resolution produces a smoother looking region, but
it takes longer to generate, and the resulting object requires more
storage space.
Style Variant: A Style object that defines the appearance of the feature.
Optional; if omitted, no style is set.

Remarks
If the Type is miCircleTypeScreen, MapX creates a region that appears circular on the screen.
However, different points on the circle might not be the same geographic distance from the
center of the circle. MapX calculates a point along the x-axis that is Distance units from the
center. That distance is converted to screen units (pixels) and used as the radius to calculate
the rest of the nodes in the circle. Note: If you change the map's display coordinate system
after creating the region, the region may appear lop-sided, rather than circular.

If the Type is miCircleTypeMap, MapX creates a region whose points are all the same
geographic distance from the center. However, due to the curvature of the earth, and due to
the way that coordinate systems and map projections work, such a circle might appear lop-
sided, rather than circular.

MapInfo MapX Developer Guide v4.5 329

FeatureFactory Object

See Also
FeatureFactory.BufferFeatures method

FeatureFactory.CreateEllipticalRegion method

330 MapInfo MapX Developer Guide v4.5

 FeatureFactory.CreateCircularRegion method (FeatureFactory object)

FeatureFactory.CreateEllipticalRegion method (FeatureFactory

object)
Purpose
This creates a region feature shaped like an ellipse, and returns it as a stand-alone Feature
object. The feature can be added to a layer, used in searches, etc.

Syntax
[Feature = ] OBJECT.CreateEllipticalRegion( Rectangle, [Angle] , [Resolution] , [Style] )

Part Description

OBJECT Represents a FeatureFactory object.

Rectangle A Rectangle object, representing the minimum bounding rectangle
(MBR) of an ellipse in the map's current numeric coordinate system.
Angle Variant: An angle of rotation for the ellipse. The ellipse is rotated
from its center point.
Resolution Variant: A positive integer indicating the number of nodes to use in
creating the ellipse; maximum number is 32,763. If omitted, the
DefaultConversionResolution property controls the resolution.
Style Variant: A Style object that defines the appearance of the feature.
Optional; if omitted, no style is set.

Remarks
If the current DisplayCoordSys does not match the current NumericCoordSys, the ellipse
may appear distorted.

See Also
FeatureFactory.CreateArc method
FeatureFactory.CreateCircularRegion method

MapInfo MapX Developer Guide v4.5 331

FeatureFactory Object

FeatureFactory.CreateLine method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object (a line feature), built from a collection of points.

Syntax
[Feature = ] OBJECT.CreateLine( [Points] , [Style] )

Part Description

OBJECT A FeatureFactory object.

Points Variant: A Points collection, representing the set of points to use to
define the line. Optional; if omitted, no points are added to the line
feature.
Style Variant: A Style object that defines the appearance of the feature.
Optional; if omitted, no style is set.

FeatureFactory.CreateRegion method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object (a region feature), built from a collection of points.

Syntax
[Feature = ] OBJECT.CreateRegion( [Points] , [Style] )

Part Description

OBJECT A FeatureFactory object.

Points Variant: A Points collection, representing the set of points that define
the region or a Rectangle object. Passing a Rectangle object creates a
region using the four corners of the rectangle. Optional; if omitted,
no points are added to the feature.
Style Variant: A Style object that defines the appearance of the feature.
Optional; if omitted, no style is set.

332 MapInfo MapX Developer Guide v4.5

 FeatureFactory.CreateText method (FeatureFactory object)

FeatureFactory.CreateSymbol method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object (a point feature), built from a Point object.

Syntax
[Feature = ] OBJECT.CreateSymbol( [Point] , [Style] )

Part Description

OBJECT A FeatureFactory object.

Point Variant: A Point object, representing the x/y location where the
symbol should be placed. Optional; if omitted, the feature's location
is not set.
Style Variant: A Style object that defines the appearance of the feature. If
omitted, no style is set.

FeatureFactory.CreateText method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object (a text feature).

Syntax
[Feature = ] OBJECT.CreateText( [Point] , [Caption] , [Position] , [Style] )

Part Description

OBJECT A FeatureFactory object.

Point Variant: A Point object, representing the location where the text
should be anchored. Optional; if omitted, the feature's location is not
set.
Caption Variant: A string that defines the text. Optional; if omitted, the
feature's caption is not set.
Position A PositionConstants value; controls the initial position of the text,
relative to the anchor point. Optional; if omitted, defaults to
miPositionTL (i.e. the anchor point is at the top left corner of the
text).
This argument only takes effect if the Point and Caption arguments
are both specified.
Style Variant: A Style object that defines the appearance of the feature. If
omitted, no style is set.

MapInfo MapX Developer Guide v4.5 333

FeatureFactory Object

Remarks
You control the location of a text feature by specifying the Point and the Position. Note,
however, that the Position property can only be used for specifying the initial position of the
text; the Feature object does not provide a Position property that allows you to reset the text
orientation. Once this method creates a text feature, there is no way to toggle the feature's
orientation relative to the anchor point.

FeatureFactory.EraseFeature method (FeatureFactory object)

Purpose
This returns a stand-alone Feature object by "erasing" one feature's area from another
feature.

Syntax
[Feature = ] OBJECT.EraseFeature( SourceFeature, EraserFeature )

Part Description
OBJECT A FeatureFactory object.
SourceFeature A Feature object, part of which you want to erase; this can be a line
feature or a region feature.
EraserFeature A Feature object, which represents the area that you want to remove
from the SourceFeature. This must be a region feature.

Remarks
This method creates a Feature object by subtracting the EraserFeature from the
SourceFeature. If the two features do not intersect, then nothing is erased, and the featur
returned by this method is identical to the SourceFeature.

Example
This picture shows a circular region, created through the BufferFeatures method. In this
example, the circular region covers a coastal area; the gray area represents land, and the
white area represents water.

334 MapInfo MapX Developer Guide v4.5

 FeatureFactory.EraseFeature method (FeatureFactory object)

To erase part of the circular region, use the EraseFeature method. If you make the circular
region your SourceFeature, and make the gray region your EraserFeature, you will erase the
portion of the circle that overlaps the gray region.

MapInfo MapX Developer Guide v4.5 335

FeatureFactory Object

This picture shows what is left of the circular region after calling the EraseFeature method.
The EraseFeature method removes the portion of a feature that overlaps another feature. T
perform the opposite task (to remove the portion of a feature that does not overlap), use the
FeatureFactory.IntersectFeatures method.

FeatureFactory.IntersectFeatures method (FeatureFactory object)

Purpose
This returns a stand-alone feature that represents the intersection of multiple features.

Syntax
[Feature=]OBJECT.IntersectFeatures( feature1 [feature2] )

Part Description

OBJECT A FeatureFactory object.

feature1 A Feature object or a Features collection object, representing region or line
features.
feature2 Variant: A Feature object or a Features collection object representing region
or line features. This argument is only required if the feature1 argument is
a single Feature object.

336 MapInfo MapX Developer Guide v4.5

 FeatureFactory.IntersectionPoints method (FeatureFactory object)

Remarks
This method intersects a Feature or Features object with another Feature or Features object,
and returns the resulting object as a stand-alone feature.

You cannot use point or text features with this method. Only the following combinations of
feature types are supported:

• You can intersect regions with other regions. If regions overlap, the feature returned
by this method is also a region.
• You can intersect regions and lines. Assuming that the region covers at least part of
the line, the intersection is the portion of the line that is covered by the region.
• You can intersect lines with other lines. If two lines cross, IntersectFeatures will
return a polyline feature with one point.
Note that two features might not intersect at all. In the case of one line and one region– or–
two lines, the value returned by this method is a POLYLINE FEATURE with zero points.
However, when two region features do not intersect, the value returned is a REGION
FEATURE with zero points. In any case, a "zero point feature" cannot be inserted into a
layer.

When working with multiple polylines, the intersection of the features collection returns the
point or points where ALL lines intersect. Therefore, if any of the lines within the feartures
collection does NOT intersect the others, a polyline with 0 points is returned.

The IntersectFeatures method returns the portion of a feature that overlaps another feature.
To obtain the portion of a feature that does not overlap, use the EraseFeature method.

FeatureFactory.IntersectionPoints metho (FeatureFactory object)

Purpose
This returns a Points collection containing the points where two features intersect.

MapInfo MapX Developer Guide v4.5 337

FeatureFactory Object

Syntax
[Points collection=]OBJECT.IntersectionPoints( feature1, feature2, [flag] )

Part Description

object A FeatureFactory object.

feature1 A Feature object.
feature2 A Feature object.
flag Variant: An IntersectionPointConstants value; see below.
Optional; if omitted, the default is miIntersectAll.

Remarks
If the two features do not intersect, the Points collection produced by this method is empty.

The flag argument can be any of the three IntersectionPointConstants values, described
below.

Setting Value Description

miIntersectCrossings 9 This returns the set of points where a line segment
from one feature crosses a line segment from the other
feature, but the features do not have nodes at the
point of crossing.
miIntersectCommon 10 This returns the set of points where a line segment
from one feature intersects a line segment from the
other feature, and both features have a node at the
point of intersection.
miIntersectAll 11 This returns all points where the features cross or
intersect, regardless of whether there are common
nodes at the point of intersection. In other words,
retrieves all of the miIntersectCommon points and all
miIntersectCrossings points.

338 MapInfo MapX Developer Guide v4.5

FeatureFactory.IntersectionTest method (FeatureFactory object)
Purpose
This returns a Boolean value, indicating whether two features satisfy a test of intersection.

Syntax
[Boolean=]OBJECT.IntersectionTest( feature1, feature2, [flag] )

Part Description

OBJECT A FeatureFactory object.

feature1 A Feature object.
feature2 A Feature object.
flag Variant: An IntersectionTestConstants value; see below.
Optional; if omitted, the default is miIntersectFeature.

Remarks
This method tests two features to determine whether they intersect. There are three types of
intersection test; the flag argument controls which type of test is performed.

Setting Value Description

miIntersectCentroidWithinFeature 0 Test returns True if the centroid of

feature1 falls within feature2.
miIntersectFeature 1 Test returns True if the two features
intersect at any point, or if adjacent
features share common nodes.
miIntersectEntirelyWithinFeature 2 Test returns True if feature1 is
entirely inside of feature2.
FeatureFactory Object

340 MapInfo MapX Developer Guide v4.5

 FeatureFactory.IntersectionPoints method (FeatureFactory object)

Field object and Fields collection

A Fields collection is used to describe or define the columnar structure of a data table and is
passed to Datasets.Add to inform MapX which fields from the source data to include in the
Dataset. If Fields collection is not specified, then all fields from the source data will be
included. A Fields collection can also be passed to the Themes. Add method to specify
which fields from an existing Dataset to base a theme on. If there is not a Fields collection
specified, MapX uses the first numeric field. A Fields collection can also be specified as a
parameter of a LayerInfo object passed as an argument/parameter to the Layers.Add
method when the layer being added is of type miLayerInfoTypeTemp or
miLayerInfoTypeNewTab. In this case, the Fields collection specifies the columnar structure
of the new table being created.

Object Properties
• Field.AggregationFunction property
• Field.Decimals property
• Field.Name property
• Field.Precision property
• Field.Width property
• Field.Type property
Note: If the user tries to get a property that isn't available for that type Field object,
MapX throws ERR_PROPERTY_NOT_AVAILABLE (1295).

Collection Properties
• Fields.Count property
• Fields.Item property

Collection Methods
• Fields.Add method
• Fields.AddDateField method
• Fields.AddFloatField method
• Fields.AddIntegerField method
• Fields.AddLogicalField method
• Fields.AddNumericField method
• Fields.AddSmallIntField method
• Fields.AddStringField method
• Fields.Remove method
• Fields.RemoveAll method

MapInfo MapX Developer Guide v4.5 341

Field object and Fields collection

See Also
LayerInfo object

Dataset object

342 MapInfo MapX Developer Guide v4.5

 Field.Decimals property (Field object)

Field.AggregationFunction property (Field object)

Purpose
This property dictates how MapX computes the Field value when multiple data are bound
to the same feature. This is a This is a read-only property, and is set to one of the
AggregationFunctionConstants. It is initialized in the Fields.Add method.

See Also
Fields.Add method

Field.Decimals property (Field object)

Purpose
This read-only property is used to specify a numeric value for the number of decimals in the
field object.

Field.Name property (Field object)

Purpose
This read-only property specifies a field name. It is a String value. This is the default
property for the Field object.

Field.Precision property (Field object)

Purpose
This read-only property specifies the total number of numeric place values in a given Field
object.

Field.Width property (Field object)

Purpose
This read-only property specifies a string length in a given Field object.

MapInfo MapX Developer Guide v4.5 343

Field object and Fields collection

Field.Type property (Field object)

Purpose
The field type. This takes a FieldTypeConstants value. This is a read-only property.

Fields.Add method (Fields collection)

Purpose
This method adds a field to a Fields collection.

Syntax
[ Field= ]OBJECT.Add (DataSourceCol, [Name], [AggregateFunction], [Type])

Part Description

OBJECT Represents a Fields object.

DataSourceCol The column from the data source to use. Can be either the name
or the index of the column.
Name Name of field to add. The default is the field name in the data
source.
AggregateFunction The aggregate function to use. Value:
AggregationFunctionConstants
Type The type of data in column. This takes a FieldTypeConstants
value.

Remarks
A Fields collection is built to use with the Datasets.Add method. The Fields parameter takes
a Fields collection, and is built using this Add method.

The Type parameter is used only with Unbound Datasets. It is ignored for all other Dataset
types.

The aggregate function defaults to miAggregationIndividual for string columns, and

miAggregationSum for numeric columns.

The Add method can not be used on a Dataset's fields collection once the Dataset has been
created.

All field names should be unique in a given fields collection.

344 MapInfo MapX Developer Guide v4.5

 Fields.AddDateField method (Fields collection)

See Also
Datasets.Add method

Dataset.Fields property

Fields.AddDateField method (Fields collection)

Purpose
This method adds a date to the fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

Syntax
OBJECT.AddDateField (name)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the date field.

Fields.AddFloatField (Fields collection)

Purpose
This method adds a float field to a fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

Syntax
OBJECT.AddFloatField (name)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the float filed.

MapInfo MapX Developer Guide v4.5 345

Field object and Fields collection

Fields.AddIntegerField (Fileds Collection)

Purpose
This method adds an integer field to a fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

Syntax
OBJECT.AddIntegerField (name)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the the integer field.

Fields.AddLogicalField method (Fields collection)

Purpose
This method adds a logical field to a fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

Syntax
OBJECT.AddLogicalField (name)

Part Description
OBJECT This represents the Fields collection.
name This is the name of the the logical field.

Fields.AddNumericField method (Fields Collection)

Purpose
This method adds a numeric field to the field collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

346 MapInfo MapX Developer Guide v4.5

Syntax
OBJECT.AddNumericField(name, precision, decimals)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the the numeric field.
precision This is the total number of numeric places.
decimals This is the total decimal places.

Fields.AddSmallIntField method (Fields Collection)

Purpose
This method adds a small integer to the fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.

Syntax
OBJECT.AddSmallInt(name)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the small integer field.

Fields.AddStringField method (Fields collection)

Purpose
This method adds a string field to the fields collection.

Note: This method is specifically intended to be used when a Fields collection is being
passed in a LayerInfo object to Layers.Add.
Field object and Fields collection

Syntax
OBJECT.AddNumericField(name, width)

Part Description

OBJECT This represents the Fields collection.

name This is the name of the the string field.
width This is the specified lenghth of the sting.

Fields.Count property (Fields collection)

Purpose
The number of fields in a Fields collection. This is a read-only property.

Fields.Item property (Fields collection)

Purpose
Retrieve a Fields object from the Fields collection. This takes a parameter to specify which
field. The parameter can specify the field name or index number (1 based index). This is a
default property for the Fields collection.

Fields.Remove method (Fields collection)

Purpose
Removes a specified Field object from the Fields collection.

Note: If you remove an item, the collection indexes are renumbered to fill in the hole
left by the item removed.

Syntax
OBJECT.Remove (index)

Part Description

OBJECT Represents a Fields object.

index Field object name or 1 based index number.

348 MapInfo MapX Developer Guide v4.5

 Fields.Remove method (Fields collection)

Fields.RemoveAll method (Fields collection)

Purpose
Removes all Field objects from the collection.

Syntax
OBJECT.RemoveAll

MapInfo MapX Developer Guide v4.5 349

Field object and Fields collection

350 MapInfo MapX Developer Guide v4.5

Find object

Purpose
The Find object allows you to enter the name of a feature and MapX finds it. You may refine by
using a second polygon table, using street maps, and interpolate positions on the street and
side of the street using an algorithm.

Object Properties
• Find.Abbreviations property
• Find.CloseMatchMax property
• Find.ClosestAddr property
• Find.FindDataset property
• Find.FindField property
• Find.OtherBoundary property
• Find.RefineDataset property
• Find.RefineField property
• Find.RefineLayer property

Object Methods
• Find.Search method
• Find.SearchEx method
Note: The methods above do not work with remote database layers. Use the
Layer.Search method as an alternate means of locating a feature or features
collection on a remote database layer.

Find.Abbreviations property (Find object)

Purpose
This is a read/write boolean property with a default value of TRUE. When TRUE, MapX uses
the abbreviations file (mapx.abb) when it can not exactly match an address it is searching for
with a record in the table. If set to FALSE, MapX does not refer to the abbreviations file.

Remarks
The abbreviations file contains pairs of items such as "STREET ST" and "AVE AV". If the
address to search for contains "STREET" MapX will change it to "ST" and search again.

Find.CloseMatchMax property (Find object)

Purpose
This read/write property returns a FindResult object. That is, when you execute a find via the
Find.SearchEx method, if an exact match(es) can not be found, SearchEx returns as many
close matches as it can find—up to the value specified by this property. The default for this
Find object

property is eight and takes an integer value which must be >= 0 or MapX will throw an
error.

Find.ClosestAddr property (Find object)

Purpose
This Boolean property when set to TRUE will match to the closest house number if a
specified number is not found. For example, if the user asked for 120 ELM ST, but MapX
only knows about 1-100 ELM ST, this would cause MapX to match to 100 ELM ST. The
default is FALSE.

352 MapInfo MapX Developer Guide v4.5

Find.FindDataset property (Find object)
Purpose
Dataset of field to match against. If not specified, a layer's primary key is used.

Find.FindField property (Find object)

Purpose
Field from a dataset to match against. It is used in conjunction with FindDataset property.

See Also
FindDataset property

Find.SearchEx method (Find object)

Purpose
The SearchEx method extends the functionality of the search method. It enables the search
engine to look for the closest matches returned in a collection. A developer might present this
to a user in a list box. Initially a search will try to return an exact match with the parameters
given to the method. If an exact match is not found, then the MatchedFeature will contain
nothing and the FindMatches collection will contain all close FindMatch items found.

Note: This method does not work with remote database layers. Use the Layer.Search
method as an alternate means of locating a feature or features collection on a remote
database layer.

Syntax
[ FindResult= ]OBJECT.SearchEx (Address, [Boundary] )

Part Description
OBJECT Represents a Find object.
Address A string, which is the name of the object or street address that you
want to find. For example, “Rensselaer, 6 Georgian Ct,”,
“London”, or “3 Elm Street”.
Boundary A string, which is the name of the refining boundary object. Used
when a refining layer is specified. For example, “NY”, “12211”.
If a refine layer has been set, this argument is required; otherwise
it is optional.

See Also
FindResult
FindMatches
Find object

FindMatch Find.OtherBoundary property (Find object)

Purpose
This Boolean property applies when a refining boundary is used and controls how MapX
deals with a lack of matches within the refine boundary

When False, Find.Search will only return a match if it is within the refining boundary and
return no match otherwise. When True, Find.Search will first return a match within the
refining boundary; if there are none, it will return a match outside the refining boundary.
The default is False.

See Also
Find.RefineLayer property

Find.Search method

Find.RefineDataset property (Find object)

Purpose
When specifying a RefineLayer, you can use the geocolumn to match, or you can override
by specifying a Dataset and Field to use instead.

Find.RefineField property (Find object)

Purpose
Used in conjunction with RefineDataset.

354 MapInfo MapX Developer Guide v4.5

Find.RefineLayer property (Find object)
Purpose
Layer to refine with. Refinement is useful when there may be multiple matches.

For example, there may be multiple BROADWAYs in a street map - one per ZIP code. You can
use the ZIP Code layer to refine. Then when finding, you specify the street AND ZIP Code.

See Also
Find.RefineField property
Find.RefineDataset property

Find.Search metho (Find object)

Purpose
Searches the layer for a street address or for the name of a feature on the map. It returns a
FindFeature object.

Note: This method above does not work with remote database layers. Use the
Layer.Search method as an alternate means of locating a feature or features
collection on a remote database layer.

Syntax
OBJECT.Search (Address, [ Boundary ] )

Part Description
OBJECT A Find object.
Address A string, which is the name of the object or street address that
you want to find. For example, “Rensselaer, 6 Georgian Ct,”,
“London”, or “3 Elm Street”.
Boundary A string, which is the name of the refining boundary object.
Used when a refining layer is specified. For example, “NY”,
“21135”.
If a refine layer has been set, this argument is required;
otherwise it is optional.

See Also
Find object
FindFeature object
Find object

356 MapInfo MapX Developer Guide v4.5

FindFeature object

The FindFeature object is a super class of the Feature with the addition of a result code
(FindRC).
FindFeature is returned by the search method of the Find object and contains all the properties
of a Feature object and the FindRC property.

Object Properties
• FindFeature.FindRC property

See Also
Feature object

Using the FindFeature object

FindFeature object

FindFeature.FindRC property (FindFeature object)

Purpose
FindRC is the result code of the find operation.

To obtain the X,Y and/or object ID use the properties, CenterX, CenterY, FeatureID (see,
Feature objects). If an address was found FeatureID will be 0.

Digit Values Meaning

**Ones Place**
xx1 Exact match
xx2 A substitution from the abbreviations file used
xx3 ( – ) Exact match not found
xx4 ( – ) No object name specified; match not found
**Tens Place**
x1x Side of street undetermined
x2x ( + / – ) Address number was within min/max range
x3x ( + / – ) Address number was not within min/max range
x4x ( + / – ) Address number was not specified
x5x ( – ) Streets do not intersect
x6x ( – ) The row matched does not have a map object
**Hundreds Place**
1xx ( + / – ) Name found in only one region other than specified region
2xx ( – ) Name found in more than one region other than the specified region
3xx ( + / – ) No refining region was specified, and one match was found
4xx ( – ) No region was specified, and multiple matches were found
5xx ( + ) Name found more than once in the specified region

358 MapInfo MapX Developer Guide v4.5

FindMatch Object and FindMatches Collection

The FindMatch object returns a match item returned from the SearchEx method defining close
matches or exact matches. The FindMatches collection is rated in order of score with best
score first.

Object Properties
• FindMatch.FeatureID property
• FindMatch.FeatureKey
• FindMatch.Name property
• FindMatch.Score property

Collection Properties
• FindMatches.Count property
• FindMatches.Item property

See Also
FindResult object

SearchEx method

FindMatch.Name property (FindMatch object)

Purpose
This property returns the name of the object or street.

FindMatch.FeatureID property (FindMatch object)

Purpose
This property returns the ID of the feature if it exists. If the feature does not exist, a zero is
returned.

FindMatch.FeatureKey property (FindMatch object)

Purpose
This property returns the FeatureKey of the feature if it exists. If it does not exist, an empty
string is returned.
FindMatch Object and FindMatches Collection

FindMatch.Score property (FindMatch object)

Purpose
This property returns the matching score for close matches or zero for no match—100 (exact
match).

FindMatches.Count property (FindMatches collection)

Purpose
This read-only property indicates the number of matches in the collection.

FindMatches.Item property (FindMatches collection)

Purpose
This property returns an item in the FindMatches collection. The items are ordered by their
score in the FindMatches collection (the best score first).

Syntax
[FindMatch=]OBJECT.Item (index)

Part Description

OBJECT Represents a FindMatches collection

index The integer index of the item returned.

360 MapInfo MapX Developer Guide v4.5

FindResult Object

The FindResult object returns information about the FindRC in the form of properties that
make it easier to access the result of the find. FindResult contains a collection of features that
contain either the multiply matched features, or the closest matched features in priority order
of how they scored in the find. If an exact match is found, then the feature collection will only
contain the ExactMatch feature.

Object properties
• FindResult.AddressOutOfRange property
• FindResult.ExactMatch property
• FindResult.FindRC property
• FindResult.IntersectionNotFound property
• FindResult.MatchedFeature property
• FindResult.Matches property
• FindResult.MultipleMatches property
• FindResult.RefineRegion property
• FindResult.Substitute property

See Also
SearchEx method

FindResult.AddressOutOfRange property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the address number is in range.

FindResult.ExactMatch property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if an exact match is found.

See Also
FindResult.MatchedFeature property
FindResult.Matches property

FindResult.MultipleMatches property
FindResult Object

FindResult.FindRC property (FindResult object)

Purpose
This property searches the layer for a street address or for the name of a feature on the map;
returns a FindFeature object. If a negative value is returned, then an exact match was not
found.

362 MapInfo MapX Developer Guide v4.5

 FindResult.MatchedFeature property (FindResult object)

FindResult.IntersectionNotFound property (FindResult object)

Purpose
This read-only property returns a Boolean value of TRUE that indicates whether streets
intersect.

FindResult.MatchedFeature property (FindResult object)

Purpose
This property returns the resulting ExactMatch feature from a Find.SearchEx.

See Also
Find.SearchEx method

FindResult.Matches property (FindResult object)

Purpose
This property returns the resulting Match collection from a Find.SearchEx.

See Also
Find.SearchEx method

FindResult.MultipleMatches property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if multiple matches are found after
performing a Find.SearchEx.

See Also
Find.SearchEx method

FindResult.RefineRegion property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the refining region is specified.

MapInfo MapX Developer Guide v4.5 363

FindResult Object

FindResult.Substitute property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the substitute was used from an
abbreviation file.

364 MapInfo MapX Developer Guide v4.5

Geoset Object and Geosets Collection

The Geoset object is built off the Map object and allows you to define a geoset. A Geoset is a
collection of map layers and their settings. The Geosets collection object is a collection of
Geoset objects.

Object Properties
• Geoset.Centroid property
• Geoset.PathName property
• Geoset.UserName property

Collection Properties
• Geosets.Count property
• Geosets.Item property

See Also
Map object

Geoset.Centroid property (Geoset object)

Purpose
This specifies the Point object defining the geographic center of the geoset.

See Also
Point object

Geoset.PathName property (Geoset object)

Purpose
This specifies the Path defining the physical location of the geoset.

Geoset.UserName property (Geoset object)

Purpose
This specifies the Name defining the geoset.

Geosets.Count property (Geosets collection)

Purpose
This specifies the number of Geoset objects in the collection. This is a read-only property.
Geoset Object and Geosets Collection

Geosets.Item property (Geosets collection)

Purpose
This retrieves a particular Geoset object from a collection. This is a Variant, and you can
specify the Geoset's user name or a 1 based index number. This is a default property for the
Geosets collection.

366 MapInfo MapX Developer Guide v4.5

 Graphic.Caption property (Graphic object)

Graphic Object

Purpose
Each Annotation contains a Graphic object (Annotation.Graphic property) in which the
symbol or text style and location is stored.

Object Properties
• Graphic.Caption property
• Graphic.Position property
• Graphic.Style property
• Graphic.X property
• Graphic.Y property

See Also
Annotation object

Graphic.Caption property (Graphic object)

Purpose
Contains the text string if the annotation is of type miTextAnnotation. This is a String value.

See Also
Annotation.Type property

AnnotationTypeConstants

Graphic.Position property (Graphic object)

Purpose
This contains a value indicating how the text should be drawn with respect to the X,Y
coordinates. This is only used if annotation type is miTextAnnotation. This takes a
PositionConstants value, and defaults to miPositionTL.

See Also
Annotation.Type property

MapInfo MapX Developer Guide v4.5 367

Graphic Object

Graphic.Style property (Graphic object)

Purpose
A Style object containing the style of the symbol or text. This is a read-write property.

See Also
Style object
Annotation.Type

Graphic.X property (Graphic object)

Purpose
Contains the X coordinate of the annotation. This is a double value, and represents the earth
coordinate (longitude). If the annotation type is miTextAnnotation, the position of the
annotation is controlled by the X,Y coordinates in conjunction with the Position property. If
the annotation type is miSymbolAnnotation, the X,Y coordinates refer to the center of the
symbol.

See Also
Annotation.Type property

AnnotationTypeConstants

Graphic.Position property

Graphic.Y property (Graphic object)

Purpose
Contains the Y coordinate of the annotation. This is a double value, and represents the earth
coordinate (latitude). If the annotation type is miTextAnnotation, the position of the
annotation is controlled by the X,Y coordinates in conjunction with the Position property. If
the annotation type is miSymbolAnnotation, the X,Y coordinates refer to the center of the
symbol.

See Also
Annotation.Type property
AnnotationTypeConstants
Graphic.Position property

368 MapInfo MapX Developer Guide v4.5

 IndividualValueCategories.AllOthersCategory property (IndividualValueCategories collec-

IndividualValueCategory object and

IndividualValueCategories collection

An individual-values thematic map's settings are exposed through the

IndividualValueCategories collection, which is a collection of IndividualValueCategory
objects one object for each unique value in the theme.

To obtain an IndividualValueCategories collection, reference the

ThemeProperties.IndividualValueCategories property.

Object Properties
• IndividualValueCategory.NumItems property
• IndividualValueCategory.Style property
• IndividualValueCategory.Value property

Collection Properties
• IndividualValueCategories.AllOthersCategory property
• IndividualValueCategories.Count property
• IndividualValueCategories.Item property

See Also
Legend object

ThemeProperties.IndividualValueCategories property

IndividualValueCategories.AllOthersCategory property (Individu-

alValueCategories collection)
This returns one IndividualValueCategory object from the collection; this object describes a
category for all value ranges not in the individual values theme. The
IndividualValueCategory object returned with the AllOthersCategory property has a Value
property that is not defined and its default value is an empty string (“”). However, you can
set its Style property as shown in the example below. The text that appears in the legend for
the AllOthersCategory range category object can be set with the
LegendTexts.AllOthersText property.

MapInfo MapX Developer Guide v4.5 369

IndividualValueCategory object and IndividualValueCategories collection

IndividualValueCategories.Count property (IndividualValueCate-

gories collection)
Purpose
This is a read-only integer value, indicating the number of unique individual values in the
theme.

370 MapInfo MapX Developer Guide v4.5

IndividualValueCategories.Item property (IndividualValueCatego-
ries collection)
Purpose
This returns one IndividualValueCategory object from the collection; this object describes one
of the unique values in the individual values theme.

IndividualValueCategory.NumItems property (IndividualValueCate-

gories collection)
Purpose
NumItems is the number of features that fall into this category. This is an Integer value and is
a read-only property.

Note: This property is only valid when MapX generates the theme
(Theme.ComputeTheme = TRUE). If you are manually calculating the theme
(Theme.ComputeTheme = FALSE), then NumItems will NOT reflect the number of
items in the category and is undefined as a result.

IndividualValueCategory.Style property (IndividualValueCategories

collection)
Purpose
This controls the style for the category. This is a Style object and may be set to an existing style
object or you may set the style properties individually. The defaults are designed to provide
highly contrasting styles.

See Also
Style object
IndividualValueCategory object and IndividualValueCategories collection

IndividualValueCategory.Value property (IndividualValueCategory

object)
Purpose
This property gets or sets the value of an individual value category in an individual value
theme. The property can only be set when the Theme.ComputeTheme property is set to
FALSE.

Note: Setting the Value property does not affect the Legend.LegendTexts collection for
the theme because it has to be updated separately

Syntax
IndividualValueCategory.Value property

372 MapInfo MapX Developer Guide v4.5

 LabelProperties.DataField property (LabelProperties object)

LabelProperties Object

The LabelProperties object contains properties that control how labels are drawn for the
layer.

Object Properties
• LabelProperties.DataField property
• LabelProperties.Dataset property
• LabelProperties.Duplicate property
• LabelProperties.LabelMax property
• LabelProperties.LabelZoom property
• LabelProperties.LabelZoomMax property
• LabelProperties.LabelZoomMin property
• LabelProperties.LineType property
• LabelProperties.Offset property
• LabelProperties.Overlap property
• LabelProperties.Parallel property
• LabelProperties.PartialSegments property
• LabelProperties.Position property
• LabelProperties.Style property
• LabelProperties.Visible property

See Also
Layer object

LabelProperties.DataField property (LabelProperties object)

Purpose
This property sets the location (i.e. the DataField) used for labels. The field used for labeling
is specified by both this property as well as the Dataset property to indicate which Dataset
to use. This takes a Field object.

See Also
LabelProperties.Dataset property

Field object

MapInfo MapX Developer Guide v4.5 373

LabelProperties Object

LabelProperties.Dataset property (LabelProperties object)

Purpose
This property sets the Dataset to use for labels. The field to use for labeling is specified by
both this property as well as the DataField property to indicate which field in the Dataset to
use. Specifying no Dataset causes the features to get labeled with the feature name. This is
the default behavior. This takes a Dataset object.

See Also
LabelProperties.DataField property

Dataset object

LabelProperties.Duplicate property (LabelProperties object)

Purpose
Controls whether features with the same name can have labels on the map simultaneously.
This is a Boolean value, and the default is False.

LabelProperties.LabelMax property (LabelProperties object)

Purpose
Controls the maximum number of labels that are automatically generated for a layer. This is
an Integer value, and the default is 100.

LabelProperties.LabelZoom property (LabelProperties object)

Purpose
Controls whether labels are zoom layered. Zoom layering controls the range of zoom levels
(distance across map) the labels are displayed. If LabelZooming is on, then the values stored
in the LabelZoomMax and LabelZoomMin properties are used. This is a Boolean value, and
the default is False.

See Also
LabelProperties.LabelZoomMax property
LabelProperties.LabelZoomMin property

374 MapInfo MapX Developer Guide v4.5

 LabelProperties.LineType property (LabelProperties object)

LabelProperties.LabelZoomMax property (LabelProperties object)

Purpose
If label ZoomLayering is on (LabelProperties.LabelZoom property), then this specifies the
maximum zoom value for displaying the labels. This takes a double value specifying
distance in Map units (Map.MapUnit). The labels will appear if the zoom is >= to min and <
max.

See Also
LabelProperties.LabelZoom property

Map.MapUnit property

LabelProperties.LabelZoomMin property (LabelProperties object)

Purpose
If label ZoomLayering is on (LabelProperties.LabelZoom property), then this specifies the
minimum zoom value for displaying the labels. This takes a double value specifying
distance in Map units (Map.MapUnit). The labels will appear if the zoom is >= to min and <
max.

See Also
LabelProperties.LabelZoom property

Map.MapUnit property

LabelProperties.LineType property (LabelProperties object)

Purpose
Controls the type of line to be used to connect the label to the feature being labeled. This is
used when the Offset is large. This takes a LineTypeConstants value, and the default is
miLineTypeNone.

See Also
LabelProperties.Offset property

MapInfo MapX Developer Guide v4.5 375

LabelProperties Object

LabelProperties.Offset property (LabelProperties object)

Purpose
This property specifies the distance between the label and the feature being labeled. This is
useful for symbol features, when you want the label a certain distance away from the
symbol. This is an Integer value, and specifies the distance in pixels. The default is 2.

Note: If the LableProperties.Position property is specified, the LableProperties.Offset is

ignored.

See Also
LabelProperties.Position property

LabelProperties.Overlap property (LabelProperties object)

Purpose
Allow labels to overlap each other when they are drawn on a layer. This is a Boolean value,
and the default is False.

LabelProperties.Parallel property (LabelProperties object)

Purpose
Controls whether to label linear features with the label parallel to the feature. This is a
Boolean value, and the default is True.

LabelProperties.PartialSegments property (LabelProperties

object)
Purpose
Setting this value to true enables MapX to label polylines, even if only a small part of the
polyline is currently visible. However, this will NOT work for other features/objects, as it
only applies to autolabels. This is a Boolean value, and the default is True.

Remarks
This property allows a label to be automatically displayed even if the centroid of the object
is not in the map view. Also, in order for a label to be displayed automatically, its centroid
must be within the viewable map area.

376 MapInfo MapX Developer Guide v4.5

 LabelProperties.Style property (LabelProperties object)

LabelProperties.Position property (LabelProperties object)

Purpose
This property sets how the label should be positioned relative to the map feature. This takes
a PositionConstants value.

The default value depends on the PredominantObjectType:

• miFeatureTypeSymbol is miPositionCL
• miFeatureTypeLine is miPositionBC
• miFeatureTypeRegion is miPositionCC

LabelProperties.Style property (LabelProperties object)

Purpose
This property sets the style used to display the labels. The default is 10 point Helvetica.

LabelProperties.Visible property (LabelProperties object)

Purpose
Controls whether labels are visible for the layer. Labels can be created using the
Layer.Autolabel property, or manually using the Layer.LabelAtPoint method or using the
Label tool. This Visible property controls whether all labels for the layer are visible. This
takes a Boolean value, and the default is True.

MapInfo MapX Developer Guide v4.5 377

LabelProperties Object

378 MapInfo MapX Developer Guide v4.5

 LabelProperties.Visible property (LabelProperties object)

Layer Object and Layers Collection

Each Map has a collection of layers. The Layers collection is made up of Layer objects. The
Layers collection has methods and properties used to add and remove Layer objects from
the collection.

Computer maps are organized into layers. Think of the layers as transparencies that are
stacked on top of one another. Each layer contains different aspects of the entire map. Each
layer contains different map objects, such as regions, points, lines and text.
For example, one layer may contain state boundaries, a second layer may have symbols that
represent capitals, a third layer might consist of text labels. By stacking these layers one on
top of the other, you begin to build a complete map. You can display multiple layers at a
time. Map layers form the building blocks of maps in MapX. Once you have created your
map of layers, you can customize the layers in a variety of ways, add and delete layers, or
reorder them.

You can set the following layer options by using the commands and properties in the Layers
collection and Layer object, and LabelProperties object.

Reordering Layers
Map layers display in a particular order. It is important to order your layers correctly. For
example, you have a layer of customer points and a layer of census tracts. If the layers ar
incorrectly ordered in the map window, MapX might draw the customer points first and
then display the census tract layer second. Your points would be obscured beneath the
census tract layer

Zoom Layering
Sometimes you want a map layer to display only at certain zoom levels. Zoom Layering
controls the display of a map layer only when the map's zoom level falls within a preset
distance.

For example, you have a layer of streets and a layer of ZIP Code boundaries. When you
zoom out past 10 or so miles, the streets look like a black smudge in the window. This is
because the zoom (window width) is too wide to show detailed street maps. Use Zoom
Layering to prompt MapX to display the street layer only when the zoom is set to distance
that allows you to see the street detail properly, for instance, less than 5 miles.

MapInfo MapX Developer Guide v4.5 379

Layer Object and Layers Collection

The first map doesn't have zoom layering set for its street layer. At a zoom of 15 miles
across, notice how difficult it is to see any detail. The second map has zoom layering set to
display the streets when the zoom is less than five miles. Therefore, the streets layer does not
display when the window is set at 15 miles.

You can set a different zoom layering level for each layer.

Object Properties
• Layer.AutoLabel property
• Layer.Bounds property
• Layer.CoordSys property
• Layer.Datasets property
• Layer.DrawLabelsAfter property
• Layer.Editable property
• Layer.FileSpec property
• Layer.Find property
• Layer.KeyField property
• Layer.LabelProperties property
• Layer.Name property
• Layer.OverrideStyle property
• Layer.PredominantFeatureType property
• Layer.Selectable property
• Layer.Selection property
• Layer.ShowNodes property
• Layer.ShowCentroids property
• Layer.ShowLineDirection property
• Layer.Style property
• Layer.Type property
• Layer.Visible property
• Layer.ZoomLayer property
• Layer.ZoomMax property
• Layer.ZoomMin property

Object Methods
• Layer.AddFeature method
• Layer.AllFeatures method
• Layer.BeginAccess method
• Layer.ClearCustomLabels method
• Layer.DeleteFeature method
• Layer.DrilldownAddFeatures method
• Layer.DrilldownRemoveFeatures method
• Layer.DrilldownReset method
• Layer.EndAccess method
• Layer.FeatureIDFromFeatureName method
• Layer.FeatureKeyFromFeatureName method
• Layer.GetDrilldownFeaturesByID method

380 MapInfo MapX Developer Guide v4.5

 Layer.AddFeature method (Layer object)

• Layer.GetFeatureByID method
• Layer.GetFeatureByKey method
• Layer.Invalidate method
• Layer.LabelAtPoint method
• Layer.NoFeatures method
• Layer.Refresh method
• Layer.Search method
• Layer.SearchAtPoint method
• Layer.SearchWithinDistance method
• Layer.SearchWithinFeature method
• Layer.SearchWithinRectangle method
• Layer.UpdateFeature method

Collection Properties
• Layers.AnimationLayer property
• Layers.Bounds property
• Layers.Count property
• Layers.InsertionLayer property
• Layers.Item property

Collection Methods
• Layers.Add method
• Layers.AddGeosetLayers method
• Layers.AddServerLayer method
• Layers.AddUserDrawLayer method
• Layers.ClearSelection method
• Layers.CreateLayer method
• Layers.LayersDlg method
• Layers.Move method
• Layers.Remove method
• Layers.RemoveAll method

See Also
Map Object

Layer.AddFeature method (Layer object)

Purpose
This method creates and returns a new feature in the layer with the properties of the Source
object feature. This method is useful for Object Editing.

MapInfo MapX Developer Guide v4.5 381

Layer Object and Layers Collection

Syntax
[feature=]OBJECT.AddFeature (Source, [RowValues])

Part Description

OBJECT Represents a Layer object.

Source Source is a Feature object.
RowValues RowValues represents the new values of the attribute data, for one row
of data. Each value in the RowValues collection corresponds to one
column of attribute data. This parameter is ONLY applicable to a
Dataset of type miDatasetLayer.

See Also
Layer.AllFeatures method

Layer.DeleteFeature method

Layer.Invalidate method
Layer.NoFeatures method

Layer.SearchAtPoint method

Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method

Layer.UpdateFeature method

Feature.FeatureKey property

Layer.AllFeatures method (Layer object)

Purpose
This returns a features object with all features from the layer.

Syntax
[ Features= ]OBJECT.AllFeatures

See Also
Layer.AddFeature method

Layer.DeleteFeature method

382 MapInfo MapX Developer Guide v4.5

 Layer.AutoLabel property (Layer object)

Layer.Invalidate method

Layer.NoFeatures method

Layer.SearchAtPoint method

Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method

Layer.UpdateFeature method

Layer.AutoLabel property (Layer object)

Purpose
Controls whether a layer is automatically labeled. This is a Boolean value, and the default is
False.

Layer.BeginAccess method (Layer object)

Purpose
This method will open and lock the table for read/write access. This improves the
performance for repeated layer and Dataset operations. You must call Layer.EndAccess
once for each call to Layer.BeginAccess.

Syntax
OBJECT.BeginAccess (BeginAccessType)

Part Description

OBJECT Represents a Layer object.

BeginAccessType One of the LayerBeginAccessConstants, specifying the type of
access (e.g. read-only or read/write).

Remarks
MapX programs written without using BeginAccess and EndAccess will work as before, but
without the performance enhancement for multiple operations.

You may nest calls to BeginAccess, however, only the first one has any effect.

MapInfo MapX Developer Guide v4.5 383

Layer Object and Layers Collection

See Also
Layer.EndAccess

Layer.Bounds property (Layer object)

Purpose
This returns a Rectangle object representing the geographic extents (i.e. the minimum
bounding rectangle) of all objects in the layer; does not apply to user draw layers.

Remarks
This property is useful if you want to zoom the map out far enough to show all objects in
one layer.

See Also
Layers.Bounds

Layer.CoordSys property (Layer object)

Purpose
This returns a read-only CoordSys object, indicating the coordinate system in which the
layer was saved.

See Also
CoordSys object

Map.DisplayCoordSys

Map.NumericCoordSys

Layer.ClearCustomLabels method (Layer object)

Purpose
Removes any labels placed on the current layer.

Syntax
OBJECT.ClearCustomLabels

384 MapInfo MapX Developer Guide v4.5

 Layer.DeleteFeature method (Layer object)

Layer.Datasets property (Layer object)

Purpose
This read-only property is a Datasets collection that is bound to the map layer it is
associated with. This collection is a subset of the full Datasets collection (Map.Datasets).
The objects within Layer.Datasets are the same as the objects within Map.Datasets.

Remarks
Layers that do not have Datasets (such as Raster and UserDraw) will return an empty
collection.

Layer.Datasets will not support the Add or Restore methods. An exception is thrown if
either are used.

Adding a Dataset to Map.Datasets via Datasets.Add also adds that Dataset to the Datasets
collection of the layer it is bound to. Removing a Dataset from a Layer.Dataset collection,
also removes it from Map.Datasets, and vice versa.

See Also
Datasets.Add method

Map.Datasets

Layer.DeleteFeature metho (Layer object)

Purpose
Deletes the feature and its database row from the layer.

Syntax
OBJECT.DeleteFeature (FeatureKey)

Part Description

OBJECT Represents a Layer object.

FeatureKey The Feature object to delete. This is a replacement for FeatureID
parameter. FeatureID still works as it did before, but it is recommended
that you use the new FeatureKey parameter. The FeatureKey is used to
identify a unique record in a table. In previous versions, the FeatureID
was used for this purpose, but it did not work correctly for seamless and
remote layers. The FeatureKey property works for all layer types.

MapInfo MapX Developer Guide v4.5 385

Layer Object and Layers Collection

See Also
Layer.AddFeature method

Layer.AllFeatures method

Layer.Invalidate method

Layer.NoFeatures method

Layer.SearchAtPoint method

Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method

Layer.UpdateFeature method

Layer.DrawLabelsAfter property (Layer object)

Purpose
Boolean. When set to True, the labels for all layers from the bottom layer (or the last layer
with this property set) up to and including the layer itself are drawn after the layer is drawn.
This allows for better control over where labels are in the drawing order.

By default, layers have this property set to False, and the labels are drawn after the topmost
layer, but before any animation layer.

Layer.DrilldownAddFeatures method (Layer object)

Purpose
Adds features to a Drilldown layer.

Syntax
OBJECT.DrilldownAddFeatures (Level, FeatureKeys)

Part Description
OBJECT A Layer object that corresponds to a Drilldown layer.
Level String, indicating which level in the Drilldown layer contains the
features that are to be added.

386 MapInfo MapX Developer Guide v4.5

 Layer.DrilldownRemoveFeatures method (Layer object)

Part Description

FeatureKeys Variant: A string or an array of strings, identifying the Drilldown IDs of

the features that should be added. Note that these are Drilldown IDs (i.e.
values from a column in the Drilldown component table), not the MapX
Feature's internal FeatureID values.

Remarks
This method does not actually alter the contents of any tables. The features that you are
adding are already in a table; by "adding" them to the layer, you make them visible.

Layer.DrilldownRemoveFeatures method (Layer object)

Purpose
Removes features from a Drilldown layer.

Syntax
OBJECT.DrilldownRemoveFeatures (Level, FeatureKeys)

Part Description

OBJECT A Layer object that corresponds to a Drilldown layer.

Level String, indicating which level contains the features to remove.
FeatureKeys Variant: A string or an array of strings, identifying the Drilldown
IDs of the features that should be removed. Note that these are the
IDs specified in the Drilldown table's first column, not the MapX
Feature's internal FeatureID values.

Remarks
Method does not actually alter the contents of any tables. The features that you ar
removing are not deleted from the table; by "removing" them, you simply make them
disappear.

MapInfo MapX Developer Guide v4.5 387

Layer Object and Layers Collection

Layer.DrilldownReset method (Layer object)

Purpose
Clears all features from the Drilldown layer, and reinitializes the layer using features from a
single level.

Syntax
OBJECT.DrilldownReset (Level)

Part Description
OBJECT A Layer object that corresponds to a Drilldown layer.
Level String, indicating which level of detail should appear in the
Drilldown layer. If the string is empty, the layer will be cleared (all
objects will be removed from the Drilldown layer).

Remarks
This method resets the Drilldown layer so that it only shows features from one specific level.
You might use this method if you want to provide a "Reset" button, which restores the
Drilldown layer to its original state.

Layer.Editable property (Layer object)

This property allows a selection in the layer to be edited (moved, resized, or deleted). The
ArrowTool can be used to move or resize selected objects. The delete key deletes selected
objects.

Layer.EndAccess method (Layer object)

Purpose
The EndAccess method unlocks map tables. You must call Layer.EndAccess once for each
call to Layer.BeginAccess.

388 MapInfo MapX Developer Guide v4.5

 Layer.FeatureIDFromFeatureName method (Layer object)

Syntax
OBJECT.EndAccess (endAccessType)

Part Description

OBJECT Represents a Layer object.

endAccessType One of the LayerEndAccessConstants, specifying the end access
type.

Remarks
If Layer.BeginAccess was called with a beginAccessType of miAccessRead or
miAccessReadWrite, the EndAccessType parameter must be miAccessEnd.
MapX programs written without using BeginAccess and EndAccess will work as before, but
without the performance enhancement for multiple operations.

See Also
BeginAccess method

Layer.FeatureIDFromFeatureName method (Layer object)

Given a name, this method returns the ID of the feature with that name (returns the ID of the
first feature with the specified name if the name is not unique within the layer). The name is
currently defined to be the value in the first column of the MapInfo table. It throws an
exception if there is no feature with the name specified.

Syntax
[int=]OBJECT.FeatureIDFromFeatureName (Name)

Part Description

OBJECT Represents a Layer object.

Name A string which is the name of the feature whose ID you want to get.

MapInfo MapX Developer Guide v4.5 389

Layer Object and Layers Collection

Layer.FeatureKeyFromFeatureName method (Layer object)

Purpose
This method returns a FeatureKey from the FeatureName in a Layer object. MapX searches
to Layer.KeyField for the first row containing the name in the KeyValue parameter. If the
KeyValue is NOT found, MapX throws error #1205. Otherwise, it returns the FeatureKey of
the new row it found.

Syntax
[BSTR=]OBJECT.FeatureKeyFromFeatureName (KeyValue)

Part Description

OBJECT Represents a Layer object.

KeyValue The name of the feature and the value to search for.

REmarks
This method is not applicable for remote database layers (ODBC or OCI). Use the
Layer.Search method as an alternate means of locating a feature or features collection for a
remote database layer.

See Also
Layer.KeyField property

Layer.FileSpec property (Layer object)

Purpose
This property contains the full file specification of where the layer is physically stored. This
is a String value, and is read-only.

Layer.Find property (Layer object)

Purpose
This property defines the Find object for the layer

390 MapInfo MapX Developer Guide v4.5

 Layer.GetFeatureByID method (Layer object)

Layer.GetDrilldownFeaturesByID metho (Layer object)

Purpose
This method returns a Feature object, given the feature's ID.

Syntax
[Feature=]OBJECT.GetDrilldownFeaturesByID( strLevel, FeatureID)

Part Description

OBJECT Represents a Layer object.

strLevel The name of a level in the Drilldown layer.
FeatureID A string or an array of strings, identifying which feature(s) to query.

Layer.GetFeatureByID metho (Layer object)

Purpose
This method returns a Feature object, given the feature's ID.

Syntax
[Feature=]OBJECT.GetFeatureByID( FeatureKey )

Part Description

OBJECT A Layer object.

FeatureKey A string that identifies the feature. This is the value returned by
Feature.FeatureKey property. This is a replacement for Feature.FeatureID
, which still works as it did before, but it is recommended that you use the
new FeatureKey property.
The FeatureKey property is used to identify a unique record in a table. In
previous versions, the FeatureID property was used for this purpose, but it
did not work correctly for seamless and remote layers. The FeatureKey
property works for all layer type .

MapInfo MapX Developer Guide v4.5 391

Layer Object and Layers Collection

Layer.GetFeatureByKey method (Layer object)

Purpose
This method returns a feature object with a given key in a Layer object.

Syntax
[Feature=]OBJECT.GetFeatureByKey (FeatureKey)

Part Description

OBJECT This represents a Layer object.

FeatureKey A string that identifies the feature. This is the value returned by
Feature.FeatureKey property. The FeatureKey is used to identify a unique
record in a table. In previous versions, the FeatureID property was used for
this purpose, but it did not work correctly for seamless and remote layers.
The FeatureKey property works for all layer types.

See Also
Feature.FeatureKey property

Layer.Invalidate method (Layer object)

Purpose
This method causes the rectangle (in container screen coords) to be redrawn.

Syntax
OBJECT.Invalidate ([InvalidRect])

Parts Description

OBJECT This represents a Layers object.

InvalidRect This represents the rectangle.

See Also
Layer.AddFeature method

Layer.AllFeatures method

Layer.DeleteFeature method

Layer.NoFeatures method

Layer.SearchAtPoint method

392 MapInfo MapX Developer Guide v4.5

 Layer.KeyField property (Layer object)

Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method

Layer.UpdateFeature method

Layer.KeyField property (Layer object)

Purpose
This string property identifies the column (field) name in the layer's MapInfo table that will
be set or retrieved by the KeyValue property of a feature object. It currently defaults to the
first column in the layer's table. This property does not apply to raster or userdraw layers.
An error is raised if you try to set the KeyField to an invalid field name.

Layer.LabelAtPoint method (Layer object)

Purpose
Labels a particular object at a point.

Syntax
OBJECT.LabelAtPoint (x, y)

Part Description

OBJECT Represents a Layer object.

x X map coordinate of point (double value).
y Y map coordinate of point (double value).

Layer.LabelProperties property (Layer object)

Purpose
This read-only property returns the layer's LabelProperties object. The LabelProperties
object is used to control the appearance of labels for the layer.

MapInfo MapX Developer Guide v4.5 393

Layer Object and Layers Collection

See Also
LabelProperties object

Layer.AutoLabel property

Layer.Name property (Layer object)

Purpose
This property contains the name of the layer. A name is given to the layer when added.

Layer.NoFeatures method (Layer object)

Purpose
This returns an empty features object for the layer.

Syntax
OBJECT.NoFeatures()

See Also
Layer.AddFeature method

Layer.AllFeatures method
Layer.DeleteFeature method

Layer.Invalidate method

Layer.SearchAtPoint method
Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method
Layer.UpdateFeature method

394 MapInfo MapX Developer Guide v4.5

 Layer.PredominantFeatureType property (Layer object)

Layer.OverrideStyle property (Layer object)

Purpose
Controls whether the style for the map features should be overridden using the Style
property. This is a Boolean value, and the default is False.

See Also
Layer.Style property

Layer.PredominantFeatureType property (Layer object)

Purpose
A read-only property that returns an integer representing one of the FeatureTypeConstants.
It is used to determine which type of feature is most prevalent in a layer.

Remarks
If the layer has an equal number of features of more than one type (eg 2 symbols and 2
regions) then predominantFeatureType uses this order of precidence to determine what to
return.

• symbol
• line
• region
• misc

Layer.Refresh metho (Layer object)

Purpose
This method flushes the cache from the layer. This is useful for server layers that have
caching turned on.

Syntax
OBJECT.Refresh

See Also
LayerInfo object

MapInfo MapX Developer Guide v4.5 395

Layer Object and Layers Collection

Layer.Search method (Layer object)

Purpose
The Layer.Search method exposes the power of SQL queries. The expression (the "where-
clause" portion of the statement) is evaluated for each row in the Layers table, and a
Features collection is returned, made up of every feature for which the expression is true.

Syntax
[ Features collection= ]OBJECT.Search (strWhere, [Variables])

Part Description

OBJECT Represents a Layer object.

strWhere String: An expression to evaluate for each feature.
Variables Variant: This is an optional parameter. If specified, it must be a
Variables object. When an expression interacts with an unresolved
identifier it will try to resolve it in the Variables collection.

Remarks
Layer.Search will not work on raster, seamless, or userdraw tables. If an expression uses an
identifier that is not a Dataset field name or a variable found in the variables collection,
Layer.Search will throw an exception.
If you use a string value in either a Boolean 'AND', 'OR', or 'NOT' expressesion, the string is
considered "True" if it has at least one character in it, and "False" if it is of zero length.

When specifying dates as string constants, the following applies:

• Dates consist of a month, a day, and an optional year.

• The year must be specified by four digits.
• The entire date string should be enclosed in double quotes.
• The components of a date can be separated by hyphens or slashes.

See Also
Creating Expressions
IDispatch Table

Geographic Operators

Variables object and Variables collection

396 MapInfo MapX Developer Guide v4.5

 Layer.Refresh method (Layer object)

Layer.SearchAtPoint method (Layer object)

Purpose
This returns Features collection object.

• Regions - if the point is within the region, the region is in the resulting collection.
• Lines and Symbols - The closest point(s) or line(s) (can be multiple if many points
have same coordinates) within a 3 pixels area around the given point are added to
the resulting collection.

Syntax
OBJECT.SearchAtPoint (Point)

Part Description

OBJECT This represents a Layer object.

Point X or Y map coordinates of a given point location.

See Also
Layer.AddFeature method

Layer.AllFeatures method

Layer.DeleteFeature method

Layer.Invalidate method

Layer.NoFeatures method

Layer.SearchWithinDistance method

Layer.SearchWithinFeature method

Layer.SearchWithinRectangle method
Layer.UpdateFeature method

MapInfo MapX Developer Guide v4.5 397

Layer Object and Layers Collection

Layer.SearchWithinDistance method (Layer object)

Purpose
Searches for map features within a specified distance, and returns search results as a
Features collection.

Syntax
OBJECT.SearchWithinDistance(Source, double Distance, short Units, short SearchType)

Part Description
OBJECT Represents a layer object.
Source A Point object or a Feature object, representing the origin of the
search.
Distance The distance to search, in the map units specified by the Units
parameter.
Units A MapUnitConstants value, such as miUnitMile (0), that
identifies the unit of measure for the Distance argument.
SearchType A SearchTypeConstants value; controls the search criteria that are
used to determine whether a feature is ”within” the search area.

Remarks
This method creates a buffer region around the source object, then searches within the buffer
region. After the search has been performed, the buffer is discarded; if you need to save the
buffer, use the BufferFeatures method instead.

The resolution of the buffer region (i.e. the number of nodes) is controlled by the
Map.DefaultConversionResolution property.

See Also
Layer.AddFeature method
Layer.UpdateFeature method
Layer.DeleteFeature method
Layer.Invalidate method
Layer.SearchWithinFeature method
Layer.SearchWithinRectangle
Layer.SearchAtPoint method
Layer.AllFeatures method
Layer.NoFeatures method

398 MapInfo MapX Developer Guide v4.5

 Layer.Refresh method (Layer object)

Layer.SearchWithinFeature metho (Layer object)

Purpose
This method returns a Features collection of the feature it is searching within.

Syntax
OBJECT.SearchWithinFeature (Feature, SearchType)

Part Description

OBJECT Represents a Layer object.

Feature Feature object to use as basis of search.
SearchType SearchType is miSearchTypeCentroidWithin,
miSearchTypePartiallyWithin, or miSearchTypeEntirelyWithin.

See Also
Selection.SelectByRegion method

Layer.AddFeature method

Layer.AllFeatures method

Layer.DeleteFeature method

Layer.Invalidate method

Layer.NoFeatures method

Layer.SearchAtPoint method

Layer.SearchWithinDistance method

Layer.SearchWithinRectangle method
Layer.UpdateFeature method

MapInfo MapX Developer Guide v4.5 399

Layer Object and Layers Collection

Layer.SearchWithinRectangle metho (Layer object)

Purpose
This returns Features collection within bounds of specified Rectangle.

Syntax
OBJECT.SearchWithinRectangle (Rectangle, SearchType)

Part Description

OBJECT Represents a Layer object.

Rectangle Feature object to use as basis of search.
SearchType SearchType is miSearchTypeCentroidWithin,
miSearchTypePartiallyWithin, miSearchTypeEntirelyWithin.

See Also
Layer.AddFeature method

Layer.AllFeatures method

Layer.DeleteFeature method

Layer.Invalidate method

Layer.NoFeatures method

Layer.SearchAtPoint method

Layer.SearchWithinDistance method
Layer.SearchWithinFeature method
Layer.UpdateFeature method

Layer.Selectable property (Layer object)

Purpose
Controls whether layer is selectable using the selection tools. This property does not affect
the selection process using the automation methods in the Selection collection. This is a
Boolean value, and the default is On/True.

400 MapInfo MapX Developer Guide v4.5

 Layer.ShowNodes property (Layer object)

Layer.Selection property (Layer object)

Purpose
A collection of selected features for the layer.

See Also
Selection collection

Layer.ShowNodes property (Layer object)

Purpose
This read/write property draws a small box around the node of an object when true. Its
default is false.

Layer.ShowCentroids property (Layer object)

Purpose
This read/write property draws object centroids (regions only) when set to true. Its default
is false.

Layer.ShowLineDirection property (Layer object)

Purpose
This read/write property draws an arrow indicating line direction (lines and poly lines
only) when set true. Its default is false.

Layer.Style property (Layer object)

Purpose
The style object used to override the appearance of all features in the layer on the map. The
Style object is retrieved and filled with the new requested override values. This style is used
if the Override property is set to True.

See Also
Layer.OverrideStyle property

MapInfo MapX Developer Guide v4.5 401

Layer Object and Layers Collection

Layer.Type property (Layer object)

Purpose
This ia a read only property that returns an integer corresponding to one of the
LayerTypeConstants:

• miLayerTypeNormal = 0
• miLayerTypeRaster = 2
• miLayerTypeSeamless = 4
• miLayerTypeUnknown = 5
• miLayerTypeUserDraw = 6

Layer.UpdateFeature metho (Layer object)

Purpose
This updates the target feature in the layer to have the properties of the Source feature. This
method is useful for object editing.

Syntax
OBJECT.UpdateFeature (FeatureKey, [Source], [RowValues])

Part Description

OBJECT Represents a Layer object.

FeatureKey The Feature object to update. This is a replacement for
FeatureID parameter. FeatureID still works as it did before, but
it is recommended that you use the new FeatureKey parameter.
The FeatureKey is used to identify a unique record in a table. In
previous versions, the FeatureID property was used for this
purpose, but it did not work correctly for seamless and remote
layers. The FeatureKey property works for all layer types.
Source The Feature object to take the properties from. The default is
Target.
RowValues RowValues represents the new values of the attribute data, for
one row of data. Each value in the RowValues collection
corresponds to one column of attribute data. This parameter is
ONLY applicable to a Dataset of type miDatasetLayer.

402 MapInfo MapX Developer Guide v4.5

 Layer.UpdateFeature method (Layer object)

Remarks
When the Computetheme property is set to false that the legend.showemptyranges
property must be set to true in order for the theme's legend text(s) to be visible.

This is because MapX does not calculate theme category counts when computetheme is set
to false.

See Also
RowValue object and RowValues collection
Feature object

MapInfo MapX Developer Guide v4.5 403

Layer Object and Layers Collection

Layer.Visible property (Layer object)

Purpose
This controls whether the layer is visible or not. This is a Boolean value, and the default is
True.

Layer.ZoomLayer property (Layer object)

Purpose
This controls whether the layer is zoom layered. Zoom layering controls the range of zoom
levels (distance across map) for which the layer is displayed. If Zoom Layering is on, then
the values stored in the ZoomMax and ZoomMin properties are used. This is a Boolean
value, and the default is False.

See Also
Layer.ZoomMin property

Layer.ZoomMax property

Layer.ZoomMax property (Layer object)

Purpose
If ZoomLayering is on (Layer.ZoomLayer property), then this specifies the maximum zoom
value for which a layer will be drawn on the map. This takes a double value specifying
distance in Map units (Map.MapUnit).

See Also
Layer.ZoomLayer property

Map.MapUnit property

Layer.ZoomMin property (Layer object)

Purpose
If ZoomLayering is on (Layer.ZoomLayer property), then this specifies the minimum zoom
value for which a layer will be drawn on the map. This takes a double value specifying
distance in Map units (Map.MapUnit).

404 MapInfo MapX Developer Guide v4.5

 Layers.Add method (Layers collection)

See Also
Layer.ZoomLayer property

Map.MapUnit property

Layers.Add method (Layers collection)

Purpose
This method creates a layer object for a specified file, adds it to the collection, and displays it
on the map.

Syntax
[Layer=]OBJECT.Add (LayerInfo, [Position])

Part Description

OBJECT Represents a Layers object.

LayerInfo Variant: This can be either a LayerInfo object or a Pathname of the
MapInfo table (.TAB) file to be added as a layer.
Position Variant: Its initial position in the layer list. If omitted or 0, the auto layer
positioning algorithm is used.

Remarks
The layer is positioned automatically with respect to other layers in the map. For example,
the layer with points is placed above a layer with regions.

If a string is passed for the LayerInfo parameter, it is treated as a file specification with the
following interpretation:

• .tab extension is treated as a .tab file.

• Any other extension is treated as a self-registering raster file.
• No extension is treated as a geodictionary user name.
Duplicate layer names are no longer allowed in MapX. When a developer explicitly
specifies a layer name ( as in the "name" parameter of the LayerInfo object,
Layers.AddUserDrawLaye , and Layers.AddServerLaye , an exception will be thrown if
the name is not unique.

When the type property of LayerInfo is 'NewTab' and the 'Fields' parameter has a 'string'
field of length 255 or greater, an exception will be thrown. The field length is based upon
the 254 length limit of MapInfo Professional.

MapInfo MapX Developer Guide v4.5 405

Layer Object and Layers Collection

Layers.AddGeosetLayers metho (Layers collection)

Purpose
This method is included for backwards compatibility. It is highly recomended that you do
NOT use this method. The preferred method for performing the same function is simply the
Layers.Add method with the LayerInfo object passed as an argument. However, this
method adds the specified GeoSet to the current map and creates Layer objects for each
layer specified in the GeoSet that is not already in the Layers collection.

Syntax
OBJECT.AddGeosetLayers (GeosetName)

Part Description
OBJECT Represents a Layers object.
GeosetName Geoset 'friendly' name or full file specification.

See Also
Map.Geoset property

Layers.AddServerLayer method (Layers collection)

Purpose
This method is included for backwards compatibility. It is highly recomended that you do
NOT use this method. The preferred method for performing the same function is simply the
Layers.Add method with the LayerInfo object passed as an argument. This allows you to
specify that the layer is a server layer and to control the cache and MBR search and adds
remote spatial data to the map (i.e. a layer of features retrieved from a remote database, such
as Oracle or Informix).

406 MapInfo MapX Developer Guide v4.5

Syntax
[Layer=]OBJECT.AddServerLayer (Name, ConnectString, Query, [ Position ],
[ServerLayerOptions] )

Part Description

OBJECT A Layers collection object.

Name A string indicating the name of the layer to create (e.g. ”Highways”).
ConnectString An ODBC connection string, which specifies connection information
such as host name, password, etc. If the string does not provide all
necessary information, the ODBC data source displays a connection
dialog. You can re-use connections, thus avoiding redundant
connection dialogs. If you pass a complete connection string that
matches an existing string in the current connection pool, that
connection will be shared by the two tables. The password does not
need to be in the connection string for the two strings to match.
Query A string that specifies a GISSQL/Server-specific SQL query.
Position Optional: The position in the list of layers. To make this layer the top
layer in the map, specify 1 (one).
ServerLayerOptions Optional: Accepts a bitwise OR of the LayerSrvLayerOptions values,
which control the behavior of the server layer. The default value is
(miLayerCacheOn OR miMBRSearchOn). The reason for this
distinction is that while in VB, the OR operator is used for both
logical and bitwise OR, C++ has different operators for each.
Someone embedding MapX in a C++ app should know the correct
OR to use.This allows control of certain behavior of a server layer
(presently the cache and the MBRsearch options). It does not take a
Boolean. It takes a set of flags (bitmask) as described below. Use the
enumerated values provided and simply OR them together to define
the SrvLayerOptions value before calling AddServerLayer

The following table summarizes the effect of the Options parameter. The constants can be
bitwise "or-ed" together to combine options.
miLayerCacheOn Attributes and objects which have been read in will be kept in
memory. This will make map interaction (such as zooming,
labeling, themes and panning) faster. However, the latest
updates to the data will not be shown until Layer.Refresh is
called.
miLayerCacheOff All data will be fetched from the database each time the layer
is drawn. This will be less efficient, but it will give the most
up to date data.
miLayerMBRSearchOn This will cause an MBRSearch predicate to be added to the
spatial query when retrieving the data.
Layer Object and Layers Collection

miLayerMBRSearchOff Turns off the MBRSearch predicate that is appended to the

query when the Map is drawn. This is useful for queries which
already contain a spatial predicate and where an additional
spatial predicate should be avoided.

Remarks
Duplicate layer names are no longer allowed in MapX. When a developer explicitly
specifies a layer name ( as in the "name" parameter of the LayerInfo object,
Layers.AddUserDrawLaye , and Layers.Add), an exception will be thrown if the name is
not unique.

This adds ODBC layers ONLY. Oracle Spatial layers must be added via Layers.Add with the
LayerInfo object.

See Also
Layers.Add

LayerInfo object

Layers.AddUserDrawLayer metho (Layers collection)

Purpose
This method is included for backwards compatibility. It is highly recomended that you do
NOT use this method. The preferred method for performing the same function is simply the
Layers.Add method with the LayerInfo object passed as an argument. However, this
method adds a layer that the container application is responsible for drawing to. It is used in
conjunction with the DrawUserLayer event, which is fired when the layer needs to get
drawn. This returns newly created Layer object.

Syntax
OBJECT.AddUserDrawLayer (Name, Position)

Part Description
OBJECT Represents a Layers object.
Name Name of layer to create.
Position Where to add the layer in the layer list.

408 MapInfo MapX Developer Guide v4.5

 Layers.AnimationLayer property (Layers collection)

Remarks
Duplicate layer names are no longer allowed in MapX. When a developer explicitly
specifies a layer name ( as in the "name" parameter of the LayerInfo object,
Layers.AddServerLaye , and Layers.Add), an exception will be thrown if the name is not
unique.

Layers.AnimationLayer property (Layers collection)

The animation layer is useful where map features need to be updated frequently, such as in
real-time applications. For example, you can develop a fleet-management application that
represents each vehicle as a point object. You can receive current vehicle coordinates by
using GPS (Global Positioning Satellite) technology, and then update the point objects to
show the current vehicle locations on the map. In this type of application, where map
objects are constantly changing, the map redraws much more quickly if the objects being
updated are stored in the animation layer instead of a conventional layer.

Initially AnimationLayer is set to null. You can assign a Layer object to the property to make
that Layer the animation layer (it can be a regular layer or user draw layer). When a layer is
assigned to the AnimationLayer property, it is drawn on top of all layers, including the
annotations layer and selections. The layer is still in the same position in the layers
collection. Floating objects like legends are still displayed on top of the animation layer,
although they don't have to be re-drawn each time because they are clipped out. If a normal
layer is used as the animation layer, selections and labeling will still work.

To turn off the animation layer, you assign null to it:

Set Map.Layers.AnimationLayer = nothing

This turns the layer back into a normal layer, which is still positioned in the same place in
the layer list.

MapInfo MapX Developer Guide v4.5 409

Layer Object and Layers Collection

Layers.Bounds property (Layers collection)

Purpose
This returns a Rectangle object representing the geographic extents of all layers in the
collection (except the UserDraw layer).

Remarks
This property is useful if you want to zoom the map out far enough to show all objects in all
layers.

See Also
Layer.Bounds property

Layers.ClearSelection metho (Layers collection)

Purpose
Deselects features in all layers of the Layers collection.

See Also
Selection.ClearSelection

Layers.Count property (Layers collection)

Purpose
Contains the number of Layer objects in the collection. This is an Integer value and is read-
only.

Layers.CreateLayer metho (Layers collection)

Purpose
The CreateLayer method allows you to create a new temporary or permanent MapInfo table
layer. The created table has a column for the feature name, which is used by labeling and
data binding. When you add or update a feature, the Name property is put into the feature
name column.

Note: This is a 'deprecated' method that still works for backward compatability.The
new way to create a layer is to use Layers.Add with a Layerinfo object.

410 MapInfo MapX Developer Guide v4.5

 Layers.InsertionLayer (Layers object)

Syntax
[Layer=]OBJECT.CreateLayer (Name , [FileSpec] , [Position] , [KeyLength] , [CoordSys])

Part Description

OBJECT A Layers collection object.

Name A name to refer to the layer by (the username of the layer).
FileSpec Variant: The pathname of where to create the layer. The filename should
include the .tab extension. The other files that make up a MapInfo table
(.map, .dat, etc.) are created in the same directory as the .tab file. If no
filename is given, then a temporary layer is created, which will be deleted
when then map or ocx is destructed.
Position Variant: Its initial position in the layer list. If omitted, the auto layer
positioning algorithm assigns a layer order based on the type of layer.
KeyLength Variant: The length of the column added to the table to hold the feature
names. If omitted, the default is 32.
CoordSys Variant: A CoordSys object that specifies the coordinate system in which
the new layer is stored. Optional; if omitted, the Map.NumericCoordSys
property is used.

Remarks
The method returns a Layer object-the Layer object that was added to the collection. The
new layer is created with a key column named "GEONAME".

Layers.InsertionLayer (Layers object)

Purpose
This property specifies what new layer objects will be inserted into by the built-in object
editing tools. Initially InsertionLayer is set to null. You can assign a Layer object to the
property to make that Layer the InsertionLayer.

Remarks
You cannot make a drill-down, raster, seamless or user-draw layer the insertion layer.

The layer's editable property must be set to true before you can make that layer the
InsertionLayer.

At any time only one layer can be designated the insertion layer.

MapInfo MapX Developer Guide v4.5 411

Layer Object and Layers Collection

The AddPoint, AddLine, AddRegion and AddPolyLine stock tools (object creation tools)
will add features to the layer designated as the insertion layer
You cannot set Map.CurrentTool to any of the object creation tools until you've specified an
insertion layer.

Layers.Item property (Layers collection)

Purpose
Gets a specific Layer object from the collection. Item takes either an index (Integer value
starting at 1), or a layer name, to specify which Layer object to get.

Layers.LayersDlg method (Layers collection)

Purpose
Presents a dialog where the user can add layers, remove layers, change layer ordering, and
change layer properties. If the user clicks OK, the changes made within the dialog will
immediately be applied to the map.

Syntax
[Boolean=]OBJECT.LayersDlg ([HelpFile], [HelpID])

Part Description
OBJECT A Layers collection.
HelpFile Variant: The file name of a Windows Help file. (optional)
HelpID Variant: The ID number of a topic in the Help file. (optional)

Remarks
If you specify both the HelpFile and the HelpID, the dialog includes a Help button; if the
user clicks the Help button, MapX displays the specified Help topic.

The return value of LayersDlg is True if the user clicked OK and False if the user clicked
Cancel.

Example
The following statement displays the Layer Control dialog box

Map1.Layers.LayersDlg

412 MapInfo MapX Developer Guide v4.5

Layers.Move metho (Layers collection)
Purpose
Moves a layer in the Layer collection to change the order in which layers are drawn.

Syntax
OBJECT.Move (From, To)

Part Description

OBJECT Represents a Layer object.

From Index number of the layer to move. The topmost layer is 1.
To New location for the layer. For example, if you want it to be the
second layer, use 2.

Remarks
The order of layers in the Layers collection controls draw order. When layers are added using
Layers.Add or Layers.AddGeosetLayers, the layers are intelligently inserted into the layer
collection. For example, layers with points are put above layers with lines, and layers with
lines are put above layers with regions, and layers with regions are put above raster layers.

See Also
Layers collection

Layers. Remove metho (Layers collection)

Purpose
This method removes a Layer object from the collection. This has the effect of removing the
layer from the map.

Syntax
OBJECT.Remove (Index)

Part Description
OBJECT Represents a Layer object.
Index Either an Integer index value (starting at 1), or the name of the layer to
remove.

Remarks
If a Layer is removed from the Layers collection by the Layers.Remove method, the datasets
associated with the layer will also be deleted from the Datasets collection.
Layer Object and Layers Collection

If you remove an item, the collection indexes are renumbered to fill in the hole left by the
item removed.

Layers.RemoveAll method (Layers collection)

Purpose
Removes all Layer objects from the collection.

Syntax
Layers.RemoveAll

414 MapInfo MapX Developer Guide v4.5

 Layers.RemoveAll method (Layers collection)

LayerInfo Object

A LayerInfo object is the first argument passed to Layers.Add. The LayerInfo object passed
to Layers.Add describes/defines the layer to be added. The Type property of the LayerInfo
object determines what parameters the object must have, that is, the parameters that any
given LayerInfo object must have will vary depending on the type of layer being added.
The LayerInfo.AddParameter method is used to set these parameters. LayerInfo.Type is set
to one of the LayerInfoTypeConstants.

The table below displays the parameters that need to be used for each layer type.

LayerInfoType Parameter Required Type

miLayerInfoTypeTable FileSpec Yes String: File specification of

the .tab file to open
Name No String: Name of the added
layer
miLayerInfoTypeUserDraw Name Yes String: Name of the added
layer
miLayerInfoTypeRaster FileSpec Yes String: File specification of
the self-registering raster
file to open
Name No String: Name of the added
layer
miLayerInfoTypeShape FileSpec Yes String: File specification of
the .shp file (shapefile).
Name No String: Name of the added
layer
CoordSys Yes CoordSys Object:
Coordinate System in
which object data is stored
in the .shp file.
Style No Style Object: Style to use in
rendering the objects.

miLayerInfoTypeServer Name Yes String: Name of the added

layer

MapInfo MapX Developer Guide v4.5 415

LayerInfo Object

LayerInfoType Parameter Required Type

ConnectString Yes String: ODBC connection

string (see
AddServerLayer)
Query Yes String: SQL Query (see
AddServerLayer)
ToolKit Yes String: ToolKit option,
either ODBC or ORAINET
Cache No String: Either ON or OFF.
Default is OFF.
MBRSearch No String: Either ON or OFF.
Default is OFF.
miLayerInfoTypeGeodict_ Name Yes String: Name of the layer
UserName to add (as stored in the
Geodictionary).
miLayerInfoTypeTemp Name No String: Name of the added
layer.
Default: "LayerX"
Fields No Fields collection: Specifies
the column(s) the table will
have.
Features Yes, if no Features collection:
fields Specifies the rows to fill the
table with
Default: none
TableStorageType No String: Default: Native.
Valid options: Native,
MemTable
miLayerInfoTypeNewTable FileSpec Yes String: Name of .tab file for
new table
Name No String: Name of the added
layer
Default: built on filespec
Fields No Fields collection: Specifies
the column the table will
have

416 MapInfo MapX Developer Guide v4.5

 Layers.RemoveAll method (Layers collection)

LayerInfoType Parameter Required Type

Features Yes, if no Features collection:

Fields Specifies the rows to fill the
table with
Default: none
For any LayerInfoType other than miLayerInfoTypeUserDraw or miLayerInfoTypeRaster,
the following options are also supported:

Any AutoCreateDataset No Numeric: if 1, then a Dataset of

type miDatasetLayer is added
after the layer is added. If 0 (the
default), no Dataset is added.
Any DatasetName No String: If the AutoCreateDataset
parameter is 1, then this will be
the name of the new Dataset. If
not specified, a default name is
used.
Any Cache No String: Either ON or OFF,
specifying whether to cache the
data fetched from server layers.
Default is OFF.
Any Visible No Bool: Should this layer be visible
when added
Default: true

Remarks
To improve performance, you can specify the TableStorageType as "memtable".

Duplicate layer names are no longer allowed in MapX. When a developer explicitly
specifies a layer name ( as in the "name" parameter of the Layers.AddServerLayers,
Layers.AddUserDrawLaye , and Layers.Add), an exception will be thrown if the name is
not unique.

miLayerInfoTypeTemp is a temporary layer that lasts until the MapX control is closed, then
the layer is discarded. It is never saved to disk. One may specify a layer name, but not a
filespec.

miLayerInfoTypeNewTab is a layer that can be generated from external data (i.e. query
results).

MapInfo MapX Developer Guide v4.5 417

LayerInfo Object

For miLayerInfoTypeTemp and miLayerInfoTypeNewTab:

• Either a Fields collection or a Features collection is required; both can be used.

• If only a Features collection is passed, MapX will try to get the column information
from the table the Features came from.
• If a Features collection and a Fields collection are passed, MapX will try to match
the field names passed in with the columns found in the table the Features came
from.
• If only a Fields collection is passed, check the layer for a Dataset of type
miDatasetLayer. If found, check the passed-in Fields against the columns in the
miDatasetLayer. If the miDatasetLayer Dataset isn't present, create the table solely
on the Fields information passed in.
• The Fields default should be columns found in the Features collection's source table.
When using the LayerInfo object to add a .tab that references a raster, remote table, etc, use
LayerInfo type miLayerInfoTypeTab. LayerInfo type LayerInfoTypeRaster is used
specifically for adding self-registering raster files that do not have an associated .tab file.
LayerInfo type LayerInfoTypeServerLayer is used specifically for adding remote tables that
do not have an associated .tab file.

Object Properties
• LayerInfo.Type property

Object Methods
• LayerInfo.AddParameter method

See Also
Layers.Add method

LayerInfo.Type property (LayerInfo object)

Purpose
This is a read/write property whose value is one of the LayerTypeConstants

See Also
LayerInfo.AddParameter method

Layers.Add method

418 MapInfo MapX Developer Guide v4.5

 LayerInfo.Type property (LayerInfo object)

LayerInfo.AddParameter metho (LayerInfo object)

Purpose
The Addparameter method adds to the set of parameters required for a given call to the
Layers.Add method. The necessary parameters are determined by the type property of the
LayerInfo object.

Syntax
OBJECT.AddParameter (name, value)

Part Description

OBJECT This represents a LayerInfo object.

name The name of the parameter.
value The value of the parameter.

Remarks
Duplicate layer names are no longer allowed in MapX. When a developer explicitly
specifies a layer name (in a layerinfo "name" param, addserverlayer, or adduserdrawlayer),
an exception will be thrown if the name is not unique.

See Also
Layers.Add method

LayerInfo object

MapInfo MapX Developer Guide v4.5 419

LayerInfo Object

420 MapInfo MapX Developer Guide v4.5

Legend Object

Purpose
Each Theme object has a Legend object (Theme.Legend). The Legend object contains
properties to control the display of a theme's legend. Each ThemeCategory object
(RangeCategory, IndividualValueCategory, or MultiVarCategory) has an entry in the legend
contained in a LegendText object.

Object Properties
• Legend.BodyTextStyle property
• Legend.Compact property
• Legend.CompactTitle property
• Legend.CompactTitleStyle property
• Legend.CurrencyFormat property
• Legend.Height property
• Legend.Left property
• Legend.LegendTexts property
• Legend.PaperHeight property
• Legend.PaperWidth property
• Legend.ShowCount property
• Legend.ShowEmptyRanges property
• Legend.SubTitle property
• Legend.SubTitleStyle property
• Legend.Title property
• Legend.TitleStyle property
• Legend.Top property
• Legend.Visible property
• Legend.Width property

Object Methods
• Legend.ExportLegend method
• Legend.LegendDlg method
• Legend.PrintLegend method
Legend Object

Legend.BodyTextStyle property (Legend object)

Purpose
This is a Style object which controls the text style for the legend body and may be set to an
existing Style object or you may set the style properties individually.

See Also
Style object

Legend.Compact property (Legend object)

Purpose
Controls whether the legend is compact (1 line) or full sized. This is a Boolean value, and
defaults to the setting of Map.PreferCompactLegends.

See Also
Map.PreferCompactLegends property

Legend.CompactTitle property (Legend object)

Purpose
Contains the compact legend title text string. This is displayed when the legend is compact
sized. This is a String value, and a default title is created when the thematic map is created.

Legend.CompactTitleStyle property (Legend object)

Purpose
This is a Style object which controls the text style for the compact title. This is a Style object
and may be set to an existing style object or you may set the style properties individually.

See Also
Style object

422 MapInfo MapX Developer Guide v4.5

 Legend.CurrencyFormat property (Legend object)

Legend.CurrencyFormat property (Legend object)

Purpose
Controls whether numbers are displayed using a currency format or a standard number
format. This is a Boolean value, and defaults to False.

Legend.ExportLegend method (Legend object)

Purpose
Exports an image of the Legend to a file or to the clipboard.

Syntax
OBJECT.ExportLegend (Destination, Format)

Part Description
OBJECT Represents a Legend object.
Destination File specification of where to put the output, such as
”C:\Temp\Legend.bmp”. If you specify ”CLIPBOARD” instead of a file
path, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value. Note: If you
specify miFormatGIF (to generate GIF files), please read the Licensing
Requirements for Users of GIF Files. If you direct output to
CLIPBOARD, the format must be metafile or bitmap.

See Also
Map.ExportMap

Legend.Height property (Legend object)

Purpose
Contains the height of the legend in screen units. This is a Single value, and is a read-only
property.

MapInfo MapX Developer Guide v4.5 423

Legend Object

Legend.Left property (Legend object)

Purpose
Contains the position of the left edge of the legend in screen units, relative to the upper left
corner of the map control. This is a Single value.

Note: You can drag the legend outside the bounds of the MapX control in a form and
not be able to drag it back (if you release the mouse button with the legend off the
screen).
It is possible, however, to programmatically reset the Left andTop properties of the object to
be within the bounds of the map. This also applies to map titles and annotations.

Legend.LegendDlg method (Legend object)

Purpose
Presents a dialog where the user can adjust legend settings (altering the property values of
the legend object through a user interface). If the user clicks 'OK', the changes made within
the dialog will immediately be applied to the map.

Syntax
[Boolean=]OBJECT.LegendDlg([ HelpFile ] [ HelpID ])

Part Description
OBJECT Represents a Legend object.
HelpFile HelpFile is an optional parameter that is a pathname to a .hlp file that
contains help topics for the dialog.
HelpID HelpID is an optional parameter that refers to the ID of a specific help
topic within the given .hlp file.

Remarks
If either of the optional parameters are not given, the help button will not appear on the
dialog.

The return value of LegendDlg is True if the user clicked OK and False if the user clicked
Cancel.

424 MapInfo MapX Developer Guide v4.5

Legend.LegendTexts property (Legend object)
Purpose
A collection of Legendtext objects for the legend. Ranged, Individual Value, Pie, Bar and Dot
Density themes have one LegendText item per category. Graduated Symbol has three.

See Also
LegendText object and LegendTexts collection

Legend.PaperHeight property (Legend object)

Purpose
Contains the paper height of the legend in Map.PaperUnit units. This is a Single value, and is
a read-only property.

See Also
Map.PaperUnit property

Legend.PaperWidth property (Legend object)

Purpose
Contains the paper width of the legend in Map.PaperUnit units. This is a Single value, and is a
read-only property.

See Also
Map.PaperUnit property

Legend.PrintLegend metho (Legend object)

Purpose
Prints the legend in the specified rectangle to the specified device context.

Syntax
OBJECT.PrintLegend (hDC, x, y, w, h)

Part Description

OBJECT Represents a Legend object.

hDC Printer device context. Can be any device context.
x Upper left corner X in HIMETRIC units.
y Upper left corner Y in HIMETRIC units.
Legend Object

Part Description

w Width in HIMETRIC units.

h Height in HIMETRIC units.

Remarks
The current legend is drawn to fit the rectangle given. Best results are obtained when the
aspect ratio of width to height is maintained.

Legend.ShowCount property (Legend object)

Purpose
Controls whether or not to show on the legend the count portion of the ranges. This takes a
Boolean value, and the default is True.

Legend.ShowEmptyRanges property (Legend object)

Purpose
This is a read/write Boolean property that determines whether empty ranges (ranges that
do not contain any features) are displayed in the legend. The default is False.

Legend.SubTitle property (Legend object)

Purpose
This is a read/write string value that contains the legend subtitle text string. This is
displayed when the legend in normal sized. A default subtitle is created when the thematic
map is created.

426 MapInfo MapX Developer Guide v4.5

 Legend.Title property (Legend object)

Legend.SubTitleStyle property (Legend object)

Purpose
This returns a read/write style object which controls the text style for the legend subtitle.
This is a Style object and may be set to an existing style object or you may set the style
properties individually.

See Also
Style object

Legend.Title property (Legend object)

Purpose
Contains the legend title text string. This is displayed when the legend in normal sized. This
is a String value. A default title is created when the thematic map is created.

Legend.TitleStyle property (Legend object)

Purpose
This is a Style object which controls the text style for the title. This is a Style object and may
be set to an existing style object or you may set the style properties individually.

See Also
Style object

Legend.Top property (Legend object)

Purpose
This property contains the position of the top edge of the legend in screen units, relative to
the upper left corner of the map control. This is a Single value.

Note: You can drag the legend outside the bounds of the MapX control in a form and
not be able to drag it back (if you release the mouse button with the legend off the
screen).
It is possible, however, to programmatically reset the Left and Top properties of
the object to be within the bounds of the map. This also applies to map titles and
annotations.

MapInfo MapX Developer Guide v4.5 427

Legend Object

Legend.Visible property (Legend object)

Purpose
Controls whether the legend is visible or not. This is a Boolean value, and the default is True.

Legend.Width property (Legend object)

Purpose
Contains the width of the legend in screen units. This is a Single value, and is a read-only
property.

428 MapInfo MapX Developer Guide v4.5

 LegendTexts.AllOthersText property (LegendTexts collection)

LegendText Object and LegendTexts Collection

Purpose
Each Theme has a collection of LegendText objects called LegendTexts. Each object (each
line under the title) of a legend has a LegendText object in this collection which may be
manipulated individually.

• miThemeRanged has one LegendText per range (per RangeCategory).

• miThemeIndividualValue, miThemePieChart, and miThemeBarChart have
oneLegendText per category (per IndividualValueCategory or per
MultiVarCategory).
• miGradSymbol has 3 LegendTexts—one for each sample size.
• miDotDensity has one LegendText.

Object Properties
• LegendText.Text property
• LegendText.Visible property

Collection Properties
• LegendTexts.AllOthersText property
• LegendTexts.AutoGenerate property
• LegendTexts.Count property
• LegendTexts.Item property

See Also
Theme object

LegendTexts.AllOthersText property (LegendTexts collection)

Purpose
This returns a LegendText object from a collection. This LegendText object is associated with
the AllOthersCategory property of either the RangeCategories collection or
IndividualValueCategories collection.You can set the properties of the AllOthersText
property like any other LegendText object.

MapInfo MapX Developer Guide v4.5 429

LegendText Object and LegendTexts Collection

LegendText.Text property (LegendText object)

Purpose
Contains the text for a range or category in a legend. This is a String value, and a default is
set when the thematic map is created. The legend text is automatically recomputed
whenever the Theme object is recomputed (for example, number of ranges changed to 6),
unless the LegendTexts.AutoGenerate property is set to False.

See Also
Theme object

Theme.AutoRecompute property

LegendText.Visible property (LegendText object)

Purpose
Controls whether ranges are visible for the legend. This takes a Boolean value, and the
default is True.

LegendTexts.AutoGenerate property (LegendTexts collection)

Purpose
Controls whether the LegendText values should be re-computed by MapX when the Theme
object is recomputed. This is a Boolean value, and the default is True. If you are going to
modify the LegendText values, you should set this to False, so MapX doesn't override your
changes.

See Also
Theme.AutoRecompute

LegendTexts.Count property (LegendTexts collection)

Purpose
The number of LegendText objects in the collection. This is a read-only property.

430 MapInfo MapX Developer Guide v4.5

 LegendTexts.Count property (LegendTexts collection)

LegendTexts.Item property (LegendTexts collection)

Purpose
Retrieve a particular LegendTexts object from a collection. You must specify the text string.

MapInfo MapX Developer Guide v4.5 431

LegendText Object and LegendTexts Collection

432 MapInfo MapX Developer Guide v4.5

 LegendTexts.Count property (LegendTexts collection)

Map object

Maps are the basic building blocks for MapInfo MapX. Each map is defined by Dataset,
Layer and Annotations objects and collections.

Object Properties
• Map.Annotations property
• Map.AreaUnit property
• Map.AutoRedraw property
• Map.BackColor property
• Map.Bounds property
• Map.CenterX property
• Map.CenterY property
• Map.CurrentTool property
• Map.Dataset property
• Map.DatasetGeoField property
• Map.Datasets property
• Map.DatasetTheme property
• Map.DefaultConversionResolution property
• Map.DefaultStyle property
• Map.DisplayCoordSys property
• Map.ExportSelection property
• Map.FeatureEditMode property
• Map.FeatureFactory property
• Map.GeoDictionary property
• Map.GeoSet property
• Map.GeoSets property
• Map.GeoSetWidth property
• Map.hWnd property
• Map.InfotipSupport property
• Map.InfotipPopupDelay property
• Map.Layers property
• Map.MapUnit property
• Map.MapPaperHeight property
• Map.MapPaperWidth property
• Map.MapScreenHeight property
• Map.MapScreenWidth property
• Map.MatchNumericFields property
• Map.MatchThreshold property
• Map.MaxSearchTime property
• Map.MouseIcon property
• Map.MousePointer property
• Map.MouseWheelSupport property

MapInfo MapX Developer Guide v4.5 433

Map object

• Map.NumericCoordSys property
• Map.PanAnimationLayerproperty
• Map.PaperUnit property
• Map.PreferCompactLegends property
• Map.RedrawInterval property
• Map.Refresh method
• Map.Rotation property
• Map.SearchPath property
• Map.SelectionStyle property
• Map.SetSize method
• Map.Title property
• Map.TitleText property
• Map.Version property
• Map.WaitCursorEnabled property
• Map.Zoom property

Object Methods
• Map.AboutBox method
• Map.ClipLine method
• Map.CliplineV method
• Map.ConvertCoord method
• Map.ConvertCoordV method
• Map.CreateCustomTool method
• Map.Distance method
• Map.ExportMap method
• Map.IsPointVisible method
• Map.Pan method
• Map.PrintMap method
• Map.PropertyPage method
• Map.SaveMapAsGeoset method
• Map.ZoomTo method

See Also
Dataset objects
Layer object

Annotations objects

434 MapInfo MapX Developer Guide v4.5

 Map.Annotations property (Map object)

Map.AboutBox method (Map object)

Purpose
This displays the About Box, which contains information such as the version of MapX and
proper credits.

Syntax
OBJECT.AboutBox

Map.Annotations property (Map object)

Purpose
A collection of annotations for the map.

See Also
Annotation object and Annotations collection

Map.AreaUnit property (Map object)

Purpose
This is the units used in Area methods/properties. It takes an AreaUnitConstants value.
Default is miUnitSquareMile.

Map.AutoRedraw property (Map object)

Purpose
This temporarily turns off screen updating. It takes a Boolean value and is a read/write
property.

Remarks
Set AutoRedraw to FALSE to turn screen updating off, or TRUE to resume normal screen
updating.

When property or methods cause the map to change (such as Map.Zoom), the map gets
redrawn. If you want to make several changes to the map, this property lets you turn off
redrawing, make the several changes, then turn redrawing back on. This will prevent the
numerous redraws you would get otherwise. When set to TRUE, the entire map is redrawn.

MapInfo MapX Developer Guide v4.5 435

Map object

Map.BackColor property (Map object)

Purpose
This property controls what color the background of the map is 'erased' with before drawing
the map. You must specify an OLE_COLOR value. It can be a specific solid color or one of
the Windows System Colors such as 'Window Background'. (Most containers like Visual
Basic display a special color picker dialog in their property pages for properties of type
OLE_COLOR.)

Remarks
Since MapX has just one top level color property, it is selected by default and the property
name combo box is disabled. You may choose one of the colors and it is highlighted and the
system color combo is empty. Alternatively, you may pick a system color

See Also
OLE_COLOR Values

Map.Bounds property (Map object)

Purpose
The Map.Bounds property (which was called Map.MBR in earlier versions) enables you to
set the bounds of the map window in map coordinates. It takes a Rectangle object.

See Also
Rectangle object

Map.CenterX property (Map object)

Purpose
This property sets the current X coordinate for the center of the map. This property is a
double representing the longitude (negative values for the Western hemisphere).

436 MapInfo MapX Developer Guide v4.5

 Map.CenterY property (Map object)

Remarks
The CenterX property is set when a new Geoset is loaded.

See Also
Map.CenterY property
Map.ZoomTo method

Map.CenterY property (Map object)

Purpose
This property sets the current Y coordinate for the center of the map. This property is a
double representing the latitude.

Remarks
The CenterY property is set when a new Geoset is loaded.

See Also
Map.CenterX property

Map.ZoomTo method

Map.ClipLine method (Map object)

Purpose
This method accepts parameters representing the endpoints of an imaginary line on the
map. If any portion of the line falls within the view rectangle, ClipLine will adjust the
parameters so that none of the resulting line falls outside of the view rectangle.

Syntax
[ Boolean= ]OBJECT.ClipLine (X1, Y1, X2, Y2)

Part Description

OBJECT Represents a Map object.

X1 Double (by Reference). On input: Longitude coordinate of the first
endpoint of the unclipped line. On output: longitude coordinate of the
first endpoint of the clipped line.

MapInfo MapX Developer Guide v4.5 437

Map object

Part Description

Y1 Double (by Reference). On input: Latitude coordinate of the first

endpoint of the unclipped line. On output: latitude coordinate of the first
endpoint of the clipped line.
X2 Double (by Reference). On input: Longitude coordinate of the second
endpoint of the unclipped line. On output: longitude coordinate of the
second endpoint of the clipped line.
Y2 Double (by Reference). On input: Latitude coordinate of the second
endpoint of the unclipped line. On output: Latitude coordinate of the
second endpoint of the clipped line.

Remarks
All parameters are passed by reference and should be in the Map.NumericCoordSys
coordinate system.

The return value of ClipLine is True if any portion of the line fell inside the view rectangle,
and False otherwise.

If the line is completely within the Map window, none of the parameters will be affected and
ClipLine will return True. If some section of the line is within the map window, the
coordinates will be adjusted so that they form the portion of the line that is within the view
window, and ClipLine will return True. If the line is completely outside the map window
the coordinates will not be affected and ClipLine will return False.

See Also
Map.ClipLineV method

Layers.AddUserDrawLayer method
DrawUserLayer event

Map.NumericCoordSys property

438 MapInfo MapX Developer Guide v4.5

 Map.ClipLine method (Map object)

Map.CliplineV method (Map object)

Purpose
This method accepts parameters representing the endpoints of an imaginary line on the
map. If any portion of the line falls within the view rectangle, ClipLineV will adjust the
parameters so that none of the resulting line falls outside of the view rectangle. It is identical
to the Map.ClipLine method, except that it has Variant parameters rather than double
parameters.

Syntax
[ Boolean= ] OBJECT.ClipLineV(X1, Y1, X2, Y2)

Part Description
OBJECT Represents a Map object.
X1 Variant (by Reference). On input: Longitude coordinate of the first
endpoint of the unclipped line. On output: longitude coordinate of the
first endpoint of the clipped line.
Y1 Variant (by Reference). On input: Latitude coordinate of the first
endpoint of the unclipped line. On output: latitude coordinate of the first
endpoint of the clipped line.
X2 Variant (by Reference). On input: Longitude coordinate of the second
endpoint of the unclipped line. On output: longitude coordinate of the
second endpoint of the clipped line.
Y2 Variant (by Reference). On input: Latitude coordinate of the second
endpoint of the unclipped line. On output: Latitude coordinate of the
second endpoint of the clipped line.

All parameters are variants which are passed by reference. They are expected to contain
numeric values and should be in the Map.NumericCoordSys coordinate system. An
exception code 1111 is thrown if any of the parameters could not be converted to a number

The return value of ClipLineV is True if any portion of the line fell inside the view rectangle,
and False otherwise.

If the line is completely within the Map window, none of the parameters will be affected and
ClipLineV will return True. If some section of the line is within the map window, the
coordinates will be adjusted so that they form the portion of the line that is within the view
window, and ClipLineV will return True. If the line is completely outside the map window,
the coordinates will not be affected and ClipLineV will return False.

MapInfo MapX Developer Guide v4.5 439

Map object

See Also
Map.ClipLine method

Map.NumericCoordSys method

Map.ConvertCoord method (Map object)

Purpose
Converts map coordinates to screen display coordinates or screen coordinates to map
coordinates depending on the Dir parameter passed in the method. Screen coordinates are
specified in pixels.

Syntax
OBJECT.ConvertCoord (ScreenX, ScreenY, MapX, MapY, Dir)

Part Description

OBJECT Represents a Map object.

ScreenX Screen x coordinate in pixels. Single value.
ScreenY Screen y coordinate in pixels. Single value.
MapX Map x coordinate (longitude). Double value.
MapY Map y coordinate (latitude). Double value.
Dir Direction to convert coordinates, either from Map to Screen, or Screen to
Map. This takes a ConversionConstants value.

Either the Screen coordinates or the Map coordinates are provided, and the others are filled
out based on the Dir specified.

440 MapInfo MapX Developer Guide v4.5

 Map.CreateCustomTool method (Map object)

Map.ConvertCoordV metho (Map object)

Purpose
Converts map coordinates to screen display coordinates or screen coordinates to map
coordinates depending on the Dir parameter passed in the method. Variant version of
ConvertCoord method. Screen coordinates are specified in pixels.

Syntax
OBJECT.ConvertCoordV (ScreenX, ScreenY, MapX, MapY, Dir)

Part Description

OBJECT Represents a Map object.

ScreenX Screen x coordinate in pixels. Variant value.
ScreenY Screen y coordinate in pixels. Variant value.
MapX Map x coordinate (longitude). Variant value.
MapY Map y coordinate (latitude). Variant value.
Dir Direction to convert coordinates, either from Map to
Screen, or Screen to Map. This takes a
ConversionConstants value.

Either the Screen coordinates or the Map coordinates are provided, and the others are filled
out based on the Dir specified.

Map.CreateCustomTool method (Map object)

Purpose
This creates a custom tool, that when used, sends a ToolUsed event.

Note: If you create a Custom Tool of type circle and in theTool_Used event of the MapX
control do a SelectByRadius with the values passed into the event, the results are
not the same as if you select objects with the Radius Select Tool. The
SelectByRadius method will not select exactly what is under the circle drawn on
the Control when the custom tool is being used because this circle is an
approximation that does not consider the projection of the map. Selections made
with the actual Radius Select Tool correspond exactly to what is under the circle.

MapInfo MapX Developer Guide v4.5 441

Map object

Syntax
OBJECT.CreateCustomTool (ToolNumber, Type, Cursor, [ShiftCursor] , [CtrlCursor],
[InfoTips])

Part Description

OBJECT Represents a Map object.

ToolNumber Number of the tool used to reference it later. This value can be an
integer between 1 and 999.
Type The type describes the tool behavior. This takes a ToolTypeConstants
value.
Cursor Cursor shape when the tool created is the CurrentTool and the cursor
is over the map. This takes a CursorConstants value -OR- a custom
cursor file name.
ShiftCursor Variant: A CursorConstants value, indicating the cursor that should
appear while the SHIFT key is held down. Optional. If omitted, the
SHIFT key has no effect on the cursor.
CtrlCursor Variant: A CursorConstants value, indicating the cursor that should
appear while the CTRL key is held down. Optional. If omitted, the
CTRL key has no effect on the cursor.
InfoTips Boolean: Set to true if you want to show InfoTips. Default value is
false.

Remarks
Custom tools can be created to build tools that perform specialized behavior. For example, a
tool could be built to have the behavior of displaying information about the object that was
clicked on. Here, we would define a tool of type miToolTypePoint, and in the ToolUsed
event handler, write code to display information about the object that falls under the point
that was clicked on (using Layer.SelectByPoint).

See Also
Map.CurrentTool property

ToolUsed Event

442 MapInfo MapX Developer Guide v4.5

 Map.Dataset property (Map object)

Map.CurrentTool property (Map object)

Purpose
This property sets the current tool. This takes a ToolConstants value. The default is
miArrowTool.

Remarks
Different tools will cause the mouse to perform a variety of different tasks. For example, if
the current tool is set to miLabelTool, when you click the mouse, it will place a label on that
particular map object. The mouse cursor will change based on the tool you are using.

If you have defined a custom tool, set it to the CurrentTool by specifying its ToolNumber.

See Also
Map.CreateCustomTool method

ToolUsed Event

Map.Dataset property (Map object)

Purpose
This property specifies a Dataset to add. This only works at Design time - not at Run time.
This property is for use in Microsoft Visual Basic only.

Remarks
Visual Basic will display a list of all of the Data Controls on the current form in the Visual
Basic property sheet for MapX. Choosing one of the Data Controls in the list for the Dataset
property will cause MapX to create a Dataset for it at Run time with the data defined by the
DataControl.

This is similar to Datasets.Add method. However, since this takes no parameters, it assumes
default behavior for the rest of the parameters. The GeoField parameter can be specified
using the Map.DatasetGeoField property. You can also choose which fields (columns) and
aggregation methods to use for each field on the MapX `Data' property page.

See Also
Datasets.Add method,

Map.DatasetGeoField property

MapInfo MapX Developer Guide v4.5 443

Map object

Map.DatasetGeoField property (Map object)

Purpose
This property specifies which field of the Dataset specified in the Map.Dataset property
contains the geographic information. This is a String specifying the field name.

Remarks
This is similar to the GeoField parameter of the Datasets.Add method, but specifying the
GeoField for the Dataset specified at Design time.

See Also
Map.Dataset property
Datasets.Add method

Map.Datasets property (Map object)

Purpose
The Datasets collection for the map.

See Also
Dataset object and collection

Map.DatasetTheme property (Map object)

Purpose
This property specifies the theme type for the Dataset specified by the Map.Dataset
property. This takes a ThemeTypeConstants value. This defaults to miAutoThemeType.

Remarks
If you are specifying a Dataset at Design time (Map.Dataset property), then you can have
that data thematically mapped. This controls the theme style. This is similar to the
Themes.Add method, but is available at Design time. You can choose which field or fields to
base your theme on in the MapX Theme tab of the property page.

The DatasetTheme property is ignored if the Dataset property is not set.

444 MapInfo MapX Developer Guide v4.5

 Map.DefaultConversionResolution property (Map object)

See Also
Themes.Add method

Map.Dataset property

Map.DefaultConversionResolution property (Map object)

Purpose
A read/write system setting that controls the resolution (i.e. the number of nodes) used
when converting special MapInfo feature types, such as arcs, into regions or polylines, or
when generating circles, ellipses, arcs or buffers. It is an integer which can take on any value
up to 32,763.

Remarks
Various methods (listed below) allow you to explicitly specify an optional resolution
parameter. If you do not specify a resolution value, MapX uses the resolution setting
specified by the DefaultConversionResolution property.

This property affects the generation of buffers, circles, ellipses, and arcs. When generating
these types of features, you can control the resolution (sometimes called the "smoothness")
of the features. For example, the following table shows two different circular regions-one
containing 10 nodes, and the other containing 30 nodes.

Circular region with 10 nodes Circular region with 30 nodes

Increasing the resolution produces a smoother looking region; however, such regions take
longer to generate, and the resulting object requires more storage space.

This property also controls the resolution used when a MapInfo table contains an arc, circle,
rectangle, or rounded rectangle feature, and MapX converts the feature into a region or
polyline.

MapInfo MapX Developer Guide v4.5 445

Map object

See Also
FeatureFactory.BufferFeatures method

FeatureFactory.CreateArc method

FeatureFactory.CreateCircularRegion method

FeatureFactory.CreateEllipticalRegion method

Layer.SearchWithinDistance method

Map.DefaultStyle property (Map object)

Purpose
This is a Style object that has the style for both symbol and text objects when they are created
by using the Annotation.AddSymbol or Annotation.AddText methods.

See Also
Style object

Map.DisplayCoordSys property (Map object)

Purpose
This returns a read-write CoordSys object (coordinate system) that controls how the map is
displayed.

Note: If a map includes one or more raster image layers, MapX automatically displays
the map in the projection specified by the most visible raster image. The
coordinate system could then change as the map view changes (due to zooming
or panning) if a different raster image with a different projection becomes the
most visible. In this case, you cannot change the map's display coordinate system.

446 MapInfo MapX Developer Guide v4.5

 Map.Distance method (Map object)

Remarks
The Map.DisplayCoordSys represents the coordinate system (or "projection") in which the
map is displayed. By default, the map's coordinate system is set by the geoset. By modifying
the map's DisplayCoordSys (through the CoordSys.Set method), you can display the map in
another coordinate system.
The Map.DisplayCoordSys property only affects the appearance of the map. To access the
coordinate system used to interpret or return map coordinates, use the
Map.NumericCoordSys property.

See Also
Introduction to Using Coordinate Systems

CoordSys object

Map.NumericCoordSys

Map.Distance method (Map object)

Purpose
This computes the distance between two specified points on the map. The distance is
returned as a double, in the units specified by the MapUnit property.

Syntax
[ distance = ]OBJECT.Distance( x1,y1,x2,y2 )

Part Description

OBJECT Represents a Map object.

x1 x coordinate of the first point (longitude). Double value.
y1 y coordinate of the first point (latitude). Double value.
x2 x coordinate of the second point (longitude). Double value.
y2 y coordinate of the second point (latitude). Double value

Remarks
The distance is calculated using the Great Circle Calculation.

MapInfo MapX Developer Guide v4.5 447

Map object

See Also
CoordSys object

Map.NumericCoordSys

Map.MapUnit property

Map.ExportMap method (Map object)

Purpose
This exports the map window

MapX is capable of exporting to the following formats:

JPG TIF GIF

PNG WMF PSD

BMP

Syntax
OBJECT.ExportMap (Location, Format, [Width], [Height])

Part Description
OBJECT Represents a Map object.
Location File specification of place to put the output. If the keyword
'CLIPBOARD' is used, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value.
Width Width of output. This is a double value, and specifies width in terms
of Paper Units (Map.PaperUnit). This is an optional parameter, and if
not specified, Map.MapPaperWidth is used.
Height Height of output. This is a double value, and specifies height in terms
of Paper Units (Map.PaperUnit). This is an optional parameter, and if
not specified, Map.MapPaperHeight is used.

448 MapInfo MapX Developer Guide v4.5

 Map.ExportSelection property (Map object)

Remarks
If features on the map are selected, you might not want to output the selection highlighting;
see Map.ExportSelection property.

See Also
Map.ExportSelection property

Map.PaperUnit property

Map.ExportSelection property (Map object)

Purpose
This returns or sets a Boolean property, controlling whether the selection's highlighting is
included in output.

If set to True, output produced by the Map.ExportMap method or the Map.PrintMap

method will include any current selection highlighting. If set to False, output will not
include the highlighting.

To control the style in which the selection highlighting is drawn, set the Map.SelectionStyle
property.

Map.FeatureEditMode property (Map object)

Purpose
This property controls the edit mode of the map (i.e. feature editing (miEditModeFeature) or
node editing (miEditModeNode)). Node Editing can be masked with other node operations
when set to one of the FeatureEditModeConstants. The default for this property is
miEditModeFeature.

See Also
Node Selecting and Editing

MapInfo MapX Developer Guide v4.5 449

Map object

Map.FeatureFactory property (Map object)

Purpose
This returns a FeatureFactory object, which supports various methods for creating and
modifying features on the map.

Remarks
This property returns a FeatureFactory object, which has methods that support various
editing tasks-creating features, generating buffer regions, combining features, and testing
for intersections between features.

See Also
FeatureFactory object

Map.GeoDictionary property (Map object)

Purpose
This property specifies the location of a registry entry which is used to determine the
GeoDictionary file and the default data directory. This is a String value, and be set at run
time. Essentially, you may change the geodictionary that MapX is looking at by setting the
this property.

Remarks
When a map control is created, MapX will query the registry key:
HKEY_LOCAL_MACHINE\Software\MapInfo\MapX\4.0\<Value of GeoDictonary
Property>

The value of this registry key specifies two things:

• The GeoDictionary file, which maintains information about which map layers can
be matched to which information. (MapX can be used without a GeoDictionary.)
• The default data directory. This directory is searched for GeoSet files (*.gst) which
are shown in the Property Pages and the Map.GeoSets collection.
There are three valid options for the registry value:

• Could contain a full file spec for the Geodictionary file (e.g. "C:\Program
Files\MapInfo MapX\Maps\geodict.dct"). The data directory is set to be the path
leading to the Geodictionary file named by this key (in this example, "C:\Program
Files\MapInfo MapX\Maps\". The in-memory geodictionary is initialized from the
Geodictionary file and layers contained in the Geodictionary can be automatically

450 MapInfo MapX Developer Guide v4.5

 Map.GeoSet property (Map object)

matched against it too. Layers added to the map are added to the in-memory
geodictionary so they can be auto matched against.
• Could contain just a path specification (e.g. "C:\Program Files\MapInfo
MapX\Maps\"). The data directory is set to this directory. The in-memory
geodictionary is initialized empty. Layers added to the map are still added to the in-
memory geodictionary so they can be auto matched against.
• Could be empt . The in-memory geodictionary is initialized empty. Layers added
to the map are still added to the in-memory geodictionary so they may be auto
matched.
The default value of Map.GeoDictionary is "GeoDictionary", meaning that MapX will query
the registry entry
HKEY_LOCAL_MACHINE\Software\MapInfo\MapX\4.0\GeoDictionary.

See Also
Map.GeoSet property

Map.GeoSet property (Map object)

Purpose
This read/write property sets the GeoSet. It retuns a String Value. To set this property, the
filespec (entire path) or the `friendly name' (the name a geoset) of the GeoSet is used.

Remarks
A GeoSet is a collection of map layers and their settings. A GeoSet can be specified at Design
time. If this is set during Run time, it will first remove all loaded layers and Datasets, then
load the new GeoSet. To simply remove all loaded layers and Datasets and not load a new
geoset, specify an empty string. The default GeoSet that is loaded is US.GST.

Map.GeoSets property (Map object)

Purpose
This read-only property returns a collection of Geoset objects. This collection consists of all
geosets in the Maps directory.

See Also
Geoset object and collection

MapInfo MapX Developer Guide v4.5 451

Map object

Map.GeoSetWidth property (Map object)

Purpose
A read-only property representing the width of the GeoSet (maximum width of all Layers in
the map). This is a double value in units specified by the MapUnit property.

This property is useful when you need to set the zoom to the extents of the map.

Map.hWnd property (Map object)

Purpose
This is thee handle to the window of the MapX control. Only valid at Run time. This is a
read-only property.

Map.InfotipSupport property (Map object)

Purpose
This property allows the programmer to control whether or not MapX displays pop-up
InfoTips. It is a Boolean property, and defaults to True.

Remarks
When InfoTipSupport is True, InfoTips will pop up for the following tools: Arrow Tool,
Select Tool, Label Tool, and any custom tools where the ShowInfoTips parameter to
Map.CreateCustomTool was True.

Infotips only look at the selectable layers. It also searches the layer list from top to bottom.
Therefore, if objects from one layer obscure another, you will only see infotips for
uppermost objects.

See Also
Map.InfotipPopupDelay property

Map.CreateCustomTool method

452 MapInfo MapX Developer Guide v4.5

 Map.IsPointVisible method (Map object)

Map.InfotipPopupDelay property (Map object)

Purpose
This property controls the duration of time the user needs to have the mouse pointer over an
object before an InfoTip is popped up. This property only applies when Map.InfotipSupport
is True. It is an Integer value, specified in Milliseconds. The default is 500.

See Also
Map.InfotipSupport property

Map.IsPointVisible metho (Map object)

Purpose
This returns true or false whether the point (in map coordinates) is currently within the
visible portion of the map window.

Syntax
[ bool= ] OBJECT.IsPointVisible (X, Y )

Part Description

OBJECT Represents a Map object.

X Map Coordinates for east/west position (latitude).
Y Map Coordinates for north/south position (longitude).

Map.Layers property (Map object)

Purpose
The Layers collection for the map.

See Also
Layer object and Layers collection

MapInfo MapX Developer Guide v4.5 453

Map object

Map.MapUnit property (Map object)

Purpose
This property sets the units used for distance calculations. Takes a MapUnitConstants
value. The default unit is miUnitMile.

Map.MapPaperHeight property (Map object)

Purpose
The height of the map control. This is a double value specified in terms of Paper Units
(Map.PaperUnit.). It is a read-only property.

Map.MapPaperWidth property (Map object)

Purpose
The width of the map control. This is a double value specified in terms of Paper Units
(Map.PaperUnit.). It is a read-only property.

Map.MapScreenHeight property (Map object)

Purpose
The MapScreenHeight and MapScreenWidth properties make it easy to position legends.
These properties contain the width and height of the map control, in pixels. Since legends
also contain their width and height, in pixels, it is easy to position legends.

Map.MapScreenWidth property (Map object)

Purpose
The MapScreenHeight and MapScreenWidth properties make it easy to position legends.
These properties contain the width and height of the map control, in pixels. Since legends
also contain their width and height, in pixels, it is easy to position legends.

454 MapInfo MapX Developer Guide v4.5

 Map.MatchThreshold property (Map Object)

Map.MatchNumericFields property (Map object)

Purpose
This property controls matching on numeric and date fields. This property appears on the
Data (design time) property page. If MatchNumericFields is true, then numeric fields are
considered candidate keys (along with the alpha/numeric or date fields) when MapX is
auto-matching. If it is false, then numeric columns are not considered when performing
auto-matching. By default this property is false.

If you specify a date or numeric GeoField in Datasets.Add, MapX will use it whether or not
MatchNumericFields is TRUE.

Map.MatchThreshold property (Map Object)

Purpose
This is the minimum threshold percentage required for matching a map layer with a data
source.

The default = 80.

Map.MaxSearchTime property (Map object)

Purpose
This property sets the search time for automatic GeoColumn detection and the automatic
GeoSet detection when bringing in data using Datasets.Add. This is an Integer value
specifying time in Seconds. The default time is 5 seconds.

Map.MouseIcon property (Map object)

Purpose
If you need to specify a customized cursor for the mouse icon with the Map.MousePointer
property, use the Map.MouseIcon property. The Map.MouseIcon property lets the
programer specify a custom cursor to use as the default mouse cursor in MapX with a string
which specifies either the the full specification path (including the name of the file), or, the
custom mouse cursor. The name must specify either a .cur, .ico, or .ani file type. If the
specified cursor can not be loaded, an exception is thrown.

MapInfo MapX Developer Guide v4.5 455

Map object

Remarks
If Map.MousePointer is set to miCustomCursor and Map.MouseIcon has not been set yet,
then the cursor will be drawn with the shape of miDefaultCursor. The MousePointer
property will still have a value of miCustomCursor (40). As soon as the Map.MouseIcon is
properly set, then the new cursor shape will be used.
Alternatively, the MouseIcon and MousePointer properties can be set via the MapX
properties dialog. Simply right click your map and select the Mouse tab.

See Also
Map.MousePointer property

CursorConstants

Map.MousePointer property (Map object)

Purpose
This property sets the shape of the mouse cursor. This takes a CursorConstants value. The
default is miDefaultCursor, which means that the cursor of the current tool will be used.

456 MapInfo MapX Developer Guide v4.5

Remarks
If Map.MousePointer is set to miCustomCursor (40) and Map.MouseIcon has not been set yet,
then the cursor will be drawn with the shape of miDefaultCursor.The MousePointer property
will still have a value of miCustomCursor.As soon as the Map.MouseIcon is properly set, then
the new cursor shape will be used.

Map.MouseWheelSupport property (Map object)

Purpose
Controls the level of Intellimouse support: None, Zoom/Scroll only (no Autscroll), or Full.
This property is set with a MouseWheelSupportConstants.
Map object

Map.NumericCoordSys property (Map object)

Purpose
This returns a read-write CoordSys object (coordinate system) that controls how MapX
interprets numeric map coordinates.

Note: If a map includes one or more raster image layers, MapX automatically displays
the map in the projection specified by the most visible raster image. The
coordinate system could then change as the map view changes (due to zooming
or panning) if a different raster image with a different projection becomes the
most visible. In this case, you cannot change the map's display coordinate system.

Remarks
The NumericCoordSys represents the coordinate system used to process numeric map
coordinates. The default coordinate system is Longitude/Latitude WGS-84. By modifying
the map's NumericCoordSys (through its CoordSys.Set method), you can work with map
coordinates in another coordinate system.

The NumericCoordSys property does not affect the appearance of the map. To set the
coordinate system (or "projection") in which the map is displayed, use the
Map.DisplayCoordSys property.

See Also
Introduction to Using Coordinate Systems

Map.Pan method (Map object)

Purpose
This method will pan the map by the given offset in screen coordinates (pixels).

Syntax
OBJECT.Pan (ScreenX, ScreenY)

Part Description

OBJECT Represents a Map object

ScreenX The amount to offset the horizontal screen coordinate.
ScreenY The amount to offset the vertical screen coordinate.

458 MapInfo MapX Developer Guide v4.5

Map.PanAnimationLayerproperty (Map object)
Purpose
This property controls whether the animation layer (if there is one) is drawn into the backing
store when the pan tool is in use so that the contents of the layer are dragged around with the
rest of the map. The default is FALSE.

Map.PaperUnit property (Map object)

Purpose
This property sets the unit of measure MapX will use for the map on paper. Specify the unit of
measure by using the PaperUnitsConstants. The default is miPaperUnitInch.

Map.PreferCompactLegends property (Map object)

Purpose
This property sets whether or not to display a compact legend. This takes a Boolean value. The
default value is false.

Remarks
When legends are created, they can be compact or full sized. When a thematic map is created,
a legend is always shown. This setting controls how the legend will be shown. The legend can
always be changed later using the Theme.Legend.Compact or Theme.Legend.Visible settings,
but the initial setting controls the position of the legend.

Map.PrintMap metho (Map object)

Purpose
Prints the map in the specified rectangle to the specified device context.

Syntax
OBJECT.PrintMap (hDC x, y, w, h)

Part Description
OBJECT Represents a Map object.
hDC Printer device context. Can be any device context.
x Upper left corner X in HIMETRIC units.
y Upper left corner Y in HIMETRIC units.
w Width in HIMETRIC units.
Map object

Part Description

h Height in HIMETRIC units.

Remarks
The current map is drawn to fit the rectangle given. Best results are obtained when the
aspect ratio of width to height is maintained.
If features on the map are selected, you might not want to output the selection highlighting;
see Map.ExportSelection property.

Map.PropertyPage method (Map object)

Purpose
The PropertyPage method allows the user to control or set various properties of the map
object at run-time. This is the same property page that is available in design mode, although,
some properties cannot be set at run-time using this method.

Syntax
OBJECT.PropertyPage

Map.RedrawInterval property (Map object)

Purpose
This property enables incremental drawing. It is the time, in 1/100ths of a second, between
when the display is updated with the off-screen bitmap. The minimum value is 10. A very
high value (e.g., 3000) effectively turns off incremental drawing -- the screen won't be
updated until the map is completely drawn off screen.

Remarks
Currently, the map is drawn to an off-screen bitmap, then transferred to the screen when the
bitmap is complete. Now, you can transfer to the screen more often to show the user that
something is indeed happening. (This is especially useful when drawing streets at 25 mile
zoom.)

460 MapInfo MapX Developer Guide v4.5

 Map.Rotation property (Map object)

Map.Refresh method (Map object)

Purpose
Forces the map to get redrawn immediately

Syntax
OBJECT.Refresh

Remarks
Normally when an action is taken that causes the Map to be redrawn, MapX won't actually
redraw until it receives a paint message, so that it can combine multiple redraws into one.
This method causes MapX to redraw immediately, without waiting for the next paint
message. This method will not return until the redraw is complete.

See Also
Map.AutoRedraw property

Map.Rotation property (Map object)

Purpose
This property sets the rotation of the map. Rotation values are specified in degrees,
increasing clockwise, with 0 indicating an unrotated map. Applying a rotation to a map
does not change its zoom level or center point.

Note: A map containing one or more raster layers cannot be rotated, because MapX is
unable to rotate raster images.

Map.SaveMapAsGeoset metho (Map object)

Purpose
This creates a geoset file representing the current status of the map (layer information,
labeling settings, etc.).

MapInfo MapX Developer Guide v4.5 461

Map object

Syntax
OBJECT.SaveMapAsGeoset (name, filespec)

Part Description

OBJECT A Map object.

name String that represents the geoset's ”friendly” name (the description that
appears in the Geodictionary). If you specify an empty string, the map's
Title is used.
filespec String that represents a full file path for the geoset file. If no path is
specified, the new file is placed in the data directory. If no extension is
specified, the standard .gst extension is used. If the specified file already
exists, it is overwritten.

Remarks
If the map contains any temporary layers, those layers are left out of the new geoset file and
an exception is thrown (after the geoset has been otherwise completely saved) to indicate
such. This method also throws an exception if there are no layers in the map.

Map.SearchPath property (Map object)

Purpose
This property allows the user to set the SearchPath dynamically. A SearchPath is a "plotted
course" via the drive and directory(ies) to where information "lives". The SearchPath is
initially read from the registry. This property is available at run-time only.

Map.SelectionStyle property (Map object)

Purpose
This returns or sets a Style object, representing the style in which selected features are
drawn.

462 MapInfo MapX Developer Guide v4.5

Remarks
This property returns a read/write Style object that controls the appearance of selected
features in all layers.

To control the appearance of selected regions, set this Style object's RegionXXX properties,
such as RegionColor. The RegionColor and RegionBorderXXX properties are used to draw the
box around selected symbol features. The LineXXX properties are used to draw selected line
features. Note that the SymbolXXX and TextXXX properties do not apply and have no effect.

Note: The "XXX" is a place holder for the various properties of the Style object that
define a region, line, etc.

Remarks
To omit the selection highlighting from output, set the Map.ExportSelection property to
False.

Map.SetSize metho (Map object)

Purpose
This property sets the size of the control, in pixels.

Syntax
OBJECT.SetSize (W, H)

Part Description

OBJECT Represents a Map object.

W The desired width of the control, in pixels.
H The desired height of the control, in pixels.

Remarks
In most Visual Basic applications, you can resize the control without using the SetSize method
-- just use the standard Width and Height properties supported by Visual Basic. The SetSize
method can not be used with a map object on a form. SetSize is for users that create map
objects via CreateObject() call.
Map object

Map.Title property (Map object)

Purpose
A Title object specifying the title for the map. This can be set to NULL for no title.

Use the Title object to control the title's text, display style, and position. Tip: If you want to
set the title's text, and you do not care about its style or position, you can set the
Map.TitleText property at design time.

Map.TitleText property (Map object)

Purpose
This returns or sets a string that appears as the map's title. If you specify an empty string,
the title is hidden.

Remarks
The title defaults to the GeoSet name. If the TitleText is equal to the GeoSet name and the
Geoset is changed, the TitleText also changes.

See Also
Map.Title property

Map.Version property (Map object)

Purpose
This property specifies the version of MapX you are using. This is a String value, and is
read-only.

Map.WaitCursorEnabled property (Map object)

Purpose
This property allows you to turn the Wait Cursor on or off manually. Default is True.

464 MapInfo MapX Developer Guide v4.5

Map.Zoom property (Map object)
Purpose
Contains or sets the current zoom value for the map. The zoom value is defined as the width
across the map. This is a double value in the units specified by the MapUnit property.

Map.ZoomTo method (Map object)

Purpose
Zooms and centers the map.

Syntax
OBJECT.ZoomTo (Zoom, x, y)

Part Description

OBJECT Represents a Map object.

Zoom The zoom value. MapX defines the zoom value as the width across the
control. This is a double value specified in terms of Map Units (MapUnit).
X The x coordinate to center the map to. A double value representing the
longitude.
Y The y coordinate to center the map to. A double value representing the
latitude.

Remarks
Use this method as a simple way to zoom and re-center the map. The alternative would be to
set the Zoom, CenterX, and CenterY properties of the Map object, but doing it that way would
cause 3 screen redraws unless screen updating was turned off, then on using the
Map.AutoRedraw property.
Map object

466 MapInfo MapX Developer Guide v4.5

MultivarCategory Object and MultivarCategories
Collection

A pie or bar chart thematic map is exposed to OLE through the MultivarCategories collection,
which is a collection of MultivarCategory objects. The collection contains one object for each
bar in the bar chart, or one object for each wedge in the pie chart.

To obtain a MultivarCategories collection, reference the ThemeProperties.MultivarCategories

property.

Object Properties
• MultivarCategory.Style property

Collection Properties
• MultivarCategories.Count property
• MultivarCategories.Item property

See Also
ThemeProperties.MultivarCategories property

LegendText object and LegendTexts collection

MultivarCategories.Count property (MultivarCategories collection)

Purpose
This is a read-only integer value, indicating the number of variables used by the theme-the
number of bars in a thematic bar chart, or the number of wedges in a thematic pie chart.

MultivarCategories.Item property (MultivarCategories collection)

Purpose
This returns one MultivarCategory object from the collection. This object describes the
settings for one of the thematic variables (e.g. one of the bars in a bar chart theme).
MultivarCategory Object and MultivarCategories Collection

MultivarCategory.Style property (MultivarCategory object)

Purpose
This property controls the style for objects that fall within this MultivarCategory.This is a
Style object and may be set to an existing style object or you may set the style properties
individually. The defaults are designed to provide highly contrasting styles.

See Also
Style object

468 MapInfo MapX Developer Guide v4.5

NotesQueryInfo object

Perform queries on a Notes Dataset by making a NotesQueryInfo object and using Dataset
type 8 (miDatasetNotesQuery).
This Dataset type will allow the MapX user to ask Notes to perform queries upon a database
at run-time. To add a Dataset of this type to MapX, you will need to create a NotesQueryInfo
object and pass it to Datasets.Add.

Object Properties
• NotesQueryInfo.BeginDate property
• NotesQueryInfo.Database property
• NotesQueryInfo.DefaultNumericValue
• NotesQueryInfo.DefaultStringValue property
• NotesQueryInfo.EndDate property
• NotesQueryInfo.FullTextSearch property
• NotesQueryInfo.MaxNumDocs property
• NotesQueryInfo.Query property
• NotesQueryInfo.Server property

NotesQueryInfo.BeginDate property (NotesQueryInfo object)

Purpose
A string that defines a beginning cutoff date/time or a string that represents it (optional).
Notes modified before this date/time are ignored during the search.

NotesQueryInfo.Database property (NotesQueryInfo object)

Purpose
This is either a name of a Notes database on a server, or a path to a local Notes database (.nsf).
NotesQueryInfo object

NotesQueryInfo.DefaultNumericValue property (NotesQueryInf

object)
Purpose
Because a Notes Query can return documents that do not contain all of the fields specified,
MapX will return a default numeric (double) if the requested numeric field is not found
(optional). This value defaults to 0.

See Also
Datasets.Add

NotesQueryInfo.DefaultStringValue property (NotesQueryInfo

object)
Purpose
Because a Notes Query can return documents that do not contain all of the fields specified,
MapX will return a default string if the requested string field is not found (optional). This
value defaults to "".

NotesQueryInfo.EndDate property (NotesQueryInfo object)

Purpose
A string that defines a end cutoff date/time or a string that represents it (optional). Notes
modified before this date/time are ignored during the search.

NotesQueryInfo.FullTextSearch property (NotesQueryInfo object)

Purpose
This is a Boolean value (TRUE or FALSE) that indicates both that the database will have a
full text index and that the Query property is a full-text search query.

See Also
NotesQueryInfo.Query property

470 MapInfo MapX Developer Guide v4.5

 NotesQueryInfo.Query property (NotesQueryInfo object)

NotesQueryInfo.MaxNumDocs property (NotesQueryInfo object)

Purpose
An integer which specifies the maximum number of Notes to be allowed in the results
(optional). If the input is zero, all notes that match the search criteria will collected.

NotesQueryInfo.Query property (NotesQueryInfo object)

Purpose
If the FullTextSearch property is set to TRUE, this property is a full-text search query string.
If the FullTextSearch property is FALSE, this property become a Notes search formula. See
your Notes database for information on how to form full-text search query or formula
strings.

See Also
NotesQueryInfo.FullTextSearch property

NotesQueryInfo.Server property (NotesQueryInfo object)

Purpose
This is a string that defines which Notes server that the above database is on. This string is
left empty if the Database property refers to a local database.

See Also
NotesQueryInfo.Database property

MapInfo MapX Developer Guide v4.5 471

NotesQueryInfo object

472 MapInfo MapX Developer Guide v4.5

NotesViewInfo Object

The NotesViewInfo object is required for the second parameter to Datasets.Add for Datasets of
type miDatasetNotesView. This Dataset type will access a specified view of a Database.

Object Properties
• NotesViewInfo.Database property
• NotesViewInfo.Server
• NotesViewInfo.View

See Also
Datasets.Add method

NotesViewInfo.Database property (NotesViewInfo object)

Purpose
This read/write property is either a name of a Notes database on a server, or a path to a local
Notes database (.nsf).

NotesViewInfo.Server (NotesViewInfo object)

Purpose
This read/write property is a string that defines which Notes server that the above database is
on. This string is left empty if the Database property refers to a local database.

NotesViewInfo.View (NotesViewInfo object)

Purpose
This read/write property is a string that refers to the specific view within the database that the
data will be pulled from.
NotesViewInfo Object

474 MapInfo MapX Developer Guide v4.5

 ODBCQueryInfo.ConnectString property (ODBCQueryInfo object)

ODBC QueryInfo Object

An ODBCQueryInfo object is passed into the Datasets.Add method as the source parameter
if the Dataset type is miDatasetODBC. This object contains information about how to
connect to an ODBC data source and which records to treat as the record set.

Note: If you use the ODBCQueryInfo object, your project must reference
MODBCDataset.DLL ("MapInfo ODBC Dataset Engine Library").
In Visual Basic, choose Tools > References (for VB 4) or Project > References (for VB 5). Click
the Browse button to add references to appropriate dlls. The dlls are installed in the MapX
Program directory.

Object Properties
• ODBCQueryInfo.ConnectString property
• ODBCQueryInfo.DataSource property
• ODBCQueryInfo.SqlQuery property

See Also
Datasets.Add method

ODBCQueryInfo.ConnectString property (ODBCQueryInfo object)

Purpose
This property sets the connect string to connect with an ODBC data source. For example,
specify "ODBC;". You can also include "uid=" , "pwd=", or DLG=. If information is missing
and needed, the ODBC driver for the DataSource will prompt the user.

"DLG=" controls the display of the connection dialog box: DLG=0 means never put up a
dialog, DLG=1 means always put one up, DLG=2 displays the connection dialog, but only if
needed (i.e., if not all required information was provided).

MapInfo MapX Developer Guide v4.5 475

ODBC QueryInfo Object

ODBCQueryInfo.DataSource property (ODBCQueryInfo object)

Purpose
This property sets the name of the ODBC data source. If this property is left blank, ODBC
will prompt the user. ODBC DataSources are set up using the ODBC administrator, which
can be found in the Windows Control Panel.

ODBCQueryInfo.SqlQuery property (ODBCQueryInfo object)

Purpose
This property specifies the SQL query string which is used to retrieve the rows and columns
to build a Dataset.
For example, specify "select * from USA".

476 MapInfo MapX Developer Guide v4.5

Parts Collection

A Parts object is a collection of Points collection objects. It has the normal Count, Item, and
Remove methods. The Add method takes a Source Points object and returns the Points object
added to the Parts collection (i.e., a new Points object is added to the Parts collection and the
points are copied from the Source Points collection).

Collection Properties
• Parts.Count property (Parts collection)
• Parts.Item property (Parts collection)

Collection Methods
• Parts.Add method (Parts collection)
• Parts.Remove method (Parts collection)
• Parts.RemoveAll method (Parts collection)

Parts.Add method (Parts collection)

Purpose
The Add method takes a Source Points object and returns the Points object added to the Parts
collection (i.e., a new Points object is added to the Parts collection and the points are copied
from the Source Points collection).

Syntax
OBJECT.Add(Points)

Points is the Points collection object you want to add.

Parts.Count property (Parts collection)

Purpose
This property counts the number of items in collection.
Parts Collection

Parts.Item property (Parts collection)

Purpose
This property returns a Points collection object from Parts collection. This is a Variant and
you must specify the 1 based index number. This is the default property of the Parts
collection.

Parts.Remove method (Parts collection)

Purpose
This method removes a Points collection object from this collection.

Syntax
OBJECT.Remove (index)

Parts.RemoveAll method (Parts collection)

Purpose
This method removes all Parts objects from the collection.

Syntax
OBJECT.RemoveAll

478 MapInfo MapX Developer Guide v4.5

 Point.Offset method (Point object)

Point Object and Points Collection

The Point object represents an XY coordinate pair. When a Point belongs to a Feature, the X
coordinate represents longitude, and the Y coordinate represents latitude.

Object Properties
• Point.X property
• Point.Y property

Object Methods
• Point.Offset method
• Point.Set method

Collection Properties
• Points.Count property
• Points.Item property

Collection Methods
• Points.Add method
• Points.AddXY method
• Points.Remove method
• Points.RemoveAll method

Point.Offset method (Point object)

Purpose
This method changes the position of a point by changing its coordinates.

Syntax
OBJECT.Offset(double deltaX, double deltaY)

Part Description

OBJECT Represents a Point object.

deltaX The amount to add to the x coordinate.
deltaY The amount to add to the y coordinate.
double DeltaX and deltaY are values in the Map's Numeric Coordinate System.

See Also
Map.Numeric CoordSys

MapInfo MapX Developer Guide v4.5 479

Point Object and Points Collection

Point.Set metho (Point object)

Purpose
This method sets the coordinates of a point.

Syntax
OBJECT.Set(double X, double Y)

Part Description

OBJECT Represents a Point object.

X X is the x coordinate of the point.
Y Y is the y coordinate of the point.
double DeltaX and deltaY are values in the Map's Numeric Coordinate
System.

Point.X property (Point object)

Purpose
This is the point's X coordinate. X and Y are values in the Map's numeric coordinate system.

See Also
Map.NumericCoordSys

Point.Y property (Point object)

Purpose
This is the point's Y coordinate. X and Y are values in the Map's numeric coordinate system.

See Also
Map.NumericCoordSys

480 MapInfo MapX Developer Guide v4.5

Points.Add metho (Points collection)
Purpose
This method adds a point to the Points collection.

Syntax
[ Point= ]OBJECT.Add(Point, [Position])

Part Description

OBJECT Represents a Points object.

Point The Point object to add.
Position An integer between 1 and Points.Count, specifying the position in the
collection where the point should be added. If it is not specified or
invalid, the point will be appended to the end of the collection.

Points.AddXY method (Points collection)

Purpose
This method creates a new point with the given X and Y values and adds it to a Points
collection.

Syntax
[ Point= ]OBJECT.AddXY (x, y, [Position])

Part Description
OBJECT Represents a Points object.
x Double numeric CoordSys.
y Double numeric CoordSys.
Position An integer between 1 and Points.Count, specifying the position in the
collection where the point should be added. If it is not specified or
invalid, the point will be appended to the end of the collection.
Point Object and Points Collection

Points.Count property (Points collection)

Purpose
This is the number of items in a collection.

Points.Item property (Points collection)

Purpose
This property returns a Points collection object from Parts collection. This is a Variant and
you must specify the 1 based index number. This is the default property of the Parts
collection.

Points.Remove metho (Points collection)

Purpose
This method removes a Point object from the collection.

Syntax
OBJECT.Remove (index)

Points.RemoveAll metho (Points collection)

Purpose
This method removes all Point objects from the collection.

Syntax
OBJECT.RemoveAll

482 MapInfo MapX Developer Guide v4.5

RangeCategory Object and RangeCategories
Collection

A Ranged thematic map's settings are exposed through the RangeCategories collection, which
is a collection of RangeCategory objects, one object for each range, sorted in ascending order.
Each object in the collection describes one range (its display style, its minimum and maximum
values, etc).

Object Properties
• RangeCategory.Max property
• RangeCategory.Min property
• RangeCategory.NumItems property
• RangeCategory.Style property

Collection Properties
• RangeCategories.AllOthersCategory property
• RangeCategories.Count property
• RangeCategories.Item property

RangeCategories.AllOthersCategory property (RangeCategories

collection)
Purpose
This returns one RangeCategory object from the collection; this object describes a category for
all ranges not in the ranged theme. The RangeCategory object returned with the
AllOthersCategory has Min and Max properties that are not defined and their default value is
zero. However, you can set its Style property as shown in the example below. The text that
appears in the legend for the AllOthersCategory range category object can be set with
LegendTexts.AllOthersText property.

RangeCategories.Count property (RangeCategories collection)

Purpose
This is a read-only integer value, indicating the number of ranges in the ranged theme.
RangeCategory Object and RangeCategories Collection

RangeCategories.Item property (RangeCategories collection)

Purpose
This returns one RangeCategory object from the collection; this object describes a range in
the ranged theme.

RangeCategory.Max property (RangeCategory object)

Purpose
Contains or sets the maximum value for a range in a Ranged theme. This is a double value.
An initial value is set when the theme is created (Themes.Add) depending on the
distribution method (ThemeProperties.DistMethod):

• If ThemeProperties.DistMethod is miEqualCountPerRange, miEqualRangeSize,

miNaturalBreak, or miStandardDeviation, a new value will be set each time the
Theme object is recomputed.
• If ThemeProperties.DistMethod is miCustomRanges, MapX will assume that you
have set this value yourself, and will use the ranges that you have defined when
grouping data values. An error is generated if there are ranges that overlap when
the Theme is recomputed.

See Also
ThemeProperties.DistMethod

RangeCategory.Min property (RangeCategory object)

Purpose
Contains or sets the minimum value for a range in a Ranged theme. This is a double value.
An initial value is set when the theme is created (Themes.Add) depending on the
distribution method (ThemeProperties.DistMethod):
• If ThemeProperties.DistMethod is miEqualCountPerRange, miEqualRangeSize,
miNaturalBreak, or miStandardDeviation, a new value will be set each time the
Theme object is recomputed.
• If ThemeProperties.DistMethod is miCustomRanges, MapX will assume that you
have set this value yourself, and will use the ranges that you have defined when
grouping data values. An error is generated if there are ranges that overlap when
the Theme is recomputed.

484 MapInfo MapX Developer Guide v4.5

 RangeCategory.NumItems property (RangeCategory object)

See Also
ThemeProperties.DistMethod

Themes.Add

Theme.AutoRecompute

RangeCategory.NumItems property (RangeCategory object)

Purpose
NumItems is the number of features that fall into the range specified by the Min and Max
properties for this range category. This is an Integer value and is a read-only property.

Note: This property is only valid when MapX generates the theme
(Theme.ComputeTheme = TRUE). If you are manually calculating the theme
(Theme.ComputeTheme = FALSE), then NumItems will NOT reflect the number
of items in the category and is undefined as a result.

RangeCategory.Style property (RangeCategory object)

Purpose
Contains the Style for all objects within the Min and Max properties' range for the given
RangeCategory object. It may be set to an existing style object or you may set the Style
properties individually.

Note: If you are using ranges for a theme and specifying range colors individually (ie
per range), ThemeProperties.SpreadBy must be set to miSpreadByNone.

MapInfo MapX Developer Guide v4.5 485

RangeCategory Object and RangeCategories Collection

486 MapInfo MapX Developer Guide v4.5

Rectangle Object

Rectangle objects are used to specify the extents of an object. Several properties, such as
Map.Bounds, Feature.Bounds, and Layer.Bounds, are rectangle objects. A rectangle is defined
by its minimum and maximum X coordinates, and its minimum and maximum Y coordinates.
For geographic properties (such as Map.Bounds), these coordinates will be specified in terms
of the Map.NumericCoordSys. For methods relating to Windows (such as
Style.DrawLineSample), the properties of the Rectangle object will be in pixel values.

Object Properties
• Rectangle.Height property
• Rectangle.Width property
• Rectangle.XMax property
• Rectangle.XMin property
• Rectangle.YMax property
• Rectangle.YMin property

Object Methods
• Rectangle.Offset method
• Rectangle.Set method

Rectangle.Height property (Rectangle object)

Purpose
The height of the rectangle. The height is defined as Rectangle.YMax - Rectangle.YMin. This is
a read-only double property. To change the height of the rectangle, use the Rectangle.Set
method.
Rectangle Object

Rectangle.Offset method (Rectangle object)

Purpose
Changes the position of a rectangle by changing its coordinates. This shifts the rectangle by
deltaX in the X direction and deltaY in the Y direction.

Syntax
Object.Offset( deltaX, deltaY )

Part Description
OBJECT Represents a Rectangle object.
deltaX Double value, representing the amount to shift the rectangle in the X
direction.
deltaY Double value, representing the amount to shift the rectangle in the Y
direction.

Rectangle.Set method (Rectangle object)

Purpose
This property sets the coordinates of a rectangle. Rectangle.Set will sort the parameters to
ensure that Rectangle.XMin <= Rectangle.XMax and Rectangle.YMin <= Rectangle.YMax.
You're allowed to pass parameters where x1 > x2 or y1 > y2.

Syntax
OBJECT.Set (x1, y1, x2, y2)

Part Description

OBJECT Represents a Rectangle object.

x1, y1 Double values, representing the coordinates of one corner of the rectangle.
x2, y2 Double values, representing the coordinates of the opposite corner of the
rectangle.

488 MapInfo MapX Developer Guide v4.5

 Rectangle.XMax property (Rectangle object)

Rectangle.Width property (Rectangle object)

Purpose
The width of the rectangle. The width is defined as Rectangle.XMax - Rectangle.XMin. This
is a read-only Double property. To change the width of the rectangle, use the Rectangle.Set
method.

Rectangle.XMax property (Rectangle object)

Purpose
The coordinate of the left edge of the rectangle. It is a read-only double property. In order to
change the location of the rectangle, use the Rectangle.Set or Rectangle.Offset methods.

Rectangle.XMin property (Rectangle object)

Purpose
The coordinate of the right edge of the rectangle. It is a read-only double property. In order
to change the location of the rectangle, use the Rectangle.Set or Rectangle.Offset methods.

Rectangle.YMax property (Rectangle object)

Purpose
The coordinate of the top edge of the rectangle. It is a read-only double property. In order to
change the location of the rectangle, use the Rectangle.Set or Rectangle.Offset method.

Rectangle.YMin property (Rectangle object)

Purpose
The coordinate of the bottom edge of the rectangle. It is a read-only double property. In
order to change the location of the rectangle, use the Rectangle.Set or Rectangle.Offset
method.

MapInfo MapX Developer Guide v4.5 489

Rectangle Object

490 MapInfo MapX Developer Guide v4.5

 ResolveObject.TableName property (ResolveObject object)

ResolveObject Object and ResolveObjects

Collection

A ResolveObjects collection is passed as a parameter to the ResolveDataBindEx event. It is a

collection of the candidate layers which may be bound to when using automatic
databinding.

Object Properties
• ResolveObject.TableName property
• ResolveObject.SourceMatch property
• ResolveObject.TableMatch property

Collection Properties
• ResolveObjects.Count property
• ResolveObjects.Item property

See Also
ResolveDataBindEx event

ResolveObject.TableName property (ResolveObject object)

Purpose
This property is used to set the name of table being resolved.

ResolveObject.SourceMatch property (ResolveObject object)

Purpose
This is the percentage of source rows matching the table. Example: If the source data is 5
rows and 4 match this vaule = 80.

ResolveObject.TableMatch property (ResolveObject object)

Purpose
Percentage of map objects matching the source data. Example: If the source data is 5 rows
and 4 match and the map has 50 objects then the value = 8.

MapInfo MapX Developer Guide v4.5 491

ResolveObject Object and ResolveObjects Collection

ResolveObjects.Count property (ResolveObjects collection)

Purpose
Number of items in collection.

ResolveObjects.Item property (ResolveObjects collection)

Purpose
This returns a ResolveObject object from a collection. This is a Variant and you can specify
the name or 1 based index number. This is a default property of the ResolveObjects
collection.

492 MapInfo MapX Developer Guide v4.5

 RowValue.ReadOnly property (RowValue object)

RowValue Object and RowValues Collection

The RowValue object represents a single value for a field in a Dataset. A collection of
RowValue objects is returned by Dataset.RowValues.
RowValues collection is a group of createable RowValue objects. The RowValues collection
can be passed to Layer.UpdateFeature, Layer.AddFeature, and Feature.Update to specify
data values for fields in Datasets that are bound to the layer being updated.

Object Properties
• RowValue.Dataset property
• RowValue.Field property
• RowValue.ReadOnly property
• RowValue.Value property

Collection Properties
• RowValues.Count property
• RowValues.Item property
• RowValues.ReadOnly property

Collection Methods
• RowValues.Add method
• RowValues.Clone method
• RowValues.Remove method
• RowValues.RemoveAll method

See Also
Layer.UpdateFeature method

Layer.AddFeature method

Feature.Update method
Dataset.RowValues property

RowValue.ReadOnly property (RowValue object)

Purpose
This property determines whether or not the properties can be set on the object.

MapInfo MapX Developer Guide v4.5 493

RowValue Object and RowValues Collection

RowValue.Dataset property (RowValue object)

Purpose
This property is used to specify which Dataset the value is for.

RowValue.Field property (RowValue object)

Purpose
This property is used to specify the field in the Dataset that the value is for.

RowValue.Value property (RowValue object)

Purpose
This property is used to specify the value for the field.

RowValues.Count property (RowValues collection)

Purpose
This read-only property specifies the number of rows in the the RowValues collection.

RowValues.ReadOnly property (RowValues collection)

Purpose
This read-only property specifies whether or not properties can be set on the collection. It
will be "True" for the Datasets.RowValues collection and "False" for independently created
RowValue objects.

RowValues.Item property (RowValues collection)

Purpose
This returns a specific RowValue object from the RowValues collection.

494 MapInfo MapX Developer Guide v4.5

Syntax
OBJECT.Item (index)

Part Description

OBJECT Represents a RowValues collection.

index Variant: This specifies which item in the collection to return. It can be
either a field name or a numeric index.

RowValues.Remove method (RowValues collection)

Purpose
This method removes a specified RowValue object from the collection.

Note: Though removed from the collection, it will leave the Dataset in tact.

Syntax
OBJECT.Remove (index)

Part Description

OBJECT Represents a RowValues collection.

index Variant: This specifies the item in the collection to remove. It can be
either a field name or a numeric index.

RowValues.Add method (RowValues collection)

Purpose
This property adds a RowValue object to a specified RowValues collection.

Syntax
[ RowValues= ] OBJECT.Add (RowValue)

Part Description

OBJECT Represents a RowValues collection.

RowValue This represents a RowValue object to add to the collection.
RowValue Object and RowValues Collection

RowValues.RemoveAll method (RowValues collection)

Purpose
This method removes all RowValue objectss from a RowValues collection.

Note: Though removed from the collection, it will leave the Dataset in tact.

Syntax
OBJECT.RemoveAll

Part Description

OBJECT Represents a RowValues collection.

RowValues.Clone method (RowValues collection)

Purpose
This method clones specified row values from a Dataset and returns a new RowValue object.
The clone is not read-only or read/write.

Syntax
[ RowValues= ]OBJECT.Clone

Part Description

OBJECT Represents a RowValues collection.

496 MapInfo MapX Developer Guide v4.5

Selection Collection

A fundamental function of MapX is selecting objects or records so that you can perform
additional tasks on them such as getting more information. A Selection is a collection of
Feature objects.

The Layer.Selection object is a special Features collection in that objects can be added to or
removed from it by the end user if they use of any of the selection tools. You can get a
snapshot of a layer's selection by using the Clone method to return a Features object.

MapX gives you a number of commands and tools for making selections, the Select tool,
Radius Select, Marquee Select, and Boundary Select tool.

To select records with the tools, click on or encircle the associated graphic objects.

Use the property and methods in the Selection collection and Feature objects to obtain
additional information or manipulate the features of the collection.

Collection Methods
• Selection.Add method
• Selection.ClearSelection method
• Selection.Clone method
• Selection.Common method
• Selection.Remove method
• Selection.Replace method
• Selection.SelectAll method
• Selection.SelectByID method
• Selection.SelectByPoint method
• Selection.SelectByRadius method
• Selection.SelectByRectangle method
• Selection.SelectByRegion method

See Also
Layer object
Feature object

Selection.Count property (Selection collection)

Purpose
Number of items in the collection.
Selection Collection

Selection.Item property (Selection collection)

Purpose
This returns a Feature object from the selection collection - currently only numeric indexes
are supported. This is a default property for the Selection collection.

Selection.Add method (Selection collection)

Purpose
This method adds a Feature Object, FindFeature Object or all features from a Features
Collection into the Selection Collection (UNION set operation). The result is that this
Selection Collection contains all features in the selection before the call, and all features in
the object they are passed in. The object passed in will remain unchanged

Syntax
OBJECT.Add (Source)

Part Description

OBJECT Represents a Selection collection.

Source The Feature, Features or FindFeature object to add.

See Also
Feature object and collection

FindFeature Object

Selection.ClearSelection method (Selection collection)

Purpose
This method deselects all features in this layer. Use Layers.ClearSelection to clear the
selection from all layers.

Syntax
OBJECT.ClearSelection

Part Description

OBJECT Represents a Selection collection.

498 MapInfo MapX Developer Guide v4.5

 Selection.Common method (Selection collection)

Selection.Clone method (Selection collection)

Purpose
This method makes a copy of the collection as a Features collection object.

Syntax
OBJECT.Clone

Part Description

OBJECT Represents a Selection collection.

Selection.Common method (Selection collection)

Purpose
This method combines this collection with a Feaure Object, a FindFeature Object or a
Features Collection so that this Selection collection contains only features that are in both.
(INTERSECT set operation). This will remove each feature from the Selection Collection
which is not in the object passed in. The object passed in will remain unchanged.

Syntax
OBJECT.Common (Source)

Part Description
OBJECT Represents a Selection collection.
Source This is the Feature object , FindFeature object, or Features
collection you will combine with an OBJECT.

Selection.Remove metho (Selection collection)

Purpose
This method removes a Feaure object, a FindFeature object or all features in a Features
collection from this collection (SUBTRACT set operation). The Selection collection will then
contain only features that are not in the object that is passed in. The object passed in will
remain unchanged.

MapInfo MapX Developer Guide v4.5 499

Selection Collection

Syntax
OBJECT.Remove (Source)

Part Description
OBJECT Represents a Selection collection.
Source This is the Feature object , FindFeature object, or Features
collection you remove from OBJECT.

Selection.Replace method (Selection collection)

Purpose
This method replaces the contents of the collection with a Feaure Object, a FindFeature
Object or a Features Collection. This selection collection will then contain only the features
in the object passed in. The object passed in will remain unchanged.

Syntax
OBJECT.Replace (Source)

Part Description

OBJECT Represents a Selection collection.

Source This is the Feature object , FindFeature object, or Features
collection you will replace OBJECT with.

Selection.SelectAll metho (Selection collection)

Purpose
Selects all features within a layer.

Syntax
Map.Selection.SelectAll SelectionTypeConstant

See Also
SelectionTypeConstant

500 MapInfo MapX Developer Guide v4.5

 Selection.SelectByPoint method (Selection collection)

Selection.SelectByID method (Selection collection)

Purpose
Selects the feature by FeatureID or FeatureKey. FeatureKey is a string value that identifies a
feature. This is the value returned by Feature.FeatureKey propert . You can use
FeatureKey anywhere FeatureID can be used.

Syntax
OBJECT.SelectByID (*FeatureID, Flag)

Part Description

OBJECT Represents a Selection collection.

*FeatureID FeatureID of the feature to select. You may also use the FeatureKey.
Flag This controls whether this selected feature is added to, removed
from, or replaces the current selection. This takes a
SelectionTypeConstants value.

Note: Although the FeatureID parameter is still a functional part of MapX, it is

recommended that you use the FeatureKey for the sake of simplicity and
expedience. The FeatureKey is used to identify a unique record in a table. In
previous versions, the FeatureID property was used for this purpose, but it did
not work correctly for seamless and remote layers. The FeatureKey property
works for all layer types.

Selection.SelectByPoint method (Selection collection)

Purpose
Selects the feature at a specified location within the layer

Syntax
OBJECT.SelectByPoint (X, Y,Flag)

Part Description
OBJECT Represents a Selection collection.
X X coordinate of the point to select at. double value (Longitude).
Y Y coordinate of the point to select at. double value (Latitude).
Flag This controls whether this selected feature is added to, removed
from, or replaces the current selection. This takes a
SelectionTypeConstants value.

MapInfo MapX Developer Guide v4.5 501

Selection Collection

Remarks
If you are selecting regions, the SelectByPoint method will select a region that contains the
location. If you are selecting points or lines, the method will select a point or line within 3
pixels of the location.

Selection.SelectByRadius method (Selection collection)

Purpose
Selects features from the layer within a specified radius around a point. A flag
(SelectionTypeConstant) controls whether these selected features are added to, removed
from, or replace the current selection.

Syntax
OBJECT.SelectByRadius (X, Y,Radius, Flag)

Part Description

OBJECT Represents a Selection collection.

X X coordinate of center of circle. Double value (Longitude).
Y Y coordinate of center of circle. Double value (Latitude).
Radius Radius of the search. A double specifying the distance from the
point specified by X and Y in Map units.
Flag This controls whether the selected objects are added to, removed
from, or replace the current selection. This takes a
SelectionTypeConstants value.

Remarks
A feature is considered to be within "within" the radius if and only if its centroid is within
the radius. If you need more control over selection criteria, you may want to use the Layer
object's SearchWithinDistance method.

502 MapInfo MapX Developer Guide v4.5

 Selection.SelectByRegion method (Selection collection)

Selection.SelectByRectangle method (Selection collection)

Purpose
Selects features within a rectangle.

Syntax
OBJECT.SelectByRectangle (X1, Y1, X2, Y2, Flag)

Part Description

OBJECT Represents a Selection collection.

X1 First x coordinate of the rectangle. Double value (Longitude).
Y1 First y coordinate of the rectangle. Double value (Latitude).
X2 Second x coordinate of the rectangle. Double value (Longitude).
Y2 Second y coordinate of the rectangle. Double value (Latitude).
Flag This controls whether the selected objects are added to, removed from,
or replace the current selection. This takes a SelectionTypeConstants
value.

Remarks
A feature is considered to be "within" the rectangle if and only if its centroid is within the
radius. If more control over selection criteria is needed, you may want to use the Layer
object's SearchWithinRectangle method.

See Also
Layer.SearchWithinRectangle method

Selection.SelectByRegion method (Selection collection)

Purpose
Selects features from the layer within a region. A flag (SelectionTypeConstant) controls
whether these selected features are added to, removed from, or replace the current selection.

Syntax
OBJECT.SelectByRegion (Layer, *FeatureKey, Flag)

Part Description

OBJECT Represents a Selection collection.

MapInfo MapX Developer Guide v4.5 503

Selection Collection

Part Description

Layer Layer that the region to select within resides. This takes a Layer object.
FeatureKey *FeatureKey (a string) of the region to select within. This is a
replacement for FeatureID parameter. FeatureID still works as it did
before, but it is recommended that you use the new FeatureKey
parameter. The FeatureKey is used to identify a unique record in a
table. In previous versions, the FeatureID property was used for this
purpose, but it did not work correctly for seamless and remote layers.
The FeatureKey property works for all layer types.
Flag This controls whether the selected objects are added to, removed from,
or replace the current selection. This takes a SelectionTypeConstants
value.

Remarks
A feature is considered to be within "within" the region if and only if its centroid is within
the radius. If you need more control over selection criteria, you may want to use the Layer
object's SearchWithinFeature method.

See Also
Feature.FeatureKey property

Layer.SearchWithinFeature method

504 MapInfo MapX Developer Guide v4.5

 SourceRow.Row property (SourceRow object)

SourceRow Object and SourceRows Collection

The Dataset.SourceRows property is used to get a collection of rows (as SourceRow objects)
from the original data source that were aggregated together for a row in the MapX Dataset.
Use this object to identify which row or rows in the original source data are represented by a
row in the MapX Dataset. This is particularly useful when working with Selections and
Feature objects.

Object Properties
• SourceRow.Row property

Collection Properties
• SourceRows.Count property
• SourceRows.Item property

SourceRow.Row property (SourceRow object)

Purpose
Contains the row number from the original data source. This is an Integer value and is read-
only.

The row numbers start at 1 and are sequential in the order that the data was read from the
original source data. This is a default property of the SourceRow object.

SourceRows.Count property (SourceRows collection)

Purpose
Contains the number of SourceRow objects in a collection. This is a 1 based Integer value,
and is read-only.

SourceRows.Item property (SourceRows collection)

Purpose
This gets a SourceRow object from the collection. An index is used to specify which
SourceRow to get. The index is an Integer value from 1 to SourceRows.Count, or a Feature
object. This is the default property of the SourceRows collection.

MapInfo MapX Developer Guide v4.5 505

SourceRow Object and SourceRows Collection

Syntax
[ SourceRow= ]OBJECT.Item (index)

Part Description

OBJECT Represents a SourceRows object.

index Row in Dataset to get value. This is a Variant, and can be a row number or a
Feature object.

The Dataset.SourceRows property is a SourceRows collection, which contains a SourceRow

object for each row in the original data source that was aggregated to the row in the MapX
Dataset.

You can use a Feature object as the Row parameter, since a feature object uniquely identifies
a single row in the Layer that the Dataset is bound to.

506 MapInfo MapX Developer Guide v4.5

 SourceRows.Item property (SourceRows collection)

Style Object

The Style object contains attributes for drawing symbols, lines, regions, and text. The object
contains attributes for all feature types, even though a particular feature type only uses a
subset of the properties. The property names begin with a keyword indicating the feature
type it applies to.

Object Properties
• Style.LineColor property
• Style.LineInterleaved property
• Style.LineStyle property
• Style.LineStyleCount property
• Style.LineSupportsInterleave property
• Style.LineWidth property
• Style.LineWidthUnit property
• Style.RegionBackColor property
• Style.RegionBorderColor property
• Style.RegionBorderStyle property
• Style.RegionBorderWidth property (Style object)
• Style.RegionBorderWidthUnit property
• Style.RegionColor property
• Style.RegionPattern property
• Style.RegionTransparent property
• Style.SupportsBitmapSymbols property
• Style.SymbolBitmapColor property
• Style.SymbolBitmapName property
• Style.SymbolBitmapOverrideColor property
• Style.SymbolBitmapSize property
• Style.SymbolBitmapTransparent property
• Style.SymbolCharacter property
• Style.SymbolFont property
• Style.SymbolFontBackColor property
• Style.SymbolFontColor property
• Style.SymbolFontHalo property
• Style.SymbolFontOpaque property
• Style.SymbolFontRotation property
• Style.SymbolFontShadow property
• Style.MinVectorSymbolCharacter property
• Style.MaxVectorSymbolCharacter property
• Style.SymbolVectorColor property
• Style.SymbolVectorSize property
• Style.TextFont property
• Style.TextFontAllCaps property

MapInfo MapX Developer Guide v4.5 507

Style Object

• Style.TextFontBackColor property
• Style.TextFontColor property
• Style.TextFontDblSpace property
• Style.TextFontHalo property
• Style.TextFontOpaque property
• Style.TextFontShadow property
• Style.TextFontRotation property
• Style.SymbolType property

Object Methods
• Style.Clone method
• Style.DrawLineSample method
• Style.DrawRegionSample method
• Style.DrawSymbolSample method
• Style.DrawTextSample method
• Style.ExportLineSample method
• Style.ExportRegionSample method
• Style.ExportSymbolSample method
• Style.ExportTextSample method
• Style.PickLine method
• Style.PickRegion method
• Style.PickSymbol method
• Style.PickText method

Style.Clone method (Style object)

Purpose
This returns a stand-alone Style object which is a copy of another Style object.

Syntax
OBJECT.Clone

The OBJECT placeholder represents a Style object.

Remarks
When you reference a Style object that is owned by another object (for example, using an
expression such as objFeature.Style), any changes that you make to the style automatically
affect the style's parent object.

508 MapInfo MapX Developer Guide v4.5

 Style.DrawLineSample method (Style object)

To create a modified style without affecting the parent object, use the Clone method to create
a copy of the style. The style returned by this method is a stand-alone object; changes made
to this Style object do not automatically affect any other object.You can assign a stand-alone
Style object to any object's Style property.

A Style object created through the Clone method supports bitmap symbols if and only if the
original Style object supports bitmap symbols.

Style.DrawLineSample method (Style object)

Purpose
This method is used if the user would like to have a sample of a line style drawn into a
HDC.

Syntax
OBJECT.DrawLineSample (HDC, Rectangle)

Part Description

HDC The HDC into which the sample is drawn.

Rectangle A Rectangle object that defines the pixel coordinates in the DC that the
sample will be draw into. If the sample does not need the entire
rectangle to display, the sample will be centered in the rectangle.

Style.DrawRegionSample method (Style object)

Purpose
This method is used if the user would like to have a sample of a region style drawn into a
HDC.

MapInfo MapX Developer Guide v4.5 509

Style Object

Syntax
OBJECT.DrawRegionSample (HDC, Rectangle)

Part Description

OBJECT This represents a Style object.

HDC The HDC into which the sample is drawn.
Rectangle a MapXLib.Rectangle that defines the pixel coordinates in the DC that the
sample will be draw into. If the sample does not need the entire rectangle
to display, the sample will be centered in the rectangle.

Style.DrawSymbolSample method (Style object)

Purpose
This method is used if the user would like to have a sample of a symbol style drawn into a
HDC. This method does not work on a MetaFile device context.

Syntax
OBJECT.DrawSymbolSample (HDC, Rectangle)

Part Description

OBJECT This represents a Style object.

HDC The HDC into which the sample is drawn.
Rectangle a MapXLib.Rectangle that defines the pixel coordinates in the DC that the
sample will be draw into. If the sample does not need the entire rectangle
to display, the sample will be centered in the rectangle.

510 MapInfo MapX Developer Guide v4.5

 Style.ExportLineSample method (Style object)

Style.DrawTextSample method (Style object)

Purpose
This method is used if the user would like to have a sample of a text style drawn into a
HDC.

Syntax
OBJECT.DrawTextSample (HDC, Rectangle, SampleText)

Part Description
OBJECT Represents a Style object.
HDC The HDC into which the sample is drawn.
Rectangle A MapXLib.Rectangle that defines the pixel coordinates in the DC that
the sample will be draw into. If the sample does not need the entire
rectangle to display, the sample will be centered in the rectangle.
SampleText The text that the function will use to draw the TextStyle sample.

Style.ExportLineSample method (Style object)

Purpose
Exports the line style sample.

Syntax
OBJECT.ExportLineSample (Destination, Format, Width, Height, [BackColor])

Part Description
OBJECT Represents a Style object
Destination File specification of where to put the output, such as
"C:\Temp\Symbol.bmp". If you specify "CLIPBOARD" instead of a
file path, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value. Note: If
you specify miFormatGIF (to generate GIF files), please read the
Licensing Requirements for Users of GIF Files.
Width Width of output. This is a double value, and specifies width in terms
of pixels.
Height Height of output. This is a double value, and specifies height in terms
of pixels.

MapInfo MapX Developer Guide v4.5 511

Style Object

Part Description

BackColor Variant. Controls color of the background. Specify an OLE_COLOR

value. It can be a specific solid color or one of the Windows System
Colors such as 'Window Background'. (Most containers like Visual
Basic display a special color picker dialog in their property pages for
properties of type OLE_COLOR.)

Style.ExportRegionSample method (Style object)

Purpose
Exports the region style sample.

Syntax

512 MapInfo MapX Developer Guide v4.5

 Style.ExportSymbolSample method (Style object)

OBJECT.ExportRegionSample (Locatio , Format, Width, Height,

[BackColor ])
Part Description
OBJECT Represents a Style object
Location File specification of where to put the output, such as
"C:\Temp\Symbol.bmp". If you specify "CLIPBOARD" instead of a
file path, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value. Note: If
you specify miFormatGIF (to generate GIF files), please read the
Licensing Requirements for Users of GIF Files.
Width Width of output. This is a double value, and specifies width in terms
of pixels.
Height Height of output. This is a double value, and specifies height in terms
of pixels.
BackColor Variant: Controls color of the background. Specify an OLE_COLOR
value. It can be a specific solid color or one of the Windows System
Colors such as 'Window Background'. (Most containers like Visual
Basic display a special color picker dialog in their property pages for
properties of type OLE_COLOR.)

Style.ExportSymbolSample method (Style object)

Purpose
Exports the symbol style sample.

Syntax
OBJECT.ExportSymbolSample (Location, Format, Width, Height, [BackColor ] )

Part Description

OBJECT Represents a Style object

Location File specification of where to put the output, such as
"C:\Temp\Symbol.bmp". If you specify "CLIPBOARD" instead of a
file path, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value. Note: If
you specify miFormatGIF (to generate GIF files), please read the
Licensing Requirements for Users of GIF Files.

MapInfo MapX Developer Guide v4.5 513

Style Object

Part Description

Width Width of output. This is a double value, and specifies width in terms
of pixels.
Height Height of output. This is a double value, and specifies height in terms
of pixels.
BackColor Variant. Controls color of the background. Specify an OLE_COLOR
value. It can be a specific solid color or one of the Windows System
Colors such as 'Window Background'. (Most containers like Visual
Basic display a special color picker dialog in their property pages for
properties of type OLE_COLOR.)

Style.ExportTextSample method (Style object)

Purpose
Exports the text style sample.

Syntax
OBJECT.ExportTextSample (Location, Format, Width, Height, [BackColor ])

Part Description
OBJECT Represents a Style object
Location File specification of where to put the output, such as
"C:\Temp\Symbol.bmp". If you specify "CLIPBOARD" instead of a
file path, the image is put on the clipboard.
Format Output format. This takes an ExportFormatConstants value. Note: If
you specify miFormatGIF (to generate GIF files), please read the
Licensing Requirements for Users of GIF Files.
Width Width of text output. This is a double value, and specifies width in
terms of pixels.
Height Height of text output. This is a double value, and specifies height in
terms of pixels.
SampleText String. The sample text to export.
BackColor Variant. Controls color of the background. Specify an OLE_COLOR
value. It can be a specific solid color or one of the Windows System
Colors such as 'Window Background'. (Most containers like Visual
Basic display a special color picker dialog in their property pages for
properties of type OLE_COLOR.)

514 MapInfo MapX Developer Guide v4.5

 Style.LineInterleaved property (Style object)

Style.LineColor property (Style object)

Purpose
Contains the line color. Used for linear objects. This is an OLE_COLOR value.

Style.LineInterleaved property (Style object)

Purpose
A read-write Boolean property. It is used to make a pen style interleaved if that pen style
supports being interleaved with the LineSupportsInterleave property. An interleaved pen
style can create the appearance of intersections on your maps for overlapping intersections
and lines.

Style.LineStyle property (Style object)

Purpose
This returns or sets a line style number (solid, dashed, etc.) and is used to display linear
features.

Remarks
This property is a read-write integer line style number: 0 represents a non–visible line, 1 a
solid line, and a larger number for a patterned line; see table below.

You can assign any PenStyleConstants value to this property. However, most of the line
styles do not have corresponding constants. The table below shows the complete set of
LineStyle numbers.

MapInfo MapX Developer Guide v4.5 515

Style Object

Note: The table (above) shows the default styles. If the user has customized the
mapx.pen file (the file that defines the line styles), the set of available styles might
not match the table shown above. Use the LineStyleCount property to determine
the number of styles in the .pen file.

516 MapInfo MapX Developer Guide v4.5

 Style.LineSupportsInterleave property (Style object)

Style.LineStyleCount property (Style object)

Purpose
A read-only integer value, indicating the number of line styles that are available. The count
includes pen styles read in from the mapx.pen file.

Style.LineSupportsInterleave property (Style object)

Purpose
A read-only Boolean property. Denotes whether a given pen style supports interleave or not.

See Also
Style.LineInterleaved

Style.LineWidth property (Style object)

Purpose
Contains the width of a line in pixels and is used for linear objects. This is an Integer value.

Style.LineWidthUnit property (Style object)

Purpose
Controls the unit of measurement for the line width. The width is specified in either pixels
or tenths of points, by specifying a StyleUnitConstants value.

See Also
Style.LineWidth

Style.PickLine method (Style object)

Purpose
This displays the Line Style Picker dialog that allows a user to choose line style properties.
The Style object is updated with the new properties if the user clicks OK in the dialog.

Syntax
OBJECT.PickLine

MapInfo MapX Developer Guide v4.5 517

Style Object

Style.PickRegion method (Style object)

Purpose
This displays the Region Style Picker dialog that allows a user to choose region style
properties. The Style object is updated with the new properties if the user clicks OK in the
dialog.

Syntax
OBJECT.PickRegion

Style.PickSymbol method (Style object)

Purpose
This displays the Symbol Style Picker dialog that allows a user to choose symbol style
properties. The style object is updated with the new properties if the user clicks OK in the
dialog.

Syntax
OBJECT.PickSymbol

Style.PickText method (Style object)

Purpose
This displays the Text Style Picker dialog that allows a user to choose text style properties.
The style object is updated with the new properties if the user clicks OK in the dialog.

Syntax
OBJECT.PickText

Style.RegionBackColor property (Style object)

Purpose
Contains the region background color and is used when a RegionPattern other than
miPatternSolid is specified for region objects. This is an OLE_COLOR value.

See Also
FillPatternConstants

518 MapInfo MapX Developer Guide v4.5

Style.RegionBorderColor property (Style object)
Purpose
Contains the region border color and is used for region objects. This is an OLE_COLOR value.

Style.RegionBorderStyle property (Style object)

Purpose
Contains the line style for a region border and is used for region objects. This takes a
PenStyleConstants value.

Style.RegionBorderWidth property (Style object)

Purpose
Contains the width of a region border and is used for region objects. This is an Integer value,
and width is specified in pixels.

Style.RegionBorderWidthUnit property (Style object)

Purpose
Controls the unit of measurement for the region border width. The width is specified in either
pixels or tenths of points, by specifying a StyleUnitConstants value.

See Also
Style.RegionBorderWidth

Style.RegionColor property (Style object)

Purpose
Contains the region color and is used for region objects. This is an OLE_COLOR value.
Style Object

Style.RegionPattern property (Style object)

Purpose
Contains the region pattern and is used for region objects. This takes a FillPatternConstants
value.

Style.RegionTransparent property (Style object)

Purpose
A read-write Boolean value, indicating whether a region drawn with a pattern is
transparent. A value of True makes the region transparent, while False makes it opaque.

Remarks
If a region feature is drawn with a fill pattern (as opposed to a solid fill), you can control
whether the fill pattern is transparent. Use a transparent fill style if features on your map
overlap, and you want to see what is underneath a region.

The following picture shows two buffer regions. The region on the left is opaque; the region
on the right is transparent, allowing you to see features beneath the region.

The RegionTransparent property does not have any effect on regions drawn with a solid fill.

Style.SupportsBitmapSymbols property (Style object)

Purpose
A read-only Boolean value, indicating whether the style object supports bitmap symbols.

Remarks
A True value indicates that the Symbol object supports bitmap symbols.

Currently, only Feature, Layer, and Theme objects support bitmap symbols.

520 MapInfo MapX Developer Guide v4.5

 Style.SymbolBitmapColor property (Style object)

See Also
Bitmap Symbols

Style.SymbolBitmapColor property (Style object)

Purpose
A read-write OLE_COLOR value, used to override the non-white pixels in a bitmap symbol.

Remarks
To make the non-white pixels in a bitmap symbol appear in a particular color:
1. Set the SymbolBitmapColor property to the desired color.

2. Set the SymbolBitmapOverrideColor property to True.

When you change a TrueType font symbol into a bitmap symbol - in other words, when you
change the SymbolType property to miSymbolTypeBitmap (1) - MapX sets the
SymbolBitmapColor property to match the SymbolFontColor property.

See Also
Bitmap Symbols

Style.SymbolBitmapName property (Style object)

Purpose
A read-write string value, representing the name of the bitmap file to use as a bitmap
symbol.

Remarks
The name that you specify should not include a full directory path. The bitmap file must be
in the custom symbol directory, currently defined to be:

<path>\CUSTSYMB
where <path> is the path where the MapX Common Files are installed, e.g. C:\Program
Files\Common Files\MapInfo Shared\MapXCommon.

See Also
Bitmap Symbols

MapInfo MapX Developer Guide v4.5 521

Style Object

Style.SymbolBitmapOverrideColor property (Style object)

Purpose
A read-write Boolean value, indicating whether the non-white pixels in a bitmap symbol are
drawn in an override color.

Remarks
The default is false, meaning that the non–white pixels in a bitmap symbol will appear in
their default colors. If you want all of the non–white pixels to display in an override color
(the color specified by the SymbolBitmapColor property), set this property to True.

See Also
Bitmap Symbols

Style.SymbolBitmapSize property (Style object)

Purpose
A read-write integer value, indicating the size of the symbol, in points. 72 points is
equivalent to 1 inch.

Remarks
When you change a TrueType font symbol into a bitmap symbol - in other words, when you
change the SymbolType property to miSymbolTypeBitmap (1) - MapX sets the
SymbolBitmapSize property to match the value of the SymbolFont.Size property. For
example, if you change a 12-point TrueType font symbol into a bitmap symbol, the
SymbolBitmapSize will be 12.

See Also
Bitmap Symbols

522 MapInfo MapX Developer Guide v4.5

 Style.SymbolCharacter property (Style object)

Style.SymbolBitmapTransparent property (Style object)

Purpose
A read-write Boolean value, indicating whether the white portion of a bitmap symbol is
drawn as transparent.

Remarks
Default value is False, meaning that the white portion of a bitmap symbol will appear white.
Set to True if you want white portions of the bitmap to be transparent.

See Also
Bitmap Symbols

Style.SymbolCharacter property (Style object)

Purpose
This property specifies which symbol to use. Used for symbol objects. This takes an Integer
value between 0 and 255, and represents the ASCII code of the character in the TrueType
font set to use.

See Also
Style.SymbolFont

Style.SymbolFont property (Style object)

Purpose
This returns a standard Font object (IFontDispatch, OLE_FONT) which allows you to set
font properties (Bold, Size, etc.) to alter a symbol's appearance and can only apply to
TrueType font symbols.

Remarks
A symbol can be defined by the combination of a TrueType font and a character within that
font (Style.SymbolCharacter). Therefore, if you need to modify the appearance of a symbol,
you might need to obtain and modify the symbol's Style.SymbolFont property.

The SymbolFont property is read-only; however, you can set the properties of the Font
object that it returns.

MapInfo MapX Developer Guide v4.5 523

Style Object

See Also
Style.SymbolCharacter property

Setting Font Attributes

Style.SymbolFontBackColor property (Style object)

Purpose
This contains the symbol background color and is used for symbol objects and can only
apply to TrueType font symbols. This is an OLE_COLOR value.

Style.SymbolFontColor property (Style object)

Purpose
Contains the symbol color. Used for symbol objects and can only apply to TrueType font
symbols. This is an OLE_COLOR value.

Style.SymbolFontHalo property (Style object)

Purpose
This read/write property controls whether a halo is drawn around the symbol. Used for
symbol objects and can only apply toTrueType font symbols. A halo is a `buffer' around the
symbol - to help offset it from the map beneath. This is a Boolean value that one can set to
true for individual features.

Style.SymbolFontOpaque property (Style object)

Purpose
This read/write property controls whether the symbol displays a background color (and is
thus opaque). Used for symbol objects and can only apply toTrueType font symbols. This is
a Boolean value.

524 MapInfo MapX Developer Guide v4.5

 Style.SymbolFontShadow property (Style object)

Style.SymbolFontRotation property (Style object)

Purpose
Read-write integer value, indicating the number of degrees to rotate a TrueType symbol.

Remarks
This property should be set to an integer between zero and 360. Rotation is clockwise.
This property only applies to TrueType font symbols, not to bitmap symbols; bitmap
symbols cannot be rotated.

Feature, Layer, and Theme objects support rotated symbols. If an object does not support
rotated symbols, this property is ignored.

Style.SymbolFontShadow property (Style object)

Purpose
Applies only to Layer Styles and Label Styles. Controls whether a shadow is drawn under
the symbol. Used for symbol objects and can only apply to TrueType font symbols. This is a
Boolean value.

Style.MinVectorSymbolCharacter property (Style object)

Purpose
This property applies to Symbol Style objects. It is a read-only integer property which
contains the minimum value of Style.SymbolCharacter which will yield a Vector symbol.
For these symbols, the Style.SymbolType should be set to miSymbolTypeVector.

Style.MaxVectorSymbolCharacter property (Style object)

Purpose
This property applies to Symbol Style objects. It is a read-only integer property which
contains the maximum value of Style.SymbolCharacter which will yield a vector symbol.
For these symbols, the Style.SymbolType should be set to miSymbolTypeVector.

MapInfo MapX Developer Guide v4.5 525

Style Object

Style.SymbolVectorColor property (Style object)

Purpose
This property applies to vector symbol Style objects. It is a read-write OLE_COLOR value
which specifies the color of the vector symbol. The default is miColorBlack.

Style.SymbolVectorSize property (Style object)

Purpose
This property applies to vector symbol Style objects. It is a read-write Integer value which
specifies the point size of the vector symbol. The default is 12.

Style.TextFont property (Style object)

Purpose
This returns a standard Font object (IFontDispatch, OLE_FONT) which allows you to set
font properties (Bold, Size, etc.) to alter the appearance of text features.

Remarks
The TextFont property is read-only; however, you can set the properties of the Font object
that it returns.

Style.TextFontAllCaps property (Style object)

Purpose
Applies only to Layer Styles and Label Styles. Controls whether the text is displayed in all
capital letters. Used for text objects. This is a Boolean value.

Style.TextFontBackColor property (Style object)

Purpose
Contains the text background color. Used for text objects. This is an OLE_COLOR value.

See Also
OLE_Color Values

526 MapInfo MapX Developer Guide v4.5

 Style.TextFontDblSpace property (Style object)

Style.TextFontColor property (Style object)

Purpose
Contains the text color. Used for text objects. This is an OLE_COLOR value.

See Also
OLE_Color Values

Style.TextFontDblSpace property (Style object)

Purpose
Applies only to Layer Styles and Label Styles. Controls whether the text is displayed using
large spacing between the letters. Used for text objects. This is a Boolean value.

Style.TextFontHalo property (Style object)

Purpose
Applies only to Layer Styles and Label Styles. Controls whether a halo is drawn around the
text. This is used for text objects. A halo is a `buffer' around the text - to help offset it from
the map beneat. This is a Boolean value.

Style.TextFontOpaque property (Style object)

Purpose
Controls whether the text displays a background color (and is thus opaque). This is used for
text objects and is a Boolean value.

Style.TextFontShadow property (Style object)

Purpose
Applies only to Layer Styles and Label Styles. It controls whether a shadow is drawn under
the text. This is used for text objects and is a Boolean value.

MapInfo MapX Developer Guide v4.5 527

Style Object

Style.TextFontRotation property (Style object)

Purpose
Indicates the number of degrees to rotate (clockwise) a Text object. Valid values are 0 <= x
<= 360. Currently valid only for Feature objects. If set/queried for any object other that a
Feature object, this property is ignored/undefined.

Style.SymbolType property (Style object)

Purpose
A read-write short value, indicating how to display a point feature (as a character from a
TrueType font, a bitmap, or a VectorSymbol). It should be set to one of the
SymbolTypeConstants.

Remarks
To use a TrueType font symbol, set this to miSymbolTypeTrueTypeFont.

To change to a bitmap symbol, set this to miSymbolTypeBitmap.

To change to a vector symbol, set this to miSymbolTypeVector.

Note: Only some objects (Feature, Layer, Theme) support bitmap symbols. Attempting
to set SymbolType to miSymbolTypeBitmap will throw an exception if the object
does not support bitmap symbols.

See Also
Bitmap Symbols

528 MapInfo MapX Developer Guide v4.5

Theme Object and Themes Collection

Theme objects contain the attributes of a theme.

Each Dataset has a collection of Themes (Dataset.Themes). The Theme collection has methods
and properties used to add and remove Theme objects from the collection.

Object Properties
• Theme.AutoRecompute property
• Theme.ComputeTheme property
• Theme.DataMax property
• Theme.DataMin property
• Theme.Fields property
• Theme.Layer property
• Theme.Legend property
• Theme.Name property
• Theme.Properties property
• Theme.ThemeProperties property
• Theme.Type property
• Theme.Visible property

Object Methods
• Theme.ThemeDlg method

Collection Properties
• Themes.Count property
• Themes.Item property

Collection Methods
• Themes.Add method
• Themes.Remove method
• Themes.RemoveAll method
Theme Object and Themes Collection

Theme.AutoRecompute property (Theme object)

Purpose
Controls when theme ranges are recomputed. This is a Boolean property, and defaults to
TRUE.

Remarks
When theme properties are changed (such as ThemeProperties.NumRanges), the Theme
object is recomputed. This can take some time. If you want to change several properties, you
should set AutoRecompute to FALSE, change the properties, then set AutoRecompute to
TRUE, and have the recomputation happen only once.

Theme.ComputeTheme property (Theme object)

Purpose
This property controls whether themes are computed from the data on the table. This is a
Boolean property, and defaults to True. A True value will calculate the theme from the raw
data.

Remarks
If the value is set to False an invisible theme object will be created with 10 ranges for
Individual value themes and 5 ranges for Ranged themes. You can then manually set the
minimum and maximum values to define the theme with Theme.DataMin property and
Theme.DataMax property. ThemeProperties.NumRanges and
IndividualValueCategory.Value properties are used to modify it.

For ranged themes you can manually set the theme ranges or calculate equal size ranges
determined by the minimum (Theme.DataMin) and maximum (Theme.DataMax) values.

When this property is set to "false", the Legend.ShowEmptyranges property must be set to
"true" in order for the theme's legend text(s) to be visible. This is because MapX does not
calculate theme category counts while ComputeTheme is "false".

530 MapInfo MapX Developer Guide v4.5

 Theme.DataMin property (Theme object)

Theme.DataMax property (Theme object)

Purpose
Determines the maximum value to set the theme ranges or calculate equal size ranges for
ranged themes when the Theme.ComputeTheme property or the ComputeTheme
parameter of the Themes.Add method is set to FALSE.

See Also
Theme.ComputeTheme

Theme.DataMin

Theme.DataMin property (Theme object)

Purpose
Determines the minimum value to set the theme ranges or calculate equal size ranges for
ranged themes when the Theme.ComputeTheme property or the ComputeTheme
parameter of the Themes.Add method is set to FALSE.

See Also
Theme.ComputeTheme

Theme.DataMax

Theme.Fields property (Theme object)

Purpose
This returns a read-only Fields collection, representing the set of fields used by the Dataset
that this theme is based on.

Theme.Layer property (Theme object)

Purpose
This is a read-only property that returns a Layer object, representing the layer that the theme
is based on.

MapInfo MapX Developer Guide v4.5 531

Theme Object and Themes Collection

Theme.Legend property (Theme object)

Purpose
Each Theme object has a Legend object (Theme.Legend). The Legend object contains
properties to control the display of a theme's legend. Each ThemeCategory object
(RangeCategory, IndividualValueCategory, or MultiVarCategory) has an entry in the legend
contained in a LegendText object.

See Also
Legend object

Theme.Name property (Theme object)

Purpose
The name of the Theme must be unique within a Themes collection. This is a read/write
property, and is either specified as a parameter to the Themes.Add method or generated by
MapX when the theme is created. This is the default property for the Theme object.

Remarks
The Name property can be used with the Themes.Item property and the Themes.Remove
method.

See Also
Themes.Add method

Themes.Item property

Themes.Remove method

Theme.Properties property (Theme object)

Purpose
This is the set of properties contained in the Theme object and is determined by the type of
thematic map in use.

Note: In MapX 3.5, we renamed Theme.Properties to Theme.ThemeProperties, but left

Theme.Properties in the object model for backward compatibility of code.
Nonetheless, Theme.ThemeProperties is the preferred way of getting to the
theme's properties.

532 MapInfo MapX Developer Guide v4.5

 Theme.ThemeDlg method (Theme object)

See Also
Theme.ThemeProperties

ThemeProperties object

Theme.ThemeDlg method (Theme object)

Purpose
Brings up a stock dialog that allows the user to manipulate the style of the Theme. The
particular dialog brought up will match the type of the Theme object (Range, Dot Density,
Pie, Bar, IndividualValues, or Graduated Symbol). If the user clicks 'OK', the changes made
within the dialog will immediately be applied to the theme on the map.

Syntax
[Boolean=]OBJECT.ThemeDlg ([HelpFile], [HelpID])

Part Description
OBJECT Represents a Theme object.
HelpFile HelpFile is an optional parameter that is a pathname to a .hlp
file that contains help topics for the dialog.
HelpID HelpID is an optional parameter that refers to the ID of a specific
help topic within the given .hlp file.

Remarks
If either of the optional parameters are not given, the help button will not appear on the
dialog.

The return value of ThemeDlg is True if the user clicked OK and False if the user clicked
Cancel.

MapInfo MapX Developer Guide v4.5 533

Theme Object and Themes Collection

Theme.ThemeProperties property (Theme object)

Purpose
An object containing properties about the theme. The set of properties contained in the
ThemeProperties object is determined by the type of the Theme object (type of thematic
map).

See Also
ThemeProperties object

Theme.Typeproperty (Theme object)

Purpose
The type of theme for a Theme object. This is a ThemeTypeConstants value and is a read-
only property.

Theme.Visible property (Theme object)

Purpose
This property sets whether or not the theme is visible. This is a Boolean value, and defaults
to TRUE.

Themes.Add method (Themes collection)

Purpose
This creates a theme and adds it to the Themes collection for a particular Dataset.

Remarks
When creating a theme, computing ranges for layers with large numbers of rows, such as
drilldown or server layers, can take some time. The ComputeTheme parameter lets you
create a non-compute theme for any theme type. A non-compute theme gives you the ability
to create a theme without having the ranges automatically calculated for you. You can then
create the ranges yourself. This is a faster way for drilldown and server layers.

Note: MapX will create an empty theme against an empty Dataset. A theme object is
created and added to the themes collection, but because the theme is based on a
Dataset with no data, the theme will not be visible.

534 MapInfo MapX Developer Guide v4.5

 Themes.Add method (Themes collection)

A Dataset with no rows would probably only occur if there is a programmer error. For
instance, if one accidentally binds USA data against the Canada layer, the result is a Dataset
with no rows (i.e. no data). If one tries to make a theme based on that Dataset, an "empty"
theme is created. The responsibility of checking whether there are any rows in the Dataset
before making a theme, is the progammer’s.

Syntax
OBJECT.Add ([Type], [Field], [Name], [ComputeTheme])

Part Description

OBJECT Represents a Themes object.

Type Specifies the type of thematic map to create. This takes a
ThemeTypeConstants value. This is an optional parameter, and if not
specified (or specified as miThemeAuto), MapX will attempt to choose a
good default based on the number of fields passed in as well as what other
theme types are already being displayed. If MapX cannot choose a default
theme type, an error is generated.
Field(s) Specifies the field or fields to thematically map. A field can be specified by
name, index, or by a Field object. If you are creating a theme using
multiple variables (such as a bar chart or pie chart), pass in a Fields
collection or an array of field names, indexes, or Field objects. This is an
optional parameter, and if not specified, MapX uses the first numeric field
of the Dataset.
Name Specifies the name of the thematic map. This is a String parameter. This is
an optional parameter, and if not specified, MapX generates a name such
as StatesBySales.
ComputeThem Boolean. The default value is True which will calculate the theme from the
e table data. If the value is set to False an invisible theme object will be
created with 10 ranges for IndividualValue themes and 5 ranges for
Ranged themes. You can then manually set the minimum and maximum
values to define the theme with Theme.DataMin and Theme.DataMax. For
ranged themes you can manually set the theme ranges or calculate equal
size ranges determined by the minimum (Theme.DataMin) and maximum
(Theme.DataMax) values.

MapInfo MapX Developer Guide v4.5 535

Theme Object and Themes Collection

See Also
Field object

Theme.DataMax property

Theme.DataMin property

Theme.Name property

Theme.Type property

Themes.Count property (Themes collection)

Purpose
The number of Theme objects in a Themes collection. This is a read-only property.

Themes.Item property (Themes collection)

Purpose
Retrieve a Theme object from the Themes collection. This takes a parameter to specify which
theme. The parameter is a Variant representing the 1 based index number, or the theme
name. This is the default property for the Themes collection.

Syntax
OBJECT.Item (index)

Part Description

OBJECT Represents a Themes object.

index Theme object 1–based index number or theme name.

See Also
Theme.Name property

536 MapInfo MapX Developer Guide v4.5

 Themes.RemoveAll method (Themes collection)

Themes.Remove method (Themes collection)

Purpose
Removes the specified Theme object from the Themes collection.

Note: If you remove an item, the collection indexes are renumbered to fill in the hole
left by the item removed.

Syntax
OBJECT.Remove (index)

Part Description

OBJECT Represents a Themes object.

index Theme object 1 based index number or theme name.

See Also
Theme.Name property

Themes.RemoveAll method (Themes collection)

Purpose
Removes all Theme objects from the collection.

Syntax
OBJECT.RemoveAll

MapInfo MapX Developer Guide v4.5 537

Theme Object and Themes Collection

538 MapInfo MapX Developer Guide v4.5

 Themes.RemoveAll method (Themes collection)

ThemeProperties Object

The ThemeProperties object is a property of a Theme object and contains the information
defining the Theme.

Note: The Theme.Properties property still works as it did before, but it is recommended
that you use the ThemeProperties object because of its improved functionality.

Object Properties
• ThemeProperties.AllowEmptyRanges property
• ThemeProperties.ApplyAttribute property
• ThemeProperties.BarFramed property
• ThemeProperties.BarFrameStyle
• ThemeProperties.BarGraduatedStack property
• ThemeProperties.BarIndependentScale property
• ThemeProperties.BarStacked property
• ThemeProperties.BarWidth property
• ThemeProperties.BorderStyle property
• ThemeProperties.ColorMethod property
• ThemeProperties.DataValue property
• ThemeProperties.DistMethod property
• ThemeProperties.DotColor property
• ThemeProperties.DotSize property
• ThemeProperties.Graduated property
• ThemeProperties.GraduateSizeBy property
• ThemeProperties.Independent property
• ThemeProperties.IndividualValueCategories property
• ThemeProperties.InflectionColor property
• ThemeProperties.InflectionRange property
• ThemeProperties.InflectRanges property
• ThemeProperties.MultivarCategories property
• ThemeProperties.NegativeSymbolStyle property
• ThemeProperties.NumRanges property
• ThemeProperties.PieClockwise property
• ThemeProperties.PieGraduated property
• ThemeProperties.PieHalfPies property
• ThemeProperties.PieStartAngle property
• ThemeProperties.PositiveSymbolStyle property
• ThemeProperties.RangeCategories property
• ThemeProperties.RoundBy property
• ThemeProperties.RoundRanges property
• ThemeProperties.ShowNegativeValues property
• ThemeProperties.Size property
• ThemeProperties.SpreadBy property

MapInfo MapX Developer Guide v4.5 539

ThemeProperties Object

• ThemeProperties.SymbolStyle property
• ThemeProperties.ValuePerDot property
• ThemeProperties.Width property

ThemeProperties.AllowEmptyRanges property (ThemeProperties

object)
Purpose
This is a read/write Boolean property that controls whether empty ranges are allowed in a
ranged theme. The default is False for a new theme, meaning that empty ranges are not
allowed in a ranged theme.

Remarks
If the ThemeProperties.DistMethod property is set to miCustomRanges (value: 0), empty
ranges are allowed, regardless of the value of the AllowEmptyRanges property.

See Also
Legend.ShowEmptyRanges

ThemeProperties.DataValue property (ThemeProperties object)

Purpose
This applies to GraduatedSymbol, Pie, and Bar themes. It works in conjunction with the Size
property to control how big the thematic graphics are at particular values. This is a double
value, and is the value at which the thematic graphic is drawn at the size specified by the
Size property. The default value for this property is set to the largest data value of the
mapped features.

See Also
ThemeProperties.Size property

540 MapInfo MapX Developer Guide v4.5

 ThemeProperties.DataValue property (ThemeProperties object)

ThemeProperties.DistMethod property (ThemeProperties object)

Purpose
This property applies to Ranged themes. It controls how ranges (in the RangeCategories
collection) are created when a Theme object is recomputed. This property takes a
DistribMethodConstants value and defaults to miEqualCountPerRange. The available
distribution types are as follows:

Distribution Description

miEqualRangeSize Takes the maximum data value and the minimum data
value, andchooses ranges by breaking the range of data
values into equally sized pieces (e.g. 0-25; 25-50; 51-75; 76-
100)
miEqualCountPerRange Attempts to assign ranges in such a way that each range
contains the same number of features.
miCustomRanges You will specify your own ranges in the RangeCategories
collection ( MapX won't compute ranges).
miNaturalBreak Range breaks are determined using an algorithm that
attempts to minimize the difference between the data values
and the average of the data values, minimized on a per
range basis.
miStandardDeviation The middle range breaks at the mean of the data values, and
the ranges above and below the middle range are one
standard deviation above or below the mean.

See Also
RangeCategories collection

MapInfo MapX Developer Guide v4.5 541

ThemeProperties Object

ThemeProperties.DotSize property (ThemeProperties object)

Purpose
This property applies to DotDensity themes. This controls the dot size used by DotDensity
thematic maps. This is a DotSizeConstants value and defaults to miDotSizeSmall.

ThemeProperties.Graduated property (ThemeProperties object)

Purpose
This property applies to Pie themes. This controls whether the size of the Pie charts are
graduated based on the total value of the Pie. This is a Boolean value, and defaults to TRUE.

Note: This property has been replaced by ThemeProperties.PieGraduated. However, it

still exists for backward compatibility

See Also
ThemeProperties.PieGraduated

ThemeProperties.Independent property (ThemeProperties object)

Purpose
This property applies to Bar themes. This controls whether the data values for the bars
should be treated independently (not comparable values such as Population and
AvgIncome). This is a Boolean value, and the default is FALSE. The developer should set
this to true for multi-value Bar themes where the data for each bar of a single feature is
unrelated to a bar for a different field of the theme or the maximum values for a field of data
differ greatly. An example of this would be a population bar theme where one bar may
represent the population of a state and another may be a ranking in exports. The population
data would be in the millions and the ranking would only be between 1 and 50. If the
Independent property is set to True, then the highest populated state's population bar
would be equal in height to the highest ranking state in exports export bar. Were the
Independent property left false, the export ranking bar would be difficult to obtain any
meaning from because the state ranked 1st would have an export bar the size of a state's
population bar if that state had 1 person in it.

Note: BarIndependentScale is now the prefered name for this property.

542 MapInfo MapX Developer Guide v4.5

 ThemeProperties.IndividualValueCategories property (ThemeProperties object)

See Also
ThemeProperties.BarIndependentScale property

ThemeProperties.IndividualValueCategories property (ThemePro-

perties object)
Purpose
This returns an IndividualValueCategories collection; used with Individual Value thematic
maps.

See Also
IndividualValueCategories collection

ThemeProperties.MultivarCategories property (ThemeProperties

object)
Purpose
This returns a MultivarCategories collection; used with thematic maps that use multiple
variables (bar or pie charts).

See Also
MultivarCategories collection

ThemeProperties.NumRanges property (ThemeProperties object)

Purpose
This property applies to Ranged themes. It controls the number of ranges for a ranged
thematic map. This is an Integer value, and defaults to 5.

MapInfo MapX Developer Guide v4.5 543

ThemeProperties Object

ThemeProperties.RangeCategories property (ThemeProperties

object)
Purpose
This returns a RangeCategories collection; used with ranged thematic maps.

See Also
RangeCategories collection

ThemeProperties.Size property (ThemeProperties object)

Purpose
This property applies to Pie and Bar themes. This works in conjunction with the DataValue
property to control how big the thematic graphics are at particular values. It specifies the
height of the thematic graphic in Paper units (PaperUnit).This is a double value, and
defaults to .25 inches.

See Also
Map.PaperUnit property

ThemeProperties.DataValue property

ThemeProperties.SpreadBy property (ThemeProperties object)

Purpose
Controls how autospreading is done for ranged thematic maps. MapX can compute a set of
colors between two colors or compute sizes between two sizes.

Remarks
This takes a SpreadByConstants value. To control which colors or sizes are used for the start
or end set the ThemeProperties.RangeCategories(x).Style values, where x = 1 for the first
range (start value) and x is ThemeProperties.NumRanges for the last range (end value).

Note: If you are using ranges for a theme and specifying range colors individually (ie
per range), ThemeProperties.SpreadBy must be set to miSpreadByNone.

544 MapInfo MapX Developer Guide v4.5

ThemeProperties.SymbolStyle property (ThemeProperties object)
Purpose
This property applies to GraduatedSymbol themes. This controls the symbol that is used, as
well as the size of the symbol drawn at the value specified by the DataValue property. This is
a Style object, and is a read-only property (although the properties of the SymbolStyle are
Read/Write).

Note: ThemeProperties.PositiveSymbolStyle is now the preferred name for this property.

See Also
ThemeProperties.PositiveSymbolStyle property

Style object

ThemeProperties.DataValue property

ThemeProperties.ValuePerDot property (ThemeProperties object)

Purpose
This property applies to DotDensity themes. This specifies that value a dot represents. For
example, if ValuePerDot was 2000, and a region had a population of 48,000, then 24 dots
would be drawn in the region. This is a double value, and defaults to a reasonable value.

ThemeProperties.Width property (ThemeProperties object)

Purpose
This property applies to Bar themes. It specifies the width of each bar of a Bar theme in Paper
units (Map.PaperUnit). This is a double value, and defaults to .25 inches.

See Also
Map.PaperUnit property
ThemeProperties Object

ThemeProperties.PieClockwise property (ThemeProperties

object)
Purpose
This is a Boolean property which applies to pie chart themes. It controls the direction that
the pie wedges are drawn; if true, they are drawn increasing clockwise. The default is true.

See Also
ThemeProperties.PieStartAngle property

ThemeProperties.PieStartAngle property (ThemeProperties

object)
Purpose
This property applies to pie chart themes. It is an Integer property specifying the angle at
which the first pie wedge is drawn. It is measured in degrees, increasing counterclockwise,
with 0 degrees pointing to the right. The default is 180 degrees.

See Also
ThemeProperties.PieClockwise property

ThemeProperties.PieHalfPies property (ThemeProperties object)

Purpose
This is a Boolean property which applies to pie chart themes. If True, half pies are drawn
instead of full pies. The default is False.

ThemeProperties.PieGraduated property (ThemeProperties

object)
Purpose
This is a Boolean property which applies to pie chart themes. It controls whether the size of
the pies vary. If True, then the total size of a pie is graduated by its total value. If False, then
all pies are the same size. The default is True.

Note: This property replaces ThemeProperties.Graduated. PieGraduated is the

preferred property.

546 MapInfo MapX Developer Guide v4.5

See Also
ThemeProperties.GraduateSizeBy property

ThemeProperties.BarStacked property (ThemeProperties object)

Purpose
This is a Boolean property which applies to Bar chart themes. If True, the bars of the chart will
be stacked on top of each other; if false, the bars will be side by side. The default is False.

See Also
ThemeProperties.BarGraduatedStack property

ThemeProperties.BarGraduatedStack property (ThemeProperties

object)
Purpose
This Boolean property applies to Bar charts whose ThemeProperties.BarStacked property is
True. This controls whether the total size of a bar chart varies. If true, the size of a bar chart
will be graduated by the total value of the chart; if false, all of the charts will be the same total
size. The default is True.

See Also
ThemeProperties.BarStacked property

ThemeProperties.GraduateSizeBy property

ThemeProperties.BarIndependentScale property (ThemeProperties

object)
Purpose
This property applies to Bar themes. It controls whether the data values for the bars should be
treated independently (not comparable values such as Population andAvgIncome). This is a
Boolean value, and the default is False. The developer should set this to true for multi-value
Bar themes where the data for each bar of a single feature is unrelated to a bar for a different
field of the theme or the maximum values for a field of data differ greatly. An example of this
would be a population bar theme where one bar may represent the population of a state and
another may be a ranking in exports. The population data would be in the millions and the
ranking would only be between 1 and 50. If the Independent property is set to True, then the
highest populated state's population bar would be equal in height to the highest ranking state
in exports export bar. Were the Independent property left false, the export ranking bar would
ThemeProperties Object

be difficult to obtain any meaning from because the state ranked 1st would have an export
bar the size of a state's population bar if that state had 1 person in it. This property replaces
ThemeProperties.Independent.

ThemeProperties.BarWidth property (ThemeProperties object)

Purpose
This is a double property which applies to Bar Themes. It specifies the width of each bar of a
Bar theme in Paper units (Map.PaperUnit). This is a double value, and defaults to .25 inches.
This property replaces the ThemeProperties.Width property.

See Also
Map.PaperUnit property

ThemeProperties.BarFramed property (ThemeProperties object)

Purpose
This Boolean property is set to false and specifies whether the bar objects are drawn with
frames.

ThemeProperties.BarFrameStyle (ThemeProperties object)

Purpose
This is a Style object which determines the style of the frame of a bar chart.

See Also
Style object

ThemeProperties.BorderStyle property

548 MapInfo MapX Developer Guide v4.5

 ThemeProperties.ShowNegativeValues property(ThemeProperties object)

ThemeProperties.BorderStyle property (ThemeProperties object)

Purpose
This is a Style object which affects Bar chart and Pie chart themes. It controls the line style of
the border around a pie or bar chart.

See Also
Style object

ThemeProperties.BarFrameStyle property

ThemeProperties.ShowNegativeValues property(ThemeProperties
object)
Purpose
This is a Boolean property which applies to Graduated Symbol themes. If True, then
negative data values will be treated like their absolute values; a symbol representing -4000
will have the same size as a symbol representing 4000. If False, then negative values will not
be shown. The default is False.

See Also
ThemeProperties.PositiveSymbolStyle property

ThemeProperties.NegativeSymbolStyle property

ThemeProperties.PositiveSymbolStyle property (ThemeProper-

ties object)
Purpose
This property applies to Graduated Symbol themes. This controls the symbol that is used for
all positive data values, as well as the size of the symbol drawn at the value specified by the
DataValue property. This is a Style object, and is a read/write property (although the
properties of the Style object are Read/Write).

Note: This property replaces ThemeProperties.SymbolStyle.

MapInfo MapX Developer Guide v4.5 549

ThemeProperties Object

See Also
Style object

ThemeProperties.ShowNegativeValues property

ThemeProperties.NegativeSymbolStyle property

ThemeProperties.DataValue property

ThemeProperties.NegativeSymbolStyle property (ThemeProper-

ties object)
Purpose
This applies to Graduated Symbol themes whose ThemeProperties.ShowNegativeValues
property is True. It is a Style object which controls the symbol that is used for all negative
data values of the theme. It is a read/write property (although the properties of the Style
object are Read/Write).

See Also
Style object

ThemeProperties.ShowNegativeValues property

ThemeProperties.PositiveSymbolStyle property
ThemeProperties.DataValue property

ThemeProperties.GraduateSizeBy property (ThemeProperties

object)
Purpose
This property applies to Graduated Symbol themes, as well as Pie chart and Bar chart
themes which have been set to Graduated. It must be set to a Short value matching one of
the GraduationConstants. It controls the relationship between a data value and the size of
the corresponding symbol or chart on the map. The default is miGraduateBySquareRoot.

See Also
ThemeProperties.PieGraduated property

ThemeProperties.BarGraduatedStack property

550 MapInfo MapX Developer Guide v4.5

 ThemeProperties.RoundRanges property (ThemeProperties object)

ThemeProperties.DotColor property (ThemeProperties object)

Purpose
This property applies to Dot Density themes. It controls the color of the dots in the theme. It
is an OLE_COLOR value.

ThemeProperties.RoundRanges property (ThemeProperties

object)
Purpose
This is a Boolean property which applies to Ranged themes. It controls whether the
boundaries of the ranges are rounded off. The default is True. The amount that the values
are rounded is controlled by the ThemeProperties.RoundBy property.

See Also
ThemeProperties.RoundBy property

ThemeProperties.RoundBy property (ThemeProperties object)

Purpose
This is a double value which applies to Ranged themes. It specifies the interval to round the
ranges to. It only applies when ThemeProperties.RoundRanges is True.

Remarks
If RoundBy was 100, and the computed ranges were 420-560, and 560-930, then they would
be rounded to 400-600, and 600-900, respectively. The default RoundBy value is calculated
by finding the power of 10 which is closest to the difference between the maximum and
minimum data value. For example, if the difference between the maximum and minimum
data value was 11,554, then the default value for the RoundBy property would be 100.

See Also
ThemeProperties.RoundRanges property

MapInfo MapX Developer Guide v4.5 551

ThemeProperties Object

ThemeProperties.InflectRanges property (ThemeProperties

object)
Purpose
This is a Boolean property which applies to Ranged themes. In a ranged theme, an inflection
point can be used to separate the data and the ranges into two sections. When InflectRanges
is true, the colors in the ranged theme will spread from the top range color to the
InflectionColor, then from the InflectionColor to the bottom range color. The default is False.

Remarks
For example, if the InflectionColor is miColorWhite, and the top and bottom range colors
are blue and red respectively, then the color would go from blue to white, then from white to
red. If InflectRanges was False, then the color in the middle ranges would instead be some
mixture of blue and red.

See Also
ThemeProperties.InflectionRange property
ThemeProperties.InflectionColor property

ThemeProperties.RangeCategories property

ThemeProperties.InflectionRange property (ThemeProperties

object)
Purpose
This is a Short value which applies to Ranged themes. It controls which range takes on the
color specified in InflectionColor. The ranges above and below the InflectionRange will have
a mixture of InflectionColor and the top and bottom range colors, respectively.

Remarks
This property only applies if ThemeProperties.InflectRanges is True. The default is 2 (the
second range).

See Also
ThemeProperties.InflectRanges property

ThemeProperties.InflectionColor property

552 MapInfo MapX Developer Guide v4.5

 ThemeProperties.ColorMethod property (ThemeProperties object)

ThemeProperties.InflectionColor property (ThemeProperties

object)
Purpose
This is an OLE_COLOR value which applies to Ranged themes whose
ThemeProperties.InflectRanges is True. It indicates the color of the inflected range. The
range that is inflected on is specified in the ThemeProperties.InflectionRange property. The
default is miColorWhite.

See Also
ThemeProperties.InflectRanges property

ThemeProperties.ColorMethod property (ThemeProperties object)

Purpose
This is a Short property which applies to Ranged themes. It should be one of the
ColorSpreadingMethodConstants. It specifies the method used to interpolate between the
top and bottom range colors to get the colors of the intermediate ranges. It is only valid
when ThemeProperties.SpreadBy is set to miSpreadByColor.

See Also
ThemeProperties.SpreadBy property

ThemeProperties.ApplyAttribute property (ThemeProperties

object)
Purpose
This is a Short property, which should be set to one of the ApplyAttributeConstants. It
applies to Ranged or Individual Value themes. It controls which of the theme category's
style attributes are actually applied to the theme. It can be used to selectively modify either
the color or the size of the categories of the theme, without affecting the other's appearance.
The default is miApplyAttributeAll.

MapInfo MapX Developer Guide v4.5 553

ThemeProperties Object

See Also
ThemeProperties.RangeCategories property

RangeCategories collection

ThemeProperties.IndividualValueCategories property

IndividualValueCategories collection

554 MapInfo MapX Developer Guide v4.5

 Title.Border property (Title object)

Title Object

Each map contains a title (Map.Title property) in which the title, its style and location are
stored.

Object Properties
• Title.Border property
• Title.Caption property
• Title.Editable property
• Title.Position property
• Title.TextStyle property
• Title.Visible property
• Title.X property
• Title.Y property

Title.Border property (Title object)

Purpose
Controls whether or not to draw the title's border. This is a Boolean value, and defaults to
True.

Title.Caption property (Title object)

Purpose
Contains the text of the Title. This is a String value. This is a default property of the Title
object.

Title.Editable property (Title object)

Purpose
Controls whether the title is editable by the end user. By this we mean whether the user can
click on it and move it, resize it, or change its text. This is a Boolean value, and defaults to
True.

MapInfo MapX Developer Guide v4.5 555

Title Object

Title.Position property (Title object)

Purpose
Contains a value indicating how the text should be drawn with respect to the X,Y
coordinates. This takes a PositionConstants value, and the default is miPositionCC.

Title.TextStyle property (Title object)

Purpose
A Style object containing the style of the title.

Title.Visible property (Title object)

Purpose
Controls whether the title is visible or not. This is a Boolean value, and defaults to True.

Title.X property (Title object)

Purpose
Contains the X coordinate of the title. This is a Float value, and represents Screen
coordinates. The position of the title is controlled by the X,Y coordinates in conjunction with
the Position property, which controls how the title sits with respect to the X,Y coordinates.

Title.Y property (Title object)

Purpose
Contains the Y coordinate of the title. This is a Float value, and represents Screen
coordinates. The position of the title is controlled by the X,Y coordinates in conjunction with
the Position property, which controls how the title sits with respect to the X,Y coordinates.

556 MapInfo MapX Developer Guide v4.5

 Title.Y property (Title object)

Variable object and Variables collection

MapX supports variable substitution in expressions. The Variable object and Variables
collection are key components in MapX’s ability to mix attribute and geographic criteria in
expressions. That is, an expression can contain a reference to any variable name in a MapX
application by passing a Variables Collection (i.e. a set of Variable objects) to the
Layer.Search method as an optional parameter.

Object Properties
• Variable.Name property
• Variable.Value property

Collection Properties
• Variables.Count property

Collection Methods
• Variable.Add method
• Variables.Clone method
• Variables.Item method
• Variables.Remove method
• Variables.RemoveAll method
Note: The default property is Variables.Item, and the Variable object is NOT createable.
Also, there is no limitation in terms of length and character set.

Remarks
A variable is a name "tied to" a variant. When an expression reads an unresolved identifier,
it will try to resolve it in theVariables collection. If a programmer has added the Variable
object in question to the Variables collection, the expression will execute. The variant can be
of any type (string, number, etc.).

Note: When using a feature object as a variable, you will get the best performance if the
Feature object and the layer being searched have the same coordinate system. This
will prevent "on the fly" coordinate transformations from occurring.
Dataset names and Dataset field names have precedence over variable names.

The Variables collection IS createable.

Note that in the case of Feature objects, a copy of the feature is made during the call to
Variables.Add. If you subsequently modify the feature, the variable will not reflect the
changes. You will need to update the value of the Variable via the Variables.Add method or
via the Variable.Value property.

MapInfo MapX Developer Guide v4.5 557

Variable object and Variables collection

Variable.Name property (Variable object)

Purpose
This read-only property specifies the name of the variable being placed in the variables
collection. Variable names are not case sensitive within the collection.

Variable.Value property (Variable object)

Purpose
This read-only property specifies the value of the variable being placed in the Variables
collection.

Variables.Count property (Variables collection)

Purpose
This read-only property contains an integer value for the number of variables in the
Variables collection and is the default property of the Variables collection.

Variables.Add metho (Variables collection)

Purpose
This method adds a Variable object to a Variables collection.

Syntax

558 MapInfo MapX Developer Guide v4.5

 Variables.Clone method (Variables collection)

[ Variables collection= ]OBJECT.Add(Name, Value)

Part Description
OBJECT This represents a Variable object.
Name This is a string value for the name of the variable to add.
Value Variant: This is the value of the variable that is being added. (see
"Remarks")

Remarks
The Variables.Add method adds a new variable to the collection. If a variable with the same
name is already in the collection, it will update the existing variable with the new variable
value.

The variant can be of any numeric, string, or date type. In addition, it can be a IDispatch
where the object is a MapX Feature object.

See Also
Feature object

IDispatch Table in MapX Reference section

Variables.Clone method (Variables collection)

Purpose
This method clones a specified object in a Variables collection and returns a new Variables
collection with a copy of the variables from the specified collection.

Syntax
[ Variable object= ]OBJECT.Clone

Part Description
OBJECT This represents a Variables collection.

MapInfo MapX Developer Guide v4.5 559

Variable object and Variables collection

Variables.Item metho (Variables collection)

Purpose
This method returns a specific Variable object from the Variables collection. This is the
default method for the variables collection.

Syntax
[ Variable object= ]OBJECT.Item(Index)

Part Description
OBJECT This represents a Variables collection.
Index Variant: This specifies which item to return from the Variables
collection. It can be a 1-based index number or a variable name.

Variables.Remove method (Variables collection)

Purpose
This method removes a specified Variable object from a Variables collection.

Syntax
OBJECT.Remove(Index)

Part Description
OBJECT This represents a Variables collection.
Index Variant: This specifies which item to remove from the Variables
collection. It can be a 1-based index number or a variable name.

560 MapInfo MapX Developer Guide v4.5

 Variables.Remove method (Variables collection)

Variables.RemoveAll method (Variables collection)

Purpose
This method removes all Variable objects from a Variables collection. The Variables
collection will remain intact, though empty, until other Variable objects are added to it.

Syntax
[ Variable object= ]OBJECT.Clone

Part Description
OBJECT This represents a Variables collection.

MapInfo MapX Developer Guide v4.5 561

Variable object and Variables collection

562 MapInfo MapX Developer Guide v4.5

 Part III:
MapX Reference
Information
564 MapInfo MapX Developer Guide v4.5
MapX Events
t

Stock events
MapX supports the following stock events:

Event OLE Dispatch ID Description

Click -600 The user presses and releases a mouse button.

DblClick -601 The user double-clicks.
KeyDown -602 The user presses down on a key. Useful for building
modifiers for mouse activities.
KeyPress -603 The user presses a key.
KeyUp -604 The user releases a key.
MouseDown -605 The user presses a mouse button.
MouseMove -606 The user moves the mouse. Can be used to displays
cursor coordinates in the Status Bar.
MouseUp -607 The user releases a mouse button.
Error -608 An error occurs during an asynchronous activity
such as a redraw, or when a user is using a map tool.

Custom Events
MapX supports the following custom events:

Event Dispatch ID Called…

AddFeatureToolUsed Event 16 when an Add Feature tool is used.

AnnotationAdded event 7 when annotation is added.
AnnotationChanged event 8 when annotation is added, modified,
or deleted.
DataMismatch event 5 during data binding, if a row doesn't
match.
DrawUserLayer Event 10 when the map window needs
updating and the application has
created a UserDraw layer.
MapDraw event 15 once before a draw, and once after a
draw is completed.

MapInfo MapX Developer Guide v4.5 565

tMapX Events

Event Dispatch ID Called…

MapInitialized event 13 after map initialization is complete.

MapViewChanged event 6 when the map's minimum bounding
rectangle has changed (e.g. when you
zoom or pan).
MouseWheel Event 12 when a user uses the mouse wheel.
PolyToolUsed Event 11 when user uses a polytool (e.g. to
draw a polyline).
RequestData event 4 to request data from a cell container
when dealing with unbound data.
ResolveDataBind event 2 during automatic data binding, if
data is ambiguous.
ResolveDataBindEx event 14 when it has the same function as the
ResolveDataBind Event, but it passes
a collection of ResolveObjects
instead of a string array.
SelectionChanged event 1 when the selection changes.
ThemeModifyRequested event 9 when user double-clicks legend.
ToolUsed event 3 when user uses a tool on the map.
Depending on your development environment, you may be able to use other events as well.
For example, Visual Basic provides support for these events: DragDrop, DragOver,
GotFocus, LostFocus.

566 MapInfo MapX Developer Guide v4.5

AddFeatureToolUsed Event
This event is called whenever the user uses one of the standard object creation tools
(miAddPointTool, miAddLineTool, miAddPolylineTool, or miAddRegionTool). The
behavior of this event is similar to the PolyToolUsed Event.

Dispatch ID = 16

Syntax
AddFeatureToolUsed(ToolNum, Flags, Feature, Shift, Ctrl, EnableDefault)

Part Description

ToolNum Indicates the tool number of the Add Feature tool.

Flags A ToolFlagConstants value; this indicates whether the user is
starting, in the process of, or finishing the tool use.
Feature A Feature object representing the feature that the user has
created thus far.
Shift, Ctrl Boolean values that indicate whether modifier keys (SHIFT, CTRL)
were pressed at the time the event was fired; True indicates that
a key was pressed.
EnableDefault Boolean. This parameter controls whether MapX allows the
tool's standard behavior to take effect. Default value is True. To
prevent the tool's standard behavior (e.g. to cancel the user's
action), set this parameter to False. This parameter only takes
effect when the user concludes the tool use (miToolEnd).

Remarks
This event is fired multiple times during every use of the object creation tools:

Once at the beginning of the tool use, when the user clicks to place the first node of the
feature. During this call, the Flags variable is set to miToolBegin (0).

For the Add Polyline and Add Region tools, it is fired once for every time the user clicks to
add another node, and also for every time the user deletes a node by pressing the
BACKSPACE key. During this call, the Flags variable has a value equal to miToolInProgress
(3).

Fired once at the end of the tool use, when the user performs one of these actions:

• Ends the drawing of the feature by double clicking (polyline and polygon tools) or
releasing the mouse (line and point tools), in which case the Flags variable will be
set to miToolEnd (1); -or-

MapInfo MapX Developer Guide v4.5 567

tMapX Events

• Presses the ESC key to end the add feature tool, in which case the Flags variable will
be set to miToolEndEscaped (2); -or-
• Uses the backspace key to delete all of the nodes, in which case the Flags variable
will be set to miToolEndEscaped (2).

AnnotationAdded event
Purpose
This event that is called whenever an annotation is added, modified, or deleted. It is called
right before the annotation is changed. The programmer also has an opportunity to prevent
the operation.

Dispatch ID = 7

AnnotationChanged event
Purpose
This is an event that is called whenever an annotation is added, modified, or deleted. It is
called right before the annotation is changed, and the programmer has an opportunity to
prevent the operation.

Dispatch ID = 8

Note: The event is only fired for changes brought about by user interaction (like
selecting the annotation, moving the annotation, resizing it, etc.), NOT through
programmatic changes in the annotations. For example, this will not fire the
AnnotationChanged event: annotation.X = 100. Even though it is moving the
annotation.

568 MapInfo MapX Developer Guide v4.5

 DataMismatch event

Syntax
AnnotationChanged (changetype, EnableDefault)

Part Description

changetype Object pointer to the annotation object

EnableDefault Boolean. This parameter controls whether MapX allows the
Annotations’s standard behavior to take effect. Default value is
True. If the programmer sets EnableDefault to FALSE, MapX
will not do anything in response to the Annotation.

See Also
AnnotationChangedType Constants

DataMismatch event
Purpose
This event is called when a row doesn't match an object in the map during data binding.

Once MapX knows a geocolumn for a data set, it can then bind it to a map. However, MapX
may encounter a row that doesn't match an object in the map. In the default case, it is simply
skipped over. If the DataMismatch event handler is defined, we will send an event to it
when a row doesn't match.
Dispatch ID = 5

Syntax
DataMismatch (DatasetName, ByValRow, GeoColValue)

Part Description
DatasetName This string value is the name of the Dataset that dosen’t match.
ByValrow This is the row number (as long) in the general data source that
dosen’t match.
GeoColValue This is a string value of the field in the dataset that dosen’t match.

MapInfo MapX Developer Guide v4.5 569

tMapX Events

DrawUserLayer Event
Purpose
When the application creates a UserDraw layer using the AddUserDrawLayer method of
the Layers collection, an event is fired to the application when the window needs updating:

Dispatch ID = 10

Syntax
DrawUserLayer (Layer, hOutputDC, hAttributeDC, RectFull, RectInvalid)

Part Description

Layer Layer object: the layer to draw.

hOutputDC OLE_HANDLE: device context to draw to.
hAttributeDC OLE_HANDLE: device context to draw to; usually the same as
hOutputDC, except when drawing to a metafile device context.
RectFull Rectangle object: the full window.
RectInvalid Rectangle object: the invalidated area.

The rectangles are objects of type Rectangle. The coordinates in the rectangles are screen
(client) coordinate .

Remarks
You can also add a UserDrawLayer via Layers.Add.

MapDraw event
This event will be called once before a draw, and once after a draw is completed. There is
one parameter which states whether a draw is beginning or ending.

Disp ID = 15

Syntax
MapDraw (Flag)

Part Description

Flag Either miDrawBegin or miDrawEnd.

570 MapInfo MapX Developer Guide v4.5

 MapInitialized event

See Also
MapDrawConstants

MapInitialized event
Purpose
This event is called immediately after map initialization is complete. It serves to notify the
container application of the best time to do any necessary run-time configuration.

Dispatch ID = 13

Syntax
MapInitialized < no parameters >

MapViewChanged event
Purpose
This event is called whenever the distance across the control (map) changes or the
centerpoint is moved.

Dispatch ID = 6

Syntax
MapViewChanged < no parameters >

MouseWheel Event
Purpose
The Intellimouse provides a wheel as a third (middle) button on the Microsoft mouse. In
addition to the regular mouse button messages, the wheel sends a MOUSEWHEEL message
when turned.
The MouseWheel will zoom the map when rolled, scroll the map up and down when the
wheel is rolled with the control key down, and "AutoScroll" when the middle button is held
down and moved away from the mouse click point. The speed of the scrolling is
proportional to the distance of the cursor from the mouse-click point. The MouseWheel
event allows you to override this built-in behavior of the MouseWheel.

MapInfo MapX Developer Guide v4.5 571

tMapX Events

Note that there is no support in Visual Basic under Windows 95 for the MouseWheel, but
third party ActiveX controls have been built that you can use to take advantage of the
MouseWheel. (That is, you put another control on your form that gathers and sends along
the MOUSEWHEEL messages.)

Dispatch ID = 12

Syntax
MouseWheel(long Flags, int zDelta, single X &Y, bool EnableDefault)

Part Description
Flags Indicates whether various virtual keys are down. This
parameter can be any combination of the following values:
MK_CONTROL: Set if the CTRL key is down.
MK_LBUTTON: Set if the left mouse button is down.
MK_MBUTTON: Set if the middle mouse button is down.
MK_RBUTTON: Set if the right mouse button is down.
MK_SHIFT: Set if the SHIFT key is down.
zDelta The value of the high-order word of wParam. Indicates the
distance that the wheel is rotated, expressed in multiples or
divisions of WHEEL_DELTA, which is 120. A positive value
indicates that the wheel was rotated forward, away from the
user; a negative value indicates that the wheel was rotated
backward, toward the user
X Specifies the x-coordinate of the pointer, relative to the upper-
left corner of the screen.
Y Specifies the y-coordinate of the pointer, relative to the upper-
left corner of the screen.
EnableDefault Boolean. This parameter controls whether MapX allows the
mousewheel's standard behavior to take effect. Default value is
True. If the programmer sets EnableDefault to FALSE, MapX
will not do anything in response to the MouseWheel.

572 MapInfo MapX Developer Guide v4.5

 MouseWheel Event

PolyToolUsed Event
This event is called whenever the user draws a polyline or polygon, using either the
standard tool miPolygonSelectTool (1010), or a custom tool of type miToolTypePoly (4).
Dispatch ID = 11

Syntax
PolyToolUsed(ToolNum, Flags, Pts, Shift, Ctrl, EnableDefault)

Part Description

ToolNum Indicates the custom tool number

Flags A PolyToolFlagConstants value; this indicates whether the user
is starting or finishing the tool use.
Pts A collection of points (the same kind as used in
Feature.Parts.Add).
Shift, Ctrl Boolean values that indicate whether modifier keys (SHIFT, CTRL)
were pressed at the time the event was fired; True indicates that
a key was pressed. For the standard tool miPolygonSelectTool,
MapX only uses the state of these keys when the user concludes
the tool use (i.e. when the Flag parameter is miPolyToolEnd).
EnableDefault Boolean. If this event was triggered by the standar
miPolygonSelectTool, this parameter controls whether MapX
allows the tool's standard behavior to take effect. Default value
is True. To prevent the tool's standard behavior (e.g. to cancel the
user's action), set this parameter to False. This parameter only
takes effect when the user concludes the tool use
(miPolyToolEnd).

Remarks
This event is fired multiple times during every use of the PolyTool.

Once at the beginning of the tool use, when the user clicks to place the first node of the
polyline/polygon. During this call, the Flags variable is set to miPolyToolBegin (0).

Once for every time the user clicks to add another node to the polyline, and also for every
time the user deletes a node by pressing the BACKSPACE key. During this call, the Flags
variable has a value equal to miPolyToolInProgress (3).

Once at the end of the tool use, when the user performs one of these actions:

• Double-clicks to end the drawing of the polygon, in which case the Flags variable
will be set to miPolyToolEnd (1);

MapInfo MapX Developer Guide v4.5 573

tMapX Events

-or-
• Presses the ESC key to end the drawing of the polygon, in which case the Flags
variable will be set to miPolyToolEndEscaped (2);
-or-
• Uses the backspace key to delete all of the nodes, in which case the Flags variable
will be set to miPolyToolEndEscaped (2)

RequestData event
Purpose
This is event is called to request data from a cell container when dealing with unbound data.

Dispatch ID = 4

Syntax
RequestData (row, column, value, done)
Set the done flag when there is no more data to pass to the container.

ResolveDataBind event
Purpose
Automatic Data Binding can encounter ambiguous situations. Theses situations include:
multiple geocolumns are detected in the user data, multiple layers are detected that match
the geocol,multiple geosets are available for the matched map layer. In these cases, MapX
will take the first one, unless the following ResolveDataBind event handler is defined. If
defined, MapX will call it, and let the handler choose which one to use.

Dispatch ID = 2

Syntax
ResolveDataBind (flag, nummatches, matches, choice, cancel )

Part Description

flag Indicates if the event is being called because of multiple geocols

(0), multiple layers (1), or multiple geosets (2).
nummatches Indicates how many entries are in the matches array. The array
of strings matches contains list of matches.
matches Variant: Represents an array of strings.

574 MapInfo MapX Developer Guide v4.5

 ResolveDataBindEx event

Part Description

choice The return variable. 1 based. 0 means auto–select and has MapX
choose the best one).
cancel Allows the user to cancel the data bind and causes it to fail.

Remarks
ResolveDataBind could get fired 3 times.

First, it chooses columns in the source table, then for the chosen column it chooses a table if
there are > 1, and lastly, for the table it chooses geosets if there are > 1.
The geodictinonary lists geosets for each table.

ResolveDataBindEx event
Purpose
This event has the same function as the ResolveDataBind event, but it passes a collection of
ResolveObjects instead of a string array. So, for situations like multiple geocolumns being
detected in the user data, multiple layers detected that match the geocol, or multiple geosets
available for the matched map layer, MapX will take the first one, unless either the
ResolveDataBind or the ResolveDataBindEx event handler is defined. If defined, MapX will
call one, and let the handler choose which one to use.

Dispatch ID = 14

Syntax
ResolveDataBindEx (flag, nummatches, matches, choice, cancel )

Part Description
flag Indicates the event is being called because of multiple geocols.
This flag is always set to one.
nummatches Indicates how many entries are in the matches collection.
matches Variant: Represents a collection of ResolveObject objects.
choice The return variable. 1 based. 0 means auto–select and has MapX
choose the best one.
cancel Allows the user to cancel the data bind and causes it to fail.

MapInfo MapX Developer Guide v4.5 575

tMapX Events

Remarks
ResolveDataBindEx is fired only for multiplegeo columns and only if choice is set to 1
during ResolveDataBind Event.

SelectionChanged event
Purpose
This event is called whenever the selection changes and enables the container to react to a
selection made on the map. The selection can change as a result of a user using a selection
tool, or by using one of the Selection methods from the Layer object.

Dispatch ID = 1

Syntax
SelectionChanged

ThemeModifyRequested event
Purpose
This event is called when a user double clicks on a thematic legend. The parameter is the
Theme object that `owns' the legend. The purpose for this event is to be able to write code
and let the user modify theme or legend properties when the user double clicks on the
legend.

Dispatch ID = 9

Syntax
ThemeModifyRequested
Theme as object

ToolUsed event
The ToolUsed event is called when the user uses a custom tool on the map. This procedure
allows you to determine how the tool was used; for example, it tells you the map
coordinates where the user clicked. Within the ToolUsed procedure, you write code to carry
out the intended functionality of the tool.

576 MapInfo MapX Developer Guide v4.5

 ToolUsed event

This event is also called when a standard tool is used, in which case the event is called after
the user interaction, but before the operation is executed for standard tools.
Dispatch ID = 3

Syntax
ToolUsed(ToolNum, x1, y1, x2, y2, distance, shift, control, *EnableDefault)

Part Description

ToolNum Integer: Indicates the tool number. Note that if you create
multiple custom tools, this event is called when any of those
tools are used; therefore, you need to check ToolNum to
determine which tool is in use.
x1, y1 Double: Map coordinates where user clicked.
x2, y2 Double: Map coordinates where the user ended the tool use;
does not apply to Point tools, which do not allow dragging.
distance Double: Distance, in Map Units, between beginning location and
ending location.
shift Boolean: Indicates whether user held down SHIFT KEY.
control Boolean: Indicates whether user held down CTRL KEY.
*EnableDefault Boolean: In cases where a standard tool is being used, this
parameter controls whether MapX allows the tool's standard
behavior to take effect. Default value is True. To prevent the
tool's standard behavior (e.g. to cancel the user's action), set this
parameter to False.

MapInfo MapX Developer Guide v4.5 577

tMapX Events

578 MapInfo MapX Developer Guide v4.5

 ToolUsed event

MapX Error Codes

This is a table of the MapX errors encountered when writing MapX applications. For
information on handling errors in Visual Basic, Delphi, and Powerbuilder, see the respective
programmer's reference book and/or help system. For C++ similar information on
programmers, see Working With Visual C++..

Error Description

1000 Out of memory.

1001 Property or method not implemented.
1002 Property not supported by themes of this type.
1003 Object is no longer valid.
1004 No object was found using the index you specified.
1005 Invalid DataSet type specified.
1006 Non-Unique Name specified. (Name already in use by another object).
1007 Invalid GeoField specified. Name not found, or index out of range.
1008 Invalid Secondary GeoField specified. Name not found, or index out of range.
1009 Unable to match a GeoField or BindLayer automatically.
1010 Invalid Fields parameter.
101 Unexpected error in MapX.
1012 Invalid Theme type specified.
1013 Unexpected error.
1014 No key column was found in the specified dataset. Cannot create theme.
1015 The DataBinding process was cancelled by setting the cancel property in the
ResolveDataBind event.
1016 Invalid aggregation function specified.
1017 No source field specified.
1018 Invalid field type specified.
1019 Unable to refresh dataset.
1020 Cannot find the BindLayer for this dataset. Unable to create theme.
1021 Unable to create theme.

MapInfo MapX Developer Guide v4.5 579

MapX Error Codes

Error Description

1022 Invalid ranges.

1023 Invalid number of ranges.
1024 Theme categories cannot be removed.
1025 Invalid distribution method.
1026 Invalid fill pattern.
1027 Invalid pen style.
1028 Invalid Fields Parameter - Name or index of a field not found.
1029 Could not create a default theme.
1030 This property is available at design time only.
1031 Layer specified is not matchable.
1032 Matched or specified Layer is not in any GeoSets.
1033 Invalid Name parameter specified.
1034 The color you specified is invalid.
1035 Invalid Spread by value.
1036 Invalid pen width.
1037 The Coordinate specified was not within the bounds of the map's Numeric
CoordSys.
1038 Invalid Zoom specified. Zoom must be > 0.
1039 Invalid Tool specified. The tool number is invalid or doesn't exist, or the tool
type or cursor is invalid.
1040 Invalid paper unit specified.
1041 Invalid mouse pointer specified.
1042 Invalid export format specified.
1043 Unable to create specified file.
1044 An ODBC error has occurred: <error>.
1045 Invalid ODBCQueryInfo object specified. Object not of correct type or
SqlQuery not specified.
1046 Property not supported for annotations of this type.
1047 Invalid character code. Value must be between 0 and 255.
1048 Cannot create a theme of this type based on an attribute data column that has
been aggregated by individual value.

580 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Error Description

1049 Invalid Row Parameter: Row out of range, or fetch past end of table.
1050 Invalid Column Parameter.
1051 Unable to find or load MIODBC.DLL
1052 Error initializing MIODBC.DLL Check DLL version.
1053 MIODBC.DLL called with an invalid handle.
1054 Dataset has no fields. No fields were successfully added to the dataset from the
source data.
1055 Unable to obtain a temporary directory.
1056 Unable to create a filename for the new layer.
1057 Key column not specified, cannot create new layer.
1058 The specified reference layer is not installed in the geodictionary.
1059 Unable to create new layer. Layer filename may already exist.
1060 Invalid bind layer type specified.
1061 Invalid bind layer specified.
1062 Unable to complete this type of bind with the reference column(s) specified.
1063 Unknown error creating map.
1064 Invalid Search Time specified. Time must be between 1 and 3600 seconds.
1065 Display unit specified was not valid .
1066 Inalid Conversion Constant specified.
1067 Missing or Invalid Source, or Source doesn't match Type specified.
1068 The specified reference layer is not a point reference layer.
1069 Invalid dot size.
1070 Invalid position.
1071 The maximum size for a point theme object is 48.
1072 Unable to create geotable.
1073 Unable to create map layer.
1074 Unable to set or retrieve layer information.
1075 Unable to set or retrieve label information.
1076 Unable to set or retrieve layer style information.
1077 Unable to set or retrieve label style information.

MapInfo MapX Developer Guide v4.5 581

MapX Error Codes

Error Description

1078 Feature object is no longer valid.

1079 Unable to find or load Helper Dialog DLL.
1080 Error initializing Helper Dialog DLL. Check DLL version.
1081 For the geofield specified or auto detected a secondary geofield is required,
and one was not specified or auto detected.
1082 Fields Add or Remove not allowed after dataset has been created.
1083 Property or Method not supported by layers of this type.
1084 A Lotus Notes error has occurred: <error>.
1085 Invalid NotesViewInfo object specified. Object not of correct type or Database
or View not specified.
1086 A numeric overflow or underflow has occurred during a coordinate
conversion. Under Windows95/98, all coordinates are limited to the range of -
32767 to +32767. The actual screen or map coordinates may be in range, but the
conversion overflowed. See IsPointVisible or ClipLine.
1087 Attempt to set the Animation Layer to an object which is not a valid layer
object.
1088 Invalid Filespec parameter.
1089 Invalid DataSet specified.
1090 Feature Type Invalid or not applicable.
1091 Operation not allowed on a standalone feature object.
1092 Error updating feature object.
1093 Error adding feature object.
1094 Error deleting feature object.
1095 Feature property or method not valid for feature type.
1096 Error reading Feature from layer.
1097 A line must have at least 2 points. A region must have at least 3 points.
1098 Invalid rectangle specified.
1099 Cannot find a specified Field in the DataSet.
1100 Invalid Features object.
1101 Invalid Search type specified.
1102 Invalid Search precision specified.

582 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Error Description

1103 Invalid Points object.

1104 Invalid Point object.
1105 Invalid Style object.
1106 Attempt to use a new Symbol or Text feature object without first setting the
Point property.
1107 Invalid Area unit specified.
1108 Every Feature in a Features collection object must be from the same layer.
1109 Key field not found in layer.
1110 The Layer that the Feature or Features object is from is no longer valid.
1111 Variant could not be converted to the appropriate type.
1112 The reference layer specified has no matchable columns, and therefore cannot
be used as a reference layer.
1113 Creating bitmap image failed on map export.
1114 Invalid Circle Type specified.
1115 Resolution must be >= 3.
1116 Invalid Datum object.
1117 Invalid CoordSys object.
1118 Invalid units specified.
1119 Invalid origin longitude specified.
1120 Invalid origin latitude specified.
1121 Invalid standard parallel #1 specified.
1122 Invalid standard parallel #2 specified.
1123 Invalid azimuth specified.
1124 Invalid scale factor specified.
1125 Invalid false easting specified.
1126 Invalid false northing specified.
1127 Invalid range specified.
1128 Invalid bounds specified.
1129 Invalid AffineInfo object.
1130 Datum has not been specified.

MapInfo MapX Developer Guide v4.5 583

MapX Error Codes

Error Description

1131 Units have not been specified.

1132 Origin longitude has not been specified.
1133 Origin latitude has not been specified.
1134 Standard parallel #1 has not been specified.
1135 Standard parallel #2 has not been specified.
1136 Azimuth has not been specified.
1137 Scale factor has not been specified.
1138 False easting has not been specified.
1139 False northing has not been specified.
1140 Range has not been specified.
1141 Bounds have not been specified.
1142 Invalid CoordSys type specified.
1143 Invalid AffineTransform object.
1144 Degenerate AffineTransform specified.
1145 Custom dataset error.
1146 The map contains no layers. The Geoset was not saved.
1147 The map contains temporary or userdraw layers. Those layers were not
included in the saved Geoset.
1148 Dataset type does not support dynamic column binding.
1149 Style object does not support bitmap symbols.
1150 Invalid symbol type specified.
1151 Attempt to restore a dataset by name for which there was no saved dataset.
1152 Custom dataset error. Method failed:
IMMapXColumnInfoContainer::GetColumnInfoEnumerator.
1153 Custom dataset error. Method failed: IMEnumMapXColumnInfo::Reset.
1154 Custom dataset error. Required interface not supported:
IMMapXColumnInfoContainer.
1155 Custom dataset error. Method failed: IMMapXColumnInfo::GetColumnName.
1156 Custom dataset error. Method failed:
IMMapXColumnInfo::GetColumnNumber.
1157 Custom dataset error. Method failed: IMMapXColumnInfo::GetDataType.

584 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Error Description

1158 Custom dataset error. A column contains an unsupported type.

1159 Custom dataset error. Method failed: IMMapXDataset::GetSample.
1160 Custom dataset error. Method failed: IMMapXStaticDataset::BeginFetch.
1161 Custom dataset error. Method failed: IMMapXStaticDataset::FetchData.
1162 Custom dataset error. Method failed: IMMapXStaticDataset::EndFetch.
1163 Custom dataset error. Method failed: IMMapXDynamicDataset::FetchData.
1164 Custom dataset error. Method failed: IMMapXDataset:Init.
1165 Custom dataset error. Could not find a CLSID for the type of custom dataset
specified. Check that the custom dataset is properly registered.
1166 Custom dataset error. Could not create the custom dataset object. Check that
the custom dataset is properly registered.
1167 Operation not allowed due to license restrictions.
1168 Unable to open one of the Drilldown component tables.
1169 Unable to reset Drilldown layer to specified level.
1170 The Feature is too complex. There are too many parts or points in the Featur
object.
1171 A Line or Region Feature must have at least 1 Part.
1172 The stand-alone Feature object is not attached to the map. Use Feature.Attach()
before other Feature methods or properties.
1173 Unable to attach Feature to the map. Make sure Map object is valid.
1174 Error creating buffer.
1175 Operation not allowed on an empty Features collection.
1176 Invalid parameter combination.
1177 Invalid Caption parameter specified.
1178 Invalid Intersection Point flag specified.
1179 Invalid Intersection Test flag specified.
1180 Error Combining Features
1181 Invalid Arc Distance specified.
1182 Invalid Angle specified.
1183 Missing or Invalid RefineBoundary specified in Search method.
1184 XY and PointRef datasets are not allowed with dynamic binding.

MapInfo MapX Developer Guide v4.5 585

MapX Error Codes

Error Description

1185 Custom dataset error. Required interface not supported.

1186 Custom dataset error. GetSample must return an array.
1187 Custom dataset error. Unsupported type returned.
1188 Error saving geoset.
1189 Unable to find file <file> needed by the coordsys dialog.
1190 Layer.UpdateFeature(Target, Source) - 'Target' must be a feature from 'Layer'.
1191 Range and individual value themes are not available on SpatialWare layers.
1192 The find method is not available on SpatialWare layers.
1193 Operation not allowed on a map with no layers.
1194 Empty Text Annotations not allowed.
1195 Failed adding key <key> from drilldown level <level>; possibly others failed.
Key Field not indexed?
1196 Failed removing key <key> from drilldown level <level>; possibly others
failed.
1197 Invalid minimum zoom value specified. Zoom values must be greater than
zero.
1198 Invalid maximum zoom value specified. Zoom values must be greater than
zero.
1199 Setting Value not allowed unless ComputeTheme is false.
1200 Invalid style unit value specified.
1201 Cannot add a theme of type miThemeNone.
1202 The ShowCount property is only supported for ranged and individual value
themes.
1203 The maps display coordinate system cannot be modified while the map
contains visible raster layers.
1204 This line style does not support interleaved styles.
1205 No feature was found using the name you specified.
1206 The AllOthersText property is only supported for ranged and individual value
themes.
1207 Invalid Match Threshold specified. Percentage must be between 1 and 100.
1208 The ShowCount property cannot be set to true, when ComputeTheme is false.
1209 The text font size property cannot be changed, when overriding a layer style.

586 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Error Description

1210 Invalid cache option.

121 Cannot load specified cursor.
1212 Error occurred while searching within a layer.
1213 Error occurred while updating or drawing the selection.
1214 Invalid feature ID.
1215 Unable to retrieve or set the theme style information.
1216 Error while accessing thematic object.
1217 Error occurred while creating the theme.
1218 Error occurred while accessing the thematic modifier.
1219 Error occurred while recalculating the theme.
1220 The theme ranges are invalid. Please verify that the ranges do not overlap.
You may want to set AutoRecompute to FALSE when setting custom theme
ranges.
1221 This property or method is only supported for themes with custom ranges.
1222 Invalid theme category index specified.
1223 This property or method is not supported for the all others category.
1224 Invalid Layer MBRSearch option specified.
1225 Invalid predominant object type.
1226 Operation not allowed on this datasets collection.
1227 Dataset created without SourceRow information. See
Datasets.BuildSourceRows.
1228 This property or method is only supported when ComputeTheme is false.
1229 Error occurred while setting the number of categories for the theme.
1230 A file named <filename> already exists.
1231 Unable to open file <filename>.Verify that the file exists and that you have
sufficient access rights to open it.
1232 Unable to open file <filename>.Verify that the file exists in either the
geodictionary directory or on the list of search paths. Also make sure that you
have sufficient access rights to open it.
1233 Error writing file during export.
1234 Invalid BeginAccessType or Invalid EndAccessType.

MapInfo MapX Developer Guide v4.5 587

MapX Error Codes

Error Description

1235 Theme value must be positive.

1236 This property is not supported for stacked bar charts.
1237 This property is only supported for stacked bar charts.
1238 The GraduateSizeBy property is only supported for graduated stacked bar
charts and for bar charts which are not stacked or independently scaled.
1239 Invalid LayerInfo parameter specified.
1240 Error adding LayerInfo parameter.
1241 Expected LayerInfo parameter <parameter name> is either missing or invalid.
1242 Couldn't open <table name>. Table not found in the geodictionary.
1243 This property is not supported for the current symbol type. The symbol type
must match the type of symbol for which you are changing properties.
1244 Theme deserialization error occurred.
1245 Theme serialization error occurred.
1246 Theme recreation error occurred.
1247 Cannot modify layer. Table may be readonly.
1248 Invalid Expression Parameter specified.
1249 Error occurred while creating the legend.
1250 Legend deserialization error occurred.
1251 Legend serialization error occurred.
1252 Legend recreation error occurred.
1253 Table is not mappable. Make sure table has an object column. If table is a server
table, make sure that there is an entry in the mapinfo mapcatalog for it.
1254 Invalid closematch max value specified. Closematch values must be greater
than or equal to zero.
1255 Invalid rounding value specified.
1256 This property can only be set when the RoundRanges property is set to true.
1257 This property can only be set when the SpreadBy property is set to
miSpreadByColor.
1258 This property can only be set when the InflectRanges property is set to true.
1259 An invalid inflection range index was specified.

588 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Error Description

1260 Not enough ranges to use inflection. There must be at least three ranges to use
inflection.
1261 An invalid apply attribute was specified.
1262 Cannot apply size attributes on a layer which predominantly contains
bounded objects or text objects.
1263 Cannot spread by size on a layer which predominantly contains bounded
objects or text objects.
1264 Cannot spread by color when applying size attributes.
1265 Cannot spread by size when applying color attributes.
1266 Cannot apply size attributes on an individual value theme.
1267 Invalid label max value specified. Label max values must be between 0 and
32767.
1268 Attempt to set the Insertion Layer to an object which is not a valid layer object.
1269 Invalid RowValue object specified.
1270 Invalid RowValue object specified.
1271 Invalid UpdateFeature parameter specified.
1272 Error occurred while setting the current tool to a standard tool.
1273 The insertion layer is not set. The insertion layer must be set before the object
creation tools can be used.
1274 Error occurred while setting the current tool to a custom tool.
1275 Error occurred while creating a standard tool.
1276 Error occurred while creating a custom tool.
1277 Cannot create a theme automatically on Seamless table.
1278 Invalid Key Specified.
1279 The layer that was specified is read-only. A read-only layer cannot be editable.
1280 The layer that was specified is not editable. The insertion layer can only be set
to a layer that is editable.
1281 The layer specified does not contain any area objects. Centroids can only be
shown for layers that contain bounded area objects.
1282 The layer specified does not contain any line objects. Line direction can only
be shown for layers that contain line objects.

MapInfo MapX Developer Guide v4.5 589

MapX Error Codes

Error Description

1283 The layer specified does not contain any point objects or area objects. Nodes
can only be shown for layers that contain point objects or bounded area
objects.
1284 Invalid layer specified. Cannot set the insertion layer to a drilldown, raster,
seamless, or user draw layer.
1285 Invalid Field specified. Name not found, or index out of range.
1286 Error accessing the insertion tools for the map.
1287 The editable property for the insertion layer cannot be set to false.

590 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Constants

This section lists the MapX constants and their values

AggregationFunctionConstants AnnotationChangedTypeConstants
AnnotationTypeConstants ApplyAttributeConstants
AreaUnitConstants BindLayerTypeConstants
CircleTypeConstants ColorConstants
ColorSpreadingMethodConstants ConversionConstants
CoordSysTypeConstants CursorConstants
DataSetTypeConstants DistribMethodConstants
DotSizeConstants ExportFormatConstants
FeatureEditModeConstants FeatureTypeConstants
FieldTypeConstants FillPatternConstants
GraduationConstants IntersectionPointConstants
IntersectionTestConstants LayerBeginAccessConstants
LayerEndAccessConstants LayerInfoTypeConstants
LayerSrvLayerOptions LayerTypeConstants
LineTypeConstants MapDrawConstants
MapUnitConstants MouseWheelSupportConstants
PaperUnitConstants PenStyleConstants
PolyToolFlagConstants PositionConstants
ResolveDataBindConstants SearchTypeConstants
SelectionTypeConstants SpreadByConstants
StyleUnitConstants SymbolTypeConstants
ThemeTypeConstants ToolConstants
ToolFlagConstants ToolTypeConstant

AggregationFunctionConstants
miAggregationSum = 0

MapInfo MapX Developer Guide v4.5 591

Constants

miAggregationAverage = 1

miAggregationCount = 2

miAggregationIndividual = 4

miAggregationAuto = 5

AnnotationChangedTypeConstants
miAddAnnotation = 0

miDeleteAnnotation = 1
miSelectAnnotation = 2

miEditAnnotation = 3

AnnotationTypeConstants
miSymbolAnnotation = 1

miTextAnnotation = 6

ApplyAttributeConstants
miApplyAttributeAll = 0

miApplyAttributeColor = 1

miApplyAttributeSize = 2

AreaUnitConstants
miUnitSquareMile = 14

miUnitSquareKilometer = 15
miUnitSquareInch = 16

miUnitSquareFoot = 17

miUnitSquareYard = 18

miUnitSquareMillimeter = 19

miUnitSquareCentimeter = 20

592 MapInfo MapX Developer Guide v4.5

 ToolUsed event

miUnitSquareMeter = 21

miUnitSquareSurveyFoot = 22

miUnitSquareNauticalMile = 23

miUnitSquareTwip = 24

miUnitSquarePoint = 25

miUnitSquarePica = 26

miUnitSquareDegree = 27

miUnitAcre = 28

miUnitHectare = 29

miUnitSquareLink = 33
miUnitSquareChain = 34

miUnitSquareRod = 35

miUnitPerch = 36

miUnitRood = 37

BindLayerTypeConstants
miBindLayerTypeNormal = 0

miBindLayerTypeXY = 1

miBindLayerTypePointRef = 2

MapInfo MapX Developer Guide v4.5 593

Constants

CircleTypeConstants
Constant Value Description

miCircleTypeScreen 0 The CreateCircularRegion method creates a region that

appears circular on the screen. However, different points
on the circle might not be the same geographic distance
from the center of the circle.
miCircleTypeMap 1 The CreateCircularRegion method creates a region
whose points are all the same geographic distance from
the center. However, depending on which display
coordinate system and projection are in use, the region
might appear distorted, rather than ”circular.”

ColorConstants
Note: These numbers represent OLE_COLOR values (BGR), which can be assigned to
properties such as Style.LineColor. When specifying colors in a geoset, use RGB
color settings instead.
miColorBlack = 0

miColorRed = 255

miColorGreen = 65280

miColorBlue = 16711680

miColorMagenta = 16711935
miColorCyan = 16776960

miColorWhite = 16777215

miColorLightGray = 12632256
miColorDarkGray = 4210752

miColorGray = 8421504

miColorPaleYellow = 13697023
miColorLightYellow = 8454143

miColorYellow = 65535

miColorLimeGreen = 12639424

miColorTeal = 8421440

594 MapInfo MapX Developer Guide v4.5

 ToolUsed event

miColorDarkGreen = 16384

miColorMaroon = 128

miColorPurple = 8388736

miColorOrange = 33023

miColorKhaki = 7051175

miColorOlive = 32896

miColorBrown = 4210816

miColorNavy = 8404992

miColorScrollBars = 0x80000000

miColorDesktop = 0x80000001
miColorActiveTitleBar = 0x80000002

miColorInactiveTitleBar = 0x80000003

miColorMenuBar = 0x80000004

miColorWindowBackground = 0x80000005

miColorWindowFrame = 0x80000006

miColorMenuText = 0x80000007

miColorWindowText = 0x80000008

miColorTitleBarText = 0x80000009

miColorActiveBorder = 0x8000000A

miColorInactiveBorder = 0x8000000B

miColorApplicationWorkspace = 0x8000000C

miColorHighlight = 0x8000000D

miColorHighlightText = 0x8000000E

miColorButtonFace = 0x8000000F

miColorButtonShadow = 0x80000010
miColorGrayText = 0x8000001

miColorButtonText = 0x80000012

miColorInactiveCaptionText = 0x80000013

MapInfo MapX Developer Guide v4.5 595

Constants

miColor3DHighlight = 0x80000014

miColor3DDarkShadow = 0x80000015

miColor3DLight = 0x80000016

miColorInfoText = 0x80000017

miColorInfoBackground = 0x80000018

ColorSpreadingMethodConstants
miColorMethodRGB = 0

miColorMethodHSV = 1

ConversionConstants
miMapToScreen = 0

miScreenToMap = 1

596 MapInfo MapX Developer Guide v4.5

 ToolUsed event

CoordSysTypeConstants
Constant Value Description

miAlbersEqualAreaConic 9
miAzimuthalEquidistant 5 Polar aspect only
miCylindricalEqualArea 2
miEckertIV 14
miEckertVI 15
miEquidistantConic 6 Also known as Simple Conic
miGall 17
miHotineObliqueMercator 7
miLambertAzimuthalEqualArea 4 Polar aspect only
miLambertConformalConic 3
miLambertConformalConicBelgium 19 Modified for Belgium 1972
miLongLat 1 Longitude/Latitude
miMercator 10
miMillerCylindrical 11
miMollweide 13
miNewZealandMapGrid 18
miNonEarth 0 Unprojected; cartesian coords.
miRobinson 12
miSinusoidal 16
miStereographic 20
miSwissObliqueMercator 25
miTransverseMercator 8 Also known as Gauss-Kruger
miTransverseMercatorDenmarkS34J 21 Modified for Danish System 34 Jylland-
Fyn
miTransverseMercatorDenmarkS34S 22 Modified for Sjaelland
miTransverseMercatorDenmarkS45B 23 Modified for Danish System 45 Bornholm
miTransverseMercatorFinland 24 Modified for Finnish KKJ

MapInfo MapX Developer Guide v4.5 597

Constants

CursorConstants
miDefaultCursor = 0

miArrowCursor = 1

miCrossCursor = 2
miIBeamCursor = 3

miIconCursor = 4

miSizeCursor = 5

miSizeNESWCursor = 6

miSizeNSCursor = 7

miSizeNWSECursor = 8

miSizeEWCursor = 9
miUpArrowCursor = 10

miHourglassCursor = 11

miNoDropCursor = 12

miArrowHourglassCursor = 13

miArrowQuestionCursor = 14

miSizeAllCursor = 15

miArrowToolCursor = 16

miPanCursor = 17

miCenterCursor = 18

miZoomInCursor = 19

miZoomOutCursor = 20

miSymbolCursor = 21

miTextCursor = 22

miSelectCursor = 23

miRadiusSelectCursor = 24
miRectSelectCursor = 25

miRegionSelectCursor = 26

598 MapInfo MapX Developer Guide v4.5

 ToolUsed event

miInfoCursor = 27

miSelectPlusCursor = 28

miSelectRadiusPlusCursor = 29

miSelectRectPlusCursor = 30

miSelectRegionPlusCursor = 31

miSelectMinusCursor = 32

miSelectRadiusMinusCursor = 33

miSelectRectMinusCursor = 34

miSelectRegionMinusCursor = 35

miLabelCursor = 36
miDrillDownExpandCursor = 37

miDrillDownContractCursor = 38

miInfoCursorOld = 39

miCustomCursor = 40

DataSetTypeConstants
miDataSetDAO = 1

miDataSetODBC = 2

miDataSetUnbound = 3

miDataSetGlobalHandle = 4
miDataSetOLEData = 5

miDataSetLayer = 6

miDataSetNotesView = 7
miDataSetNotesQuery = 8

miDataSetSafeArray = 9

miDataSetOEO = 10

miDataSetDelphi = 1010

miDataSetDelphi4 = 1011

MapInfo MapX Developer Guide v4.5 599

Constants

miDatasetDelphi5 = 1012

miDataSetADO = 12

miDataSetRDO = 13

DistribMethodConstants
miCustomRanges = 0

miEqualCountPerRange = 1

miEqualRangeSize = 2

miNaturalBreak = 3

miStandardDeviation = 4

DotSizeConstants
miDotSizeSmall = 0

miDotSizeLarge = 1

ExportFormatConstants
miFormatWMF = 0

miFormatBMP = 1

miFormatGIF = 2
miFormatJPEG = 3

miFormatTIF = 4

miFormatPNG = 5
miFormatPSD = 6

600 MapInfo MapX Developer Guide v4.5

 ToolUsed event

FeatureEditModeConstants
miEditModeFeature = 0x1

miEditModeNode = 0x2

miMoveDuplicateNodes = 0x4
miDeleteDuplicateNodes = 0x8

miEditModeAddNode = 0x40

FeatureTypeConstants
miFeatureTypeRegion = 0

miFeatureTypeLine = 1

miFeatureTypeSymbol = 2

miFeatureTypeMixed = 3

miFeatureTypeUnknown = 4

miFeatureTypeText = 5

miFeatureTypeNull = 6

FieldTypeConstants
miTypeString = 0

miTypeNumeric = 1

miTypeDate = 2

miTypeInt = 3

miTypeSmallInt = 4

miTypeFloat = 5

miTypeLogical = 6

MapInfo MapX Developer Guide v4.5 601

Constants

FillPatternConstants
miPatternNoFill = 0

miPatternHollow = 1

miPatternSolid = 2
miPatternHorizontal = 3

miPatternVertical = 4

miPatternFDiag = 5

miPatternFilBDiag = 6

miPatternCross = 7

miPatternDiagCross = 8

GraduationConstants
miGraduateBySquareRoot = 0

miGraduateByConstant = 1

miGraduateByLogarithm = 2

IntersectionPointConstants
miIntersectCrossings = 9

miIntersectCommon = 10

miIntersectAll = 11

IntersectionTestConstants
miIntersectCentroidWithinFeature = 0

miIntersectFeature = 1

miIntersectEntirelyWithinFeature = 2

602 MapInfo MapX Developer Guide v4.5

 ToolUsed event

LayerBeginAccessConstants
miAccessRead= 0

miAccessReadWrite = 1

LayerEndAccessConstants
miAccessEnd= 0

LayerInfoTypeConstants
miLayerInfoTypeTab = 0

miLayerInfoTypeUserDraw = 1
miLayerInfoTypeRaster = 2

miLayerInfoTypeShape = 3

miLayerInfoTypeServer = 4
miLayerInfoTypeGeodictUserName = 5

miLayerInfoTypeTemp = 6

miLayerInfoTypeNewTable = 7

LayerSrvLayerOptions
miLayerCacheOn = 0

miLayerCacheOff = 1

miLayerMBRSearchOn = 0

miLayerMBRSearchOff = 2

MapInfo MapX Developer Guide v4.5 603

Constants

LayerTypeConstants
miLayerTypeNormal = 0

miLayerTypeRaster = 2

miLayerTypeSeamless = 4
miLayerTypeUnknown = 5

miLayerTypeUserDraw = 6

miLayerTypeDrilldown = 7

LineTypeConstants
miLineTypeNone = 0

miLineTypeSimple = 1

miLineTypeArrow = 2

MapDrawConstants
miDrawBegin = 1

miDrawEnd = 2

MapUnitConstants
miUnitMile = 0

miUnitKilometer = 1
miUnitInch = 2

miUnitFoot = 3

miUnitYard = 4

miUnitMillimeter = 5

miUnitCentimeter = 6

miUnitMeter = 7
miUnitSurveyFoot = 8

miUnitNauticalMile = 9

604 MapInfo MapX Developer Guide v4.5

 ToolUsed event

miUnitTwip = 10

miUnitPoint = 11

miUnitPica = 12

miUnitDegree = 13

miUnitLink = 30

miUnitChain = 31

miUnitRod = 32

MouseWheelSupportConstants
miNoMousewheelSupport = 1

miMousewheelNoAutoScroll = 2
miFullMousewheelSupport = 3

PaperUnitConstants
miPaperUnitMile = 0

miPaperUnitKilometer = 1

miPaperUnitInch = 2

miPaperUnitFoot = 3

miPaperUnitYard = 4

miPaperUnitMillimeter = 5

miPaperUnitCentimeter = 6
miPaperUnitMeter = 7

miPaperUnitSurveyFoot = 8

miPaperUnitNauticalMile = 9

miPaperUnitTwip = 10

miPaperUnitPoint = 11

miPaperUnitPica = 12
miPaperUnitDegree = 13

MapInfo MapX Developer Guide v4.5 605

Constants

miPaperUnitLink = 30

miPaperUnitChain = 31

miPaperUnitRod = 32

PenStyleConstants
miPenNone = 0

miPenSolid = 1

Note:Other pen styles are available, although constants have not been defined for those
styles; see Style.LineStyle property.

PolyToolFlagConstants
miPolyToolBegin = 0

miPolyToolEnd = 1

miPolyToolEndEscaped = 2

miPolyToolInProgress = 3

PositionConstants
miPositionCC = 0

miPositionTL = 1

miPositionTC = 2

miPositionTR = 3
miPositionCL = 4

miPositionCR = 5

miPositionBL = 6

miPositionBC = 7

miPositionBR = 8

606 MapInfo MapX Developer Guide v4.5

 ToolUsed event

ResolveDataBindConstants
miChooseField = 0

miChooseLayer = 1

miChooseGeoSet = 2

SearchTypeConstants
miSearchTypeCentroidWithin = 0

miSearchTypePartiallyWithin = 1

miSearchTypeEntirelyWithin = 2

SelectionTypeConstants
miSelectionNew = 0

miSelectionAppend = 1
miSelectionRemove = 2

SpreadByConstants
miSpreadByColor = 1

miSpreadByNone = 0

miSpreadBySize = 2

StyleUnitConstants
miStyleUnitPixel = 0

miStyleUnitTenthsOfPoint = 1

SymbolTypeConstants
miSymbolTypeBitmap = 1

miSymbolTypeTrueTypeFont = 0

miSymbolTypeVector = 2

MapInfo MapX Developer Guide v4.5 607

Constants

ThemeTypeConstants
miThemeRanged = 0

miThemeBarChart = 1

miThemePieChart = 2
miThemeGradSymbol = 3

miThemeDotDensity = 4

miThemeIndividualValue = 5

miThemeAuto = 6

miThemeNone = 9

ToolConstants
miArrowTool = 1000

miPanTool = 1001

miCenterTool = 1002

miZoomInTool = 1003

miZoomOutTool = 1004

miSymbolTool = 1005

miTextTool = 1006
miSelectTool = 1007

miRadiusSelectTool = 1008

miRectSelectTool = 1009

miPolygonSelectTool = 1010

miLabelTool = 1011

miAddLineTool = 1012
miAddPolylineTool = 1013

miAddRegionTool = 1014

miAddPointTool = 1015

608 MapInfo MapX Developer Guide v4.5

 ToolUsed event

ToolFlagConstants
miToolBegin = 0

miToolEnd = 1

miToolEndEscaped = 2
miToolInProgress = 3

ToolTypeConstants
miToolTypePoint = 0

miToolTypeLine = 1
miToolTypeCircle = 2

miToolTypeMarquee =3

miToolTypePoly = 4

miToolTypePolygon = 5

MapInfo MapX Developer Guide v4.5 609

Constants

610 MapInfo MapX Developer Guide v4.5

 ToolUsed event

Creating Expressions

Expressions in MapX are useful for several reasons. The Layer.Search method can be used to
select a subset of a layer's features based on an expression. In this case, the expression
should evaluate to a boolean value, e.g. "year(Received) = 1990 and month(Received) > 4".

The DataSet.AddField method uses expressions to create a new field by applying an

expression to the existing columns. These expressions can evaluate to a date, numerical, or
string value, as in "Female_Pop + Male_Pop" or "Proper$(City) + "", "" + UCase$(State)"
Expressions are formed using dataset field names, constants (i.e. specific data values), or
variable substitutions, along with functions and operators which act upon the columns and
constants.

MapX allows for the use of variable substitution in expressions. An expression can contain
a reference to a variable name. A variable is a name along with a variant. When the
expression sees an unresolved identifier it will try to resolve it in the variables collection.
The variant can be of any type (date, string, number, etc, or MapX Feature object.)

String constants in expressions should be enclosed in double quotes so that MapX knows to
treat it as a string, rather than thinking it is a dataset field name or variable.
When specifying dates as string constants, the following applies:

• Dates consist of a month, a day, and an optional year.

• The year is specified by four digits.
• The entire date string should be enclosed in double quotes.
• The components of a date can be separated by hyphens or slashes.

Contents
• Operators
• Functions

MapInfo MapX Developer Guide v4.5 611

Creating Expressions

612 MapInfo MapX Developer Guide v4.5

 Geographic operators

Operators

Below is a list of the operators used in MapX and related topics.

Operators:
• Geographic operators
• Mathematical operators
• String operators 903
• Comparison operators
• Numerical Comparison
• String Comparison
• Date Comparison
• Logical Comparison
• Logical operators

Related Topics:
• String Clauses
• Date Clauses
• Keywords
• Operator Precedence

Geographic operators
MapX supports several geographic operators: contains, contains_within, entirely_within,
intersects, and within. These operators can be used in any MapX expression. All
geographic operators are infix operators (i.e. they operate on two objects and return
boolean).

Operator Evaluates true if the:

object1 CONTAINS object2 Centroid of second object is within the first

object.
object1 CONTAINS_ENTIRE object2 Second object is entirely inside the first object.
object1 CONTAINS_PART object2 First object touches second object.
object1 ENTIRELY_WITHIN object2 First object is entirely inside the second object.
object1 INTERSECTS object2 First object touches second object

MapInfo MapX Developer Guide v4.5 613

Operators

Operator Evaluates true if the:

object1 PARTIALY_WITHIN object2 First object touches second object.

object1 WITHIN object2 Centroid of first object is within the second
object.

Mathematical operators
A+B + addition
A-B - subtraction
-A (negative) - negation
A*B * multiplication
A/B / division
A\B \ integer division
A^B ^ exponentiation
Note that you can:

• Add numbers to dates to yield another date.

• Subtract a number from a date to yield another date.
• Subtract a date from a date to yield a number.
When you add numbers to dates, or subtract numbers from dates, MapX treats the numbers
as specifying a number of days. If you want to add or subtract a week, you would use the
number 7. When you want to add or subtract a month, you could use 30 or 31. When MapX
subtracts a date from a date, the resulting number indicates a number of days.

614 MapInfo MapX Developer Guide v4.5

 Comparison operators

String operators
& “concatenation” — connects strings and string expressions.
+ “concatenation” — connects strings and string expressions.
Note: Remember that string constants must be enclosed in double quotes.

Comparison operators
= “equals”
<> “not equals”
> “greater than”
< “less than”
>= “greater than or equal to”
<= “less than or equal to”

Numerical Comparison
Numerical comparisons are based on the numerical values of the expressions and numerical
constants.

Example
All rows where the median age is 42.

• MED_AGE=42
Note: This expression selects only those records where the median age is exactly 42.
When your median age data contains a decimal portion (which is the case for
MapInfo–supplied demographic data) then it is unlikely that there are many
regions with a median age of exactly 42. In this case, you may want to use the
Round function to search for records whose median age is approximately equal to
42.

String Comparison
String comparisons are based on the exact character content of the string. In this case “>”
means “alphabetically greater than” (i.e. comes after in the alphabet) and “<” means
“alphabetically less than.”

When typing a string constant into an expression, you should enclose it in quotes so that
MapX knows to treat it as a string, rather than treating it as a column name.

MapInfo MapX Developer Guide v4.5 615

Operators

Example
All rows where the vendor is Acme.

• VENDOR=”Acme”
Note: The equal operator is case insensitive.

Date Comparison
Remember to enclose date constants in quotes and use the order Month, Day, Year.

Example
All received after October 9, 1991.

• RECEIVED>”10–9–91”
Note: This expression does not select those received on October 9, 1991. When you
want them as well, use the ">=" operator
• RECEIVED>=”10–9–91”

Example
Records for all received before August, no matter what year.
• Month(RECEIVED)<8

Logical Compariso
Example
All that have shipped.

• Shipped
Note: The column “Shipped” is a logical column. It contains “T” for true, or yes, and
“F” for false, or no. When an order is shipped, it is marked “T”. Otherwise, it is
not shipped. For orders that are shipped, expression 27 evaluates to true. For
orders not shipped it evaluates to false.

Example
All that have not shipped.

• Str$(Shipped)=”F”
• Not Shipped

616 MapInfo MapX Developer Guide v4.5

 Logical operators

Logical operators

and Is “true” if (and only if) both of its arguments (the expressions it joins
together) are true. A record must satisfy both of these conditions if it is
to be selected.
or is “true” if either one, or both, of its arguments (the expressions it joins
together) are true. A record need satisfy only one of these conditions if
it is to be selected. It is also selected if both of its conditions ar
satisfied.
not is “true” if its argument (the expression it applies to) is false. A record
is selected if it does not meet the stated condition.

“And”, “or”, and “not” are logical operators. You use them to combine expressions when
using methods like Layer.Search.

For example, suppose you want to select all properties that are worth $250,000 or more and
are in Columbia county. So, you would combine two simple expressions using the "and"
operator:

• COUNTY = ”Columbia” and VALUE >= 250000

Now, what if you want all properties worth $250,000 or more and not in Columbia county?
You can use “not” to negate the first clause of the previous expression:

• not(COUNTY=”Columbia”) and VALUE>=250000

You can use “or” when you want to specify alternative conditions, such as:

• COUNTY=”Columbia” or COUNTY=”Greene”

String Clauses
Example
All customers from N to Q.
• LAST_NAME >= ”N” and LAST_NAME <”R”
Note: The first part of the expression checks for names that are either alphabetically
equal to “n” or that are alphabetically greater than (after) “n”. The second part of
the expression checks for names that are alphabetically less than (before) “r”. Any
name starting with letters “n” through “q” satisfies this condition.

MapInfo MapX Developer Guide v4.5 617

Operators

Example
All customers whose last name begins with C.

• LAST_NAME>=”C” and LAST_NAME<”D”

Note: The logic of this expression is the same as the logic for expression 47.

Date Clauses
Example
Records for all received in August 1990

• Month(RECEIVED)=8 and Year(RECEIVED)=1990

Note: In this expression we specify the year explicitly, using the
“year(<somecolumn>)” function to extract it from the date.

Example
Records for all received in July or September of 1989

• month(RECEIVED)=(7, 9) and year(RECEIVED)=89

Keywords
MapX supports the use of keywords "like" and “between”.

Consider the following example, which illustrates “between”:

• PRICE between 50000 and 100000

You can also use between with character strings.

The keyword "like" is used for string pattern matching.

• The underscore character matches a single character.

• The percent character matches zero or more characters.
The comparison is case insensitive.

Example
To determine if a string starts with "South"

• STATE like "South%"

618 MapInfo MapX Developer Guide v4.5

 Keywords

Operator Precedence
When MapX evaluates expressions it needs to know which components of an expression to
evaluate first. This is called precedence. By convention, certain operators are assigned
different levels of precedence. Those with the highest level are evaluated first. The following
table lists MapX's operators in the order in which they are evaluated. Operators at the same
level of precedence are evaluated from left to right, besides exponentiation, which evaluates
from the right.

Highest Priority: parenthesis

exponentiation
negation
multiplication, division
addition, subtraction
geographic operators
comparison operators
Not
And

Lowest Priority: Or

For example, the expression 3+4*2 produces a result of 11. That is because multiplication has
a higher precedence than addition and is performed first. Parenthesis must be used to force
MapX to do the addition first: (3+4)*2.

Now consider this expression, which is intended to select all records July or September of
1989.

• year(RECEIVED)=89 and month(RECEIVED)=7 or month(RECEIVED)=9

Because “and” has higher precedence than “or”, MapX treats this expression as though
“year(RECEIVED)=89 and month(RECEIVED)=7” was enclosed in parentheses. In this case,
any record for July of 89 or for September of any year would be selected. That's probably not
what you want. However, by adding parentheses to the second expression, you can get
what you want:

• year(RECEIVED)=89 and (month(RECEIVED)=7 or month(RECEIVED)=9)

Note: When you are not sure how MapX evaluates an expression with several
operators, you should use parentheses to group elements as you want them.

MapInfo MapX Developer Guide v4.5 619

Operators

620 MapInfo MapX Developer Guide v4.5

 Keywords

Functions

Functions take data values and perform some operation on them to produce a new value.
Most of MapX's functions take one or two parameters. A parameter can be a column or it
can be another expression.

MapX uses the keyword “obj” or “object” with the geographic functions: Area, CentroidX,
CentroidY, ObjectLen, and Perimeter. This keyword tells MapX that it has to get values
based on the graphical objects in the table rather than the tabular data.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

MapX Functions

Abs( ) function Acos( ) function Area( ) function

Asc( ) function Asin( ) function Atn( ) function
Buffer( ) function Centroid( ) function CentroidX( ) function
CentroidY( ) function Chr$( ) function Cos( ) function
CurDate( ) function Day( ) function DeformatNumber$( )
function
Distance( ) function Exp( ) function Fix( ) function
Format$( ) function FormatDate$( ) function FormatNumber$( ) function
InStr( ) function Int( ) function LCase$( ) function
Left$( ) function Log( ) function LTrim$( ) function
Maximum( ) function MBR( ) function Mid$( ) function
Minimum( ) function Month( ) function ObjectLen( ) function
ObjectType( ) function Perimeter( ) function Proper$( ) function
Right$( ) function Round( ) function RTrim$( ) function
Sgn( ) function Sin( ) function Space$( ) function
Sqr( ) function StringCompare( ) function StringCompareIntl( )
function

MapInfo MapX Developer Guide v4.5 621

Functions

StringToDate( ) function Str$( ) function Tan( ) function

UCase$( ) function Val( ) function Weekday( ) function
Year( ) function

622 MapInfo MapX Developer Guide v4.5

 Acos( ) function

Abs( ) function
Purpose
This returns the absolute value of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Abs( num_expr )

Part Description

num_expr A numeric expression.

Remarks
The Abs( ) function returns the absolute value of the expression specified by num_expr

If num_expr has a value greater than or equal to zero, Abs( ) returns a value equal to
num_expr. If num_expr has a negative value, Abs( ) returns a value equal to the value of
num_expr multiplied by negative one.

Acos( ) function
Purpose
This returns the arc-cosine value of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Acos(num_expr)

Part Description

num_expr A numeric expression between one and minus one, inclusive.

Remarks
The Acos( ) function returns the arc-cosine of the numeric num_expr value. In other words,
Acos( ) returns the angle whose cosine is equal to num_expr

MapInfo MapX Developer Guide v4.5 623

Functions

The result returned from Acos( ) represents an angle, expressed in radians. This angle will
be somewhere between zero and Pi radians (given that Pi is equal to approximately
3.141593, and given that Pi/2 radians represents 90 degrees).

To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

Since cosine values range between one and minus one, the expression num_expr should
represent a value no larger than one and no smaller than minus one.

Area( ) function
Purpose
This returns the geographical area of an Object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Area(obj_expr, unit_name)

Part Description

obj_expr An in object expression

unit_name A string representing the name of an area unit (e.g. "sq km").

Remarks
The Area( ) function returns the area of the geographical object specified by obj_expr

The function returns the area measurement in the units specified by the unit_name
parameter; for example, to obtain an area in acres, specify "acre" as the unit_name
parameter. See the Set Area Units statement for the list of available unit names.

Only regions, ellipses, rectangles, and rounded rectangles have any area. By definition, the
Area( ) of a point, arc, text, line, or polyline object is zero. The Area( ) function returns
approximate results when used on rounded rectangles. MapX calculates the area of a
rounded rectangle as if the object were a conventional rectangle.

624 MapInfo MapX Developer Guide v4.5

 Area( ) function

Asc( ) function
Purpose
This returns the character code for the first character in a string expression.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ int= ]Asc(string_expr)

Part Description

string_expr A String expression

Remarks
The Asc( ) function returns the character code representing the first character in the string
specified by string_expr.

If string_expr is a null string, the Asc( ) function returns a value of zero.

Note that the Windows and Macintosh operating environments use different character sets.
Therefore, the values returned by the Asc( ) function depend partly on the operating
environment that is in use at run-time. However, all MapInfo environments have common
character codes within the range of 32 (space) to 126 (tilde).
On a system that supports double-byte character sets (e.g. Windows Japanese): if the first
character of string_expr is a single-byte character, Asc( ) returns a number in the range 0 -
255; if the first character of string_expr is a double-byte character, Asc( ) returns a value in
the range 256 - 65,535.

On systems that do not support double-byte character sets, Asc( ) returns a number in the
range 0 - 255.

MapInfo MapX Developer Guide v4.5 625

Functions

Asin( ) function
Purpose
This returns the arc-sine value of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Asin ( num_expr )

Part Description

num_expr A numeric expression from one to minus one, inclusive.

Remarks
The Asin( ) function returns the arc-sine of the numeric num_expr value. In other words,
Asin() returns the angle whose sine is equal to num_expr

The result returned from Asin( ) represents an angle, expressed in radians. This angle will be
somewhere between -Pi/2 and Pi/2 radians (given that Pi is approximately equal to
3.141593, and given that Pi/2 radians represents 90 degrees).

To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

Since sine values range between one and minus one, the expression num_expr should
represent a value no larger than one and no smaller than minus one.

Atn( ) function
Purpose
This returns the arc-tangent value of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

626 MapInfo MapX Developer Guide v4.5

 Buffer( ) function

Syntax
[ float= ]Atn( num_expr )

Part Description

num_expr A numeric expression.

Remarks
The Atn( ) function returns the arc-tangent of the numeric num_expr value. In other words,
Atn( ) returns the angle whose tangent is equal to num_expr. The num_expr expression can
have any numeric value.

The result returned from Atn( ) represents an angle, expressed in radians, in the range -Pi/2
radians to Pi/2 radians.

To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

Buffer( ) function
Purpose
This returns a region object that represents a buffer region (the area within a specified buffer
distance of an existing object).

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ region object= ]Buffer( inputobject, resolution, width, unit_name )

Part Description

inputobject an object expression

resolution a SmallInt value representing the number of nodes per circle at
each corner
width is a Float value representing the radius of the buffer; if width is
negative, and if inputobject is a closed object, the object returned
represents an object smaller than the original object
unit_name is the name of the distance unit (e.g. "mi" for miles, "km" for
kilometers) used by width

MapInfo MapX Developer Guide v4.5 627

Functions

Remarks
The Buffer( ) function returns a region representing a buffer.

Centroid( ) function
Purpose
This returns the centroid (center point) of an object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ Point object= ]Centroid(obj_expr)

Part Description
obj_expr An object expression.

Remarks
The Centroid( ) function returns a point object, which is located at the centroid of the
specified obj_expr object.

Note: In MapInfo, a region’s centroid does not represent its center of mass. Instead, the
centroid represents the location used for automatic labeling, geocoding, and
placement of thematic pie and bar charts. If you edit a map in reshape mode, you
can reposition region centroids by dragging them.
If the obj_expr parameter represents a point object, the Centroid( ) function returns the
position of the point.
If the obj_expr parameter represents a line object, the Centroid( ) function returns the point
midway between the ends of the line.

If the obj_expr parameter represents a polyline object, the Centroid( ) function returns a
point located at the mid point of the middle segment of the polyline.
If the obj_expr parameter represents any other type of object, the Centroid( ) function
returns a point located at the true centroid of the original object. For rectangle, arc, text, and
ellipse objects, the centroid position is halfway between the upper and lower extents of the
object, and halfway between the left and right extents. For region objects, however, the
centroid position is always "on" the object in question, and therefore may not be located
halfway between the object’s extents.

628 MapInfo MapX Developer Guide v4.5

 CentroidY( ) function

CentroidX( ) function
Purpose
This returns the x-coordinate of the centroid of an object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]CentroidX( obj_expr )

Part Description

obj_expr An object expression

Remarks
The CentroidX( ) function returns the X coordinate (e.g. Longitude) component of the
centroid of the specified object. See the Centroid( ) function for a discussion of what the
concept of a centroid position means with respect to different types of graphical objects
(lines vs. regions, etc.).

The coordinate information is returned in Map.NumericCoordSys. By default, MapX uses a

longitude, latitude coordinate system.

CentroidY( ) function
Purpose
This returns the y-coordinate of the centroid of an object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]CentroidY(obj _expr)

Part Description

obj_expr An object expression

MapInfo MapX Developer Guide v4.5 629

Functions

Remarks
The CentroidY( ) function returns the Y-coordinate (e.g. latitude) component of the centroid
of the specified object. See the Centroid( ) function for a discussion of what the concept of a
centroid position means, with respect to different types of graphical objects (lines vs.
regions, etc.).
The coordinate information is returned in Map.NumericCoordSys. By default, MapX uses a
longitude, latitude coordinate system.

Chr$( ) function
Purpose
This returns a one-character string corresponding to a specified character code.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Chr$(num_expr)

Part Description
num_expr An Integer value from 0 to 255 (or, if a double-byte character set
is in use, from 0 to 65,535), inclusive

Remarks
The Chr$( ) function returns a string, one character long, based on the character code
specified in the num_expr parameter. On most systems, num_expr should be a positive
Integer value between 0 and 255. On systems that support double-byte character sets (e.g.
Windows Japanese), num_expr can have a value from 0 to 65,535.

If the num_expr parameter is fractional, MapX rounds to the nearest integer.

Character 12 is the form-feed character. Thus, you can use the statement Print Chr$(12) to
clear the Message window. Character 10 is the line-feed character; see example below.

Character 34 is the double-quotation mark ("). If a string expression includes the function
call Chr$(34), MapX embeds a double-quote character in the string.

630 MapInfo MapX Developer Guide v4.5

 CurDate( ) function

Cos( ) function
Purpose
This returns the cosine of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Cos (num_expr)

Parts Description

num_expr A numeric expression representing an angle in radians

Remarks
The Cos( ) function returns the cosine of the numeric num_expr value, which represents an
angle in radians. The result returned from Cos( ) will be between one and minus one.

To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

CurDate( ) functio
Purpose
Returns the current date in YYYYMMDD format.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
CurDate( )

Return Value
Date

Remarks
The Curdate( ) function returns a Date value representing the current date. The format will
always be YYYYMMDD. To change the value to a string in the local system format use the
FormatDate$( ) or Srt$( ) functions.

MapInfo MapX Developer Guide v4.5 631

Functions

Day( ) function
Purpose
Returns the day component from a Date expression.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
Day( date_expr )
date_expr is a Date expression

Return Value
SmallInt from 1 to 31

Remarks
The Day( ) function returns an integer value from one to thirty-one, representing the day-of-
the-month component of the specified date. For example, if the specified date is 12/17/93,
the Day( ) function returns a value of 17.

DeformatNumber$( ) function
Purpose
Removes formatting from a string that represents a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]DeformatNumber$ ( numeric_string )

Part Description
numeric_string a string that represents a numeric value, such as "12,345,678"

632 MapInfo MapX Developer Guide v4.5

 Distance( ) function

Remarks
This function returns a string that represents a number. The return value does not include
thousands separators, regardless of whether the numeric_string argument included
thousands separators. The return value uses a period as the decimal separator, regardless of
whether the user's computer is set up to use another character as the decimal separator.

Distance( ) function
Purpose
This returns the distance between two locations.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Distance( x1 , x2 , y1 , y2 , unit_name)

Part Description
x1 and x2 x-coordinates (e.g. longitude)
y1 and y2 y-coordinates (e.g. latitude)
unit_name A string representing the name of a distance unit (e.g. "km")

Remarks
The Distance( ) function calculates the distance between two locations.

The function returns the distance measurement in the units specified by the unit_name
parameter; for example, to obtain a distance in miles, specify "mi" as the unit_name
parameter. See the Set Distance Units statement for the list of available unit names.

The x- and y-coordinate parameters must use the coordinate system set in
Map.NumericCoordSys. By default, MapInfo expects coordinates to use a longitude,
latitude coordinate system.

MapInfo MapX Developer Guide v4.5 633

Functions

If Map.NumericCoordSys is an earth coordinate system, Distance( ) returns the great-circle

distance between the two points. A great-circle distance is the shortest distance between two
points on a sphere. (A great circle is a circle that goes around the earth, with the circle’s
center at the center of the earth; a great-circle distance between two points is the distance
along the great circle which connects the two points.)
If Map.NumericCoordSys is a non-earth coordinate system, Distance( ) returns the Cartesian
distance.

Exp( ) function
Purpose
This returns the number e raised to a specified exponent.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Exp( num_expr )

Part Description
num_expr A numeric expression

Remarks
The Exp( ) function raises the mathematical value e to the power represented by num_expr
has a value of approximately 2.7182818.

Note: MapX supports general exponentiation through the caret operator ( ^ ).

634 MapInfo MapX Developer Guide v4.5

 Exp( ) function

Fix( ) functio
Purpose
This returns an integer value, obtained by removing the fractional part of a decimal value.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ Int= ]Fix(num_expr)

Part Description

num_expr A numeric expression

Remarks
The Fix( ) function removes the fractional portion of a number, and returns the resultant
integer value.

The Fix( ) function is similar to, but not identical to, the Int( ) function. The two functions
differ in the way that they treat negative fractional values. When passed a negative
fractional number, Fix( ) returns the nearest integer value greater than or equal to the
original value; thus, the function call:

Fix(-2.3)
returns a value of -2. But when the Int( ) function is passed a negative fractional number, it
returns the nearest integer value that is less than or equal to the original value. Thus, the
function call:

Int(-2.3)
returns a value of -3.

MapInfo MapX Developer Guide v4.5 635

Functions

Format$( ) function
Purpose
This returns a string representing a custom-formatted number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Format$(value , pattern)

Part Description

value A numeric expression

pattern A string which specifies how to format the results

Remarks
The Format$( ) function returns a string representing a formatted number. Given a numeric
value such as 12345.67, Format$( ) can produce formatted results such as "$12,345.67".

The value parameter specifies the numeric value that you want to format.

The pattern parameter is a string of code characters, chosen to produce a particular type of
formatting. The pattern string should include one or more special format characters, such as
#, 0, % , the comma character, the period, or the semi-colon; these characters control how the
results will look. The table below summarizes the format characters.

pattern character Role in formatting results:

# The result will include one or more digits from the value.
If the pattern string contains one or more # characters to the left
of the decimal place, and if the value is between zero and one,
the formatted result string will not include a zero before the
decimal place.
0 A digit placeholder similar to the # character. If the pattern
string contains one or more 0 characters to the left of the decimal
place, and the value is between zero and one, the formatted
result string will include a zero before the decimal place. See
examples below.

636 MapInfo MapX Developer Guide v4.5

 Exp( ) function

pattern character Role in formatting results:

. (period) The pattern string must include a period if you want the result
string to include a "decimal separator." The result string will
include the decimal separator currently in use on the user's
computer. To force the decimal separator to be a period, use the
Set Format statement.
, (comma) The pattern string must include a comma if you want the result
string to include "thousand separators." The result string will
include the thousand separator currently set up on the user's
computer. To force the thousand separator to be a comma, use
the Set Format statement.
% The result will represent the value multiplied by one hundred;
thus, a value of 0.75 will produce a result string of "75%". If you
wish to include a percent sign in your result, but you do not
want MapX to multiply the value by one hundred, place a \
(back slash) character before the percent sign (see below).
E+ The result is formatted with scientific notation. For example, the
value 1234 produce the result "1.234e+03". If the exponent if
positive, a plus sign appears after the "e". If the exponent is
negative (which is the case for fractional numbers), the results
include a minus sign after the "e".
E- This string of control characters functions just as the "E+" string,
except that the result will never show a plus sign following the
"e".
; (semi-colon) By including a semicolon in your pattern string, you can specify
one format for positive numbers and another format for
negative numbers. Place the semicolon after the first set of
format characters, and before the second set of format
characters. The second set of format characters applies to
negative numbers. If you want negative numbers to appear with
a minus sign, include "-" in the second set of format characters.
\ If the back slash character appears in a pattern string, MapX
does not perform any special processing for the character which
follows the back slash. This lets you include special characters
(e.g. % ) in the results, without causing the special formatting
actions described above.

MapInfo MapX Developer Guide v4.5 637

Functions

FormatDate$( ) function
Purpose
Returns a date formatted in the short date style specified by the Control Panel.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]FormatDate$ ( value )

Part Description

value A number representing the date in a YYYMMDD format.

Remarks
The FormatDate$( ) function returns a string representing a date in the local system format
as specified by the Control Panel.

Example in Visual Basic:

Assuming Control Panel settings are d/m/y for date order, '-' for date separator, and "dd-
MMM-yyyy" for short date format:

Dim lyrUSA As MapXLib.Layer

Dim ds As MapXLib.Dataset
Dim ftrs As MapXLib.Features
Set lyrUSA = Map1.Layers.Add("USA")
Set ds = Map1.Datasets.Add(miDataSetDAO, Data1.Recordset,
"TestDataset", "GEOABBR", , lyrUSA, , False)

'Looks for "Oct" in result returned by FormatDate$. Should

succeed for each record in the dataset.
Set ftrs = lyrUSA.Search("InStr(1, FormatDate$(20001011, ""Oct"")
<> 0")
If ftrs.Count <> 51 Then
Debug.print "FormatDate$ failed"
End If

638 MapInfo MapX Developer Guide v4.5

 Exp( ) function

FormatNumber$( ) functio
Purpose
This returns a string representing a number, including thousands separators and decimal-
place separators that match the user's system configuration.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]FormatNumber$( num )

Part Description

num A numeric value or a string that represents a numeric value,

such as "1234.56"

Remarks
This function returns a string that represents a number. If the number is large enough that it
needs thousands separators, this function inserts thousands separators. MapInfo reads the
user's system configuration to determine which characters to use as the thousands separator
and decimal separator.

The following table demonstrates how the FormatNumber$( ) function behaves if the user's
computer is set up to use comma as the thousands separator and period as the decimal
separator (United States defaults):

Function Call Result returned

FormatNumber$("12345.67") "12,345.67" (inserted a thousands separator)

FormatNumber$("12,345.67") "12,345.67" (no change)

If the user's computer is set up to use period as the thousands separator and comma as the
decimal separator, the following table demonstrates the results:

Function Call Result returned

FormatNumber$("12345.67") "12.345,67" (inserted a thousands separator, and

changed the decimal separator to match user's setup)
FormatNumber$("12,345.67") "12.345,67" (changed both characters to match the user's
setup)

MapInfo MapX Developer Guide v4.5 639

Functions

InStr( ) function
Purpose
This returns a character position, indicating where a substring first appears within another
string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ int= ]InStr( position, string, substring )

Part Description

position A positive integer, indicating the start position of the search

string A string expression
substring A string expression which we will try to locate in string

Remarks
The InStr( ) function tests whether the string expression string contains the string expression
substring. MapX searches the string expression, starting at the position indicated by the
position parameter; thus, if the position parameter has a value of one, MapX will search
from the very beginning of the string parameter.

If string does not contain substring, the InStr( ) function returns a value of zero.

If string does contain substring, the InStr( ) function returns the character position where the
substring appears. For example, if the substring appears at the very start of the string, InStr(
) will return a value of one.

If the substring parameter is a null string, the InStr( ) function returns zero.

The InStr( ) function is case-sensitive. In other words, the InStr( ) function cannot locate the
substring "BC" within the larger string "abcde", because "BC" is upper-case.

640 MapInfo MapX Developer Guide v4.5

 LCase$( ) function

Int( ) functio
Purpose
This returns an integer value obtained by removing the fractional part of a decimal value.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ Int= ]Int( num_expr )

Part Description

num_expr A numeric expression

Remarks
The Int( ) function returns the nearest integer value that is less than or equal to the specified
num_expr expression.

Note that the Fix( ) function is similar to, but not identical to, the Int( ) function. The two
functions differ in the way that they treat negative fractional values. When passed a
negative fractional number, Fix( ) will return the nearest integer value greater than or equal
to the original value; thus, the function call

Fix(-2.3)
will return a value of -2. But when the Int( ) function is passed a negative fractional number,
it returns the nearest integer value that is less than or equal to the original value. Thus, the
function call

Int(-2.3)
returns a value of -3.

LCase$( ) function
Purpose
This returns a lower-case equivalent of a string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

MapInfo MapX Developer Guide v4.5 641

Functions

Syntax
[ string= ]LCase$( string_expr )

Part Description

string_expr A string expression

Remarks
The LCase$( ) function returns the string which is the lower-case equivalent of the string
expression string_expr.

Conversion from upper- to lower-case only affects alphabetic characters (A through Z);
numeric digits and punctuation marks are not affected. Thus, the function call:

LCase$( "A#12a" )
returns the string value "a#12a".

Left$( ) functio
Purpose
This returns part or all of a string, beginning at the left end of the string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Left$( string_expr, num_expr )

Part Description

string_expr A string expression

num_expr A numeric expression, zero or larger

Remarks
The Left$( ) function returns a string which consists of the left most num_expr characters of
the string expression string_expr.

The num_expr parameter should be an integer value, zero or larger. If num_expr has a
fractional value, MapX rounds to the nearest integer. If num_expr is zero, Left$( ) returns a
null string. If the num_expr parameter is larger than the number of characters in the
string_expr string, Left$( ) returns a copy of the entire string_expr string.

642 MapInfo MapX Developer Guide v4.5

 LTrim$( ) function

Log( ) function
Purpose
This returns the natural logarithm of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Log( num_expr )

Part Description

num_expr A numeric expression.

Remarks
The Log( ) function returns the natural logarithm of the numeric expression specified by the
num_expr parameter.

The natural logarithm represents the number to which the mathematical value e must be
raised in order to obtain num_expr has a value of approximately 2.7182818.

The logarithm is only defined for positive numbers; accordingly, the Log( ) function will
generate an error if num_expr has a negative value.

You can calculate logarithmic values in other bases (e.g. base 10) using the natural
logarithm. To obtain the base-10 logarithm of the number n, divide the natural log of n (
Log( n ) ) by the natural logarithm of 10 ( Log( 10 ) ).

LTrim$( ) function
Purpose
Trims space characters from the beginning of a string and returns the results.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

MapInfo MapX Developer Guide v4.5 643

Functions

Syntax
[ string= ]LTrim$( string_expr )

Part Description

string_expr A string expression

Remarks
The LTrim$( ) function removes any spaces from the beginning of the string_expr string, and
returns the resultant string.

Maximum( ) function
Purpose
This returns the larger of two numbers.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Maximum( num_expr , num_expr )

Part Description

num_expr is a numeric expression

num_expr is a numeric expression

Remarks
The Maximum( ) function returns the larger of two numeric expressions.

MBR( ) functio
Purpose
This returns a rectangle object, representing the minimum bounding rectangle of another
object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

644 MapInfo MapX Developer Guide v4.5

 Mid$( ) function

Syntax
[ Rectangle object= ]MBR( obj_expr )

Part Description

obj_expr an object expression

Remarks
The MBR( ) function calculates the minimum bounding rectangle (or MBR) which
encompasses the specified obj_expr object.

A minimum bounding rectangle is defined as being the smallest rectangle which is large
enough to encompass a particular object. In other words, the MBR of the United States
extends east to the eastern tip of Maine, south to the southern tip of Hawaii, west to the
western tip of Alaska, and north to the northern tip of Alaska.

The MBR of a point object has zero width and zero height.

Mid$( ) function
Purpose
This returns a string extracted from the middle of another string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Mid$( string_expr, position, length )

Part Description
string_expr A string expression
position A numeric expression, indicating a starting position in the
string
length A numeric expression, indicating the number of characters to
extract

MapInfo MapX Developer Guide v4.5 645

Functions

Remarks
The Mid$( ) function returns a substring copied from the specified string_expr string.

Mid$( ) copies length characters from the string_expr string, starting at the character
position indicated by position. A position value less than or equal to one tells MapX to copy
from the very beginning of the string_expr string.

If the string_expr string is not long enough, there may not be length characters to copy; thus,
depending on all of the parameters, the Mid$( ) may or may not return a string length
characters long. If the position parameter represents a number larger than the number of
characters in string_expr, Mid$( ) returns a null string. If the length parameter is zero, Mid$(
) returns a null string. If the length or position parameters are fractional, MapX rounds to
the nearest integer.

Minimum( ) function
Purpose
This returns the smaller of two numbers.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Minimum( num_expr , num_expr )

Part Description

num_expr is a numeric expression

num_expr is a numeric expression

Remarks
The Minimum( ) function returns the smaller of two numeric expressions.

646 MapInfo MapX Developer Guide v4.5

 ObjectLen( ) function

Month( ) function
Purpose
This returns the month component (1 - 12) of a date value.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ SmallInt value from 1 to 12, inclusive= ]Month( date_expr )

Remarks
The Month( ) function returns an integer, representing the month component (one to twelve)
of the specified date.

ObjectLen( ) function
Purpose
This returns the geographic length of a line or polyline object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]ObjectLen( expr , unit_name )

Part Description
expr An object expression
unit_name A string representing the name of a distance unit (e.g. "mi" for
miles)

Remarks
The ObjectLen( ) function returns the length of an object expression. Note that only line and
polyline objects have length values greater than zero; to measure the circumference of a
rectangle, ellipse, or region, use the Perimeter( ) function.

The ObjectLen( ) function returns a length measurement in the units specified by the
unit_name parameter; for example, to obtain a length in miles, specify "mi" as the
unit_name parameter. See the Set Distance Units statement for the list of valid unit names.

MapInfo MapX Developer Guide v4.5 647

Functions

ObjectType( ) functio
Purpose
Returns the type of the object (GeoObject.h).

• POINT= 1
• LINE = 2
• ARC = 3
• POLYLINE = 4
• REGION = 5
• TEXT= 6
• RECT= 7
• ROUNDRECT = 8
• ELLIPSE = 9
Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
ObjectType( object)

Part Description

object An Object expression.

Return Value
Integer

Perimeter( ) function
Purpose
This returns the perimeter of a graphical object.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

648 MapInfo MapX Developer Guide v4.5

 Proper$( ) function

Syntax
[ float= ]Perimeter( obj_expr , unit_name )

Part Description

obj_expr An object expression

unit_name A string representing the name of a distance unit (e.g. "km")

Remarks
The Perimeter( ) function calculates the perimeter of the obj_expr object. The Perimeter( )
function is defined for the following object types: ellipses, rectangles, rounded rectangles,
and polygons. Other types of objects have perimeter measurements of zero.

The Perimeter( ) function returns a length measurement in the units specified by the
unit_name parameter; for example, to obtain a length in miles, specify "mi" as the
unit_name parameter. See the Set Distance Units statement for the list of valid unit names.

The Perimeter( ) function returns approximate results when used on rounded rectangles.
MapX calculates the perimeter of a rounded rectangle as if the object were a conventional
rectangle.

Proper$( ) function
Purpose
This returns a mixed-case string, where only the first letter of each word is capitalized.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Proper$( string_expr )

Part Description

string_expr A string expression

Remarks
The Proper$( ) function first converts the entire string_expr string to lower case, and then
capitalizes only the first letter of each word in the string, thus producing a result string with
"proper" capitalization. This style of capitalization is appropriate for proper names.

MapInfo MapX Developer Guide v4.5 649

Functions

Right$( ) function
Purpose
This returns part or all of a string, beginning at the right end of the string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Right$( string_expr, num_expr )

Part Description

string_expr a string expression

num_expr a numeric expression

Remarks
The Right$( ) function returns a string which consists of the right most num_expr characters
of the string expression string_expr.

The num_expr parameter should be an integer value, zero or larger. If num_expr has a
fractional value, MapX rounds to the nearest integer. If num_expr is zero, Right$( ) returns a
null string. If num_expr is larger than the number of characters in the string_expr string,
Right$( ) returns a copy of the entire string_expr string.

Round( ) function
Purpose
This returns a number obtained by rounding off another number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Round( num_expr, round_to )

Part Description
num_expr A numeric expression.
round_to The number to which num_expr should be rounded off

650 MapInfo MapX Developer Guide v4.5

 RTrim$( ) function

Remarks
The Round( ) function returns a rounded-off version of the numeric num_expr expression.

The precision of the result depends on the round_to parameter. The Round( ) function
rounds the num_expr value to the nearest multiple of the round_to parameter. If round_to is
0.01, MapInfo rounds to the nearest hundredth; if round_to is 5, MapInfo rounds to the
nearest multiple of 5; etc.

RTrim$( ) function
Purpose
Trims space characters from the end of a string, and returns the results.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]RTrim$( string_expr )

Part Description

string_expr a string expression

Remarks
The RTrim$( ) function removes any spaces from the end of the string_expr string, and
returns the resultant string.

MapInfo MapX Developer Guide v4.5 651

Functions

Sgn( ) function
Purpose
This returns -1, 0, or 1, to indicate that a specified number is negative, zero, or positive
(respectively).

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Sgn( num_expr )

Part Description

num_expr A numeric expression

Remarks
The Sgn( ) function returns a value of -1 if the num_expr is less than zero, a value of 0 (zero)
if num_expr is equal to zero, or a value of 1 (one) if num_expr is greater than zero.

Sin( ) functio
Purpose
This returns the sine of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Sin( num_expr )

Part Description

num_expr A numeric expression

Remarks
The Sin( ) function returns the sine of the numeric num_expr value, which represents an
angle in radians. The result returned from Sin( ) will be between one and minus one.
To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

652 MapInfo MapX Developer Guide v4.5

 Sqr( ) function

Space$( ) functio
Purpose
This returns a string consisting only of spaces.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Space$( num_expr )

Part Description

num_expr A numeric expression

Remarks
The Space$( ) function returns a string num_expr characters long, consisting entirely of
space characters.

If the num_expr value is less than or equal to zero, the Space$( ) function returns a null
string.

Sqr( ) function
Purpose
This returns the square root of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Sqr( num_expr )

Part Description

num_expr A numeric expression

MapInfo MapX Developer Guide v4.5 653

Functions

Remarks
The Sqr( ) function returns the square root of the numeric expression specified by num_expr.
Since the square root operation is undefined for negative real numbers, num_expr should
represent a value greater than or equal to zero.

Taking the square root of a number is equivalent to raising that number to the power 0.5.
Accordingly, the expression Sqr(n) is equivalent to the expression n ^ 0.5; the Sqr( )
function, however, provides the fastest calculation of square roots.

StringCompare( ) function
Purpose
Performs case-sensitive string comparisons.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
StringCompare( string1, string2 )

string1 and string2 are String expressions

Return Value
SmallInt: -1 if first string precedes second; 1 if first string follows second; zero if strings are
equal

Remarks
The StringCompare( ) function performs case-sensitive string comparisons. MapX string
comparisons which use the "=" operator are case-insensitive. Thus, a comparison expression
such as the following:

If "ABC" = "abc" Then

evaluates as TRUE, because string comparisons are case-insensitive.

654 MapInfo MapX Developer Guide v4.5

 StringCompareIntl( ) function

The StringCompare( ) function performs a case-sensitive string comparison and returns an

indication of how the strings compare.

Return value: When:

-1 first string precedes the second string, alphabetically

0 the two strings are equal
1 first string follows the second string, alphabetically

StringCompareIntl( ) function
Purpose
Performs language-sensitive string comparisons.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
StringCompareIntl( string1 , string2 )
string1 and string2 are the string expressions being compared

Return Value
SmallInt: -1 if first string precedes second; 1 if first string follows second; zero if strings are
equal.

Remarks
The StringCompareIntl( ) function performs language-sensitive string comparisons. Call
this function if you need to determine the alphabetical order of two strings, and the strings
contain characters that are outside the ordinary U.S. character set (e.g. umlauts).

MapInfo MapX Developer Guide v4.5 655

Functions

The comparison uses whatever language settings are in use on the user's computer. For
example, a Windows user can control language settings through the Control Panel.

Return value: When:

-1 first string precedes the second string, using the current language
setting
0 the two strings are equal
1 first string follows the second string, using the current language
setting

StringToDate( ) function
Purpose
The StringToDate( ) function returns a Date value, given a string that represents a date.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
StringToDate ( datestring )
datestring is a String expression representing a date, such as "10/17/96"

Return Value
Date

Remarks
MapX interprets the date string according to the date-formatting options that are set up on a
user's computer. Computers within the United States are usually configured to format dates
as Month/Day/Year, but computers in other countries are often configured with a different
order (e.g. Day/Month/Year) or a different separator character (e.g. a period instead of a /).
The sequence of m/d/y in the string needs to match the Windows system's short-date-
format setting. If the setting is MM/DD/YY, then the example above of "51/01/01" will be
invalid because month "51" does not exist.

To force the StringToDate( ) function to apply U.S. formatting conventions, use the Set
Format statement.

Note: When U.S. formatting conventions apply, the datestring parameter must use the

656 MapInfo MapX Developer Guide v4.5

 Str$( ) function

forward-slash character (/) to separate the day, month, and year components of
the date.
The datestring argument must indicate the month (1 - 12, represented as one or two digits)
and the day of the month (1 - 31, represented as one or two digits).

You may specify the year as a four-digit number, or you may omit the year entirely. If you do
not specify a year, MapX uses the current year.

Note: MapInfo Corporation recommends using a 4-digit format for years in any date
variable or date string. @-digit years return unexpected results.
If you're using a MapX variable object with a date type, and you DO supply 2-digit year
representation, then the development environment (not MapX) will determine the century
StringToDate takes only a string variable as a parameter. It does not take a MapX date type
variable.

Str$( ) function
Purpose
This returns a string representing an expression (e.g. a printout of a number).

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]Str$( expression )

Part Description

expression A numeric, Date, Pen, Brush, Symbol, Font, Logical or Object

expression

Remarks
The Str$( ) function returns a string which represents the value of the specified expression.

If the expression is a negative number, the first character in the returned string is the minus
sign (-). If the expression is a positive number, the first character in the string is a space.

Depending on the number of digits of accuracy in the expression you specify, and
depending on how many of the digits are to the left of the decimal point, the Str$( ) function
may return a string which represents a rounded value. If you need to control the number of
digits of accuracy displayed in a string, use the Format$( ) function.

MapInfo MapX Developer Guide v4.5 657

Functions

If the expression is an Object expression, the Str$( ) function returns a string, indicating the
object type: Arc, Ellipse, Frame, Line, Point, Polyline, Rectangle, Region, Rounded
Rectangle, or Text.

If the expression is an Object expression of the form tablename.obj and if the current row
from that table has no graphic object attached, Str$( ) returns a null string. Note: Passing an
uninitialized Object variable to the Str$( ) function generates an error.

If the expression is a Date, the output from Str$( ) depends on how the user’s computer is
configured. If the expression is a number, the Str$( ) function uses a period as the decimal
separator, even if the user’s computer is set up to use another character as decimal
separator. The Str$( ) function never includes thousands separators in the return string. To
produce a string that uses the thousands separator and decimal separator specified by the
user, use the FormatNumber$( ) function.

Tan( ) function
Purpose
This returns the tangent of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Tan( num_expr )

Part Description
num_expr A numeric expression

Remarks
The Tan( ) function returns the tangent of the numeric num_expr value, which represents an
angle in radians.

To convert a degree value to radians, multiply that value by pi/ISO. To convert a radian
value into degrees, multiply that value by ISO/pi.

658 MapInfo MapX Developer Guide v4.5

 Val( ) function

UCase$( ) function
Purpose
This returns a string, converted to upper-case.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ string= ]UCase$( string_expr )

Part Description

string_expr A string expression

Remarks
The UCase$( ) function returns the string which is the upper-case equivalent of the string
expression string_expr.

Conversion from lower to upper case only affects alphabetic characters (A through Z);
numeric digits and punctuation marks are not affected. Thus, the function call:

UCase$("A#12a")

returns the string value "A#12A".

Val( ) function
Purpose
This returns the numeric value represented by a string.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ float= ]Val( string_expr )

Part Description

string_expr A string expression

MapInfo MapX Developer Guide v4.5 659

Functions

Remarks
The Val( ) function returns a number based on the string_expr string expression. Val( )
ignores any white spaces (tabs, spaces, line feeds) at the start of the string_expr string, then
tries to interpret the first character(s) as a numeric value. The Val( ) function then stops
processing the string as soon as it finds a character that is not part of the number.
If the first non-white-space character in the string is not a period, a digit, a minus sign, or an
ampersand character (&), Val( ) returns zero. (The ampersand is used in hexadecimal
notation; see example below.)

Note: If the string includes a decimal separator, it must be a period, regardless of

whether the user’s computer is set up to use some other character as the decimal
separator. Also, the string cannot contain thousands separators. To remove
thousands separators from a numeric string, call the DeformatNumber$( )
function.

Weekday( ) function
Purpose
This returns an integer from 1 to 7, indicating the weekday of a specified date.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ SmallInt value from 1 to 7, inclusive; 1 represents Sunday= ]Weekday( date_expr )

Part Description
date_expr A date expression

Remarks
The Weekday( ) function returns an integer representing the day-of-the-week component
(one to seven) of the specified date.

The Weekday( ) function only works for dates on or after January 1, in the year 100. If
date_expr specifies a date before the year 100, the Weekday( ) function returns a value of
zero.

660 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Year( ) functio
Purpose
This returns the year component of a date value.

Note: Functions in MapX are used to create expressions and are passed as arguments.
They can ONLY be passed to the Layer.Search and the DataSet.AddField
methods.

Syntax
[ SmallInt value from 1 to 7, inclusive; 1 represents Sunday= ]Year( date_expr )

Part Description

date_expr A date expression

Remarks
The Year( ) function returns an integer representing the year component of the specified
date. For example, if the specified date is 12/17/93, the Year( ) function returns the value
1993.

MapInfo MapX Developer Guide v4.5 661

Functions

662 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Geoset Keys

Geosets are files (ending in .GST) that contain information about a set of layers, and can b
loaded at one time. A geoset is loaded by specifying one at design time (as a property), or
using the AddGeosetLayers method of the Layers object. A geoset file is an ASCII file
containing strings. These strings consist of keys and values. The keys correspond to
properties in MapX – properties for the main Map object, as well as for Layer objects.

Keys are hierarchical in nature, and are specified as quoted strings. Key values are also
quoted values – even number are quoted. The following is a sample showing some keys
and values:

Sample Geoset
!GEOSET
!VERSION 100
begin_metadata
"\GEOSET" = ""
"\GEOSET\NAME" = "SAMPLE GEOSET"
"\GEOSET\PROJECTION" = "3,62,7,-96,23,20,60,0,0"
"\GEOSET\CENTER" = "-54851.35483414936,1844196.997419479"
"\GEOSET\MBR" = ""
"\GEOSET\MBR\LOWERLEFT" = "-3093309.705881681,-450646.671927353"
"\GEOSET\MBR\UPPERRIGHT" = "2983606.996213382,4139040.666766311"
"\GEOSET\ZOOMLEVEL" = "4019.82"
"\GEOSET\AUTOLAYER" = "FALSE"
"\GEOSET\MAPUNIT" = "0"
"\GEOSET\ROTATION" = "0"
"\TABLE" = ""
"\TABLE\1" = ""
"\TABLE\1\FILE" = "usa_caps.tab"
"\TABLE\1\DESCRIPTION" = "US Capitals"
"\TABLE\1\ISVISIBLE" = "TRUE"
"\TABLE\1\AUTOLABEL" = "FALSE"
"\TABLE\1\DRAWLABELSAFTER" = "FALSE"

MapInfo MapX Developer Guide v4.5 663

Geoset Keys

"\TABLE\1\SHOWLINEDIRECTION" = "FALSE"
"\TABLE\1\SHOWNODES" = "FALSE"
"\TABLE\1\SHOWCENTROIDS" = "FALSE"
"\TABLE\1\EDITABLE" = "FALSE"
"\TABLE\1\SELECTABLE" = "TRUE"
"\TABLE\1\REGISTERINGEOODICT" = "TRUE"
"\TABLE\1\DISPLAY" = ""
"\TABLE\1\DISPLAY\BRUSH" = ""
"\TABLE\1\DISPLAY\BRUSH\Pattern" = "2"
"\TABLE\1\DISPLAY\BRUSH\Forecolor" = "16777215"
"\TABLE\1\DISPLAY\BRUSH\Backcolor" = "16777215"
"\TABLE\1\DISPLAY\BRUSH\Transparent" = "FALSE"
"\TABLE\1\DISPLAY\PEN" = ""
"\TABLE\1\DISPLAY\PEN\LineWidth" = "1"
"\TABLE\1\DISPLAY\PEN\LineStyle" = "1"
"\TABLE\1\DISPLAY\PEN\Pattern" = "2"
"\TABLE\1\DISPLAY\PEN\Color" = "0"
"\TABLE\1\DISPLAY\LINEPEN" = ""
"\TABLE\1\DISPLAY\LINEPEN\LineWidth" = "1"
"\TABLE\1\DISPLAY\LINEPEN\LineStyle" = "1"
"\TABLE\1\DISPLAY\LINEPEN\Pattern" = "2"
"\TABLE\1\DISPLAY\LINEPEN\Color" = "0"
"\TABLE\1\DISPLAY\FONT" = ""
"\TABLE\1\DISPLAY\FONT\Style" = "3"
"\TABLE\1\DISPLAY\FONT\ExtStyle" = "1"
"\TABLE\1\DISPLAY\FONT\Description" = "Arial"
"\TABLE\1\DISPLAY\FONT\Size" = "36"
"\TABLE\1\DISPLAY\FONT\Forecolor" = "0"
"\TABLE\1\DISPLAY\FONT\Backcolor" = "16777215"
"\TABLE\1\DISPLAY\FONT\Opaque" = "FALSE"
"\TABLE\1\DISPLAY\SYMBOL" = ""
"\TABLE\1\DISPLAY\SYMBOL\Type" = "1"
"\TABLE\1\DISPLAY\SYMBOL\Code" = "35"
"\TABLE\1\DISPLAY\SYMBOL\Color" = "255"

664 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

"\TABLE\1\DISPLAY\SYMBOL\Pointsize" = "14"
"\TABLE\1\DISPLAY\SYMBOL\Font" = ""
"\TABLE\1\DISPLAY\SYMBOL\Font\Style" = "0"
"\TABLE\1\DISPLAY\SYMBOL\Font\ExtStyle" = "0"
"\TABLE\1\DISPLAY\SYMBOL\Font\Description" = "Map Symbols"
"\TABLE\1\DISPLAY\SYMBOL\Font\Size" = "14"
"\TABLE\1\DISPLAY\SYMBOL\Font\Forecolor" = "255"
"\TABLE\1\DISPLAY\SYMBOL\Font\Backcolor" = "16777215"
"\TABLE\1\DISPLAY\SYMBOL\Font\Opaque" = "FALSE"
"\TABLE\1\DISPLAY\SYMBOL\Font\Rotation" = "0"
"\TABLE\1\LABEL" = ""
"\TABLE\1\LABEL\FONT" = ""
"\TABLE\1\LABEL\FONT\Style" = "0"
"\TABLE\1\LABEL\FONT\ExtStyle" = "0"
"\TABLE\1\LABEL\FONT\Description" = "Arial"
"\TABLE\1\LABEL\FONT\Size" = "9"
"\TABLE\1\LABEL\FONT\Forecolor" = "0"
"\TABLE\1\LABEL\FONT\Backcolor" = "16777215"
"\TABLE\1\LABEL\FONT\Opaque" = "FALSE"
"\TABLE\1\LABEL\DUPLICATE" = "TRUE"
"\TABLE\1\LABEL\PARALLEL" = "TRUE"
"\TABLE\1\LABEL\OVERLAP" = "FALSE"
"\TABLE\1\LABEL\PARTIALSEGMENTS" = "FALSE"
"\TABLE\1\LABEL\LINETYPE" = "2"
"\TABLE\1\LABEL\OFFSET" = "2"
"\TABLE\1\LABEL\POSITION" = "5"
end_metadata

The first eleven lines show keys beginning with the word 'GEOSET' – these are keys that set
properties for the entire map, or properties for the Map object. Notice that some keys, like
GEOSET\MBR are multi-level – there is a LOWERLEFT and an UPPERRIGHT.

Then next thirteen lines show keys setting properties for one layer – usa_caps. The keys
begin with 'TABLE'. The next word is any keyword to refer to the set of properties for a
specific layer – in this case they are the same word as the table file name. Then follow the
hierarchical key values for the specified layer.

MapInfo MapX Developer Guide v4.5 665

Geoset Keys

Supported Keys
Below is the list of keys that are supported in a geoset file:

\GEOSET\
NAME 'Friendly' name of geoset
PROJECTION Projection clause
CENTER Number, Number – Long/Lat of the center of the map
\MBR\LOWERLEFT Number,Number - Long/Lat of lower left corner
\MBR\UPPERRIGHT Number,Number - Long/Lat of upper right corner
ZOOMLEVEL Number - Zoom level of the map
AUTOLAYER TRUE or FALSE (1 or 0) - order layers automatically
MAPUNIT Number - corresponds to Map.MapUnit. Whenever the
geoset is loaded into the map control, if there are no
layers already loaded, the MapUnit will be set to the
geoset's MapUnit. However,if there are layers already
loaded, MapX will load the geoset and use the current
map unit.
ROTATION Number - Rotation angle of the map. Corresponds to
Map.Rotation

\TABLE\<number>\

FILE String – location of .TAB fil

DESCRIPTION String – Table description
ISVISIBLE TRUE or FALSE (1 or 0) – whether layer is visible
AUTOLABEL TRUE or FALSE (1 or 0) – – whether layer is autolabeled
DRAWLABELSAFTER TRUE or FALSE (1 or 0) – whether to draw labels after
the layer is drawn
SHOWLINEDIRECTION TRUE or FALSE (1 or 0) – Corresponds to
Layer.ShowLineDirection
SHOWNODES TRUE or FALSE (1 or 0) – Corresponds to
Layer.ShowNodes
SHOWCENTROIDS TRUE or FALSE (1 or 0) – Corresponds to
Layer.ShowCentroids
EDITABLE TRUE or FALSE (1 or 0) – Corresponds to Layer.Editable

666 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

\TABLE\<number>\

SELECTABLE TRUE or FALSE (1 or 0) – Corresponds to

Layer.Selectable
REGISTERINGEODICT TRUE or FALSE (1 or 0) – whether to register the geoset
in the geodictionary
ZOOM\MIN Number – minimum zoom value to display layer
(Layer.ZoomMin)
ZOOM\MAX Number – maximum zoom value to display layer
(Layer.ZoomMax)

DISPLAY\BRUSH\
PATTERN Number – corresponds to Style.RegionPattern
FORECOLOR Number – corresponds to Style.RegionColor
BACKCOLOR Number – corresponds to Style.RegionBackColor
TRANSPARENT TRUE or FALSE – corresponds to
Style.RegionTransparent

DISPLAY\PEN\

LINEWIDTH Number – corresponds to Style.RegionBorderWidth

LINESTYLE Number – corresponds to Style.RegionBorderStyle
COLOR Number – corresponds to Style.RegionBorderColor

DISPLAY\LINEPEN\

LINEWIDTH Number – corresponds to Style.LineWidth

LINESTYLE Number – corresponds to Style.LineStyle
COLOR Number – corresponds to Style.LineColor

DISPLAY\FONT\
STYLE Number – Bit Mask (BOLD 0x01, ITALIC 0x02, UNDER
0x04, STRIKEOUT 0x08, OUTLINE 0x10, SHADOW
0x20, INVERSE 0x40, BLINK 0x80)

MapInfo MapX Developer Guide v4.5 667

Geoset Keys

DISPLAY\FONT\

EXTSTYLE Number – Bit Mask (HALO 0x01, ALLCAPS 0x02,

DBLSPACE 0x04)
DESCRIPTION String – font name
SIZE Number – font size in points
FORECOLOR Number – Corresponds to Style.TextFontColor
BACKCOLOR Number – Corresponds to Style.TextFontBackColor
OPAQUE TRUE or FALSE – Corresponds to Style.TextFontOpaque

DISPLAY\SYMBOL\
TYPE Number – Corresponds to Style.SymbolType
CODE Number – Corresponds to Style.SymbolCharacter
COLOR Number – Corresponds to Style.SymbolFontColor
POINTSIZE Number – size of symbol in points

TrueType Font Symbol Keys

FONT This is the font of the symbol. This key is present if the
symbol type is miSymbolTypeTrueTypeFont. It has the
same sub-keys as DISPLAY\FONT
FONT\ROTATION The rotation angle of the font symbol. Corresponds to
Style.SymbolFontRotation.

BitmapSymbol Keys

BITMAP\NAME String – Name of the bitmap symbol. Corresponds to

Style.SymbolBitmapName.
BITMAP\OVERRIDECOLOR TRUE or FALSE – Whether to apply color to the
symbol. Corresponds to
Style.SymbolBitmapOverrideColor
BITMAP\TRANSPARENT TRUE or FALSE – Whether the bitmap is transparent.
Corresponds to Style.SymbolBitmapTransparent.

LABEL\

ZOOM\MIN Number – minimum zoom value to label layer

668 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

LABEL\

ZOOM\MAX Number – maximum zoom value to label layer

FONT This is the label font. It has the same sub-keys as
DISPLAY\FONT above
DUPLICATE TRUE or FALSE – permit duplicate labels
PARALLEL TRUE or FALSE – Corresponds to
LabelProperties.Parallel
OVERLAP TRUE or FALSE – Corresponds to
LabelProperties.Overlap
PARTIALSEGMENTS TRUE or FALSE – Corresponds to
LabelProperties.PartialSegments
MAXLABELS Number – Corresponds to LabelProperties.LabelMax
LINETYPE Number – Corresponds to LabelProperties.LineType
OFFSET Number – Corresponds to LabelProperties.Offset
POSITION Number – Corresponds to LabelProperties.Position

MapInfo MapX Developer Guide v4.5 669

Geoset Keys

670 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

OLE_COLOR Values

An OLE_COLOR value is a BGR (Blue, Green, Red) value. To determine the BGR value,
specify blue, green, or red (each of which has a value from 0 – 255) in the following formula:

BGR value = (blue * 65536) + (green * 256) + red

Note: If you have used the MapBasic programming language, please note that
MapBasic uses the following formula to calculate the RGB values:
RGB value = (red * 65536) + (green * 256) + blue
If you are working with RGB color values (e.g. values used with a MapBasic application),
you will need to convert the colors to BGR before you can use those color values in MapX.

See Also
ColorConstants

MapInfo MapX Developer Guide v4.5 671

OLE_COLOR Values

672 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

IDispatch Table

This is a table for the IDispatches of MapX.

Method/Property IDispatch
AffineTransform.A 2
AffineTransform.B 3
AffineTransform.C 4
AffineTransform.D 5
AffineTransform.E 6
AffineTransform.F 7
AffineTransform.Set 8
AffineTransform.Units 1
Annotation.Graphic 2
Annotation.Type 1
Annotations.ActiveAnnotation 8
Annotations.AddSymbol 3
Annotations.AddText 6
Annotations.Count 2
Annotations.Editable 1
Annotations.Item 4
Annotations.Remove 5
Annotations.RemoveAll 7
BindLayer.CoordSys 6
BindLayer.Filespec 7
BindLayer.KeyLength 8
BindLayer.LayerName 1
BindLayer.LayerType 4
BindLayer.RefColumn1 2
BindLayer.RefColumn2 3

MapInfo MapX Developer Guide v4.5 673

IDispatch Table

Method/Property IDispatch

BindLayer.ReferenceLayer 5
BindLayer.ReferenceLayerField 9
BitmapSymbol.Name 1
BitmapSymbols.Count 1
BitmapSymbols.Item 2
BitmapSymbols.Refresh 3
BitmapSymbols.Unload 4
CoordSys.AffineTransform 14
CoordSys.Azimuth 9
CoordSys.Bounds 4
CoordSys.Clone 17
CoordSys.Datum 2
CoordSys.FalseEasting 11
CoordSys.FalseNorthing 12
CoordSys.OriginLatitude 6
CoordSys.OriginLongitude 5
CoordSys.PickCoordSys 16
CoordSys.Range 13
CoordSys.ScaleFactor 10
CoordSys.Set 15
CoordSys.StandardParallelOne 7
CoordSys.StandardParallelTwo 8
CoordSys.Type 1
CoordSys.Units 3
DataSet.AddField 14
DataSet.Fields 3
DataSet.GeoField 5
DataSet.Layer 7
DataSet.Name 1

674 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

DataSet.ReadOnly 12
DataSet.Refresh 8
DataSet.RowCount 2
DataSet.RowValues 13
DataSet.SecondaryGeoField 6
DataSet.SourceRows 10
DataSet.Themes 4
DataSet.Type 11
DataSet.Value 9
DataSets.Add 2
DataSets.BuildSourceRows 7
DataSets.Count 1
DataSets.Item 3
DataSets.Remove 4
DataSets.RemoveAll 6
DataSets.Restore 5
Datum.Eccentricity 13
Datum.Ellipsoid 1
Datum.Flattening 12
Datum.PrimeMeridian 9
Datum.RotateX 5
Datum.RotateY 6
Datum.RotateZ 7
Datum.ScaleAdjust 8
Datum.SemiMajorAxis 10
Datum.SemiMinorAxis 11
Datum.Set 14
Datum.SetFromList 15
Datum.ShiftX 2

MapInfo MapX Developer Guide v4.5 675

IDispatch Table

Method/Property IDispatch

Datum.ShiftY 3
Datum.ShiftZ 4
Feature.Area 10
Feature.Attach 20
Feature.Bounds 7
Feature.Caption 8
Feature.CenterX 4
Feature.CenterY 5
Feature.Clone 21
Feature.FeatureID 1
Feature.FeatureKey 23
Feature.KeyValue 17
Feature.LabelPoint 13
Feature.Layer 11
Feature.Length 3
Feature.Name 16
Feature.Nodes 22
Feature.Offset 19
Feature.Parts 9
Feature.Perimeter 14
Feature.Point 12
Feature.Smooth 15
Feature.Style 6
Feature.Type 2
Feature.Update 18
FeatureFactory.BufferFeatures 1
FeatureFactory.CombineFeatures 2
FeatureFactory.CreateArc 9
FeatureFactory.CreateCircularRegion 11

676 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

FeatureFactory.CreateEllipticalRegion 10
FeatureFactory.CreateLine 7
FeatureFactory.CreateRegion 6
FeatureFactory.CreateSymbol 5
FeatureFactory.CreateText 8
FeatureFactory.EraseFeature 4
FeatureFactory.IntersectFeatures 3
FeatureFactory.IntersectionPoints 13
FeatureFactory.IntersectionTest 12
Features.Add 4
Features.AddByID 9
Features.Bounds 8
Features.Clone 3
Features.Common 5
Features.Count 1
Features.Item 2
Features.Remove 6
Features.RemoveByID 10
Features.Replace 7
Field.AggregationFunction 3
Field.Name 2
Field.Type 1
Fields.Add 2
Fields.Count 1
Fields.Item 3
Fields.Remove 4
Fields.RemoveAll 5
Find.Abbreviations 2
Find.CloseMatchMax 10

MapInfo MapX Developer Guide v4.5 677

IDispatch Table

Method/Property IDispatch

Find.ClosestAddr 3
Find.FindDataSet 7
Find.FindField 5
Find.OtherBoundary 4
Find.RefineDataSet 8
Find.RefineField 6
Find.RefineLayer 1
Find.Search 9
Find.SearchEx 11
FindFeature.Area 65546
FindFeature.Bounds 65543
FindFeature.Caption 65544
FindFeature.CenterX 65540
FindFeature.CenterY 65541
FindFeature.FeatureID 65537
FindFeature.FindRC 1
FindFeature.KeyValue 65553
FindFeature.LabelPoint 65549
FindFeature.Layer 65547
FindFeature.Length 65539
FindFeature.Name 65552
FindFeature.Offset 65555
FindFeature.Parts 65545
FindFeature.Perimeter 65550
FindFeature.Point 65548
FindFeature.Smooth 65551
FindFeature.Style 65542
FindFeature.Type 65538
FindFeature.Update 65554

678 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

FindMatch.FeatureID 1
FindMatch.FeatureKey 4
FindMatch.Name 2
FindMatch.Score 3
FindMatches.Count 1
FindMatches.Item 2
FindResult.AddressOutOfRange 3
FindResult.ExactMatch 1
FindResult.FindRC 7
FindResult.IntersectionNotFound 4
FindResult.MatchedFeature 9
FindResult.Matches 8
FindResult.MultipleMatches 5
FindResult.RefineRegion 6
FindResult.Substitute 2
Geoset.Centroid 1
Geoset.PathName 2
Geoset.UserName 3
Geosets.Count 1
Geosets.Item 2
Graphic.Caption 1
Graphic.Position 4
Graphic.Style 5
Graphic.X 2
Graphic.Y 3
IndividualValueCategories.AllOthersCategory 3
IndividualValueCategories.Count 1
IndividualValueCategories.Item 2
IndividualValueCategory.NumItems 2

MapInfo MapX Developer Guide v4.5 679

IDispatch Table

Method/Property IDispatch

IndividualValueCategory.Style 1
IndividualValueCategory.Value 3
LabelProperties.DataField 13
LabelProperties.DataSet 9
LabelProperties.Duplicate 10
LabelProperties.LabelMax 12
LabelProperties.LabelZoom 3
LabelProperties.LabelZoomMax 5
LabelProperties.LabelZoomMin 4
LabelProperties.LineType 6
LabelProperties.Offset 7
LabelProperties.Overlap 11
LabelProperties.Parallel 8
LabelProperties.PartialSegments 15
LabelProperties.Position 14
LabelProperties.Style 1
LabelProperties.Visible 2
Layer.AddFeature 21
Layer.AllFeatures 26
Layer.AutoLabel 6
Layer.BeginAccess 41
Layer.Bounds 32
Layer.ClearCustomLabels 19
Layer.CoordSys 17
Layer.DataSets 39
Layer.DeleteFeature 22
Layer.DrawLabelsAfter 37
Layer.DrillDownAddFeatures 31
Layer.DrillDownRemoveFeatures 30

680 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Layer.DrilldownReset 34
Layer.Editable 46
Layer.EndAccess 42
Layer.FeatureIDFromFeatureName 38
Layer.FeatureKeyFromFeatureName 48
Layer.FileSpec 4
Layer.Find 14
Layer.GetDrilldownFeaturesByID 33
Layer.GetFeatureByID 35
Layer.GetFeatureByKey 47
Layer.Invalidate 23
Layer.KeyField 16
Layer.LabelAtPoint 18
Layer.LabelProperties 5
Layer.Name 1
Layer.NoFeatures 27
Layer.OverrideStyle 8
Layer.PredominantFeatureType 13
Layer.Refresh 36
Layer.Search 40
Layer.SearchAtPoint 29
Layer.SearchWithinDistance 24
Layer.SearchWithinFeature 28
Layer.SearchWithinRectangle 25
Layer.Selectable 3
Layer.Selection 12
Layer.ShowCentroids 44
Layer.ShowLineDirection 45
Layer.ShowNodes 43

MapInfo MapX Developer Guide v4.5 681

IDispatch Table

Method/Property IDispatch

Layer.Style 9
Layer.Type 15
Layer.UpdateFeature 20
Layer.Visible 2
Layer.ZoomLayer 7
Layer.ZoomMax 11
Layer.ZoomMin 10
LayerInfo.AddParameter 2
LayerInfo.Type 1
Layers.Add 4
Layers.AddGeoSetLayers 5
Layers.AddServerLayer 13
Layers.AddUserDrawLayer 8
Layers.AnimationLayer 9
Layers.Bounds 12
Layers.ClearSelection 2
Layers.Count 1
Layers.CreateLayer 10
Layers.InsertionLayer 15
Layers.Item 6
Layers.LayersDlg 11
Layers.Move 3
Layers.Remove 7
Layers.RemoveAll 14
Legend.BodyTextStyle 6
Legend.Compact 1
Legend.CompactTitle 11
Legend.CompactTitleStyle 5
Legend.CurrencyFormat 8

682 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Legend.ExportLegend 18
Legend.Height 15
Legend.Left 12
Legend.LegendDlg 16
Legend.LegendTexts 7
Legend.PaperHeight 21
Legend.PaperWidth 22
Legend.PrintLegend 20
Legend.ShowCount 19
Legend.ShowEmptyRanges 17
Legend.SubTitle 10
Legend.SubTitleStyle 4
Legend.Title 9
Legend.TitleStyle 3
Legend.Top 13
Legend.Visible 2
Legend.Width 14
LegendText.Text 1
LegendText.Visible 2
LegendTexts.AllOthersText 4
LegendTexts.AutoGenerate 1
LegendTexts.Count 2
LegendTexts.Item 3
Map.AboutBox -552
Map.Annotations 3
Map.AreaUnit 28
Map.AutoRedraw 6
Map.BackColor -501
Map.Bounds 29

MapInfo MapX Developer Guide v4.5 683

IDispatch Table

Method/Property IDispatch

Map.CenterX 8
Map.CenterY 9
Map.ClipLine 44
Map.ClipLineV 45
Map.ConvertCoord 34
Map.ConvertCoord 41
Map.CreateCustomTool 36
Map.CurrentTool 20
Map.DataSet 4
Map.DataSetGeoField 1
Map.DataSetTheme 19
Map.DataSets 22
Map.DefaultConversionResolution 50
Map.DefaultStyle 17
Map.DisplayCoordSys 30
Map.Distance 37
Map.ExportMap 39
Map.ExportSelection 32
Map.FeatureFactory 49
Map.GeoDictionary 18
Map.GeoSet 10
Map.GeoSetWidth 11
Map.Geosets 27
Map.hWnd -515
Map.InfotipPopupDelay 61
Map.InfotipSupport 63
Map.IsPointVisible 43
Map.Layers 5
Map.MapPaperHeight 12

684 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Map.MapPaperWidth 13
Map.MapScreenHeight 54
Map.MapScreenWidth 53
Map.MapUnit 25
Map.MatchNumericFields 52
Map.MatchThreshold 57
Map.MaxSearchTime 14
Map.MouseIcon 62
Map.MousePointer 21
Map.MousewheelSupport 51
Map.NumericCoordSys 31
Map.Pan 64
Map.PanAnimationLayer 60
Map.PaperUnit 15
Map.PreferCompactLegends 16
Map.PrintMap 38
Map.PropertyPage 40
Map.RedrawInterval 55
Map.Refresh -550
Map.Rotation 26
Map.SaveMapAsGeoset 47
Map.SearchPath 56
Map.SelectionStyle 33
Map.SetSize 42
Map.Title 23
Map.TitleText 24
Map.Version 2
Map.WaitCursorEnabled 58
Map.Zoom 7

MapInfo MapX Developer Guide v4.5 685

IDispatch Table

Method/Property IDispatch

Map.ZoomTo 35
MultivarCategories.Count 1
MultivarCategories.Item 2
MultivarCategory.Style 1
NotesQueryInfo.BeginDate 4
NotesQueryInfo.Database 2
NotesQueryInfo.DefaultNumericValue 8
NotesQueryInfo.DefaultStringValue 7
NotesQueryInfo.EndDate 5
NotesQueryInfo.FullTextSearch 6
NotesQueryInfo.MaxNumDocs 9
NotesQueryInfo.Query 3
NotesQueryInfo.Server 1
NotesViewInfo.Database 2
NotesViewInfo.Server 1
NotesViewInfo.View 3
ODBCQueryInfo.ConnectString 3
ODBCQueryInfo.DataSource 1
ODBCQueryInfo.SqlQuery 2
Parts.Add 4
Parts.Count 1
Parts.Item 2
Parts.Remove 3
Parts.RemoveAll 5
Point.Offset 4
Point.Set 3
Point.X 1
Point.Y 2
Points.Add 4

686 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Points.AddXY 5
Points.Count 1
Points.Item 2
Points.Remove 3
Points.RemoveAll 6
RangeCategories.AllOthersCategory 3
RangeCategories.Count 1
RangeCategories.Item 2
RangeCategory.Max 2
RangeCategory.Min 1
RangeCategory.NumItems 3
RangeCategory.Style 4
Rectangle.Height 5
Rectangle.Offset 8
Rectangle.Set 7
Rectangle.Width 6
Rectangle.XMax 3
Rectangle.XMin 1
Rectangle.YMax 4
Rectangle.YMin 2
ResolveObject.SourceMatch 2
ResolveObject.TableMatch 3
ResolveObject.TableName 1
ResolveObjects.Add 4
ResolveObjects.Count 1
ResolveObjects.Item 2
ResolveObjects.Remove 3
ResolveObjects.RemoveAll 5
RowValue.DataSet 2

MapInfo MapX Developer Guide v4.5 687

IDispatch Table

Method/Property IDispatch

RowValue.Field 3
RowValue.ReadOnly 1
RowValue.Value 4
RowValues.Add 4
RowValues.Clone 6
RowValues.Count 1
RowValues.Item 2
RowValues.ReadOnly 7
RowValues.Remove 3
RowValues.RemoveAll 5
Selection.Add 65540
Selection.ClearSelection 2
Selection.Clone 65539
Selection.Common 65541
Selection.Count 65537
Selection.Item 65538
Selection.Remove 65542
Selection.Replace 65543
Selection.SelectAll 6
Selection.SelectByID 7
Selection.SelectByPoint 3
Selection.SelectByRadius 4
Selection.SelectByRectangle 5
Selection.SelectByRegion 1
SourceRow.Row 1
SourceRows.Count 1
SourceRows.Item 2
Style.Clone 41
Style.DrawLineSample 32

688 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Style.DrawRegionSample 31
Style.DrawSymbolSample 30
Style.DrawTextSample 29
Style.ExportLineSample 51
Style.ExportRegionSample 50
Style.ExportSymbolSample 49
Style.ExportTextSample 52
Style.LineColor 2
Style.LineInterleaved 44
Style.LineStyle 3
Style.LineStyleCount 42
Style.LineSupportsInterleave 47
Style.LineWidth 4
Style.LineWidthUnit 45
Style.MaxVectorSymbolCharacter 56
Style.MinVectorSymbolCharacter 55
Style.PickLine 26
Style.PickRegion 25
Style.PickSymbol 28
Style.PickText 27
Style.RegionBackColor 7
Style.RegionBorderColor 9
Style.RegionBorderStyle 8
Style.RegionBorderWidth 10
Style.RegionBorderWidthUnit 46
Style.RegionColor 5
Style.RegionPattern 6
Style.RegionTransparent 43
Style.SupportsBitmapSymbols 39

MapInfo MapX Developer Guide v4.5 689

IDispatch Table

Method/Property IDispatch

Style.SymbolBitmapColor 35
Style.SymbolBitmapName 36
Style.SymbolBitmapOverrideColor 34
Style.SymbolBitmapSize 38
Style.SymbolBitmapTransparent 33
Style.SymbolCharacter 1
Style.SymbolFont 12
Style.SymbolFontBackColor 16
Style.SymbolFontColor 15
Style.SymbolFontHalo 19
Style.SymbolFontOpaque 17
Style.SymbolFontRotation 40
Style.SymbolFontShadow 20
Style.SymbolType 37
Style.SymbolVectorColor 53
Style.SymbolVectorSize 54
Style.TextFont 11
Style.TextFontAllCaps 23
Style.TextFontBackColor 14
Style.TextFontColor 13
Style.TextFontDblSpace 24
Style.TextFontHalo 21
Style.TextFontOpaque 18
Style.TextFontRotation 48
Style.TextFontShadow 22
Theme.AutoRecompute 5
Theme.ComputeTheme 13
Theme.DataMax 12
Theme.DataMin 11

690 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Theme.Fields 10
Theme.Layer 9
Theme.Legend 4
Theme.Name 6
Theme.Properties 3
Theme.ThemeDlg 8
Theme.ThemeProperties 7
Theme.Type 2
Theme.Visible 1
ThemeProperties.AllowEmptyRanges 15
ThemeProperties.ApplyAttribute 31
ThemeProperties.BarFrameStyle 28
ThemeProperties.BarFramed 38
ThemeProperties.BarGraduatedStack 30
ThemeProperties.BarIndependentScale 26
ThemeProperties.BarStacked 20
ThemeProperties.BarWidth 25
ThemeProperties.BorderStyle 24
ThemeProperties.ColorMethod 34
ThemeProperties.DataValue 10
ThemeProperties.DistMethod 1
ThemeProperties.DotColor 16
ThemeProperties.DotSize 5
ThemeProperties.GraduateSizeBy 23
ThemeProperties.Graduated 6
ThemeProperties.Independent 8
ThemeProperties.IndividualValueCategories 4
ThemeProperties.InflectRanges 35
ThemeProperties.InflectionColor 37

MapInfo MapX Developer Guide v4.5 691

IDispatch Table

Method/Property IDispatch

ThemeProperties.InflectionRange 36
ThemeProperties.MultivarCategories 7
ThemeProperties.NegativeSymbolStyle 21
ThemeProperties.NumRanges 2
ThemeProperties.PieClockwise 17
ThemeProperties.PieGraduated 29
ThemeProperties.PieHalfPies 18
ThemeProperties.PieStartAngle 19
ThemeProperties.PositiveSymbolStyle 27
ThemeProperties.RangeCategories 3
ThemeProperties.RoundBy 33
ThemeProperties.RoundRanges 32
ThemeProperties.ShowNegativeValues 22
ThemeProperties.Size 11
ThemeProperties.SpreadBy 14
ThemeProperties.SymbolStyle 13
ThemeProperties.ValuePerDot 9
ThemeProperties.Width 12
Themes.Add 2
Themes.Count 1
Themes.Item 3
Themes.Remove 4
Themes.RemoveAll 5
Title.Border 8
Title.Caption 1
Title.Editable 6
Title.Position 7
Title.TextStyle 2
Title.Visible 3

692 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Method/Property IDispatch

Title.X 4
Title.Y 5

MapInfo MapX Developer Guide v4.5 693

IDispatch Table

694 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Managing MapX Data

In addition to the MapX software, the MapX installer installs data products (maps and
demographic data) on your computer, so you can get started exploring the capabilities of
MapX.

Note: Use of data products is subject to the MapInfo Standard License Agreement -
Software & Data.
By default, maps and geosets are installed in the directory:
• C:\Program Files\MapInfo\MapX 4.0\Maps
Demographic data, in the form of a Microsoft Access table (MAPSTATS.MDB), is installed in
the directory:

• C:\Program Files\MapInfo\MapX 4.0\Data

The exact list of files installed on your computer depends partly on the options that you
chose during installation. (By default, all data products are installed; but the installer allows
you to un-check any or all geosets to avoid installing them.) The list of files installed also
depends upon which version of the software you installed; the MapX installation CD
provides more data products than the download-for-evaluation version of the software.

Use the MapX GeoDictionary Manager to register information about the MapInfo tables that
can be matched by MapX during automatic databinding. By default, this utility is located at
the following path:
• C:\Program Files\Common Files\MapInfo Shared\MapX
Common\GeoDictionaryManager40.EXE
Use the MapX Geoset Manager to create and manage geosets. By default, this utility is
located at the following path:

• C:\Program Files\Common Files\MapInfo Shared\MapX

Common\GeosetManager40.EXE
For more information about the Geodictionary Manager, see Using the GeoDictionary
Manager. For more information about the Geoset Manager, see Using the Geoset Manager.

MapInfo MapX Developer Guide v4.5 695

Managing MapX Data

Data Sources
The following sources provided the data released with MapInfo MapX. For more
information on MapInfo products, see the “MapInfo Data Products Catalog” or contact
MapInfo Corporation.

Map Name Copyright

Japan Geoset
Japan Cased Roads GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Japan Cities MapInfo from Digital Chart of the World
Japan Country background GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Japan Highways GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Japan Major Cities MapInfo from Digital Chart of the World
Japan Rivers and Lakes GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
World Ocean (Lat / Long) MapInfo

Australia Geoset

Australia Cities MapInfo from Digital Chart of the World

Australia Highways MapInfo from Digital Chart of the World
Australia Major Cities MapInfo from Digital Chart of the World
Australia State Boundaries MapInfo
Australia State Capital Cities MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

Europe Geoset
Asia MapInfo from Digital Chart of the World
European Capitals MapInfo from Digital Chart of the World
European Cities MapInfo from Digital Chart of the World
European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993

696 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Map Name Copyright

European Highways GisNET data licensed to MapInfo by GISdata

Limited. © GDC Ltd 1993
European Major Cities MapInfo from Digital Chart of the World
European NUTS 1 Level Boundaries Copyright URPI 1998
European NUTS 2 Level Boundaries Copyright URPI 1998
World Ocean (Lat / Long) MapInfo

France Geoset

European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
France Cities MapInfo from Digital Chart of the World
France Highway Map GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
France Major Cities MapInfo from Digital Chart of the World
France NUTS 2 Level Administrative Copyright URPI 1998
Boundaries
World Ocean (Lat / Long) MapInfo

UK Geoset

European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
United Kingdom Cities MapInfo from Digital Chart of the World
United Kingdom Class A Roads GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
United Kingdom Motorways GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
United Kingdom Standard Regions Copyright URPI 1998
World Ocean (Lat / Long) MapInfo

Canada Geoset
Canada Cities MapInfo from Digital Chart of the World
Canada Highways MapInfo from Digital Chart of the World
Canada Major Cities MapInfo from Digital Chart of the World

MapInfo MapX Developer Guide v4.5 697

Managing MapX Data

Map Name Copyright

Canadian Province Boundaries MapInfo from Digital Chart of the World

Canadian Province Capital Cities MapInfo from Digital Chart of the World
US State Boundaries MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

US Geoset

Canadian Province Boundaries MapInfo from Digital Chart of the World

Mexico State Boundaries MapInfo from the Bureau of Transportation
Statistics
US Cities MapInfo from Digital Chart of the World
US County Boundaries MapInfo from Census Bureau
US Highways MapInfo from the Bureau of Transportation
Statistics
US Major Cities MapInfo from Digital Chart of the World
US State Boundaries MapInfo from Digital Chart of the World
US State Capitals MapInfo from Digital Chart of the World
US top 20 Cities MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

World Geoset

World Capitals MapInfo from Digital Chart of the World

World Countries MapInfo from Digital Chart of the World
World Graticule MapInfo
World Ocean (Robinson) MapInfo
World Top 25 Cities MapInfo from Digital Chart of the World

DC Geoset
Dc Area Landmarks MapInfo
Dc City Boundaries MapInfo
DC Highways MapInfo from the Bureau of Transportation
Statistics
DC Interstate Roads MapInfo from the Bureau of Transportation
Statistics

698 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Map Name Copyright

DC Landmarks MapInfo
DC Roads MapInfo from the Bureau of Transportation
Statistics
DC State Roads MapInfo from the Bureau of Transportation
Statistics
Dc Water Layer MapInfo
DC Zips © 1995 Geographic Data Technology, Inc.

Asia Geoset

Asia MapInfo from Digital Chart of the World

Asia Capitals MapInfo from Digital Chart of the World
Asia Major Cities MapInfo from Digital Chart of the World
European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
World Ocean (for Asia) MapInfo

Mid-Atlantic Geoset

Mid-Atlantic Capitals MapInfo from Digital Chart of the World

Mid-Atlantic Cities MapInfo from Digital Chart of the World
Mid-Atlantic Counties MapInfo
Mid-Atlantic Highway MapInfo from the Bureau of Transportation
Statistics
Mid-Atlantic Major Cities MapInfo from Digital Chart of the World
Mid-Atlantic States MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo
US State Boundaries MapInfo from Digital Chart of the World

China Geoset
Asia MapInfo from Digital Chart of the World
Asia Major Cities MapInfo from Digital Chart of the World
China Cities MapInfo from Digital Chart of the World
China Country Bdy MapInfo from Digital Chart of the World

MapInfo MapX Developer Guide v4.5 699

Managing MapX Data

Map Name Copyright

China Highways MapInfo from Digital Chart of the World

China Major Cities MapInfo from Digital Chart of the World
World Ocean (for Asia) MapInfo

Mexico Geoset
Mexico Cities MapInfo from Digital Chart of the World
Mexico Highways MapInfo from Digital Chart of the World
Mexico Major Cities MapInfo from Digital Chart of the World
Mexico State Boundaries MapInfo from the Bureau of Transportation
Statistics
Mexico State Capital Cities MapInfo from Digital Chart of the World
US State Boundaries MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

North American Geoset

Canada Cities MapInfo from Digital Chart of the World

Canada Highways MapInfo from Digital Chart of the World
Canada Major Cities MapInfo from Digital Chart of the World
Canadian Province Boundaries MapInfo from Digital Chart of the World
Canadian Province Capital Cities MapInfo from Digital Chart of the World
Mexico Cities MapInfo from Digital Chart of the World
Mexico Highways MapInfo from Digital Chart of the World
Mexico Major Cities MapInfo from Digital Chart of the World
Mexico State Boundaries MapInfo from the Bureau of Transportation
Statistics
Mexico State Capital Cities MapInfo from Digital Chart of the World
US Cities MapInfo from Digital Chart of the World
US Highways MapInfo from the Bureau of Transportation
Statistics
US Major Cities MapInfo from Digital Chart of the World
US State Boundaries MapInfo from Digital Chart of the World
US State Capitals MapInfo from Digital Chart of the World

700 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Map Name Copyright

World Ocean (Lat / Long) MapInfo

Germany Geoset
European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Germany Cities MapInfo from Digital Chart of the World
Germany Highways GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Germany Major Cities MapInfo from Digital Chart of the World
Germany NUTS 2 Level Bdys MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

Italy Geoset

European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Italy Cities MapInfo from Digital Chart of the World
Italy Highways GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Italy Major Cities MapInfo from Digital Chart of the World
Italy NUTS 2 Level Bdys Copyright URPI 1998
World Ocean (Lat / Long) MapInfo

Portugal Geoset
European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Portugal Highways GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Portugal Major Cities MapInfo from Digital Chart of the World
Portugal NUTS 2 Level Boundary Copyright URPI 1998
World Ocean (Lat / Long) MapInfo

Argentina Geoset

MapInfo MapX Developer Guide v4.5 701

Managing MapX Data

Map Name Copyright

Argentina Cities MapInfo from Digital Chart of the World

Argentina Country Boundary MapInfo from Digital Chart of the World
Argentina Major Cities MapInfo from Digital Chart of the World
South America Country Boundaries MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

Brazil Geoset

Brazil Major Cities MapInfo from Digital Chart of the World

Brazil Cities MapInfo from Digital Chart of the World
Brazil Country Boundary MapInfo from Digital Chart of the World
South America Country Boundaries MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

Israel Geoset

Africa Country Boundary MapInfo from Digital Chart of the World

Asia MapInfo from Digital Chart of the World
Israel Cities MapInfo from Digital Chart of the World
Israel Country Boundary MapInfo from Digital Chart of the World
Israel Major Cities MapInfo from Digital Chart of the World
World Ocean (Lat / Long) MapInfo

South Korea Geoset

Asia MapInfo from Digital Chart of the World
South Korea Cities MapInfo from Digital Chart of the World
South Korea Country Boundary MapInfo from Digital Chart of the World
South Korea Major Cities MapInfo from Digital Chart of the World
World Ocean (for Asia) MapInfo

Spain Geoset

European Country Boundaries Data copyright and produced by URPI 1998 and
GisNET data licensed to MapInfo by GISdata
Limited. © GDC Ltd 1993
Spain Cities MapInfo from Digital Chart of the World

702 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Map Name Copyright

Spain Highways GisNET data licensed to MapInfo by GISdata

Limited. © GDC Ltd 1993
Spain Major Cities MapInfo from Digital Chart of the World
Spain NUTS 2 Boundaries Copyright URPI 1998
World Ocean (Lat / Long) MapInfo

India Geoset

Asia MapInfo from Digital Chart of the World

India Capital Cities MapInfo from Digital Chart of the World
India District Bdys Risk Management Solutions, Inc
India Major Cities MapInfo from Digital Chart of the World
India Minor Cities MapInfo from Digital Chart of the World
India State Bdys Risk Management Solutions, Inc
World Ocean (for Asia) MapInfo

US Detail Geoset

Canadian Province Boundaries MapInfo from Digital Chart of the World

Landmark Map MapInfo from USGS
Mexico State Boundaries MapInfo from the Bureau of Transportation
Statistics
US Cities MapInfo from Digital Chart of the World
US County Boundaries MapInfo from Census Bureau
US Highways MapInfo from the Bureau of Transportation
Statistics
US Major Cities MapInfo from Digital Chart of the World
US State Boundaries MapInfo from Digital Chart of the World
US State Capitals MapInfo from Digital Chart of the World
US top 20 Cities MapInfo from Digital Chart of the World
US ZIP Code Boundaries © 1997 Geographic Data Technology, Inc.
World Ocean (Lat / Long) MapInfo

World Detail Geoset

World Capitals MapInfo from Digital Chart of the World

MapInfo MapX Developer Guide v4.5 703

Managing MapX Data

Map Name Copyright

World Countries MapInfo from Digital Chart of the World

World Graticule MapInfo
World Major Cities MapInfo from Digital Chart of the World
World Minor Cities MapInfo from Digital Chart of the World
World Ocean (Robinson) MapInfo
World Top 25 Cities MapInfo from Digital Chart of the World

Dallas, TX Geoset

Crime County Map MapInfo

Crime Demo Map MapInfo
Dallas City Boundary A MapInfo from USGS
Dallas City Boundary B MapInfo from USGS
Dallas Locations MapInfo
Dallas Major Highways A MapInfo from USGS
Dallas Major Highways B MapInfo from USGS
Dallas Streets A MapInfo from USGS
Dallas Streets B MapInfo from USGS
Dallas Streets C MapInfo from USGS
Dallas Water Bodies MapInfo from USGS
Dallas Water Rivers MapInfo from USGS
Dallas, TX Raster Copyright © 1997, Horizons Technology, Inc

Other Files

Dallas City Boundary from MapXsite MapInfo from USGS

Streets 1.0
Dallas Major Highways from MapXsite MapInfo from USGS
Streets 1.0
Dallas Streets from MapXsite Streets 1.0 MapInfo from USGS
Dallas Water Bodies from MapXsite MapInfo from USGS
Streets 1.0
Dallas Water Rivers from MapXsite MapInfo from USGS
Streets 1.0

704 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Map Name Copyright

US 5-Digit ZIP Code Points (c) 1999 Geographic Data Technology, Inc.
US 5-Digit ZIP Code Points (c) 1995 Geographic Data Technology, Inc.
(compressed point file)

MapStats.mdb
Demographics for Asia Copyright United Nation Demographic Yearbook,
1994
Demographics for Australia MapInfo Australia
Demographics for DC copyright 1998, The Polk Company, All Rights
Reserved
Demographics for Mid-Atlantic States copyright 1998, The Polk Company, All Rights
Reserved
Demographics for the World Copyright United Nation Demographic Yearbook,
1994
Demographics for US copyright 1998, The Polk Company, All Rights
Reserved
US County Age Demographics copyright 1998, The Polk Company, All Rights
Reserved
US County Age Demographics by copyright 1998, The Polk Company, All Rights
Gender Reserved
US County Household demographics copyright 1998, The Polk Company, All Rights
Reserved
US County Household demographics copyright 1998, The Polk Company, All Rights
by Age, Income Reserved
US County Household Income copyright 1998, The Polk Company, All Rights
Reserved
US County Housing Values copyright 1998, The Polk Company, All Rights
Reserved
US County Population Demographics copyright 1998, The Polk Company, All Rights
Reserved
US Customer Database MapInfo

MapInfo MapX Developer Guide v4.5 705

Managing MapX Data

706 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Using the Geoset Manager

Use the Geoset Manager to keep a collection of map layers and their settings easily available
to you. Geosets help you to avoid the time consuming task of opening and displaying layers
individually each time you want to work with them.

Computer maps are organized into layers. Think of layers as transparencies that are stacked
on top of one another. Begin building a geoset by opening a map. Each map layer contains
different map objects, such as regions, points, lines, and text.
For example, one layer may contain state boundaries, a second layer may have symbols that
represent capitals, and a third layer might consist of text labels. By stacking these layers on
top of the other, you begin to build a complete map.

Once you have created your geoset, you can customize the way in which the layers display,
and add, delete, or reorder them.

From the Geoset Manager, work with sample geosets, or create your own.
To start the Geoset Manager, select Geoset Manager from the MapX Program Group on your
Start menu.

Note: In the Trial version of MapX, the Geoset Manager will only function on the
developer’s machine.

Opening an Existing Geoset

MapX includes some sample geosets. Use these as a starting point for your own geoset or
use them as they are. Todisplay an existing geoset:
1. Choose File > Open Geoset. The Open dialog displays.

MapInfo MapX Developer Guide v4.5 707

Using the Geoset Manager

2. Select the geoset you want and click Open. That geoset displays.
From here you can alter a variety of layer settings using items in the Map Menu or View
Menu. You can also insert other geosets to display with the current geoset. Then, save these
new settings to the existing geoset or SaveAs to create a new geoset. We will discuss these
items in detail in the following sections.

708 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Creating a Geoset
1. Choose File > New Geoset. The Layer Control dialog displays.
2. Click Add to display the Open dialog.
3. Select the layers you want to use as a part of your geoset. Hold down the Ctrl key
while selecting to mark several layers. The selected layers display in the Layer
Control dialog.

From here you can set display and label properties, reorder the way in which layers
display, remove or add additional layers and set whether layers are visible, contain
automatic labels, or are selectable. See the description of Layer Control in a
following section, below.You can edit these properties later after displaying the
initial geoset.
4. Click OK to display the geoset. Your newly created geoset displays.
Use the information in the sections that follow to manipulate and customize the layers in
your geoset. When you have finished creating your geoset you'll need to save it.

MapInfo MapX Developer Guide v4.5 709

Using the Geoset Manager

To save your geoset:

1. Choose File > Save. The Save As dialog displays.
2. Enter a name and click Save to save the layers with the attributes you specified.

Manipulating Your Layers with the Map Menu

Use the options avaiable from the Map Menu to control the way in which your map
displays.

Zoom In
Use the Zoom In tool to get a closer area view of a map or a layer.
1. Choose Map > Zoom In, or click the Zoom In button on the menu bar, or right click
the mouse in the Geoset Manager window and choose Zoom In.
The Zoom In mouse icon appears.
2. Click the Zoom In cursor on the center of the area you want to zoom in on,
magnifying the area by a linear factor of two. This point will be at the center of the
map in the zoomed in view. Repeat this procedure until you have the appropriate
level of enlargement.
To zoom in on a rectangular area:
1. Choose Map > Zoom In, or click the Zoom In button on the menu bar, or right click
the mouse in the Geoset manager window and choose Zoom In.
The Zoom In mouse icon appears.
2. Draw a marquee in the map or layout by diagonally dragging the Zoom In mouse
icon. The area within the marquee is enlarged.

Zoom Out
Use the Zoom Out tool to get a wider area view of a map or a layer.
1. Choose Map > Zoom Out, or click the Zoom Out button, or right click the mouse in
the Geoset Manager window and choose Zoom Out.
The Zoom Out mouse icon appears.
2. Click the Zoom Out mouse icon on the center of the area you want to zoom out on,
enlarging the area by a linear factor of two. This point will be at the center of the
map in the zoomed-out view. Repeat this procedure until you have the appropriate
level of magnification.

710 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

To zoom out from a rectangular area:

1. Choose Map > Zoom Out, click the Zoom Out button, or right click the mouse in the
Geoset Manager window and choose Zoom Out.
The Zoom Out mouse icon appears.
2. Draw a marquee in the map or layout by diagonally dragging the Zoom Out mouse
icon. The area within the marquee is reduced, allowing more of the map to display.

Pan
Use Pan to reposition a map within its window.
To move or adjust the map display:
1. Choose Map > Pan, or click the Pan button, or right click the mouse in the Geoset
Manager window and choose Pan.
The Pan mouse icon appears.
2. Click an area of the map.
3. While holding down the left mouse button, drag the map in the appropriate
direction. When you release the mouse button, Geoset Manager redraws the map in
its new location.

Zoom To
Zoom to a particular X and Y coordinate on the map and set a zoom level.

Choose Map > Zoom To.

The Zoom To dialog displays.

Enter the coordinates to which you want to zoom.

MapInfo MapX Developer Guide v4.5 711

Using the Geoset Manager

View Entire Layer

Use View Entire Layer to zoom and display an entire layer or all layers in a map.

Use this option if the map contains layers that cover different amounts of territory. For
example, you have a map containing New York counties, highways, ZIP Codes and streets
for Utica. If you choose All Layers, the view will be zoomed out to display the entire map.
But if you are only interested in viewing Utica streets, choose the Utica streets layer. The
zoom will be zoomed in to display those streets.

To display an entire map or map layer:

1. Choose Map > View Entire Layer, or right click with the mouse over the Map
window and choose View Entire Layer. The View Entire Layer dialog displays.

2. Choose a specific layer or All layers to display. Click OK to view the layer(s).

Layer Control
Use the Layer Control dialog to:

• Change the display of map layers in the active window

• Determine which layers are displayed, removed, added, selectable, zoom layered,
labeled and set
• Change the order of map layers.
To access Layer Control:

• Choose Map > Layer Control, click the Layer Control button, right click the mouse
over the map and choose Layer Control or create a new geoset.
The Layer Control dialog controls how maps display. Some important information includes:

712 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

• The Layer Control dialog displays the list of layers in the current map window and
indicates whether each is displayed, selectable, or labeled automatically.
• Layers include data tables, raster images, or thematic maps stacked in a map
window.
• The order of layers in the Layer Control dialog is the order of the layers in the map
window. For example, when boundary layers are placed below point layers, the
points remain visible.
• To work with a layer, choose it by clicking on it. Control its settings by checking or
clearing the appropriate box to make the layer display, selectable, or label
automatically.

Part Description

Up Moves one or more layers up.

Down Moves one or more layers down.
Add Adds one or more layers to the map. Choose from the displayed
listbox of tables.
Remove Removes one or more layers from the map.
Visible Indicates if the layer is visible. Check this box for the layer, or
layers, that you want to make visible in the map. Sometimes you
may want to include layers in your geoset for computational
purposes and not want them actually displayed in the geoset.
Selectable Indicates if the layer is selectable. Check this box for the layer, or
layers, that you want to make selectable. Layers must be
selectable if you want to choose or label objects. A layer must be
displayed to be made selectable. More than one layer may be
selectable at the same time.You may, however, only select from
one layer at a time.
Automatic Lables Check to label the map automatically.The labels are taken from
the table column designated in the Label with section of the
Label Options dialog.
Display This displays the Display Options dialog. Use this dialog to
specify display attributes for map layers.
Labels This displays the Label Properties dialog. Use this dialog to
specify label attributes for map layers.

To specify display attributes for a map layer, click the Display button from the Layer Control
dialog.

MapInfo MapX Developer Guide v4.5 713

Using the Geoset Manager

Display Mode
Part Description

Override Style Check to override the default style of a layer.

Style Button Enabled when Style Override option is checked. This displays
the button appropriate to the object type contained in the
selected layer: Region, Line, Symbol, or Text. Click to display
the corresponding dialog.

Zoom Layering
Part Description
Display within zoom Check to activate zoom layering. Zoom layering allows you to
range set the minimum and maximum distances at which the selected
layer will be visible. For example, if you only want to see
particular streets on a map when you are closer than 3 miles, set
the minimum zoom to 0 and the maximum to 3.
Min Zoom Specify the minimum distance at which the selected layer is
visible.
Max Zoom Specify the maximum distance at which the selected layer is
visible.

Automatic Labeling
To automatically label a layer in a map using information from that layer:
1. From the Layer Control dialog, choose the layer you want to label; check the
Automatic Labels check box.
2. Click OK.
The map redisplays with labels from the table column designated in the Label with section
of the Label Options dialog if a dataset is loaded and a field from that dataset is specified.

Only one column per table displays at one time.

Access the Label Properties dialog to change the visibility, content, font, text color, line style,
and position of labels.

714 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

The Label Properties Dialog

Label Properties dialog determines the visibility, content, font, text color, line style, and
anchor point of labels. These settings are used for both automatic and interactive labeling
using the Label tool. When using the Label tool, the label is positioned at the place you
designate by clicking the mouse button.

To access the Label Properties dialog:

1. Choose Map > Layer Control.
2. Click the Label button. The Label Properties dialog displays.

Part Description

Label With: Choose the Dataset and Field name that you want to be reflected
in the label.
Visibility:
On Check to allow display of labels.
Off Check to prevent display of labels.
Display within range Check to activate zoom labeling. Zoom labeling allows you to
set the minimum and maximum distances at which the labels
will be visible. For example, if you only want to see particular
labels on a map when you are closer than 3 miles, set the
minimum zoom to 0 and the maximum to 3.
Label size does not change with zoom or scale changes.
Min Zoom Specify the minimum distance at which labels are visible.
Max Zoom Specify the maximum distance at which labels are visible.
Allow duplicate text Check to place the same label on a map more than once.
Allow overlapping text Allow more than one object with the same text to be displayed.
Maximum labels Enter the maximum number of labels that will display; labels are
selected from the designated table in the order in which they are
entered in the table. For example, if the designated table is the
States table, and you enter 10, the first ten states listed in the
table, which are in view, will be labeled.
Styles:
Text Style button Click the Text Style button to display the Text Style dialog. See
Text Style Dialog.
Label Lines Select a line type, or no line type, to attach the label to the anchor
point.
None Do not display a line with the label.

MapInfo MapX Developer Guide v4.5 715

Using the Geoset Manager

Part Description

Simple Create a callout by using a simple line that connects the label to
the object's centroid. Label lines display after you move the label
from where it was originally created.
Arrow Create a callout by using an arrow line that connects the label to
the object's centroid. Label lines display after you move the label
from where it was originally created.
Position:
Anchor Point Click an icon to select the label position relative to the label
anchor. The diamond character represents the label anchor; the
rectangle represents the label. The border of the selected box is
bold.
Rotate label with line Check to rotate text to run parallel with line segments. This
setting is ignored for points regions.
Label Offset Designate number of points (a measurement of text size) label
should be placed from the anchor point.

Projection
How do you flatten the curved surface of the earth so that you can draw maps on flat pieces
of paper and (nearly) flat computer screens? You use a projection. A projection is a system
that defines how to flatten objects.You can display your maps in many different projections.

When you transfer objects from the spherical world to the relatively flat computer screen,
there is bound to be some distortion.
A projection is a method of reducing the distortion that occurs when objects from a spherical
surface are displayed on a flat surface. There are many different types of projections, each
designed to reduce the amount of distortion for a given area.

To choose a projection:
Choose Map > Projection, or right-click the mouse over the map and choose
projection.

716 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Using the View Menu

Use the Options in the View Menu to designate if Status bars or Toolbars display and to
change map distance units or coordinates.

Toolbar Displays
To show or hide the Map Toolbar, Geoset Name Toolbar, or the Status Bar, check or clear the
menu options as appropriate.

MapInfo MapX Developer Guide v4.5 717

Using the Geoset Manager

Options
Use the Options dialog to set the distance units and the numeric coordinates used by the
map.
To set options choose View > Options. The Options dialog displays.

Part Description
Distance Units Choose the measure of distnace used for the map.
Numeric Coordinates Choose the numeric coordinates the Geoset Manager will use to
find the X and Y coordinates. A coordinate system is a set of
parameters that tells you how to interpret the locations
coordinates for objects. Each point in a geometric object is
represented by a pair of numbers. Those numbers are the
coordinate for those points.

Tools and the GeoDictionary Manager

Use the options in the Tools menu to access the GeoDictionary manager. The GeoDictionary
manager allows you to register layers in the geodictionary. Layers registered in the
geodictionary can be used for databinding in other MapX sessions.

For more information on the Geodictionary Manager, see Using the GeoDictionary
Manager.

718 MapInfo MapX Developer Guide v4.5

 Weekday( ) function

Using the Geodictionary Manager

This topic describes the features of the MapX Geodictionary Manager. The Geodictionary is
a file containing registration information about the MapInfo tables that can be matched by
MapX during automatic databinding. Only MapInfo tables that can or will be matched
against should be registered in the Geodictionary.

Note: There is no need to register every .tab file that an application uses in the
Geodictionary, and in fact there is some overhead in having unnecessary files
registered.
The Geodictionary Manager Applications allows manipulation of the Geodictionary. The
Geodictionary Manager executable (GeoDictionaryManager40.exe) can be run with a
graphical user interface or with command line parameters. The command line options are
useful for calling GeoDictionaryManager40.exe from install programs to register the tables
that a MapX application may need to match against into the Geodictionary.

Background Information
Previous versions of MapX used the MapInfo Data Installer developed for Microsoft Map to
manage the Geodictionary. The Data Installer also managed geosets (groups of MapInfo
tables that can be displayed together), which was overkill for the Geodictionary Manager
and caused confusion. There is now a Geoset Manager application which should be used to
create and manage geosets. The new Geodictionary Manager will not modify geosets in any
way, nor will it delete files from a user’s disk.

In MapX 4.0 (or later versions), a permanent Geodictionary file is no longer required for
MapX to run.

There has been a change to the command line options that requires that file or path names
with spaces in them require that they be enclosed in double quotes. This may make some
command lines that worked previously fail now

• The Geodictionary File

• User Interface

MapInfo MapX Developer Guide v4.5 719

Using the Geodictionary Manager

Command Line Options The Geodictionary File

The Geodictionary is contained in a binary format file usually called geodict.dct. The
geodictionary file can be located or disabled by using the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX 4.0\GeoDictionary. There are
three valid possibilites for this key:

• Could contain a full file spec for the Geodictionary file (e.g. "C:\Program
Files\MapInfo MapX\Maps\geodict.dct"). The effect is that the data directory is
set to be the path leading to the Geodictionary file named by this key. The in-
memory geodictionary is initialized from the Geodictionary file and layers
contained in the Geodictionary can be automatically matched against it too. Layers
added to the map are added to the in-memory geodictionary so they can be auto
matched against.
• Could contain just a path specification (e.g. "C:\Program Files\MapInfo
MapX\Maps\"). The data directory is set to be the path named by this key. The in-
memory geodictionary is initialized empty. Layers added to the map are still added
to the in-memory geodictionary so they can be auto matched against.
• Could not exist at all. The in-memory geodictionary is initialized empty. Layers
added to the map are still added to the in-memory geodictionary so they may be
auto matched.
Note: An Uninstall of MapX will leave geodict.dct behind. This is the expected
behavior because the Geodictionary file may have existed before the install (from
an earlier version of MapX), or may be shared by other apps
MapX applications can share the same Geodictionary file, or use their own. In order for a
MapX application to use its own Geodictionary file (or to not use one at all), the
Map.GeoDictionary property can be changed at design time to point to a different registry
entry. Then, when the map control is initialized at runtime, MapX will query the following
registry entry:

HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX\4.0\<value of
Map.GeoDictionary>
The value of this registry entry will be interpreted as detailed above. The default value of
Map.GeoDictionary is "GeoDictionary" so that MapX will use the default registry entry.

The Geodictionary Manager always reads and updates the default Geodictionary file,
referred to by the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX\4.0\GeoDictionary. If you
change the location of the Geodictionary file in the user interface, then the registry key is
updated to point to that new location.

720 MapInfo MapX Developer Guide v4.5

 User Interface

The Geodictionary contains an entry for each registered table (mapinfo .tab file). The data
stored with each entry is:
• A user-friendly name to refer to the table and to display in the layer control dialogs.
This defaults to the ‘Description’ tag in the .tab file, or the file name if none exists. It
can be edited through the user interface.
• A list of indexed fields. The user interface allows you to check which of the
indexed fields you want MapX to consider as possible columns to match against
during automatic databinding. Fields that are not checked are ignored. When a
table is first registered, all indexed fields are initially checked by default.
• A refining table name. Some tables, e.g., US Counties, contain indexed columns
that are not unique. In that situation, a refining table is necessary to determine an
exact match for data. If the table has non-unique indexed columns, the refining
column combo box will be enabled and the user will be able to pick a refining table.
• A list of Geoset file names. When a table is selected during automatic databinding,
the list of geosets for that table is passed to the ResolveDataBind event for the MapX
program to choose one. MapX will pick the first one by default if the event is not
handled. Note: The table that was matched is always loaded, even if it is not in the
geoset that gets loaded. Also, it is not an error to have no geosets listed for a table in
the Geodictionary. In that case, only the table is loaded. Finally, only geoset files that
are located in the same directory as the Geodictionary file can be added to the list.

User Interface
This section describes the user interface for the Geodictionary Manager.

Run Geodictionary Manager

Run the GeoDictionary Manager when you want to manually register layers.

Choose Tools. > Run GeoDictionary Manager.

The Geodictionary dialog displays.

MapInfo MapX Developer Guide v4.5 721

Using the Geodictionary Manager

Part Description

Geodictionary The Geodictionary edit box is a read-only edit box containing

the full path to the Geodictionary that's being managed. This
information is found by looking at the MapX key in the registry.
The button (to the right of the Geodictionary edit box) allows the
user to browse for another Geodictionary to manage. Browsing
to another Geodictionary changes MapX's registry key so that all
subsequent MapX sessions will use the new dictionary. The
button also lets you change the default MapX search path which
is stored in the registry key
"HKEY_LOCAL_MACHINEOFTWAREapInfoap
X.0earchPaths".
Registered tables The Registered Tables list box contains a list of the friendly
names for all tables registered in the Geodictionary.

722 MapInfo MapX Developer Guide v4.5

 User Interface

Part Description

Register This displays the common file open dialog, with the Files of
Type combo box set to "MapInfoTables (*.tab)". Copy the table
to the data directory (the directory containing the
Geodictionary), or add the directory containing the table to the
data search path. After the table has been assimilated (either by
copying or by adding the directory to the search path), theTable
Properties dialog displays. Users can select multiple files to
register by holding Ctrl/Shift key down while clicking. In cases
of multiple tables being selected, the properties button is
disabled. See the Table Properties Dialog.
Unregister Remove the selected table from the Geodictionary. The
Unregister button will not remove the files from the disk. Users
can select multiple files to unregister by holding Ctrl/Shift key
down while clicking.
Properties Display the Table Properties dialog for the selected table. See the
Table Properties dialog below.
Set the Geodictionary fields for a given table using theTable Properties Dialog.

MapInfo Table Read-only edit box containing the file name of the MapInfo
table if it is located in the same directory of the Geodictionary, or
the full pathname to the file if it is not.

MapInfo MapX Developer Guide v4.5 723

Using the Geodictionary Manager

Description Provides a mechanism for changing the friendly name for the
table. This control is defaulted to the Description tag in the
.TAB file, or the filename if the Description tag is not found, but
can be changed by the user. Note that changes to the
description in the Geodictionary Manager will only be stored in
the Geodictionary and will not be reflected in the table. This
allows the Geodictionary Manager to easily work with read-
only data, e.g., data on CD-ROMs.

Geometry The Geometry static text control displays the type of entities
stored in the table.

Field Information Contains a list of the indexed columns in the table. If the box for
a given column is checked, the field will be searched during the
matching process.

Refining Table Some tables, e.g., US Counties, contain indexed columns that
are not unique. In that situation, a refining table is necessary to
determine an exact match for data. If the table has non-unique
indexed columns, the refining column combo box will be
enabled and the user will be able to pick a refining table.

Candidate Geosets List of the geoset file names that are possible candidates to load
if the MapInfo table was selected during databinding. Zero or
more geoset filenames can be listed. When the table is selected
during automatic databinding, the list of geosets for that table is
passed to the ResolveDataBind event for the MapX program to
choose one. MapX will pick the first one by default if the event
is not handled.
Please note:
• The table matched is always loaded, even if it is not in the
geoset that gets loaded.
• It is not an error to have no geosets listed for a table in the
Geodictionary. In that case, only the table is loaded.
• Only geoset files that are located in the same directory as the
Geodictionary file can be added to the list.
• Multiple candidate geosets can be added or removed

Add This displays a list box containing a list of the geoset file names
that are in the same directory as the Geodictionary file. Selecting
one adds it to the list of candidate geosets.

Remove Deletes the selected geoset file name from the list of candidate
geosets.

724 MapInfo MapX Developer Guide v4.5

 Command Line Options

Register Layers in Geodictionary

If you want the Geoset Manager to automatically register your layers, choose Tools >
Register Layers. The Register Layers dialog displays.

Check the layers you want to register and click OK.

Command Line Options

The Geodictonary Manager command line provides a mechanism for adding and removing
tables to/from the Geodictionary

geosetpath The path to a geoset file containing a list of tables. Currently a path is
required; just specifying the filename is considered an error.
• Use the geosetpath option to register all of the valid .tab files in
the geoset with the Geodictionary. (Raster, Seamless, and View
tables in the geoset will be ignored.)
• Use the geosetpath /remove option to unregister all of the valid
tab files in the geoset from the Geodictionary.

MapInfo MapX Developer Guide v4.5 725

Using the Geodictionary Manager

tablepath The path to a MapInfo table to add to the Geodictionary (the option
with no arguments).
• Use the tablepath option to register a file with the Geodictionary.
• Use the tablepath /remove option to unregister a file from the
Geodictionary.

geosetfile The file name only of a geoset file located in the same directory as the
Geodictionary file.
• Use the tablepath /geoset=geosetfile option to register a file with
the Geodictionary and add geosetfile to its list of candidate
geosets to match.
• Use the tablepath /geoset=geosetfile /remove option to remove
geosetfile from its list of candidate geosets to match.

commandfilepath The full pathname of a text file that contains a valid migm30
command line on each line of the file.
• Use the /file=commandfilepath option to process a text file of
command lines, with 1 command line on each line of the file. Do
not include ‘migm30.exe’ on each line of the file.
• Use the /file=commandfilepath /remove option to process a text
file of command lines, with 1 command line on each line of the
file. The /remove option will be added to each command line
before it is executed. Do not include ‘migm30.exe’ on each line of
the file.

Note: Paths or filenames with spaces must be enclosed in double quotes. Wherever
possible, the command line usage of the Geodictionary Manager will run
silently.It is not an error to attempt to register a file more than once. It is not an
error to unregister a table that is not currently registered.

726 MapInfo MapX Developer Guide v4.5

 Command Line Options

Custom Dataset Support

Even if you cannot access your data sources through the standard MapX data binding
techniques, you can create your own custom dataset support. MapX version 3 and later
provides a run-time extensible architecture, allowing you to plug in custom dataset types
through a COM-based dataset interface.

Creating custom dataset support is an advanced topic. This discussion assumes that you are
already familiar with creating COM objects.

Static Dataset Object Overview

A Static Dataset object is a COM object that MapX can use to retrieve data from an arbitrary
data source. Data is fetched and aggregated when the data source is bound (via a call to
MapX’s Datasets.Add(…) method), and then cached by MapX. Changes to source data are
not reflected in the map until a refresh of MapX’s cached data is forced (via a call to MapX’s
DataSet.Refresh(…) method). All of the behavior needed to retrieve and cache data in this
manner is abstracted into three interfaces; IMMapXDataSet, IMMapXStaticDataSet, and
IMMapXColumnInfoContainer. A Static DataSet object must implement all three of these
interfaces (note that IMMapXStaticDataSet is derived from IMMapXDataSet). See below
for a more detailed look at the contract encapsulated by each of these interfaces.

Special Registration
When registered, a Static DataSet object server must make some special entries in the
registry so that MapX knows when to use it:

Add the key:

HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX\DatasetEngines\<Dataset
ID>
Add the string value:

HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX\DatasetEngines\<Dataset
ID> \DE_CLSID =
The CLSID of the Static Dataset object (in the form “{xxxxxxxx-
xxxx-xxxx-xxxx-xxxxxxxxxxxx}”).
Where <DatasetID> is a unique numeric identifier for your Static DataSet object. When the
“Type” parameter to Map’s DataSet.Add(…) method is this value, your server will be asked

MapInfo MapX Developer Guide v4.5 727

Custom Dataset Support

to provided the Static DataSet object through which MapX will ultimately retrieve data. The
values 0 through 1000 are reserved by MapInfo and should not be used.

Note: Don’t forget to delete these registry entries when your server is unregiste ed!

Interfaces
The IMMapXDataSet Interface
[
uuid(96e0f395-caec-11d0-9d99-00aa00a478cb),
helpstring("IMMapXDataset Interface"),
version(1.0)
]
interface IMMapXDataset : IUnknown
{
HRESULT Init(
[in] short sType,
[in] VARIANT* pvSourceData,
[in] VARIANT* pvFields );
HRESULT GetSample(
[in] long lColNum,
[in] long lNumSampleValuesRequested,
[in] VARTYPE vtRequested,
[out] VARIANT * pvarData,
[out] long * pNumRecordsFetched);

IMMapXDataSet::Init
HRESULT Init :)

[in] short sType The dataset type requested (the Type

parameter to the DataSets.Add
method). MapX has already identified
your server as the server for datasets of
this type (via registry entries you made
when your COM server was registered).

728 MapInfo MapX Developer Guide v4.5

 Interfaces

[in] VARIANT * pvSourceData A reference to the source data. (The

SourceData parameter to the
DataSet.Add method). For example,
this parameter contains the
ODBCQueryInfo object when the bind
type is miDataSetODBC, and an
IDAORecordset pointer when the bind
type is miDataSetDAO.

[in] VARIANT * pvFields Contains an array ofVARIANTS. Each

VARIANT identifies (either by name or
by index) a column from the source data
that the client programmer wants bound
to the matched map layer. If empty
(pvFields->vt = =VT_EMPTY) all
columns from the source data should be
bound.

Description
Initializes the Static DataSet object. This method will be called immediately after the
Static DataSet object is created. It gives the Static DataSet object an opportunity to
establish a connection with the data source, and identifies which columns from the
source data will be bound to the map. The Static DataSet object should, before returning
from this call, build an internal collection of ColumnInfo objects (objects that implement
IMMapXColumnInfo). The collection must contain an initialized ColumnInfo object for
each bound column. This collection is exposed to MapX via the
IMMapXColumnInfoContainer interface.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

MapInfo MapX Developer Guide v4.5 729

Custom Dataset Support

IMMapXDataset::GetSample
HRESULT GetSample();

[in] Long lColNum The source data column to get

the sample data from.

[in] Long lNumSamplesRequested The number of sample data

values requested.

[in] VARTYPE vtRequested The preferred type for returned

data.

[out] VARIANT * pvData VARIANT to receive the sample

data. When GetSample returns,
this VARIANT should contain
an array of the type requested.
MapX will try to convert data
that is of a different type, but
this will obviously be less
efficient.

[out] Long * plNumSamplesValuesFetched The number of sample data

values in pvData.

Description
Used to collect a sample of data from a given source data column. Note that the
returned variant (pvData) must contain an array, even if that array contains only a
single data value.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

The IMMapXStaticDataset Interface

[
uuid(2e6d4cc0-d132-11d0-9da0-00aa00a478cb),

730 MapInfo MapX Developer Guide v4.5

 Interfaces

helpstring("IMMapXStaticDataset Interface"),
version(1.0)
]
interface IMMapXStaticDataset : IMMapXDataset
{
HRESULT FetchData(
[in] long lColNum,
[in] long lIdxRow,
[in] VARTYPE vtRequested,
[out] VARIANT* pvarData,
[out] BOOL * pbNoMoreData);
HRESULT BeginFetch();
HRESULT EndFetch();
}

IMMapXStaticDataset::FetchData
HRESULT FetchData();

[in] Long lColNum The source data column from which to

fetch the data.

[in] Long lIdxRow The source data row from which to

fetch the data.

[in] vtRequested vtRequested The preferred type for returned data.

[out] VARIANT * pvarData VARIANT to hold the fetched data.

Should be of the type identified by
vtRequested. MapX will try to convert
data that is of a different type, but this
will obviously be less efficient.

[out] BOOL * pbNoMoreData A flag to indicate that the fetch has

gone past the end of the available
source data. If there are 10 rows of
source data, set this flag when MapX
tries to fetch the 1 th.

MapInfo MapX Developer Guide v4.5 731

Custom Dataset Support

Description
Fetches a cell of data from the data source.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

IMMapXStaticDataset::BeginFetc
HRESULT BeginFetch();

Description
Indicates that a fetch sequence is about to begin. Can be used to allocate/set up
resources needed for fetching data.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

IMMapXStaticDataset::EndFetch
HRESULT EndFetch();

Description
Indicates that a fetch sequence has ended. Can be used to free resources that are used
for fetching data.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

The IMMapXColumnInfoContainer Interface

[

732 MapInfo MapX Developer Guide v4.5

 Interfaces

uuid(1e584f00-d2a5-11d0-9da3-00aa00a478cb),
helpstring("IMMapXColumnInfoContainer Interface"),
version(1.0
]
interface IMMapXColumnInfoContainer : IUnknown
{
HRESULT GetColumnInfoByName(
[in] BSTR bstrColumnName,
[out] IMMapXColumnInfo** ppIMMapXColumnInfo);
HRESULT GetColumnInfoByIndex(
[in] long lIndex,
[out] IMMapXColumnInfo** ppIMMapXColumnInfo);
HRESULT GetColumnInfoEnumerator(
[out] IMEnumMapXColumnInfo** ppIMEnumMapXColumnInfo);
}

IMMapXColumnInfoContainer::GetColumnInfoByName
HRESULT GetColumnInfoByName();

[in] BSTR bstrColumnName The name of the source

data column.

[out] IMMapXColumnInfo ** ppIMMapXColumnInfo The ColumnInfo object

identified by
bstrColumnName

Description
Used to retrieve a ColumnInfo object by column name.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

MapInfo MapX Developer Guide v4.5 733

Custom Dataset Support

IMMapXColumnInfoContainer::GetColumnInfoByIndex
HRESULT GetColumnInfoByIndex ();

[in] Long lIndex The index of the source

data column.

[out] IMMapXColumnInfo ** ppIMMapXColumnInfo The ColumnInfo object

identified by lIndex.

Description
Used to retrieve a ColumnInfo object by column number.

Return Value
S_OK is returned on success.

E_OUTOFMEMORY is returned if an out of memory condition is encountered.

E_FAIL is returned on any other failure.

IMMapXColumnInfoContainer::GetColumnInfoEnumerator
HRESULT GetColumnEnumerator( );

[out] IMEnumMapXColumnInfo ** ppIMEnumMapXColumnInfo The enumerator

Description
Used to retrieve a ColumnInfo Enumerator object (an object that implements
(IMMapXEnumColumnInfo). This object can be used to enumerate the collection of
ColumnInfo objects contained in the dataset.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.
E_FAIL is returned on any other failure.

734 MapInfo MapX Developer Guide v4.5

 Interfaces

ColumnInfo Enumerator object overview

The ColumnInfo Enumerator object is used to enumerate the collection of ColumnInfo
objects contained in a DataSet object. It implements the interface
IMEnumMapXColumnInfo (described below)

The IMEnumMapXColumnInfo Interface

[
uuid(96e0f396-caec-11d0-9d99-00aa00a478cb),
helpstring("IMEnumColumnInfo Interface"),
version(1.0)
]
interface IMEnumMapXColumnInfo : IUnknown
{
HRESULT Next([in] ULONG celt, [out] IMMapXColumnInfo **
rgelt, [out] ULONG * pceltFetched);
HRESULT Skip([in] ULONG celt);
HRESULT Reset();
HRESULT Clone([out] IMEnumMapXColumnInfo **
ppIMMapXColumnInfo);
}
IMEnumMapXColumnInfo is an example of a standard enumeration interface, modeled
after IEnumUnknown, which is used to enumerate IMMapXColumnInfo pointers. For
complete documentation of IEnumUnknown, see the OLE32 SDK.

ColumnInfo object overview

The ColumnInfo object contains information about a column of source data. It implements
the interface IMMapXColumnInfo (described below)

The IMMapXColumnInfo Interface

[
uuid(96e0f394-caec-11d0-9d99-00aa00a478cb),
helpstring("IMMapXColumnInfo Interface"),
version(1.0)
]
interface IMMapXColumnInfo : IUnknown
{
HRESULT Init(
[in] BSTR bstrName,
[in] VARTYPE vt,

MapInfo MapX Developer Guide v4.5 735

Custom Dataset Support

[in] long lColNum);

HRESULT GetName([out] BSTR *pbstrName);
HRESULT GetDataType([out] VARTYPE *pvt);
HRESULT GetColumnNumber([out] long *plColNum);

IMMapXColumnInfo::Init
HRESULT Init(

[in] BSTR bstrName The name of the source data column.

[in] VARTYPE vt The type of the source data column.

[out] long lColNum The index of the source data column.

);

Description
Initialize a ColumnInfo object. MapX will never call this method, it is up to the DataSet
object to initialize the ColumnInfo object after it is created. Note that MapX currently
supports only numeric and string data types.

Return Value
S_OK is returned on success.

E_OUTOFMEMORY is returned if an out of memory condition is encountered.

E_FAIL is returned on any other failure.

IMMapXColumnInfo::GetName
HRESULT GetName(

[out] BSTR * pbstrName

The name of );
the source
data column.

736 MapInfo MapX Developer Guide v4.5

 Interfaces

Description
Retrieves the name of the source data column.

Return Value
S_OK is returned on success.
E_OUTOFMEMORY is returned if an out of memory condition is encountered.

E_FAIL is returned on any other failure.

IMMapXColumnInfo::GetDataType
HRESULT GetDataType(

[out]VARTYPE *pvtThe type of the source data column.);

Description
Retrieves the data type of the source data column. Note that MapX currently supports only
numeric and string data types.

Return Value
S_OK is returned on success.

E_OUTOFMEMORY is returned if an out of memory condition is encountered.

E_FAIL is returned on any other failure.

IMMapXColumnInfo::GetColumnNumber
HRESULT GetColumnNumber(

[out]long *pColNumThe column number of the source data column.);

Description
Retrieves the column number of the source data column.

Return Value
S_OK is returned on success.

E_OUTOFMEMORY is returned if an out of memory condition is encountered.

E_FAIL is returned on any other failure.

MapInfo MapX Developer Guide v4.5 737

Custom Dataset Support

738 MapInfo MapX Developer Guide v4.5

 Index
A collection), 495 (Fields Collection), 347
Add method (Selection AddStringField method (Fields
Abbreviations property (Find collection), 498 collection), 347
object), 351 Add method (Themes AddSymbol method
ABC‡Eƒ properties (Affine Collection), 534 (Annotations collection), 270
Transform object), 267 Add method (Variables AddText method (Annotations
AboutBox method collection), 558 collection), 271
(MapObject), 435 AddByID method (Features AddUserDrawLayer method
Abs( ) function, 623 collection), 319 (Layers collection), 408
Accessing remote spatial data AddDateField method (Fields AddXY method (Point
attribute data, 181–182 collection), 345 object), 481
caching, 182–183 AddFeature method (Layer Affine transformations, 202
DBMS servers, 168 object), 381 AffineTransform object, 267
LayerInfo parameters, 175 AddFeatureToolUsed AffineTransform property
Event, 567 (CoordSys object), 285
mapping with X/Y
columns, 170 AddField method (DataSet AggregationFunction property
object), 293 (Field object), 343
ODBC connection
string, 177–178 AddFloatField (Fields AggregationFunctionConstant
performance issues, 182 collection), 345 s, 591
AddGeosetLayers method AllFeatures method (Layer
Accessing remote spatial tables
(Layers collection), 406 object), 382
making mappable, 186–187
Adding AllOthersCategory property
MapInfo Map Map control, 58–59 (IndividualValueCategories),
Catalog, 183–187
map to Visual Basic 369
specifying styles, 188–188 form, 60–61 AllOthersCategory property
Acos( ) function, 623 Adding data (RangeCategories
ActiveAnnotation method data binding, 97–98 collection), 483
(Annotations collection), 270 AllOthersText property
AddIntegerField (Fileds
Add method (DataSets (LegendTexts collection), 429
Collection), 346
collection), 300 AllowEmptyRanges property
AddLogicalField method
Add method (Features (ThemeProperties
(Fields collection), 346
collection), 318 object), 540
AddNumericField method
Add method (Fields Animation layers, 92
(Fields Collection), 346
collection), 344 AnimationLayer property
AddParameter method
Add method (Layers (Layers collection), 409
(LayerInfo object), 419
Collection), 405 Annotation object, 269
AddressOutOfRange property
Add method (Parts AnnotationAdded event, 568
(FindResult object), 361
collection), 477 AnnotationChanged event, 568
AddServerLayer method
Add method (Point object), 481 AnnotationChangedTypeCons
(Layers collection), 406
Add method (RowValues tants, 592
AddSmallIntField method
Index

Annotations, 91 BarFramed property object), 549

Annotations collection, 269 (ThemeProperties Bounds property (CoordSys
properties and object), 548 object), 286
methods, 38–39 BarFrameStyle Bounds property (Feature
Annotations property (ThemeProperties object), 311
(MapObject), 435 object), 548 Bounds property (Layer
AnnotationTypeConstants, 59 BarGraduatedStack property object), 384
2 (ThemeProperties Bounds property (Layers
ApplyAttribute property object), 547 collection), 410
(ThemeProperties BarIndependentScale property Bounds property
object), 553 (ThemeProperties (MapObject), 436
ApplyAttributeConstants, 592 object), 547 Brush styles
Area property (Feature BarStacked property in remote spatial
object), 310 (ThemeProperties tables, 188
Area( ) function, 624 object), 547 BufferFeatures method
AreaUnit property BarWidth property (FeatureFactory object), 323
(MapObject), 435 (ThemeProperties BuildSourceRows property
AreaUnitConstants, 592 object), 548 (Datasets collection), 294
Asc( ) function, 625 BeginAccess method (Layer Built-in helper dialogs
Asin( ) function, 626 object), 383 Visual C++, 224–225
Atn( ) function, 626 BeginDate property
Attach method (Feature (NotesQueryInfo C
object), 310 object), 469
Attribute data Binding data, 50 Caching
accessing, 181–182 BindLayer data binding accessing remote spatial
binding, 102–102 BindLayer object, 105–107 data, 182–183
AutoGenerate property BindLayer Caption property (Feature
(LegendText object), 430 parameter, 102–102 object), 312
AutoLabel property (Layer displaying data as Caption property (Graphic
points, 105–108 object), 367
object), 383
Automatic labeling BindLayer object, 275 Caption property (Title
setting for a layer, 82 Bitmap files object), 555
export format, 247 CenterX property
AutoRecompute property
BitmapSymbol Keys, 668 (MapObject), 436
(Theme object), 530
BitmapSymbol object, 281 CenterX property, CenterY
AutoRedraw property
BitmapSymbols collection, 281 property (Feature
(MapObject), 435
Bivariate thematic maps, 146– object), 312
Azimuth property (CoordSys
147 CenterY property
object), 286
BMP files (MapObject), 437
export format, 247 Centroid property (Geoset
B BodyTextStyle property
object), 365
Centroid( ) function, 628
(Legend object), 422
BackColor property CentroidX( ) function, 629
Border property (Title
(MapObject), 436 CentroidY( ) function, 629
object), 555
Bar chart maps Choose Projection dialog
BorderStyle property
thematic map type, 143– displaying at run time, 196
144 (ThemeProperties

740 MapInfo MapX Developer Guide v4.5

 Index

Chr$( ) function, 630 CompactTitleStyle property (BitmapSymbol object), 282

CircleTypeConstants, 594 (Legend object), 422 Count property (DataSets
ClearCustomLabels method Comparison operators, 615 collection), 302
(Layer object), 384 Component tables Count property (Features
ClearSelection method (Layers drilldown layers, 160 collection), 320
collection), 410 ComputeTheme property Count property (Fields
ClearSelection method (Theme object), 530 collection), 348
(Selection collection), 498 ConnectString property Count property (Geoset
ClipLine method (ODBC QueryInfo collection), 365
(MapObject), 437 object), 475 Count property (Layers
CliplineV method Constants, 591 collection), 410
(MapObject), 439 aggregation functions, 104 Count property (LegendTexts
Clone method (CoordSys datasets, 99 object), 430
object), 286 Count property
range distribution, 138–
Clone method (Feature 139 (MultivarCategories
object), 311 theme type, 133 collection), 467
Clone method (Features Count property (Parts
Tool type, 241
collection), 320 collection), 477
Clone method (RowValues ConversionConstants, 596 Count property (Point
object), 496 ConvertCoord method object), 482
Clone method (Selection (MapObject), 440 Count property
collection), 499 ConvertCoordV method (RangeCategories
Clone method (Style (MapObject), 441 collection), 483
object), 508 Coordinate System Count property
Clone method (Variables Parameters, 198 (ResolveObjects
collection), 559 Coordinate systems collection), 492
CloseMatchMax property CoordSys object, 192 Count property (RowValues
(Find object), 351 interpreting type collection), 494
ClosestAddr property (Find numbers, 201–202 Count property (Selection
object), 352 MAPINFOW.PRJ collection), 497
file, 199–202
ColorConstants, 594 Count property (SourceRow
ColorMethod property reference material, 207 object), 505
(ThemeProperties specifying for a map, 193– Count property (Theme
object), 553 194 object), 536
COM objects CoordSys object, 285 Count property (Variables
See Static Dataset objects obtaining, 192 collection), 558
CombineFeatures method querying properties, 193 Creatable
(FeatureFactory object), 325 CoordSys property objects, 39–40
Common method (Features (BindLayer object), 275 Createable Objects in
collection), 320 CoordSys property (Layer MapX, 39
Common method (Selection object), 384 CreateArc method
collection), 499 CoordSysTypeConstants, 597 (FeatureFactory object), 326
Compact property (Legend Cos( ) function, 631 CreateCircularRegion method
object), 422 Count property (Annotations (FeatureFactory object), 328
CompactTitle property collection), 271 CreateCustomTool method
(Legend object), 422 Count property (MapObject), 441

MapInfo MapX Developer Guide v4.5 741

Index

CreateEllipticalRegion creating, 239–243 geofield parameter, 100–

method (FeatureFactory 102
drilldown tools, 163
object), 331 types, 100, 111–112
polygon drawing
CreateLayer method (Layers tools, 243–243 Database property
collection), 410 type constants, 241 (NotesQueryInfo
CreateLine method object), 469
Visual C++ example, 219–
(FeatureFactory object), 332 220 Database property
CreateRegion method writing tool handler, 241– (NotesViewInfo object), 473
(FeatureFactory object), 332 242 DataField property
CreateSymbol method (LabelProperties object), 373
(FeatureFactory object), 333 DataMax property (Theme
CreateText method
D
object), 531
(FeatureFactory object), 333 Data Access Object Recordset DataMin property (Theme
Creating data source type, 100, 111– object), 531
callouts for labels, 90 111 DataMismatch event, 569
custom tools, 239–243 Data aggregation DataSet object, 291
drilldown tools, 163 Fields.Add method, 104 DataSet property
Using the Fields.Add (LabelProperties object), 374
Features collection, 117–
118 method, 103 DataSet property
geosets, 709–709 Data binding (MapObject), 443
adding data to a map, 97– Dataset property (RowValue
map features, 122 98 object), 494
map in Visual C++ BindLayer, 105–108 Dataset Support, 727
dialog, 226–229
data source types, 96, 111– DataSetGeoField property
MapInfo Map 112
Catalog, 184–185 (MapObject), 444
DataSet object, 98 Datasets
MapX control in Visual
C++, 214 datasets, 37 data binding, 37, 50, 98
menu items in Visual DataSets.Add method, 98 Fields collection, 103
C++, 215–217 Dynamic parameter, 103 inserting in Visual Basic
permanent point sample, 65
layer, 108 Fields parameter, 102
name parameter, 100
polygon drawing Geodictionary, 36–37
refreshing, 110
tools, 243–243 in Visual C++, 221–222
Themes collection, 130–
RollUp tools, 164 making point layer 133
selections at specific permanent, 108
type constants, 99
point, 121 MapX events used in, 110–
110 DataSets collection, 291
themes, 130–133
registering MapInfo working with DataSet
CurrencyFormat property tables, 719 objects, 98
(Legend object), 423 DataSets property (Layer
SourceData parameter, 99
CurrentTool property collection), 385
(MapObject), 443 unbound datasets, 113 DataSets property
CursorConstants, 598 using Geodictionary, 109– (MapObject), 444
Custom Dataset Support, 727 110
DataSetTheme property
Custom dataset support, 727– Data sources (MapObject), 444
734 data binding, 50 DatasetTypeConstants, 599
Custom tools Fields.Add method, 103 DataSource property (ODBC

742 MapInfo MapX Developer Guide v4.5

 Index

QueryInfo object), 476 (ThemeProperties Drilldown tools

DataValue property object), 541 creating, 163
(ThemeProperties DistribMethodConstants, 600 DrilldownAddFeatures
object), 540 Dot density maps method (Layer object), 386
Date Clauses, 618 thematic map type, 141– DrilldownRemoveFeatures
Date Comparison, 616 142
method (Layer object), 387
Datum object, 305 DotColor property DrilldownReset method
Datum property (CoordSys (ThemeProperties (Layer object), 388
object), 286 object), 551 Duplicate property
DBMS servers DotSize property (LabelProperties object), 374
accessing remote spatial (ThemeProperties Dynamic parameter
data, 168 object), 542 dynamic data binding, 103
Decimals property (Field DotSizeConstants, 600
object), 343 Drawing layers, 93–94
DefaultConversionResolution DrawLabelsAfter property E
property (MapObject), 445 (Layer object), 386 Eccentricity property (Datum
DefaultNumericValue DrawLineSample method object), 305
property (NotesQueryInfo (Style object), 509 Editable (Layer object), 388
object), 470 DrawRegionSample method Editable property
DefaultStringValue property (Style object), 509 (Annotations collection), 272
(NotesQueryInfo DrawSymbolSample method Editable property (Title
object), 470 (Style object), 510 object), 555
DefaultStyle property (Map DrawTextSample method Editing
object), 446 (Style object), 511 map features, 122–124
DeformatNumber$( ) DrawUserLayer Event, 570
Ellipsoid property (Datum
function, 632 Drilldown applications
object), 305
DeleteFeature method (Layer component table
requirements, 160 EndAccess method (Layer
object), 385
object), 388
Deleting drilldown table
requirements, 160– EndDate property
map features, 124
162 (NotesQueryInfo
Delphi object), 470
drilldown tool, 163
installing MapX, 67 EraseFeature method
procedure summary, 159
Delphi Native (FeatureFactory object), 334
RollUp tool, 164
data source type, 100 Error Codes, 579
Dispatch ID Table, 673 Drilldown layers Events, 565
DisplayCoordSys property description, 156–157 ExactMatch property
(Map object), 446 limitations and (FindResult object), 361
requirements, 165
Displaying Exp( ) function, 634
data as points, 105–108 related constants, 166 ExportFormatConstants, 600
labels, 89 related methods and Exporting
properties, 166 maps, 246–247
raster images, 91 resetting, 165
Distance method (Map selection pattern, 247
terms and concepts, 158–
object), 447 158 ExportLegend method
Distance( ) function, 633 (Legend object), 423
Drilldown tables
DistMethod property ExportLineSample method
metadata keys, 162–162

MapInfo MapX Developer Guide v4.5 743

Index

(Style object), 511 creating, 117–118 FindRC property (FindFeature

ExportMap method (Map description, 116 object), 358
object), 448 modifying, 118 FindRC property (FindResult
ExportRegionSample method object), 362
FeatureTypeConstants, 601
(Style object), 512 FindResult object, 361
Field object, 341
ExportSelection property Fix( ) function, 635
Field property (RowValue
(Map object), 449 Font Attributes, 124
object), 494
ExportSymbolSample method Format$( ) function, 636
Fields collection, 341
(Style object), 513 FormatDate$( ) function, 638
data binding, 103
ExportTextSample method FormatNumber$( )
(Style object), 514 Fields parameter function, 639
Expressions, 611 determining data source FullTextSearch property
fields, 102
(NotesQueryInfo
Fields property (DataSet
object), 470
F object), 294
Functions, 621
Fields property (Theme
FalseEasting, FalseNorthing object), 531
properties (CoordSys FieldTypeConstants, 601 G
object), 286 Filespec property (BindLayer
Feature object, 309 object), 276 Geodictionary
Feature objects FileSpec property (Layer data binding, 109–110
properties, 119–119 object), 390 geodictionary file, 720–721
FeatureEditMode property Fill styles matching data source to a
(Map object), 449 in remote spatial layer, 36
FeatureEditModeConstants, 6 tables, 188 registering layers, 725
01 FillPatternConstants, 602 Geodictionary Manager
FeatureFactory Find object, 351 command line
methods, 122–123 locating map options, 719, 725–726
FeatureFactory object, 323 features, 152–?? registering MapInfo
FeatureFactory property (Map result codes, 153–153 tables, 719
object), 450 Find object, Using running, 721–724
FeatureID property (Feature locating map features, ??– utility location, 695
object), 312 152
GeoDictionary property (Map
FeatureID property Find property (Layer object), 450
(FindMatch object), 359 object), 390 Geofield parameter
FeatureIDFromFeatureName FindDataset property (Find data sources, 100–102
method (Layer object), 389 object), 353
GeoField property (DataSet
FeatureKey property (Feature FindFeature object, 357
object), 294
object), 313 storing feature object
properties, ??–153 Geoset Keys, 663
FeatureKey property
FindFeature object, Using Geoset keys, 663
(FindMatch object), 359
storing feature object Geoset Manager
FeatureKeyFromFeatureNam
properties, 152–?? labels, 714–716
e method (Layer object), 390
Features FindField property (Find Layer Control
object), 353 options, 712–716
types, 50
FindMatch object, 359 Map menu options, 710–
Features collection, 309 716
FindMatches collection, 359

744 MapInfo MapX Developer Guide v4.5

 Index

Pan tool, 711 H Interactive labeling, 90

setting projections, 716– IntersectFeatures method
716 Height property (Legend (FeatureFactory object), 336
setting zoom level, 710– object), 423 IntersectionNotFound
712 Height property (Rectangle property (FindResult
utility location, 695 object), 487 object), 363
View menu options, 717 hWnd property (Map IntersectionPointConstants, 60
object), 452 2
Geoset object, 365
GeoSet property (Map IntersectionPoints method
(FeatureFactory object), 337
object), 451 I IntersectionTest method
Geosets
creating, 709–709 Independent property (FeatureFactory object), 339
(ThemeProperties IntersectionTestConstants, 602
list of, 44–49
object), 542 Invalidate method (Layer
opening, 707–708 object), 392
Individual values maps
overview, 35 IsPointVisible method (Map
thematic map type, 135–
saving, 710 136 object), 453
Geosets collection, 365 IndividualValueCategories Item method (Variables
GeoSets property (Map collection, 369 collection), 560
object), 451 IndividualValueCategories Item property (Annotations
GeoSetWidth property (Map property (ThemeProperties collection), 272
object), 452 object), 543 Item property (BitmapSymbol
GetDrilldownFeaturesByID IndividualValueCategory object), 282
method (Layer object), 391 object, 369 Item property (DataSets
GetFeatureByID method InflectionColor property collection), 302
(Layer object), 391 (ThemeProperties Item property (Features
GetFeatureByKey method object), 553 collection), 320, 498
(Layer object), 392 InflectionRange property Item property (Fields
GIF files (ThemeProperties collection), 348
export format, 247 object), 552 Item property (Geoset
Graduated property InflectRanges property collection), 366
(ThemeProperties (ThemeProperties Item property
object), 542 object), 552 (IndividualValueCategories
Graduated symbol maps InfotipPopupDelay property collection), 371
thematic map type, 140– (Map object), 453 Item property (Layers
141 InfotipSupport property (Map collection), 412
GraduateSizeBy property object), 452 Item property (LegendTexts
(ThemeProperties InsertionLayer (Layers object), 431
object), 550 object), 411 Item property
Graduation Constants, 602 Installation (MultivarCategories
Graphic object, 367 procedure, 56–57 collection), 467
Graphic property (Annotation product components, 54– Item property (Parts
object), 269 55 collection), 478
Graphics Interchange Format system requirements, 54 Item property (Points
files InStr( ) function, 640 collection), 482
export format, 247 Int( ) function, 641 Item property

MapInfo MapX Developer Guide v4.5 745

Index

(RangeCategories LabelZoom property Layers property (Map

collection), 484 (LabelProperties object), 374 object), 453
Item property (ResolveObjects LabelZoomMax property LayersDlg method (Layers
collection), 492 (LabelProperties object), 375 collection), 412
Item property (RowValues LabelZoomMin property LayerSrvLayerOptions, 603
collection), 494 (LabelProperties object), 375 LayerType property
Item property (SourceRow Layer Control (BindLayer object), 277
object), 505 Geoset Manager, 712–716 LayerTypeConstants, 604
Item property (Theme Layer Control dialog LCase$( ) function, 641
object), 536 calling, 78 Left property (Legend
display options, 79 object), 424
Left$( ) function, 642
J Layer object, 379
Legend object, 421
layer properties, 82–82
JPEG files Legend objects
Layer property (DataSet with Theme objects, 134,
export format, 247 object), 294 150
Layer property (Feature Legend property (Theme
K object), 314 object), 532
Layer property (Theme LegendDlg method (Legend
KeyField property (Layer object), 531 object), 424
object), 393 LayerBeginAccessConstants, 6 LegendText object, 429
KeyLength property 03 LegendTexts, 429
(BindLayer object), 276 LayerEndAccessConstants, 60 LegendTexts collection, 429
KeyValue property (Feature 3 LegendTexts property
object), 313 LayerInfo object, 415 (Legend object), 425
parameters, 175 Length property (Feature
L LayerInfoTypeConstants, 603 object), 314
LayerName property Line styles
Label tool, 90 (BindLayer object), 276 in remote spatial
LabelAtPoint method (Layer Layers tables, 188
object), 393 description, 74 LineColor property (Style
LabelMax property draw order in object), 515
(LabelProperties object), 374 collection, 84 LineInterleaved property
LabelPoint property (Feature generating labels, 88–90 (Style object), 515
object), 314 registering in LineStyle property (Style
LabelProperties object, 373 Geodictionary, 725 object), 515
controlling label user draw layers, 93–94 LineStyleCount property
display, 89–90 (Style object), 517
zoom layering, 86–88
LabelProperties property LineSupportsInterleave
(Layer object), 393 Layers collection, 379
property (Style object), 517
Labels checking layer feature
type, 85 LineType property
controlling display, 89 (LabelProperties object), 375
checking layer type, 84
generating for a layer, 88– LineTypeConstants, 604
90 methods, 78–82
LineWidth property (Style
in Geoset Manager, 714– obtaining, 74–76 object), 517
716 properties, 77–78 LineWidthUnit property
removing, 90

746 MapInfo MapX Developer Guide v4.5

 Index

(Style object), 517 MapDrawConstants, 604 installation procedure, 56–

Locating map features, 152– MapInfo Map Catalog 57
152 creating, 184–185 key features, 25–26
Log( ) function, 643 making remote tables new for v. 4.0 & 4.01, 6
Logical Comparison, 616 mappable, 183–187 new for v4.5, 4
Logical operators, 617 MapInfo Professional product components, 54–
Lotus Notes creating Map Catalog 55
accessing data via Notes in, 183
function queries, 69 system requirements, 54
MapInfo tables
upgrading v. 2.0
accessing data via Notes data source type, 100, 112– applications to v.
View, 68 112 3.0, 18
data driver importing into MapX applications
installation, 67–68 SpatialWare, 183
upgrading from earlier
data source type, 100, 112 registering in versions, 211
with MapX control, 67 Geodictionary, 36–37,
719 MapX control
LTrim$( ) function, 643 creating in Visual
MAPINFOW.PRJ file C++, 214
customizing, 201
MapX data
M parameters, 199–200 installation notes, 695
using settings, 199–202 sources, 696–705
Map control
adding, 58–59 MapInitialized event, 571 MapX Events, 565
MapPaperHeight property MapX events in Visual
Map creation
(Map object), 454 C++, 217
creatable objects, 39–40
MapPaperWidth property MapX exceptions
geoset overview, 35 (Map object), 454 in Visual C++, 225–226
layers overview, 33 Maps
MatchedFeature property
Map object, 30–30 exporting, 246–247
(FindResult object), 363
map properties, 31–32 printing, 248 Matches property (FindResult
Map features MapScreenHeight property object), 363
creating, 122 (Map object), 454 MatchThreshhold property
deleting, 124 MapScreenWidth property (Map Object), 455
(Map object), 454 Mathematical operators, 614
description, 116
MapUnit property (Map Max property
editing, 122–124
object), 454 (RangeCategories
modifying, 123–123 MapUnitConstants, 604 collection), 484
obtaining for editing, 124 MapViewChanged event, 571 Maximum( ) function, 644
stand-alone, 119–119 MapX MaxNumDocs property
Map layer description, 74 documentation set (NotesQueryInfo
description, 69–70
Map menu object), 471
using Geoset enhancements and MaxSearchTime property
Manager, 710–716 additions to v. 3.0, 16
(Map object), 455
Map object, 433 enhancements and MaxVectorSymbolCharacter
additions to v. 3.5, 13
feature types, 50 property (Style object), 525
enhancements and
properties, 30–30 additions to v. MBR( ) function, 644
MapDraw event, 570 3.5.1, 12 Menu items
creating in Visual

MapInfo MapX Developer Guide v4.5 747

Index

C++, 215–217 N ObjectInfo( ) function, 647

Methods ObjectLen( ) function, 647
accessing in Visual Name parameter Objects
C++, 212 datasets, 100 creatable, 39–40
DataSets collection, 98 Name property ODBC connection string, 177–
FeatureFactory, 122–123 (BitmapSymbol object), 281 178
Fields collection, 103 Name property (DataSet ODBC Connection String
object), 295 Format, 177
Layers collection, 78–82
Name property (Feature ODBC data source type, 100,
Selection collection, 119 object), 315 112
Themes collection, 130– Name property (Field ODBCQueryInfo object, 475
133
object), 343 Offset method (Feature
Mid$( ) function, 645 Name property (FindMatch object), 316
Min property object), 359 Offset method (Point
(RangeCategories Name property (Layer object), 479
collection), 484 object), 394 Offset method (Rectangle
Minimum( ) function, 646 Name property (Theme object), 488
MinVectorSymbolCharacter object), 532 Offset property
property (Style object), 525 NegativeSymbolStyle (LabelProperties object), 376
Modifying property (ThemeProperties OLE_COLOR Values, 671
existing map object), 550 Opening
features, 123–123
Node Selecting and geosets, 707–708
Features collection, 118 Editing, 234 Operators, 613
themes, 147–149 Nodes property (Feature Oracle Sparial Reference
Month( ) function, 647 object), 315 support, 173
MouseIcon property (Map NoFeatures method (Layer Oracle Spatial Connection
object), 455 object), 394 String Format, 178
MousePointer property (Map Notes Oracle8i support, 171–174
object), 456 accessing data via Notes Oracle8i v8.15 and v8.16
MouseWheel Event, 571 View, 68
Support, 171
MouseWheelSupportConstant with MapX control, 67 OriginLatitude,
s, 605 NotesQueryInfo object, 469 OriginLongitude properties
Move method (Layers NotesViewInfo object, 473 (CoordSys object), 287
collection), 413 Numerical Comparison, 615 OtherBoundary property
MrSID, 264 NumericCoordSys property (Find object), 354
MultipleMatches property (Map object), 458 Overlap property
(FindResult object), 363 NumItems property (LabelProperties object), 376
MultivarCategories (IndividualValueCategories OverrideStyle property (Layer
collection, 467 collection), 371 object), 395
MultivarCategories property NumRanges property
(ThemeProperties (ThemeProperties
object), 543 object), 543 P
MultivarCategory object, 467
Pan method (Map object), 458
O Pan tool
Geoset Manager, 711
Object editing tools, 234

748 MapInfo MapX Developer Guide v4.5

 Index

PanAnimationLayer property object), 546 Projections

(Map object), 459 PieStartAngle property, 546 setting in Geoset
PaperHeight property PNG files Manager, 716–716
(Legend object), 425 export format, 247 Proper$( ) function, 649
PaperUnit property (Map Point object, 479 Properties
object), 459 Point property (Feature accessing in Visual
PaperUnitConstants, 605 C++, 212
object), 317
PaperWidth property (Legend Point reference binding, 107 Annotations
object), 425 collection, 38–39
Point styles
Parallel property BindLayer object, 105–107
in remote spatial
(LabelProperties object), 376 tables, 188 Feature object, 119–119
PartialSegments property Points collection, 479 Layer object, 82–82
(LabelProperties object), 376 Polygon drawing tools, 243– Layers collection, 77–78
Parts collection, 477 243 Map object, 30–30
Parts property (Feature PolyToolFlagConstants, 606
Theme objects, 133–134
object), 316 PolyToolUsed Event, 573
PathName property (Geoset Portable Network Graphics Properties property (Theme
object), 365 files object), 532
Pen styles export format, 247 Property Page
in remote spatial modifying a map, 31–32
Position of labels, 89
tables, 188 PropertyPage method (Map
Position property (Graphic
PenStyleConstants, 606 object), 367 object), 460
Perimeter property (Feature Position property PSD files
object), 316 (LabelProperties object), 377 export format, 247
Perimeter( ) function, 648 Position property (Title
Photoshop files object), 556 Q
export format, 247 PositionConstants, 606
PickCoordSys method PositiveSymbolStyle property Query property
(CoordSys object), 287 (ThemeProperties (NotesQueryInfo
PickLine method (Style object), 549 object), 471
object), 517 PowerBuilder
PickRegion method (Style data source type, 100, 113
object), 518
R
inserting Map control, 66
PickSymbol method (Style Range property (CoordSys
Precision (Field object), 343
object), 518 object), 288
PredominantFeatureType
PickText method (Style RangeCategories
property (Layer object), 395
object), 518 collection, 483
PreferCompactLegends
Pie chart maps RangeCategories property
property (Map object), 459
thematic map type, 145– (ThemeProperties
146 PrimeMeridian property
(Datum object), 306 object), 544
PieClockwise property, 546 RangeCategory object, 483
Printing a map, 248
PieGraduated property Ranged maps
PrintLegend method (Legend
(ThemeProperties range distribution
object), 425
object), 546 types, 138–139
PrintMap method (Map
PieHalfPies property thematic map type, 137–
object), 459
(ThemeProperties 139
Product features, 25–26

MapInfo MapX Developer Guide v4.5 749

Index

Raster images RegionBorderStyle property collection), 499

displaying, 91 (Style object), 519 Remove method (Theme
ReadOnly property (Dataset RegionBorderWidth property object), 537
object), 296 (Style object), 519 Remove method (Variables
ReadOnly property RegionBorderWidthUnit collection), 560
(RowValue object), 493 property (Style object), 519 RemoveAll method
ReadOnly property RegionColor property (Style (Annotations collection), 273
(RowValues collection), 494 object), 519 RemoveAll method (DataSets
Rectangle object, 487 RegionPattern property (Style collection), 303
Redistributing Your MapX object), 520 RemoveAll method (Fields
Application With RegionTransparent property collection), 349
MrSID, 264 (Style object), 520 RemoveAll method (Layers
RedrawInterval property Remote spatial data collection), 414
(Map object), 460 accessing, 168 RemoveAll method (Parts
RefColumn1 property accessing attribute collection), 478
(BindLayer object), 278 data, 181–182 RemoveAll method (Point
RefColumn2 property caching, 182–183 object), 482
(BindLayer object), 278 LayerInfo parameters, 175 RemoveAll method
ReferenceLayer property mapping with X/Y (RowValues collection), 496
(BindLayer object), 279 columns, 170 RemoveAll method (Theme
ReferenceLayerfield property ODBC connection object), 537
(BindLayer object), 279 string, 177–178 RemoveAll method (Variables
RefineDataset property (Find performance issues, 182 collection), 561
object), 354 Remote spatial tables RemoveByID method
RefineField property (Find making mappable, 186– (Features collection), 321
object), 354 187 Removing
RefineLayer property (Find MapInfo Map labels, 90
object), 355 Catalog, 183–187 Replace method (Features
RefineRegion property specifying styles, 188–188 collection), 322
(FindResult object), 363 Remove method (Annotations Replace method (Selection
Refining boundaries collection), 272 collection), 500
feature searches, 152 Remove method (DataSets RequestData event, 574
Refresh method collection), 303 ResolveDataBind event, 574
(BitmapSymbol Remove method (Features ResolveDataBindConstants, 6
collection), 282 collection), 321 07
Refresh method (DataSet Remove method (Fields ResolveDataBindEx event, 575
object), 295 collection), 348 ResolveObject object, 491
Refresh method (Layer Remove method (Layers ResolveObjects collection, 491
object), 395 collection), 413 Restore method (DataSets
Refresh method (Map Remove method (Parts collection), 297
object), 461 collection), 478 Result codes
Refreshing datasets, 110 Remove method (Point Find object, 153–153
RegionBackColor property object), 482 Right$( ) function, 650
(Style object), 518 Remove method (RowValues RollUp tools
RegionBorderColor property object), 495 creating, 164
(Style object), 519 Remove method (Selection RotateX, RotateY, RotateZ

750 MapInfo MapX Developer Guide v4.5

 Index

properties (Datum Search type constants Basic 6, 65

object), 306 selections, 121 within a distance in Visual
Rotation property (Map SearchAtPoint method (Layer Basic 6, 65
object), 461 object), 397 SelectionStyle property (Map
Round( ) function, 650 SearchEx method (Find object), 462
RoundBy property object), 353 SelectionTypeConstants, 607
(ThemeProperties SearchPath property (Map SemiMajorAxis,
object), 551 object), 462 SemiMinorAxis properties
RoundRanges property SearchTypeConstants, 607 (Datum object), 307
(ThemeProperties SearchWithinDistance method Server (NotesViewInfo
object), 551 (Layer object), 398 object), 473
Row property (SourceRow SearchWithinFeature method Server property
object), 505 (Layer object), 399 (NotesQueryInfo
RowCount property (DataSet SearchWithinRectangle object), 471
object), 296 method (Layer object), 400 Set method (AffineTransform
RowValue object, 493 Secondary Geofield object), 268
RowValues collection, 493 parameter, 102 Set method (CoordSys
RowValues property (Dataset SecondaryGeoField property object), 289
object), 295 (DataSet object), 297 Set method (Datum
RTrim$( ) function, 651 Selectable property (Layer object), 307
object), 400 Set method (Point object), 480
SelectAll method (Selection Set method (Rectangle
S collection), 500 object), 488
Sample application SelectByID method (Selection SetSize method (Map
Visual C++, 210 collection), 501 object), 463
SelectByPoint method Sgn( ) function, 652
Sample applications
(Selection collection), 501 Shapefile (.shp), 415
additional programs, 27
SelectByRadius method Shortcut menus
Sample Connection
(Selection collection), 502 adding in Visual C++, 223
Strings, 178
SelectByRectangle method ShowCentroids (Layer
Sample Geoset, 663
(Selection collection), 503 object), 401
SaveMapAsGeoset method
SelectByRegion method ShowCount property (Legend
(Map object), 461
(Selection collection), 503 object), 426
Saving
Selection collection, 497 ShowEmptyRanges property
geosets, 710
description, 116 (Legend object), 426
ScaleAdjust property (Datum
methods, 119 ShowLineDirection (Layer
object), 306
Selection property (Layer object), 401
ScaleFactor property
object), 401 ShowNegativeValues
(CoordSys object), 289
SelectionChanged event, 576 property (ThemeProperties
Score property (FindMatch
Selections object), 549
object), 360
creating at specific ShowNodes (Layer
SDO_GEOMETRY, 172
point, 121 object), 401
Search method (Find
search type constants, 121 Sin( ) function, 652
object), 355
SelectionChangedEvent, 1 Size property
Search method (Layer
21–121 (ThemeProperties
object), 396
using queries in Visual object), 544

MapInfo MapX Developer Guide v4.5 751

Index

Smooth property (Feature Style property (Feature SymbolFontBackColor

object), 317 object), 317 property (Style object), 524
SourceData parameter Style property (Graphic SymbolFontColor property
data binding, 99 object), 368 (Style object), 524
SourceMatch property Style property SymbolFontHalo property
(ResolveObject object), 491 (IndividualValueCategories (Style object), 524
SourceRow object, 505 collection), 371 SymbolFontOpaque property
SourceRows collection, 505 Style property (Style object), 524
SourceRows property (DataSet (LabelProperties object), 377 SymbolFontRotation property
object), 297 Style property (Layer (Style object), 525
Space$( ) function, 653 object), 401 SymbolFontShadow property
SpatialWare Style property (Style object), 525
importing MapInfo tables (MultivarCategory SymbolStyle property
into, 183 object), 468 (ThemeProperties
troubleshooting MapX Style property object), 545
applications, 189–189 (RangeCategories SymbolType property (Style
Specifying styles collection), 485 object), 528
labels, 90 Styles SymbolTypeConstants, 607
SpreadBy property in remote spatial SymbolVectorColor property
(ThemeProperties tables, 188 (Style object), 526
object), 544 StyleUnitConstants, 607 SymbolVectorSize property
SpreadByConstants, 607 Substitute property (Style object), 526
SqlQuery property (ODBC (FindResult object), 364 System requirements
QueryInfo object), 476 SubTitle property (Legend for Oracle8i, 171
Sqr( ) function, 653 object), 426 MapX, 54
SRID, 173 SubTitleStyle property
Stand-alone features, 119–119 (Legend object), 427
SupportsBitmapSymbols T
Standard tools
available types, 233–233 property (Style object), 520 Tab-delimited data
Symbol styles data source type, 100, 112–
StandardParallelOne,
in remote spatial 112
StandardParallelTwo tables, 188
properties (CoordSys TableMatch property
SymbolBitmapColor property (ResolveObject object), 491
object), 290
(Style object), 521 TableName property
Static dataset objects
SymbolBitmapName property (ResolveObject object), 491
interfaces, 728–734
(Style object), 521 Tagged Image File Format files
registration, 727–728 SymbolBitmapOverrideColor export format, 247
Str$( ) function, 657 property (Style object), 522
String Clauses, 617 Tan( ) function, 658
SymbolBitmapSize property
String Comparison, 615 Text objects, 91
(Style object), 522
String operator, 615 Text property (LegendText
SymbolBitmapTransparent
StringCompare( ) object), 430
property (Style object), 523
function, 654 TextFont property (Style
SymbolCharacter property
StringCompareIntl( ) object), 526
(Style object), 523
function, 655 TextFontAllCaps property
SymbolFont property (Style
StringToDate( ) function, 656 (Style object), 526
object), 523
Style object, 507 TextFontBackColor property

752 MapInfo MapX Developer Guide v4.5

 Index

(Style object), 526 TIF files U

TextFontColor property (Style export format, 247
object), 527 Title object, 555 UCase$( ) function, 659
TextFontDblSpace property Title property (Legend Unbound datasets
(Style object), 527 object), 427 data source type, 100, 113
TextFontHalo property (Style Title property (Map Units property
object), 527 object), 464 (AffineTransform
TextFontOpaque property TitleText property (Map object), 268
(Style object), 527 object), 464 Units property (CoordSys
TextFontRotation property Tool handler, 241–242 object), 290
(Style object), 528 ToolConstants, 608 Unload method
TextFontShadow property ToolFlagConstants, 609 (BitmapSymbol
(Style object), 527 Tools collection), 283
TextStyle property (Title object editing, 234 Update method (Feature
object), 556 polygon drawing object), 318
Thematic legends, 134, 150 tools, 243–243 UpdateFeature method (Layer
Thematic maps specifying current object), 402
bivariate, 146–147 tool, 232 Upgrading
types, 135–146 standard types, 233–233 MapX 2.0 applications to
v. 3.0, 18
using data, 129–130 Visual Basic 6.0 sample, 64
User draw layers, 93–94
Theme object, 529 ToolTypeConstants, 609
UserName property (Geoset
Theme objects ToolUsed event, 576
object), 365
properties, 133–134 ToolUsedEvent, 242–242
Using the Fields.Add method
ThemeDlg method, 147– Top property (Legend
147 adding column data as a
object), 427 field, 103
ThemeDlg method (Theme True Type Font Symbol
object), 533 Keys, 668
ThemeModifyRequested Type property (Annotation V
event, 576 object), 270 Val( ) function, 659
ThemeProperties object, 539 Type property (CoordSys Value method (DataSet
ThemeProperties property object), 290 object), 298
(Theme object), 534 Type property (DataSet Value property (DataSet
Themes object), 298 object), 298
creating, 130–133 Type property (Feature Value property
inserting in Visual Basic object), 317 (IndividualValueCategories
sample, 65 Type property (Field collection), 372
modifying, 147–149 object), 344 Value property (RowValue
type constants, 133 Type property (Layer object), 494
object), 402 Value property (Variable
Themes collection, 529
Type property (LayerInfo object), 558
methods, 130–133
object), 418 ValuePerDot property
ThemeProperties Type property (Theme
object, 148–149 (ThemeProperties
object), 534 object), 545
Themes property (DataSet
object), 298 Variable object and Variables
ThemeTypeConstants, 608 collection, 557

MapInfo MapX Developer Guide v4.5 753

Index

Version property (Map data binding, 221–222 object), 489

object), 464 including MapX.cpp X-Y coordinates
View (NotesViewInfo file, 213 displaying as points, 107–
object), 473 MapX events using 107
View menu C++, 217 specifying in a different
using Geoset MapX exceptions, 225–226 CoordSys, 195–196
Manager, 717
MapX properties and
Visible property methods, 212 Y
(LabelProperties object), 377 sample application, 210
Visible property (Layer Y property (Graphic
upgrading applications to
object), 404 MapX 4.0, 60 object), 368
Visible property (Legend upgrading MapX Y property (Point object), 480
object), 428 applications, 211 Y property (Title object), 556
Visible property (LegendText Year( ) function, 661
object), 430 YMax property (Rectangle
W object), 489
Visible property (Theme
object), 534 WaitCursorEnabled property YMin property (Rectangle
Visible property (Title (Map object), 464 object), 489
object), 556 Weekday( ) function, 660
Visual Basic Width (Field object), 343
adding a map, 60–61
Z
Width property (Legend
adding Map control object), 428 ZIP Code data
to, 58–58 Width property (Rectangle displaying as points, 107–
upgrading application to object), 489 108
MapX 4.0, 59–59 Width property Zoom layering
using Notes Query (ThemeProperties labels, 89
from, 69 object), 545 map layers, 86–88
version 4 example, 62–63 Windows metafile setting for a layer, 83–83
version 6 example, 63–66 export format, 247
Zoom level
Visual C++ WMF files setting in Geoset
adding Map control to, 58 export format, 247 Manager, 710–712
adding shortcut Zoom property (Map
menus, 223
X object), 465
built-in helper ZoomLayer property (Layer
dialogs, 224–225 X property (Graphic object), 404
creating a map, 226–229 object), 368 ZoomMax property (Layer
creating a MapX X property (Point object), 480 object), 404
control, 214 X property (Title object), 556 ZoomMin property (Layer
creating menu items, 215– XMax property (Rectangle object), 404
217 object), 489 ZoomTo method (Map
custom tools, 219–220 XMin property (Rectangle object), 465

754 MapInfo MapX Developer Guide v4.5