10. Extension

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.

Sample classes

Class	Description
PinView	Displays a pin anchored to a point on the image.
CircleView	Displays a circle that moves and scales with the image.
FreehandView	A very simple freehand drawing demonstration. The user can draw a freehand line, which will scale and move with the image. Illustrates how to extend event detection.

Adding overlays

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

Customising event detection

You can override the onTouchEvent 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 the FreehandView sample class.

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

Checking view state

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), call isReady(). You can receive notification of this event by overriding onReady().

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

Overridable methods

The following methods can be overridden to customise the behaviour of the view. This is not an exhaustive list - the image view extends Android's View 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.

onDraw

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

onTouchEvent

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

onSizeChanged

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.

onMeasure

Normally you should set the view to match_parent for width and height. If wrap_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.

onReady

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

onImageLoaded

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

Utility methods

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

viewToSourceCoord

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 a PointF 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).

sourceToViewCoord

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 a PointF object.