This project is read-only.


It's recommended to read / skim through it before you start dealing with new version.
1. Application callback.
New GlobalSettings.ApplicationCallback property was added. Callback object assigned to this property intercepts errors in all MapWinGIS classes so there is no longer needed to assign GlobalCallback to individual instances. In some cases errors are reported to application callback ONLY so there is strong recommendation to use it in ANY MapWinGIS application, however small it may be. Here is the simplest implementation of callback in C#:

// simplest implementation of callback
public class MyCallback : ICallback
    public void Progress(string KeyOfSender, int Percent, string Message)
        Debug.Print("{0}: {1}", Message, Percent);
    public void Error(string KeyOfSender, string ErrorMsg)
        Debug.Print("MapWinGIS error: ", ErrorMsg);

// let's assign this callback as early as possible during app's execution:
var gs = new GlobalSettings();
gs.ApplicationCallback = new MyCallback();

Here is the same code in VBA, can be used in MS Access for example:

' in a separate MwCallback class
Implements ICallback

Private Sub ICallback_Error(ByVal KeyOfSender As String, ByVal ErrorMsg As String)
    Debug.Print ErrorMsg
End Sub

Private Sub ICallback_Progress(ByVal KeyOfSender As String, ByVal Percent As Long, ByVal Message As String)
    Debug.Print Message & ": " & Percent
End Sub

' setting callback
Private Sub Form_Load()
   Dim gs As New GlobalSettings
   gs.ApplicationCallback = New MwCallback
End Sub

The use of application callback doesn't abolish o.get_ErrorMsg(o.LastErrorCode) scheme to report error message to GUI, for example:

var sf = new Shapefile();
if (!sf.Open(@"d:\my_data.shp", null)) {
     MessageBox.Show("Failed to open shapefile: " + sf.get_ErrorMsg(sf.LastErrorCode));

Known issue: in version there are some "Assertion failed: Provider wasn't found: #." messages reported via callback. Please ignore them.
2. Deprecated members removed from API.
In this version for the first time a significant number of obsolete API members were removed from Map class. Here is the list of members. Most of those members had been marked as deprecated for quite some time in the documentation. For each such member a substitute is recommended in the docs. Also the definitions aren't permanently removed from the source but excluded by conditional compilation, so if this move will cause too much trouble for the existing apps it can be reverted or a separate version of MapWinGIS with full API can be released. If you have issues with this decision please make you case in the discussions section.
3. Stricter policy on licensing of tile services.
License information with a link is supplied in the bottom right corner of the map. Some of the commercial tile providers were changed to allow use official API key: Bing Maps, Here Maps. Yandex Maps provider was removed as they don't allow to access their data other than from a browser. Yahoo maps and Topomapper providers were removed from API (the services were discontinued). Free MapQuest Aerial provider was added. See details here.
4. Demo application.
MapWinGIS is now shipped with demo application which is dubbed MapWindow Lite. Any functionality that this demo provides, can be easily incorporated in your own applications. The source code for the app is available here. The source also includes Legend control and GUI to set properties and labels for vector layers (from MapWindow 4). They can be easily reused in you own projects as well. Just checkout the source and start your own coding (only prerequisites are .NET framework 4.0 and MapWinGIS installed).
5. Support of OGR vector formats and spatial databases.
MapWinGIS can now directly open vector formats supported by GDAL / OGR, including spatial databases. Here is the list of formats. Pay attention that some of the formats in the list may not be included in MapWinGIS build (require additional plugins). Check these instructions on how to open various data formats supported by MapWinGIS. Here is a brief code sample to give some impression about new API:

string filename = @"c:\my_data.kml";
var ogrLayer = new OgrLayer();
if (!ogrLayer.OpenFromFile(filename, true))
    MessageBox.Show("Failed to open file: " + filename);
    var sf = ogrLayer.GetBuffer(); // data is held in an instance of shapefile
    for (int i = 0; i < sf.NumShapes; i++)
        // do something with your data
    //it's also possible to save changes with ogrLayer.SaveChanges()

   // let's add it to the map
   int layerHandle = axMap1.AddLayer(ogrLayer, true);

   // retrieve it back
   var ogrLayer2 = axMap1.get_OgrLayer(layerHandle);

   // get underlying the shapefile; it's the same one we get with OgrLayer.GetBuffer
   var sf2 = axMap1.get_Shapefile(layerHandle);

OGR layer uses an instance of in-memory Shapefile to hold its data. So in most cases these layers can be processed with exactly the same code as regular shapefiles. The differences will be noticeable when the saving of data is needed or for large layers (see OgrLayer.DynamicLoading).
6. Improved API for projection mismatch testing.
For the situations when layer is being added to the map with missing coordinate system / projection or if they differ from coordinate system / projection of the map the behaviour of MapWinGIS control can be set:

a) globally, for all layers at once:

var gs = new GlobalSettings();
gs.ReprojectLayersOnAdding = true;
gs.AllowLayersWithoutProjections = true;
gs.AllowProjectionMismatch = false;

b) on layer to layer bases using events:

// adding handles for the events
axMap1.ProjectionMismatch += axMap1_ProjectionMismatch;
axMap1.LayerProjectionIsEmpty += axMap1_LayerProjectionIsEmpty;
axMap1.LayerReprojected += axMap1_LayerReprojected;

// actually handling them
void axMap1_LayerProjectionIsEmpty(object sender, AxMapWinGIS._DMapEvents_LayerProjectionIsEmptyEvent e)
    e.cancelAdding = tkMwBoolean.blnFalse;   // accept layers without projection
    Debug.Print("Layer without projection was added: " + axMap1.get_LayerName(e.layerHandle));
void axMap1_ProjectionMismatch(object sender, AxMapWinGIS._DMapEvents_ProjectionMismatchEvent e)
    e.reproject = tkMwBoolean.blnTrue;    // try to reproject on the fly
    Debug.Print("Layer with different projection; attempting reprojection: " + axMap1.get_LayerName(e.layerHandle));
void axMap1_LayerReprojected(object sender, AxMapWinGIS._DMapEvents_LayerReprojectedEvent e)
    Debug.Print("Reprojection results: " + e.success);
7. Improved selection tool.
In previous versions it was needed to handle Map.MouseDownEvent and Map.SelectBoxFinal events to make built-in cmSelection tool work. In both cases quite a lot of code was needed (conversion of coordinates, retrieving of shapefile, calling Shapefile.SelectShapes, updating Shapefile.ShapeSelected property for new selection). Now all this logic is embedded in MapWinGIS so it's only necessary to handle Map.ChooseLayer event.

// in the form constructor
axMap1.ChooseLayer += axMap1_ChooseLayer;

private void axMap1_ChooseLayer(object sender, _DMapEvents_ChooseLayerEvent e)
    if (axMap1.CursorMode == tkCursorMode.cmSelection)
        // choose layer according to the logic of your application 
        // for example, legend1.SelectedLayer if your app uses legend control
        e.layerHandle = legend1.SelectedLayer;

If Map.ChooseLayer event isn't handled for cmSelection tool, the control works as before, i.e. it's necessary to handle Map.MouseDownEvent and Map.SelectBoxFinal to update selection.
8. Interactive shapefile editor.
MapWinGIS now has built-in shape editor which works both for shapefiles and OGR layers (with some limitations depending on particular driver). Here is a code sample which demonstrates how to add shapes interactively into particular shapefile.

private int _layerHandle = -1;

private void StartEditing()
    axMap1.GrabProjectionFromData = true;

    string filename = @"d:\data\sf\buildings.shp";
    var sf = new Shapefile();
    if (!sf.Open(filename))
        MessageBox.Show("Failed to open: " + filename);

    _layerHandle = axMap1.AddLayer(sf, true);

    sf.InteractiveEditing = true;
    axMap1.CursorMode = tkCursorMode.cmAddShape;  // cmEditShape, etc
    axMap1.ChooseLayer += axMap1_ChooseLayer;

    // doing some edits interactively


private void axMap1_ChooseLayer(object sender, AxMapWinGIS._DMapEvents_ChooseLayerEvent e)
    if (axMap1.CursorMode == tkCursorMode.cmAddShape)  // cmMoveShapes, etc
        e.layerHandle = _layerHandle;

See Demo app and its source code for details on more complex behavior. The API reference of ShapeEditor class is here. To save changes for OGR layers OgrLayer.SaveChanges call is needed. The undo/redo functionality is provided by AxMap.UndoList.
9. Update of GDAL library.
MapWinGIS 4.9.3 uses development version of GDAL 2.0 (which will certainly evolve into stable one after some time). The previous versions of MapWinGIS were linked against 1.xx versions of GDAL. Subjectively the move hardly brought any significant changes in performance / functionality, but GDAL 2.0 has somewhat different API (first of all GDALDatasource class is now used to open both raster and vector datasets) plus it's the version that will be developed further. See more details on building process that MapWinGIS uses here.
10. Reporting GDAL errors.
In this version of MapWinGIS it became possible to see all the error messages that GDAL library reports. The messages are reported to application callback described above. Each message is prefixed with "GDAL_WARNING:". The presence of such errors doesn't necessarily mean that the app doesn't work correctly, but it's an important diagnostic info if that is indeed the case. Also such warnings can appear in the existing apps after migrating to v.4.9.3. It's not because new version works less stable, quite on contrary - now it reports all properly.
11. GDAL environment variables.
The support projections and coordinate transformations the previous versions of MapWinGIS depended on GDAL_DATA environment variable. Since this same variable can be used by other GIS applications, which can overwrite it to point to their own location, it wasn't particularly good approach. Now the location of data is set internally during initialization of library. By default it's \gdal-data folder in the folder where MapWinGIS control resides. The same policy is used for location of GDAL plugins (\gdalplugins folder by default). These settings can be queried and changed using the properties below. If you want to override this settings, you should do it as early as possible after application startup.

var gs = new GlobalSettings();
Debug.Print("GDAL data path: " + gs.GdalDataPath);
Debug.Print("GDAL plugin path: " + gs.GdalPluginPath);

PROJ_LIB environment variable has remained untouched. Presumably it's needed for some of the GDAL plugins which call proj4 library directly. This variable isn't needed for main MapWinGIS functionality.
12. Update of Visual C++ runtime.
The new version uses VC2010 runtime (the previous versions had used VC2008 for a long time). The runtime should be deployed on the machines of users. It's included in the MapWinGIS installer. You can also create a custom installer for your app based on MapWinGIS installation script.

Last edited Jan 21, 2015 at 8:14 AM by sleschinski, version 25


sleschinski Jan 21, 2015 at 8:13 AM 
Hi Yong, we are using VS 2013 with VC 2010 runtime (target runtime can be selected in the project settings). We depend on GDAL_SDK: At the time 4.9.3 version was prepared only VC2010 build was available there. However I've just checked it and it seems that more recent runtimes were added as well. We shall try to migrate to VC2013 for the next version.

yong_wang Jan 14, 2015 at 2:08 PM 
thanks very much for your hard work!
Why not use VC 2013 instead of VS 2010?
Microsoft has release a community version of VS 2013:
It is free for open source projects and small companies.
I believe VC 2013 is faster than VC 2010