Show All

Article
09/10/2006

Show All

Getting started using the MapPoint Control

Microsoft MapPoint 2006 includes a Microsoft ActiveX control (sometimes called the "MapPoint Control"). This control enables you to embed maps into your Microsoft Visual Basic applications. These maps can have the full functionality of the MapPoint object model in addition to the MapPoint user interface.

Note In MapPoint 2006, the MapPoint Control is supported only in Visual Basic 6.0. Consequently, the MapPoint Control is not supported in Visual Basic for Applications (for example, the Visual Basic for Applications included with Microsoft Office). It also does not include 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 and are ready to use it in your applications.

Referencing the MapPoint Control

Visual Basic 6.0

In Visual Basic, you can choose the Components item on the Project menu to add controls to your current project. Choosing Microsoft Mappoint Control 13.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 13.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.

Visual Studio .NET 2003

On the Tools menu, select Add/Remove Toolbox Items.
In the Customize Toolbox dialog, select the COM Components tab.
In the list of components, select Microsoft MapPoint Control 13.0. Be sure to select the check box to the left of this component.
Click OK. The component has been added to your toolbox and can be used in a project.

Visual Studio 2005

On the Tools menu, select Choose Toolbox Items.
In the Customize Toolbox dialog, select the COM Components tab.
In the list of components, select Microsoft MapPoint Control 13.0. Be sure to select the check box to the left of this component.
Click OK. The component has been added to your toolbox and can be used in a project.

Using the MapPoint Control

You can now choose the MapPoint icon in your toolbox and draw a map right on your form, as shown in the following illustration:

The MapPoint Control icon

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

After you have added the Control to your form, you can start coding with it. The first step is configuring the Control with the map you want to show. You do this by calling either the NewMap or OpenMap methods of the MappointControl object.

  [Visual Basic 6.0]

Sub Form_Load()
  MappointControl1.NewMap geoMapNorthAmerica
End Sub


[C#]

//Assume the MappointControl on your form is named "MPC"
private void Form1_Load(object sender, System.EventArgs e)
{
  MapPoint.Map objMap = null;

  //Use the default North American Map
  objMap = MPC.NewMap(MapPoint.GeoMapRegion.geoMapNorthAmerica);
}

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 Component Object Model (COM) add-in will work in the Control also.

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 display 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 those 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 your 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.

The Control's Region property becomes more valuable when you have both MapPoint Europe and MapPoint North America installed on your 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

When you show a task pane or any toolbars, 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 TreeView control, where you can set the focus to any node of the tree) require additional functionality to provide keyboard access 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. Therefore, if you are using TAB to navigate through your application and you get to the MapPoint Control, pressing TAB again moves the focus to the next control on your form. This situation 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 moves 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 navigates through the MapPoint user interface. If the user presses CTRL+SHIFT+T again, the focus will be moved back to the entire Control, and the user can once again 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 or that each computer has an embedded license through the Independent Software Vendor (ISV) Royalty Licensing program.

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