Since we published a tutorial for GMap.NET: Maps, markers and polygons back in 2013, it’s been viewed many times and GMap.NET remains a very popular .NET component. Over the years, it’s become better and more stable and now that it’s at stable version 1.7, it’s time to update the beginners tutorial to using the GMap.NET […]
This article was posted by Independent Software, a website and database application development company based in Maputo, Mozambique. Our website offers regular write-ups on technical and design issues, ranging from details at code level to 3D Studio Max rendering. Read more about Independent Software's philosophy, or get in touch with Independent Software.
Since we published a tutorial for GMap.NET: Maps, markers and polygons back in 2013, it’s been viewed many times and GMap.NET remains a very popular .NET component. Over the years, it’s become better and more stable and now that it’s at stable version 1.7, it’s time to update the beginners tutorial to using the GMap.NET control to create maps, markers and polygons in your .NET/C# application. In this fresh three-part tutorial, you will learn how to place the GMap.NET control on a form, how to configure it to show a map at the coordinates you want, how to add markers to a map, and how to show polygons.
Getting GMap.NET and setting up
The first step to using GMap it to download it here. This will get you a .zip with DLL files which contain the components you will need. For this tutorial, I have used the latest stable version, which is 1.7 at the time of writing. There is also a hot build, but that may contain some bugs that need ironing out. Once you’ve downloaded GMap.NET, create a fresh Windows Forms project in your Visual Studio. Inside your project, create a subfolder and place the DLLs you downloaded in it (GMap.NET.Core.dll and GMap.NET.WindowsForms.dll).
In order to make your project use the new components, you need to create a reference to the DLL files. To do so, right-click References in the Solution Explorer and select Add Reference. In the dialog that pops up, use Browse to find the DLL files and create the references:
The new references should now show up in the Solution Explorer. Although you are now ready to create instances of the GMap.NET control through code, it’ll be easier to add the GMap.NET control to the Toolbox so that you can drag it onto your forms. That way, Visual Studio will do that instancing work for you. To add GMap.NET to your Toolbox, right-click in your Toolbox and select Choose Items. In the dialog that appears, use Browse to locate the GMap.NET.WindowsForms.dll file (the other DLL is not required). It will appear pre-checked in the list of assemblies.
After you close the dialog, the new control will appear in your toolbox ready to be dragged onto a form:
Creating your first map
Go ahead and drag an instance of the GMap.NET control onto a Windows form. Your fresh Windows Forms application should already have an empty form ready for you. The control will appear showing only a small red cross, but no map. We’ll need to do a bit of coding for a map to actually appear. In the Properties window, you might as well call it gmap rather than the cumbersome GMapControl1 .
With the control selected, you will see that the Properties window offers a set of GMap.NET specific properties apart from the usual control properties. These will allow us to configure the behaviour of our map, but not its contents:
Here is what some of these properties do:
- CanDragMap – If set to true, the user can drag (pan) the map using the right mouse button. You’ll probably want to keep this set to true.
- EmptyTileColor – This is the color GMap will use to draw tiles for which its could not obtain any data from the map provider. This may happen when you’re showing a bit of map at very high zoom levels and it depends on the provider. For instance, Google maps has map tiles at the highest zoom levels for most land areas, but not so much for open sea and the poles.
- MarkersEnabled – If set to true, GMap will show any markers you defined. It’s best to leave this set to true for now, or you might be left wondering where your markers went (this happened to me). The same applies for PolygonsEnabled and RoutesEnabled.
- ShowTileGridLines – If true, GMap.NET will show tile coordinates on the tiles. Not something for a production environment, but it may help with debugging.
- Zoom, MinZoom and MaxZoom – The Zoom level for Google Maps is somewhere between 0 (zoomed out to global level) to 18 (zoomed in to street level). Zoom is the current zoom level (5 would be good for country level), while MinZoom and MaxZoom should be set to 0 and 18 respectively if you want users to be able to zoom in and out fully. Zooming is done with the mouse wheel.
- Bearing – This property will rotate the map by the specified number of degrees to the left.
All this looks very promising, but there isn’t any property that we can use the configure where the map data is coming from, only how it will be shown in the control. It turns out that defining the map source must be done in code. Let’s write our first code by creating an OnLoad event for our form. Do this by selecting the form, finding the Load event in the Properties window and double-clicking it. In the code window, add this:
gmap.MapProvider = GMap.NET.MapProviders.BingMapProvider.Instance;
GMap.NET.GMaps.Instance.Mode = GMap.NET.AccessMode.ServerOnly;
Also, in the Properties window for the GMap.NET control, set MinZoom = 2, MaxZoom = 18 and Zoom = 13. Zoom is originally set to 0, which will cause map providers to send you errors because there is not data for that zoom level. Run your project and see this:
Let’s take the code apart. There are three things that we must do to get a map to show in the GMap.NET control:
- Configure a map provider: Set the MapProvider property to an instance of any of the map providers supported by GMap. We’ve used Bing, but we’ll look at alternatives shortly.
- Set the GMap working mode to use only server data: GMap can fetch data from a server, from both a server and the local cache, or the local cache only. In this example, we prefer to always fetch data from the server, so we set the Mode property to GMap.NET.AccessMode.ServerOnly . Note that this applies to all instances of the GMap control that you create in your application, and you only need to set this value once.
- Center the map: Use the SetPositionByKeywords method to center your map where you want it.
There are two things to note regarding centering the map. First, in older versions of GMap.NET the required method was called SetCurrentPositionByKeywords, so be careful if you’re using an previous version. Second, you won’t always have keywords to center your map with, especially if you’re showing a region where there are few points of reference. Therefore, you can also center your map by writing a coordinate straight to the control’s Position property:
gmap.Position = new GMap.NET.PointLatLng(48.8589507, 2.2775175);
This will, once again, center your map on Paris, France. While running the program, you will notice that the map can be dragged with the right mouse button, and zooming is done with the mouse wheel. If these operations do not work, then check that you’ve set the GMap.NET control’s properties correctly in the Properties panel – you may have inadvertently turned off dragging, or fixed the zooming level.
Getting rid of the little red cross in the middle of the map
By default, the GMap.NET control shows a little red cross on the map to show you exactly where the center is. This may not be what you want (I always want to get rid of it, anyway). There is no way to hide this red cross through the properties in the Properties window, but you can set the relevant property in code:
gmap.ShowCenter = false;
… and it’s gone.
In the example above, we’ve configured GMap.NET to obtain all its data from the Bing map provider. But the magic of GMap.NET is that we can use any one of a whole bunch of map providers. Here is a short list of the most interesting ones:
Some map providers come have street, satellite and hybrid variants. Interestingly, the Google Map provider is (for me, at least), the slowest one. The applications takes a good number of seconds to start, presumably because a connection with Google is being (slowly) made. The Bing Map provider was much faster. But, of course, the data shown will be different so it all depends on your preferences. At the very least, your map code could have fallback providers. Here’s what the maps look like with different providers:
Google Map Provider
Bing Map Provider
WikiMapia Map Provider
Yandex Map Provider
All of these providers provide different APIs, and that’s where GMap.NET really shines. Whatever provider you choose, GMap provides you with a common interface you can use to setup the map and add markers, polygons, and routes. This means that when you switch to a new provider, you don’t need to change any of your code. In fact, you could just build an option into your software that allows the user to select a preferred provider!
Read on for more on using GMap.NET.