Android
com.google.android.maps
public abstract class

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

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

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 dispatches Tap and Focus-change events to optional listeners.

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

Summary

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

Fields

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

Public Constructors

            ItemizedOverlay(Drawable defaultMarker)
Create a new ItemizedOverlay.

Public Methods

          void  draw(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()
    final      Item  getItem(int position)
    final      int  getLastFocusedIndex()
          int  getLatSpanE6()
          int  getLonSpanE6()
          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  onTap(GeoPoint p, MapView mapView)
Handle a tap event.
          boolean  onTouchEvent(MotionEvent event, MapView mapView)
Handle a touch event.
          boolean  onTrackballEvent(MotionEvent event, MapView mapView)
Handle a trackball event.
          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.
          void  setOnFocusChangeListener(ItemizedOverlay.OnFocusChangeListener l)
abstract          int  size()
The number of items in this overlay.

Protected Methods

      static    Drawable  boundCenter(Drawable balloon)
Adjusts a drawable's bounds so that (0,0) is the center center of the drawable.
      static    Drawable  boundCenterBottom(Drawable balloon)
Adjusts a drawable's bounds so that (0,0) is a pixel in the center of the bottom row of the drawable.
abstract          Item  createItem(int i)
Method by which subclasses create the actual Items.
          int  getIndexToDraw(int drawingOrder)
Returns the rank of the item with the given index.
          boolean  hitTest(Item item, Drawable marker, int hitX, int hitY)
See if a given hit point is within the bounds of an item's marker.
          boolean  onTap(int index)
Override this method to handle a "tap" on an item.
    final      void  populate()
Utility method to perform all processing on a new ItemizedOverlay.
Methods inherited from class com.google.android.maps.Overlay
Methods inherited from class java.lang.Object

Details

Fields

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.

Public Constructors

public ItemizedOverlay(Drawable defaultMarker)

Create a new ItemizedOverlay.

Parameters

defaultMarker A Drawable to be drawn on the map for each item in the overlay; see draw(Canvas, MapView, boolean). An item may provide an alternate marker via its getMarker(int) method. The marker may be drawn in two states: null or 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.)

Public Methods

public void draw(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 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.

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 getProjection() to convert between on-screen pixels and latitude/longitude pairs.
shadow If true, draw the shadow layer. If false, draw the overlay contents.

public GeoPoint getCenter()

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

public Item getFocus()

Returns

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

public final Item getItem(int position)

Returns

  • the Item of the given index.

public final int getLastFocusedIndex()

Returns

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

public int getLatSpanE6()

Returns

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

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.

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.

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.

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.

public boolean onTouchEvent(MotionEvent event, MapView mapView)

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

Parameters

event The motion event.
mapView the MapView that generated the touch event

Returns

  • True if the tap was handled by this overlay.

public boolean onTrackballEvent(MotionEvent event, MapView mapView)

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

Parameters

event The motion event.
mapView the MapView that generated the trackball event

Returns

  • True if the tap was handled by this overlay.

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.

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.

public void setOnFocusChangeListener(ItemizedOverlay.OnFocusChangeListener l)

public abstract int size()

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

Protected Methods

protected static Drawable boundCenter(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.

protected static Drawable boundCenterBottom(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.

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.

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.

protected boolean hitTest(Item item, 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

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.

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.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48