Getting started with the MapPoint object model

Article
11/16/2006

There are several ways that you can automate Microsoft MapPoint:

Create a COM add-in to extend the functionality of MapPoint

Use the new ActiveX control (called "MapPoint Control") to embed a MapPoint map into your own Microsoft Visual Basic application

Use Microsoft Visual Basic for Applications in other applications (such as Microsoft Word or Microsoft Excel) to automate MapPoint along with the other application

Use Visual Basic (or any other COM-compliant programming language) to create a .exe or .dll that automates MapPoint

To get started using the application in Visual Basic or Visual Basic for Applications, whether you are creating a macro or writing a full application that automates Microsoft MapPoint, you need to connect to the MapPoint Application object. If you are using the new MapPoint ActiveX Control, you are automatically connected to MapPoint and you use the MappointControl object rather than the Application object to access the rest of the MapPoint object model. Otherwise, you can connect to the Application object using one of several Visual Basic functions: CreateObject, New, or GetObject. Each of these is discussed here.

Note For the purposes of this discussion, Visual Basic and Visual Basic for Applications work the same way, with explicit differences called out.

Using the Visual Basic New keyword

You can use the New keyword with the MapPoint Application object (you can also use it with the MapPointUtilities object). To use New, you must reference the MapPoint type library first (by clicking References on the Project menu in Visual Basic, or by clicking References on the Tools menu in Visual Basic for Applications). Using New creates a new instance of MapPoint and gives you a reference to the object for which you ask. The following example shows how you can use New in code:

Dim MPApp As MapPoint.Application
Set MPApp = New MapPoint.Application

Note You can also combine these into a single line of code, such as:

  	Dim MPApp As New MapPoint.Application

When you create a new application in this way, MapPoint will be running but will not be visible. It is still usable and able to be automated, but if you want it to be visible, you need to explicitly make it visible. If you want MapPoint to continue running until the user closes it, then you should also set the UserControl property to True. The following code is essentially the equivalent of choosing MapPoint from the Start menu:

  	Dim MPApp As New MapPoint.Application
	MPApp.Visible = True
	MPApp.UserControl = True

The New keyword will always create the version of the Application object that you specifically referenced. This means that if you have both MapPoint North America and MapPoint Europe installed on a computer and you reference the North America version, New will always create the North America version. To create a different version of the Application object than the one you have referenced, you must use the Visual Basic CreateObject method. This is important because although you cannot reference both versions of MapPoint in the same Visual Basic project, you can automate both from the same project.

Notes

You can also create the Map object by using the New keyword, but it is preferable to instead create the Application object, and then use the NewMap or OpenMap methods, or the ActiveMap property to create or connect to the Map object.

The New keyword cannot be used within the MapPoint Control.

Using the Visual Basic CreateObject method

You can also use the CreateObject method to create a new instance of MapPoint. It works in a similar way to New but does not require that you reference MapPoint. It is a good idea, however, to reference MapPoint because you get type-checking and Microsoft IntelliSense technology, as well as performance benefits. For example:

  	Dim MPApp As Object 'Or MapPoint.Application, if referenced
	Set MPApp = CreateObject("MapPoint.Application")

In this case, the most recently used MapPoint (North America or Europe) will be created, and you will have a reference to the Application object. If you have only a single MapPoint installed on the computer, then CreateObject and New are identical.

Note Technically, the New keyword creates the object based on the ClassID, or GUID, for the Application object in the type library that you registered. CreateObject looks up the ProgID that you give it in the registry and finds the ClassID based on the registry setting. For more information on CreateObject and New, see the Visual Basic online Help or the Microsoft Developer Network (MSDN) Library.

CreateObject is even more versatile, however. Using it, you can specify the version of MapPoint that you create by changing the ProgID that you pass into it. The following code creates one instance of MapPoint Europe and one of MapPoint North America (assuming that you have both installed on your computer):

  	Dim MPAppNA As MapPoint.Application
	Dim MPAppEur As MapPoint.Application
	Set MPAppNA = CreateObject("MapPoint.Application.NA")
	Set MPAppEur = CreateObject("MapPoint.Application.EU")

If you have multiple releases of MapPoint installed on your computer, you can also specify the release that you want to create. The following example creates an instance of MapPoint North America 2004:

  	Dim MPApp As MapPoint.Application
	Set MPApp = CreateObject("MapPoint.Application.NA.11")

Note MapPoint 2004 is version 11 of MapPoint.

With all these choices, there are several ProgIDs that you can use to create a MapPoint Application object:

Object	ProgID	Opens this
Application	MapPoint.Application	Most recently run version of MapPoint
	MapPoint.Application.11	Most recently run version of MapPoint 2004 (MapPoint North America or MapPoint Europe, if both are installed)
	MapPoint.Application.NA	MapPoint North America
	MapPoint.Application.NA.11	MapPoint North America 2004
	MapPoint.Application.EU	MapPoint Europe
	MapPoint.Application.EU.11	MapPoint Europe 2004

Note You can also create the Map object by using the CreateObject method, but it is preferable to instead create the Application object, and then use the NewMap or OpenMap methods, or the ActiveMap property to create or connect to the Map object.

Using the Visual Basic GetObject method

New and CreateObject create new instances of MapPoint that you can automate. This is useful, but a common scenario is to automate an already-running instance of MapPoint. In this case, use the GetObject method instead. GetObject works in a similar way as CreateObject. The following code gets an already-running instance of MapPoint and connects to it using GetObject:

  	Dim MPApp As MapPoint.Application
	Set MPApp = GetObject(,"MapPoint.Application")

If there is more than a single instance of MapPoint already running, the GetObject method returns the first one that it finds.

Notes

The GetObject method works only with MapPoint 2004.

For more information on GetObject, see the Visual Basic online Help or the MSDN Library.

You can also create the Map object by using the GetObject method, but it is preferable to instead create the Application object, and then use the NewMap or OpenMap methods, or the ActiveMap property to create or connect to the Map object.

Using the MapPoint object model

Once you are connected to the Application object, you can use its properties and methods to access the rest of MapPoint. For example, you can access the current map by using the ActiveMap property of the Application object.

Cleaning up MapPoint when you have finished

If you are automating an existing MapPoint instance, or if you set the Visible and UserControl properties to True, then all you need to do to clean up MapPoint is end your program, or, explicitly, set the MapPoint objects that you are using to Nothing.

If you have set the UserControl or Visible property to False (which is the default for both when a new MapPoint instance is created programmatically), then you should clean up MapPoint after you have finished.

To save changes that you have made to the map, call the Save or SaveAs method on the Map object. If you do not want to save changes, and you do not want MapPoint to automatically prompt to save changes, set the Saved property of the Map object to True. This tells MapPoint that you want to treat the map as saved even though it has not been. If further changes are made to the map after setting this property, however, the property will be reset to False.

Finally, after dealing with changes that need to be saved to the map, you can call the Quit method on the Application object to explicitly end the MapPoint session.

The following code is a common way of ending MapPoint if you do not want to save changes to the current map:

  	MPApp.ActiveMap.Saved = True
	MPApp.Quit
	Set MPApp = Nothing

If there have been any changes to the map and you call the Quit method without first saving the map or setting the Saved property to True, MapPoint will prompt the user to save the changes (just as if you had clicked Exit on the File menu).