WinForms Map - New Data Management and Breaking Changes in 14.1

As with any new release we try to add new features. When adding these fantastic features, there are unfortunately difficult decisions to be made. As you begin the process of migrating to the latest version of our Windows Forms Map Control I thought I would spend some time discussing some of the key changes and improvements.

The first thing we’ve done is consolidate a number of often used properties in the VectorItemsLayer class (such as Items, DataSource, DataMember, Mappings, AttributeMappings) into a single Data property which implements the IMapDataAdapter interface.

The first (and obvious question) is why would we do such a thing? With the introduction of Pies and Bubbles into the Map component we realized that we needed to expand our definition of the meaning of “Data” in each scenario. Rather than adding a bunch of properties that would be useful in one scenario but useless in another, we added the ability to abstract away (via the IMapDataAdapter interface) how each type of object behaves when it comes to data. Currently we have 4 such IMapDataAdapter implementations:

• MapItemStorage - to manually manipulate vector items via the Items collection
• ListSourceDataAdapter - to bind a Map control to a data source and specify mappings via the Mappings property
• PieChartDataAdapter - to automatically generate Pie charts from a data source
• BubbleChartDataAdapter - to automatically generate Bubble charts from a data source

This flexibility allows the creation of future map visualizations and bindings.

You can see the new Data options available in the Map Layer’s editor.

Once this is set properly, notice that Mapping property. In this release new descendants were created to extend the base functionality in order to support pies or bubbles.

Let’s take a look at how this feels in code.

Example 1:

VectorItemsLayer itemsLayer = new VectorItemsLayer(); 
ListSourceDataAdapter dataAdapter = new ListSourceDataAdapter(); 
dataAdapter.Mappings.Latitude = "Latitude"; 
dataAdapter.Mappings.Longitude = "Longitude"; 
dataAdapter.DataSource = GetDataSource(); 

itemsLayer.Data = dataAdapter;

In this example we are using a ListSourceDataAdapter to create a binding to auto-generate the MapItems that will be displayed on the map.

Example 2:

VectorItemsLayer itemsLayer = new VectorItemsLayer();
MapItemStorage storage = new MapItemStorage();
MapBubble bubble = new MapBubble();
storage.Items.Add(bubble);
itemsLayer.Data = storage;

In example 2 we are manually adding the MapItems we wish to see in our map via the MapItemStorage object. Note that in both cases data is managed in each layer by the IMapDataAdapter (not the layer itself).

Final Words

We know these kinds of changes can be difficult for you. We did our best to provide backwards compatibility – old projects will be properly deserialized into the new object structure. To make sure these changes take effect properly, run the project converter. If you still get any warnings, simply open the form with the map control, make a small change, and save the form. Everything should be peachy-king after that.

I really hope this helps!

As always, if there are any comments and/or questions, feel free to get a hold of me!

Seth Juarez
Email: sethj@devexpress.com
Twitter: @SethJuarez

Free DevExpress Products - Get Your Copy Today