Getting started with the MapPoint Control

Article
11/16/2006

Microsoft MapPoint 2004 includes an ActiveX control (sometimes called the "MapPoint Control"). This control allows you to embed maps into your Visual Basic applications. These maps can have the full functionality of the MapPoint object model as well as the interaction of the MapPoint user interface behind them.

Note With MapPoint 2004, the MapPoint Control is supported only in Microsoft Visual Basic 6.0 or later. This does not include Visual Basic for Applications (for example, the Visual Basic for Applications included with Microsoft Office). It also does not include Microsoft Internet Explorer. You can use MapPoint as an ActiveDocument in Internet Explorer to achieve the same functionality.

The MapPoint Control

If you have installed MapPoint, then you have installed the ActiveX control. In Visual Basic, you can choose the Components item on the Project menu to add controls to your current project. Choosing Microsoft Mappoint Control 11.0 (as in the following illustration) adds the MapPoint icon to your toolbox.

Components dialog box in Visual Basic

Note Do not also reference the MapPoint 11.0 Object Library in the References dialog box. When you add the MapPoint Control to your toolbox, you automatically have access to the MapPoint type library. The only difference is that objects will have the Control type names, such as MapPointCtl.Map rather than the MapPoint type name MapPoint.Map. Referencing the MapPoint type library in addition to the Control can cause unexpected behavior.

You can now choose the MapPoint icon in your toolbox and draw a map right on your form:

The MapPoint Control icon

In design mode, the MapPoint Control is simply a white box with the MapPoint icon.

Once you have added the Control to your form, you can start coding with it. The first thing that you must do is tell the Control what map to show. You do this by calling either the NewMap or OpenMap methods of the MappointControl object. For example:

  	Sub Form_Load()
	    MappointControl1.NewMap geoMapNorthAmerica
	End Sub

Notes

By default, the Control opens with no map open and with no additional border. If you do not call NewMap or OpenMap, the Control may appear invisible on your form when you first open it. This is expected behavior because the Control does not have a map to display. If you want to see the Control even when there is no map open, you can change its BorderStyle and Appearance properties to change how it is displayed.

You can close the map in the Control with the CloseMap method. If you do this, it will invalidate any sub-objects that you have stored, and you must get them again using the properties of the Control. For example, the following code is invalid:

  	Set MyMap = MappointControl1.ActiveMap
	MappointControl1.CloseMap
	MappointControl1.NewMap geoMapNorthAmerica
	MsgBox MyMap.Name

However, the following code is valid:

  	Set MyMap = MappointControl1.ActiveMap
	MappointControl1.CloseMap
	MappointControl1.NewMap geoMapNorthAmerica
	Set MyMap = MappointControl1.ActiveMap
	MsgBox MyMap.Name

Using the Control is similar to using the standard MapPoint automation. The Control has methods and properties that are analogous to the Application object and provide access to the objects in the MapPoint object model. For example, you can call the ActiveMap property of the MappointControl object to get the current map, just as you would call the ActiveMap property of the Application object in the MapPoint object model. The Map object that is returned and all child objects that you can access are the same type as the ones in the MapPoint object model. For the most part, code that you write, for example, in a MapPoint COM add-in will work in the Control as well.

Note The lifetime of a COM add-in is different when loaded by the MapPoint Control than when loaded by MapPoint. A COM add-in loaded by the MapPoint Control is loaded every time a map is loaded and closed every time a map is closed.

File I/O in the Control

The most noticeable change in behavior of methods and properties in the Control is the way that you load and save files. The methods and properties of the Application and Map objects that load and save MapPoint files (.ptm and .ptt) will not work when running in the Control. You must use the Control's methods for loading and saving maps. These include the NewMap, OpenMap, SaveMap, SaveMapAs, and CloseMap methods, as well as the FullMapName property.

The Control also has a state that is unavailable in MapPoint: having no map open at all. When you load the Control, there is no map open by default, and you must call the NewMap or OpenMap method to show a map. To later return the Control to the state with no map open, you can call the Control's CloseMap method. Note that it is not necessary to call CloseMap between successive calls to the Newmap and OpenMap methods.

It is not necessary, but it is more convenient to use the events on the MappointControl object rather than the ones on the Map object, because they are automatically added to the Control's form.

Using MapPoint North America and MapPoint Europe in the Control

One of the big differences between the MapPoint Control and MapPoint standard automation is that the same Control works with both MapPoint Europe and MapPoint North America (as long as they are both installed on a computer). What this means for you as a developer is that you must specify the type of map you want to open. For example, if you call the Control's NewMap method, you must specify the template or region to use. If you specify the file name of a template, then MapPoint chooses the appropriate region automatically. However, if you do not specify a specific template file, you must specify the region to open (by using the GeoMapRegion constants geoMapNorthAmerica or geoMapEurope). You can also open an existing map file with the OpenMap method, and the Control will automatically load the correct version of MapPoint.

This also makes the Control's Region property more valuable in the case that you have both MapPoint Europe and MapPoint North America installed on a computer. After calling the OpenMap method, you can check the region of the file opened by getting the value of the Region property of the MappointControl object.

The MapPoint user interface and accessibility in the Control

By default, the Control only shows the map, as in the following illustration:

MapPoint Control

You can also show other parts of the MapPoint user interface. You can show a task pane by modifying the Control's PaneState property, or show or hide toolbars through the Control's Toolbars collection, accessible through the Toolbars property. The toolbars and panes show up within the Control's space, making the map smaller, as in the following illustration:

MapPoint Control with toolbars and panes

Showing a task pane or any toolbars means that the Control is no longer a simple control. Most controls (for example buttons or text boxes) are simple controls and consist of a single focus point. More complex controls (such as the Microsoft TreeView control, where you can set the focus to any node of the tree) require additional functionality to provide keyboard accessibility to the different parts of the control. By default, when a control has focus, using TAB, CTRL+TAB, or any other keyboard shortcuts affects your application and not the focus within the control. This means that if you are using TAB to navigate through your application and you get to the MapPoint Control, pressing TAB again will move focus to the next control on your form. This appears to be perfect for a simple map.

However, the MapPoint Control is not a simple control. When you add a task pane or any toolbars, the MapPoint Control is now a complex control that requires additional functionality. CTRL+SHIFT+T is a keyboard shortcut that sets the focus into the MapPoint Control. If the Control has the focus and the user presses CTRL+SHIFT+T, the focus will be set to the MapPoint map. If the user then uses TAB, CTRL+TAB, F6, or any other accessibility keys, the user will be navigating through the MapPoint user interface. If the user presses CTRL+SHIFT+T again, the focus will be moved back to the entire Control, and you will once again be allowed to navigate through the rest of the form.

Note For best results, set the color settings on a computer running an application created with the MapPoint Control at the highest level supported by the monitor. The palette colors may not be correct at the minimum color setting of 256 Colors.

Run-time requirements and distribution of your application

The MapPoint Control requires that MapPoint North America or MapPoint Europe be installed on the computer where it runs. Rather than installing the full version of MapPoint, you may buy run-time licenses for each client computer on which you want to distribute your application. The run-time-only version does not allow the stand-alone MapPoint to run, nor does it allow the Control to run in design-time mode (within Visual Basic). The run-time-only version does allow compiled Visual Basic applications that use the Control to run. As long as you have a run-time license for each client computer, you can install the run-time version with your own application as a single installation.

Create an installation disc for an application created using the MapPoint Control