com.google.android.maps
Class ItemizedOverlay<Item extends OverlayItem>

java.lang.Object
  com.google.android.maps.Overlay
      com.google.android.maps.ItemizedOverlay<Item>

All Implemented Interfaces:

Overlay.Snappable

public abstract class ItemizedOverlay<Item extends OverlayItem>
extends Overlay
implements Overlay.Snappable

A base class for an Overlay which consists of a list of OverlayItems. This handles sorting north-to-south for drawing, creating span bounds, drawing a marker for each point, and maintaining a focused item. It also matches screen-taps to items, and dispatches Focus-change events to an optional listener.

Nested Class Summary

static interface

ItemizedOverlay.OnFocusChangeListener Interface for listeners interested in when the focused Item changes.

Nested classes/interfaces inherited from class com.google.android.maps.Overlay

Overlay.Snappable

Field Summary

protected int

mLastFocusedIndex The index of the item that was most recently (or currently) focused, or -1 if none ever was.

Fields inherited from class com.google.android.maps.Overlay

SHADOW_X_SKEW, SHADOW_Y_SCALE

Constructor Summary

ItemizedOverlay(android.graphics.drawable.Drawable defaultMarker)
Create a new ItemizedOverlay.

Method Summary

protected static android.graphics.drawable.Drawable	boundCenter(android.graphics.drawable.Drawable balloon) Adjusts a drawable's bounds so that (0,0) is the center center of the drawable.
protected static android.graphics.drawable.Drawable	boundCenterBottom(android.graphics.drawable.Drawable balloon) Adjusts a drawable's bounds so that (0,0) is a pixel in the center of the bottom row of the drawable.
protected abstract Item	createItem(int i) Method by which subclasses create the actual Items.
void	draw(android.graphics.Canvas canvas, MapView mapView, boolean shadow) Draw a marker on each of our items.
GeoPoint	getCenter() By default, returns the first-ranked item.
Item	getFocus()
protected int	getIndexToDraw(int drawingOrder) Returns the rank of the item with the given index.
Item	getItem(int position)
int	getLastFocusedIndex()
int	getLatSpanE6()
int	getLonSpanE6()
protected boolean	hitTest(Item item, android.graphics.drawable.Drawable marker, int hitX, int hitY) See if a given hit point is within the bounds of an item's marker.
Item	nextFocus(boolean forwards) Returns the next Item to be focused in the given direction, or null if we're at the end of the line.
boolean	onKeyUp(int keyCode, android.view.KeyEvent event, MapView mapView) Handle a key up event.
boolean	onSnapToItem(int x, int y, android.graphics.Point snapPoint, MapView mapView) Checks to see if the given x and y are close enough to an item resulting in snapping the current action (e.g.
boolean	onTap(GeoPoint p, MapView mapView) Handle a tap event.
protected boolean	onTap(int index) Override this method to handle a "tap" on an item.
boolean	onTouchEvent(android.view.MotionEvent event, MapView mapView) Handle a touch event.
boolean	onTrackballEvent(android.view.MotionEvent event, MapView mapView) Handle a trackball event.
protected void	populate() Utility method to perform all processing on a new ItemizedOverlay.
void	setDrawFocusedItem(boolean drawFocusedItem) Set whether or not to draw the focused item.
void	setFocus(Item item) If the given Item is found in the overlay, force it to be the current focus-bearer.
protected void	setLastFocusedIndex(int lastFocusedIndex) Set the index of the item that was most recently (or currently) focused, or -1 if none ever was.
void	setOnFocusChangeListener(ItemizedOverlay.OnFocusChangeListener l)
abstract int	size() The number of items in this overlay.

Methods inherited from class com.google.android.maps.Overlay

draw, drawAt, onKeyDown

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mLastFocusedIndex

protected int mLastFocusedIndex

The index of the item that was most recently (or currently) focused, or -1 if none ever was. This is remembered so that nextFocus(boolean) can resume sequential browsing of an Overlay even if the user pans away momentarily. Ordinarily subclasses will not need to set this variable, since it will be automatically updated when the focus is changed.

Constructor Detail

ItemizedOverlay

public ItemizedOverlay(android.graphics.drawable.Drawable defaultMarker)

Create a new ItemizedOverlay.

Parameters:

defaultMarker - A Drawable to be drawn on the map for each item in the overlay; see draw(android.graphics.Canvas, com.google.android.maps.MapView, boolean). An item may provide an alternate marker via its OverlayItem.getMarker(int) method. The marker may be drawn in two states: null or R.attr.state_focused. In order for hit-testing to work correctly, the two states must have the same bounds. (A simple drawable will ignore its state, which means that it will automatically have the same bounds.)

Note that you will need to add bounds to the marker in order for it to draw correctly. Typically this is done with boundCenterBottom, as in super(boundCenterBottom(marker)).

Method Detail

boundCenterBottom

protected static android.graphics.drawable.Drawable boundCenterBottom(android.graphics.drawable.Drawable balloon)

Adjusts a drawable's bounds so that (0,0) is a pixel in the center of the bottom row of the drawable. Useful for "pin"-like graphics. For convenience, returns the same drawable that was passed in.

Parameters:

balloon - the drawable to adjust

Returns:

the same drawable that was passed in.

boundCenter

protected static android.graphics.drawable.Drawable boundCenter(android.graphics.drawable.Drawable balloon)

Adjusts a drawable's bounds so that (0,0) is the center center of the drawable. Useful for "waypoint badge"-like graphics. For convenience, returns the same drawable that was passed in.

Parameters:

balloon - the drawable to adjust

Returns:

the same drawable that was passed in.

createItem

protected abstract Item createItem(int i)

Method by which subclasses create the actual Items. This will only be called from populate(); we'll cache them for later use.

size

public abstract int size()

The number of items in this overlay. Called once during populate(), and saved for all time.

getCenter

public GeoPoint getCenter()

By default, returns the first-ranked item. populate() must have been called first.

getIndexToDraw

protected int getIndexToDraw(int drawingOrder)

Returns the rank of the item with the given index. By default, the items are ranked by latitude. Subclasses may override this method in order to change the drawing order.

draw

public void draw(android.graphics.Canvas canvas,
                 MapView mapView,
                 boolean shadow)

Draw a marker on each of our items. populate() must have been called first.

The marker will be drawn twice for each Item in the Overlay--once in the shadow phase, skewed and darkened, then again in the non-shadow phase. The bottom-center of the marker will be aligned with the geographical coordinates of the Item.

The order of drawing may be changed by overriding the getIndexToDraw(int) method. An item may provide an alternate marker via its OverlayItem.getMarker(int) method. If that method returns null, the default marker is used.

The focused item is always drawn last, which puts it visually on top of the other items.

Overrides:

draw in class Overlay

Parameters:

canvas - The Canvas upon which to draw. Note that this may already have a transformation applied, so be sure to leave it the way you found it.

mapView - the MapView that requested the draw. Use MapView.getProjection() to convert between on-screen pixels and latitude/longitude pairs.

shadow - If true, draw the shadow layer. If false, draw the overlay contents.

getLatSpanE6

public int getLatSpanE6()

Returns:

the Latitude span of the overlay, computed during populate() as the difference between the northernmost and southernmost Items.

getLonSpanE6

public int getLonSpanE6()

Returns:

the Longitude span of the overlay, computed during populate() as the difference between the westernmost and easternmost Items. Overlays that span the longitude discontinuity at -180 degrees will report very large spans.

populate

protected final void populate()

Utility method to perform all processing on a new ItemizedOverlay. Subclasses provide Items through the createItem(int) method. The subclass should call this as soon as it has data, before anything else gets called.

setLastFocusedIndex

protected void setLastFocusedIndex(int lastFocusedIndex)

Set the index of the item that was most recently (or currently) focused, or -1 if none ever was. This is remembered so that nextFocus(boolean) can resume sequential browsing of an Overlay even if the user pans away momentarily. Ordinarily subclasses will not need to set this variable, since it will be automatically updated when the focus is changed.

setFocus

public void setFocus(Item item)

If the given Item is found in the overlay, force it to be the current focus-bearer. Any registered ItemizedOverlay.OnFocusChangeListener will be notified. This does not move the map, so if the Item isn't already centered, the user may get confused. If the Item is not found, this is a no-op. You can also pass null to remove focus.

getFocus

public Item getFocus()

Returns:

the currently-focused item, or null if no item is currently focused.

getLastFocusedIndex

public final int getLastFocusedIndex()

Returns:

the rank of the most-recently focused item, or -1 if we've never had a focus.

getItem

public final Item getItem(int position)

Returns:

the Item of the given index.

nextFocus

public Item nextFocus(boolean forwards)

Returns the next Item to be focused in the given direction, or null if we're at the end of the line. If we've never been focused before, returns the first item, or null if we're empty.

onTap

public boolean onTap(GeoPoint p,
                     MapView mapView)

Handle a tap event. A tap will only be handled if it lands on an item, and you have overridden onTap(int) to return true.

Overrides:

onTap in class Overlay

Parameters:

p - the point that has been tapped

mapView - the MapView that generated the tap event

Returns:

true if the tap was handled by this overlay.

onSnapToItem

public boolean onSnapToItem(int x,
                            int y,
                            android.graphics.Point snapPoint,
                            MapView mapView)

Checks to see if the given x and y are close enough to an item resulting in snapping the current action (e.g. zoom) to the item.

Specified by:

onSnapToItem in interface Overlay.Snappable

Parameters:

x - The x in screen coordinates.

y - The y in screen coordinates.

snapPoint - To be filled with the the interesting point (in screen coordinates) that is closest to the given x and y. Can be untouched if not snapping.

mapView - The MapView that is requesting the snap. Use MapView.getProjection() to convert between on-screen pixels and latitude/longitude pairs.

Returns:

Whether or not to snap to the interesting point.

onTrackballEvent

public boolean onTrackballEvent(android.view.MotionEvent event,
                                MapView mapView)

Description copied from class: Overlay

Handle a trackball event. By default does nothing and returns false.

Overrides:

onTrackballEvent in class Overlay

Parameters:

event - The motion event.

mapView - the MapView that generated the trackball event

Returns:

True if the tap was handled by this overlay.

onKeyUp

public boolean onKeyUp(int keyCode,
                       android.view.KeyEvent event,
                       MapView mapView)

Description copied from class: Overlay

Handle a key up event. By default does nothing and returns false.

Overrides:

onKeyUp in class Overlay

Parameters:

keyCode - The key code

event - The key event

mapView - the MapView that generated the key event

Returns:

True if the tap was handled by this overlay.

onTouchEvent

public boolean onTouchEvent(android.view.MotionEvent event,
                            MapView mapView)

Description copied from class: Overlay

Handle a touch event. By default does nothing and returns false.

Overrides:

onTouchEvent in class Overlay

Parameters:

event - The motion event.

mapView - the MapView that generated the touch event

Returns:

True if the tap was handled by this overlay.

hitTest

protected boolean hitTest(Item item,
                          android.graphics.drawable.Drawable marker,
                          int hitX,
                          int hitY)

See if a given hit point is within the bounds of an item's marker. Override to modify the way an item is hit tested. The hit point is relative to the marker's bounds. The default implementation just checks to see if the hit point is within the touchable bounds of the marker.

Parameters:

item - the item to hit test

marker - the item's marker

hitX - x coordinate of point to check

hitY - y coordinate of point to check

Returns:

true if the hit point is within the marker

setOnFocusChangeListener

public void setOnFocusChangeListener(ItemizedOverlay.OnFocusChangeListener l)

setDrawFocusedItem

public void setDrawFocusedItem(boolean drawFocusedItem)

Set whether or not to draw the focused item. The default is to draw it, but some clients may prefer to draw the focused item themselves.

Parameters:

drawFocusedItem -

onTap

protected boolean onTap(int index)

Override this method to handle a "tap" on an item. This could be from a touchscreen tap on an onscreen Item, or from a trackball click on a centered, selected Item. By default, does nothing and returns false.

Returns:

true if you handled the tap, false if you want the event that generated it to pass to other overlays.