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

java.lang.Object
  extended by com.google.android.maps.Overlay
      extended by 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
 
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
 

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.