Show All

Article
09/10/2006

Show All

Getting started using the MapPoint object model

There are several ways that you can automate Microsoft MapPoint. You can:

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

Use the Microsoft 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 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 by using the New keyword, the CreateObject method, or the GetObject method. 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 the New keyword.

  	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. Creating a different version 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 create the Application object instead, 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 in addition to performance benefits. The following code example illustrates how to create a new instance of a MapPoint object.

  	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 about the CreateObject method and the New keyword, see the Visual Basic online Help or the MSDN Library.

CreateObject is even more versatile, however. By 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")

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

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

Note You can also create the Map object by using the CreateObject method, but it is preferable to create the Application object instead, 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

The New keyword and CreateObject method create new instances of MapPoint that you can automate. Although creating a new object is useful, a common scenario is to automate an already-running instance of MapPoint. In this case, use the GetObject method instead. GetObject works in the same way as CreateObject. The following code example gets an already-running instance of MapPoint and connects to it by 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 2002 and later.

For more information about 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 create the Application object instead, 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

After 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 properties 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 using the object.

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. By setting it to True, you instruct MapPoint 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 example is a common way of closing 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).