This view has been designed from the ground up to be easily extendable, and provides several methods you can override to render your own overlays and customise touch event handling, together with some utility methods for converting view coordinates to image coordinates and vice versa. The sample app includes three simple examples of subclasses that add overlays, and these are a great place to start if you want to understand how to create a subclass of your own.

To add your own overlays, override theonDraw method. You must always call the superclass method from the start of your method usingsuper.onDraw(canvas) - if you don't, the view will never initialise. You must also check the view is ready by callingisReady() before attempting to use the utility messages documented below. Before the view is ready, they may throwNullPointerExceptions or return invalid coordinates.

You can override theonTouchEvent method and customise event detection in any way you want, handle some events yourself and pass others to the view. This is a complex topic and requires a strong understanding of how Android touch events work, so it's beyond the scope of this wiki. For an example, please see theFreehandView sample class.

Callsuper.onTouchEvent(event) from your method when you want the view's default event handling.

Until the dimensions of the view and the source image are known, the scale and center cannot be calculated, so it isn't possible to convert view to image coordinates or draw anchored overlays. To determine whether the view is ready to display an image (which may be the preview if you are using one), callisReady(). You can receive notification of this event by overridingonReady().

If you want to know whether the full size image (or its base layer tiles when using tiling) has been loaded, callisImageLoaded() or receive a notification by overridingonImageLoaded(). If you are not using a preview image, this event occurs at the same moment asonReady.

The following methods can be overridden to customise the behaviour of the view. This is not an exhaustive list - the image view extends Android'sView class so inherits all its methods - but these are the key methods the class adds or overrides that you are likely to want to override in your subclass.

Override to add your own overlays on top of the image. See notes above.Android API docs.

Override to customise event detection. See notes above.Android API docs.

The default behaviour when the view size is changed is to preserve the current scale and center. This is suitable for small changes in dimensions but may not be appropriate if the view is made significantly larger or smaller. You can override this method to implement the behaviour you need.Android API docs.

Normally you should set the view tomatch_parent for width and height. Ifwrap_content is used for one dimension, the view will match the aspect ratio of the image when it loads. You can modify this behaviour by overriding this method.Android API docs.

Override to receive a notification when an image is ready to be displayed. See notes above.

Override to receive a notification when the full size image or base layer tiles are loaded. See notes above.

These methods are useful for converting view to image coordinates and vice versa. See thestate andconfiguration pages for documentation on other methods that may be useful.

A set of methods that accept view coordinates, measured from the top left, and convert them into coordinates of the image. Use these methods to determine the image coordinates of a tap or other touch event. The various methods accept coordinates in different forms, either as a pair of floats or aPointF object.

When the image is zoomed out and has a border, converting a view coordinate that is in the border will return a source coordinate that isn't valid (either a negative x or y coordinate, or an x/y coordinate greater than the width/height of the image).

A set of methods that accept image coordinates, measured from the top left, and convert them into view coordinates. If the image coordinates are currently off screen, the view coordinates will also be outside the view. Use these methods to anchor overlays to fixed points on the image as it moves. The various methods accept coordinates in different forms, either as a pair of floats or aPointF object.