Upgrade Guide
- The built zoom controls have been removed in favor of a simple overlay based classes with some basic always on screen zoom buttons. There's no API change so you can still use the
MapView.setUseBuiltInZoomControls(true/false). If this doesn't work for you, fork, fix, and pr. The old zoom buttons were actually built into the Android and were memory leak prone and will log some nasty warning messages under certain circumstances.
Version 6.0.0 has some major changes. I'd suggest extensive testing with your application(s) before rolling out updates.
- Lifecycle changes. MapView now has a
onPauseandonResume. These calls are passed on to all overlays classes. In general, this was added to help reduce the amount of boilerplate code that users of osmdroid-android would need to do properly handle start/stopping the compass and gps sensors. This code was all incorporated into those overlays. Bottom line, you can probably delete any code you have in your application related to starting/stopping GPS or Compass overlays and replace it withmapView.onPause()andmapView.onResume()calls. - If you were previously using the geopackage support library, several of the class and packages names were changed. Impacts should be minimal, but expect some find and replace work.
- Several new fields were added to
IConfigurationProviderinterface. If you've written your own, expect to do some work (it's minor). If you've extended theDefaultConfigurationProvider, then you should be ok. - There was several changes to MapView and MapController, none of which should be breaking. These methods involve getting/setting the current zoom level and animation to a zoom level. Impacts should be minimal.
- With floating point zoom, custom implementations of overlays may have to perform some tweaking.
- Expect higher memory usage due to increase memory caching of map tiles. Previous versions used on average 50-60MB of ram to run. v6 can use around 100MB.
- MapView in a recycler is now supported and functions on API16+ devices. This sets the default value for
view.setHasTransientState(true)when the MapView is created. If this causes issues, you can opt out of this setting via the newIConfiguration#setMapViewRecyclerFriendly(boolean)setting - Permissions were removed from the AAR library's manifest.xml, so you may need to update your apk's manifest file depending on your usage scenario.
- Enabling hardware acceleration should now be supportable on all devices, however there are still some performance issues with polygons (to be addressed in v6.1)
- The various deprecated methods in
OpenStreetMapsTileProviderConstantshave been removed. Replacement calls are now in IConfigurationProvider. - Advisory only, this version increases the method counts for osmdroid-android to around 3000
- The LatLonGridlineOverlay has been deprecated in favor of LatLonGridlineOverlay2, which has a much cleaner and simpler integration.
- osmdroid-android/src/main/java/org/osmdroid/util/constants/UtilConstants.java
- osmdroid-android/src/main/java/org/osmdroid/views/util/constants/MapViewConstants.java
- All APIs referencing Lat/Lon based on E6
- All APIs referencing Zoom level based Int
- All APIs related to
setMapListener, replaced by add/remove MapListener
- Several new fields were added to
IConfigurationProviderinterface. If you've written your own, expect to do some work (it's minor). If you've extended theDefaultConfigurationProvider, then you should be ok. - There were several changes to the CacheManager API.
- There were several improvements made to the scale bar overlay class. None that should be API breaking.
- No major or minor API changes. Upgrading should be straight forward
- No breaking API changes, new constructors added for tile source for the copyright notice
- Consider using the CopyrightOverlay to give proper attribution to the map source owner
- Old mapsforge example had a memory leak, which is now fixed on the sample with Open Map
- Geopackage support added, see sample
- Sample app Cache Analyzer is now available always
- Bing tile source was moved into osmdroid-android and added to the Sample Open Map
- There were a number of memory leak prevention fixes that went in this build, specificaly on MyNewLocationOverlay. As such, you must be destroy your MyNewLocationOverlay onPause and create a new one onResume
- More flexibility with cache expiration dates (new IConfiguration options)
- Sample app now also includes a cache analyzer (only when debug is turned on), which lets you get various statistics about the cache database and browse the cache database records
- no code changes
- New overlay type added, efficient for many thousands of icons (up to 100k depending on device), see
SimpleFastPointOverlay - The SqlTileWriter will at start up, will check its size and trim to be under the maximum size set by the OpenStreetMapTileProviderConstants setting. Expired tiles are not touched until the trim size is reached
- Behavior change for hardware acceleration. At start up, the osmdroid mapview is now automatically set to oftware acceleration mode only due to unpredictable crashes when using polylines or polygons. This behavior can be overridden using the constructor or by
Configuration.getInstance().setMapViewHardwareAccelerated()before the MapView is created (layout inflation counts!) -
Overlay.onDraw()is now a public method. - OpenStreetMapTileProviderConstants has been majorly redesign and refactored. Sorry if I caused you pain, but having a class with the name"constants" in it always irked me since the were in fact configuration settings. So all settings that was there, have been relocated to the IConfiguration/DefaultConfiguration settings class. In addition, all of the debug settings throughout the code base have been moved there. Also included are some automagic classes to help you set the tile cache locations and to store and load from shared preferences. See the sample application's MainActivity
- Behavioral change for tile caching. At start up, osmdroid will now scan for all mounted partitions and storage devices and will use the device with the largest free space be default. If there's no other solutions, it will use application private storage. See the sample application's MainActivity to override, as always, you can set the Cache Directory via
Configuration.getInstance(). This is a significant change and may cause unexpected behavior if you don't handle this situation in the future (the mount point with the most free space, can change, therefore you should handle setting the cache path as a user preference). Threadpools are now adjustable via this mechanism. User Agent is autopopulated by the application package name. - Many bug fixes, most of the issues at zoom 19-22 were fixed
- Many changes to the sample app
No APIs changes, just bug fixes
No APIs changes, just bug fixes
Overlays no longer require a Context constructor
The "Doubles" branch was finally merged. This means that osmdroid uses doubles internally now for higher precision as lower zoom levels (higher numerically). All 1E6 based APIs are deprecated but still accessible. This does not resolve issues with zoom > 20 due to Android using an integer based coordinate system.
osmdroid has always stored map tiles to the local file system. When upgrading to 5.1 and from now on, downloaded tiles will be stored in a database named tiles.db which contains the tile source name, the tile id (x/y/z), and an expiration date. When osmdroid (or apps that use it) starts up, it will automatically prune old tiles from the database. This only happens when the map is created and it happens asynchronously.
Tiles that were already loaded in device....
TBD do we leave it or delete it? Or run an import routine, then delete from local storage....
Mapquest now apparently uses MapBox for map tiles. Go to MapBox's website to get an access token, then use that access token for both MapQuest and MapBox tile sources.
The MapBox tile source formerly used the "ACCESS_TOKEN" meta-data entry in the manifest. It now uses "MAPBOX_ACCESS_TOKEN".
MapQuest uses "MAPQUEST_ACCESS_TOKEN" and "MAPQUEST_MAPID" (default is "mapquest.streets-mb" if not defined)
Everything based on overlay has had it's constructor simplified in order to support the creation of overlays in an async task. As such, you may have some work to do for updating overlays. There was one field removed from the base Overlay class, mScale, which wasn't used anywhere except for the ScaleBarOverlay. The old api with Context parameters is still there but set to depricated.
If you were using OSMBonusPack with osmdroid, there's been some significant changes recently. Namely, everything but the KML/GeoJson parsing and online routing tools have been migrated (with Git history). As a consequence, several packages were shuffled around and renamed in order to prevent collisions and to better align with osmdroid's package structure. We also made some minor, hopefully non-breaking changes to the CacheManager and to Marker (both from OSMBonusPack).
- CacheManager - org.osmdroid.tileprovider.cachemanager
- Marker and Overlays from OSMBonusPack - org.osmdroid.views.overlay, org.osmdroid.views.overlay.infowindow
Included with the migration of OSMBonusPack's capabilities is the Mapsforge Adapter, which lets you use on device rendered tiles with Mapsforge's rendering engine. Since Mapsforge is LGPL based license, so is this adapter.
Ever wanted Lat/Lon gridlines? We have to covered.
- org.osmdroid.views.overlay.gridlines
The command line and swing GUI tile packagers also received some attention and are now included with the distribution. This adds a number of bug fixes.
All my location type overlays were consolidated into it's own package
- Resource Proxy and all derived classes were deleted and removed from all resource paths and constructors
- MapControllerOld was deleted (use MapController)
- MyLocationOverlay was deleted (use MyNewLocationOverlay)
If you were previously using IMapController.isNightMode or setNightMode or extended IMapController, these functions were removed and migrated directly into the TilesOverlay. The same functionality can be implemented using the following
this.mMapView.getOverlayManager().getTilesOverlay().setColorFilter(TilesOverlay.INVERT_COLORS);
If you were using the ScaleBarOverlay, the constructor has changed from passing in Context to MapView.
There were some changes to the resource proxy interface. If you inherit from one of the provided implementations, you're probably good to go.
Output target is now AAR and the default osmdroid resources are now included (my location icon and whatnot). If you 'borrowed' those icons from osmdroid, you now will no longer need to include them.
If you use any custom map tile sources, a parameter was removed from the constructor so you'll need to adjust accordingly.
If you used a custom overlay manager, that class was interfaced and refactored. Please now extend from DefaultOverlayManager or implement the interface as appropriate.