Section 2.1. The MapPoint 2004 Object Model

2.1. The MapPoint 2004 Object Model

The MapPoint 2004 APIs and MapPoint 2004 ActiveX Control are designed for building disconnected Windows applications. Since all map data is installed locally on your hard drive, you can build Windows applications that don't need any network connectivity. However, if you need to build a connected web-based mapping application to keep your application footprint to a minimum size, consider instead the MapPoint Web Service, which is discussed later in this book in detail. Building a web-based application using the MapPoint 2004 APIs (or ActiveX Control) not only results in a poorly-performing web application but also violates the MapPoint license model! So, MapPoint 2004 can be used only for building Windows applications.

For a more detailed discussion on which platform to choose for your application development, refer to Chapter 1.

You can develop three kinds of applications using MapPoint 2004:

Location data-processing applications

Use MapPoint 2004 automation internally but don't create maps.

Location visual applications (with map display)

Display location and thematic maps embedded into applications using MapPoint2004.

MapPoint 2004 Add-Ins

Extend the capabilities of MapPoint 2004.

Location data-processing applications are typically used in the business intelligence part of an enterprise application. For example, a goods-delivery company must optimize the stops in a delivery route to save on fuel costs and drivers' time. These applications are developed using the MapPoint 2004 APIs .

The visual application category applies when you want to display a map to represent business data thematically. For example, a map displaying sales across the country based on zip code gives an immediate understanding of whether location plays a crucial role in sales. For applications that embed maps, it is ideal to use the MapPoint 2004 ActiveX Control; however, you can also use MapPoint APIs to display maps without using the ActiveX Control, as discussed in Chapter 3.

MapPoint 2004 Add-Ins extend MapPoint functionality to include your specific business needs. For example, you might want to use MapPoint 2004 application as a mapping tool in your enterprise but need an additional feature to display sales data that is available as an internal web service. In this case, MapPoint 2004 Add-Ins are ideal for adding features to the MapPoint 2004 application. There are also some specific scenarios where you need to implement your application logic as an Add-In for performance reasons, which we will discuss in Chapter 4.

Whether you are developing with the APIs or with the ActiveX Control, the core concepts behind MapPoint 2004 programming are still the same. The only difference is that the ApplicationClass is the root class if you are programming using the APIs, and the AxMapPointControl class is the root class if you are programming using the ActiveX Control. However, both these classes expose the MapClass (via the ActiveMap property), which is the centerpiece of the MapPoint 2004 programming. MapClass offers an extensive set of functions, properties, and collections, including a reference to the parent ApplicationClass via the Application property, which can be used in developing a wide variety of location-based applications.

Figure 2-1 shows the relation of these classes, while Table 2-1 gives you a selective list of the methods exposed on the MapClass object.

Figure 2-1. MapPoint 2004 Object Modelkey objects

Table 2-1. Important methods available on the Map Class

Method name	Description
FindAddressResults	Finds addresses and returns FindResults collection
FindPlaceResults	Finds places (by name) and returns FindResults collection
FindResults	Combines the functionality of FindAddressResults and FindPlaceResults into one method; takes an input string, tries both address and place finding, and returns the successful results as FindResults collection
ObjectsFromPoint	Takes the x and y coordinates on the map and returns a collection of Locations and/or Pushpins that are located at that point
LocationToX and LocationToY	Converts any given location into x and y coordinates on the screen
XYToLocation	Converts any given x and y coordinates on the screen to a MapPoint Location object
AddPushpin	Adds a pushpin at a specified location

The Map class exposes a set of methods that does basic methods to find, mark (by adding pushpins), and convert screen coordinates to loctation objects and vice versa.

Apart from the Map object, the other two important and most frequently used objects are the FindResults and Location objects. The FindResults object represents a collection of Location and/or Pushpin objects. You can access the individual collection items using the FindResults.get_Item method (discussed in more detail later in this chapter). The Location object, on the other hand, represents a real location in MapPoint 2004. The Location object exposes methods such as FindNearby to find nearby points of interest and DistanceTo to find the distance between two points (locations).