09. Events

Loading events

Using the OnImageEventListener interface you can be notified of loading events. This can be useful if you want to display a loading message until the image has initialised (but note you can't hide the view until it is loaded because Android will not call its onDraw method). The interface has five methods, and if you don't want to implement all of them you can extend DefaultOnImageEventListener which provides default no-op implementations for each method.

Method	Description
onReady()	Called when the dimensions of the image and view are known, and either a preview image, the full size image, or base layer tiles are loaded. This indicates the scale and translate are known and the next draw will display an image. This event can be used to hide a loading graphic, or inform a subclass that it is safe to draw overlays.
onImageLoaded()	Called when the full size image is ready. When using tiling, this means the lowest resolution base layer of tiles are loaded, and when tiling is disabled, the image bitmap is loaded. If you are not using a preview image, this occurs at the same moment as onReady().

Subclasses do not need to register an OnImageEventListener to be notified of these events, they can override the protected onReady and onImageLoaded methods instead.

Error events

The OnImageEventListener interface provides three methods you can override to be notified when an error occurs while loading an image or tile. These methods are not entirely reliable; sometimes the image decoder will fail to properly decode an image and return a blank or corrupt image, and there's no way to detect this.

Method	Description
onPreviewLoadError(Exception)	Called when a preview image could not be loaded. Only relevant when you are using a preview image. The view will continue loading the full size image.
onImageLoadError(Exception)	Indicates an error initialising the decoder when tiling is enabled, or when loading the full size bitmap when tiling is disabled. The view will remain blank.
onTileLoadError(Exception)	Called when an image tile could not be loaded. The view will display other tiles if any were successfully loaded, and may attempt to load the same tile later.

Touch events

The view supports OnClickListeners and OnLongClickListeners.

For more advanced touch event detection, you can use a GestureDetector. The simplest way to detect gestures is with a SimpleOnGestureListener as shown in this simple example. Using public methods on the class, you can convert the view coordinates of the event into coordinates of the source image.

final SubsamplingScaleImageView imageView = (SubsamplingScaleImageView)findViewById(id.imageView);
final GestureDetector gestureDetector = new GestureDetector(this, new GestureDetector.SimpleOnGestureListener() {
    @Override
    public boolean onSingleTapConfirmed(MotionEvent e) {
        if (imageView.isReady()) {
            PointF sCoord = imageView.viewToSourceCoord(e.getX(), e.getY());
            // ...
        }
        return true;
    }
});
imageView.setImage(ImageSource.asset("map.png"));
imageView.setOnTouchListener(new OnTouchListener() {
    @Override
    public boolean onTouch(View view, MotionEvent motionEvent) {
        return gestureDetector.onTouchEvent(motionEvent);
    }
});

As this example illustrates, you must check that the view is ready with the isReady() method before attempting to convert screen coordinates to image coordinates. A NullPointerException may be thrown if you don't.

It is safe to override onSingleTapUp, onSingleTapConfirmed, onLongPress and onDown from the SimpleOnGestureListener class. If you override other methods, you will prevent the view from properly handling double taps, zoom and pan gestures.

Subclasses can override the view's onTouchEvent, and with care it is possible to add sophisticated event handling without interrupting the view's behaviour.