SUMMARY OF CHANGES IN VERSION 4.9.3.
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 callbackpublicclass MyCallback : ICallback { publicvoid Progress(string KeyOfSender, int Percent, string Message) { Debug.Print("{0}: {1}", Message, Percent); } publicvoid 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 classImplements ICallback PrivateSub ICallback_Error(ByVal KeyOfSender AsString, ByVal ErrorMsg AsString) Debug.Print ErrorMsg EndSubPrivateSub ICallback_Progress(ByVal KeyOfSender AsString, ByVal Percent AsLong, ByVal Message AsString) Debug.Print Message & ": "& Percent EndSub' setting callbackPrivateSub Form_Load() Dim gs AsNew GlobalSettings gs.ApplicationCallback = New MwCallback EndSub
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 4.9.3.2. 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); } else { var sf = ogrLayer.GetBuffer(); // data is held in an instance of shapefilefor (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 mapint layerHandle = axMap1.AddLayer(ogrLayer, true); // retrieve it backvar ogrLayer2 = axMap1.get_OgrLayer(layerHandle); // get underlying the shapefile; it's the same one we get with OgrLayer.GetBuffervar 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 themvoid 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; privatevoid 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.privateint _layerHandle = -1; privatevoid 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); return; } _layerHandle = axMap1.AddLayer(sf, true); sf.InteractiveEditing = true; axMap1.CursorMode = tkCursorMode.cmAddShape; // cmEditShape, etc axMap1.ChooseLayer += axMap1_ChooseLayer; // doing some edits interactively//sf.StopEditingShapes(); } privatevoid 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.