Download Sample Code From This Exercise

Welcome to Map Suite™ from ThinkGeo, a full featured mapping control that makes it easy for any Microsoft .NET developer to add mapping functionality to a Microsoft .NET application quickly and efficiently. Using the intuitive object model, even developers inexperienced in Geographic Information Systems (GIS) can have fully functional maps working in minutes.

The purpose of this guide is to help you get started quickly to building your own spatially aware applications. Like any new software, there is some learning to be done.

How do we start to learn how to take advantage of the power of Map Suite? The best way is to make a sample application with it.

(For the purposes of this guide, let's assume we have installed the Map Suite Desktop Edition 4.0 to the default folder "C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\")

Setting up the Environment

Let's start with a new Windows Forms project in the Visual Studio.NET 2008 IDE and call it HelloWorld (see Figure 1). We can create the project with .NET Framework 3.5, 3.0 or 2.0.

Figure 1. Creating a new project in the Visual Studio.NET 2008 IDE.

The project HelloWorld is created in a new solution called HelloWorld. The wizard creates a single Windows Form.

Next we need to put a Map control on the Form from our Toolbox. The Map control is located on the Toolbox under Windows Forms (see Figure 2). If you do not see these controls, you will need to add them to your Toolbox manually.

Adding the Map Controls to the Visual Studio.NET IDE Toolbar

1. When you first open the Visual Studio.NET IDE after installing Map Suite, you may not see the controls in the Toolbox. You will need to follow these steps to add the controls.

Hover on Toolbox and right click anywhere on list of controls. You will get a pop-up menu. Choose "Choose Items...".

2. A dialogue box to Choose Toolbox Items will appear. You will need to select the .NET Framework Components tab and then click the Browse button. Finally navigate to the "C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Developer Reference\DesktopEdition" folder and select the DesktopEdition.dll.

3. You should now have the Map Control available in your Toolbox as shown in Figure 2 below.

Figure 2. The Map Controls under the Toolbox window.

Adding the Map Control to your Windows Form

We need to add MapSuiteCore.dll to the reference. Right-click the project in solution explorer and select "Add Reference...", navigate to the "C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Developer Reference\DesktopEdition" folder and select MapSuiteCore.dll.

Draw the Map control on the form by clicking on the Map Control object in the Toolbox and then dragging and dropping (using the left mouse button) to the size you desire. You can leave the name of the Map control to winformsMap1. Our map will display in it.

Now that we have our MapSuiteCore.dll referenced and a Map Control added. We are ready for adding the code.

Map Suite Desktop "Hello World" Sample

After this section, you will be able to draw a map with the MapControl using your own data. At the very beginning, let's have a look at the data and the important objects we will use.

Shapefiles

Map Suite Desktop Edition 4.0 supports multiple kinds of data sources, such as SQL Server 2008, Postgre, Oracle, etc. Here we will provide an introduction to Shapefiles which we will use in this Quick Start Guide.

Simply put, Shapefiles are used by Map Suite to provide data that we will use to draw our map. Shapefiles store binary vector coordinates to be used by the component. They have a .shp extension. Shapefiles also come with two supplementary files that help Map Suite to work with the data.

The first supplementary file is called the .shx file. Its purpose is to provide a simple index of the main Shapefile. It tells the Map Suite component when to start reading binary data and when to stop. It is much like a directory for reading the binary data, sort of a lookup mechanism.

The second supplementary file is the .dbf file. This file holds tabular data associated with the main Shapefile. For example, the Shapefile may have the coordinates for a line to be drawn that represents a road. The .dbf file may have information to tell you what the name of the road is or what type of road it is, such as county road, state road, interstate highway, etc.

All three files need to reside in the same directory as the main Shapefile (.shp), but the Map Suite component only expects you to designate the name and file path of the main Shapefile. Next, when we discuss layer, you will start understanding a little more about how maps are constructed in Map Suite using the shape data.

ShapeFileFeatureLayers

A ShapeFileFeatureLayer in a map correlates to a single Shapefile, such as networks of roads. You can think of layers much like actual terrain in the real world. The bare earth might be a layer and has either physically defined boundaries, such as a fence around a military installation, or legal boundaries, such as the border of a country. Another layer on top of that might be roads that are built upon the bare earth. It is important to understand this when working with layers, as they need to be added in the logical order you might expect so that they can be visualized correctly from above. In other words, you would not want to lay down roads and then cover them with earth, because they could not be seen or used by vehicles.

How do we create and add layers? First, you should know that there are three types of styles that layers represent. As mentioned above, it follows logically that you would create and add layers based on how they should be viewed, so naturally you might start with some polygons, such as the outline of a country and all of the regions within it. You might then lay down lines that represent rivers and roads and then finally you might lay down points like cities or places of interest. Again, keep in mind that logic will dictate what works best. For instance, laying down roads and then rivers would put rivers on top of roads when it should more than likely be the other way around (the exception here might be a tunnel!).

Map

A Map object is the highest level object that encompasses layers and some other objects. For now, you can think of a Map as a set of layers, which can render each layer and present you with a map based on actions performed, such as moving in and out, or panning across the surface to view another part of the map.

Styles

Shapefiles provide the data, but Styles are the way you color and draw them. You can specify the color of the country, the width of a road, the shape (triangle, circle, cross etc) of a point, and so on.

Map Suite has many preset Styles built in, including predefined Styles for roads, rivers, cities, countries, and more. This makes it easier to create great looking maps without a lot of hassle.

PresetZoomLevels

Styles define the way we visually represent the data, while ZoomLevels define the situation in which we want to display them. The reason why we need ZoomLevels is because we may want to display a small town when we are zoomed into a state, but we definitely don't want to display that town when we are zoomed out and looking at the entire country.

We have provided the 20 most common scales, from ZoomLevel01 to ZoomLevel20, at which you may want to change the way your data looks. What is scale? Scale indicates how much the given area has been reduced. If a road is 10,000 inches long in the real world and a map depicts this length as 1 inch on the screen, then we say the scale of this map is 1:10,000. Now let's say ZoomLevel02 uses a scale of 1:500 and ZoomLevel03 uses a scale of 1:1200. This means the map with a current scale of 1:1000 matches ZoomLevel03, the ZoomLevel whose scale is the closest to that.

PresetZoomLevels has a very useful property called "ZoomLevel.ApplyUntilZoomLevel", which you can very easily use to extend your ZoomLevels. Let's say you want a particular Style to be visible at ZoomLevel03 through ZoomLevel10. To make that work, we can simply code as follows:

worldLayer.ZoomLevelSet.ZoomLevel03.DefaultAreaStyle = AreaStyles.Country1; 
worldLayer.ZoomLevelSet.ZoomLevel03.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level10;

Map Suite Desktop "Hello World"

In creating our "Hello World" sample application, our first step is to set references to the Map Suite Core and Map Suite DesktopEdition workspaces at the very top of our code, as we will use many classes within that. We do this so that we do not have to use the fully qualified name of the Map Suite classes throughout our code. Setting a reference to the Map Suite workspace can be done in the "code-behind" of the Form by selecting the Form and hitting the F7 function key. Set the reference like this:

using ThinkGeo.MapSuite.Core;
using ThinkGeo.MapSuite.DesktopEdition;

Now let's look at a code sample to bring this concept to fruition. We'll look at Shapefiles relating to the entire world. In our example, we have one such Shapefile:

• The borders of every country in the world (Countries02.shp)

(NOTE: The data used in this sample can be found in the installation folder under \Samples\SampleData\Data. Figure 3 shows that folder)

Figure 3. The data used in this sample.

Our next step is to define and add our Layers. Here is the code to use for our example. All of the following code can be placed in the Form1_Load event of the form.

private void Form1_Load(object sender, EventArgs e)
    {
        // Set the Map Unit. The reason for setting it to DecimalDegrees is that is what the shapefile’s unit of measure is inherently in.
        winformsMap1.MapUnit = GeographyUnit.DecimalDegree;
        
        // We create a new Layer and pass the path to a Shapefile into its constructor. 
        ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\Countries02.shp");
        
        // Set the worldLayer with a preset Style, as AreaStyles.Country1 has YellowGreen background and black border, our worldLayer will have the same render style.  
        worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
        
        // This setting will apply from ZoonLevel01 to ZoomLevel20, that means we can see the world the same style with ZoomLevel01 all the time no matter how far we zoom out/in. 
        worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        // Create a new Layer Overlay to hold the layer we just created
        LayerOverlay layerOverlay = new LayerOverlay();
        
        // Add the shapefile layer to the layer overlay
        layerOverlay.Layers.Add(worldLayer);
        
        // We need to add the layer overlay to Map.
        winformsMap1.Overlays.Add(layerOverlay);
        
        // Set a proper extent for the Map.  
        winformsMap1.CurrentExtent = new RectangleShape(0, 78, 30, 26);
        
        // We now need to call the Refresh() method of the Map control so that the Map can redraw based on the data that has been provided.
        winformsMap1.Refresh();
    }

If you compile and run what you have now, your map should look like the one below. (see Figure 4).

Figure 4. A Simple map of Europe.

So what has occurred here? We have created a layer and added it to the Map, and the Map has rendered it according to its default style parameters. Also, we have used ZoomLevel to display the map the way we want.

NOTE: It is important that the MapUnit property of a Map object be set using the GeographyUnit Enumeration. This is because Shapefiles only store binary vector coordinates, which can be in DecimalDegree, feet, meters, etc., and our map has no idea about what the unit of measurement is until we set it. This information is normally found somewhere in the documentation or within the supplemental data file as discussed in the section on Shapefiles.

Navigate the Map

With the above code, not only can you display a map, but you can also navigate it. You can pan by dragging the map, zoom in by double-clicking, track zoom in by drawing a rectangle with your left mouse button mouse while holding the shift key, or zoom in and out by using the mouse wheel. Very powerful for just couple lines of code, isn't it?

That was an easy start! Now, let's add another Shapefile to the sample so that we will have a total of two layers:

1. The borders of every country in the world (Countries02.shp)
2. The capitals of the world countries (WorldCapitals.shp)

private void Form1_Load(object sender, EventArgs e)
    {
        winformsMap1.MapUnit = GeographyUnit.DecimalDegree;
        
        ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\Countries02.shp");
        worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
        worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\WorldCapitals.shp");
        // Similarly, we use the presetPointStyle for cities.     
        capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.Capital3;
        // This setting also applies from ZoonLevel01 to ZoomLevel20, that means we can see city symbols the same style with ZoomLevel01 all the time. 
        capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        LayerOverlay layerOverlay = new LayerOverlay();
        layerOverlay.Layers.Add(worldLayer);
        // We need to add both of the new layers to the Layer OverLay. 
        layerOverlay.Layers.Add(capitalLayer);
        
        winformsMap1.Overlays.Add(layerOverlay);
        winformsMap1.CurrentExtent = new RectangleShape(0, 78, 30, 26);
        
        winformsMap1.Refresh();
    }

And the result is as following (Figure 5):

Figure 5. Europe map with 2 layers.

How to Use GeoTextStyle

TextStyle

TextStyle are used to label items on map. As every Shapefile has a relative .dbf file, which includes descriptions for every record, the most common way to use TextStyles is for labeling. For example, WorldCapital Shapefile's corresponding .dbf file contains the field "CITY_NAME". We can use this field to label the cities on our map.

Map Suite has many TextStyles built in, which will help us quickly design attractive labels for the cities on our map. We can just pick the TextStyle we like and use it.

private void Form1_Load(object sender, EventArgs e)
    {
        winformsMap1.MapUnit = GeographyUnit.DecimalDegree;
        
        ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\Countries02.shp");
        worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
        worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\WorldCapitals.shp");
        // Similarly, we use the presetPointStyle for cities. 
        capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.Capital3;
        // This setting also applies from ZoonLevel01 to ZoomLevel20, that means we can see city symbols the same style with ZoomLevel01 all the time. 
        capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        // We create a new Layer for labeling the capitals.
        ShapeFileFeatureLayer capitalLabelLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\WorldCapitals.shp");
        // We use the preset TextStyle. Here we passed in the “CITY_NAME”, which is the name of the field we want to label on map.
        capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.Capital3("CITY_NAME");
        capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        // As the map is drawn by tiles, it needs to draw on the margin to make sure the text is complete after we joining the tiles together.
        // Change the number to another one (for example 0) and you can see the difference expecially when panning.
        capitalLabelLayer.DrawingMarginPercentage = 50;
        
        LayerOverlay layerOverlay = new LayerOverlay();
        layerOverlay.Layers.Add(worldLayer);
        layerOverlay.Layers.Add(capitalLayer);
        layerOverlay.Layers.Add(capitalLabelLayer);
        
        winformsMap1.Overlays.Add(layerOverlay);
        winformsMap1.CurrentExtent = new RectangleShape(0, 78, 30, 26);
        
        winformsMap1.BackgroundOverlay.BackgroundBrush = new GeoSolidBrush(GeoColor.GeographicColors.ShallowOcean);
        winformsMap1.Refresh();
    }

The result is as following (Figure 6):

Figure 6. Europe map with TextStyle.

Now that we know how to render text and render symbols, let's define two different ZoomLevels in one single layer, and create our own custom Style and TextStyle.

private void Form1_Load(object sender, EventArgs e)
    {
        winformsMap1.MapUnit = GeographyUnit.DecimalDegree;
        
        ShapeFileFeatureLayer worldLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\Countries02.shp");
        worldLayer.ZoomLevelSet.ZoomLevel01.DefaultAreaStyle = AreaStyles.Country1;
        worldLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        ShapeFileFeatureLayer capitalLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\WorldCapitals.shp");
        // We can customize our own Style. Here we passed in a color and a size.
        capitalLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.CreateSimpleCircleStyle(GeoColor.StandardColors.White, 7, GeoColor.StandardColors.Brown);
        // The Style we set here is available from ZoomLevel01 to ZoomLevel05. That means if we zoom in a bit more, the appearance we set here will not be visible anymore.
        capitalLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level05;
        
        capitalLayer.ZoomLevelSet.ZoomLevel06.DefaultPointStyle = PointStyles.Capital3;
        // The Style we set here is available from ZoomLevel06 to ZoomLevel20. That means if we zoom out a bit more, the appearance we set here will not be visible any more.
        capitalLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        
        ShapeFileFeatureLayer capitalLabelLayer = new ShapeFileFeatureLayer(@"C:\Program Files\ThinkGeo\Map Suite Desktop Evaluation Edition 4.0\Samples\SampleData\Data\WorldCapitals.shp");
        // We can customize our own TextStyle. Here we passed in the font, the size, the style and the color.
        capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.CreateSimpleTextStyle("CITY_NAME", "Arial", 8, DrawingFontStyles.Italic, GeoColor.StandardColors.Black, 3, 3);
        // The TextStyle we set here is available from ZoomLevel01 to ZoomLevel05. 
        capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level05;
        
        capitalLabelLayer.ZoomLevelSet.ZoomLevel06.DefaultTextStyle = TextStyles.Capital3("CITY_NAME");
        // The TextStyle we set here is available from ZoomLevel06 to ZoomLevel20. 
        capitalLabelLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        capitalLabelLayer.DrawingMarginPercentage = 50;
        
        LayerOverlay layerOverlay = new LayerOverlay();
        layerOverlay.Layers.Add(worldLayer);
        layerOverlay.Layers.Add(capitalLayer);
        layerOverlay.Layers.Add(capitalLabelLayer);
        
        winformsMap1.Overlays.Add(layerOverlay);
        winformsMap1.CurrentExtent = new RectangleShape(0, 78, 30, 26);
        
        winformsMap1.MapBackground.BackgroundBrush = new GeoSolidBrush(GeoColor.GeographicColors.ShallowOcean);
        winformsMap1.Refresh();
    }

Can you imagine what the map will look like now? Below is the result. At first it appears like figure 7, and the map changes to figure 8 as you zoom in.

Figure 7. Europe Map with two ZoomLevels, before Zoom In.

Figure 8. Europe Map with two ZoomLevels, after Zoom In.

Notes:

Because Desktop Edition uses multi-threading internally for drawing, if you want to change an overlay after the map is initialized, you need to lock the overlay first to avoid threading conflicts. For more information, please have a look at our "How Do I?" sample applications that come with the product.

Summary

You now know the basics of using the Map Suite Map control and be able to get started adding functionality into your own applications. Let's recap what we have learned about the object relationships and how the pieces of Map Suite work together:

1. It is of the utmost importance that the units (feet, meters, decimal degrees, etc.) be set properly for the Map control based on the data.
2. Shapefiles provide the data used by a Map control to render a map.
3. A Map is the basic control that contains all of the other objects that are used to tell how the map is to be rendered.
4. A Map has one-to-many Layers. A Layer correlates one-to-one with a shape file (.shp).
5. A Layer can have one-to-many ZoomLevels. ZoomLevels help to define ranges (upper and lower) of when a Layer should be shown or hidden.

If you have question on anything covered in this quick start guide, the ThinkGeo Support Team is ready and available to help. If we can be of any assistance, please contact us using the below information:

Free Discussion Forums: ThinkGeo Discussion Forums
Pre-Sales & Customer Support: ThinkGeo Customer Portal
Support Phone: 1-866-847-7510
1-785-727-4133 (Outside North America)
Web Site: http://thinkgeo.com

Download Sample Code From This Exercise