ARTICLES

A Simple Add-in for MapPoint API Beginners

Richard Marsden's latest article shows step by step how to create a MapPoint COM Add-in using Visual Basic to draw circles around pushpins. Includes complete source code and screenshots.

This "How To" article was prompted by AgDawg’s post on the MapPoint forums ( Drawing Multiple Radius Circles ). It is intended to show how to create a simple add-in that uses Visual Basic 6 (VB6) – a part of Visual Studio 6. It also demonstrates pushpin processing and simple shape drawing. Namely, it draws circles of 30 miles radius around every pushpin in the ‘My Pushpins’ pushpin set.

VB6 might seem an odd choice for 2008. It is old. It is creaky. Microsoft has recently withdrawn their support. Despite this, much of the MapPoint programming documentation still uses it. It is also easy to use with MapPoint’s COM interface. C# might be a much nicer language with wonderful .NET bells and whistles, but writing a MapPoint add-in using C# is always much more work than it should be. So although serious developers should probably look at C++ or C#, VB6 is a great entry point to learning MapPoint’s API and object model. It is also cheap – Visual Studio is sufficiently out of date that sealed unopened copies are no longer in demand.

Anyway, let’s get started!

Start Visual Basic 6 and in the New/Open project wizard, select the New tab and the Addin icon:

By default, VB6 will save your project in the main "VB98" directory. This is a very bad place, and will probably cause an error on Vista. It is recommended that you save your project to a better location immediately - before you modify your project. It is recommended that you save the add-in to a new directory in your My Documents directory.

After saving your project, go to the Project menu and select References. This will display the following dialog box:

Scroll down to "Microsoft MapPoint Object Library", check the check box and press OK. The exact name will vary according to the version used. In this example, "13.0" refers to MapPoint 2006.

Set the name of the project using the Project Properties dialog box (select Properties on the Project menu):

A project browser should be visible on the right. Select the Connect.Dsr file that is listed under Designers. Use this to set the name, and to tell VB6 that the Addin will be for MapPoint:

VB6 has also added an empty form. We do not need this dialog box. Select it in the project browser, press the delete key.

If you right click on the Connect.Dsr file, you can see the VB6 code that has been automatically created for you. This should connect MapPoint to your add-in.

Unfortunately VB6 assumed you were writing an add-in for Visual Studio, so we need to make some changes. It is considered good programming practice to separate code into logical chunks, so we shall create a separate module to do the actual circle drawing. Here is the modified connection code:

DrawCircles() is a new subroutine which we need to write. This is the ‘guts’ of the add-in and will go in the new module. Create a new module by right clicking on the project name in the project browser, and select Add followed by Module from the menus. Name the module MapCode and save it.

The DrawCircles subroutine definition and initialization are as follows:

As with the connection method, all errors result in a dialog box and stop processing. We also define a few MapPoint reference variables which we shall be using. These are all reset to nothing at the end. This is good practice with all MapPoint programming. The system is clever and de-allocates memory when there are no longer any references to it. Unfortunately the removal of these references is complicated by COM, and we have to explicitly clear all references that we use. If we do not, then some of these objects might appear to be in use when MapPoint comes to close. MapPoint will not remove the objects, and so it will remain in memory as a ‘zombie’.

MapPoint treats pushpin sets as simply a special kind of dataset. We want to work with the ‘My Pushpins’ pushpin set. Here we do this by looping over all datasets. Note that we could easily change this to work with all pushpin sets, or specific combinations.

Yes it is that simple - one loop that goes over all datasets, and then a couple of if statements to find the pushpin set with a specific name. Note that we exit when we have found (and processed) the required pushpin set.

Records and pushpins in a dataset are processed through a query. We can query on, for example, all pushpins within a shape. We want all pushpins, so we use the QueryAllRecords method. This returns a RecordSet object. We simply loop over this to find each pushpin. Note that some pushpin records may not have been located – e.g. the data import wizard could not locate them. We need to filter these out, otherwise we shall get errors.

Again we have a simple loop. This time we loop over all data records, finding valid pushpins. To finish the add-in, all we need is the pushpin processing code. We need to fetch the pushpin’s location and then use it to create a shape – a 30mile diameter circle. This is as follows:

The final MapCode module looks like this:

Visual Basic will automatically install this add-in when you build it. To distribute it, you will need to distribute the resulting DLL library. This then has to be manually added to MapPoint using the COM Add-Ins... entry on the Tools menu. You may also have to distribute some of the VB6 DLLs, although these will already have been installed on many PCs. See your VB6 documentation as to which DLLs you need to distribute - they will depend on which facilities you intend to use.

Previous to Winwaed, Richard has worked as a software developer in the seismic exploration business.

Richard holds geology and geophysics degrees from the University of Cambridge (Churchill College), and the University of Durham.

	MP2Kmag Internet