X. Migration guides
This page contains migration instructions for versions that contain breaking changes to the API or behaviour. Full release notes can be found on the releases page.
setParallelLoadingEnabled method has been removed, and replaced with
setExecutor(Executor). You can use
AsyncTask.THREAD_POOL_EXECUTOR (the default as of 3.9.0),
AsyncTask.SERIAL_EXECUTOR (the default before 3.9.0), or one of your own. If you provide your own, it is strongly recommended you use a single executor across all view instances and kept for the life of your application.
The default executor has been changed to
AsyncTask.THREAD_POOL_EXECUTOR in an attempt to reduce the likelihood of the view blocking due to other background work e.g. network I/O.
The view no longer synchronizes its calls to
ImageRegionDecoder.decodeRegion, in order to support parallel loading when decoder classes support it. Because a multi-threaded executor is now used by default, custom
ImageRegionDecoder instances must be modified to support concurrent calls to
decodeRegion. If your decoder is not thread safe, you could simply add
synchronized to the method signature.
The default region decoder,
SkiaImageRegionDecoder, is thread safe but uses
BitmapRegionDecoder which is internally synchronized and cannot load tiles in parallel. Therefore using a multi-threaded executor helps to reduce contention with other tasks but does not allow parallel loading of tiles.
Tiles are now loaded while gestures and animations are still in progress instead of when they end. This makes the view more responsive but can cause reduced frame rates on cheap/old devices. Call
setEagerLoadingEnabled(false) to disable this feature.
Image quality is now capped at 320dpi (approximately retina quality) instead of matching the screen's density, which results in high memory use and poor performance when displaying large images on very high density screens. The difference in quality is usually unnoticeable, especially with photos. Use
setMinimumTileDpi(int) to override the default.
Support for SDK 10-13 has been dropped. The minimum SDK is now 14.
Version 3 includes breaking changes. To upgrade, you will need to make a few simple changes to your activities and subclasses.
Support for preview images, allowing a low resolution preview to be displayed and gestures to be enabled while base layer tiles of the full size image are loaded. This is useful for very big images (over 10,000px).
Revised lifecycle events, so you can display a loading message until the base layer is fully loaded.
A listener interface to allow activities to respond to lifecycle events and image loading errors.
ScaleImageViewhas been merged into
SubsamplingScaleImageView, which now supports display of large images with tiling, and small images without tiling or from a bitmap object.
Migrating to version 3
1) Change the method for setting the image source.
|Old method||New method|
2) Replace uses of
SubsamplingScaleImageView and disable tiling if required. For example:
SubsamplingScaleImageView view = (SubsamplingScaleImageView)findViewById(id.imageView); view.setImage(ImageSource.asset("map.png").tilingDisabled());
3) Replace uses of
4) In subclasses, replace overrides of