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