0% found this document useful (0 votes)

34 views

MapX 50 DevGuide

Uploaded by

Hugo Quijana

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

34 views

MapX 50 DevGuide

Uploaded by

Hugo Quijana

We take content rights seriously. If you suspect this is your content, claim it here.

Affine Transform object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
AllFeaturesConstraint object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Annotation Object and Annotations Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
BindLayer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
BitmapSymbol Object and BitmapSymbols Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
BoundsConstraint object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
CoordSys Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Dataset object and Datasets collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Datum Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Feature Object and Features Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
FeaturesConstraint object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
FeatureFactory Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Field object and Fields collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Find object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
FindFeature object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
FindMatch Object and FindMatches Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
FindResult Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Geoset Object and Geosets Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Graphic Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
IndividualValueCategory object and IndividualValueCategories collection . . . . . . . . . 363

vi MapInfo MapX Developer Guide v5.0

Table of Contents

Label object and Labels collection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

LabelProperties Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Layer Object and Layers Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
LayerInfo Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Legend Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
LegendText Object and LegendTexts Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Map object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
MultivarCategory Object and MultivarCategories Collection . . . . . . . . . . . . . . . . . . . . . . 461
NotesQueryInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
NotesViewInfo Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
OCIQueryInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
ODBCQueryInfo Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Parts Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Point Object and Points Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
RangeCategory Object and RangeCategories Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Rectangle Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
ResolveObject Object and ResolveObjects Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
RowValue Object and RowValues Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Selection Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
SourceRow Object and SourceRows Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
State Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Style Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Theme Object and Themes Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
ThemeProperties Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Title Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Variable object and Variables collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

MapInfo MapX Developer Guide v5.0 vii

Table of Contents

Appendix A: MapX Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

Appendix B: Custom Dataset Support . . . . . . . . . . . . . . . . . . . . . . . . . 565

Appendix C: MapX Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

Appendix D: Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Appendix E: Creating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605

Appendix F: Geoset Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

Appendix G: OLE_COLOR Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Appendix H: IDispatch Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

viii MapInfo MapX Developer Guide v5.0

Welcome...
to the MapInfo MapX Developer’s Guide!
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.
New in MapInfo MapX
This section summarizes the improvements and enhancements made to MapX for versions 5.0.
• Layer Packing: Packing the data contained in a layer will remove deleted records and will
rebuild the index and graphics files. To implement this feature, two methods have been
added to the Layer object.They are:
• Layer.Pack method (Layer object) on page 393
• Layer.SupportsPack method (Layer object) on page 400
• Save Layer as native MapInfo table with .mdb data file: When creating a new table, MapX
offers a choice between MapInfo Native and MS Access format. Additionally, you have the
choice of which version of Access MDB MapX creates.
A new permanent table can be created by specifying a LayerInfo.Type (see TableStorageType
& AccessVersion on the parameter table of LayerInfo Object on page 412 under
miLayerInfoTypeNewTable).
• Cache Performance Improvements for Remote Database connectivity: Enhancements to
MapX’s caching ability have been made by expanding the Cache parameter of the LayerInfo
object, the addition of three new objects and three methods connecting them to the Layer
object. Specifically, the Cache dataset is used to cache records from a remote database dataset
to prevent return trips the remote database server for data that MapX recently fetched.
Previously in MapX, the cache maintained one MBR constraint for each layer. Now, a user/
programmer has the ability to dictate what is allowed to be stored in cache, how much is
stored, and when it should be removed. Please refer to the following for more specific
information:
• LayerInfo Object on page 412
• BoundsConstraint object on page 285
• FeaturesConstraint object on page 322
• AllFeaturesConstraint object on page 272
• Layer.CreateBoundsConstraint method (Layer Object) on page 382
• Layer.CreateFeaturesConstraint method (Layer Object) on page 382
• Layer.CreateAllFeaturesConstraint method (Layer Object) on page 381
• Double Stereographic Projection: For Double Stereographic projection the ellipsoidal data is
first mapped conformally on a conformal sphere. Then, a second conformal mapping of the
spherical data to the plane completes the process. This projection is used for Prince Edward
Island and New Brunswick in Canada. Please refer to, ”Chapter 13: Summary of Parameters
Used by Coordinate Systems” on page 199.
• Dynamic Selection for Radius and Rectangle Selection Tools: In the Map object, you will
find a new property called Map.DynamicSelectionSupport property (Map object) on
page 440. Previously in MapX, when you dragged your selected tool cursor and released the
mouse button, MapX highlighted all objects within the rubber band circle you drew. With
Dynamic selection mode turned on, you can select objects as you are dragging the mouse (i.e.
without having to release the mouse buttons so you can see your selection with out having
actually made it). This mode is optional and will be enabled by setting this boolean property
to true or false. It will affect only rectangle and radius selection tools.
• Labeling Enhancements: Previously in MapX, a programmer had control over labels on a per
layer basis, but not on an individual label basis. Until now, there was no ability to customize
the appearance and content of individual labels. With the addition of the Label object and

x MapInfo MapX Developer Guide v5.0

New in MapInfo MapX

collection, the LabelChanged Event, AND two new properties in the LabelProperties object,
MapInfo has extended this functionality to MapX programmers.
MapX programmers can also allow users to edit labels manually with the MapX Select tool.
The Map.EditableLabels property controls whether the user can select and move labels with
the stock select tool. (see Map.EditableLabels property (Map object) on page 440
The new features are:
• LabelProperties.LabelPartialObjects property (LabelProperties object) on page 374:
The PartialSegment property has been deprecated (but will be supported for backward
compatibility) and replaced with the new property, LabelProperties.LabelPartialObjects.
Its behavior applies to all map objects (with the exception of points) rather than just
polylines. Therefore, if two dimensional GeoObjects are being labeled but their centroids
are outside the map, MapX will still label them. The behavior is the same when labelling
polylines.
• LabelProperties.LabelAlong property (LabelProperties object) on page 373: The
LabelAlong property replaces the old Parallel property, which we still support but have
deprecated to a hidden property. The parallel property dictated whether labels on lines
and polylines are not rotated or are drawn at the same angle as the line or polyline
segment to which they are anchored. With the LabelAlong property, you may indicate
that the label will follow the contour of what it is labeling if the object being labeled is a
polyline. LabelAlong has three states, represented by constants. (See
LabelAlongConstants on page 597). For objects other than polylines, if the property is set
to miLabelAlongMultiSegment, the property is ignored (i.e., for point and region
objects). For line objects, if the property is set to miLabelAlongMultiSegment, automatic
labels are drawn as if the property is set to miLabelAlongParallel.
• Label object and Labels collection on page 365: There is a new object accessed through
the Layer object (see the new property Layer.Labels property (Layer object) on page 391)
that represents a collection of labels.The collection is the set of labels that are currently
drawn AND those that were edited either through the user interface or programatically.
Please refer to the properties associated with the Label object.
• LabelChanged Event on page 557: MapX fires this event whenever a label is about to be
modified, hidden (labels cannot really be deleted), marked as hidden, or unhidden. The
MapX programmer has the opportunity to prevent the operation by setting the
EnableDefault value to False.
• Military Grid Reference System: MapX now includes the ability to convert to and from
MGRFS using the following methods of the Map object.
• Map.MilitraryGridReferenceFromPoint method (Map object) on page 447
• Map.MilitaryGridReferenceToPointV method (Map object) on page 448
• Map.MilitaryGridReferenceToPoint method (Map object) on page 449
• Snap to Node: When this feature is enabled, if there are any nodes present in the rectangle
around the current mouse position, the feature snaps to the closest node to the centroid of the
rectangle and draws cross hair. This mode can be turned on under all tools. Please refer to the
following new Map object properties and method:
• Map.SnapToNodeSupport property (Map object) on page 458
• Map.SnapTolerance property (Map object) on page 458
• JPEG2000 support: This Raster format has been added to this list of Raster formats MapX
supports.

MapInfo MapX Developer Guide v5.0 xi

• Unicode Support: MapX is now a unicode application.
• Mutipoint and Collection objects: MapInfo has added support for two new GeoObject types
in MapX 5.0 – Multipoint and Collection objects. A Multipoint is a single object consisting of
a number of points. The Multipoint object corresponds to a single record in a table and all the
points within the object have the same symbol. A Collection object consists of a number of
objects that have been combined into a single object. The Collection object may contain a
mixture of points, polylines, and polygons.
Six new Feature object properties were added for Multipoint and Collection objects in order
to support these new GeoObject types:
• Feature.HasMultipoint property (Feature object) on page 312
• Feature.HasPolyline property (Feature object) on page 312
• Feature.HasRegion property (Feature object) on page 313
• Feature.Multipoint property (Feature object) on page 314
• Feature.Polyline property (Feature object) on page 316
• Feature.Region property (Feature object) on page 316
FeatureFactory object now has two new methods:
• FeatureFactory.CreateMultipoint method (FeatureFactory object) on page 333
• FeatureFactory.CreateCollectionFeature method (FeatureFactory object) on page 331
• Label Thematics Support: This feature allows a MapX developer to add themes to a layer
dataset to modify the layer’s label display characteristics (i.e. a label’s textual style). Please
refer to Label Thematics on page 127 for additional information and ThemeTypeConstants on
page 603 for the new enumerated constant values.
• Coordinate System Updates: Five additional coordinate systems have been added to MapX.
(See “Summary of Parameters Used by Coordinate Systems” on page 199) The new
projections are:
• Mercator Regional
• Polyconic
• Cassini - Soldner
• *Azimuthal Equidistant (now, all origin latitudes)
• *Lambert Azimuthal Equal-Area (now, all origin latitudes)
Please refer to the CoordSysTypeConstants on page 592 for the new enumerated constant
values.
Note: *The Azimuthal Equidistant and Lambert Azimuthal Equal-Area projection existed
previously in MapX, but with only with pole aspects.
• Oracle Call Interface(OCI) Data Source Support: MapX can use OCI to retrieve data from an
Oracle data source. You need to specify the connection string and the SQL string to execute
by using the OCIQueryInfo Object.
For additional information, see OCIQueryInfo object on page 467.
• Points and Parts Performance Optimization: With the addition of three additional methods
of the Points collection, MapX developers can quickly derive the XY coordinates of any given
point. These methods and their corresponding pages in the developer guide are:
• Points.GetXY method (Points collection) on page 474

xii MapInfo MapX Developer Guide v5.0

New in MapInfo MapX

• Points.X method (Points collection) on page 475

• Points.Y method (Points collection) on page 476
• Points.GetXYV method (Points Collection) on page 475
• State Object: This allows you to save the current state of an item, such as an object or
variable, so that you can restore the item back to that state at a later time. You can save and
restore MapX objects or variables (e.g. a String or Boolean.)
For additional information, see State Object on page 499.
• Grid and Raster Handlers: MapX includes support for additional raster and grid file formats.
These raster formats include:
• MrSID (*.sid) from Lizard Tech
• ECW (*.ecw) from ER Mapper
• Vertical Mapper Continuous Grids (*.grd) from Northwood Technologies
• Vertical Mapper Classified Grids (*.grc) from Northwood Technologies
Grid formats include:
• USGS DEM (*.dem)
• GTOPO30 (*.dem)
• DTED (*.dt0, *.dt1, *.dt2)
• Vertical Mapper Continuous Grids (*.grd) from Marconie (Formarly Northwood)
These raster and grid handlers provide support for displaying files in additional formats.
These handlers are in addition to the existing handlers that have been included in previous
versions.
• Translucent Rasters Images: A translucent image can be seen through. This allows raster
images to be placed on top of other layers, while the underlying layers are still partially
visible. MapXtreme supports translucency for raster tables that have translucency enabled
using MapInfo Professional 6.5.

MapInfo MapX Developer Guide v5.0 xiii

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 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.com
• 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

xiv MapInfo MapX Developer Guide v5.0

Chapter 1: Introduction to MapX

Introduction to MapX
1
Chapter
Welcome to the MapInfo family of products. As the field
of enterprise mapping continues to expand, MapInfo ➤ Mapping at a Glance
leads the way with new products that are designed to ➤ Making MapX Work for You
fulfill users’ desktop and enterprise mapping needs from
our flagship product, MapInfo Professional, to the most
➤ Overview of Key Features
specialized with MapMarker, our premier address- ➤ Learning About MapX
matching product.
MapInfo MapX is a mapping 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. If
you have created or purchased MapInfo map data
(tables) for use with MapInfo Professional, you can use
those same files with MapX.
Chapter 1: Introduction to 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.
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.

2 MapInfo MapX Developer Guide v5.0

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, 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.

MapInfo MapX Developer Guide v5.0 3

Chapter 1: Introduction to MapX

Overview of Key Features

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 MapX 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.
• 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 Oracle Spatial and
MapInfo SpatialWare running on Oracle, Informix, SQL Server 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.

4 MapInfo MapX Developer Guide v5.0

Learning About MapX

This document 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++, or Delphi.
If you are using MapX for the first time, here are some pointers for how to learn about MapX:
• Read ”Chapter 2: MapX Basics” on page 7.
• 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>\ Samples50.
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 v5.0 5

Chapter 1: Introduction to MapX

6 MapInfo MapX Developer Guide v5.0

2
Chapter 2: MapX Basics

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

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 Datasets, 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 coordinate of the center of the map. X Map1.CenterX = -79.4458
coordinates are associated with Longitude or Easting,
depending on map projection.
CenterY Sets the Y coordinate of the center of the map. Y Map1.CenterY = 44.9932
coordinates are associated with Latitude or Northing,
depending on map projection..

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.

8 MapInfo MapX Developer Guide v5.0

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:
Select View > Properties Windowlick on (Custom) from the Properties Window.

3. 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..."

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

MapInfo MapX Developer Guide v5.0 9

Chapter 2: MapX Basics

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.

10 MapInfo MapX Developer Guide v5.0

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.

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 ”Chapter 5: Mapping in Layers” on page 45, 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.

MapInfo MapX Developer Guide v5.0 11

Chapter 2: MapX Basics

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 ”Chapter 7: Features and Selections” on page 99.

12 MapInfo MapX Developer Guide v5.0

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 be returned as you
have saved them. The GeoSet Manager lets you modify layers, manage zoom levels, labels, and other
properties.

MapInfo MapX Developer Guide v5.0 13

Chapter 2: MapX Basics

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.

14 MapInfo MapX Developer Guide v5.0

Annotations

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 collection. Map1.Annotations.AddSymbol X,

A default style is used (as specified in Y
Map.DefaultStyle).
AddText Adds text to the Annotation collection. The Map1.Annotations.AddText _
fourth parameter is the initial position of the “Developer Services”, _
text relative to the coordinates given. 79.44, 46.8889, _
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 object If Map1.Annotations(2).Type_
type. = miTextAnnotation Then _ Print “It is text”
Graphic This contains a Graphic object, See the Graphic Object on page 361.
which has properties for the
Annotation.

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.
The following code adds a symbol to a specified location:
'Add a symbol at location
Map1.Annotations.AddSymbol X1, Y1

MapInfo MapX Developer Guide v5.0 15

Chapter 2: MapX Basics

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.
When using programming languages like Visual Basic, Delphi and you are required to specify the
MapX version number after the object name (e.g. "MapX.Style.5").

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.5"),
// 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.5');
s.PickRegion;
MapObject.Layers.Item(1).Style := s;
end

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

16 MapInfo MapX Developer Guide v5.0

Creatable Objects in MapX

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

Dim objStyle as new object
Set objStyle = CreateObject(“MapX.Style.5)
Map1.Layers(1).OverrideStyle = True
objStyle.PickRegion
set objMap.Layers(1).Style = objStyle

MapInfo MapX Developer Guide v5.0 17

Chapter 2: MapX Basics

18 MapInfo MapX Developer Guide v5.0

3
Chapter 3: Mapping Concepts

Mapping Concepts
Now that you have installed MapX and been enticed by
the wide variety of features and functionality, you are
Chapter
probably anxious to get mapping. However, first, take a
few minutes to read this chapter, especially if you are
➤ Organizing Your Data and
new to MapX. This chapter gives you a solid Maps: An Overview of Tables
understanding of the concepts for successful mapping
with MapX.
➤ What Are GeoSets?
➤ Map Features
➤ Putting Your Data on the Map
➤ 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.

20 MapInfo MapX Developer Guide v5.0

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 v5.0 21

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.

22 MapInfo MapX Developer Guide v5.0

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. See
”Chapter 6: Putting Your Data On The Map” on page 73 for a list of data sources you can bind.

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).

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.

MapInfo MapX Developer Guide v5.0 23

Chapter 3: Mapping Concepts

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.

24 MapInfo MapX Developer Guide v5.0

4
Chapter 4: Getting Started With MapX

Getting Started With MapX

This chapter presents the information you need to install
Chapter
MapX successfully and gives you a quick overview of
MapX. First-time users should read this chapter.
➤ What Is MapX?
➤ Before Installing MapX
➤ MapX Mobile Documentation
Set
➤ Where to Go Next
➤ What Is MapX?
➤ 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 C++
➤ Getting Started with
PowerBuilder
➤ Getting Started With Delphi
➤ Getting Started with Lotus
Notes
➤ MapX Documentation Set
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 a DLL that can be quickly
integrated into client applications using object-oriented languages such as Visual Basic, Delphi, and
Visual C++.

System Requirements
MapX requires a 32-bit version of Windows 98 (2nd Edition), 2000 (Service Pack 2), Windows NT
4.0(Service Pack 6A, or Windows XP.

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 5.0

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

Sample Maps
A collection of map files of different regions around the world. The formats included are:
• MapInfo TAB
• ImagePro
• GDT 2001
• StreetPro
• Military Grid Reference System (MGRS)

Sample Data
A Microsoft Access database containing sample demographic data, an Oracle database containing
spatial and non spatial data, and a SQL Server database.

Sample Applications
For the latest sample programs, visit the MapX web site: http://www.mapx.com

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

26 MapInfo MapX Developer Guide v5.0

What Is MapX?

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.

MapInfo MapX Developer Guide v5.0 27

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 MapXand exit from all
Windows programs before beginning the installation.

Uninstalling Older Versions of MapX

Uninstalling an older version of MapX is a 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.

Unicode Version of MapX

MapX is a unicode application. However, if you are running Windows 98, MapX will detect this upon
installation and install a non-unicode version.

28 MapInfo MapX Developer Guide v5.0

Installing MapX

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:). The CD should run automatically, but if it
fails, click on the Windows Start button and select Run, then type or select [ CD Drive Letter
]\Setup.exe (e.g., D:\Setup.exe) in the Open drop-down list and click OK.
2. A welcome screen appears with several options. Click the 'Install MapX' button.

3. The Welcome screen displays. Choose Next to continue the installation process.
4. The Software License screen displays. Choose YES to accept the terms of the agreement and
to continue the installation process.
5. 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 5.0
If you already have MapX installed, the default is the current installation directory.

MapInfo MapX Developer Guide v5.0 29

Chapter 4: Getting Started With MapX

Note: We strongly recommend that you remove all previous versions of MapX and exit 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.
6. 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.
7. The Select Program Folder screen displays; designate the program folder.
8. 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.
9. When the MapX Installer has finished, the MapX Data Set up Dialog will launch. Repete all
steps detailed above to complete this installation.

30 MapInfo MapX Developer Guide v5.0

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 v5.0" 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 v5.0" 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 Samples50\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.

Using Visual C++ version 5 and 6

From the Project menu, choose Add To 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.

MapInfo MapX Developer Guide v5.0 31

Chapter 4: Getting Started With MapX

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 DLL is added into the project, you will need to restore any custom properties.

32 MapInfo MapX Developer Guide v5.0

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())

MapInfo MapX Developer Guide v5.0 33

Chapter 4: Getting Started With MapX

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 on page 31 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.

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 ).

34 MapInfo MapX Developer Guide v5.0

Getting Started with Visual Basic

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 5.0\Samples50

Understanding ASIA.VBP
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.

MapInfo MapX Developer Guide v5.0 35

Chapter 4: Getting Started With MapX

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
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.

36 MapInfo MapX Developer Guide v5.0

Getting Started with Visual Basic

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 5: Mapping in Layers” on page 45.

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.

MapInfo MapX Developer Guide v5.0 37

Chapter 4: Getting Started With MapX

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 ”Chapter 8: Thematic
Mapping and Analysis” on page 109.

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 Chapter 9:”Finding
Features on a Map” on page 129.

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
”Chapter 7: Features and Selections” on page 99.

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.

38 MapInfo MapX Developer Guide v5.0

Getting Started with Visual C++

One way to learn MapX is to study sample applications. Look for sample applications in the folder:
MapInfo\MapX 5.0\Samples50
As you study the sample C++ application mapxsamp.cpp, refer to ”Chapter 14: Working with Visual
C++” on page 211 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.

MapInfo MapX Developer Guide v5.0 39

Chapter 4: Getting Started With MapX

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 v5.0 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.

Creating a Simple Map

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

1. Select the MapX icon from the Tools 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.

40 MapInfo MapX Developer Guide v5.0

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. 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 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.

MapInfo MapX Developer Guide v5.0 41

Chapter 4: Getting Started With MapX

“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.

42 MapInfo MapX Developer Guide v5.0

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 v5.0 43

Chapter 4: Getting Started With MapX

44 MapInfo MapX Developer Guide v5.0

5
Chapter 5: Mapping in Layers

Mapping in Layers
This chapter presents the relationship between tables and
maps, and shows how they are layered to create the level
Chapter
of detail you want.

➤ Maps as Layers
➤ The Layers Collection:
Building Blocks of Your Map
➤ Some Properties of the Layers
Collection
➤ Some Methods of the Layers
Collection
➤ Creating Layers with the
LayerInfo Object
➤ The Layer Object
➤ Layer Order
➤ Examining Layers
➤ Checking the Feature Type
➤ Zoom Layering
➤ Generating Labels for a Layer
➤ Annotations 81
➤ Raster Images
➤ Animation Layers
➤ Drawing Layers
Chapter 5: Mapping in 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.

46 MapInfo MapX Developer Guide v5.0

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.

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 v5.0 47

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.

48 MapInfo MapX Developer Guide v5.0

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: For a complete listing of Layers Collection methods and properties, see Layer Object and
Layers Collection on page 377.

Get the Number of Layers in a Collection

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 v5.0 49

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

50 MapInfo MapX Developer Guide v5.0

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: For a complete listing of Layers Collection methods and properties, see Layer Object and
Layers Collection on page 377.

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.

Layers Control Dialog

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 Dialog

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 v5.0 51

Chapter 5: Mapping in Layers

Layer Options Dialog

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 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.

52 MapInfo MapX Developer Guide v5.0

Creating Layers with the LayerInfo Object

The LayerInfo object is used to add new or existing layers to your map. The object has two properties
and one method.The Type property is used to specify the type of layer you wish to add to the map, its
value is set to one of the LayerInfoTypeConstants. Depending on the LayerInfo type, you must specify
a certain set of parameters via the AddParameter method. For a complete list of LayerInfo types and
their required parameters see the LayerInfo Object on page 412. Once set, properties can be viewed or
changed via the Parameter property.

Creating A Layer
You can create new MapInfo tables to add to your map. These tables can be permanent
(miLayerInfoTypeNewTable) which means the layer will be created on your hard drive and remain
after your application is done running, or temporary (miLayerInfoTypeTemp) which means the layer
will be created in memory and will not remain after your application is done running. The examples
below show the creation of new permanent and temporary layers.
'Create a new permanent layer that contains all features selected in the
'USA layer
Dim li as New MapXLib.LayerInfo
Dim ftrs as MapXLib.Features
Dim flds as MapXLib.Fields
Dim ds as MapXLib.Dataset

'the new table will have the same columnar structure as the USA layer
Set ds = Map1.Datasets.Add (miDatasetLayer, Map1.Layers("USA"))
Set flds = ds.Fields

'the new table will contain all features currently selected in the USA
'layer
Set ftrs = Map1.Layers.Item("USA").Selection.Clone

li.Type = miLayerInfoTypeNewTable
li.AddParameter "Name", "USA Selections"
li.AddParameter "FileSpec", App.Path & "\USA_Selections.tab"
li.AddParameter "Fields", flds
li.AddParameter "Features", ftrs
li.AddParameter "OverwriteFile", "1"
'The layer is created when added to the layers collection
Map1.Layers.Add li

'Create a new temporary layer that contains all features selected in the
'USA layer
Dim li as New MapXLib.LayerInfo
Dim ftrs as MapXLib.Features

MapInfo MapX Developer Guide v5.0 53

Chapter 5: Mapping in Layers

Dim flds as MapXLib.Fields

Dim ds as MapXLib.Dataset

'the new table will have the same columnar structure as the USA layer
Set ds = Map1.Datasets.Add (miDatasetLayer, Map1.Layers("USA"))
Set flds = ds.Fields

'the new table will contain all features currently selected in the USA
layer
Set ftrs = Map1.Layers.Item("USA").Selection.Clone

li.Type = miLayerInfoTypeTemp
li.AddParameter "Name", "USA Selections"
li.AddParameter "Fields", flds
li.AddParameter "Features", ftrs
'The layer is created when added to the layers collection.
Map1.Layers.Add li

Adding an Existing Layer

The LayerInfo object is also used to add existing layers to your map. When using LayerInfoTypeTab
the only parameter you need to specify is the FileSpec, the physical location of the MapInfo table you
wish to add to the map. There are several other optional parameters that allow you to set the visibility
of the layer (Visible parameter) or to create a dataset from the newly added layer (AutoCreateDataset
parameter and DatasetName parameter). Below is an example that uses these optional parameters, it
adds the USA layer to the map, makes the layer invisible and creates a dataset from the layer.
Dim li as MapXLib.LayerInfo
Set li = CreateObject ("MapXMobile.LayerInfo.5")

li.Type = miLayerInfoTypeTab
li.AddParameter "FileSpec", "\My Documents\Maps\USA.tab"
li.AddParameter "Visible", False
li.AddParameter "AutoCreateDataset", True
li.AddParameter "DatasetName", "dsUSA"

Map1.Layers.Add li

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

Remove All Layers

The RemoveAll method removes all layers from the map.
Private Sub btnLayersRemoveAll_Click()
Dim nLayers As Integer

54 MapInfo MapX Developer Guide v5.0

Creating Layers with the LayerInfo Object

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

MapInfo MapX Developer Guide v5.0 55

Chapter 5: Mapping in Layers

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 Layer Object and
Layers Collection on page 377.

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

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

56 MapInfo MapX Developer Guide v5.0

The Layer Object

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

MapInfo MapX Developer Guide v5.0 57

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.

58 MapInfo MapX Developer Guide v5.0

Examining Layers

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
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.

MapInfo MapX Developer Guide v5.0 59

Chapter 5: Mapping in Layers

Checking the 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 miFeatureTypeUnknown
MsgBox “Layer ” & lyr.Name & “ contains unknown _
features”
Case miFeatureTypeText
MsgBox “Layer ” & lyr.Name & “contains text features”
End Select
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.

60 MapInfo MapX Developer Guide v5.0

Zoom Layering

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.

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.

MapInfo MapX Developer Guide v5.0 61

Chapter 5: Mapping in Layers

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.
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.

62 MapInfo MapX Developer Guide v5.0

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.
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.
You can also cotrol the appearance of individual labels via the Labels Collection. There is a Labels
collection associated with each layer, and each item in the collection is a Layer Object. By
manipulating the properties of a Label Object you can control the display of a label independently
from the rest of the labels in that layer

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

MapInfo MapX Developer Guide v5.0 63

Chapter 5: Mapping in Layers

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.

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.

64 MapInfo MapX Developer Guide v5.0

Generating Labels for a Layer

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.
Labels can be moved interactively by selecting a label or labels with the select tool (miSelectTool
1007) then dragging the label(s) to a new location. A label that has been edited manually then
becomes an itemin that layer's Labels Collection. It can then be edited programatically by setting
properties of the Label Object.

MapInfo MapX Developer Guide v5.0 65

Set lyr = Map1.Layers.Add (li, 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 Add method of the Layers collection,
an event is fired to the application when the window needs updating.

Example
A complete example is shown below.
' API DEFS should be declared in a separate module
Declare Function MoveToEx Lib "gdi32" Alias "MoveToEx" (ByVal hdc As
Long, ByVal x As Long, ByVal y As Long, lpPoint As POINTAPI) As Long
Declare Function LineTo Lib "gdi32" Alias "LineTo" (ByVal hdc As Long,
ByVal x As Long, ByVal y As Long) As Long
Declare Function SetMapMode Lib "gdi32" Alias "SetMapMode" (ByVal hdc As
Long, ByVal nMapMode As Long) As Long
Type POINTAPI
x As Long
y As Long
End Type
Public Const MM_TWIPS = 6

' this sets the UserDraw Layer to “My Layer”

Dim lyr as Layer
Set lyr = Map1.Layers.AddUserDrawLayer("My Layer", 1)

' this example draws a line between the corners of Wyoming

Private Sub Map1_DrawUserLayer(ByVal Layer As Object, ByVal hDC As Long,
ByVal RectFull As Object, ByVal RectInvalid As Object)
Dim pt As POINTAPI

SetMapMode hDC, MM_TWIPS

70 MapInfo MapX Developer Guide v5.0

Drawing Layers

dim PX as single
dim PY as single

X1 = -111.0542
Y1 = 45.0009
X2 = -104.0528
Y2 = 41.0018

if map1.ClipLine(X1,Y1,X2,Y2) then
map1.ConvertCoord(PX, PY, X1,Y1, miMapToScreen)
MoveToEx hDC , PX, -PY, pt ' win api call
map1.ConvertCoord(PX, PY, X2,Y2, miMapToScreen)
LineTo hDC, PX, -PY ' win api call
end if

End Sub

MapInfo MapX Developer Guide v5.0 71

Chapter 5: Mapping in Layers

72 MapInfo MapX Developer Guide v5.0

Chapter 6: Putting Your Data on the Map
6
Chapter

➤ What Is Data Binding?

Putting Your Data On The Map
➤ The Power of Adding Your
Datasets enable you to bind user data to your maps. For
Data to a Map
example, if you have a Microsoft access database of sales
by county and you had a Oracle database of the location ➤ How to Add Your Data to a
of your sales force, you could bind that data to a map and Map
spot trends or notice correlations between the two sets of ➤ Using the Dataset Object
data.
➤ Using the Datasets Collection
➤ Using the Datasets.Add
Method
➤ 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
➤ XML Support
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
OCI MapX can use OCI to retrieve data from an Oracle data source.
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 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.

74 MapInfo MapX Developer Guide v5.0

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 ”Chapter 9: Finding Features on a Map”
on page 129.
• 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 ”Chapter 8: Thematic Mapping and Analysis” on page 109.

MapInfo MapX Developer Guide v5.0 75

Chapter 6: Putting Your Data on the Map

How to Add Your Data to a Map

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.
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.
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.

76 MapInfo MapX Developer Guide v5.0

Using the 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 is 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).

MapInfo MapX Developer Guide v5.0 77

Chapter 6: Putting Your Data on the Map

Using the 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 adds it Set ds = Map1.Datasets.Add_

to the collection. (miDatasetADO, rs)
Remove Removes a specified Dataset object Map1.Datasets.Remove 2
from the Datasets collection.

78 MapInfo MapX Developer Guide v5.0

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 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
miDatasetDelphi5 Borland Delphi 5
miDatasetGlobalHandle Tab delimited data
miDatasetLayer MapInfo Table
miDatasetNotesQuery Lotus Notes Query
miDatasetNotesView Lotus Notes View
miDatasetOCI Oracle Call Interface Data Source
miDatasetODBC ODBC Database
miDatasetOLEData OLE data source
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 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.

MapInfo MapX Developer Guide v5.0 79

Chapter 6: Putting Your Data on the Map

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
miDatasetOCI An OCIQueryInfo object.
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.
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.

80 MapInfo MapX Developer Guide v5.0

Using the Datasets.Add Method

If a Fields collection is specified, the Geofield parameter refers to columns in the Fields collection
rather than in the source data.

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.

Note: When miBindLayerTypeXY is used within DataSets.Add a temporary table will be created
with one column named "GeoName" , in order for a fields collection to be recognized a new
Databind must be created on a permanent layer.

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.
If a Fields collection is specified, the Geofield and SecondaryGeofield parameters refer to columns in
the Fields collection rather than in the source data.

MapInfo MapX Developer Guide v5.0 81

Chapter 6: Putting Your Data on the Map

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.

82 MapInfo MapX Developer Guide v5.0

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.

MapInfo MapX Developer Guide v5.0 83

Chapter 6: Putting Your Data on the Map

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 method (or with the
Themes.Add method; see ”Chapter 8: Thematic Mapping and Analysis” on page 109) 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 Fields.Add method (Fields collection) on page 343.

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.

84 MapInfo MapX Developer Guide v5.0

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.

MapInfo MapX Developer Guide v5.0 85

Chapter 6: Putting Your Data on the Map

BindLayer Object Properties

Property Description Values

LayerType Specifies the layer type that the data is A BindLayerTypeConstant:

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 and A text string that identifies a file
location of a file, so that the path and file name.
Datasets.Add method can create a
permanent layer instead of a
temporary layer.
KeyLength A positive number, representing the A numeric value (1-254).
desired size of the character column in
the resulting layer.
LayerName Specifies the name of the layer which A string value.
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 file A string.
to use if BindLayer.LayerType is
miBindLayerTypePointRef.
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.

86 MapInfo MapX Developer Guide v5.0

Displaying Your Data as a Layer of Points (BindLayer)

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 5.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
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.

MapInfo MapX Developer Guide v5.0 87

Chapter 6: Putting Your Data on the Map

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.
This example creates a permanent table through data binding using X / Y coordinates.
Dim BindLayerObject As New MapXLib.BindLayer
Dim ds as Dataset

'Where to save the newly created permanent table

BindLayerObject.FileSpec = “C:\MapInfo\Data\Dealers.TAB”
BindLayerObject.LayerType = miBindLayerTypeXY ‘Binding to Long/Lat
BindLayerObject.LayerName = "US Dealers" 'Layer Name to use
BindLayerObject.RefColumn1 = ("LONG") 'Name of Longitude column
BindLayerObject.RefColumn2 = ("LAT") 'Name of Latitude column

'Add the dataset and create the permanent layer

Set ds = Map1.Datasets.Add(miDataSetADO, rs, "My Dealers", "Dealer", ,
BindLayerObject)

88 MapInfo MapX Developer Guide v5.0

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—GeoDictionaryManager50.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 GeoDictionary.
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.

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.

MapInfo MapX Developer Guide v5.0 89

Chapter 6: Putting Your Data on the Map

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 miBindLayerTypeXY.
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.

90 MapInfo MapX Developer Guide v5.0

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)

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.

miDatasetDelphi4 & miDatasetDelphi5 (Delphi DataSource Object)

These data types are only used with the Borland Delphi programming language. In order to create a
Delphi Dataset, use the following steps:
1. Add a data source (such as a Table or Query control) to theDelphi form and point it to the
appropriate BDE data source by setting its DatabaseName and TableName properties. Set its
Active property to True to open the database.
2. Add a DataSource control to the form. Set its DataSet property to whichever control you
created in step 1.
3. Select View -> Project Manager in the menu.
4. Right click on the .exe of your project in the Project Manager window, and select View Source.
5. Insert the line "ShareMem" directly after the "uses" line in the source window.
6. Save your project.

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
. . .

MapInfo MapX Developer Guide v5.0 91

Chapter 6: Putting Your Data on the Map

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.

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).

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.

92 MapInfo MapX Developer Guide v5.0

The Different Types of Data Sources

miDatasetXML
The MapX XML Dataset Driver is an implementation of the MapX Dataset Driver interface suite. The
MapX Dataset Driver interfaces are based on the Microsoft Component Object Model (COM)
architecture. Specifically, the MapX XML Dataset Driver provides a set of interfaces providing access
of XML data to MapX.For detailed information on using XML datasets with your MapX applications,
see help topic, XML Support on page 94

miDatasetOCI (Oracle Call Interface data source)

MapX can use OCI to retrieve data from an Oracle data source. You need to specify the connection
string and the SQL string to execute by using the OCIQueryInfo object.
The OCIQueryInfo.ConnectString property sets the connect string to connect with an Oracle data
source. This parameter is identical to the values used with the LayerInfo object's ConnectString
parameter when using the ORAINET toolkit (OCI) to add a layer using Oracle Spatial. Refer to
”Chapter 12: Accessing Data from a DBMS” on page 163 for more information.

MapInfo MapX Developer Guide v5.0 93

Chapter 6: Putting Your Data on the Map

XML Support
The MapX XML Dataset Driver leverages the Microsoft XML Parser. There are several versions of
Microsoft XML Parser. Version 1.x is not supported. MapX XML Dataset Driver has been tested with
and supports Version 2.x. Additionally, the upcoming Version 3.0 of the Microsoft XML Parser may be
supported but has not been tested. No other parsers are currently supported.
On issues of standards conformance, the MapX XML Dataset Driver standards conformance is based
on the version of the Microsoft XML Parser registered with the system. For example, Version 2.5 of the
Microsoft XML Parser standards conformance includes:
• XML: Conformance is based on the Extensible Markup Language Version 1.0 specification.
• XSL: Conformance is based on the XML Stylesheet Language Working Draft (12.18.1998)
For more information refer to Microsoft support for the Microsoft XML Parser.
Version 2.0 of the Microsoft XML Parser is included as part of the installation. However, as of this
writing, Version 2.5 SP1 of the Microsoft XML Parser is available as a stand-alone redistribution and
included as part of the installations for Microsoft Windows 2000 SP1 and Microsoft Internet Explorer
Version 5.01 or higher.

Adding a MapInfo XML Dataset to Your Map Object

The Datasets container of the MapX component library includes a method to add a new dataset. The
first two parameters are unique to each dataset driver. The first parameter is the identifier for the
dataset driver. Each dataset driver is identified by a unique numeric code. The MapX component
library contains predefined constants for these identifiers. The predefined constant and the actual
numeric code for the MapX XML Dataset Driver follows:
miDataSetXML = 14
The second parameter provides the necessary metadata the dataset driver needs to obtain the data. In
the case of the MapX XML Dataset Driver, there are two mechanisms for passing the necessary
metadata. The first and simpler of the two mechanisms requires a string providing the location for
MapInfo XML Dataset in the form of a uniform resource identifier (URI) or a path (local or UNC). In
the case of the path, the path is relative to the MapXtreme Server. The following is a simple example
for Microsoft Visual Basic:
DIM XMLURL As String
Dim XMLDataset As MapXLib.Dataset
'Initialize XMLURL
XMLURL = "http://www.xml.com/DataSource.xml"
'Assume MapObject exists within a form
Set XMLDataset = MapObject.Datasets.Add(miDataSetXML, XMLURL)
The second mechanism is more complicated and involves the creation of a second automation object,
the MXMLDatasetDriverConfiguration object. This object has two properties, the first property, the
SourceLink, provides the URI or path identifying the location of a MapInfo XML Dataset; while the
second property, the FilterLink, provides the URI or path identifying the location of an XSLT

94 MapInfo MapX Developer Guide v5.0

XML Support

document for transforming a specified XML Dataset based on an external schema into a MapInfo XML
Dataset. The following snippet is a simple example for Microsoft Visual Basic:
Dim XMLDataset As MapXLib.Dataset
DIM XMLResource As MXMLDatasetDriverConfiguration
' Set XMLResource SourceLink
XMLResource.SourceLink = "http://www.xml.com/DataSource.xml"
' Set XMLResource FilterLink – currently unsupported
XMLResource.FilterLink = "http://www.xml.com/DataFilter.xml"
' Assume MapObject exists within a form
Set XMLDataset = MapObject.Datasets.Add(miDataSetXML, XMLResource)

Authoring A MapInfo XML Dataset

Authoring a MapInfo XML Dataset refers to the ability to create a valid XML document developed in
such a way as to be appropriately processed by the MapX XML Dataset Driver. To understand how to
do this it is necessary to understand how to author an XML document in general. Based on this it is
then necessary to review the schemas on which the MapInfo XML Dataset is based. Note, the MapInfo
XML Dataset was designed with XML Schemas in mind. While as of this writing, XML Schemas are
not a universally accepted standard; this implementation leverages the capabilities of the Microsoft
XML Parser, Version 2 and after which supports a limited version of XML Schemas.
The schema on which a valid and well-formed MapInfo XML dataset is based is a subset of the
Microsoft XML rowset schema. The universal-resource-name for the Microsoft rowset schema is
schemas-microsoft-com:rowset. The following snippet is the basic MapInfo dataset schema,
which is a subset of the Microsoft rowset schema:
<s:Schema xmlns:s='urn:schema-microsoft-com:xml-data'
xmlns:dt='urn:schemas-microsoft-com:datatypes'>

<s:ElementType name='baserow' content='eltOnly'/>
<s:element type='baserow'/>

<s:ElementType name='data' content='eltOnly'>
<s:element type='baserow' minOccurs='0' maxOccurs='*'/>
</s:ElementType>
<s:element type='data'/>
</s:Schema>
Note: The above snippet the first line identifies two important namespaces. The first of the two
namespaces refers to the Microsoft schema schema, which defines the schema definition
language. A schema defines the structure of valid content for a specific class of XML
documents, or XML document. The MapInfo XML dataset schema utilizes an inline
schema, a document fragment defining the structure of data content. The second
namespace refers to the Microsoft datatype schema. This schema provides the language
definitions for the supported data types.
A MapInfo XML Dataset consists of two distinct document fragments. The first document fragment is
an inline schema. This schema fragment adheres to the aforementioned Microsoft schema schema

MapInfo MapX Developer Guide v5.0 95

Chapter 6: Putting Your Data on the Map

and defines the structure of the MapInfo XML Dataset. Each column is identified by name and type as
distinct attributes of a row element. The second document fragment contains the actual data.
Adhering to the data definition of the MapInfo dataset schema, the data fragment contains multiple
row elements representing the individual rows. Each of the following two samples provides an
example of a MapInfo XML Dataset, both exposing the same data. After the two samples, we break
down the XML document and study the individual pieces and fragments.

Sample A
<xml xmlns:s="urn:schema-microsoft-com:xml-data" xmlns:ds="urn:schemas-
microsoft-com:rowset" xmlns:dt="urn:schemas-microsoft-com:datatypes"
xmlns:x="#DatsetSchema">

<s:schema>
<s:elementType name='row' content='eltOnly'>
<s:attributeType name='StateAbbr' dt:type='string'/>
<s:attributeType name='StateName' dt:type='string'/>
<s:attributeType name='StatePop' dt:type='14'/>
<extends type='rowbase'/>
</s:elementType>
</s:schema>

<ds:data>
<x:row StateAbbr ='AK'StateName='Alaska' StatePop='550043'/>
<x:row StateAbbr ='NY' StateName='New York' StatePop='17990455'/>
</ds:data>
</xml>

Sample B
<xml xmlns="#xmldataset">

<schema>
<elementType name='row' content='eltOnly'>
<attributeType name='StateAbbr' type='string'/>
<attributeType name='StateName' type='string'/>
<attributeType name='StatePop' type='14'/>
<extends type='rowbase'/>
</elementType>
</schema>
<data>
<row StateAbbr ='AK'StateName='Alaska'StatePop=' 550043'/>
<row StateAbbr ='NY' StateName='New York' StatePop='17990455'/>
</data>
</xml>
First, we will break out the document root tag, the <xml> tag. The important points to notice in this
fragment is the namespaces:

96 MapInfo MapX Developer Guide v5.0

XML Support

<xml xmlns:s="urn:schema-microsoft-com:xml-data" xmlns:ds="urn:schemas-

microsoft-com:rowset" xmlns:dt="urn:schemas-microsoft-com:datatypes"
xmlns:x="#DatsetSchema">
The first three namespaces refer to the aforementioned Microsoft schema, ‘rowset and datatypes
schemas. The final namespace is the internal namespace for the inline schema (more on this to come).
There is one important issue to discuss – namespace alias usage. The MapX XML Dataset Driver
assumes the Microsoft schema schema defines the schema, elementType and attributeType
elements. If these elements are prefixed by a namespace alias, the alias must refer to the Microsoft
schema schema. Furthermore, the ‘type'attribute for the column definition is assumed by the MapX
XML Dataset Driver to be defined by the Microsoft datatypes schema. If these attributes are
prefixed by a namespace alias, the alias must refer to the Microsoft datatypes schema. Finally, the
data element is assumed to be defined in the Microsoft rowset namespace. If the data element is
prefixed by a namespace alias, the alias must refer to the Microsoft rowset namespace. The MapX
XML Dataset Driver explicitly checks for the Microsoft namespaces to determine if an alias is used. If
an alias prefixes any of the above elements and refers to an unsupported namespace, the XML Dataset
will not be processed correctly.
The universal resource name for the Microsoft schema namespace is urn:schema-microsoft-
com:xml-data. The universal resource name for the Microsoft datatypes namespace is
urn:schemas-microsoft-com:datatypes. The universal resource name for the Microsoft
rowset namespace is urn:schemas-microsoft-com:rowset.
Take a brief look at Sample B. Notice only the internal namespace is referred to in the root tag. Also
notice no namespace aliases are used on the elements outlined above. This will pass a validation check
and be processed by the MapX XML Dataset Driver. As for the internal namespace, the MapX XML
Dataset Driver has no requirements on this, so long as the document is valid.
Now, looking once more at Sample A, review the fragment for the inline schema:

<s:schema>
<s:elementType name='row' content='eltOnly'>
<s:attributeType name='StateAbbr' dt:dt='string'/>
<s:attributeType name='StateName' dt:dt='string'/>
<s:attributeType name='StatePop' dt:dt='long'/>
<extends type='rowbase'/>
</s:elementType>
</s:schema>
This schema identifies an element called row, which actually extends the element rowbase, an
element defined in the above MapInfo dataset schema and Microsoft rowset schema. According
to this inline schema, the row element consists of three attributes. These attributes are the actual
columns of the row. There is a StateAbbr attribute/column of type string, a StateName attribute/
column of type string and a StatePop attribute/column of type long.
There is one important point to note here – it is important to understand that XML element tags are
case sensitive. The current version of the MapX XML Dataset Driver expects schema in place of

MapInfo MapX Developer Guide v5.0 97

Chapter 6: Putting Your Data on the Map

Schema, elementType in place of ElementType, and attributeType in place of

AttributeType. If this is not adhered to, the inline schema will not be processed as expected.
Quickly referring to Sample B, notice as well the fact that no namespace alias is used to prefix the
schema, elementType and attributeType elements, but otherwise the inline schema is
unchanged.
Finally, review the fragment for the data from Sample A:

<ds:data>
<x:row StateAbbr ='AK'StateName='Alaska'StatePop='550043'/>
<x:row StateAbbr ='NY' StateName='New York' StatePop='17990455'/>
</ds:data>
The root element of this fragment is the data element, which for Sample A is defined in the above
MapInfo dataset schema and the aforementioned Microsoft rowset schema. Therefore the tag is
prefixed with the appropriate namespace alias, which in this case is ds. This then, according to the
schemas, contains one or more elements based on the rowbase element, which in this instance is the
row element defined in the above inline schema. Each of these elements has one attribute for each
attribute/column identified in the inline schema. Note that the row element is prefixed by the
designated namespace alias. Referring to Sample B, notice that once again the only difference is the lack
of the namespace aliases.

98 MapInfo MapX Developer Guide v5.0

Chapter 7: Features and Selections

Features and Selections

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

100 MapInfo MapX Developer Guide v5.0

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.

MapInfo MapX Developer Guide v5.0 101

Chapter 7: Features and Selections

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.

102 MapInfo MapX Developer Guide v5.0

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

Method Description Features ‘this creates a
collection of Features)

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

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

MapInfo MapX Developer Guide v5.0 103

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 Collection

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.

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 associates the map's coordinate
system with the feature.

104 MapInfo MapX Developer Guide v5.0

Using the Features Collection

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 feature IVar = ftr.FeatureID
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 feature. If ftr.Perimeter > 500 Then
Print “Too Long”
End If
Name Contains the name of the feature. MsgBox ftr.name
Type Contains the type of the feature (point, line, ftr.Type =
etc.). miFeatureTypeSymbol

MapInfo MapX Developer Guide v5.0 105

Chapter 7: Features and Selections

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 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.
For a complete listing, see the Selection Collection on page 489

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.

106 MapInfo MapX Developer Guide v5.0

Feature Editing

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

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.
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 MapX Online Help provides 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:

MapInfo MapX Developer Guide v5.0 107

Chapter 7: Features and Selections

• 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.

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.

108 MapInfo MapX Developer Guide v5.0

8
Chapter 8: Thematic Mapping and Analysis

Thematic Mapping and Analysis

Thematic mapping is a powerful way to analyze and
visualize your data. You give graphic form to your data
Chapter
so that you can see it on a map. Patterns and trends that
are almost impossible to detect in lists of data reveal
➤ What Is Thematic Mapping?
themselves clearly when you use thematic shading to
display data on a map. ➤ Planning Your Thematic Map
With MapX, you can create applications with thematic ➤ Types of Thematic Mapping
maps using the following thematic types: ranges of
➤ Manipulating a Theme Map
values, graduated symbols, dot density, individual
values, and bar and pie charts. ➤ Customizing a Thematic
Legend
➤ Label Thematics
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 ThemeProperties
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.

110 MapInfo MapX Developer Guide v5.0

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.
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 Collection
Each dataset has a collection of themes. A Themes collection creates, counts, adds, or removes a Theme
object from a collection of themes. For information on the methods of the Themes collection, please
refer to the Chapter 18:”Theme Object and Themes Collection” on page 526.

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” .
For information on the Themes.Add method, please refer to Chapter 18:”Themes.Add method
(Themes collection)” on page 530.

MapInfo MapX Developer Guide v5.0 111

Chapter 8: Thematic Mapping and Analysis

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).
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.

112 MapInfo MapX Developer Guide v5.0

Planning Your Thematic Map

ThemeType Constants
These are the types of themes you can create are:

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
miLabelRangedTheme Ranged Label Theme
miLabelIndividualValuesTheme Individual Label Value 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.
For a complete listing of all Theme object properties, please refer to the Chapter 18:”Theme Object and
Themes Collection” on page 526.

MapInfo MapX Developer Guide v5.0 113

Chapter 8: Thematic Mapping and Analysis

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 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.

114 MapInfo MapX Developer Guide v5.0

Types of Thematic Mapping

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.

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.

MapInfo MapX Developer Guide v5.0 115

Chapter 8: Thematic Mapping and Analysis

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.
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.

116 MapInfo MapX Developer Guide v5.0

Types of Thematic Mapping

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.
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.

MapInfo MapX Developer Guide v5.0 117

Chapter 8: Thematic Mapping and Analysis

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).

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 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

118 MapInfo MapX Developer Guide v5.0

Types of Thematic Mapping

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.

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.

MapInfo MapX Developer Guide v5.0 119

Chapter 8: Thematic Mapping and Analysis

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 New York are spread throughout the state; they are
not concentrated in New York City, where the majority of the state’s population lives.

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.

120 MapInfo MapX Developer Guide v5.0

Types of Thematic Mapping

There are five theme properties you control for bar charts: DataValue, Size, Independent,
MultiVarCategories, and Width.
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,

MapInfo MapX Developer Guide v5.0 121

Chapter 8: Thematic Mapping and Analysis

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.

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.
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.

122 MapInfo MapX Developer Guide v5.0

Types of Thematic Mapping

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.

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.

MapInfo MapX Developer Guide v5.0 123

Chapter 8: Thematic Mapping and Analysis

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 are 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.

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.
For a complete listing of all ThemeProperties object properties, please refer to
Chapter 18:”ThemeProperties Object” on page 534.
Several of the ThemeProperties properties are actually other objects. Those objects include the
RangeCategory object, IndividualValue object, MultiVar object and the Style object. Look at the next
table 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

124 MapInfo MapX Developer Guide v5.0

Manipulating a Theme Map

Property Description Code Sample

NumItems Shows the number of items in a Print Map1.DataSets(1).Themes(1).

range. Properties.RangeCategories(1).NumItems
Style A style object representing the Map1.Datasets(1).Themes.Item(1).Propert
style of that range. ies.RangeCategories.Item(1).Style.PickReg
ion
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 v5.0 125

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

126 MapInfo MapX Developer Guide v5.0

Label Thematics

Label Thematics
Label thematics allows one to add themes to a layer dataset which modifies the layer’s label display
characteristics. There are two types of label themes. They are:
• Ranged Value
• Individual Value

Individual Value Themes

For individual themes, you may modify the label style individually by using the Style property of each
individual value theme category. You can use the ApplyAttribute theme property to modify either the
label's foreground color or all its font properties. For example, to make the first individual value's label
capitalized and bold do the following:
Theme.ThemeProperties.IndividualValueCategories(1).Style.TextFont.Bold
= True
Theme.ThemeProperties.IndividualValueCategories(1).Style.TextFontAllCap
s = True
Theme.ThemeProperties.ApplyAttribute = miApplyAttributeAll

Ranged Themes
For ranged themes, you may modify the label style by using the Style property of each range theme
category (or bin.) You can use the ApplyAttribute theme property to modify the label's foreground
color, size or all its font properties. In addition, you can automatically spread the font size or
foreground color between all range categories by using the SpreadBy theme property. When you apply
all the attributes and perform a spread by (either color or size), all attributes (except for the one being
automatically spread) come from what is called the model style. In MapX, the model style is the first
range category style. For example, to automatically spread the label font size and modify only the font
size do the following:
Theme.ThemeProperties.ApplyAttribute = miApplyAttributeSize
Theme.ThemeProperties.SpreadBy = miSpreadBySize
To add a new label theme, you can use the Themes.Add method using either one of the following
theme ThemeTypeConstants:
• miLabelRangedTheme
• miLabelIndividualValueTheme.
See Chapter 19:”ThemeTypeConstants” on page 603 for a complete listing of available theme types.
You may then use the Theme.ThemeProperties property to configure your themes.

MapInfo MapX Developer Guide v5.0 127

Chapter 8: Thematic Mapping and Analysis

128 MapInfo MapX Developer Guide v5.0

9
Chapter 9: Finding Features on a Map

Finding Features on a Map

The Find method of the Layer object allows you to search
a layer in a map object and locate a specific feature within
Chapter
the layer.

➤ Find Object
➤ FindFeature Object
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
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 on page 349.

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”

130 MapInfo MapX Developer Guide v5.0

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.

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.
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 v5.0 131

Chapter 9: Finding Features on a Map

132 MapInfo MapX Developer Guide v5.0

Chapter 10: Using the Geodictionary Manager

Using the Geodictionary and Geoset

Managers
The Geodictionary Managher and Geoset Manager are
utilities that come with MapX to aid in your Mapping
applications. This chapter deals with how to use them
10Chapter
and their respective interfaces.
➤ Using the
GeodictionaryManager
➤ The GeoDictionary Manager’s
User Interface
➤ Using the Geoset Manager
Chapter 10: Using the Geodictionary Manager

Using the GeodictionaryManager

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 (GeoDictionaryManager50.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
Geodictionary Manager will not modify geosets in any way, nor will it delete files from a user’s disk.
In MapX 5.0 (or later versions), a permanent Geodictionary file is no longer required for MapX to run.

Note: 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

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 5.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

134 MapInfo MapX Developer Guide v5.0

Using the GeodictionaryManager

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 5.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 5.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.
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.

MapInfo MapX Developer Guide v5.0 135

Chapter 10: Using the Geodictionary Manager

The GeoDictionary Manager’s User Interface

This section describes the user interface for the Geodictionary Manager.

Run GeoDictionary Manager

To run the GeoDictionary Manager when you want to manually register layers:
1. Start -> Programs -> MapInfo MapX vX.0 ->
2. Select a Geoset from the Windows Open Dialog.
3. In the Tools menu, select Run GeoDictionary Manager.
The Geodictionary dialog displays.

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".

136 MapInfo MapX Developer Guide v5.0

The GeoDictionary Manager’s User Interface

Part Description

Registered tables The Registered Tables list box contains a list of the friendly names for all
tables registered in the Geodictionary.
Register This displays the common file open dialog, with the Files of Type
combo box set to "MapInfo Tables (*.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), the Table 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 the Table 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 v5.0 137

Chapter 10: 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.

Register Layers in Geodictionary

If you want the Geoset Manager to automatically register your layers, choose Tools > Register Layers.
The Register Layers dialog displays.

138 MapInfo MapX Developer Guide v5.0

The GeoDictionary Manager’s User Interface

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.

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.

MapInfo MapX Developer Guide v5.0 139

Chapter 10: Using the Geodictionary Manager

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.

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.

140 MapInfo MapX Developer Guide v5.0

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. To display an existing geoset:
1. Choose File > Open Geoset. The Open dialog displays.

MapInfo MapX Developer Guide v5.0 141

Chapter 10: Using the Geodictionary 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.

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.

142 MapInfo MapX Developer Guide v5.0

Using the Geoset Manager

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.
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.

MapInfo MapX Developer Guide v5.0 143

Chapter 10: Using the Geodictionary Manager

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.
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.

144 MapInfo MapX Developer Guide v5.0

Using the Geoset Manager

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 v5.0 145

Chapter 10: Using the Geodictionary 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).

Chapter 10: Using the Geodictionary Manager

Part Description

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.

150 MapInfo MapX Developer Guide v5.0

Using the Geoset Manager

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.

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.

MapInfo MapX Developer Guide v5.0 151

Chapter 10: Using the Geodictionary Manager

152 MapInfo MapX Developer Guide v5.0

Chapter 11: Using Drilldown Layers
11Chapter

➤ What Is a Drilldown Layer?

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

152 MapInfo MapX Developer Guide v5.0

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 v5.0 153

Chapter 11: 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.

154 MapInfo MapX Developer Guide v5.0

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 v5.0 155

Chapter 11: 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

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.
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.

156 MapInfo MapX Developer Guide v5.0

Preparing a Drilldown Layer

• 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:

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.

MapInfo MapX Developer Guide v5.0 157

Chapter 11: Using Drilldown Layers

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 that are currently visible.

158 MapInfo MapX Developer Guide v5.0

Creating a Drilldown Tool

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.

MapInfo MapX Developer Guide v5.0 159

Chapter 11: Using Drilldown Layers

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.

160 MapInfo MapX Developer Guide v5.0

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 v5.0 161

Chapter 11: 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.

162 MapInfo MapX Developer Guide v5.0

12
Chapter 12: Accessing Data from a DBMS

Accessing Data from a DBMS

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

164 MapInfo MapX Developer Guide v5.0

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=GEORGETOWN;PWD=s
ecret;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 v5.0 165

Chapter 12: 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.

166 MapInfo MapX Developer Guide v5.0

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.

You 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).

MapInfo MapX Developer Guide v5.0 167

Chapter 12: Accessing Data from a DBMS

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 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 POINT
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
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

168 MapInfo MapX Developer Guide v5.0

Oracle Support

From Oracle 8i GTYPES To MapInfo

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 one Region
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.

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

MapInfo MapX Developer Guide v5.0 169

Chapter 12: Accessing Data from a DBMS

• 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 Spatial 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 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.

170 MapInfo MapX Developer Guide v5.0

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. Please refer to the LayerInfo Object on
page 412 for a complete listing of parameters the LayerInfo object of type miLayerInfoTypeServer
supports.

MapInfo MapX Developer Guide v5.0 171

Chapter 12: Accessing Data from a DBMS

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.

172 MapInfo MapX Developer Guide v5.0

DBMS Connection String Format

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_tli;SERV
ICE=sqlexec;PROTOCOL=onsoctcp;

SpatialWare connection string:

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

SpatialWare for SQL Server string:

DRIVER={SQL SERVER};SERVER=LAMONT;VID=Troll;
PWD=secret;Database=GEORGETOWN

MapInfo MapX Developer Guide v5.0 173

Chapter 12: Accessing Data from a DBMS

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
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

174 MapInfo MapX Developer Guide v5.0

A MapX DBMS Layer Query

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 or mi_prinx, (e.g. select custid mi_prinx, ccustname, object from mycust).

Example
Select customer_id prinx, object, from customer_view
The column alias “prinx” is used to identify and use the customer_id column as the key column for the
layer. You can alternately alias 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.

MapInfo MapX Developer Guide v5.0 175

Chapter 12: Accessing Data from a DBMS

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
Map1.Datasets.Add miDataSetLayer, Lay, dsname

176 MapInfo MapX Developer Guide v5.0

Performance Issues

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.

MapInfo MapX Developer Guide v5.0 177

Chapter 12: Accessing Data from a DBMS

Working with the Cache

Knowing how to work with Cache in MapX will enable you to improve your applications
performance. The sections below describe what the Cache is, how it works in MapX, and the CACHE
parameter of the LayerInfo object.

What is the Cache?

In place of local files, applications can access MapX features from a remote database. In place of
reading these records from the database each time the map needs to be acted upon. MapX can
temporarly store these records in the cache. This limits the number of calls between the application
and the remote database. Records in a Server Layer can be cached to improve the performance of your
application (e.g. drawing, thematics, labeling, etc). Server 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.
There are several settings that developers can use to customize cache usage. The cache can be enabled
(or disabled) when the server layer is added by specifying the CACHE parameter in the LayerInfo
object and is ON by default.

How the Cache Works

For each record that is cached, each attribute data value is stored in memory and each feature object is
stored on disk in a temporary Rtree file. For tables with a lot of records and/or a large record size (e.g.
number of bytes per record for the attribute data), caching may use a significant amount of memory. If
an application tries to cache too much data, virtual memory usage may be required which will
degrade performance. Applications should be selective about how the cache is utilized. MapX offers a
variety of mechanisms for controlling the cache.

The LayerInfo object and the CACHE Parameter

When a server layer is added to the map, the cache can be enabled by specifying the CACHE
parameter in the LayerInfo object that is passed to Layers.Add. This parameter has four possible
values: ON, OFF, ALL, USER, with ON being the default.

Parameter Description

OFF A value of 'Off' means that the layer will not use the cache at all. All data operations
will go directly to the database server.

178 MapInfo MapX Developer Guide v5.0

Working with the Cache

Parameter Description

ON A value of 'ON' for the LayerInfo CACHE parameter means that MapX will maintain
the record cache in a fashion that best improves standard MapX operations. The
cache is maintained to contain, at a minimum, all the records displayed for the layer,
which appear in the MBR of the current map window. Once the initial map window
MBR has been cached, pan and zoom operations which fall entirely within the initial
extents of the cache will access the cached records and will not need to query the
database. If a pan/zoom operation falls outside the cached region, MapX will add the
new map window MBR (view) to the cache and obtain the missing records from the
database server and add them to the cache.
The old map view is not initially discarded; rather, an internal history of previous
map views is maintained. To avoid having a cache that grows excessively large, there
are controls that can be placed on MapX to determine when to discard old cached
views (map window MBR regions). These controls are parameters of the LayerInfo
object which can be set at the time the layer is initially added and allow the developer
to set limits on the maximum amount of memory or disk space used by the cache, the
maximum number of previous map window views to maintain in the history, the
maximum number of records to maintain in the cache, and/or the maximum amount
of time old map window views are allowed to remain in the cache history. These
limits can be used individually or in combination to provide the cache management
that best suits the application's needs.
See the LayerInfo Object on page 412 for specific parameter names, default values,
and available settings.
NOTE: The default values for these limits are set to provide consistent behavior with
older versions of MapX, that is, the maximum number of previous map views
maintained in the cache's history (not including the current map view) is defaulted to
zero.

MapInfo MapX Developer Guide v5.0 179

Chapter 12: Accessing Data from a DBMS

Parameter Description

USER A value of USER for the LayerInfo CACHE parameter means that MapX will create a
cache, but the only records that will be placed in the cache are those specified by the
application developer. The mechanisms available for specifying which records are
placed in the cache are BoundConstraint, FeaturesConstraint, and
AllFeaturesConstraint objects. The word constraint implies that these objects are
constraining the cache to include the specified records. The BoundsConstraint object
(see BoundsConstraint object on page 285) can be used to place all records into the
cache for which the MBR of the feature intersects the MBR of the constraint.
A FeaturesConstraint object (see FeaturesConstraint object on page 322) can be used
to add specific records to the cache. For example, if an analysis is going to be
performed that involves multiple steps and/or reads of the Feature or RowValues of
the feature, possibly on a set of features returned from a Layer.Search,
Layer.SearchWithinDistance, etc, it may be advantageous to place these records into
the local cache for the duration of the analysis and remove them when finished. The
FeaturesConstraint provides this capability. If an application is going to perform an
analytically intensive operation that may hit every record, it may be desirable to
temporarily cache the entire set of data for the layer. This may be accomplished by
using the AllFeaturesConstraint (see AllFeaturesConstraint object on page 272).
These cache constraint objects may also be used when the cache is set to ON. In this
case, they may add records to the cache but have no effect on the cache's history of
previous map window views. The constraint objects may be used when the cache is
set to OFF or ALL in which case they have no effect.
NOTE: The constraint objects have no effect on non-server layers.
ALL ALL means that MapX will cache the entire table one time and not need to add and
remove records on a draw-by-draw basis. Small tables that are accessed very
frequently are good candidates for this type of option.
*TIP: The entire cache can be refreshed from the database through the use of the Layer.Refresh method
[see Layer.Refresh method (Layer object) on page 395]. This will refresh the data in the current view
and any currently allocated constraint objects and will eliminate all other cache history.

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

180 MapInfo MapX Developer Guide v5.0

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.
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 one.

Note: MapX supports the storage of style informaton for individual features in remote
databases. Therefore, layers get their styles from the Map Catalog.

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).
• To load data into SQL Server SpatialWare, 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.

MapInfo MapX Developer Guide v5.0 181

Chapter 12: Accessing Data from a DBMS

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),
RENDITIONTYPE INTEGER,
RENDITIONCOLUMN CHAR(32),
RENDITIONTABLE 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)

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

182 MapInfo MapX Developer Guide v5.0

Per-Record Styles

Per-Record Styles
Per-record style support brings a feature to spatial database implementations that has long been
available in MapInfo TAB files. Specifically, it allows each geometry in a single layer to have its own
style. For example, a single 'public institution' layer in Oracle8i Spatial can have schools, town halls,
libraries and police departments and each point type would be represented with its own symbol (i.e. a
school symbol for all the schools). Similarly, a single road layer in SpatialWare SQL Server may have
different road types such that streets are shown as a single pixel black line, secondary roads as a
double pixel red line and interstates as parallel red lines.

Column Data Type Description

RENDITIONTYPE INTEGER Numeric indicator of the table’s per-record

rendition type. Valid values are:
• 0: No per-record styles are in effect for the
indicated table. Objects will be read/updated
as before using the default style for the table.
• 1: The indicated table uses The indicated
table uses per-record styles. The column in
the table which contains the style is recorded
in RENDITIONCOLUMN and it contains a
MapBasic string (e.g. the same format that is
currently used in the Map Catalog’s SYMBOL
column).
RENDITIONCOLUMN VARCHAR(32) This column contains the name of the column in
the indicated table which holds the object style
value (for a rendition type of 1).
RENDITIONTABLE VARCHAR(32) Presently this column is not used, however, it
must be present before MapX will properly
detect the existence of this new feature. A future
enhancement has been proposed to have the
styles managed in a separate table and to have
the value in the column identified by the
RenditionColumn contain a key that can be used
to look up the style in the table identified by this
attribute. This functionality is not implemented.

Note: If these columns are not present, object styles will continue to work as before (e.g. the
table’s default style will be applied to all objects) with one exception which is discussed
below. If these columns are present in the Map Catalog, they will be used as follows:

Known Limitations/Requirements
When using layers that specifically request the style column, you may experience difficulty updating
existing features (or other row data values) and inserting new records. The reason for this is that MapX
automatically adds the style column to the INSERT/UPDATE statements as necessary, and may, for

MapInfo MapX Developer Guide v5.0 183

Chapter 12: Accessing Data from a DBMS

layers which do not have a hidden style column, generate SQL statements which specify the column
name twice.

184 MapInfo MapX Developer Guide v5.0

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 column 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 Object
Type 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
14.x: SpatialWare for Microsoft SQL Server
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
OWNERNAME The owner name of the table. GEORGETOWN

MapInfo MapX Developer Guide v5.0 185

Chapter 12: Accessing Data from a DBMS

Column Name Values to Assign Examples

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 are
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
COORDINATESYSTEM A string representing a MapInfo CoordSys Earth Projection 1, 0
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 Symbol(35,0,12)
contains only points); or a Symbol clause Pen(1,2,0) Pen(1,2,0)
followed by a Pen clause (indicating styles for Brush(2,255,255)
linear features) 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 NO_COLUMN
name 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 NO_COLUMN
name of the column containing Y–coordinates,
or specify NO_COLUMN.

186 MapInfo MapX Developer Guide v5.0

Making a DBMS Table Mappable

Column Name Values to Assign Examples

RENDITIONTYPE This indicates how the object style information 0 or 1

is applied.
• “0” - Indicates that all the objects will have
the style specified in the symbol field of the
Map.Catalog applied to them.
• “1” - Indicates that the table has a separate
column which contains a string
representation of the style information for
each object in the table (e.g. each object
may have its own style).
RENDITIONCOLUMN If RENDITIONTYPE is “1”, this field stores MI_SYMBOLOGY
the name of the column in the spatial table
(identified by the TABLENAME) that contains
style information. This column is
automatically added to any query against the
table and is maintained (updated) as the object
is updated. Users should NOT specify this
column in their queries as problems can occur
with intersect or update statements. Queries
which include this column in the select clause
(excluding the wildcard character “* “) may
access the values through the Dataset object.
Rows with a NULL value in their style column
will have the style from the SYMBOL field of
the MapCatalog applied to the object.
RENDITIONTABLE Currently not used, but reserved for future NULL
use, this column must exist in order for MapX
to correctly identify and apply record-level
styles.

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.

MapInfo MapX Developer Guide v5.0 187

Chapter 12: Accessing Data from a DBMS

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 v5.0

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 attempted Data binding is not currently
matchable." against a SpatialWare layer. supported for SpatialWare layers.
No object was found using the A query was made against a Check that the table name is correct
index that you specified. table that does not exist. and in the proper case. Also, the
No spatial object is contained table may need to be mappable.
in the result of the spatial Use the EasyLoader Upload utility
query. to make the table a mappable table.
A query was made against a Check the query for possible syntax
non-spatial table. 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 has The dataset was created from a MapX datasets.rowcount will
the value of zero. DBMS server. always have a value of zero for
datasets created from a DBMS
server. Use the layer’s
AllFeatures.Count property
Map appears to have incorrect The MBR for a DBMS layer is Edit the extents (DB_X_LL,
zoom level. For example, the determined by the DB_X_UR, DB_Y_LL, DB_Y_UR) in
map may be zoomed out too MapInfo_MapCatalog table. the MapInfo_MapCatalog using the
far to identify any geography. The table extents in the MapInfo Professional MDX tool,
MapCatalog result in a MISETMBR.MDX.
different zoom level than the
one you desire for your output.

MapInfo MapX Developer Guide v5.0 189

Chapter 12: Accessing Data from a DBMS

190 MapInfo MapX Developer Guide v5.0

13
Chapter 13: Using Coordinate Systems

Using Coordinate Systems

In this chapter, you'll learn how to use Coordinate
Systems (sometimes called "map projections") to change
Chapter
the appearance of a map, or to change the units in which
map coordinates are processed by MapX.
➤ Basic Concepts of Coordinate
Systems
➤ Obtaining a Coordinate
System Object
➤ Querying the Properties of a
CoordSys Object
➤ Displaying a Map in a
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 13: 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.

192 MapInfo MapX Developer Guide v5.0

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 on page 195, 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 on page 196.
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.)

MapInfo MapX Developer Guide v5.0 193

Chapter 13: Using Coordinate Systems

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 on page 199.
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.

194 MapInfo MapX Developer Guide v5.0

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.

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

MapInfo MapX Developer Guide v5.0 195

Chapter 13: Using Coordinate Systems

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)

iDatumNumber = 62 'North American 1927 (NAD 27)
iUnits = miUnitMeter '(value: 7)
dOriginLongitude = 0

Map1.NumericCoordSys.Set iProjectionType, iDatumNumber, _

iUnits, dOriginLongitude

196 MapInfo MapX Developer Guide v5.0

Specifying X-Y Coordinates in a Different CoordSys

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

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

MapInfo MapX Developer Guide v5.0 197

Chapter 13: Using Coordinate Systems

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:
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

198 MapInfo MapX Developer Guide v5.0

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. 1 Par. 2 Fact. East. Nor.

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

Azimuthal X X X X* X
Equidistant

Cylindrical Equal X X X X
Area

Double X X X X X X X
Stereographic
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 Oblique X X X X X X X X
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

MapInfo MapX Developer Guide v5.0 199

Chapter 13: Using Coordinate Systems

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

Swiss Oblique X X X X X X
Mercator

Transverse X X X X X X X
Mercator

Regional X X X X
Mercator

Polyconic X X X X X X

Cassini - Soldner X X X X X X
* 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.

200 MapInfo MapX Developer Guide v5.0

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]
[Set of 9 Custom Datum Optional; applies only if the Datum number is 9999.
Arguments]
Set of Projection From zero to 8 parameters, depending on which Type is specified. Refer to
Parameters 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 greater
Transformation than a CoordSysTypeConstant.
Parameters]
[Set of 4 Bounds Optional; applies only if the Type number is exactly 2000 or 3000 greater
Parameters] 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:

MapInfo MapX Developer Guide v5.0 201

Chapter 13: Using Coordinate Systems

• 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

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).

202 MapInfo MapX Developer Guide v5.0

Using Settings from MAPINFOW.PRJ

"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:
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)

MapInfo MapX Developer Guide v5.0 203

Chapter 13: Using Coordinate Systems

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.

204 MapInfo MapX Developer Guide v5.0

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.
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.)

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.

MapInfo MapX Developer Guide v5.0 205

Chapter 13: Using Coordinate Systems

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.

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.

206 MapInfo MapX Developer Guide v5.0

Datum Conversion

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.
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.

MapInfo MapX Developer Guide v5.0 207

Chapter 13: Using Coordinate Systems

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

208 MapInfo MapX Developer Guide v5.0

Chapter 14: Working With Visual C++
14 Chapter

➤ Understanding the Sample

Working with Visual C++ Application
One way to learn MapX is to study sample applications.
➤ Upgrading C++ Applications
Look for sample applications in the folder: MapInfo from an Earlier Version of
MapX 5.0\Samples50. However, this chapter will help MapX
you in getting started with MapX and Visual C++.
➤ Accessing MapX Properties
and Methods in C++
➤ Including MapX.cpp in Your
Project
➤ Creating a MapX Control
➤ Creating Menu Items
➤ Handling MapX Events
➤ Using Custom Tools
➤ Data Binding Using C++
➤ Adding a Shortcut Menu
➤ Using the Built-In Helper
Dialogs from C++
➤ Handling MapX Exceptions
➤ Creating a Map in a C++
Dialog
Chapter 14: Working With Visual C++

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”.

212 MapInfo MapX Developer Guide v5.0

Upgrading C++ Applications from an Earlier Version of MapX

AffineTransform BindLayer BitmapSymols

CoordSys Datum Feature

Fields LayerInfo Map

ODBCQueryInfo Parts Point

Points Rectangle RowValue

RowValues Style Variables

MapInfo MapX Developer Guide v5.0 213

Chapter 14: 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 as VARIANTs. 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;
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 of VARIANTS, 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.

214 MapInfo MapX Developer Guide v5.0

Accessing MapX Properties and Methods in C++

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 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.

MapInfo MapX Developer Guide v5.0 215

Chapter 14: Working With Visual C++

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
Samples50\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.

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.

216 MapInfo MapX Developer Guide v5.0

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 > ClassWizard
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
// 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);
}

MapInfo MapX Developer Guide v5.0 217

Chapter 14: Working With Visual C++

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();
}

218 MapInfo MapX Developer Guide v5.0

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 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);

MapInfo MapX Developer Guide v5.0 219

Chapter 14: Working With Visual C++

}
void CMapxSampleView::OnMapToolZoomin()
{
m_ctrlMapX.SetCurrentTool(miZoomInTool);
}
// switch to the previous view
void CMapxSampleView::OnContextPreviousview()
{
m_ctrlMapX.ZoomTo(m_dPrevZoom, m_dPrevX, m_dPrevY);
}

Once the tool is selected, built-in MapX functionality handles the zooming, selecting, etc.

220 MapInfo MapX Developer Guide v5.0

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.

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)

MapInfo MapX Developer Guide v5.0 221

Chapter 14: Working With Visual C++

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++".

222 MapInfo MapX Developer Guide v5.0

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();

style.SetRegionBackColor(255);
// update the feature in the layer
ftr.Update();
}
catch (COleDispatchException *e) {

MapInfo MapX Developer Guide v5.0 223

Chapter 14: Working With Visual C++

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();
}
}
}

224 MapInfo MapX Developer Guide v5.0

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
// 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

MapInfo MapX Developer Guide v5.0 225

Chapter 14: Working With Visual C++

//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)
}

226 MapInfo MapX Developer Guide v5.0

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 v5.0 227

Chapter 14: 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) {
e->ReportError();
e->Delete();
}
}

228 MapInfo MapX Developer Guide v5.0

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 in the online help.
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;
// 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();

MapInfo MapX Developer Guide v5.0 229

Chapter 14: Working With Visual C++

e->Delete();
}
}

230 MapInfo MapX Developer Guide v5.0

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 v5.0.
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 Sample50\CPP directory.

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)

MapInfo MapX Developer Guide v5.0 231

Chapter 14: Working With Visual C++

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);
}

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

232 MapInfo MapX Developer Guide v5.0

Creating a Map in a C++ Dialog

//control. EXCEPTION: OCX Property Pages should

// return FALSE
}

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 v5.0 233

Chapter 14: Working With Visual C++

234 MapInfo MapX Developer Guide v5.0

Chapter 15: MapX Tools

MapX Tools
15 Chapter
Most mapping applications provide an assortment of
tools to aid with common drawing tasks (such as
➤ Overview of Standard Tools
drawing a line on the map) and navigation tasks (such as ➤ Object Editing Tools
zooming in). MapX provides several common mapping
➤ Node Selecting and Editing
tools, plus you can also create your own custom tools.
➤ Creating a Custom Tool
➤ Creating Polygon Drawing
Tools (Polytools)
Chapter 15: MapX Tools

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

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.

236 MapInfo MapX Developer Guide v5.0

Overview of Standard Tools

Tool Constant Description

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 v5.0 237

Chapter 15: 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.

Note: To set which tool is being used, set the Map.CurrentTool property.
The object editing 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 move 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.

238 MapInfo MapX Developer Guide v5.0

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".
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 property.

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

MapInfo MapX Developer Guide v5.0 239

Chapter 15: MapX Tools

Node Edit Mode and Add Node Mode

Map1.FeatureEditMode = miEditModeNode | miEditModeAddNode

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.

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.

240 MapInfo MapX Developer Guide v5.0

Node Selecting and Editing

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.

Deleting Duplicate Nodes

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.

246 MapInfo MapX Developer Guide v5.0

16
Chapter 16: Exporting Maps

Exporting Maps
Often, the user may need to print out a map or
incorporate the visual image of the map in another
Chapter
application. MapX has methods which allow you to send
the contents of a map to the clipboard, to the printer, or to
➤ Methods for Exporting Maps
a graphics file.
➤ ExportSelection Property
➤ Printing Maps
Chapter 16: Exporting Maps

Method for Exporting Maps

To export a map to a graphics file or copy a map’s contents to the clipboard, you would use the
Map.ExportMap method.
To export titles correctly, the ratio of the width and the height of the exported image must be the same
as that of the map. width/height ration. To export a map that is half the height/width of the original,
use the following code (Visual basic example):
Map1.ExportMap "BMP" Map1.MapPaperWidth/2,map1.MapPaperHeight/2

Method Description Code Sample

ExportMap Exports a map to a graphics file. Map1.ExportMap “C:\Map.TIF”,miFormatTIF

(graphic file)
ExportMap Exports a map to the clipboard. Map1.ExportMap “clipboard”
(clipboard)

See Also
Map.ExportMap method (Map object) on page 440
Map.MapPaperHeight property (Map object) on page 445
Map.MapPaperWidth property (Map object) on page 446

Export 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

248 MapInfo MapX Developer Guide v5.0

ExportSelection Property

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 v5.0 249

Chapter 16: Exporting Maps

Printing Maps
To print a map, use the PrintMap method. For additional information, please refer to Map.PrintMap
method (Map object) on page 453

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

250 MapInfo MapX Developer Guide v5.0

Chapter 17: Distributing Your MapX Application
17 Chapter

➤ MapX Customer Installation

Distributing Your MapX Application
➤ Installing MapX
The MapX product you have purchased from MapInfo is
a developer's kit. It contains MapX, sample programs, an ➤ Installing Support for Spatial
on-line help system, sample maps and geosets, and Server Access
various utilities and other support files. This chapter ➤ Installing Raster Format
deals with distributing your MapX application(s) to your Handlers
customers. Please be reminded that you must purchase a
➤ Installing Maps and Geosets
Use License (i.e., seat) as evidenced by a MapInfo License
certificate for each user of each application that you ➤ Adding Keys to the Windows
distribute with MapX functionality as described in the Registry
MapInfo Standard License/Development Environments, ➤ Passing in the MapX License
which is included in your product packaging. String
➤ Redistributing Your MapX
Application with MrSID
➤ Redistributing Your MapX
Application with ECW
Chapter 17: Distributing Your MapX Application

MapX Customer Installation

Providing the 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 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 the MapX 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.

Files Installed Automatically with the Installer

Running [ CD\Install\ setup.exe ] will install the following in the default MapX installation directory:
C:\Program Files\MapInfo\MapX 5.0
• The MapX control mapx50.dll
• Ιts support dlls
• The raster and grid dlls and handlers
• The default dataset drivers
System dlls will also be installed in the appropriate locations (see Installing MapX on page 254).
You can use setup.exe to install the default data supplied with MapX by passing it a "-data" command
line argument.

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 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 will not 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.

252 MapInfo MapX Developer Guide v5.0

MapX Customer Installation

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 DLL 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

MapInfo MapX Developer Guide v5.0 253

Chapter 17: Distributing Your MapX Application

Installing MapX
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. MapX v4.x installs the program files under the following path “\Program
Files\Common Files\MapInfo Shared\MapX Common”. MapX v5.0, by default, stores all of the
required files in "\Program Files\MapInfo\MapX 5.0". 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 Program directory be: "\Program Files\MapInfo\MapX 5.0".
The following table describes what files need to be installed and where they should be installed to.

Where to Install Files Other Special

Files
Requirements

Mfc42.dll, msvcp60.dll, msvcrt.dll, ALT.dll, \Windows\System Do a version check before

MFC42.dll, MFC42U.dll (for unicode platforms) 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
Mapx50.dll MapX common Must be registered using
directory regsvr32.exe. Prior to
registering, make sure
the MapX dependent
files are installed.
mdatasetint.tlb MapX common Must be registered using
directory regtyplib.exe

254 MapInfo MapX Developer Guide v5.0

Installing MapX

Where to Install Files Other Special

Files
Requirements

MapX dependent files: MapX Program

ALLTYPE.DLL, AllTypeRes.dll, AppSelection.dll directory
ChangeManager.dll, ColLookupSystem.dll,
CommandProcessor.dll,
CommandProcessorRes.dll, COORDSYS.DLL,
CoordSysRes.dll, CustomProperties.dll,
DAENGINE.DLL, DAEngineRes.dll,
DBINFO.DLL, DBInfoRes.dll, DBLAYER.DLL,
DBLayerRes.dll, DELPHIMM.DLL,
ExprPacket.dll, ExprPacketCreator.dll,
ExprPacketCreatorRes.dll, ExprPacketRes.dll,
FcnInfoServer.dll, FcnInfoServerRes.dll,
FIND.DLL, FINDRES.DLL, GEO.DLL,
GeoDictionaryManager50.exe,
GeoDictionaryManagerIntl50.dll, GeoObject.dll,
GeoObjectProcess.dll, GeoObjectProcessRes.dll,
GeoObjectRes.dll, GEORES.DLL, GEOSET.DLL,
GeosetManager50.exe, GeosetManagerIntl50.dll,
GeosetRes.dll, GRIDDLL.DLL, LEGEND.DLL,
LegendRes.dll, libspw_mi.dll,
MapBasicInternalFcn.dll,
MapBasicInternalFcnRes.dll,
MapBasicTranslator.dll,
MapBasicTranslatorRes.dll, MAPINFOW.FNT,
MAPINFOW.PRJ, MAPPER.DLL,
MapperRes.dll, MAPX.ABB, MAPX.PEN,
MAPX50.DLL, MapXADODS.dll,
MapXDAODS.dll, MapXRDODS.dll,
mapxstate.dll, mapxstateres.dll, mdatasetint.tlb,
MIAPP.DLL, MIAPPRES.DLL, MIDLG50.DLL,
MIDLIN50.DLL, MILEXER.DLL,
MILexerRes.dll, MIMetadata.dll, MIOCI.DLL,
MIODBC.DLL, MIRDB.DLL, MIRDBRES.DLL,
mirdbspatial.dll, mirdbspatialRes.dll,
MIWINDOW.DLL, MIWindowRes.dll,
MOCIDataset50.dll, MODBCDataset.dll,
MSafeArrayDataset.dll, MXINTL50.DLL,
mxmldataset.dll, RASTER.DLL, RasterRes.dll,
REGSVR32.EXE, RegTypLib.exe, STYLES.DLL,
TextFileReader.dll, TextFileReaderRes.dll
Thematics.dll, ThematicsRes.dll, TOKENS.DLL,
TOOLS.DLL, UTILITY.DLL, UtilityRes.dll,
WINMGR.DLL, WinMgrRes.dll, XMLUTIL.DLL,
XMLUTILRES.DLL,

MapInfo MapX Developer Guide v5.0 255

Chapter 17: Distributing Your MapX Application

Where to Install Files Other Special

Files
Requirements

MapX font files; Windows\Fonts These fonts have to be

ARIAL.TTF, MAPIS___.TTF, MAPSYM.TTF, directory installed and registered
TTMIAR__.TTF, TTMICG__.TTF, with the operating
TTMIMI__.TTF, TTMIOG__.TTF, system. Please see below
TTMIOS__.TTF, TTMIRE__.TTF, TTMITC__.TTF, for more information.
TTMIWE__.TTF
Nadcon support files: MapX Program Only required if using
ALASKA.LAS, ALASKA.LOS, CONUS.LAS, directory layers with the NAD 27
CONUS.LOS, HAWAII.LAS, HAWAII.LOS, and NAD 83 coordinate
PRVI.LAS, PRVI.LOS, STGEORGE.LAS, systems.
STGEORGE.LOS, STLRNC.LAS, STLRNC.LOS,
STPAUL.LAS, STPAUL.LOS
Bitmap symbols: Underneath the MapX Only required if using
TOWE1-32.BMP, POLI1-32.BMP, MBOX2- Program directory, in a custom bitmap symbols.
32.BMP, GOLF1-32.BMP, TOWE2-32.BMP, directory called
RAIL1-32.BMP, MOSQ1-32.BMP, HOSP1- Custsymb. For
32.BMP, IEL2-32.BMP, RAIL2-32.BMP, ONEW1- example: \Program
32.BMP, HOUS1-32.BMP, ADG1-32.BMP, Files\MapInfo\MapX\
ONEW2-32.BMP, HOUS2-32.BMP, ADG2- Custsymb
32.BMP, HOUS3-32.BMP, ANK1-32.BMP, 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,

Installing Fonts
MapX also uses some TrueType fonts. These font files (*.ttf) must be copied to Window’s Font Folder.
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-

256 MapInfo MapX Developer Guide v5.0

Installing MapX

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts

MapInfo MapX Developer Guide v5.0 257

Chapter 17: Distributing Your MapX Application

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 path

MapInfo mirdbspatialres.dll,
ODBC mirdbspatial.dll
Oracle 8i Spatial Mioci.dll, mirdb.dll, Odbc32.dll must exist in system path
mirdbspatialres.dll

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 mapx50.dll>
• 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. 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>
MapX allows you to bind data to a map layer. Please see,”Chapter 6: Putting Your Data On The Map”
on page 73 for additional information.

Note: All of these dataset drivers should be installed in the same directory as MapX.
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 Nnotes.dll must be in the system path

ODBC MODBCDataset.dll Odbc32.dll must be in the system path
Delphi v3 MgenDSetDrvr.dll, Dslibp.dll Delphimm.dll must be in the system
path
Delphi v4 MgenDSetDrvr.dll, Dslibp4.dll Borlndmm.dll must be in the system
path. Run RegisterDS4.exe on
Dslibp4.dll

258 MapInfo MapX Developer Guide v5.0

Installing Support for Spatial Server Access

Dataset source type Dataset drivers Installation Requirements

Delphi v5 MgenDSetDrvr.dll, Dslibp5.dll Borlndmm.dll must be in the system

path. Run RegisterDS5.exe on
Dslibp5.dll
Delphi v6 MgenDSetDrvr.dll, Dslibp6.dll Borlndmm.dll must be in the system
path. Run registerDS6.exe on
Dslibp6.dll
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 installed
OCI MOCIDataset50.dll Oracle client, mioci.dll, and mirdb.dll
must be installed
DAO MapXDAODS.dll MDAC v2.5 or greater
XML mxmldataset.dll msxml4 must be installed

MapInfo MapX Developer Guide v5.0 259

Chapter 17: 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 MapX.
Here is a table of handlers included with MapX:

Supported Raster Types and DLLs

Format Handler Format Handler
needed

All Raster types MIRASTER.DLL

(MIRASTERU.DLL for unicode)
Lead Tools LTFIL12N.DLL, BMP: LFBMP12N.DLL
LTKRN12N.DLL, JPG: LFCMP12N.DLL
LTDIS12N.DLL, GIF: LFGIF12N.DLL
LEADTOOL.RHX J2K: LFJ2K12N.DLL
PNG: LFPNG12N.DLL
PSD: LFPSD12N.DLL
TIF: LFTIF12N.DLL, LFFAX12N.DLL
WMF: LFWMF12N.DLL

260 MapInfo MapX Developer Guide v5.0

Installing Raster Format Handlers

Supported Raster Types and DLLs

Format Handler Format Handler
needed

Halo Libraries Halo.rhv, Mihiffl.dll BMP: miffbmp.dll

GIF: miffgif.dll
JBPG: miffjpeg.dll
PCX: miffpcx.dll
TGA: mifftga.dll
TIF: mifftiff.dll
TIF TIFF.RHL Or you may use the Lead Tools or Halo
TIF library
SPOT Spot.rhd BIL
ECW ECW.RHL ECW
NCSCNET.DLL
NCSECW.DLL
NCSECWEX.DLL
NCSUTIL.DLL
Northwood Grid (as MIGRID.DLL ( MIGRIDU.DLL - GRD
raster) for Unicode)
MIRASTER.DLL
(MIRASTERU.DLL - for Unicode)
MapInfo Grid GRIDDLL.DLL, MIG.GHL MIG
Government ADAGASRP.RHL ADRG, ASRP
Government CADRGCIB.RHL CADRG, CIB, NITF
Northwood Grid (as VMGRID.DLL, NWGRD30.GHL GRD
grid)
DTED DTED.GHL DT?
USGS Digital Elevation DEM.GHL DEM
Grid
GTOPO Grid GTOPO30.GHR DEM

Supported Raster Types and DLLs

Format Handler Format Handler
needed

All Raster types MIRASTER.DLL (Unicode =

MIRASTERU.DLL)

MapInfo MapX Developer Guide v5.0 261

Chapter 17: Distributing Your MapX Application

Supported Raster Types and DLLs

Format Handler Format Handler
needed

Lead Tools LTFIL12N.DLL, BMP: LFBMP12N.DLL

LTKRN12N.DLL, JPG: LFCMP12N.DLL
LTDIS12N.DLL, GIF: LFGIF12N.DLL
LEADTOOL.RHX J2K: LFJ2K12N.DLL
PNG: LFPNG12N.DLL
PSD: LFPSD12N.DLL
TIF: LFTIF12N.DLL, LFFAX12N.DLL
WMF: LFWMF12N.DLL
Halo Libraries Halo.rhv, Mihiffl.dll BMP: miffbmp.dll
GIF: miffgif.dll
JBPG: miffjpeg.dll
PCX: miffpcx.dll
TGA: mifftga.dll
TIF: mifftiff.dll
TIF TIFF.RHL Or you may use the Lead Tools or
Halo TIF library
SPOT Spot.rhd BIL
ECW ECW.RHL ECW
NCSCNET.DLL
NCSECW.DLL
NCSECWEX.DLL
NCSUTIL.DLL
Northwood Grid (as MIGRID.DLL (Unicode = MIRASTER.DLL (Unicode =
raster) MIGRIDU.DLL) MIRASTERU.DLL)
GRD MapInfo Grid GRIDDLL.DLL, MIG.GHL
MIG Government ADAGASRP.RHL
ADRG, ASRP Government CADRGCIB.RHL
CADRG, CIB, NITF Northwood Grid (as grid) VMGRID.DLL, NWGRD30.GHL
GRD DTED DTED.GHL
DT? USGS Digital Elevation Grid DEM.GHL
DEM GTOPO Grid GTOPO30.GHR
DEM

262 MapInfo MapX Developer Guide v5.0

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 refer to, ”Chapter 6: Putting
Your Data On The Map” on page 73.
If it is determined that you need to use the GeoDictionary, when you register a geoset,
GeoDictionaryManager50.exe adds appropriate entries into the Geodictionary (geodict.dct). If the
Geodictionary does not exist, GeoDictionaryManager50.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.

MapInfo MapX Developer Guide v5.0 263

Chapter 17: Distributing Your MapX Application

Adding Keys to the Windows Registry

MapX also uses the following five registry keys (which your installer must create on the end-user's
system, if they do not exist already). The MapX installer creates these 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 file

MapInfo\MapX 5.0\GeoDictionary specification for the geodictionary file.
Example: C:\Program
Files\myappdir\Maps\GeoDict.DCT
HKEY_LOCAL_MACHINE\Software\_ String - The SearchPaths key has semicolon-
MapInfo\MapX 5.0 \SearchPaths 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 where
MapInfo\MapX 5.0\ CommonDLLDir MapX and support files are Located. Example:
\Program Files\Common Files\MapInfo
Shared\MapX Common
HKEY_LOCAL_MACHINE\Software\MapInfo\_ String - Location of MapX Control and
MapX\5.0\Program Dir support files.
HKEY_LOCAL_MACHINE\Version Code\ String - MapX version.

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.

264 MapInfo MapX Developer Guide v5.0

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.

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().

MapInfo MapX Developer Guide v5.0 265

Chapter 17: Distributing Your MapX Application

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-2002,
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.

266 MapInfo MapX Developer Guide v5.0

Redistributing Your MapX Application with ECW

If you need to deploy an application which supports the ECW raster file format (*.ecw), you must
include the following copyright information:
ECW for MapInfo is Copyright MapImagery Limited. See the MapImagery web site
http://www.mapimagery.com for more information.
The ECW compression format is Copyright Earth Resource Mapping. See the Earth Resource
Mapping web site:
http://www.ermapper.com for more information. The ECW compression Technology is covered by
one or more of U.S. Patent Nos. 6,201,897

MapInfo MapX Developer Guide v5.0 267

Chapter 17: Distributing Your MapX Application

268 MapInfo MapX Developer Guide v5.0

Chapter 18: The MapX Object Model

The MapX Object Model

18
Chapter
This chapter is an alphabetically organized reference that
describes the objects, properties, methods of MapInfo ➤
MapX.
Chapter 18: The MapX Object Model

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

Object Methods
• AffineTransform.Set method
• AffineTransform.Units 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 ”Chapter 13: Using Coordinate Systems” on
page 191.

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.

270 MapInfo MapX Developer Guide v5.0

AffineTransform.Set method (AffineTransform object)

These properties are all read-only; to set the properties, use the Set method.

AffineTransform.Set method (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 method (Affine Transform 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.

MapInfo MapX Developer Guide v5.0 271

Chapter 18: The MapX Object Model

AllFeaturesConstraint object
This object allows the programmer to specify that all features in a remote map layer should be stored
in the cache. An AllFeaturesConstraint object is created by calling the
Layer.CreateAllFeaturesConstraint method. A layer can have more than one AllFeaturesConstraint
object associated with it. The Enable and Disable methods of the AllFeaturesConstraint object can be
used to add and remove this constraint after it is created. The Enabled property can be used to
determine the current state of the constraint.
To force a refresh of the cache use the Layer.Refresh method.

Object Properties
• AllFeaturesConstraint.Enabled property

Object Methods
• AllFeaturesConstraint.Disable method
• AllFeaturesConstraint.Enable method

Example
• Example in Visual Basic

See Also
LayerInfo Object on page 412
Working with the Cache on page 178
Layer.CreateAllFeaturesConstraint method (Layer Object) on page 381
BoundsConstraint object on page 285
FeaturesConstraint object on page 322

AllFeaturesConstraint.Disable method (AllFeaturesConstraint

object)
Purpose
Once an AllFeaturesConstraint object is created, this method, along with the Enable method, is used to
control whether the contraint defined by the object is used. When disabled the AllFeaturesConstraint
object is not used to deternine which records are stored in the cache. When enabled the
AllFeaturesConstraint object is used to determine which records are stored in the cache. Unlike the
other constraint objects, when instantiated an AllFeaturesConstraint object is disabled by default.

Syntax
OBJECT.Disable
OBJECT – An AllFeaturesConstraint object

272 MapInfo MapX Developer Guide v5.0

AllFeaturesConstraint.Enable method (AllFeaturesConstraint object)

See Also
Working with the Cache on page 178
AllFeaturesConstraint.Enabled property (AllFeaturesConstraint object) on page 273
AllFeaturesConstraint.Enable method (AllFeaturesConstraint object) on page 273

AllFeaturesConstraint.Enable method (AllFeaturesConstraint

object)
Purpose
Once an AllFeaturesConstraint object is created, this method, along with the Disable method, is used
to control whether the constraint defined by the object is used. When disabled the
AllFeaturesConstraint object is not used to determine which records are stored in the cache. When
enabled the AllFeaturesConstraint object is used to determine which records are stored in the Cache.
When instantiated an AllFeaturesConstraint object is disabled by default, therefore, this method must
be used to initially use the constraint.

Syntax
OBJECT.Enable
OBJECT – An AllFeaturesConstraint object

See Also
Working with the Cache on page 178
AllFeaturesConstraint.Enabled property (AllFeaturesConstraint object) on page 273
AllFeaturesConstraint.Disable method (AllFeaturesConstraint object) on page 272

AllFeaturesConstraint.Enabled property (AllFeaturesConstraint

object)
Purpose
This is a boolean, read-only property. When TRUE, the AllFeaturesConstraint object is being used to
determine what map features are stored in the cache. When FALSE the AllFeaturesConstraint object is
not being used.

See Also
Working with the Cache on page 178
AllFeaturesConstraint.Enable method (AllFeaturesConstraint object) on page 273
AllFeaturesConstraint.Disable method (AllFeaturesConstraint object) on page 272

MapInfo MapX Developer Guide v5.0 273

Chapter 18: The MapX Object Model

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

Annotation.Graphic property (Annotation object)

Purpose
This property contains a Graphic object, which contains the properties for the Annotation. See Graphic
object description.

274 MapInfo MapX Developer Guide v5.0

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 (Map object) on page 438
Graphic.X property (Graphic object) on page 362
Graphic.Y property (Graphic object) on page 362

Annotations.AddText method (Annotations collection)

Purpose
This method adds a text annotation to the Annotations collection. A default style is used (as specified
in Map.DefaultStyle).

MapInfo MapX Developer Guide v5.0 275

Chapter 18: The MapX Object Model

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 (Map object) on page 438
Graphic.Caption property (Graphic object) on page 361
Graphic.Position property (Graphic object) on page 361
Graphic.X property (Graphic object) on page 362
Graphic.Y property (Graphic object) on page 362

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.

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.

276 MapInfo MapX Developer Guide v5.0

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 collection) on page 276

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 (Annotations collection) on page 276

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 v5.0 277

Chapter 18: The MapX Object Model

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.OverwriteFile property
• BindLayer.RefColumn1 property
• BindLayer.RefColumn2 property
• BindLayer.ReferenceLayer property
• BindLayer.ReferenceLayerField property

See Also
Datasets.Add method (Datasets collection) on page 300

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.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.

278 MapInfo MapX Developer Guide v5.0

BindLayer.KeyLength property (BindLayer object)

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.

See Also
BindLayerTypeConstants on page 589
BindLayer.ReferenceLayer property (BindLayer object) on page 281
BindLayer.LayerType property (BindLayer object) on page 279
BindLayer.RefColumn1 property (BindLayer object) on page 281
BindLayer.RefColumn2 property (BindLayer object) on page 281

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.

MapInfo MapX Developer Guide v5.0 279

Chapter 18: The MapX Object Model

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.

See Also
Datasets.Add method (Datasets collection) on page 300
BindLayerTypeConstants on page 589
BindLayer.ReferenceLayer property (BindLayer object) on page 281
BindLayer.LayerType property (BindLayer object) on page 279
BindLayer.RefColumn1 property (BindLayer object) on page 281
BindLayer.RefColumn2 property (BindLayer object) on page 281

BindLayer.OverwriteFile property (BindLayer object)

Purpose
This property allows one to specify whether or not MapX overwrites the file specified by the
Bindlayer.Filespec property (if it already exists). This is a Boolean property which is false by default.

Remarks
This property applies to the X/Y and point-ref data binding (i.e. the BindLayer.LayerType property is
miBindLayerTypeXY or miBindLayerTypePointRef).
This property is used in conjunction with the BindLayer.FileSpec property AND by the Datasets.Add
method to create a permenant layer, stored at the path specified. If this property is set to false, but the
file specified by the BindLayer.Filespec property DOES exist, exception #1230 is thrown.

280 MapInfo MapX Developer Guide v5.0

BindLayer.RefColumn1 property (BindLayer object)

See Also
BindLayer.LayerType property (BindLayer object) on page 279
BindLayer.Filespec property (BindLayer object) on page 278
Datasets.Add method (Datasets collection) on page 300

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
BindLayerTypeConstants on page 589

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 property (BindLayer object) on page 279
BindLayerTypeConstants on page 589

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).

MapInfo MapX Developer Guide v5.0 281

Chapter 18: The MapX Object Model

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 property (BindLayer object) on page 279
BindLayerTypeConstants on page 589

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.

282 MapInfo MapX Developer Guide v5.0

BitmapSymbol.Name property (BitmapSymbol object)

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.

Remarks
The symbol bitmap sizes range from 1 - 48 points. If a BitmapSymbol is less than 1 point size then the
Size property is set to 1. If a BitmapSymbols size is greater than 48 points then the Size property is set
to 48.
Please be aware that 2, 16 and 256 bit color bitmaps ARE supported and 24 bit color is NOT.

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.

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).

Note: Please be aware that 2, 16 and 256 bit color bitmaps ARE supported and 24 bit color is
NOT.

MapInfo MapX Developer Guide v5.0 283

Chapter 18: The MapX Object Model

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 BitmapSymbol object.

index An integer indicating which BitmapSymbol object to return.

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.

Syntax
OBJECT.Refresh ()

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 ()

284 MapInfo MapX Developer Guide v5.0

BoundsConstraint.Bounds property (BoundsConstraint object)

BoundsConstraint object
This object allows the programmer to specify which features is cached for a remote database layer by
specifying the bounds of a rectangle. Any features for which the MinimumBoundingRectangle (MBR)
of the feature intersects the MBR of the rectangle used to define this constraint will be saved in the
cache. A BoundsConstraint object is created by calling the Layer.CreateBoundsConstraint method. A
layer can have more than one BoundsConstraint object associated with it. The Enable and Disable
methods of the BoundsConstraint object can be used to add and remove this constraint after it is
created. The Enabled property can be used to determine the current state of the constraint. The
Bounds property can be used to set or check the MBR that defines this constraint.
To force a refresh of the cache use the Layer.Refresh method.

Object Properties
• BoundsConstraint.Bounds property
• BoundsConstraint.Enabled property

Object Methods
• BoundsConstraint.Disabel method
• BoundsConstraint.Enable method

Example
• Example in Visual Basic

See Also
LayerInfo Object on page 412
Working with the Cache on page 178
Layer.CreateBoundsConstraint method (Layer Object) on page 382
Rectangle Object on page 480
FeaturesConstraint object on page 322
AllFeaturesConstraint object on page 272

BoundsConstraint.Bounds property (BoundsConstraint object)

Purpose
This is a read/write property that takes or returns a MapX Rectangle object. The Rectangle defines the
geographic extents of the BoundsConstraint object, which determines what features are stored in the
cache. Any features for which the MinimumBoundingRectangle (MBR) of the feature intersects the
MBR of the rectangle used to define this constraint will be saved in the cache. By changing the Bounds
property you are potentially changing which features are stored in the cache.

MapInfo MapX Developer Guide v5.0 285

Chapter 18: The MapX Object Model

Syntax
[ Rectangle= ] OBJECT.Bounds
[Rectangle=] – A returned MapX Rectangle object
OBJECT – A BoundsConstraint object

See Also
Rectangle Object on page 480
Working with the Cache on page 178

BoundsConstraint.Disabel method (BoundsConstraint object)

Purpose
Once a BoundsConstraint object is created, this method, along with the BoundsConstraint.Enable
method, is used to control whether the contraint defined by the object is used. When disabled the
BoundsConstraint object is not used to deternine which records are stored in the cache. When enabled
the BoundsConstraint object is used to determine which records are stored in the cache. When
instantiated a BoundsConstraint object is enabled by default.

Syntax
OBJECT.Disable
OBJECT – A BoundsConstraint object

See Also
Working with the Cache on page 178
BoundsConstraint.Enabled property (BoundsConstraint object) on page 287
BoundsConstraint.Enable method (BoundsConstraint object) on page 286
BoundsConstraint.Disabel method (BoundsConstraint object) on page 286

BoundsConstraint.Enable method (BoundsConstraint object)

Purpose
Once a BoundsConstraint object is created, this method, along with the Disable method, is used to
control whether the constraint defined by the object is used. When disabled the BoundsConstraint
object is not used to determine which records are stored in the cache. When enabled the
BoundsConstraint object is used to determine which records are stored in the Cache. When
instantiated a BoundsConstraint object is enabled by default, this method need only be used when the
BoundsConstraint has been disabled via the BoundsConstraint.Disable method.

286 MapInfo MapX Developer Guide v5.0

BoundsConstraint.Enabled property (BoundsConstraint object)

Syntax
OBJECT.Enable
OBJECT – A BoundsConstraint object

See Also
Working with the Cache on page 178
BoundsConstraint object on page 285
BoundsConstraint.Enabled property (BoundsConstraint object) on page 287
BoundsConstraint.Disabel method (BoundsConstraint object) on page 286

BoundsConstraint.Enabled property (BoundsConstraint object)

Purpose
This is a boolean, read only property. When TRUE, the BoundsConstraint object is being used to
determine what map features are stored in the cache. When FALSE the BoundsConstraint object is not
being used.

See Also
Working with the Cache on page 178
BoundsConstraint.Enable method (BoundsConstraint object) on page 286
BoundsConstraint.Disabel method (BoundsConstraint object) on page 286

MapInfo MapX Developer Guide v5.0 287

Chapter 18: The MapX Object Model

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
”Chapter 13: Using Coordinate Systems” on page 191
Map.DisplayCoordSys property (Map object) on page 438
Map.NumericCoordSys property (Map object) on page 451
Layer.CoordSys property (Layer object) on page 383

CoordSys.AffineTransform property (CoordSys object)

Purpose
This is a read-only property that returns an AffineTransform object.

See Also
Affine Transform object on page 270

288 MapInfo MapX Developer Guide v5.0

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.

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.

MapInfo MapX Developer Guide v5.0 289

Chapter 18: The MapX Object Model

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 mapx50.dll.

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).

290 MapInfo MapX Developer Guide v5.0

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 latitude).
StandardParallelTwo
Azimuth Double value, representing the azimuth, in degrees.
ScaleFactor Double value, representing a scale factor.
FalseEasting Double values, representing Falseeasting and FalseNorthing (in Units
FalseNorthing 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 v5.0 291

Chapter 18: The MapX Object Model

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.

292 MapInfo MapX Developer Guide v5.0

CoordSys.Units property (CoordSys object)

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.

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.
For an in depth information on datatypes supported by MapX, see ”Chapter 6: Putting Your Data On
The Map” on page 73 .

Object Properties
• Dataset.Fields property
• Dataset.GeoField property
• Dataset.Layer property
• Dataset.Name property
• Dataset.ReadOnly property
• Dataset.RowCount property
• Dataset.SecondaryGeoField property
• Dataset.SourceRows property
• Dataset.Themes property
• Dataset.Type property

Object Methods
• Dataset.AddField method
• Dataset.Refresh method
• Dataset.RowValues method
• Dataset.Value method

MapInfo MapX Developer Guide v5.0 293

Chapter 18: The MapX Object Model

Collection Properties
• Datasets.BuildSourceRows property
• Datasets.Count property
• Datasets.Item property

Collection Methods
• Datasets.Add method
• Datasets.Contains 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. Though the aggregation type is set to miAggregationSum, the new field will
not hold the aggregated value of any field.
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.

See Also
See “Creating Expressions” on page 605

294 MapInfo MapX Developer Guide v5.0

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 Datasetset.SourceRows 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 Fields collection on page 340

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.

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.

MapInfo MapX Developer Guide v5.0 295

Chapter 18: The MapX Object Model

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 property (Dataset object)

Purpose
This property returns the RowValues object for a given row. It takes as a parameter either a row ID
number (type Long), a serialized key (type String) or the feature object from which to extract the key
(type Feature).

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.

296 MapInfo MapX Developer Guide v5.0

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 data is bound to a layer, Dataset.RowCount actually returns the number of features in the layer.
Items in a Dataset can have NULL values if no data is bound to the feature.
Dataset.RowCount will return a value of zero when the dataset was created from a DBMS server.

See Also
Layer.AllFeatures method (Layer object) on page 380
Features.Count property (Features collection) on page 320

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 on page 485
Layer.UpdateFeature method (Layer object) on page 401
Feature.Update method (Feature object) on page 317

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.

MapInfo MapX Developer Guide v5.0 297

Chapter 18: The MapX Object Model

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 (Datasets collection) on page 300

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.

See Also
SourceRow Object and SourceRows Collection on page 497
Feature.KeyValue property (Feature object) on page 312

Dataset.Themes property (Dataset object)

Purpose
Themes collection for the Dataset.

See Also
Theme Object and Themes Collection on page 526

298 MapInfo MapX Developer Guide v5.0

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.

See Also
DataSetTypeConstants on page 594

Dataset.Value method (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.

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.

MapInfo MapX Developer Guide v5.0 299

Chapter 18: The MapX Object Model

See Also
Feature.KeyValue property (Feature object) on page 312
'Feature.Name property (Feature object) on page 314

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.
NOTE: When miBindLayerTypeXY is used within DataSets.Add a
temporary table will be created with one column named "GeoName",
in order for a fields collection to be recognized a new databind must
be created on a permanent layer.

300 MapInfo MapX Developer Guide v5.0

Datasets.Add method (Datasets collection)

Part Description

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.
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.

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.
When miBindLayerTypeXY is used within DataSets.Add a temporary table will be created with one
column named "GeoName", in order for a fields collection to be recognized a new databind must be
created on a permanent 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.

MapInfo MapX Developer Guide v5.0 301

Chapter 18: The MapX Object Model

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 on page 340

Datasets.Contains method (Datasets object)

Purpose
This property returns True if the dataset specified by the argument is present in the collection. The
argument can be either the Dataset name or a 1 based index number. This method is useful for
restoring datasets via the State object.

Syntax
OBJECT.Contains(Index)

Part Description

OBJECT This is a Datasets object.

Index This is the Dataset name or 1 based index number.

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 v5.0

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

MapInfo MapX Developer Guide v5.0 303

Chapter 18: The MapX Object Model

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 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

Object Methods
• Datum.Set method
• Datum.SetFromList method

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."

Datum.Flattening property (Datum object)

Purpose
This is a read-only property that returns a double value representing the Datum's flattening.

304 MapInfo MapX Developer Guide v5.0

Datum.PrimeMeridian property (Datum object)

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.

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..

MapInfo MapX Developer Guide v5.0 305

Chapter 18: The MapX Object Model

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 method (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) on page 306

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.

306 MapInfo MapX Developer Guide v5.0

Datum.ShiftX, ShiftY, ShiftZ properties (Datum object)

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.

MapInfo MapX Developer Guide v5.0 307

Chapter 18: The MapX Object Model

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.CenterXproperty, CenterYproperty
• Feature.FeatureID property
• Feature.FeatureKey property
• Feature.HasMultipoint property
• Feature.HasPolyline property
• Feature.HasRegion property
• Feature.KeyValue property
• Feature.LabelPoint property
• Feature.Layer property
• Feature.Length property
• Feature.Multipoint property
• Feature.Name property
• Feature.Nodes property
• Feature.Parts property
• Feature.Perimeter property
• Feature.Point property
• Feature.Polyline property
• Feature.Region property
• Feature.Smooth property
• Feature.Style property
• Feature.Type property

Object Methods
• Feature.Attach method
• Feature.Clone method
• Feature.Offset method
• Feature.Update method

308 MapInfo MapX Developer Guide v5.0

Feature.Area property (Feature object)

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.RemoveByID method
• Features.Replace method

See Also
Selection Collection on page 489
Layer.Search method (Layer object) on page 395

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).

See Also
Map.AreaUnit property (Map object) on page 429

Feature.Attach method (Feature object)

Purpose
Attaches a stand-alone feature to the map so that the map's coordinate system applies to the feature.

Syntax
OBJECT.Attach (Map)

Part Description

OBJECT A feature object.

Map A map object.

MapInfo MapX Developer Guide v5.0 309

Chapter 18: The MapX Object Model

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).

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.

310 MapInfo MapX Developer Guide v5.0

Feature.CenterX property, CenterYproperty (Feature object)

Part Description

= string A text string, up to 255 characters long.

See Also
Feature Object and Features Collection on page 308

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

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 (Selection collection) on page 495
Dataset.Value method (Dataset object) on page 299

MapInfo MapX Developer Guide v5.0 311

Chapter 18: The MapX Object Model

Dataset.SourceRows property (Dataset object) on page 298

Layer.UpdateFeature method (Layer object) on page 401)
Layer.DeleteFeature method (Layer object) on page 384
Features.AddByID method (Features collection) on page 318
Features.RemoveByID method (Features collection) on page 320
Selection.SelectByID method (Selection collection) on page 492

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.

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 property (Layer object) on page 391
Layer Object and Layers Collection on page 377

Feature.HasMultipoint property (Feature object)

Purpose
This read-only property returns true if the Collection object has a Multipoint part or false if it does not.

Syntax
[bool= ] OBJECT.HasMultipoint

Feature.HasPolyline property (Feature object)

Purpose
This read-only property returns true if the Collection object has Polyline part or false if it does not.

312 MapInfo MapX Developer Guide v5.0

Feature.HasRegion property (Feature object)

Syntax
[bool= ] OBJECT.HasPolyline

Feature.HasRegion property (Feature object)

Purpose
This read-only property returns true if the Collection object has Region part or false if it does not.

Syntax
[bool= ] OBJECT.HasRegion

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 and Points Collection on page 472

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 and Layers Collection on page 377

Feature.Length property (Feature object)

Purpose
This is a read-only property that returns the sum of the lengths of the line segments that make up a
polyline. If the feature has several parts, the value returned is the sum of all the line segments in all
the parts.

Note: The length calculation does not take into account the curvature of the Earth, so it will
generally be inaccurate for line segments spanning long distances. Length is determined
using a modified Cartesian calculation: longitude/latitude coordinates are converted to X,
Y coordinates in MapX's current map units, taking into account the number of miles per
degree of longitude at each line segment's centroid. The distance between the resulting
points is then calculated using the Pythagorean Theorem.

MapInfo MapX Developer Guide v5.0 313

Chapter 18: The MapX Object Model

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
Feature.Length returns a value based on the "modified" version of the object (the object as it exists in
memory).

See Also
Feature.Perimeter property (Feature object) on page 315
Map.MapUnit property (Map object) on page 445

Feature.Multipoint property (Feature object)

Purpose
This read/write property returns the Multipoint part of feature, that has a type of
miFeatureTypeCollection.

Remarks
Reading from this property returns the multipoint part of a collection feature (if it exists). This feature
is returned as a stand-alone feature, if editing is done on this feature, in order to have edits saved in a
table, user need to update the parent feature.
Writing to this property makes a copy of a feature passed in and sets it into an existing collection
feature.

'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 (LabelProperties object) on page 372

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.

314 MapInfo MapX Developer Guide v5.0

Feature.Offset method (Feature object)

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.

Feature.Offset method (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.

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.

MapInfo MapX Developer Guide v5.0 315

Chapter 18: The MapX Object Model

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 property (Feature object) on page 313

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 and Points Collection on page 472

Feature.Polyline property (Feature object)

Purpose
This read/write property returns the Polyline part of a feature, that has a type of
miFeatureTypeCollection.

Remarks
Reading from this property returns the Polyline part of a collection feature (if it exists) and is returned
as a stand-alone feature. If editing is done on this feature, in order to have edits saved in a table, the
user needs to update parent feature.
Writing to this property makes a copy of the feature passed in and sets it into existing collection
feature.

Feature.Region property (Feature object)

Purpose
This read/write property returns region part of feature, that has type miFeatureTypeCollection .

Remarks
Reading from this property returns the region part of a collection feature (if it exists) and is returned as
a stand-alone feature. If editing is done on this feature, in order to have edits saved in a table, the user
needs to update parent feature.
Writing to this property makes a copy of the feature passed in and sets it into existing collection
feature.

316 MapInfo MapX Developer Guide v5.0

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 on page 507

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 method (FeatureFactory object) on page 334

Feature.Update method (Feature object)

Purpose
This method updates the layer with changes made to the Feature object.

Syntax
OBJECT.Update ( [UpdateFeature] , [RowValues] )

Part Description

OBJECT Represents a place holder for a Feature object.

UpdateFeature Boolean value that indicates whether or not to update the object
column. Its default is True.

MapInfo MapX Developer Guide v5.0 317

Chapter 18: The MapX Object Model

Part Description

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.
Note: The object column stores the geographic data for the Feature object.

Remarks
If the RowValues collection points to fields added via the Dataset.AddField method, then these fields
will not be not updateable.

Features.Add method (Features collection)

Purpose
Add a Feature object or all features from a Features object into the collection (UNION set operation).

Syntax
OBJECT.Add (Source)

Part Description

OBJECT Represents a place holder for a Features object.

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.

320 MapInfo MapX Developer Guide v5.0

Features.Replace method (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.

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".

MapInfo MapX Developer Guide v5.0 321

Chapter 18: The MapX Object Model

FeaturesConstraint object
This object allows the programmer to specify which features will be cached for a remote database layer
by specifying a MapX Features collection. A FeaturesConstraint object is created by calling the
Layer.CreateFeaturesConstraint method. A layer can have more than one FeaturesConstraint object
associated with it. The Enable and Disable methods of the FeaturesConstraint object can be used to
add and remove this constraint after it is created. The Enabled property can be used to determine the
current state of the constraint. The Features property can be used to set or check the Features
collection that defines this constraint.
To force a refresh of the cache use the Layer.Refresh method.

Object Properties
• FeaturesConstraint.Enabled property
• FeaturesConstraint.Features property

Object Methods
• FeaturesConstraint.Diasable method
• FeaturesConstraint.Enable method

Example
• Example in VB

See Also
LayerInfo Object on page 412
Working with the Cache on page 178
Feature Object and Features Collection on page 308
Layer.CreateFeaturesConstraint method (Layer Object) on page 382
AllFeaturesConstraint object on page 272
BoundsConstraint object on page 285

FeaturesConstraint.Diasable method (FeaturesConstraint object)

Purpose
Once a FeaturesConstraint object is created, this method, along with the Enable method, is used to
control whether the contraint defined by the object that is used. If enabled, the FeaturesConstraint
object is used to determine which records are stored in the cache. When instantiated, a
FeaturesConstraint object is enabled by default.

Syntax
OBJECT.Disable
OBJECT – A FeaturesConstraint object

322 MapInfo MapX Developer Guide v5.0

FeaturesConstraint.Enabled property (FeaturesConstraint object)

See Also
Working with the Cache on page 178
FeaturesConstraint.Enabled property (FeaturesConstraint object) on page 323
FeaturesConstraint.Enable method (FeaturesConstraint object) on page 323

FeaturesConstraint.Enabled property (FeaturesConstraint object)

Purpose
This is a boolean, read only property. When TRUE, the FeaturesConstraint object is being used to
determine what map features are stored in the cache. When FALSE the FeaturesConstraint object is
not being used.

See Also
Working with the Cache on page 178
FeaturesConstraint.Enable method (FeaturesConstraint object) on page 323
FeaturesConstraint.Diasable method (FeaturesConstraint object) on page 322

FeaturesConstraint.Features property (FeaturesConstraint object)

Purpose
This is a read/write property that takes or returns a MapX Features object. The Features collection
determines which records from a remote layer will be stored in the cache.

Syntax
[Rectangle=] OBJECT.Bounds
Rectangle – A MapX Rectangle object
OBJECT – A FeaturesConstraint object

See Also
Feature Object and Features Collection on page 308
Working with the Cache on page 178

FeaturesConstraint.Enable method (FeaturesConstraint object)

Purpose
Once a FeaturesConstraint object is created, this method, along with the Disable method, is used to
control whether the constraint defined by the object is used. When disabled the FeaturesConstraint
object is not used to determine which records are stored in the cache. When enabled the

MapInfo MapX Developer Guide v5.0 323

Chapter 18: The MapX Object Model

FeaturesConstraint object is used to determine which records are stored in the Cache. When
instantiated a FeaturesConstraint object is enabled by default, this method need only be used when the
FeaturesConstraint has been disabled via the FeaturesConstraint.Disable method.

Syntax
OBJECT.Enable
OBJECT – A FeaturesConstraint object

See Also
Working with the Cache on page 178
FeaturesConstraint object on page 322
FeaturesConstraint.Enabled property (FeaturesConstraint object) on page 323
FeaturesConstraint.Diasable method (FeaturesConstraint object) on page 322

324 MapInfo MapX Developer Guide v5.0

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.CreateCollectionFeature method
• FeatureFactory.CreateEllipticalRegion method
• FeatureFactory.CreateLine method
• FeatureFactory.CreateMultipoint method
• FeatureFactory.CreateRegion method
• FeatureFactory.CreateSymbol method
• FeatureFactory.CreateText method
• FeatureFactory.EraseFeature method
• FeatureFactory.IntersectFeatures method
• FeatureFactory.IntersectionPoints method
• FeatureFactory.IntersectionTest method

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.

FeatureFactory.CreateArc method (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.

Point1, 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.

MapInfo MapX Developer Guide v5.0 327

Chapter 18: The MapX Object Model

Part Description

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 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

328 MapInfo MapX Developer Guide v5.0

FeatureFactory.CreateArc method (FeatureFactory object)

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

90 0.5

90 0.25

165 1

165 0.5

MapInfo MapX Developer Guide v5.0 329

Chapter 18: The MapX Object Model

Angle Offset Result

270 0.5

See Also
FeatureFactory.CreateEllipticalRegion method (FeatureFactory object) on page 332

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.

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,767, the minimum is 3. 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.

330 MapInfo MapX Developer Guide v5.0

FeatureFactory.CreateCollectionFeature method (FeatureFactory object)

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.

See Also
FeatureFactory.BufferFeatures method (FeatureFactory object) on page 325
FeatureFactory.CreateEllipticalRegion method (FeatureFactory object) on page 332

FeatureFactory.CreateCollectionFeature method (FeatureFactory

object)
Purpose
This creates a collection type feature, and returns it as a stand-alone Feature object. The feature can be
added to a layer, used in searches, etc..

Syntax
[Featurel= ] OBJECT.CreateCollectionFeature ([feature1], [feature2], [feature3])

Remarks
This method creates a stand-alone Feature object. You can pass up to three features objects as
parameters to this method. At most, you can pass one region feature, one polyline feature and one
multipoint feature. If no parameters are passed then an empty feature of type
miFeatureTypeCollection is created. You can't pass feature of the same type to this method.

Part Description

OBJECT A FeatureFactory object

feature1 Variant: A feature object representing region, polyline or multipoint feature.
This is an optional argument
feature2 Variant: A feature object representing region, polyline or multipoint feature.
This is an optional argument
feature3 Variant: A feature object representing region, polyline or multipoint feature.
This is an optional argument

MapInfo MapX Developer Guide v5.0 331

Chapter 18: The MapX Object Model

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 object) on page 327
FeatureFactory.CreateCircularRegion method (FeatureFactory object) on page 330

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] )

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.

MapInfo MapX Developer Guide v5.0 333

Chapter 18: The MapX Object Model

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.

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

334 MapInfo MapX Developer Guide v5.0

FeatureFactory.EraseFeature method (FeatureFactory 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 feature 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.

MapInfo MapX Developer Guide v5.0 335

Chapter 18: The MapX Object Model

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.

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. To perform the

336 MapInfo MapX Developer Guide v5.0

FeatureFactory.IntersectFeatures method (FeatureFactory object)

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.

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:

MapInfo MapX Developer Guide v5.0 337

Chapter 18: The MapX Object Model

• 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 method (FeatureFactory object)

Purpose
This returns a Points collection containing the points where two features intersect.

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.

338 MapInfo MapX Developer Guide v5.0

FeatureFactory.IntersectionTest method (FeatureFactory object)

Setting Value Description

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.

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.

MapInfo MapX Developer Guide v5.0 339

Chapter 18: The MapX Object Model

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
miLayerInfoTypeNewTable. 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.Indexed property
• Field.Name property
• Field.Type property
• Field.TypeEx 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
• Fields.AddIntegerField
• Fields.AddLogicalField
• Fields.AddNumericField method
• Fields.AddSmallIntField method
• Fields.AddStringField method4
• Fields.Count property
• Fields.Item property
• Fields.Remove method
• Fields.RemoveAll method

See Also
LayerInfo Object on page 412
Dataset object and Datasets collection on page 293

340 MapInfo MapX Developer Guide v5.0

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 read-only property, and is set to one of the AggregationFunctionConstants. It is
initialized in the Fields.Add method.

See Also
Fields.Add method (Fields collection) on page 343

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.Indexed property (Field object)

Purpose
This read-only property returns true if a field in an underlying table is indexed.

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 v5.0 341

Chapter 18: The MapX Object Model

Field.Type property (Field object)

Purpose
This property returns a field type, but only for fields of type String, Date and Numeric types. This is a
read-only property.

Note: The Field.TypeEx property has been added to MapX in order to return ALL of the
FieldTypeConstants.

Remarks
The table below describes what data types are returned when using Field.Type and Field.TypeEx.

Field Type MapX returns Using Field.Type MapX returns Using Field.TypeEx

Integer numeric Integer

Character Character Character
Float numeric Float
Logical numeric Logical
Date Date Date
Small Int numeric Small Int
Decimal(4,2) numeric numeric

See Also
Field.TypeEx property (Field object) on page 342

Field.TypeEx property (Field object)

Purpose
This property returns a field type with a FieldTypeConstants value. This is a read-only property.
Note: This property is new to MapX. It was implemented to correct a problem with the
Field.Type property. The Field.Type property could only return String, Date, and Numeric
types. The Field.TypeEx property can return ALL of the FieldTypeConstants.

Remarks
The table below describes what data types are returned when using Field.Type and Field.TypeEx.

Field Type MapX returns Using Field.Type MapX returns Using Field.TypeEx

Integer numeric Integer

Character Character Character
Float numeric Float

342 MapInfo MapX Developer Guide v5.0

Fields.Add method (Fields collection)

Field Type MapX returns Using Field.Type MapX returns Using Field.TypeEx

Logical numeric Logical

Date Date Date
Small Int numeric Small Int
Decimal(4,2) numeric numeric

See Also
Field.Type property (Field object) on page 342

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.

See Also
Datasets.Add method (Datasets collection) on page 300
Dataset.Fields property (Dataset object) on page 295

MapInfo MapX Developer Guide v5.0 343

Chapter 18: The MapX Object Model

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, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the date field.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the float filed.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

Fields.AddIntegerField (Fields 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.

344 MapInfo MapX Developer Guide v5.0

Fields.AddLogicalField method (Fields collection)

Syntax
OBJECT.AddIntegerField (Name, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the the integer field.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the the logical field.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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.

MapInfo MapX Developer Guide v5.0 345

Chapter 18: The MapX Object Model

Syntax

OBJECT.AddNumericField(Name, Precision, Decimals, [Indexed])

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.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the small integer field.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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.

346 MapInfo MapX Developer Guide v5.0

Fields.Count property (Fields collection)

Syntax
OBJECT.AddStringField(Name, Width, [Indexed])

Part Description

OBJECT This represents the Fields collection.

Name This is the name of the the string field.
Width This is the specified length of the sting. Valid values are integers
between 1 and 254.
Indexed Boolean: this indicates if an index should be created on this field. The
default value is false.

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.

MapInfo MapX Developer Guide v5.0 347

Chapter 18: The MapX Object Model

Fields.RemoveAll method (Fields collection)

Purpose
Removes all Field objects from the collection.

Syntax
OBJECT.RemoveAll

348 MapInfo MapX Developer Guide v5.0

Find.Abbreviations property (Find object)

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 FALSE. When FALSE, MapX does not
refer to the abbreviations file. If set to 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.

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 property determines the maximum number of matches the FindResult object may contain. 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

MapInfo MapX Developer Guide v5.0 349

Chapter 18: The MapX Object Model

default for this property is eight and takes an integer value which must be >= 0 or MapX throws 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.

Find.FindDataset property (Find object)

Purpose
Dataset of field to match against. If not specified, a layer's KeyField 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
Find.FindDataset property (Find object) on page 350

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.

350 MapInfo MapX Developer Guide v5.0

Find.OtherBoundary property (Find object)

Part Description

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 Object on page 357
FindMatch Object and FindMatches Collection on page 355

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.

MapInfo MapX Developer Guide v5.0 351

Chapter 18: The MapX Object Model

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 object) on page 351
Find.RefineDataset property (Find object) on page 351

Find.Search method (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 on page 349
FindFeature object on page 353

352 MapInfo MapX Developer Guide v5.0

FindFeature.FindRC property (FindFeature object)

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 and Features Collection on page 308Feature object
”Chapter 9: Finding Features on a Map” on page 129

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

MapInfo MapX Developer Guide v5.0 353

Chapter 18: The MapX Object Model

Digit Values Meaning

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

354 MapInfo MapX Developer Guide v5.0

FindMatch.Name property (FindMatch object)

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 property
• FindMatch.Name property

Collection Properties
• FindMatches.Count property)
• FindMatches.Item property

See Also
FindResult Object on page 357
Find.SearchEx method (Find object) on page 350

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.Score property (FindMatch object)

Purpose
This property returns the matching score for close matches or zero for no match—100 (exact match).

MapInfo MapX Developer Guide v5.0 355

Chapter 18: The MapX Object Model

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.

356 MapInfo MapX Developer Guide v5.0

FindResult.AddressOutOfRange property (FindResult object)

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
Find.SearchEx method (Find object) on page 350

FindResult.AddressOutOfRange property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the address number is outside the 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 object) on page 358
FindResult.Matches property (FindResult object) on page 358
FindResult.MultipleMatches property (FindResult object) on page 358

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.

MapInfo MapX Developer Guide v5.0 357

Chapter 18: The MapX Object Model

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 (Find object) on page 350

FindResult.Matches property (FindResult object)

Purpose
This property returns the resulting Match collection from a Find.SearchEx.

See Also
Find.SearchEx method (Find object) on page 350

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 (Find object) on page 350

FindResult.RefineRegion property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the refining region is specified.

FindResult.Substitute property (FindResult object)

Purpose
This property returns a Boolean value of TRUE if the substitute was used from an abbreviation file.

358 MapInfo MapX Developer Guide v5.0

Geoset.Centroid property (Geoset object)

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

Geoset.Centroid property (Geoset object)

Purpose
This specifies the Point object defining the geographic center of the geoset.

See Also
Point Object and Points Collection on page 472

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.

MapInfo MapX Developer Guide v5.0 359

Chapter 18: The MapX Object Model

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.

360 MapInfo MapX Developer Guide v5.0

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 and Annotations Collection on page 274

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 (Annotation object) on page 275
AnnotationTypeConstants on page 588

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 (Annotation object) on page 275

Graphic.Style property (Graphic object)

Purpose
A Style object containing the style of the symbol or text. This is a read-write property.

MapInfo MapX Developer Guide v5.0 361

Chapter 18: The MapX Object Model

See Also
Style Object on page 507
Annotation.Type property (Annotation object) on page 275

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 (Annotation object) on page 275
AnnotationTypeConstants on page 588
Graphic.Position property (Graphic object) on page 361

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 (Annotation object) on page 275
AnnotationTypeConstants on page 588
Graphic.Position property (Graphic object) on page 361

362 MapInfo MapX Developer Guide v5.0

IndividualValueCategories.AllOthersCategory property (IndividualValueCategories col-

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 on page 418
ThemeProperties.IndividualValueCategories property (ThemeProperties object) on page 537

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.

IndividualValueCategories.Count property (IndividualValueCate-

gories collection)
Purpose
This is a read-only integer value, indicating the number of unique individual values in the theme.

MapInfo MapX Developer Guide v5.0 363

Chapter 18: The MapX Object Model

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 (IndividualValueCat-

egories 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 (IndividualValueCatego-

ries 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 on page 507

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 (IndividualValueCategory object) on page 364

364 MapInfo MapX Developer Guide v5.0

IndividualValueCategory.Value property (IndividualValueCategory object)

Label object and Labels collection

There is a Labels collection for each layer in the Map. Each item in the collection is a Label object. The
Labels collection for a layer consists of all labels in that layer that are currently visible in the map
window or in the cache, as well as any labels from that layer that have been edited either manually
(selected or moved using the stock Select tool or added using the stock Label tool) or programatically
(using methods and properties of the Layer object and Layers Collection).
By editing the properties of a label object the user can change the position or style of a label
independently of other labels in that layer.

Label object properties

• Label.AnchorX property
• Label.AnchorY property
• Label.Angle property
• Label.Caption property
• Label.Drawn property
• Label.Edited property
• Label.EditedAnchor property
• Label.EditedAngle property
• Label.EditedCaption property
• Label.EditedLineStyle property
• Label.EditedLineType property
• Label.EditedMultiSegment property
• Label.EditedOffset property
• Label.EditedPosition property
• Label.EditedTextStyle property
• Label.EditedVisibile property
• Label.Layer property
• Label.LineType property
• Label.MultiSegment property
• Label.Offset property
• Label.Position property
• Label.Selected property
• Label.Style property
• Label.Visible property

See Also
Layer.Labels property (Layer object) on page 391
LabelProperties.LabelAlong property (LabelProperties object) on page 373
LabelProperties.LabelPartialObjects property (LabelProperties object) on page 374

MapInfo MapX Developer Guide v5.0 365

Chapter 18: The MapX Object Model

Label.AnchorX property (Label object)

Purpose
This read/write property is the X coordinate of the label's anchor location. This is a double value
representing the longitude in degrees (negative values for the Western hemisphere).

Label.AnchorY property (Label object)

Purpose
This read/write property is the Y coordinate of the label's anchor location. This is a double value
representing the latitude in degrees.

Label.Angle property (Label object)

Purpose
This read/write property is the label's counter-clockwise rotation angle in degrees. It is not applicable
if the label is multi-segmented.

Label.Caption property (Label object)

Purpose
This read/write property gets the label's text.

Label.Drawn property (Label object)

Purpose
This read-only property is set to true if the label is drawn in the current view.

Label.Edited property (Label object)

Purpose
This read-only property is set to "True" if the label has been customized in some way (programatically
or with the SelectPoint tool). It is set to "False" if not.

366 MapInfo MapX Developer Guide v5.0

Label.EditedAnchor property (Label object)

Purpose
This read-only property is set to "True" if label's anchor has been customized in some way
(programatically or with the SelectPoint tool). It is set to "False" if not.

See Also
Label.AnchorX property (Label object) on page 366
Label.AnchorY property (Label object) on page 366

Label.EditedAngle property (Label object)

Purpose
This read-only property is set to "True" if label's Angle has been customized programatically. It is set
to "False" if not

See Also
Label.Angle property (Label object) on page 366

Label.EditedCaption property (Label object)

Purpose
This read-only property is set to "True" if label's caption has been customized programatically. It is set
to "False" if not.

See Also
Label.Caption property (Label object) on page 366

Label.EditedLineStyle property (Label object)

Purpose
This read-only property is set to "True" if label's callout line style has been customized
programatically. It is set to "False" if not.

See Also
Label.Style property (Label object) on page 370

MapInfo MapX Developer Guide v5.0 367

Chapter 18: The MapX Object Model

Label.EditedLineType property (Label object)

Purpose
This read-only property is set to "True" if label's callout line type has been customized programatically.
It is set to "False" if not.

See Also
Label.LineType property (Label object) on page 369

Label.EditedMultiSegment property (Label object)

Purpose
This read-only property is set to "True" if the label's multi-segment status has been changed
(programatically or with the SelectPoint tool). It is set to "False" if not.

See Also
Label.MultiSegment property (Label object) on page 370

Label.EditedOffset property (Label object)

Purpose
This read-only property is set to "True" if the label's offset has been customized in some way
(programatically or with the SelectPoint tool). It is set to "False" if not.

See Also
Label.Offset property (Label object) on page 370

Label.EditedPosition property (Label object)

Purpose
This read-only property is set to "True" if the label's position has been customized in some way
(programatically or with the SelectPoint tool). It is set to "False" if not.

See Also
Label.Position property (Label object) on page 370

368 MapInfo MapX Developer Guide v5.0

Label.EditedTextStyle property (Label object)

Purpose
This read-only property is set to "True" if label's text style is customized programatically. It is set to
"False" if not.

Label.EditedVisibile property (Label object)

Purpose
This read-only property is set to "True" if the label's visibility is customized in some way
(programatically or with the SelectPoint tool). It is set to "False" if not.

See Also
Label.Visible property (Label object) on page 371

Label.FeatureKey (Label object)

Purpose
This read-only property returns the key of the feature associated with the label. Use this key to access
the feature with Layer.GetFeatureByKey.

See Also
Layer.GetFeatureByKey method (Layer object) on page 390

Label.Layer property (Label object)

Purpose
This read-only property sets the layer to which the label belongs.

See Also
Layer Object and Layers Collection on page 377

Label.LineType property (Label object)

Purpose
This read/write property gets the label's callout line type (miLineTypeArrow, miLineTypeNone, or
miLineTypeSimple).

MapInfo MapX Developer Guide v5.0 369

Chapter 18: The MapX Object Model

Label.MultiSegment property (Label object)

Purpose
This read/write property gets the label's multi-segment status. It is “True” if the label is a multi-
segment label, “False” otherwise.

Label.Offset property (Label object)

Purpose
This read/write property gets the distance (in pixels) that the label is offset from its anchor location.

See Also
LabelProperties.Offset property (LabelProperties object) on page 375

Label.Position property (Label object)

Purpose
This read/write property gets the label's position relative to its anchor position. This takes a
PositionConstants value.

Label.Selected property (Label object)

Purpose
This read/rwite indicates whether the label is selected or not. (Read/Write property).

Label.Style property (Label object)

Purpose
This read/write property gets a label's text style.

See Also
Style Object on page 507

370 MapInfo MapX Developer Guide v5.0

Label.Visible property (Label object)

Purpose
This read/write property indicates whether the label has been hidden or not. A hidden label means
that when a label qualifies to be drawn automatically, if it is marked as hidden, it does not get drawn.

Labels.Count property (Labels collection)

Purpose
This read-only property counts the number of labels in the labels collection.

Labels.Item property (Labels Collection)

Purpose
This read/write property gets a specific label from the labels collection. It takes an integer index value
starting at 1. This is the default property for the Labels collection.

MapInfo MapX Developer Guide v5.0 371

Chapter 18: The MapX Object Model

LabelProperties Object
The LabelProperties object contains properties that control how labels are drawn for the layer.

Object Properties
• LabelProperties.DataField
• LabelProperties.Dataset
• LabelProperties.Duplicate
• LabelProperties.LabelAlong
• LabelProperties.LabelMax
• LabelProperties.LabelPartialObjects
• LabelProperties.LabelZoom
• LabelProperties.LabelZoomMax
• LabelProperties.LabelZoomMin
• LabelProperties.LineType
• LabelProperties.Offset
• LabelProperties.Overlap
• LabelProperties.Parallel
• LabelProperties.PartialSegments
• LabelProperties.Position
• LabelProperties.Style
• LabelProperties.Visible

See Also
Layer Object and Layers Collection on page 377

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 (LabelProperties object) on page 372
Field object and Fields collection on page 340

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

372 MapInfo MapX Developer Guide v5.0

LabelProperties.Duplicate property (LabelProperties object)

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 (LabelProperties object) on page 372
Dataset object and Datasets collection on page 293

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.LabelAlong property (LabelProperties object)

Purpose
With the LabelAlong property, you may indicate that the label will follow the contour of what it is
labeling if the object being labeled is a polyline. It has three states, represented by the
LabelAlongConstants.

Remarks
The LabelAlong property replaces the old Parallel property, which we still support but have
deprecated to a hidden property. The parallel property dictated whether labels on lines and polylines
are not rotated or are drawn at the same angle as the line or polyline segment to which they are
anchored.
For objects other than polylines, if the property is set to miLabelAlongMultiSegment, the property is
ignored (i.e., for point and region objects). For line objects, if the property is set to
miLabelAlongMultiSegment, automatic labels are drawn as if the property is set to
miLabelAlongParallel.

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.

MapInfo MapX Developer Guide v5.0 373

Chapter 18: The MapX Object Model

LabelProperties.LabelPartialObjects property (LabelProperties

object)
Purpose
Setting this value to true enables MapX to label map objects, even if only a small part of the map object
is currently visible. However, this property is not applicable to point objects. This is a Boolean value,
and the default is False.

Remarks
This property allows a label to be automatically displayed even if the centroid of the object is not in the
map view.

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 object) on page 374
LabelProperties.LabelZoomMin property (LabelProperties object) on page 375

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 (LabelProperties object) on page 374
Map.MapUnit property (Map object) on page 445

374 MapInfo MapX Developer Guide v5.0

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 (LabelProperties object) on page 374
Map.MapUnit property (Map object) on page 445

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 miLineTypeArrow.

See Also
LabelProperties.Offset property (LabelProperties object) on page 375

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 set to miPositionCC (center-center), then the

LableProperties.Offset property will be ignored.

See Also
LabelProperties.Position property (LabelProperties object) on page 376
LabelProperties.LineType property (LabelProperties object) on page 375

LabelProperties.Overlap property (LabelProperties object)

Purpose
This property allow labels to overlap with each other when they are drawn on a layer. This is a
Boolean value, and the default is False.

MapInfo MapX Developer Guide v5.0 375

Chapter 18: The MapX Object Model

Remarks
The LabelProperties.Overlap is used only for auto labels. For manually labeled features, Overlap is
ignored.

LabelProperties.Parallel property (LabelProperties object)

Note: This is a 'deprecated' property that still works for backward compatability. Please use the
LabelProperties.LabelAlong property (LabelProperties object) on page 373 instead.

LabelProperties.PartialSegments property (LabelProperties

object)
Note: This is a 'deprecated' property that still works for backward compatability. Please use the
LabelProperties.LabelPartialObjects property (LabelProperties object) on page 374 instead.

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 miPositionCR
• 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.

376 MapInfo MapX Developer Guide v5.0

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 are 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.
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.ClippedBounds property
• Layer.CoordSys property

MapInfo MapX Developer Guide v5.0 377

Chapter 18: The MapX Object Model

• 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.ShowCentroids property
• Layer.ShowLineDirection property
• Layer.ShowNodes 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.FeatureIDFromFeatureName method
• Layer.FeatureKeyFromFeatureName method
• Layer.GetDrilldownFeaturesByID method
• 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.ClippedBounds property
• Layers.Count property

378 MapInfo MapX Developer Guide v5.0

Layer.AddFeature method (Layer object)

• Layers.Item property

Collection Methods
• Layers. Remove method
• Layers.Add method
• Layers.AddGeosetLayers method
• Layers.AddServerLayer method
• Layers.AddUserDrawLayer method
• Layers.ClearSelection method
• Layers.CreateLayer method
• Layers.InsertionLayer
• Layers.LayersDlg method
• Layers.Move method
• Layers.RemoveAll method

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.

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 object) on page 380
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.SearchWithinFeature method (Layer object) on page 398

MapInfo MapX Developer Guide v5.0 379

Chapter 18: The MapX Object Model

Layer.SearchWithinRectangle method (Layer object) on page 398

Layer.UpdateFeature method (Layer object) on page 401
Feature.FeatureKey property (Feature object) on page 311

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 object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.SearchWithinFeature method (Layer object) on page 398
Layer.SearchWithinRectangle method (Layer object) on page 398
Layer.UpdateFeature method (Layer object) on page 401

Layer.AutoLabel property (Layer object)

Purpose
This property controls whether a layer is automatically labeled. In order for a label to be displayed
automatically, its centroid must be within the viewable map area. This is a Boolean value, and its
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.

380 MapInfo MapX Developer Guide v5.0

Layer.Bounds property (Layer object)

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.

See Also
Layer.EndAccess method (Layer object) on page 387

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 property (Layers collection) on page 407

Layer.CreateAllFeaturesConstraint method (Layer Object)

Purpose
This method creates a new AllFeaturesConstraint object for use in controlling the data in the cache.

Syntax
[objAllFeaturesConstraint = ]OBJECT.CreateAllFeaturesConstraint

Remarks
The data that is held in the cache by this object is only held as long as the constraint (or some other
constraint) exists. Thus, specifying code such as:
lyr.CreateAllFeaturesObject.Enable = True

MapInfo MapX Developer Guide v5.0 381

Chapter 18: The MapX Object Model

This code will creates constraint and that ensures that all records are cached as it is above). However,
the newly created constraint object is then destroyed releasing the records from the cache. To be
effective, the constraint object must be stored in a variable by the client and released (or set to Nothing
or Enabled = False) when the records are no longer needed.
Unlike the BoundsConstraint and FeaturesConstraint, the AllFeatures constraint is initially disabled
and will not ensure that all records are cached until the constraint is enabled.

See Also
AllFeaturesConstraint object on page 272
Feature Object and Features Collection on page 308

Layer.CreateBoundsConstraint method (Layer Object)

Purpose
This method is used to create a new BoundsConstraint object for use in controlling the cached data in
the layer.

Syntax
[objBoundsConstraint = ]OBJECT.CreateBoundsConstraint
Remarks
The data that is held in cache by this object is only held as long as the constraint (or some other
constraint) exists. Thus, specifying code such as:
Set lyr.CreateBoundsObject.Bounds = rect
This code creates a constraint and sets the constraint's bounds. This will ensure records are cached.
However, the newly created BoundsConstraint object is then destroyed releasing the records from the
cache. To be effective, the BoundsConstraint object must be stored in a variable by the client and
released (or set to Nothing) when the records are no longer needed.

See Also
BoundsConstraint object on page 285
Rectangle Object on page 480

Layer.CreateFeaturesConstraint method (Layer Object)

Purpose
This method creates a new FeaturesConstraint object for use in controlling the data in the cache.

Syntax
[objFeaturesConstraint = ]OBJECT.CreateFeaturesConstraint

382 MapInfo MapX Developer Guide v5.0

Layer.ClippedBounds property (Layer object)

Remarks
The data that is held in the cache by this object is only held as long as the constraint (or some other
constraint) exists. Thus, specifying code such as:
Set lyr.CreateFeaturesObject.Features = ftrs
This code creates a constraint and set the constraint's features collection which ensures these records
are cached. However, the newly created FeaturesConstraint object is destroyed, releasing the records
from the cache. To be effective, the FeaturesConstraaint object must be stored in a variable by the client
and released (or set to Nothing) when the records are no longer needed.

See Also
FeaturesConstraint object on page 322
Feature Object and Features Collection on page 308

Layer.ClippedBounds property (Layer object)

Purpose
This read-only property returns the union of all layer clipped boundaries within a Rectangle object.
Use this property to set the Map.Bounds property when the map projection has infinite poles, such as
a Mercator projection, and the layer projection does not. Otherwise, the latitude would need to be
adjusted manually so that near-infinite numbers are not produced (which would cause the map to
appear as a thin vertical line).

Remarks
Since this is a read-only property, you may NOT set it to another rectangle object.

Example
Set Map.Bounds = Map.Layer.ClippedBounds

See Also
Map.Bounds property (Map object) on page 430
Layer.Bounds property (Layer object) on page 381
Layers.ClippedBounds property (Layer collection) on page 407

Layer.CoordSys property (Layer object)

Purpose
This property returns a read-only CoordSys object, indicating the coordinate system in which the layer
was saved.

MapInfo MapX Developer Guide v5.0 383

Chapter 18: The MapX Object Model

See Also
CoordSys Object on page 288
Map.DisplayCoordSys property (Map object) on page 438
Map.NumericCoordSys property (Map object) on page 451

Layer.ClearCustomLabels method (Layer object)

Purpose
Removes any labels placed on the current layer.

Syntax
OBJECT.ClearCustomLabels

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 (Datasets collection) on page 300
Map.Datasets property (Map object) on page 436

Layer.DeleteFeature method (Layer object)

Purpose
Deletes the feature and its database row from the layer.

384 MapInfo MapX Developer Guide v5.0

Layer.DrawLabelsAfter property (Layer object)

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.

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.

MapInfo MapX Developer Guide v5.0 385

Chapter 18: The MapX Object Model

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.
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 are removing are not
deleted from the table; by "removing" them, you simply make them disappear.

386 MapInfo MapX Developer Guide v5.0

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.

Syntax
OBJECT.EndAccess (endAccessType)

Part Description

OBJECT Represents a Layer object.

endAccessType One of the LayerEndAccessConstants, specifying the end access type.

MapInfo MapX Developer Guide v5.0 387

Chapter 18: The MapX Object Model

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
Layer.BeginAccess method (Layer object) on page 380

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.

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.

388 MapInfo MapX Developer Guide v5.0

Layer.FileSpec property (Layer object)

See Also
Layer.KeyField property (Layer object) on page 391

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.

Layer.GetDrilldownFeaturesByID method (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.

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 (Feature object) on page 311

Layer.Invalidate method (Layer object)

Purpose
This method causes the rectangle (in container screen coords) to be redrawn.

390 MapInfo MapX Developer Guide v5.0

Layer.KeyField property (Layer object)

Syntax
OBJECT.Invalidate ([InvalidRect])

Parts Description

OBJECT This represents a Layers object.

InvalidRect This represents the rectangle.

See Also
Layer.AddFeature method (Layer object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.SearchWithinFeature method (Layer object) on page 398
Layer.SearchWithinRectangle method (Layer object) on page 398
Layer.UpdateFeature method (Layer object) on page 401

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.Labels property (Layer object)

Purpose
This read-only property returns the Labels collection for a layer in the map. The Labels collection for a
layer consists of all labels in that layer that are currently visible in the map window or in the cache, as
well as any labels from that layer that have been edited either manually (using the stock Select tool) or
programatically (using methods and properties of the Layer object and Layers Collection).

Syntax
[ Labels= ]OBJECT.Labels

See Also
Label object and Labels collection on page 365

MapInfo MapX Developer Guide v5.0 391

Chapter 18: The MapX Object Model

Map.EditableLabels property (Map object) on page 440

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.

See Also
LabelProperties Object on page 372
Layer.AutoLabel property (Layer object) on page 380

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()

392 MapInfo MapX Developer Guide v5.0

Layer.OverrideStyle property (Layer object)

See Also
Layer.AddFeature method (Layer object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.SearchWithinFeature method (Layer object) on page 398
Layer.SearchWithinRectangle method (Layer object) on page 398
Layer.UpdateFeature method (Layer object) on page 401

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.

Layer.Pack method (Layer object)

Purpose
This method enables you to compress tables (so that they use less disk space) and eliminate records
that have been marked as deleted. Packing the data will rebuild the index and graphics files.

Note: Performing a Pack Table operation can corrupt your customized labels in MapInfo
Professional Workspaces. For additional information, please refer to the MapInfo
Professional Online Help System or Users Guide.

Syntax
OBJECT.Pack (PackType)

Part Description

OBJECT Represents a layer object

Layer.SearchWithinRectangle method (Layer object) on page 398

Layer.UpdateFeature method (Layer object) on page 401

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 object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinFeature method (Layer object) on page 398
Layer.SearchWithinRectangle method (Layer object) on page 398
Layer.UpdateFeature method (Layer object) on page 401

MapInfo MapX Developer Guide v5.0 397

Chapter 18: The MapX Object Model

Layer.SearchWithinFeature method (Layer object)

Purpose
This method returns the 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 (Selection collection) on page 495
Layer.AddFeature method (Layer object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.SearchWithinRectangle method (Layer object) on page 398
Layer.UpdateFeature method (Layer object) on page 401

Layer.SearchWithinRectangle method (Layer object)

Purpose
This method returns a Features collection within the bounds of a specified Rectangle.

Syntax
[features collection=]OBJECT.SearchWithinRectangle (Rectangle, SearchType)

Part Description

OBJECT Represents a Layer object.

Rectangle Rectangle object to use as basis of search.
SearchType SearchType is miSearchTypeCentroidWithin, miSearchTypePartiallyWithin,
miSearchTypeEntirelyWithin.

398 MapInfo MapX Developer Guide v5.0

Layer.Selectable property (Layer object)

See Also
Layer.AddFeature method (Layer object) on page 379
Layer.DeleteFeature method (Layer object) on page 384
Layer.Invalidate method (Layer object) on page 390
Layer.NoFeatures method (Layer object) on page 392
Layer.SearchAtPoint method (Layer object) on page 396
Layer.SearchWithinFeature method (Layer object) on page 398
Layer.SearchWithinDistance method (Layer object) on page 397
Layer.UpdateFeature method (Layer object) on page 401

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.

Layer.Selection property (Layer object)

Purpose
A collection of selected features for the layer.

See Also
Selection Collection on page 489

Layer.ShowNodes property (Layer object)

Purpose
This read/write property displays all nodes for all features in a layer 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.

MapInfo MapX Developer Guide v5.0 399

Chapter 18: The MapX Object Model

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 (Layer object) on page 393

Layer.SupportsPack method (Layer object)

Purpose
This method is used to determine if a layer can be packed or not.

Syntax
[bool=]OBJECT.SupportsPack (PackType)

Part Description

OBJECT Represents a layer object

PackType One or more of the LayerPackConstants, specifying the type of packing to
perform.
bool= Boolean value that indicates if a layer can be packed.

See Also
Layer.Pack method (Layer object) on page 393
LayerPackConstants on page 599

Layer.Type property (Layer object)

Purpose
This ia a read only property that returns an integer corresponding to one of the LayerTypeConstants:
• miLayerTypeNormal = 0

400 MapInfo MapX Developer Guide v5.0

Layer.UpdateFeature method (Layer object)

• miLayerTypeRaster = 2
• miLayerTypeSeamless = 4
• miLayerTypeUnknown = 5
• miLayerTypeUserDraw = 6

Layer.UpdateFeature method (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 (Target, [Source], [RowValues])

Part Description

OBJECT Represents a Layer object.

Target The Feature object to update that could be a FeatureKey, FeatureID, or Feature
Object. However, it is recommended that you use the FeatureKey as it is a
replacement for FeatureID parameter. (NOTE: FeatureID still works as it did
before.) 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 This optional parameter is the Feature object to take the properties from. The
default is Target.
RowValues This optional parameter is the 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.

Remarks
This method should not be used to update a computed column, but will not throw an exception if you
are trying to do so. The reason for this for this is that the RowValues collection may contain both
computed columns and non-computed columns.
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.
Columns named or aliased with name of MI_PRINX or PRINX are not updateable.

Note: Layer.UpdateFeature will not throw exceptions when one attempts to update non-
updateable columns. Oracle layer columns of the following datatypes are not updateable
and will not envoke exceptions if you try to update them:

MapInfo MapX Developer Guide v5.0 401

Chapter 18: The MapX Object Model

• Long
• Raw
• LOB,BFILE

See Also
RowValue Object and RowValues Collection on page 485
Feature Object and Features Collection on page 308

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.ZoomMax property (Layer object) on page 402
Layer.ZoomMin property (Layer object) on page 403

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.ZoomMax property (Layer object) on page 402
Layer.ZoomMin property (Layer object) on page 403

402 MapInfo MapX Developer Guide v5.0

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).

See Also
Layer.ZoomLayer property (Layer object) on page 402
Map.MapUnit property (Map object) on page 445

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.AddUserDrawLayer, and
Layers.AddServerLayer, an exception will be thrown if the name is not unique.

MapInfo MapX Developer Guide v5.0 403

Chapter 18: The MapX Object Model

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.

Layers.AddGeosetLayers method (Layers collection)

Purpose
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)

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.
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.AddUserDrawLayer, and
Layers.Add), an exception will be thrown if the name is not unique.

MapInfo MapX Developer Guide v5.0 405

Chapter 18: The MapX Object Model

This adds ODBC layers ONLY. Oracle Spatial layers must be added via Layers.Add with the
LayerInfo object.

See Also
Layers.Add method (Layers collection) on page 403
LayerInfo Object on page 412

Layers.AddUserDrawLayer 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. 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.

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.AddServerLayer, 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.

406 MapInfo MapX Developer Guide v5.0

Layers.Bounds property (Layers collection)

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.

Layers.Bounds property (Layers collection)

Purpose
This returns a Rectangle object representing the geographic extents (i.e. the minimum bounding
rectangle) 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 (Layer object) on page 381

Layers.ClippedBounds property (Layer collection)

Remarks
Since this is a read-only property, you may NOT set it to another rectangle object.

Example
Set Map.Bounds = Map.Layers.ClippedBounds

See Also
Map.Bounds property (Map object) on page 430
Layer.Bounds property (Layer object) on page 381

MapInfo MapX Developer Guide v5.0 407

Chapter 18: The MapX Object Model

Layer.ClippedBounds property (Layer object) on page 383

Layers.ClearSelection method (Layers collection)

Purpose
Deselects features in all layers of the Layers collection.

See Also
Selection.ClearSelection method (Selection collection) on page 490

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 method (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.

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 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.

408 MapInfo MapX Developer Guide v5.0

Layers.InsertionLayer (Layers object)

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.
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.

MapInfo MapX Developer Guide v5.0 409

Chapter 18: The MapX Object Model

Part Description

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

Layers.Move method (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.

Layers. Remove method (Layers collection)

Purpose
This method removes a Layer object from the collection. This has the effect of removing the layer from
the map.

410 MapInfo MapX Developer Guide v5.0

Layers.RemoveAll method (Layers collection)

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.
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
OBJECT.RemoveAll

MapInfo MapX Developer Guide v5.0 411

Chapter 18: The MapX Object Model

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.

Requir
LayerInfoType Parameter Type
ed

miLayerInfoTypeTab 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
*Shapes supported by (shapefile).
MapX are:
• Null
• Point
• PolyLine
• Polygon
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

ConnectString Yes String: ODBC connection string (see
AddServerLayer)
Query Yes String: SQL Query (see AddServerLayer)
ToolKit Yes String: ToolKit option, either ODBC or
ORAINET

412 MapInfo MapX Developer Guide v5.0

Layers.RemoveAll method (Layers collection)

Requir
LayerInfoType Parameter Type
ed

Cache No String - Possible values are:

• OFF - The cache is not used for this
layer.
• ON (default) - Cache is enabled and
automatically performs caching based
on the map view (center/zoom). User
may additionally control the cache
through the cache constraint objects.
• USER - Cache is enabled for this layer
without the automatic caching
performed internally in MapX. Only
the data requested by the user (via the
cache constraint objects) will be
cached.
• ALL - The entire layer is cached
during the entire existance of the layer.
Default is ON.
NOTE: Specifying Cache=ON or USER
with MBRSearch set to OFF is treated
internally the same as Cache=ALL and all
records will be cached.
MBRSearch No String: Either ON or OFF.
Default is ON.
CacheStorageType No String: Either MemTable or Native.
Default is MemTable.
CacheMaxDisk No Numeric: Indicates the maximum amount
of disk storage (in KB) to use by the cache.
A value of -1 signifies unlimited which is
the default. Note that even a
CacheStorageType of Memtable uses
some disk space to store the geographic
objects. This option only applies when the
cache parameter is set to "ON".
CacheMaxMemory No Numeric: Indicates the maximum amount
of memory storage (in KB) to use by the
cache. A value of -1 signifies unlimited
which is the default. This option is only
applicable when the CacheStorageType
parameter is Memtable. This option only
applies when the cache parameter is set to
"ON".

MapInfo MapX Developer Guide v5.0 413

Chapter 18: The MapX Object Model

Requir
LayerInfoType Parameter Type
ed

CacheMaxAge No Numeric: Indicates the maximum amount

of time (in seconds) that a unused
constraint will remain in the cache's
history. A value of -1 signifies unlimited
which is the default. This option only
applies when the cache parameter is set to
"ON".
CacheMaxRecords No Numeric: Indicates the maximum
number of records to retain in the cache.
A value of -1 signifies unlimited which is
the default. This option only applies when
the cache parameter is set to "ON".
CacheMaxViews No Numeric: Indicates the maximum
number of views to retain in the cache's
history. A value of -1 signifies unlimited.
The default is 0. This option only applies
when the cache parameter is set to "ON".
miLayerInfoTypeGeodictUs Name Yes String: Name of the layer to add (as
erName 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 Features collection: Specifies the rows to
no fill the table with
fields 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 (if not specified): LayerX where X
= the number of layers currently in the
map + 1
Fields No Fields collection: Specifies the column
the table will have
Features Yes, if Features collection: Specifies the rows to
no fill the table with
Fields Default: none

414 MapInfo MapX Developer Guide v5.0

Layers.RemoveAll method (Layers collection)

Requir
LayerInfoType Parameter Type
ed

OverwriteFile No String: If 1, then the file specified by the

FileSpec parameter will be overwritten if
it currently exists.
If 0, the file will not be overwritten.
NOTE: all non-zero values will force the
file to be overwritten.
TableStorageType No String: Default: Native. Valid options:
Native, Access
NOTE: For a table storage type of Access,
fields of type DECIMAL will be changed
to FLOAT.
AccessVersion No String: Default: V2000. Valid options:
V9597, V2000.
NOTE: This parameter only applies if the
table storage type is Access.
For any LayerInfoType other than miLayerInfoTypeUserDraw or miLayerInfoTypeRaster, the
following options are also supported:

LayerInfoType Parameter Required Type

Any other than AutoCreateDataset No Numeric: if 1, then a Dataset of

miLayerInfoTypeUserDraw type miDatasetLayer is added
or after the layer is added. If 0 (the
miLayerInfoTypeRaster default), no Dataset is added.
Any other than DatasetName No String: If the AutoCreateDataset
miLayerInfoTypeUserDraw parameter is 1, then this will be
or the name of the new Dataset. If
miLayerInfoTypeRaster not specified, a default name is
used.

The following paramerter can be used with any type of LayerInfoType:

LayerInfoType Parameter Required Type

Any Visible No Bool: Specifies if layer should 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.AddUserDrawLayer, and
Layers.Add), an exception will be thrown if the name is not unique.

MapInfo MapX Developer Guide v5.0 415

Chapter 18: The MapX Object Model

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.
miLayerInfoTypeNewTable is a layer that can be generated from external data (i.e. query results).
For miLayerInfoTypeTemp and miLayerInfoTypeNewTable:
• 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
• LayerInfo.Parameter property

Object Methods
• LayerInfo.AddParameter method

See Also
Layers.Add method (Layers collection) on page 403
Working with the Cache on page 178

LayerInfo.Type property (LayerInfo object)

Purpose
This is a read/write property whose value is one of the LayerTypeConstants

See Also
LayerInfo.AddParameter method (LayerInfo object) on page 417
Layers.Add method (Layers collection) on page 403

416 MapInfo MapX Developer Guide v5.0

LayerInfo.AddParameter method (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 (Layers collection) on page 403

LayerInfo.Parameter property (LayerInfo object)

Purpose
This read/write property takes an argument, which is a string representing the parameter’s name.
When retrieved, the Parameter property returns a variant whose type is whatever the type was when
the parameter was inserted. You can also set, add, insert, or modify parameters with this property.

Example
To get the value of an existing parameter (e.g. CoordSys) do the following:
Set oCoordSys = oLayerInfo.Parameter("CoordSys")
To modify an existing or add a new parameter (e.g. Style), use method AddParameter or use the
Parameter property as follows:
Set oLayerInfo.Parameter("Style") = Map1.Layers("MyLayer").Style

Note: Set is only used when setting objects. Other properties such as strings or numbers do not
require the Set statement.

MapInfo MapX Developer Guide v5.0 417

Chapter 18: The MapX Object Model

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.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 on page 507

418 MapInfo MapX Developer Guide v5.0

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 (Map object) on page 452

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 on page 507

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.

MapInfo MapX Developer Guide v5.0 419

Chapter 18: The MapX Object Model

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 method (Map object) on page 440

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.

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 and Top 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.

420 MapInfo MapX Developer Guide v5.0

Legend.LegendTexts property (Legend object)

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.

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 on page 425

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 (Map object) on page 452

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 (Map object) on page 452

MapInfo MapX Developer Guide v5.0 421

Chapter 18: The MapX Object Model

Legend.PrintLegend method (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.
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.

422 MapInfo MapX Developer Guide v5.0

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 on page 507

Legend.Title property (Legend object)

Purpose
Contains the legend title text string. This is displayed when the legend is of normal size. 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 on page 507

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.

Legend.Visible property (Legend object)

Purpose
Controls whether the legend is visible or not. This is a Boolean value, and the default is True.

MapInfo MapX Developer Guide v5.0 423

Chapter 18: The MapX Object Model

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.

424 MapInfo MapX Developer Guide v5.0

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 and Themes Collection on page 526

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.

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 and Themes Collection on page 526
Theme.AutoRecompute property (Theme object) on page 526

MapInfo MapX Developer Guide v5.0 425

Chapter 18: The MapX Object Model

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 property (Theme object) on page 526

LegendTexts.Count property (LegendTexts collection)

Purpose
The number of LegendText objects in the collection. This is a read-only property.

LegendTexts.Item property (LegendTexts collection)

Purpose
Retrieve a particular LegendTexts object from a collection. You must specify the text string.

426 MapInfo MapX Developer Guide v5.0

LegendTexts.Item 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.InfotipPopupDelay property
• Map.InfotipSupport property
• Map.Layers property
• Map.MapPaperHeight property
• Map.MapPaperWidth property
• Map.MapScreenHeight property
• Map.MapScreenWidth property
• Map.MapUnit property
• Map.MatchNumericFields property
• Map.MatchThreshold property
• Map.MaxSearchTime property
• Map.MouseIcon property
• Map.MousePointer property
• Map.MouseWheelSupport property
• Map.NumericCoordSys property
• Map.PanAnimationLayer property
• Map.PaperUnit property
• Map.PreferCompactLegends property
• Map.RedrawInterval property
• Map.ReuseEquivalentOnRestore property

MapInfo MapX Developer Guide v5.0 427

Chapter 18: The MapX Object Model

• Map.Rotation property
• Map.SearchPath property
• Map.SelectionStyle property
• 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.ConvertCoordP 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.Refresh method
• Map.SaveMapAsGeoset method
• Map.SetSize method
• Map.ZoomTo method

See Also
Dataset object and Datasets collection on page 293
Layer Object and Layers Collection on page 377
Annotation Object and Annotations Collection on page 274

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

428 MapInfo MapX Developer Guide v5.0

Map.Annotations property (Map object)

Purpose
A collection of annotations for the map.

See Also
Annotation Object and Annotations Collection on page 274

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.

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.

MapInfo MapX Developer Guide v5.0 429

Chapter 18: The MapX Object Model

See Also
OLE_COLOR Values on page 655

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.

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).

Remarks
The CenterX property is set when a new Geoset is loaded.

See Also
Map.CenterY property (Map object) on page 430
Map.ZoomTo method (Map object) on page 460

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.CenterY property (Map object) on page 430
Map.ZoomTo method (Map object) on page 460

430 MapInfo MapX Developer Guide v5.0

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.
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 (Map object) on page 432
Layers.AddUserDrawLayer method (Layers collection) on page 406
Map.NumericCoordSys property (Map object) on page 451

MapInfo MapX Developer Guide v5.0 431

Chapter 18: The MapX Object Model

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.

See Also
Map.ClipLine method (Map object) on page 431
Map.NumericCoordSys property (Map object) on page 451

432 MapInfo MapX Developer Guide v5.0

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.

Map.ConvertCoordP method (Map object)

Purpose
The method takes a screen/map X and Y and a direction (miScreenToMap or miMapToScreen) and
returns a Point whose X and Y properties correspond to the converted map/screen coordinates.

Syntax
Object.ConvertCoordP(X , Y , Dir)

Part Description

X Varient: This is the screen/map coordinate X.

Y Varient: This is the screen/map coordinate Y.
Dir Direction to convert coordinates, either from Map to Screen, or Screen to
Map. This takes a ConversionConstants value.

MapInfo MapX Developer Guide v5.0 433

Chapter 18: The MapX Object Model

Map.ConvertCoordV 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. 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.

Syntax
OBJECT.CreateCustomTool (ToolNumber, Type, Cursor, [ShiftCursor] , [CtrlCursor], [InfoTips])

Part Description

OBJECT Represents a Map object.

434 MapInfo MapX Developer Guide v5.0

Map.CurrentTool property (Map object)

Part Description

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 (Map object) on page 435

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 (Map object) on page 434

MapInfo MapX Developer Guide v5.0 435

Chapter 18: The MapX Object Model

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.

Note: THIS METHOD IS NOT AVAILABLE IN MAPX MOBILE.

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 (Datasets collection) on page 300
Map.DatasetGeoField property (Map object) on page 436

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.

Note: THIS METHOD IS NOT AVAILABLE IN MAPX MOBILE.

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.Datasets property (Map object) on page 436
Datasets.Add method (Datasets collection) on page 300

Map.Datasets property (Map object)

Purpose
The Datasets collection for the map.

436 MapInfo MapX Developer Guide v5.0

Map.DatasetTheme property (Map object)

See Also
Dataset object and Datasets collection on page 293

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.

Note: THIS METHOD IS NOT AVAILABLE IN MAPX MOBILE.

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.

See Also
Themes.Add method (Themes collection) on page 530
Map.Datasets property (Map object) on page 436

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 a long integer which can take on any value between 3 and 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

MapInfo MapX Developer Guide v5.0 437

Chapter 18: The MapX Object Model

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.

See Also
FeatureFactory.BufferFeatures method (FeatureFactory object) on page 325
FeatureFactory.CreateArc method (FeatureFactory object) on page 327
FeatureFactory.CreateCircularRegion method (FeatureFactory object) on page 330
FeatureFactory.CreateEllipticalRegion method (FeatureFactory object) on page 332
Layer.SearchWithinDistance method (Layer object) on page 397

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 on page 507

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.

438 MapInfo MapX Developer Guide v5.0

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
”Chapter 13: Using Coordinate Systems” on page 191
CoordSys Object on page 288
Map.NumericCoordSys property (Map object) on page 451

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.

See Also
CoordSys Object on page 288
Map.NumericCoordSys property (Map object) on page 451
Map.MapUnit property (Map object) on page 445

MapInfo MapX Developer Guide v5.0 439

Chapter 18: The MapX Object Model

Map.DynamicSelectionSupport property (Map object)

Purpose
This boolean property controls whether or not Dynamic Selection is enabled. When True the user will
see selection highlighting added to the map while the Radius Select and Rectangle Select tools are
being used. When False selection highlighting is not drawn until the user releases the mouse button
when using the Radius Select and Rectangle Select tools.

Remarks
This property is false by default. It will affect only rectangle and radius selection tools. The behavior of
the tools themselves are the same.

Map.EditableLabels property (Map object)

Purpose
This is a boolean property on the Map object. Setting it to true allows the labels to be selected and
moved via the user interface with the MapX Select tool (miSelectTool). Setting it to false disables
editing via the user interface.

Remarks
The Labels Collection can always be used to edit labels programatically regardless of the value of
Map.EditableLabels. Map.EditableLabels controls whether users can edit labels (select and move)
using the Select Tool.
The LabelChanged event is fired when this property is True and the user uses the Select tool to select
or move labels

See Also
Label object and Labels collection on page 365
LabelChanged Event on page 557

Map.ExportMap method (Map object)

Purpose
This method is used for exporting map images. MapX for the desktop is capable of exporting to the
following formats (see note if using MapX Mobile):

JPG TIF GIF

PNG WMF PSD

440 MapInfo MapX Developer Guide v5.0

Map.ExportSelection property (Map object)

BMP

Note: If using MapX Mobile, you may only export in BMP. Attempting to export in alternative
formats will generate an error.

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. NOTE: if using MapX Mobile, you
may only paste a map in BMP format to the given location.
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.
NOTE: If using MapX Mobile,this parameter is ignored so the size of the
exported map is the same size as the hand held device’s screen.
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.
NOTE: if using MapX Mobile,this parameter is ignored so the size of the
exported map is the same size as the hand held device’s screen.

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 object) on page 441
Map.PaperUnit property (Map object) on page 452

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.

MapInfo MapX Developer Guide v5.0 441

Chapter 18: The MapX Object Model

See Also
Map.ExportSelection property (Map object) on page 441
Map.PrintMap method (Map object) on page 453
Map.SelectionStyle property (Map object) on page 457

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.

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 on page 325

Map.GeoDictionary property (Map object)

Purpose
This read-only property specifies the location of a registry entry which is used to determine the
GeoDictionary file and the default data directory.

Remarks
When a map control is created, MapX will query the registry key:
HKEY_LOCAL_MACHINE\Software\MapInfo\MapX\5.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.)

442 MapInfo MapX Developer Guide v5.0

Map.GeoSet property (Map object)

• 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:
• 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 matched against it too. Layers
added to the map are added to the in-memory geodictionary so they can be auto matched
against.
• 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.
• Empty. 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\5.0\GeoDictionary.

See Also
Map.GeoSet property (Map object) on page 443

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' 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 Geosets Collection on page 359

MapInfo MapX Developer Guide v5.0 443

Chapter 18: The MapX Object Model

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 the 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 object) on page 444
Map.CreateCustomTool method (Map object) on page 434

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 object) on page 444

444 MapInfo MapX Developer Guide v5.0

Map.IsPointVisible method (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 on page 377

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.

MapInfo MapX Developer Guide v5.0 445

Chapter 18: The MapX Object Model

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)

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.

446 MapInfo MapX Developer Guide v5.0

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 30 seconds.

Map.MilitraryGridReferenceFromPoint method (Map object)

Purpose
This method takes a XY point from a map's numeric coordinate system and converts it to a Military
Grid Reference System (MGRS) point.

Syntax
[ strPoint= ]OBJECT.MilitaryGridReferenceFromPoint (dblX, dblY)

Part Description

strPoint= This return value is the converted point. It is a string.

OBJECT This represents a map object.
dblX This double value represents the X coordinate point to be converted.
dblY This double value represents the Y coordinate point to be converted.

Example
Private Sub Map1_MouseMove(Button As Integer, Shift As Integer, X As
Single, Y As Single)
Dim MapX As Double
Dim MapY As Double

Map1.ConvertCoord X, Y, MapX, MapY, miScreenToMap

Text2.Text = MapX
Text3.Text = MapY

Dim s As String
s = Map1.MilitaryGridReferenceFromPoint(MapX, MapY)

Dim b As Boolean

Dim dx As Double
Dim dy As Double
b = Map1.MilitaryGridReferenceToPoint(s, dx, dy)

Dim vx As Variant

MapInfo MapX Developer Guide v5.0 447

Chapter 18: The MapX Object Model

Dim vy As Variant
b = Map1.MilitaryGridReferenceToPointV(s, vx, vy)

Map.MilitaryGridReferenceToPointV method (Map object)

Purpose
This method converts a Military Grid Reference System MGRS point to a XY point in Map's numeric
coordinate system. This method returns boolean and returns x,y values in variants

Syntax
[ bool= ] OBJECT.MilitaryGridReferenceToPointV (strMGRS, vX, vY)

Part Description

bool= This return value is the converted point. It is a string.

OBJECT This represents a map object.
strMGRS This string value represents theMGRS point to be converted.
vX Varient: This represents the converted X coordinate point.
vY Varient: This represents the converted Y coordinate point.

Example
Private Sub Map1_MouseMove(Button As Integer, Shift As Integer, X As
Single, Y As Single)
Dim MapX As Double
Dim MapY As Double

Map1.ConvertCoord X, Y, MapX, MapY, miScreenToMap

Text2.Text = MapX
Text3.Text = MapY

Dim s As String
s = Map1.MilitaryGridReferenceFromPoint(MapX, MapY)

Dim b As Boolean

Dim dx As Double
Dim dy As Double
b = Map1.MilitaryGridReferenceToPoint(s, dx, dy)

Dim vx As Variant
Dim vy As Variant
b = Map1.MilitaryGridReferenceToPointV(s, vx, vy)

448 MapInfo MapX Developer Guide v5.0

Map.MilitaryGridReferenceToPoint method (Map object)

Purpose
This method converts a Military Grid Reference System MGRS point to a XY point in Map's numeric
coordinate system.

Syntax
[ bool= ] OBJECT.MilitaryGridReferenceToPointV (strMGRS, dblX, dblY)

Part Description

bool= This return value is the converted point. It is a string.

OBJECT This represents a map object.
strMGRS This string value represents theMGRS point to be converted.
dblX This double value represents the converted X coordinate point.
dblY This double value represents the converted Y coordinate point.

Example
Private Sub Map1_MouseMove(Button As Integer, Shift As Integer, X As
Single, Y As Single)
Dim MapX As Double
Dim MapY As Double

Map1.ConvertCoord X, Y, MapX, MapY, miScreenToMap

Text2.Text = MapX
Text3.Text = MapY

Dim s As String
s = Map1.MilitaryGridReferenceFromPoint(MapX, MapY)

Dim b As Boolean

Dim dx As Double
Dim dy As Double
b = Map1.MilitaryGridReferenceToPoint(s, dx, dy)

Dim vx As Variant
Dim vy As Variant
b = Map1.MilitaryGridReferenceToPointV(s, vx, vy)

MapInfo MapX Developer Guide v5.0 449

Chapter 18: The MapX Object Model

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.

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

450 MapInfo MapX Developer Guide v5.0

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.

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.NumericCoordSys property (Map object)

Purpose
This returns a read-write CoordSys object (coordinate system) that controls how MapX interprets
numeric map coordinates.

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
”Chapter 13: Using Coordinate Systems” on page 191

MapInfo MapX Developer Guide v5.0 451

Chapter 18: The MapX Object Model

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.

Map.PanAnimationLayer property (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.

452 MapInfo MapX Developer Guide v5.0

Map.PrintMap method (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.
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.

Note: THIS METHOD IS NOT AVAILABLE IN MAPX MOBILE.

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.,

MapInfo MapX Developer Guide v5.0 453

Chapter 18: The MapX Object Model

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.)

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 object) on page 429

Map.ReuseEquivalentOnRestore property (Map object)

Purpose
This is a Boolean property that defaults to True.
When the value of this property is False and the Datasets collection or Map object is being restored
from the State object, MapX discards all existing datasets and restores new ones when restored from a
State object. To completely restore each dataset, Datasets.Restore must also be called to supply the
external source (e.g. ADO recordset.) of each dataset being restored.
When the value of this property is True and the Datasets collection or Map object is being restored
from the State object, MapX attempts to reuse existing datasets that are equivalent to the datasets being
restored. You must call Datasets.Item to find out if an equivalent dataset was found. If no equivalent
dataset is found, you must call Datasets.Restore to completely restore the dataset.

Example
The following example saves and restores a Map with a dataset called "Dataset1":

454 MapInfo MapX Developer Guide v5.0

Map.ReuseEquivalentOnRestore property (Map object)

' Save the map:

objState.Save objMap
' Perform other operations
...
' If equivalent allow reuse of existing layers and/or datasets when
restoring state
objMap.ReuseEquivalentOnRestore = True
' Restore the map object:
objState.Restore objMap
' If the dataset is not yet present:
if not objMap.Datasets.Contains("Dataset1") then
' Setup the dataset source (e.g. ADO recordset):
...
' Complete restoring the dataset:
objMap.Datasets.Restore "Dataset1", source
end if

Remarks
This property is very useful in MapXtreme applications to speed up the process of restoring the Map
object state on each session request. Restoring a dataset can be an expensive operation because MapX
must bind and read all data from an external source (such as ADO.) Allowing MapX to reuse a dataset
that matches the one being restored bypasses having to bind and read from an external source.
Setting the value of this property does not guarantee that MapX will find a matching dataset. For
example, if you have an ASP application that shares a MapX object between sessions, and the
application allows each session to add or remove a dataset, when each session restores its Map state,
the map might or might not have the dataset. If MapX does not find a matching dataset, you must call
Datasets.Restore to completely restore the dataset. You can find out if MapX found a matching dataset
by calling Datasets.Contains.
Keep in mind that if your external source changes frequently (e.g. while a session is active) you might
not want to reuse existing datasets. If the data does not change frequently, you can start with a new
dataset on the first session request and then allow MapX to reuse existing datasets, if present, during
subsequent session requests.

See Also
State Object on page 499
Datasets.Contains method (Datasets object) on page 302

MapInfo MapX Developer Guide v5.0 455

Chapter 18: The MapX Object Model

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 method (Map object)

Purpose
This creates a geoset file representing the current status of the map (layer information, labeling
settings, etc.).

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, user draw layers, or remote layers added via
miLayerInfoTypeServer, those layers are left out of the new geoset file and an exception is thrown
(after the geoset has been saved). Remote layers added via .tab file are saved in the resulting geoset.
This method also throws an exception if there are no layers in the map. Also, shape files(*.shp) can not
be saved into a geoset.

Map.SearchPath property (Map object)

Purpose
This property allows the user to set the search path dynamically. Essentially, a search path is an
"electronically plotted course" of the drive and directory(ies) to where information exists. Before a
programmer sets this property, the search path is initially read from the registry. The SearchPath
property is available at run-time only.

456 MapInfo MapX Developer Guide v5.0

Map.SelectionStyle property (Map object)

Purpose
This returns or sets a Style object, representing the style in which selected features are drawn.

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 method (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.

MapInfo MapX Developer Guide v5.0 457

Chapter 18: The MapX Object Model

Map.SnapTolerance property (Map object)

Purpose
This property takes an integer between 1 and 50. Use SnapTolerance to specify a tolerance within
which Snap to nodes operates (i.e. the distance in pixels from the mouse cursor that a node must be for
the tool to "snap to" that node) . The default value is 5 pixels.

Remarks
When you are working in a Map window containing many closely positioned objects, you want a
fairly tight Snap tolerance (1, 2, or 3 pixels). This allows you to draw very close to a node without
snapping to it. When objects are more loosely positioned, you can have a looser tolerance. This allows
you to be farther away from a node and still snap to it.

See Also
Node Selecting and Editing on page 239
Map.SnapToNodeSupport property (Map object) on page 458

Map.SnapToNodeSupport property (Map object)

Purpose
When this boolean property is True, SnapToNode functionality is enabled. With snap to node enabled
a crosshair cursor appears when the mouse cursor is near a node in a selectable layer. The tool you are
using "snaps to" that node, allowing you to more easily use the current tool on that node (for example,
select the node using the select tool). You can determine how close the cursor needs to be to a node
before the crosshair appears by setting the Map.SnapTolerance property.

Remarks
You may enact this feature by pressing 's' or 'S' key. (This character is defined in the MapX resource, so
that it can be changed on foreign platforms).
This functionality works with any of the MapX stock tools as well as any custom tools created by your
application. This functionality is especially useful when editing the nodes of a feature by selecting and
dragging them with the Select tool.

See Also
Map.SnapTolerance property (Map object) on page 458
Node Selecting and Editing on page 239

458 MapInfo MapX Developer Guide v5.0

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 object) on page 459

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.

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.

MapInfo MapX Developer Guide v5.0 459

Chapter 18: The MapX Object Model

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.

460 MapInfo MapX Developer Guide v5.0

MultivarCategories.Count property (MultivarCategories collection)

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 (ThemeProperties object) on page 537
LegendText Object and LegendTexts Collection on page 425

MultivarCategories.Count property (MultivarCategories collec-

tion)
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.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.

MapInfo MapX Developer Guide v5.0 461

Chapter 18: The MapX Object Model

See Also
Style Object on page 507

462 MapInfo MapX Developer Guide v5.0

NotesQueryInfo.BeginDate property (NotesQueryInfo object)

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.

Note: THIS OBJECT AND IT’S PROPERTIES ARE NOT YET AVAILABLE IN MAPX MOBILE
DUE TO THE FACT THAT MAPX MOBILE DOES NOT SUPPORT REMOTE
CONNECTIVITY.

Object Properties
• NotesQueryInfo.BeginDate property
• NotesQueryInfo.Database property
• NotesQueryInfo.DefaultNumericValue property
• 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.DefaultNumericValue 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 numeric (double) if the requested numeric field is not found (optional). This value
defaults to 0.

MapInfo MapX Developer Guide v5.0 463

Chapter 18: The MapX Object Model

See Also
Datasets.Add method (Datasets collection) on page 300

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.

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.

464 MapInfo MapX Developer Guide v5.0

NotesQueryInfo.Server property (NotesQueryInfo object)

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 v5.0 465

Chapter 18: The MapX Object Model

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 (Datasets collection) on page 300

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.

466 MapInfo MapX Developer Guide v5.0

OCIQueryInfo.ConnectString property (OCIQueryInfo object)

OCIQueryInfo object
An OCIQueryInfo object is passed into the Datasets.Add method as the source parameter if the
Dataset type is miDatasetOCI. This object contains information about how to connect to an OCI data
source and which records to treat as the record set.
When using an OCIQueryInfo object, one must ensure that the proper OCI dlls are installed. In Visual
Basic, choose Project > References. Click the Browse button to add references to appropriate dlls. The
dlls are installed in the MapX Program directory.

Note: THIS OBJECT AND IT’S PROPERTIES ARE NOT YET AVAILABLE IN MAPX MOBILE
DUE TO THE FACT THAT MAPX MOBILE DOES NOT SUPPORT REMOTE
CONNECTIVITY.

Object Properties
• OCIQueryInfo.ConnectString property
• OCIQueryInfo.Query property

See Also
Datasets.Add method (Datasets collection) on page 300

OCIQueryInfo.ConnectString property (OCIQueryInfo object)

Purpose
This property sets a string value that specifies the database you will connect to, the user you will
connect as, and a valid pass word if necessary.

Example
"SRVR=rock;UID=mapx;PWD=mapx"

OCIQueryInfo.Query property (OCIQueryInfo object)

Purpose
This property sets a string value that specifies a valid SQL Select statement.

MapInfo MapX Developer Guide v5.0 467

Chapter 18: The MapX Object Model

ODBCQueryInfo 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.

Note: THIS OBJECT AND ITS PROPERTIES ARE NOT YET AVAILABLE IN MAPX MOBILE
DUE TO THE FACT THAT MAPX MOBILE DOES NOT SUPPORT REMOTE
CONNECTIVITY.

Object Properties
• ODBCQueryInfo.ConnectString property
• ODBCQueryInfo.DataSource property
• ODBCQueryInfo.SqlQuery property

See Also
Datasets.Add method (Datasets collection) on page 300

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).

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.

468 MapInfo MapX Developer Guide v5.0

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".

MapInfo MapX Developer Guide v5.0 469

Chapter 18: The MapX Object Model

Parts Collection
A Parts collection is a grouping of Points collection objects. That is, each object of a Parts Collection is
made up of a Points Collection. A Parts collection 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.Item property

Collection Methods
• Parts.Add method
• Parts.Remove method
• Parts.RemoveAll method

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.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.

470 MapInfo MapX Developer Guide v5.0

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

MapInfo MapX Developer Guide v5.0 471

Chapter 18: The MapX Object Model

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.GetXY method
• Points.GetXYV method
• Points.X method
• Points.Y 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.NumericCoordSys property (Map object) on page 451

472 MapInfo MapX Developer Guide v5.0

Point.Set method (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.

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 property (Map object) on page 451

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 property (Map object) on page 451

Points.Add method (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.

MapInfo MapX Developer Guide v5.0 473

Chapter 18: The MapX Object Model

Part Description

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.

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.GetXY method (Points collection)

Purpose
This method returns the XY coordinates of a specified point in a Points collection.

474 MapInfo MapX Developer Guide v5.0

Points.GetXYV method (Points Collection)

Note: This method is NOT available in MapX Mobile. To get the XY coordinates in MapX
Mobile, you must use the GetXYV method.

Syntax
OBJECT.GetXY(lIndex, dX, dY)

Part Description

OBJECT This is a Points collection.

lIndex long: This by reference value is the index of the point object.
dX double: This by reference value is the X coordinate.
dY double: This by reference value is the Y coordinate.

Points.GetXYV method (Points Collection)

Purpose
This method returns the XY coordinates of a specified point in a Points collection as variants.

Syntax
OBJECT.GetY(lIndex, vX, vY)

Part Description

OBJECT This is a Points object.

lIndex long: This by reference value is the index of the point object.
vX variant: This by reference value is the X coordinate.
vY variant: This by reference value is the Y coordinate.

Points.X method (Points collection)

Purpose
This method returns the X coordinates of a specified point in a Points collection.

Syntax
OBJECT.X(lIndex)

Points.Remove method (Points collection)

Purpose
This method removes a Point object from the collection.

Syntax
OBJECT.Remove (index)

Points.RemoveAll method (Points collection)

Purpose
This method removes all Point objects from the collection.

Syntax
OBJECT.RemoveAll

476 MapInfo MapX Developer Guide v5.0

RangeCategories.AllOthersCategory property (RangeCategories collection)

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.

RangeCategories.Item property (RangeCategories collection)

Purpose
This returns one RangeCategory object from the collection; this object describes a range in the ranged
theme.

MapInfo MapX Developer Guide v5.0 477

Chapter 18: The MapX Object Model

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 property (ThemeProperties object) on page 535

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.

See Also
ThemeProperties.DistMethod property (ThemeProperties object) on page 535
Themes.Add method (Themes collection) on page 530
Theme.AutoRecompute property (Theme object) on page 526

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

478 MapInfo MapX Developer Guide v5.0

RangeCategory.Style property (RangeCategory object)

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 v5.0 479

Chapter 18: The MapX Object Model

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.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.

480 MapInfo MapX Developer Guide v5.0

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.

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.

MapInfo MapX Developer Guide v5.0 481

Chapter 18: The MapX Object Model

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.

482 MapInfo MapX Developer Guide v5.0

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.SourceMatch property
• ResolveObject.TableMatch property
• ResolveObject.TableName property

Collection Properties
• ResolveObjects.Count property
• ResolveObjects.Item property

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.

ResolveObjects.Count property (ResolveObjects collection)

Purpose
Number of items in collection.

MapInfo MapX Developer Guide v5.0 483

Chapter 18: The MapX Object Model

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.

484 MapInfo MapX Developer Guide v5.0

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 creatable 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 object) on page 401
Layer.AddFeature method (Layer object) on page 379
Feature.Update method (Feature object) on page 317
Dataset.RowValues property (Dataset object) on page 296

RowValue.ReadOnly property (RowValue object)

Purpose
This property determines whether or not the properties can be set on the object.

RowValue.Dataset property (RowValue object)

Purpose
This property is used to specify which Dataset the value is for.

MapInfo MapX Developer Guide v5.0 485

Chapter 18: The MapX Object Model

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.

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.

486 MapInfo MapX Developer Guide v5.0

RowValues.Add method (RowValues 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.

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 returns a copy of the specified RowValues collection from a Dataset. Fields can be added
or removed from the cloned RowValues collection to do a sparse update i.e. to update just certain

MapInfo MapX Developer Guide v5.0 487

Chapter 18: The MapX Object Model

fields. Obtaining the RowValues collection directly from the dataset (without cloning) will not allow
you to add or remove fields.

Note: This is the only type of updateable dataset is miDatasetLayer.

Syntax
[ RowValues= ]OBJECT.Clone

Part Description

OBJECT Represents a RowValues collection.

See Also
Feature.Update method (Feature object) on page 317

488 MapInfo MapX Developer Guide v5.0

Selection.Count property (Selection collection)

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 collection 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.

Object Properties
• Selection.Count property
• Selection.Item property

Object 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 and Layers Collection on page 377
Feature Object and Features Collection on page 308

Selection.Count property (Selection collection)

Purpose
Number of items in the collection.

MapInfo MapX Developer Guide v5.0 489

Chapter 18: The MapX Object Model

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 Features Collection on page 308
FindFeature object on page 353

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.

490 MapInfo MapX Developer Guide v5.0

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 method (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.

Syntax
OBJECT.Remove (Source)

Part Description

OBJECT Represents a Selection collection.

MapInfo MapX Developer Guide v5.0 491

Chapter 18: The MapX Object Model

Part Description

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 method (Selection collection)

Purpose
Selects all features within a layer.

Syntax
Map.Selection.SelectAll SelectionTypeConstant

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 property. You can use FeatureKey anywhere
FeatureID can be used.

492 MapInfo MapX Developer Guide v5.0

Selection.SelectByPoint method (Selection collection)

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
This method selects the feature(s) at a specified location within the layer.

Syntax
OBJECT.SelectByPoint (X, Y, SelectFlag, [SearchResultFlag])

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).
SelectFlag This controls whether the selected feature is added to, removed from, or
replaces the current selection. This takes a SelectionTypeConstants value.
SearchResultFlag This optional parameter controls what to return. It takes one or a
combination of SearchResultTypeConstants values.

Remarks
If you are selecting regions, the Selection.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.
By combining (using OR operator) one or more of the SearchResultTypeConstants you may define
whether you want all the features, the topmost feature, all the regions, all the points, the topmost
point, etc. The default is to return all the features.

MapInfo MapX Developer Guide v5.0 493

Chapter 18: The MapX Object Model

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.

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.

MapInfo MapX Developer Guide v5.0 495

Chapter 18: The MapX Object Model

See Also
Feature.FeatureKey property (Feature object) on page 311
Layer.SearchWithinFeature method (Layer object) on page 398
Layer Object and Layers Collection on page 377

496 MapInfo MapX Developer Guide v5.0

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.

Syntax
[ SourceRow= ]OBJECT.Item (index)

Part Description

OBJECT Represents a SourceRows object.

MapInfo MapX Developer Guide v5.0 497

Chapter 18: The MapX Object Model

Part Description

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.

498 MapInfo MapX Developer Guide v5.0

SourceRows.Item property (SourceRows collection)

State Object
The State object allows you to save the current state of an item, such as an object or variable, so that
you can restore the item back to that state at a later time. You can save and restore MapX objects or
variables (e.g. a String or Boolean.)
The State object is very useful in MapXtreme applications to restore the state of the Map object on each
session request. (See “State.Stream property (State object)” on page 504 for more information). It is
also useful in MapX applications (e.g. when using Visual Basic) if you want to save and restore
Datasets and Themes into a permanent file so that you can then restore them at a later time. See
“State.WriteToFile method (State object)” on page 505 for more information.

Note: This object is not available in MapX Mobile.

Creating a State object in Visual Basic

To use a State object in Visual Basic, you need to add the "MapInfo MapX V5 State Type Library"
reference to your project . You can then use the object type MapXStateLib.State to create a new state
object.
The following example creates a new State object:
Dim objState as MapXStateLib.State
Set objState = new MapXStateLib.State

Creating a State object in ASP

To use a State object in ASP, you need to use Server.CreateObject and the state object's class ID
"MapX.State.5".
The following example creates a new State object:
Dim objState
set objState = Server.CreateObject("MapX.State.5")

Saving and restoring items

You can save and restore single element variables of any Visual Basic native type (e.g. String, Variant,
Boolean, etc.) Array variables are not supported.
You can save and restore objects as long as they support persistence. The following MapX objects
support persistence: Map, Annotation, Annotations, Layer, Layers, Labels, LabelProperties, Feature,
Dataset, Datasets, Theme, Themes, CoordSys, Style, Field and Fields.
For more information on saving and restoring items, see State.Save and State.Restore.

Saving and restoring the Map object

When you save a Map object, all the Map properties and objects within its hierarchy are saved as well
(e.g. Layers, Title, Datasets, Themes, etc.) The only exception is the Annotations collection. If you want
to save your annotations, you need to explicitly save and restore them after saving and restoring the
Map object.

MapInfo MapX Developer Guide v5.0 499

Chapter 18: The MapX Object Model

For example, to save the map and your annotations, do the following:
objState.Save objMap
objState.Save objMap.Annotations
To then restore the map and its annotations, do the following:
objState.Restore objMap
objState.Restore objMap.Annotations
Saving and restoring the Map object also saves the Datasets collection object. However, in order to
completely restore each dataset, the Datasets collection might need each dataset external source (e.g.
ADO recordset.) See "Saving and restoring datasets" for more information.

Saving and restoring datasets

When you save and restore the Datasets collection or the Map object, you save and restore each dataset
in the map.
In order to create a dataset you need an external source. This source can be an ADO recordset, a RDO
resultset or even a layer, depending on the type of dataset you are creating. MapX uses this source to
create the dataset. To restore datasets from the state object, you might need to supply MapX with this
source in order to completely restore the dataset. You do this by calling Datasets.Restore.
The property Map.ReuseEquivalentOnRestore allows MapX to reuse an existing dataset if it is
equivalent to the one being restored. For more information on this property, see
Map.ReuseEquivalentOnRestore property (Map object) on page 454.
The following example saves and restores a Map with a dataset called "Dataset1":
' Save the map:
objState.Save objMap
' Perform other operations
...
' If equivalent allow reuse of existing layers and/or datasets when
restoring state.
objMap.ReuseEquivalentOnRestore = True
' Restore the map object:
objState.Restore objMap
' If the dataset is not yet present:
if not objMap.Datasets.Contains("Dataset1") then
' Setup the dataset source (e.g. ADO recordset):
...
' Complete restoring the dataset:
objMap.Datasets.Restore "Dataset1", source
end if

Saving the Layers collection or the Layer object explicitly

When you save the Layers collection object or a Layer object explicitly, the Datasets associated with the
layer are not saved. If you are explicitly saving the Layer or Layers objects, you must save the Datasets
or Dataset object explicitly.

500 MapInfo MapX Developer Guide v5.0

State.ReadFromFile method (State object)

Notes on saving the Dataset object explicitly

Saving and restoring an individual dataset only saves property information about the dataset. In order
to save and restore an individual dataset, you must have an existing dataset. This means that the only
information that needs to be restored once you have a dataset is the labeling state of the dataset
(whether the dataset is being used to label a layer) and its themes.

See Also
Datasets.Contains method (Datasets object) on page 302
Map.ReuseEquivalentOnRestore property (Map object) on page 454
Dataset object and Datasets collection on page 293

Object Methods
• State.ReadFromFile method
• State.Reset method
• State.Restore method
• State.Save method
• State.WriteToFile method

Object Properties
• State.Stream property

State.ReadFromFile method (State object)

Purpose
This method initializes the State object from a binary file.

Syntax
OBJECT.ReadFromFile (strFile)

Part Description

OBJECT This is a State object.

strFile String argument, which is the filepath, such as "C:\Temp\State.sav".

Remarks
When using this method on a server-side script running on an internet application such as ASP you
need to make sure that the user account executing the script has read access to the file specification.
Keep in mind, however, that if you are also calling State.WriteToFile you need write access as well.

See Also
State.WriteToFile method (State object) on page 505

MapInfo MapX Developer Guide v5.0 501

Chapter 18: The MapX Object Model

State.Reset method (State object)

Purpose
This method rewinds the state object to the beginning of its saved or initialized storage. It is
particularly useful when restoring multiple copies of stored objects and/or variables.

Example
Save a map using the following statement:
Stateobj.Save mapobj
Then, restore two copies by using the following statements:
Stateobj.Restore mapobj1
Stateobj.Reset
Stateobj.Restore mapobj2

See Also
State.ReadFromFile method (State object) on page 501
State.Restore method (State object) on page 502
State.Save method (State object) on page 504
State.Stream property (State object) on page 504

State.Restore method (State object)

Purpose
This method restores an item into the State object's internal storage. An item can be an object that
supports persistence (e.g. a Map object) or a variable (e.g. a String variable) You cannot restore arrays
(e.g. a String(5) variable.) In order to restore an item properly, you must call State.Restore the same
number of times and order as State.Save. Incorrect order results in an error.

Syntax
OBJECT.Restore (item)

Part Description

OBJECT This is a State object.

item This is the object or variable to restore.

Examples
A MapX map object is a persistent object. To restore a previously saved map object embedded in a
Visual Basic form, you need to do the following:
objState.Restore Map1.Object
Note: Object is a property in VB to access the OLE object of an embedded control.

502 MapInfo MapX Developer Guide v5.0

State.Restore method (State object)

To restore a previously saved map object in ASP (or any other web server application), there is no
Object property, so you can just send the actual object directly:
objState.Restore objMap
Note: objMap must be an existing Map object.
To restore three previously saved variables, e.g. the map zoom, center x and center y, do the following:
Dim nZoom
Dim nCenterX
Dim nCenterY
'save state
objState.Save Map1.Zoom
objState.Save Map1.CenterX
objState.Save Map1.CenterY
'restore state calls are made in the same order
objState.Restore nZoom
objState.Restore nCenterX
objState.Restore nCenterY
objMap.ZoomTo nZoom, nCenterX, nCenterY

Remarks
You can call this method multiple times to restore multiple items.
When restoring persistent objects, you must have an existing object, not just an empty object variable.
You may call State.Restore multiple times to restore more than one object or variable in the same State
object, as long as you have originally called State.Save the same number of times and order with
equivalent objects and variables.
You do not need to call State.Reset before the first State.Restore call, if calling State.Restore right after
setting the State.Stream property or calling State.Save or State.ReadFromFile) because it is done
automatically.
You cannot restore the property of an object directly. You must restore it into a variable and then set the
object property. For example, to save the Map.Zoom property, do the following:
objState.Save Map1.Zoom
To restore it, however, you must do the following:
Dim nZoom as Double
objState.Restore nZoom
Map1.Zoom = nZoom

See Also
State.Save method (State object) on page 504

MapInfo MapX Developer Guide v5.0 503

Chapter 18: The MapX Object Model

State.Save method (State object)

Purpose
This method saves an item into the State object's internal storage. An item can be an object that
supports persistence (e.g. a Map object) or a variable (e.g. a String variable) You cannot save arrays
(e.g. a String(5) variable.)

Syntax

Part Description

OBJECT This is a State object.

item This is the object or variable to restore.

Examples
A MapX map object is a persistent object. To save a map object embedded in a Visual Basic form, you
need to do the following:
objState.Save Map1.Object
Note: Object is a property in VB to access the OLE object of an embedded control.
To save a map object in ASP (or any other web server application), there is no Object property, so you
can just send the actual object directly:
objState.Save objMap
To save three variables, e.g. the map zoom, center x and center y, do the following:
objState.Save objMap.Zoom
objState.Save objMap.CenterX
objState.Save objMap.CenterY

Remarks
You can call this method multiple times to save multiple items.
The following MapX objects support persistence: Map, Annotation, Annotations, Layer, Layers,
Labels, LabelProperties, Feature, Dataset, Datasets, Theme, Themes, CoordSys, Style, Field and Fields.

See Also
State.Restore method (State object) on page 502

State.Stream property (State object)

Purpose
This property gets or sets an alphabetic string of characters representing the State object's internal
storage.

504 MapInfo MapX Developer Guide v5.0

State.WriteToFile method (State object)

Example
You can use the State object in an ASP application to save and restore the state of a Map object on every
session request. The following ASP code snippet sends the current state of the Map object back to the
client through a hidden HTML form field:
Dim objState
Set objState = Server.CreateObject("MapX.State.5")
objState.Save objMap
Response.Write("<INPUT TYPE=HIDDEN NAME=""State"" VALUE=" &
objState.Stream & ">")
The following ASP code snippet then restores the Map object to its previous state on the next HTTP
request:
Dim objState
Set objState = Server.CreateObject("MapX.State.5")
objState.Stream = Request.Form.Item("State")
objState.Restore objMap

Remarks
The value of the Stream property contains alphabetic characters only. It does not contain any special
HTML characters so that it can be written in an HTML page as a string value.
This property is useful in web applications to save and restore the state of the Map object on each
session request. You can save the Map object into a State object and then use the Stream property to
send the state back to the client on a hidden HTML form field. On the next session request, you can set
the Stream property of a new State object to the value of the hidden HTML form field and call
State.Restore to restore the Map object.
Keep in mind that saving Map objects with a lot of information (e.g. maps that have several layers or
temporary layers with several features) can significantly increase the amount of data transferred
between the client and the server. An alternate solution is to save the value of the Stream property to
store the value of the Stream object in a database and send a key back to the client. This key can then be
used on the next session request to retrieve the Stream value from the database.

See Also
State.Restore method (State object) on page 502
State.Save method (State object) on page 504

State.WriteToFile method (State object)

Purpose
This method writes the State object to a binary file.

MapInfo MapX Developer Guide v5.0 505

Chapter 18: The MapX Object Model

Syntax
OBJECT.WriteToFile (strFile)

Part Description

OBJECT This is a State object.

strFile String argument, which is the filepath, such as "C:\Temp\State.sav".

Remarks
When using this method on a server-side script running on an internet application such as ASP you
need to make sure that the user account executing the script has write access to the file specification.

See Also
State.ReadFromFile method (State object) on page 501

506 MapInfo MapX Developer Guide v5.0

State.WriteToFile method (State object)

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.MaxVectorSymbolCharacter property
• Style.MinVectorSymbolCharacter property
• Style.RegionBackColor property
• Style.RegionBorderColor property
• Style.RegionBorderStyle property
• Style.RegionBorderWidth property
• 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.SymbolType property
• Style.SymbolVectorColor property
• Style.SymbolVectorSize property
• Style.TextFont property
• Style.TextFontAllCaps property
• Style.TextFontBackColor property
• Style.TextFontColor property
• Style.TextFontDblSpace property
• Style.TextFontHalo property
• Style.TextFontOpaque property
• Style.TextFontRotation property

MapInfo MapX Developer Guide v5.0 507

Chapter 18: The MapX Object Model

• Style.TextFontShadow 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.
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.

508 MapInfo MapX Developer Guide v5.0

Style.DrawRegionSample method (Style object)

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.

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.

MapInfo MapX Developer Guide v5.0 509

Chapter 18: The MapX Object Model

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.
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.)

510 MapInfo MapX Developer Guide v5.0

Style.ExportRegionSample method (Style object)

Purpose
Exports the region style sample.

Syntax
OBJECT.ExportRegionSample (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 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.

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.)

512 MapInfo MapX Developer Guide v5.0

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 v5.0 513

Chapter 18: The MapX Object Model

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.

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.

514 MapInfo MapX Developer Guide v5.0

Style.LineSupportsInterleave property (Style object)

Purpose
A read-only Boolean property. Denotes whether a given pen style supports interleave or not.

Style.LineWidth property (Style object)

Purpose
This property contains the width of a line and is used for linear objects. This is an Integer value.

Remarks
You may specify a style Style.LineWidth in tenths of points or in pixels by setting the
Style.LineWidthUnit property to one of the StyleUnitConstants.

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.

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 v5.0 515

Chapter 18: The MapX Object Model

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.

516 MapInfo MapX Developer Guide v5.0

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 property (Style object) on page 517

Style.RegionColor property (Style object)

Purpose
Contains the region color and is used for region objects. This is an OLE_COLOR value.

Style.RegionPattern property (Style object)

Purpose
Contains the region pattern and is used for region objects. This takes a FillPatternConstants value.

MapInfo MapX Developer Guide v5.0 517

Chapter 18: The MapX Object Model

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.

See Also
BitmapSymbol Object and BitmapSymbols Collection on page 283

Style.SymbolBitmapColor property (Style object)

Purpose
A read-write OLE_COLOR value, used to override the non-white pixels in a bitmap symbol.

518 MapInfo MapX Developer Guide v5.0

Style.SymbolBitmapName property (Style object)

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
BitmapSymbol Object and BitmapSymbols Collection on page 283

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
BitmapSymbol Object and BitmapSymbols Collection on page 283

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
BitmapSymbol Object and BitmapSymbols Collection on page 283

MapInfo MapX Developer Guide v5.0 519

Chapter 18: The MapX Object Model

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.
The SymbolBitmapSize point values range from 1 - 48. If a bitmap symbol is less than 1 then
SymbolBitmapSize is set to 1. Conversely, if a bitmap symbol is greater than 48 points, then
SymbolBitmapSize is set to 48.

See Also
BitmapSymbol Object and BitmapSymbols Collection on page 283

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
BitmapSymbol Object and BitmapSymbols Collection on page 283

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 property (Style object) on page 521

520 MapInfo MapX Developer Guide v5.0

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.

See Also
Style.SymbolCharacter property (Style object) on page 520
Setting Font Attributes on page 108

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 to TrueType 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.

MapInfo MapX Developer Guide v5.0 521

Chapter 18: The MapX Object Model

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 to TrueType font symbols. This is a Boolean
value.

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.

522 MapInfo MapX Developer Guide v5.0

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 on page 655

MapInfo MapX Developer Guide v5.0 523

Chapter 18: The MapX Object Model

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 on page 655

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
This property 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
beneath. 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.

Style.TextFontRotation property (Style object)

Purpose
This read/write property indicates the number of degrees to rotate a Text object with an integer value.
Negative integers will rotate the text clockwise and positive integers will rotate the text counter-

524 MapInfo MapX Developer Guide v5.0

Style.SymbolType property (Style object)

clockwise. It is valid only for Feature objects and if set/queried for any other 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
BitmapSymbol Object and BitmapSymbols Collection on page 283

MapInfo MapX Developer Guide v5.0 525

Chapter 18: The MapX Object Model

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 object)
• 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.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.

526 MapInfo MapX Developer Guide v5.0

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".

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 property (Theme object) on page 527
Theme.DataMin property (Theme object) on page 527

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 property (Theme object) on page 527
Theme.DataMin property (Theme object) on page 527

MapInfo MapX Developer Guide v5.0 527

Chapter 18: The MapX Object Model

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.

See Also
Layer Object and Layers Collection on page 377

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.

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 collection) on page 530
Themes.Item property (Themes collection) on page 532

528 MapInfo MapX Developer Guide v5.0

Theme.Properties property (Theme object)

Themes.Remove method (Themes collection) on page 532Themes.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.

See Also
Theme.ThemeProperties property (Theme object) on page 530
ThemeProperties Object on page 534

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 v5.0 529

Chapter 18: The MapX Object Model

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 on page 534

Theme.Type property (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.
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.

530 MapInfo MapX Developer Guide v5.0

Themes.Count property (Themes collection)

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.
ComputeTheme Boolean. The default value is True which will calculate the theme from the 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.

See Also
Field object and Fields collection on page 340
Theme.DataMax property (Theme object) on page 527
Theme.DataMin property (Theme object) on page 527
Theme.Name property (Theme object) on page 528
Theme.Type property (Theme object) on page 530

Themes.Count property (Themes collection)

Purpose
The number of Theme objects in a Themes collection. This is a read-only property.

MapInfo MapX Developer Guide v5.0 531

Chapter 18: The MapX Object Model

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 (Theme object) on page 528

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 (Theme object) on page 528

Themes.RemoveAll method (Themes collection)

Purpose
Removes all Theme objects from the collection.

532 MapInfo MapX Developer Guide v5.0

Themes.RemoveAll method (Themes collection)

Syntax
OBJECT.RemoveAll

MapInfo MapX Developer Guide v5.0 533

Chapter 18: The MapX Object Model

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
• ThemeProperties.SymbolStyle property
• ThemeProperties.ValuePerDot property
• ThemeProperties.Width property

534 MapInfo MapX Developer Guide v5.0

ThemeProperties.AllowEmptyRanges property (ThemeProperties object)

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 property (Legend object) on page 422

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 (ThemeProperties object) on page 538

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.

MapInfo MapX Developer Guide v5.0 535

Chapter 18: The MapX Object Model

Distribution Description

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
RangeCategory Object and RangeCategories Collection on page 477

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 property (ThemeProperties object) on page 540

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.

536 MapInfo MapX Developer Guide v5.0

ThemeProperties.IndividualValueCategories property (ThemeProperties object)

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.

See Also
ThemeProperties.BarIndependentScale property (ThemeProperties object) on page 541

ThemeProperties.IndividualValueCategories property (ThemePro-

perties object)
Purpose
This returns an IndividualValueCategories collection; used with Individual Value thematic maps.

See Also
IndividualValueCategory object and IndividualValueCategories collection on page 363

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
MultivarCategory Object and MultivarCategories Collection on page 461

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 v5.0 537

Chapter 18: The MapX Object Model

ThemeProperties.RangeCategories property (ThemeProperties

object)
Purpose
This returns a RangeCategories collection; used with ranged thematic maps.

See Also
RangeCategory Object and RangeCategories Collection on page 477

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 (Map object) on page 452
ThemeProperties.DataValue property (ThemeProperties object) on page 535

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.

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).

538 MapInfo MapX Developer Guide v5.0

ThemeProperties.ValuePerDot property (ThemeProperties object)

Note: ThemeProperties.PositiveSymbolStyle is now the preferred name for this property.

See Also
ThemeProperties.PositiveSymbolStyle property (ThemeProperties object) on page 543
Style Object on page 507
ThemeProperties.DataValue property (ThemeProperties object) on page 535

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 (Map object) on page 452

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 object) on page 540

MapInfo MapX Developer Guide v5.0 539

Chapter 18: The MapX Object Model

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 object) on page 539

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.

See Also
ThemeProperties.GraduateSizeBy property (ThemeProperties object) on page 543

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 object) on page 541

540 MapInfo MapX Developer Guide v5.0

ThemeProperties.BarGraduatedStack property (ThemeProperties object)

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 object) on page 540
ThemeProperties.GraduateSizeBy property (ThemeProperties object) on page 543

ThemeProperties.BarIndependentScale property (ThemeProper-

ties 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 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. 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 (Map object) on page 452

MapInfo MapX Developer Guide v5.0 541

Chapter 18: The MapX Object Model

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 on page 507
ThemeProperties.BorderStyle property (ThemeProperties object) on page 542

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 on page 507
ThemeProperties.BarFrameStyle (ThemeProperties object) on page 542

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 object) on page 543
ThemeProperties.NegativeSymbolStyle property (ThemeProperties object) on page 543

542 MapInfo MapX Developer Guide v5.0

ThemeProperties.PositiveSymbolStyle property (ThemeProperties object)

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.

See Also
Style Object on page 507
ThemeProperties.ShowNegativeValues property(ThemeProperties object) on page 542y
ThemeProperties.NegativeSymbolStyle property (ThemeProperties object) on page 543
ThemeProperties.DataValue property (ThemeProperties object) on page 535

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).

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.

MapInfo MapX Developer Guide v5.0 543

Chapter 18: The MapX Object Model

See Also
ThemeProperties.PieGraduated property
ThemeProperties.BarGraduatedStack property

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.

See Also
OLE_COLOR Values on page 655

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 object) on page 544

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 (ThemeProperties object) on page 544

544 MapInfo MapX Developer Guide v5.0

ThemeProperties.InflectRanges property (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 object) on page 545
ThemeProperties.InflectionColor property (ThemeProperties object) on page 546
ThemeProperties.RangeCategories property (ThemeProperties object) on page 538

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.InflectionRange property (ThemeProperties object) on page 545
ThemeProperties.InflectionColor property (ThemeProperties object) on page 546

MapInfo MapX Developer Guide v5.0 545

Chapter 18: The MapX Object Model

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 object) on page 545

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 object) on page 538

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.

See Also
ThemeProperties.RangeCategories property (ThemeProperties object) on page 538
RangeCategory Object and RangeCategories Collection on page 477
ThemeProperties.IndividualValueCategories property (ThemeProperties object) on page 537
IndividualValueCategory object and IndividualValueCategories collection on page 363

546 MapInfo MapX Developer Guide v5.0

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.

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.

MapInfo MapX Developer Guide v5.0 547

Chapter 18: The MapX Object Model

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.

548 MapInfo MapX Developer Guide v5.0

Variable.Name property (Variable 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
• Variables.Item method

Collection Methods
• Variables.Add method
• Variables.Clone 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 the Variables 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.

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.

MapInfo MapX Developer Guide v5.0 549

Chapter 18: The MapX Object Model

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.

Variables.Add method (Variables collection)

Purpose
This method adds a Variable object to a Variables collection and is the default property/method of the
Variables collection.

Syntax
[ 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 and Features Collection on page 308
IDispatch Table on page 657

550 MapInfo MapX Developer Guide v5.0

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.

Variables.Item method (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.

MapInfo MapX Developer Guide v5.0 551

Chapter 18: The MapX Object Model

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.

552 MapInfo MapX Developer Guide v5.0

Appendix A: MapX Events

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.
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.
Event Dispatch ID Called…

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.

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.

554 MapInfo MapX Developer Guide v5.0

AnnotationAdded event

Part Description

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-
• 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

Syntax

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

MapInfo MapX Developer Guide v5.0 555

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.

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.

556 MapInfo MapX Developer Guide v5.0

DrawUserLayer Event

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)
coordinates.

Remarks
You can also add a UserDrawLayer via Layers.Add.

LabelChanged Event
MapX fires this event whenever a label is about to be added (via the stock Label tool), selected,
deselected or moved (via stock Select tool). The MapX programmer has the opportunity to prevent the
operation by setting the EnableDefault value to False.

Note: This event is only fired for changes made via user interaction (like selecting the label or
moving it), NOT through programmatic changes. For example, Label.AnchorX = -110 will
not fire the event, even though it does move the label.

Syntax
LabelChanged(ChangeType, ChangingLabels, *EnableDefault)
Dispatch ID = 17

Part Description

changetype Integer: is the type of change that is about to occur (miLabelMove,

miLabelAdd, or miLabelSelectionChange)

MapInfo MapX Developer Guide v5.0 557

Part Description

ChangingLabels Labels object: Represents a collection of Label objects that are about to
change. This has the same interface as the Layer object's Labels collection
(i.e., it has a Count and [Item] property).
*EnableDefault Boolean: Controls whether the MapX default behavior is allowed to take
effect. Default value is True. If you set this to False in the event handler,
MapX will ignore the user interaction about to change the label.

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.

558 MapInfo MapX Developer Guide v5.0

MouseWheel Event

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.
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)

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.

MapInfo MapX Developer Guide v5.0 561

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.

Remarks
ResolveDataBindEx is fired only for multiplegeo columns and only if choice is set to 1 during
ResolveDataBind Event.

562 MapInfo MapX Developer Guide v5.0

SelectionChanged 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.
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

MapInfo MapX Developer Guide v5.0 563

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.

564 MapInfo MapX Developer Guide v5.0

Custom Dataset Support

Appendix B: 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\<DatasetID>
Add the string value:
HKEY_LOCAL_MACHINE\SOFTWARE\MapInfo\MapX\DatasetEngines\<DatasetID>
\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 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 unregistered!

MapInfo MapX Developer Guide v5.0 565

Custom Dataset Support

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).

[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.

566 MapInfo MapX Developer Guide v5.0

Custom Dataset Support

[in] VARIANT * pvFields Contains an array of VARIANTS. 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.

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.

MapInfo MapX Developer Guide v5.0 567

Custom Dataset Support

[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),
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();
}

568 MapInfo MapX Developer Guide v5.0

Custom Dataset Support

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 11th.

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::BeginFetch
HRESULT BeginFetch();

Description
Indicates that a fetch sequence is about to begin. Can be used to allocate/set up resources needed
for fetching data.

MapInfo MapX Developer Guide v5.0 569

Custom Dataset Support

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

[
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.

570 MapInfo MapX Developer Guide v5.0

Custom Dataset Support

[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.

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

MapInfo MapX Developer Guide v5.0 571

Custom Dataset Support

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.

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"),

572 MapInfo MapX Developer Guide v5.0

Custom Dataset Support

version(1.0)
]
interface IMMapXColumnInfo : IUnknown
{
HRESULT Init(
[in] BSTR bstrName,
[in] VARTYPE vt,
[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

MapInfo MapX Developer Guide v5.0 573

Custom Dataset Support

The name of );
the source
data column.

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.

574 MapInfo MapX Developer Guide v5.0

MapX Error Codes

Appendix C: 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.

MapInfo MapX Developer Guide v5.0 585

MapX Error Codes

Error Description

1309 Invalid snap tolerance. The tolerance must be between 1 and %d

1310 Pack operation failed. This is most likely caused by inability to obtain
exclusive access to the necessary file(s) which may be due to another
application or a call to BeginAccess without a corresponding call to
EndAccess.
1311 Unable to convert point to Military Grid reference system point
1312 Unable to convert point from Military Grid reference system point
1313 The XML document object is invalid
1314 The XML construct is incomplete or invalid
1315 Invalid label LabelAlong setting specified.
1316 Invalid label position specified.
1317 Invalid label offset specified. Label offsets must be between 0 and 50.
1318 Invalid label line type specified.
1319 Invalid label anchor specified.

586 MapInfo MapX Developer Guide v5.0

Constants

Appendix D: 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
SearchResultTypeConstants SelectionTypeConstants
SpreadByConstants StyleUnitConstants
SymbolTypeConstants ThemeTypeConstants
ToolConstants ToolFlagConstants
ToolTypeConstant

AggregationFunctionConstants
miAggregationSum = 0
miAggregationAverage = 1

MapInfo MapX Developer Guide v5.0 587

Constants

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
miUnitSquareMeter = 21
miUnitSquareSurveyFoot = 22
miUnitSquareNauticalMile = 23
miUnitSquareTwip = 24
miUnitSquarePoint = 25

588 MapInfo MapX Developer Guide v5.0

Constants

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

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

MapInfo MapX Developer Guide v5.0 589

Constants

miColorBlue = 16711680
miColorMagenta = 16711935
miColorCyan = 16776960
miColorWhite = 16777215
miColorLightGray = 12632256
miColorDarkGray = 4210752
miColorGray = 8421504
miColorPaleYellow = 13697023
miColorLightYellow = 8454143
miColorYellow = 65535
miColorLimeGreen = 12639424
miColorTeal = 8421440
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

590 MapInfo MapX Developer Guide v5.0

Constants

miColorHighlight = 0x8000000D
miColorHighlightText = 0x8000000E
miColorButtonFace = 0x8000000F
miColorButtonShadow = 0x80000010
miColorGrayText = 0x80000011
miColorButtonText = 0x80000012
miColorInactiveCaptionText = 0x80000013
miColor3DHighlight = 0x80000014
miColor3DDarkShadow = 0x80000015
miColor3DLight = 0x80000016
miColorInfoText = 0x80000017
miColorInfoBackground = 0x80000018

ColorSpreadingMethodConstants
miColorMethodRGB = 0
miColorMethodHSV = 1

ConversionConstants
miMapToScreen = 0
miScreenToMap = 1

MapInfo MapX Developer Guide v5.0 591

Constants

CoordSysTypeConstants
Constant Value Description

miAlbersEqualAreaConic 9
miAzimuthalEquidistant 5 Polar aspect only
miDblStereographic 31
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
miMercatorStdParallel 26 Regional Mercator
miPolyconic 27 Polyconic

592 MapInfo MapX Developer Guide v5.0

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

FeatureEditModeConstants
miEditModeFeature = 0x1
miEditModeNode = 0x2
miMoveDuplicateNodes = 0x4
miDeleteDuplicateNodes = 0x8
miEditModeAddNode = 0x40

MapInfo MapX Developer Guide v5.0 595

Constants

FeatureTypeConstants
miFeatureTypeRegion = 0
miFeatureTypeLine = 1
miFeatureTypeSymbol = 2
miFeatureTypeMixed = 3
miFeatureTypeUnknown = 4
miFeatureTypeText = 5
miFeatureTypeNull = 6
miFeatureTypeMultipoint = 7
miFeatureTypeCollection = 8

FieldTypeConstants
miTypeString = 0
miTypeNumeric = 1
miTypeDate = 2
miTypeInteger = 3
miTypeSmallInt = 4
miTypeFloat = 5
miTypeLogical = 6

FillPatternConstants
miPatternNoFill = 0
miPatternHollow = 1
miPatternSolid = 2
miPatternHorizontal = 3
miPatternVertical = 4
miPatternFDiag = 5
miPatternFilBDiag = 6
miPatternCross = 7
miPatternDiagCross = 8

596 MapInfo MapX Developer Guide v5.0

Constants

GraduationConstants
miGraduateBySquareRoot = 0
miGraduateByConstant = 1
miGraduateByLogarithm = 2

IntersectionPointConstants
miIntersectCrossings = 9
miIntersectCommon = 10
miIntersectAll = 11

IntersectionTestConstants
miIntersectCentroidWithinFeature = 0
miIntersectFeature = 1
miIntersectEntirelyWithinFeature = 2

LabelAlongConstants
miLabelAlongNone = 0
miLabelAlongParallel = 1
miLabelAlongMultiSegment = 2

LineTypeConstants
miLineTypeArrow = 0
miLineTypeNone = 1
miLineTypeSimple = 2

LabelChangedType Constants
miLabelMove = 0
miLabelAdd = 1
miLabelSelectionChange = 2

MapInfo MapX Developer Guide v5.0 597

Constants

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

LayerTypeConstants
miLayerTypeNormal = 0
miLayerTypeRaster = 2
miLayerTypeSeamless = 4
miLayerTypeUnknown = 5
miLayerTypeUserDraw = 6
miLayerTypeDrilldown = 7

598 MapInfo MapX Developer Guide v5.0

Constants

LineTypeConstants
miLineTypeNone = 0
miLineTypeSimple = 1
miLineTypeArrow = 2

LayerPackConstants
miPackGraphics=1
miRebuildGraphics=2
miPackIndex=4
miRebuildIndex=8
miPackData=16
miCompactDB=32
miPackAll=21 (miPackGraphics & miPackIndex & miPackData)

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
miUnitTwip = 10
miUnitPoint = 11

Constants

ThemeTypeConstants
miThemeRanged = 0
miThemeBarChart = 1
miThemePieChart = 2
miThemeGradSymbol = 3
miThemeDotDensity = 4
miThemeIndividualValue = 5
miThemeAuto = 6
miLabelRangedTheme = 7
miLabelIndividualValuesTheme = 8
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

ToolFlagConstants
miToolBegin = 0

MapInfo MapX Developer Guide v5.0 603

Constants

miToolEnd = 1
miToolEndEscaped = 2
miToolInProgress = 3

ToolTypeConstants
miToolTypePoint = 0
miToolTypeLine = 1
miToolTypeCircle = 2
miToolTypeMarquee = 3
miToolTypePoly = 4
miToolTypePolygon = 5

604 MapInfo MapX Developer Guide v5.0

Creating Expressions

Appendix E: 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.
In expressions, MapX will perform a type conversion from boolean to string for function parameters
that expect a string argument.
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 v5.0 605

Creating Expressions

Operators
Below is a list of the operators used in MapX and related topics.

Operators:
• Geographic operators
• Mathematical operators
• String operators
• 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
object1 PARTLY WITHIN object2 First object touches second object.
object1 WITHIN object2 Centroid of first object is within the second object.

606 MapInfo MapX Developer Guide v5.0

Mathematical operators

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.

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.

MapInfo MapX Developer Guide v5.0 607

Creating Expressions

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.

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>stringtodate("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>=stringtodate("10-9-91")

Example
Records for all received before August, no matter what year.
• Month(RECEIVED)<8

Logical Comparison
Example
All that have shipped.

608 MapInfo MapX Developer Guide v5.0

Logical operators

• 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

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 are 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”

MapInfo MapX Developer Guide v5.0 609

Creating Expressions

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.

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%"

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

610 MapInfo MapX Developer Guide v5.0

Operator Precedence

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 v5.0 611

Creating Expressions

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
StringToDate( ) function Str$( ) function Tan( ) function
UCase$( ) function Val( ) function Weekday( ) function
Year( ) function

612 MapInfo MapX Developer Guide v5.0

Abs( ) 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.
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).

MapInfo MapX Developer Guide v5.0 613

Creating Expressions

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.

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.

614 MapInfo MapX Developer Guide v5.0

Asin( ) function

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.

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).

MapInfo MapX Developer Guide v5.0 615

Creating Expressions

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.

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.

616 MapInfo MapX Developer Guide v5.0

Centroid( ) function

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

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.

MapInfo MapX Developer Guide v5.0 617

Creating Expressions

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.

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.

618 MapInfo MapX Developer Guide v5.0

Chr$( ) function

Syntax
[ float= ]CentroidY(obj _expr)

Part Description

obj_expr An object expression

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.

MapInfo MapX Developer Guide v5.0 619

Creating Expressions

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( ) function
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.

620 MapInfo MapX Developer Guide v5.0

Day( ) function

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"

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.

MapInfo MapX Developer Guide v5.0 621

Creating Expressions

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
MapUnitConstants on page 599 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.
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.

622 MapInfo MapX Developer Guide v5.0

Fix( ) function

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 ( ^ ).

Fix( ) function
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.

Format$( ) function
Purpose
This returns a string representing a custom-formatted number.

MapInfo MapX Developer Guide v5.0 623

Creating Expressions

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.
. (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).

624 MapInfo MapX Developer Guide v5.0

FormatDate$( ) function

pattern character Role in formatting results:

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.

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

MapInfo MapX Developer Guide v5.0 625

Creating Expressions

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

FormatNumber$( ) function
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)

626 MapInfo MapX Developer Guide v5.0

InStr( ) function

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)

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.

628 MapInfo MapX Developer Guide v5.0

Left$( ) function

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$( ) function
Purpose
This returns part or all of a string, beginning at the left end of the string.

Remarks
The Maximum( ) function returns the larger of two numeric expressions.

MBR( ) function
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.

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.

MapInfo MapX Developer Guide v5.0 631

Creating Expressions

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

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

Remarks
The Minimum( ) function returns the smaller of two numeric expressions.

632 MapInfo MapX Developer Guide v5.0

Month( ) 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 v5.0 633

Creating Expressions

ObjectType( ) function
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.

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")

634 MapInfo MapX Developer Guide v5.0

Proper$( ) function

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.

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.

MapInfo MapX Developer Guide v5.0 635

Creating Expressions

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.

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( ) function
Purpose
This returns the sine of a number.

Note: Functions in MapX are used to create expressions and are passed as arguments. They can

MapInfo MapX Developer Guide v5.0 637

Creating Expressions

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.

Space$( ) function
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.

638 MapInfo MapX Developer Guide v5.0

StringCompare( ) function

Syntax
[ float= ]Sqr( num_expr )

Part Description

num_expr A numeric expression

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.
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

MapInfo MapX Developer Guide v5.0 639

Creating Expressions

Return value: When:

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).
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 )

640 MapInfo MapX Developer Guide v5.0

Str$( ) function

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 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

MapInfo MapX Developer Guide v5.0 641

Creating Expressions

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.
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.

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.

MapInfo MapX Developer Guide v5.0 643

Creating Expressions

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.

Year( ) function
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

644 MapInfo MapX Developer Guide v5.0

Year( ) function

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 v5.0 645

Creating Expressions

646 MapInfo MapX Developer Guide v5.0

Geoset Keys

Appendix F: Geoset Keys

Geosets are files (ending in .GST) that contain information about a set of layers, and can be 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:

MapInfo MapX Developer Guide v5.0 647

Geoset Keys

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"
"\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"

648 MapInfo MapX Developer Guide v5.0

Sample Geoset

"\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"
"\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" = ""

MapInfo MapX Developer Guide v5.0 649

Geoset Keys

"\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.

650 MapInfo MapX Developer Guide v5.0

Supported 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
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

MapInfo MapX Developer Guide v5.0 651

Geoset Keys

\TABLE\<number>\

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)
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

652 MapInfo MapX Developer Guide v5.0

Supported Keys

DISPLAY\FONT\

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

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

MapInfo MapX Developer Guide v5.0 653

Geoset Keys

LABEL\

LINETYPE Number – Corresponds to LabelProperties.LineType

OFFSET Number – Corresponds to LabelProperties.Offset
POSITION Number – Corresponds to LabelProperties.Position

654 MapInfo MapX Developer Guide v5.0

OLE_COLOR Values

Appendix G: 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.

MapInfo MapX Developer Guide v5.0 655

OLE_COLOR Values

656 MapInfo MapX Developer Guide v5.0

PNG files Feature object 105 ReferenceLayer property (Bind-
export format 248 Layer object 56 Layer object) 281
Point object 472 Layers collection 49–50 ReferenceLayerfield property
Point property (Feature object) Map object 8 (BindLayer object) 282
316 Theme objects 113 RefineDataset property (Find ob-
Point reference binding 87 Properties property (Theme object) 351
Point styles ject) 529 RefineField property (Find object)
in remote spatial tables 188 Property Page 351
Points collection 472 modifying a map 9–10 RefineLayer property (Find ob-
Polygon drawing tools 246 PropertyPage method (Map object) 352
Polyline property (Feature object) ject) 453 RefineRegion property (Find-
316 PSD files Result object) 358
PolyToolFlagConstants 601 export format 248 Refining boundaries
PolyToolUsed Event 560 feature searches 130
Portable Network Graphics files Q Refresh method (BitmapSymbol
export format 248 Query property (NotesQueryInfo collection) 284
Position of labels 64 object) 464 Refresh method (DataSet object)
Position property (Graphic object) Query property (OCIQueryInfo 296
361 object) 467 Refresh method (Layer object) 395
Position property (Label object) Refresh method (Map object) 454
370 R Refreshing datasets 90
Position property (LabelProper- Range property (CoordSys object) Region property (Feature object)
ties object) 376 290 316
Position property (Title object) 547 RangeCategories collection 477 RegionBackColor property (Style
PositionConstants 601 RangeCategories property object) 516
PositiveSymbolStyle property (ThemeProperties object) 538 RegionBorderColor property
(ThemeProperties object) 543 RangeCategory object 477 (Style object) 517
PowerBuilder Ranged maps RegionBorderStyle property
data source type 80, 92 range distribution types 116– (Style object) 517
Precision (Field object) 341 118 RegionBorderWidth property
PredominantFeatureType proper- thematic map type 115–118 (Style object) 517
ty (Layer object) 394 Raster images RegionBorderWidthUnit proper-
PreferCompactLegends property displaying 67 ty (Style object) 517
(Map object) 452 ReadFromFile method (State ob- RegionColor property (Style ob-
PrimeMeridian property (Datum ject) 501 ject) 517
object) 305 ReadOnly property (Dataset ob- RegionPattern property (Style ob-
Printing a map 250 ject) 297 ject) 517
PrintLegend method (Legend ob- ReadOnly property (RowValue RegionTransparent property
ject) 422 object) 485 (Style object) 518
PrintMap method (Map object) ReadOnly property (RowValues Remote spatial data
453 collection) 486 accessing 164
Product features 4 Rectangle object 480 accessing attribute data 176
Projections Redistributing Your MapX Appli- caching 178–180
setting in Geoset Manager cation With MrSID 266 LayerInfo parameters 171
149 RedrawInterval property (Map mapping with X/Y columns
Proper$( ) function 635 object) 453 167
Properties RefColumn1 property (BindLayer ODBC connection string 172–
accessing in Visual C++ 214 object) 281 173
Annotations collection 15 RefColumn2 property (BindLayer performance issues 177

686 MapInfo MapX Developer Guide v5.0

Index

Remote spatial tables Replace method (Selection collec- ScaleFactor property (CoordSys
making mappable 185–186 tion) 492 object) 291
MapInfo Map Catalog 181– RequestData event 561 Score property (FindMatch object)
186 Reset method (State object) 502 355
specifying styles 187–188 ResolveDataBind event 561 SDO_GEOMETRY 169
Remove method (Annotations ResolveDataBindConstants 601 Search method (Find object) 352
collection) 277 ResolveDataBindEx event 562 Search method (Layer object) 395
Remove method (DataSets collec- ResolveObject object 483 Search type constants
tion) 303 ResolveObjects collection 483 selections 106
Remove method (Features collec- Restore method (DataSets collec- SearchAtPoint method (Layer ob-
tion) 320 tion) 297 ject) 396
Remove method (Fields collec- Restore method (State object) 502 SearchEx method (Find object) 350
tion) 347 Result codes SearchPath property (Map object)
Remove method (Layers collec- Find object 131 456
tion) 410 Right$( ) function 635 SearchResultTypeConstants 602
Remove method (Parts collection) RollUp tools SearchTypeConstants 601
471 creating 158 SearchWithinDistance method
Remove method (Point object) 476 RotateX, RotateY, RotateZ proper- (Layer object) 397
Remove method (RowValues ob- ties (Datum object) 305 SearchWithinFeature method
ject) 486 Rotation property (Map object) (Layer object) 398
Remove method (Selection collec- 456 SearchWithinRectangle method
tion) 491 Round( ) function 636 (Layer object) 398
Remove method (Theme object) RoundBy property (ThemeProp- Secondary Geofield parameter 81
532 erties object) 544 SecondaryGeoField property
Remove method (Variables collec- RoundRanges property (Theme- (DataSet object) 298
tion) 551 Properties object) 544 Selectable property (Layer object)
RemoveAll method (Annotations Row property (SourceRow object) 399
collection) 277 497 SelectAll method (Selection collec-
RemoveAll method (DataSets col- RowCount property (DataSet ob- tion) 492
lection) 303 ject) 297 SelectByID method (Selection col-
RemoveAll method (Fields collec- RowValue object 485 lection) 492
tion) 348 RowValues collection 485 SelectByPoint method (Selection
RemoveAll method (Layers col- RowValues property (Dataset ob- collection) 493
lection) 411 ject) 296 SelectByRadius method (Selection
RemoveAll method (Parts collec- RTrim$( ) function 637 collection) 494
tion) 471 SelectByRectangle method (Selec-
RemoveAll method (Point object) S tion collection) 494
476 Sample application SelectByRegion method (Selection
RemoveAll method (RowValues Visual C++ 212 collection) 495
collection) 487 Sample applications Selected property (Label object)
RemoveAll method (Theme ob- additional programs 5 370
ject) 532 Sample Connection Strings 173 Selection collection 489
RemoveAll method (Variables Sample Geoset 648 description 102
collection) 552 Save method (Map object) 504 methods 106
RemoveByID method (Features SaveMapAsGeoset method (Map Selection property (Layer object)
collection) 320 object) 456 399
Removing Saving SelectionChanged event 563
labels 64 geosets 143 Selections
Replace method (Features collec- ScaleAdjust property (Datum ob- creating at specific point 106
tion) 321 ject) 305 search type constants 106

690 MapInfo MapX Developer Guide v5.0

QGIS For Hydrological Applications Recipes For Catchment Hydrology and Water Management
100% (11)
QGIS For Hydrological Applications Recipes For Catchment Hydrology and Water Management
168 pages
MAPX45 DevGuide
No ratings yet
MAPX45 DevGuide
766 pages
MapGuide Open Source Developer Guide
No ratings yet
MapGuide Open Source Developer Guide
114 pages
MapGuide Programming Manual
No ratings yet
MapGuide Programming Manual
164 pages
Autocad Map 3d Tutorials
No ratings yet
Autocad Map 3d Tutorials
180 pages
Map Server
No ratings yet
Map Server
817 pages
Map Server Manual
100% (2)
Map Server Manual
690 pages
Map Server
No ratings yet
Map Server
819 pages
Map Server
No ratings yet
Map Server
907 pages
MapServer 5.4.0
No ratings yet
MapServer 5.4.0
714 pages
Mapguide Enterprise 2010 Devlopers Guide
No ratings yet
Mapguide Enterprise 2010 Devlopers Guide
166 pages
Auto Cad
No ratings yet
Auto Cad
175 pages
MapServer PDF
No ratings yet
MapServer PDF
941 pages
MapServer Tutorial
No ratings yet
MapServer Tutorial
708 pages
Getting Started: Autodesk Mapguide Enterprise 2010
No ratings yet
Getting Started: Autodesk Mapguide Enterprise 2010
98 pages
Gisprac 2016july FD
No ratings yet
Gisprac 2016july FD
108 pages
Map Server
No ratings yet
Map Server
758 pages
Publisher With Map Server
No ratings yet
Publisher With Map Server
20 pages
Map Server
No ratings yet
Map Server
857 pages
Map Server
No ratings yet
Map Server
758 pages
MapXtreme2008 DevGuide
No ratings yet
MapXtreme2008 DevGuide
580 pages
Map Server
No ratings yet
Map Server
758 pages
The MapServer Documentation Release 6-4-0
No ratings yet
The MapServer Documentation Release 6-4-0
774 pages
10580-00440C
No ratings yet
10580-00440C
22 pages
GIS For Web Developers
No ratings yet
GIS For Web Developers
258 pages
intro_qgis_apr2024
No ratings yet
intro_qgis_apr2024
91 pages
Map Editor Basics
No ratings yet
Map Editor Basics
436 pages
Map Composer
No ratings yet
Map Composer
68 pages
Geoserver 2.8.0 User Manual PDF
No ratings yet
Geoserver 2.8.0 User Manual PDF
1,213 pages
Map Server
100% (1)
Map Server
1,100 pages
Instant download GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis pdf all chapter
100% (4)
Instant download GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis pdf all chapter
85 pages
50 MapEditor
100% (1)
50 MapEditor
436 pages
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis pdf download
100% (1)
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis pdf download
43 pages
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis - The ebook in PDF/DOCX format is ready for download now
100% (2)
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis - The ebook in PDF/DOCX format is ready for download now
56 pages
Antonio Santiago
No ratings yet
Antonio Santiago
42 pages
Mapbasic v7.0 User Guide
No ratings yet
Mapbasic v7.0 User Guide
333 pages
Quantum GIS
No ratings yet
Quantum GIS
277 pages
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis instant download
100% (1)
GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis instant download
49 pages
QGIS for Hydrological Applications recipes for catchment hydrology and water management 1 ed. Edition Hans Van Der Kwast download
100% (1)
QGIS for Hydrological Applications recipes for catchment hydrology and water management 1 ed. Edition Hans Van Der Kwast download
54 pages
Download ebooks file GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis all chapters
100% (1)
Download ebooks file GIS for Web Developers Adding Where to Your Web Applications 1st Edition Scott Davis all chapters
79 pages
QGIS for Hydrological Applications recipes for catchment hydrology and water management 1 ed. Edition Hans Van Der Kwast download
100% (4)
QGIS for Hydrological Applications recipes for catchment hydrology and water management 1 ed. Edition Hans Van Der Kwast download
52 pages
IEE User Guide PDF
No ratings yet
IEE User Guide PDF
144 pages

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.