Skip to content

X. Migration guides

Jump to bottom
davemorrissey edited this page Dec 2, 2017 · 1 revision

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.

3.9.0

The 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.

3.8.0

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.

3.0.0

Version 3 includes breaking changes. To upgrade, you will need to make a few simple changes to your activities and subclasses.

What's new

  • 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.

  • ScaleImageView has 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
view.setImageAsset("map.png") view.setImage(ImageSource.asset("map.png"))
view.setImageResource(R.drawable.map) view.setImage(ImageSource.resource(R.drawable.map))
view.setImageUri("/sdcard/map.png") view.setImage(ImageSource.uri("/sdcard/map.png"))
view.setImageBitmap(map) view.setImage(ImageSource.bitmap(map))

2) Replace uses of ScaleImageView with 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 isImageReady() with isReady().

4) In subclasses, replace overrides of onImageReady() with onReady().

Clone this wiki locally