If you are using Visual Studio .NET Version 2003 or later, it is easy to add a reference to the MapPoint 2004 APIs using the Add Reference option from the project context menu, as shown in Figure 2-2.

Figure 2-2. Project Add Reference menu

When you see the Add Reference dialog window, select the COM tab and select the Microsoft MapPoint 11.0 Object Library (North America) to add the MapPoint 2004 type library as a reference to your project, as shown in Figure 2-3.

Figure 2-3. Adding the MapPoint 2004 library as a reference

In this process, Visual Studio .NET automatically creates an interoperable assembly and adds it as a reference to your project. By default, the namespace of the newly created assembly is set to MapPoint.

If you do not have Visual Studio .NET, or if you chose to do the hard work of creating the interoperable assembly yourself, you can use the TlbImp.EXE tool (located in the Microsoft Visual Studio .NET 2003SDKv1.1Bin directory) that ships with the .NET framework. For example, to generate the interoperable assembly for MapPoint 2004 type library with the namespace Interop.MapPoint, use the following command-line command:

    C:>tlbimp.exe "C:Program FilesMicrosoft MapPoint
    MPNA82.tlb" /out:"C:Interop.MapPoint.dll" /namespace:Interop.MapPoint /sysarray/
    transform:dispret

This command generates the interoperable assembly Interop.MapPoint.dll in the C: directory; add it to your project as a reference as you would do with any other .NET assembly.

Now that you have added the MapPoint 2004 object library to your project as a reference, let’s get started with a simple application.

When you think of mapping in general, the first thing that comes to mind is finding a location—whether it is a place or an address. A place is a general location referred by its commonly known name; an address is a more detailed specification of a location. For example, one of the best-known places in Seattle is the Space Needle, but the actual address of the Space Needle is 498 Broad St, Seattle, WA 98109. Using MapPoint 2004, you can find both places and addresses, as well as other elements that I discuss later.

Let’s start off by building a simple Windows application that finds a place and returns the address for that place. This application contains a text box to input a place name and a button that can be used to fire an event to find the input place. When the input place is found, the address of the place is displayed in the text box labeled Address. The Windows form layout, which you can lay out in Visual Studio, is shown in Figure 2-4.

Figure 2-4. Find Place sample application

Now, let’s write the code that is invoked when the Find button is clicked. The root of MapPoint 2004 API programming is the ApplicationClass, so let’s start by creating an instance of ApplicationClass:

    //Create an instance of ApplicationClass
    //Important Note: You need to clean up after you are done with the
    //application class. For more informantion, see the section
    //"Cleaning Up After You're Done"
    MapPoint.ApplicationClass app = new MapPoint.ApplicationClass( );

After creating the ApplicationClass, access the Map instance via the ActiveMap property:

    //Get a reference to the Map instance via the ActiveMap property 

    MapPoint.Map map = app.ActiveMap;

The MapClass exposes a method, FindPlaceResults, that returns all places matching the input query. This method takes the place name string as input and returns FindResults, which is a collection of locations found. The following code shows the FindPlaceResults method call:

    //Call FindPlaceResults on the MapClass instance
    MapPoint.FindResults findResults = map.FindPlaceResults(this.textBox1.Text);

When the method call is complete, the FindResults instance will contain all the locations that matched the input query. The number of matches is represented by the Count property of the FindResults instance. In our example, the search for “Space Needle” resulted in 25 matches. Next, we need to go through the list to figure out which instance represents the Space Needle in Seattle. So, let’s add a modal dialog to show a ListBox control with all found locations so that we can disambiguate the results manually.

Each location that matched the input place is represented as an instance of MapPoint.Location class in the FindResults object. Even though the FindResults class is essentially a collection of Location objects, its behavior is quite different from any .NET collection—you cannot directly access the Location items in the FindResults collection using the index number:

    FindResults.Items[index]

In fact, the Items indexer is not exposed in the FindResults class in the interoperable assembly; however, there are still two ways to get the Location objects from the FindResults collection, using either the get accessor method or an enumerator.

    //Create an object to hold index value
    object index = null;
    //Start with index 1 instead of 0
    for(int i=1; i<=findResults.Count; i++)
    {
        //Box the integer value as an object
        index = i;
        //Pass the index as a reference to the get_Item accessor method
        MapPoint.Location loc = findResults.get_Item(ref index) as MapPoint.
    Location;
        if(loc != null)
            this.listBox1.Items.Add(loc.Name);
    }

Using an enumerator

You can also access the list of Locations from FindResults instance using the enumeration. The FindResults instance exposes a method, GetEnumerator, to get an enumerated list of locations. Using this enumerator instance, you can loop through the list of locations as follows:

    //Get an enumerator using the GetEnumerator method 

    IEnumerator locationEnumerator = findResults.GetEnumerator( );
    //Loop through the location instances to get the names
    while(locationEnumerator.MoveNext( ))
    {
        MapPoint.Location loc = locationEnumerator.Current as MapPoint.Location;
        if(loc != null)
            this.listBox1.Items.Add(loc.Name);
    }

The net effect is same for both methods, but the code in the enumerator approach looks cleaner than the get_Item accessor approach. However, the get_Item accessor approach performs better than the enumerator approach, especially when a large number of locations is found. The get_Item accessor method also provides a way to access the desired item directly instead of looping through the entire list.

We can use either method to populate the list of locations in the ListBox of the modal dialog, as shown in Figure 2-5.

Figure 2-5. Disambiguation modal dialog

Look at the list to get the address. From the list of 25 found locations’ names from our query, the first name reads “Space Needle [tower], Seattle, WA,” which is what we are looking for. Since this is the very first instance in the list, you can use the index to obtain the Location object and the StreetAddress property to get the actual address:

    object currentLocationIndex = findResModalDlg.SelectedIndex + 1;
    MapPoint.Location loc = this.findResults.get_Item(ref index) as MapPoint.Location;
    //Access the StreetAddress property 
 for address
    if(loc != null)
    {
        if(loc.StreetAddress != null)
            this.textBox2.Text = loc.StreetAddress.Value;
        else
            this.textBox2.Text = loc.Name;
    }

There are a couple of things of note in this code:

• We are adding 1 to the selected index because the items in the ListBox are zero-index based, but the locations in FindResults collection start with index 1, so to offset this difference, you need to add 1 to the selected index manually.

• Not all locations have addresses. Although it sounds strange, what address would be returned if you searched for “Seattle” and the returned location was “Seattle, WA”? In cases like this, it is sufficient to return the name of the location.

After obtaining the desired Location object from the FindResults collection, you can access the street address from the Location.StreetAddress property. We now have the address for the Space Needle, which is “498 Broad St, Seattle, WA 98109.”

You may be wondering why MapPoint 2004 can’t tell you whether there is a best location match instead of making you go through the list to disambiguate the locations each and every time. Actually, it does tell you.

    //See if the FindResults.ResultsQuality is either
    //geoFirstResultGood or geoAmbiguousResults
    if(findResults.ResultsQuality ==
               MapPoint.GeoFindResultsQuality.geoFirstResultGood
       || findResults.ResultsQuality ==
               MapPoint.GeoFindResultsQuality.geoAmbiguousResults)
    {
        //No need to disambiguate, just return the street address
        //of the first location
        currentLocationIndex = 1;
        //Get the Location object
        MapPoint.Location loc
            = this.findResults.get_Item(ref currentLocationIndex) as MapPoint.Location;
        //Access the StreetAddress property for address
        if(loc != null)
        {
           if(loc.StreetAddress != null)
             this.textBox2.Text = loc.StreetAddress.Value;
           else
             this.textBox2.Text = loc.Name;
        }

    }
    else
    {
      //Add disambiguation process and show modal dialog
      FindResultListDlg findResModalDlg = new FindResultListDlg(ref findResults);
      if(findResModalDlg.ShowDialog( ) == DialogResult.OK)
      {
        //Process the selected location from the find results list
        . . .
      }
    }

MapPoint 2004 API provides a way to find addresses. The Map class has a method, FindAddressResults, which you can use to find addresses. Unlike the FindPlaceResults method, this method takes a full or partial address to find the intended location. So, in order to use the FindAddressResults method, you have to provide at least one of the following parts of an address:

The Country parameter is expressed as a GeoCountry enumeration, while the rest of the parameters are strings. For example, if you want to find the address “498 Broad St, Seattle, WA 98109” in the United States, you have to use the GeoCountry.geoCountryUnitedStates value for Country. The following code shows how to invoke the FindAddressResults method on a Map class:

    //Create an instance of the MapPoint application class
    MapPoint.ApplicationClass app = new MapPoint.ApplicationClass( );

    //Get the Map object from the application object
    MapPoint.Map map = app.ActiveMap;

    //Call the FindAddressResults method 

    MapPoint.FindResults findResults = map.FindAddressResults(
                                            "498 Broad St",
                                            "Seattle",
                                            string.Empty,
                                            "WA",
                                            "98109",
                                MapPoint.GeoCountry.geoCountryUnitedStates);

Note that when a Country parameter is supplied, the address provided must match that country’s address format, or the FindAddressResults method throws an exception. For example, if you pass the above address for GeoCountry.geoCountryUnitedKingdom (UK), the FindAddressResults method throws an exception (since some UK addresses expect the Other City parameter).

The quality of the locations returned by the method can be determined by the ResultsQuality property of the FindResults object. The rules that we have discussed in the previous section to disambiguate the locations results are applicable to this method as well.

Do you always need to have the address in the previously described format? Our application collects the input location into a simple textbox as a string, so is it possible to have an address entered as a single string so that you can programmatically parse the address before calling the FindAddressResults method? Absolutely; MapPoint 2004 has a method to do this.

    //Create an instance of the MapPoint application class
    MapPoint.ApplicationClass app = new MapPoint.ApplicationClass( );
    //Get the Map object from the application object
    MapPoint.Map map = app.ActiveMap;
    //Parse the address
    MapPoint.StreetAddress address =
        map.ParseStreetAddress("498 Broad St, Seattle, WA, 98109");

    //Now get the values from the
    //StreetAddress properties
    string streetName = address.Street;
    string city = address.City;

The Map class has a method, FindResults, that can find both places and addresses. This method takes the input location as a string and tries to parse the string into a valid address. If the input string is successfully parsed into an address, then a FindAddressResults method is called to find the input location; when the input string cannot be parsed into a valid address, the FindPlaceResults method is called. The following code snippet shows how to use the FindPlaceResults method:

    //Create an instance of the MapPoint application class
    MapPoint.ApplicationClass app = new MapPoint.ApplicationClass( );
    //Get the Map object from the application object
    MapPoint.Map map = app.ActiveMap;
    //Works with finding addresses
    MapPoint.FindResults findAddressResults
        =  map.FindResults("498 Broad St, Seattle, WA, 98109");
    //Works with finding places
    MapPoint.FindResults findPlaceResults
        =  map.FindResults("Space Needle");

Let’s replace the FindPlaceResults method in our application with the FindResults method call to support both place names and addresses:

    //Call FindResults on the MapClass instance to support both places and
    //addresses
    MapPoint.FindResults findResults = map.FindResults(textBox1.Text);

You know that our application works for both places and addresses and also handles location disambiguation well, but you may be wondering whether you need to create a user interface (UI) to support each method, since each find method’s input formats are so different. You actually don’t need to—for applications like ours, there is a method exposed by the Map class that uses the pre-built MapPoint UI.

The Map class exposes the ShowFindDialog method to show the built-in find dialog, a modal dialog that implements the FindResults and GetLocation methods along with a nice disambiguation process with a great UI. This method returns either a Location or a Pushpin class instance. Don’t worry about the details of the Pushpin class yet; I will discuss this class in detail in the next chapter. For now, consider the Pushpin class to be a graphical mark or shape that represents a location. You can access the Location represented by a Pushpin using the Pushpin.Location property.

The ShowFindDialog method takes the input location as a string. The other parameters include:

The following code shows the implementation of this method for our application:

    //Get a reference to the Map instance via the ActiveMap property
    MapPoint.Map map = app.ActiveMap;

    //Call the ShowFindDialog to show the find (modal) dialog
    object result = map.ShowFindDialog(
                              this.textBox1.Text,
                              MapPoint.GeoFindState.geoFindDefault,
                              (int) this.Handle,
                              false);

    //See whether the result is null
    if(result != null)
    {
        //If the result is a Location type get the
        //Location directly
        if(result is MapPoint.Location)
        {
            currentLocation = result as MapPoint.Location;
        }
        else if(result is MapPoint.Pushpin)
        {
            //If this is a Pushpin type, first get the Pushpin
            MapPoint.Pushpin pushpin = result as MapPoint.Pushpin;
            //Then get the location
            currentLocation = pushpin.Location;
        }
    }
    else
    {
        MessageBox.Show("No locations found. Please verify the input.");
    }

You need to check for the return type after the ShowFindDialog method returns a value. If it is a Pushpin type, access the corresponding Location object via the Pushpin.Location property.

Figure 2-6 shows the MapPoint find dialog shown for the “Space Needle” search.

We know our application works for place names and well-formatted addresses. Since we also know exactly where the Space Needle is, let’s extend our application to do a bit more and find points of interest around the Space Needle.

Points of Interest (POI) are places that may be of some interest; for example, to a tourist in Seattle, the POI could be the Space Needle, among other interesting things to see; for a coffee connoisseur in Seattle, the POI could be a list of coffee shops. If we take the interest out of context, the POI are simply locations. Each location has an interest attributed to it and is identified by the category of the place. These categories are defined as broad groups to fit several types of places into one category; examples of such categories are airports, restaurants, coffee shops, and museums.

Figure 2-6. MapPoint 2004 Find UI dialog

Using MapPoint 2004, you can find the POI around a location (or around a route) within a specific radius or distance. The location class from the MapPoint 2004 object model exposes the FindNearby method to find the POI around a location.

Let’s extend our sample application to find the POI around a location using the FindNearby method. Add a tree view control to add points of interest, a combo box to select distance, and a button to find the POI around a selected location. The new layout is shown in Figure 2-7.

Clicking the Find POI button finds the points of interest around a given location by calling the Location.FindNearby method.

The only parameter that the FindNearby method takes is distance, as type System.Double. The distance must be greater than 0 and less than or equal to 50 miles. The default unit of measurement for distance is miles, but you can change it by setting the appropriate value to the Units property of the ApplicationClass. The Units property is of GeoUnits type, an enumeration containing the values of geoKm and geoMiles. If you want to treat the distances as kilometers, set the Units property to the geoKm value as shown in the following example:

Figure 2-7. Find Place UI Extended for POI

    MapPoint.ApplicationClass app =
              new  MapPoint.ApplicationClass( );
    app.Units = MapPoint.GeoUnits.geoKm;

The following code shows the actual FindNearby call from the location found during the FindPlaceResults search:

    //Call the find nearby on the current location
    MapPoint.FindResults poiResults = location.FindNearby(distance);

The POI search within a one-mile radius around the Space Needle results in 683 POI; the same search with distance unit set to kilometers results in 288 POI. Figure 2-8 shows the POI found within a one-mile radius around the Space Needle.

Figure 2-8. Uncategorized POI around the Space Needle

Going through a list of 683 (or even 288) POI would be annoying, as well as intimidating, so we need a better way of handing the POI to give a better view of the POI search results. This is when the PlaceCategory class comes to our rescue. The place categories are names that can be used to group locations together.

Categorizing points of interest using the PlaceCategory class

The PlaceCategory class encapsulates a category name and is exposed as the PlaceCategory property from the Location class. The Parent property of the PlaceCategory gives access to all categories available in MapPoint 2004; there are 48 predefined categories, such as Pharmacies, Restaurants, Theaters, and so on, available in MapPoint 2004. In order to make the POI list more readable by grouping them into meaningful categories, we need to use the PlaceCategory.Name property, which gives the name of the category that a location belongs to. The following code shows how to group locations into categories:

    //Create an object to hold index value
    object findResultIndex = null;
    //Create a string instance to hold category name
    TreeNode node = null;
    int nodeCount = 0;

    //Create a hashtable to hold category names
    Hashtable categoryNames = new Hashtable( );

    //Start with index 1 instead of 0
    for(int i=1;i<=findResults.Count;i++)
    {
        //Box the integer value as an object
        findResultIndex = i;
        //Pass the index as a reference to the get_Item accessor method
        MapPoint.Location loc = findResults.get_Item(ref findResultIndex) as 
        MapPoint.Location;
        if(loc.PlaceCategory != null)
        {
            object nodeIndex = categoryNames[loc.PlaceCategory.Name];
            if(nodeIndex == null)
            {
                //Create a new category node
                node = new TreeNode(loc.PlaceCategory.Name);
                //Add the current location under this node
                node.Nodes.Add(new TreeNode(loc.Name));
                //Add this node to the tree
                tree.Nodes.Add(node);
                //Store the value in hashtable along with the index number
                categoryNames.Add(loc.PlaceCategory.Name, nodeCount);
                //Increment the node index
                nodeCount ++;
            }
            else
            {
                //Add the current location under this node
                tree.Nodes[Convert.ToInt32(nodeIndex)].Nodes.Add(new TreeNode(loc.Name));
            }
        }
    }

The category name is checked for each POI location; if the category name already exists in the tree view, the current location is added under that category; if that category does not exist in the tree view, a new category node is added before adding the current location. The final application layout is shown in Figure 2-9.

This POI list is easier to navigate than its predecessor in Figure 2-8, but we still have too many unrelated categories. In this case, we can programmatically hide the unwanted place categories.

Figure 2-9. Categorized POI around the Space Needle

    //Create an instance of ApplicationClass
    app = new MapPoint.ApplicationClass( );

    //Define the category that needs to be blocked
    string blockCategory = "Restaurants - Other";

    for(int i = 1; i<app.ActiveMap.PlaceCategories.Count+1; i++)
    {
        object index = i;
        //if the name of the category matches the block list
        //set the visible property to false
        MapPoint.PlaceCategory placeCategory =
        app.ActiveMap.PlaceCategories.get_Item(ref index) as MapPoint.PlaceCategory;
        if(placeCategory.Name == blockCategory)
        {
            placeCategory.Visible = false;
        }
        else
        {
            placeCategory.Visible = true;
        }
    }

    //Create an instance of ApplicationClass
    app = new MapPoint.ApplicationClass( );

    //Define the category that needs to be blocked
    String[] blockCategoryArray = new string[]
                  { "Restaurants - Other", "Museums"};

    for(int i = 1; i<app.ActiveMap.PlaceCategories.Count+1; i++)
    {
        object index = i;
        //if the name of the category matches the block list
        //set the visible property to false
        MapPoint.PlaceCategory placeCategory =
        app.ActiveMap.PlaceCategories.get_Item(ref index) as MapPoint.PlaceCategory;
        if(Array.IndexOf(blockCategoryArray, placeCategory.Name) >= 0)
        {
            placeCategory.Visible = false;
        }
        else
        {
            placeCategory.Visible = true;
        }
    }

The Location class has a DistanceTo method that calculates the distance to a given location. Keep in mind that the distance calculated using this method is not the same as the driving distance; this method only gives you the straight line (“as the crow flies”) distance between the two locations. The DistanceTo method takes another location as an argument; the following code shows how to calculate the distance between two locations:

    //Get the from location
    MapPoint.Location fromLocation
            = this.findResults.get_Item(ref fromIndex) as MapPoint.Location;
    //Get the to location
    MapPoint.Location toLocation
            = poiResults.get_Item(ref poiIndex) as MapPoint.Location;
    //Calculate the distance between the from location and
    //to location using the DistanceTo methoddouble distance = fromLocation.DistanceTo(toLocation);

Figure 2-10 shows the POI list when it’s updated to show the distances from the input location.

Figure 2-10. POI shown with distances

Another way of calculating the distance between two locations is to call the Distance method on an active Map object:

    double distance = app.ActiveMap.Distance(startLocation, endLocation);

Both startLocation and endLocation are MapPoint.Location type objects.

Keep in mind that both these methods calculate the distance based on the units specified at the ApplicationClass level. To change the units of measurement for the distances (between miles and kilometers), use the Units property on the ApplicationClass object.

After displaying the distances in the POI list, it looks much better with all the information needed to decide which points of interest to visit when you are around the Space Needle clearly shown. However, wouldn’t it be helpful if you could actually show the POI on a map? After all, what kind of application would MapPoint 2004 be if it didn’t actually display a map? For this next step, we need the MapPoint 2004 ActiveX control.

The first step towards developing with MapPoint 2004 ActiveX control starts with configuring your development environment. You need to add the ActiveX Control to your Visual Studio .NET toolbox to enable the “Drag-and-Drop” development tool. Create a new tab by selecting the Add Tab option from the toolbox context menu as shown in Figure 2-11.

Figure 2-11. Add Tab context menu

Name the newly created tab MapPoint ActiveX Control and click on it to add the MapPoint 2004 ActiveX Control reference by selecting Add/Remove Items from the context menu, as shown in Figure 2-12.

Figure 2-12. Add/Remove Items context menu

When the Customize Toolbox dialog is displayed, select the COM Components tab and Microsoft MapPoint Control 11.0 as shown in Figure 2-13.

Note that if you have MapPoint 2004 APIs already added to your project, you need to remove that reference before you add ActiveX Control; adding ActiveX Control automatically adds the MapPoint 2004 API reference to your project.

That’s it! Now you are ready to develop applications using the MapPoint 2004 object model.

When you drag-and-drop the MapPoint control onto your Windows form, the reference to the MapPoint interoperable assembly is automatically added to your project, along with the control. The drag-and-drop operation also creates and adds an instance of MapPoint control to your code file:

    private AxMapPoint.AxMappointControl axMappointControl1;

Figure 2-13. The Customize Toolbox dialog

Before you use AxMappointControl, you need to initialize the control by creating new map coverage by calling the NewMap method on the AxMappointControl class. This method takes the map region of type GeoMapRegion enumeration as an argument. There are two valid region values for the map region in MapPoint 2004: GeoMapRegion.geoMapNorthAmerica for North American maps and GeoMapRegion.geoMapEurope for European maps. The following code shows how to initialize the control to show the North American map:

    axMappointControl1.NewMap(MapPoint.GeoMapRegion.geoMapNorthAmerica);

You can also open an existing map file using the OpenMap method to initialize the control. The OpenMap method takes an existing map file path as an argument:

    axMappointControl1.OpenMap("C:MyMap.ptm");

After initializing the map control, you can access the map object via the ActiveMap property:

    MapPoint.Map map = axMappointControl1.ActiveMap;

Using this map object, you can perform all the location-based operations, such as finding places, addresses, and nearby places, as we did earlier in this chapter.

The MapPoint 2004 ActiveX map control provides the same set of toolbars as the MapPoint 2004 application. These toolbars are not visible by default, but you can make them appear or disappear programmatically using the MapPoint 2004 ActiveX control’s Toolbars property, which is a collection of four toolbars:

These toolbars are shown in Figure 2-14.

To access a particular toolbar, use either the index or the name of the toolbar; for example, the following code shows how to show make the Location and Scale toolbar visible using the index:

     //Define toolbar indexes
    object TOOLBAR_STANDARD = 1;
    object TOOLBAR_NAVIGATION = 2;
    object TOOLBAR_DRAWING = 3;
    object TOOLBAR_LOCATIONSCALE = 4;

    //using index
    axMappointControl1.Toolbars.get_Item(ref TOOLBAR_DRAWING).Visible
                                                         = true;
    axMappointControl1.Toolbars.get_Item(ref TOOLBAR_LOCATIONSCALE).Visible
                                                         = true;
    axMappointControl1.Toolbars.get_Item(ref TOOLBAR_NAVIGATION).Visible
                                                         = true;
    axMappointControl1.Toolbars.get_Item(ref TOOLBAR_STANDARD).Visible
                                                         = true;

You get the same effect using the following code, which uses the toolbar’s name:

    object name = "Location and Scale";
    axMappointControl1.Toolbars.get_Item(ref name).Visible = true;

The Standard toolbar allows users to toggle different panes, such as route pane, find nearby pane, and so forth. However, if you want to control these panes in your application, don’t make the entire Standard Toolbar visible in your application—you can control the pane visibility programmatically using the PaneState property of the ActiveX control. The PaneState property is of MapPoint.GeoPaneState type, which is an enumeration. The GeoPaneState enumeration has five values that show no panes, the Legend pane, the Find Nearby Places pane, the Route Planner pane, and the Territory Manager pane, as shown in Table 2-3.

Figure 2-14. MapPoint 2004 MapControl toolbars

For example, to let users find nearby places in your application, you can give them access to that functionality:

    //Make the route planning pane visible
    axMappointControl1.PaneState = MapPoint.GeoPaneState.geoPaneRoutePlanner;

Finally, if you want to control the Route Planner pane that displays the detailed driving directions visibility, use the ItineraryVisible property of the ActiveX Control:

    //Hide itinerary pane
    axMappointControl1.ItineraryVisible = false;

This property is also available from the ApplicationClass instance.

Now that we have a map control ready to use, let’s start off with some basic actions, such as displaying a location on a map and zooming in and out of maps.

In our sample earlier this chapter, we have implemented the find methods to find places, addresses, and nearby locations. In all these cases, a MapPoint.Location instance represents the locations found. To display a location on the map, call the Location object’s GoTo method:

    //Define a location instance
    MapPoint.Location currentLocation = null;

    //Get the current location from FindResults method
    MapPoint.FindResults findResults =
                     map.FindResults("your place input");

    currentLocation = findResults.get_Item(ref index);

    //Go to the current location on the map
    currentLocation.GoTo( );

Calling this method zooms in to the location with the best possible view on the map and centers the map on that location. To highlight the location on a map, use the Location.Select method:

    //Highlight the location on the map
    currentLocation.Select( );

After this implementation, our application looks similar to Figure 2-15.

If there is only one location, you can center the map on it using the Location.GoTo method, but you have to use the Map.Union method to center the map to display multiple locations on it. This method takes an array of locations and returns the center of the map as a Location object for all given locations:

    //Define an ArrayList to hold location objects
    ArrayList locList = new ArrayList( );
    //Add locations to the array list
    for(int i=0;i<findResult.Count;i++)
    {

Figure 2-15. Location display and highlight

       Object index = i+1;
       MapPoint.Location location =
                findResult.get_Item(ref index)
                as MapPoint.Location;

      locList.Add(location)
    }
    //Center the map to show all locations
    MapPoint.Location center = axMappointControl1.ActiveMap.Union(locList.ToArray( ));
    //Now zoom map to the center
    center.GoTo( );

How do you pinpoint the selected location? Is it possible to annotate that location, or better, to highlight it? Pushpins make this process easy.

Pushpins are visual marks on a map that contain either an annotation or data. Each pushpin on a map is associated with a location. A pushpin in MapPoint 2004 is represented by the Pushpin class. The Name property of a Pushpin object can be used to annotate the pushpin. You can also add notes to the pushpin using the Pushpin.Notes property.

A pushpin is represented pictorially by a symbol. MapPoint 2004 provides a number of symbols to be used with pushpins. These symbols are indexed, and their number should be used to indicate the symbol of a given pushpin; for example, the default symbol is the black pushpin, represented by 0. The valid range for the standard symbols is 0-255. You can also add customized pushpins, but the identity must be in the range of 256-32,766.

The location represented by a pushpin can be accessed via the Pushpin.Location property. Let’s look at some code to implement this; to add a pushpin to a predetermined location, call Map.AddPushpin method:

    //Get map center location
    MapPoint.Location location = axMappointControl1.ActiveMap.Location;
    //Add a pushpin at this location
    MapPoint.Pushpin pushpin = axMappointControl1.ActiveMap.AddPushpin(
                                                         location, "Center");
    //Assign a symbol
    pushpin.Symbol = 64;
    //Select and highlight the location
    pushpin.Select( );
    pushpin.Highlight = true;
    //Write annotation
    pushpin.Note = "This is my favorite place!";

This code adds a pushpin to the center of the map. However, the pushpin on the map does not display any information. To display the information associated with the pushpin, such as name, notes, etc., use the Pushpin.BalloonState property. Setting this property displays the pushpin tool tip information. The Pushpin.BalloonState property is of MapPoint.GeoBalloonState type, which is an enumeration. The valid values for this property are:

The following code shows how to display the full details of a given pushpin:

    //Show tooltip (Balloon State)
    pushpin.BalloonState = MapPoint.GeoBalloonState.geoDisplayBalloon;

You can remove a given pushpin by calling the Pushpin.Delete method. The Pushpin class exposes some other methods, such as Copy and Cut, to copy the pushpin to the clipboard.

Now that we know how to display a location on map, select a location, and add a pushpin to it, let’s look at how to interact with the MapPoint 2004 ActiveX Control maps.

The MapPoint 2004 ActiveX Control provides you with a fully interactive map on which to perform actions such as panning , zooming, and tracking mouse clicks. All of this functionality is accessible to both the programmer and the user.

    axMappointControl1.ActiveMap.Pan(MapPoint.GeoPanCmd.geoWest, 1);

    //Specify desired pan distance
    //For example, set to 1 mile in this case
    double desiredDist = 1;
    //Standard Altitude/Distance ratio
    const double ALT2DISTRATIO = 4.88568304395;
    //Calcuate the pan factor
    double panFactor = desiredDist * ALT2DISTRATIO /
                                     axMappointControl1.ActiveMap.Altitude;
    //Now pan the map to west
    axMappointControl1.ActiveMap.Pan(MapPoint.GeoPanCmd.geoWest, panFactor);

    axMappointControl1.ActiveMap.ZoomIn( );

    //Zoom directly into Street Level by setting 3 mile altitude
    axMappointControl1.ActiveMap.Altitude = 3;

    axMappointControl1.BeforeClick +=
                new AxMapPoint._IMappointCtrlEvents_BeforeClickEventHandler(
                                             axMappointControl1_BeforeClick);

    private void axMappointControl1_BeforeClick(object sender,
                               AxMapPoint._IMappointCtrlEvents_BeforeClickEvent e)
    {
        int XCoord = e.x;
        int YCoord = e.y;
        MapPoint.Location location =
                   axMappointControl1.ActiveMap.XYToLocation(XCoord, YCoord);
        if(location != null)
        {
            //Do some processing with location
            . . .
        }
    }

    //Get the center of the map
    MapPoint.Location location = axMappointControl1.ActiveMap.Location;
    //Get x and y coordinates
    int x = axMappointControl1.ActiveMap.LocationToX(location);
    int y = axMappointControl1.ActiveMap.LocationToY(location);
    //Display the center coordinates
    MessageBox.Show(String.Format("Map is centered at ({0}, {1})",
                                           x.ToString( ), y.ToString( )));

    this.axMappointControl1.SelectionChange +=
               new AxMapPoint._IMappointCtrlEvents_SelectionChangeEventHandler(
                                             axMappointControl1_SelectionChange);

    private void axMappointControl1_SelectionChange(object sender,
                         AxMapPoint._IMappointCtrlEvents_SelectionChangeEvent e)
    {
        //Get the previous selection
        MapPoint.Pushpin pPrev = e.pOldSelection as MapPoint.Pushpin;
        //Get the current selection
        MapPoint.Pushpin pCurr = e.pNewSelection as MapPoint.Pushpin;
        if(pPrev != null)
        {
            //Turn off the tool tip
            pPrev.BalloonState = MapPoint.GeoBalloonState.geoDisplayNone;
            //Turn off the highlight
            pPrev.Highlight = false;
        }
        if(pCurr != null)
        {
            //Display the information
            pCurr.BalloonState = MapPoint.GeoBalloonState.geoDisplayBalloon;
            //Highlight the pushpin
            pCurr.Highlight = true;
        }
    }

    //Get the previous selection
    MapPoint.Location lPrev = e.pOldSelection as MapPoint.Location;
    //Get the current selection
    MapPoint.Location lCurr = e.pNewSelection as MapPoint. Location;

There are several ways to save a map from your application. You can save the map as a standard .ptm map that can only be opened using MapPoint 2004 application, or you can save it as a web page (.htm) map that can be opened by any browser.

Saving the map as a .ptm is very straightforward; you can use the SaveMapAs method on the MapPoint 2004 ActiveX Control:

    axMappointControl1.SaveMapAs(@"C:	est.ptm");

To save the map as a web page, use the SavedWebPages property of the Map object. This property is a collection of web pages, and you call the Add method as follows to save a new map as a web page:

    string path = @"C:	est.htm";
                axMappointControl1.ActiveMap.SavedWebPages.Add(
                       path, axMappointControl1.ActiveMap.Location, "My Map",
                       true, true, true, axMappointControl1.ActiveMap.Width,
                       axMappointControl1.ActiveMap.Height, true, true, true, true);

Using the SavedWebPages collection also enables you to manage the saved pages from the MapPoint 2004 application UI using the File → Manage Saved Web Pages menu option.

What is hit-detection in MapPoint 2004, and how do you programmatically implement it? The Map object in MapPoint has the method, ObjectsFromPoint, which allows you to perform a hit-detection around any given point (x and y coordinates) on the screen. You can already get a point from any given location, so what does this method return? As the method name suggests, it returns an array of objects wrapped in a FindResults instance. The type of objects returned by this method depends on the current map altitude. For example, if you call this method at lower altitudes, it returns locations with street addresses; if you go to higher altitudes and call this method, it returns larger geographic areas, such as Zip Code, county, and time zone of the point. The following snippet shows how to call the ObjectsFromPoint method for any given Location:

    //Get Location from latitude and longitude
    MapPoint.Location location =
           app.ActiveMap.GetLocation(mylatitude, mylongitude, altitude);

    /Now use the Map.ObjectsFromPoint method 
 
 
 
 to get points from the
    //above location
    MapPoint.FindResults findresults =
         app.ActiveMap.ObjectsFromPoint(
                app.ActiveMap.LocationToX(location),
                app.ActiveMap.LocationToY(location));

The ObjectsFromPoint method is very versatile and can be used for many purposes, such as querying for address of a given location, determining time zone, querying a territory, and so on. In the following sections, I will show you how to use the ObjectsFromPoint method in a few of these scenarios.

Determining the time zone of any location can be done using the ObjectsFromPoint method. When this method is called at lower altitudes (usually around two to three miles), it returns the time zone as one of the FindResults objects. Using this technique, you can check whether FindResults contains a time zone by looking for the string “GMT” in the name of the each found result:

    string place = "Redmond, WA";
    //Find the location first
    MapPoint.FindResults findResults
        = axMappointControl1.ActiveMap.FindResults(place);
    if(findResults != null && findResults.Count > 0)
     {
      object index = 1;
      MapPoint.Location location =
      findResults.get_Item(ref index) as MapPoint.Location;
      //Zoom into it
      location.GoTo( );
      //Set low altitudes
      axMappointControl1.ActiveMap.Altitude = 2;
     //Now get points from the location
     MapPoint.FindResults points
         = axMappointControl1.ActiveMap.ObjectsFromPoint(
              axMappointControl1.ActiveMap.LocationToX(location),
              axMappointControl1.ActiveMap.LocationToY(location));
     if(points != null && points.Count > 0)
      {
        for(int i=1;i<=points.Count;i++)
        {
         object index2 = i;
         //Get location
         MapPoint.Location loc
          = points.get_Item(ref index2) as MapPoint.Location;
        //Look for GMT in the name of the location
        if(loc.Name.IndexOf("GMT") > 0)
        {
          MessageBox.Show(loc.Name);
          break;
         }
       }
     }

As an example, when this code is executed, the time zone of the New York area is displayed as “Eastern (GMT-5).”

Next, let’s see how we can extend the ObjectsFromPoint method to determine the street address of a location.

One of the limitations of the GetLocation method is that you cannot always get the address for a given set of latitude and longitude. The workaround for this limitation is to use the hit-detection technique around the given latitude and longitude.

There are a few ways to do the hit-detection:

Due to its efficiency and accuracy, I choose to implement the first option, panning around to see whether there is a nearby street. The basic approach to panning around the chosen found location is to move in a general spiral. In this case, the center of the spiral goes to the original location found using the GetLocation method, and I continue increasing the radius until I find a street address. The implementation of this approach is as follows:

    public static MapPoint.Location GetLocationEx(double latitude,
                                    double longitude, ref MapPoint.Application app)
    {
        if(app == null)
            return null;

        //Define the altitude
        double altitude = 3;
        //Flag to indicate that a street address is found
        bool found = false;
        //Original latitude and longitude
        double mylatitude = latitude;
        double mylongitude = longitude;
        //Angle to create a spiral
        double theta = 0;
        //Radius of the spiral
        double radius = 0.00003;
        //flag to indicate the original location
        bool first = true;
        //Define a location to hold end-result
        MapPoint.Location foundLocation = null;

        //Approximately corrects for latitude changing the value of longitude
        double latitudeInRadians = latitude * Math.PI / 180;
        double longMultiplier = 1 / Math.Cos(latitudeInRadians);

        //Get the location using the Map.GetLocation method 
 with the given
        //latitude and longitude
        //The altitude plays an important role in getting the better accurate
        //addresses for given lat longs
        while(!found)
        {
            MapPoint.Location location =
                   app.ActiveMap.GetLocation(mylatitude, mylongitude, altitude);

            if(location == null)
                return null;

            if(first)
            {
                //Zoom map to the original location
                location.GoTo( );
                first = false;
            }


            //Now use the Map.ObjectsFromPoint method to get points from the
            //current map center
            MapPoint.FindResults findresults =
                app.ActiveMap.ObjectsFromPoint(
                            app.ActiveMap.LocationToX(location),
                            app.ActiveMap.LocationToY(location));

            //Select a point that has street address and return that location
            object index = null;
            //Now loop through the results
            for(int i = 0; i<findresults.Count; i++)
            {
                index = i+1;
                MapPoint.Location loc =
                          findresults.get_Item(ref index) as MapPoint.Location;
                //Check for the street names
                if(loc != null && loc.StreetAddress != null)
                {
                    //Found the steet name
                    foundLocation = loc;
                    found = true;
                }
            }

            //Radius increment value; if you want your
            //Street address find to be more accurate, keep this
            //value at either 0.00001 or 0.00002, but keep
            //in mind that lower values may take more time to resolve
            Double accuracy = 0.00004;
            //Increment the radius
            radius = radius + accuracy;
            //Increment the angle
            theta = theta + Math.PI/16;
            //Pan to next latitude, longitude
            mylongitude = longitude + (longMultiplier * (Math.Cos(theta) * radius));
            mylatitude = latitude + Math.Sin(theta) * radius;
        }

        return foundLocation;

    }

An example of how the above algorithm works is shown in Figure 2-16 on a map with blue and red pushpins. The center of the spiral is the original location found for a given latitude and longitude; the pushpin to its right shows the nearest street address found using the spiral method.

You could enhance this algorithm by completing the circle (with no increments to radius) and seeing whether there is more than one intersection between the circle and a street; if there is, the midpoint of that arc would be a closer point to the original location.

Figure 2-16. Finding the nearest street address from a Lat/Long algorithm

The location found using the previously described method can be used to find the nearest street address for a given latitude and longitude. You can find this method in the ProgrammingMapPointUtilities project in the Chapter 02 file included in the companion material.

Finally, if you are using the ShowFindDialog method for finding latitude and longitude, use the GeoFindState.geoFindLatLong as FindState parameter; in this scenario, the method looks for a comma as a delimiter to parse the values correctly. Anything that lies to the left of the delimiter is considered latitude, and the value that lies to the right of the delimiter is considered longitude.

In MapPoint 2004 terms, a route is essentially a collection of locations connected in some way—via street, ferry, or highway. These locations in a route are known as waypoints and are represented using the MapPoint.Waypoint class. A valid route always contains two or more waypoints. Waypoints in a route are represented in the Route.Waypoints collection, so you use the Waypoints collection to add new waypoints:

    //Get ahold of route object
    MapPoint.Route route = axMappointControl1.ActiveMap.ActiveRoute;
    //Add the location to the ActiveRoute
    route.Waypoints.Add(loc, loc.Name);

You can access the waypoints using the same collection and the corresponding index value:

    //Obtain a waypoint from a given route
    object index = 1;
    MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);

You can use the MapPoint.Waypoint object in many ways to specify a new route or modify an existing route. To change the location represented by a Waypoint object, use the Waypoint.Anchor property. This property is of type object because it can be either a Location or a Pushpin. If you are assigning a new location to a waypoint, you can do it like this:

    //Obtain a waypoint from a given route
    object index = 1;
    MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);
    //Assign a new location
    waypoint.Anchor = newlocation;

You may have noticed that a Waypoint object also exposes the Location property, which returns the Location object that it corresponds to; however, keep in mind that this property is a read-only property, and you cannot change the location using it.

Using the Waypoint object’s SegmentPreferences property, you can set the segment preference indicating whether you prefer a shorter route, a quicker route, and so on. This is useful if you have preferences for a segment in a route. This property is of MapPoint.GeoSegmentPreferences type, an enumeration which has the following values:

The default value is always geoSegmentQuickest, and you can set a different value:

    object index = 2;
    MapPoint.Waypoint waypoint = route.Waypoints.get_Item(ref index);
    waypoint.SegmentPreferences = MapPoint.GeoSegmentPreferences.geoSegmentShortest;

There is one last concept that you need to understand about waypoints and SegementPreferences; a waypoint represents only one location, but a route segment represents two locations. So, what happens if you set two different segment preferences for each location in a single segment? The answer is that the waypoint (location) at the beginning of the segment always decides the segment’s route preference.

Waypoints are categorized into three types:

You can access this information for a given Waypoint object using the Type property. This property is of MapPoint.GeoWayPointType enumeration. This property is useful in determining the type of waypoint when analyzing a route or processing driving directions. You can set a Waypoint’s preferred arrival and departure times using the PreferredArrival and PreferredDeparture properties, respectively; MapPoint 2004 uses this information to adjust the itinerary when calculating driving directions. Finally, you can specify a stop time using the StopTime property, which is of Double type and expresses amount of hours as a fraction of a day (24 hours); for example, if you want to stop for 2 hours, you would assign the StopTime:

    waypoint.StopTime = 2/24;

Now that we know how to specify and set waypoints for a route, let’s look at how to optimize a route.

You can optimize a route if it has more than one waypoint as an intermediate stop. This is useful if you want to order waypoints (of Intermediate type stops) so that the total distance driven in a route is minimized. To optimize a route, call the Optimize method on the Waypoints collection:

    //Optimize the route
    route.Waypoints.Optimize( );

Note that the Optimize method does not alter the start and end points; it reorders only the intermediate stops. If you do not have more than three waypoints, calling this method does not effect on the waypoint order.

You can find out whether a Waypoints collection is optimized by using the WayPoints.IsOptimized property. When the Optimize method is called and a route is successfully optimized, the RouteAfterOptimize event is fired; the following code shows how to wire up this event:

    this.axMappointControl1.RouteAfterOptimize
        +=new AxMapPoint._IMappointCtrlEvents_RouteAfterOptimizeEventHandler(
                                axMappointControl1_RouteAfterOptimize);

The following code shows how a simple implementation of this event handler:

    private void axMappointControl1_RouteAfterOptimize(object sender,
        AxMapPoint._IMappointCtrlEvents_RouteAfterOptimizeEvent e)
    {
        //Now display the waypoints in correct order
        MyMethodToDisplayCorrectRouteOrder(e.pRoute);
    }

You can use this event to record or display the new order of the waypoints.

Remember that calling the Optimize method does not calculate driving directions; it only reorders the intermediate stop waypoints. So, in order to get driving directions, you need to calculate the route as a separate step.

You can calculate a route for a given set of waypoints using the Route object’s Calculate method:

    //Calculate the route
    route.Calculate( );

As you can see, this method does not take any parameters. However, when you call it, you need to make sure that you have at least two waypoints added to the Route object; otherwise an exception is thrown. Additionally, it is important to note that this method also throws an exception when two waypoints are not connected by any routable means. When this method is successfully completed, the RouteAfterCalculate event is fired; this event has several functions, including displaying driving directions, storing route cost into a database, and so on. The following code shows how to wire up the RouteAfterCalculate event:

    this.axMappointControl1.RouteAfterCalculate+=
             new AxMapPoint._IMappointCtrlEvents_RouteAfterCalculateEventHandler(
                                           axMappointControl1_RouteAfterCalculate);

This code snippet shows a sample implementation of the event handler method:

    private void axMappointControl1_RouteAfterCalculate(object sender,
            AxMapPoint._IMappointCtrlEvents_RouteAfterCalculateEvent e)
    {
        //Display diriving directions
        DisplayDrivingDirections(e.pRoute);
    }

After calculating driving directions, you can get the detailed instructions from the directions using the Route object’s Directions property:

    foreach(MapPoint.Direction direction in route.Directions)
    {
         . . .
    }

The Directions property is a collection of Direction objects. The Direction class has several properties , including driving instructions, starting time, distance, and so forth. Table 2-4 shows some key properties that are exposed on the Direction class.

Along with these properties, the Direction object also provides the FindNearby method to locate nearby points of interest; since a Direction object connects two locations, FindNearby works as a “find along route” method instead of a finding locations around a specific point. This method is useful in route-planning tasks, such as figuring out where to stop for gas and food along a route.

Personalizing a route is possible with the MapPoint 2004 API using the Route object’s DriverProfile property. This property is an instance of the DriverProfile class and can be used to set a preferred start time, end time, speed, road type, and so on. Table 2-5 shows some key properties of the DriverProfile class.

To set preferred roads for your route, use the set_PreferredRoads method to indicate the road type and preference setting on a scale of zero to one (least preferred to most preferred) as follows:

    //Really hate arterial roads
    route.DriverProfile.set_PreferredRoads(
                            MapPoint.GeoRoadType.geoRoadArterial, 0);
    //Prefer Interstates
    route.DriverProfile.set_PreferredRoads(
                            MapPoint.GeoRoadType.geoRoadInterstate, 1);

Finally, keep in mind that you need to set the driver profile settings before calculating the route.