com.google.android.maps
Class MyLocationOverlay

java.lang.Object
  com.google.android.maps.Overlay
      com.google.android.maps.MyLocationOverlay

All Implemented Interfaces:

android.hardware.SensorListener, android.location.LocationListener, Overlay.Snappable

public class MyLocationOverlay
extends Overlay
implements android.hardware.SensorListener, android.location.LocationListener, Overlay.Snappable

An Overlay for drawing the user's current location (and accuracy) on the map, and/or a compass-rose inset. Subclases can override dispatchTap() to handle taps on the current location.

You will want to call enableMyLocation() and/or enableCompass(), probably from your Activity's Activity.onResume() method, to enable the features of this overlay. Remember to call the corresponding disableMyLocation() and/or disableCompass() in your Activity's Activity.onPause() method to turn off updates when in the background.

Optionally, the constructor can also take a MapController and use it to keep the "my location" dot visible by panning the map when it would go offscreen, and a View to View.postInvalidate() when location or orientation is changed.

Runnables can be provided in runOnFirstFix(java.lang.Runnable) to be run as soon as we have a fix. (For example, this could center the map and zoom in to show the location.)

Nested Class Summary

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

MyLocationOverlay(android.content.Context context, MapView mapView)
Construct a new MyLocationOverlay.

Method Summary

void	disableCompass() Disable updates from the compass sensor.
void	disableMyLocation() Stops location updates.
protected boolean	dispatchTap() Handle a tap on the "my location" point.
boolean	draw(android.graphics.Canvas canvas, MapView mapView, boolean shadow, long when) Draw method.
protected void	drawCompass(android.graphics.Canvas canvas, float bearing) Draw the compass inset.
protected void	drawMyLocation(android.graphics.Canvas canvas, MapView mapView, android.location.Location lastFix, GeoPoint myLocation, long when) Draw the "my location" dot.
boolean	enableCompass() Enable updates from the compass sensor.
boolean	enableMyLocation() Attempts to enable MyLocation, registering for updates from LocationManager.GPS_PROVIDER and LocationManager.NETWORK_PROVIDER.
android.location.Location	getLastFix() Returns a Location corresponding to the most-recently-set user location.
GeoPoint	getMyLocation() Returns a GeoPoint corresponding to the most-recently-set user location.
float	getOrientation() Returns the most-recently-set compass bearing.
boolean	isCompassEnabled() Checks whether the compass widget is displayed.
boolean	isMyLocationEnabled() Checks whether location awareness is enabled (via GPS or network).
void	onAccuracyChanged(int sensor, int accuracy)
void	onLocationChanged(android.location.Location location) Listener to get location updates from LocationManagerService.
void	onProviderDisabled(java.lang.String provider)
void	onProviderEnabled(java.lang.String provider)
void	onSensorChanged(int sensor, float[] values) Called by the SensorManager when the compass value changes.
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.
void	onStatusChanged(java.lang.String provider, int status, android.os.Bundle extras)
boolean	onTap(GeoPoint p, MapView map) Checks whether the location of the tap is close enough to the current location (if it's known).
boolean	runOnFirstFix(java.lang.Runnable runnable) Queues a runnable to be executed as soon as we have a location fix.

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

draw, drawAt, onKeyDown, onKeyUp, onTouchEvent, onTrackballEvent

Methods inherited from class java.lang.Object

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

Constructor Detail

MyLocationOverlay

public MyLocationOverlay(android.content.Context context,
                         MapView mapView)

Construct a new MyLocationOverlay.

Parameters:

context - A context to be used for accessing system services.

mapView - The MapView on which the location is to be overlayed.

Throws:

java.lang.IllegalArgumentException - if mapView is null.

Method Detail

enableCompass

public boolean enableCompass()

Enable updates from the compass sensor. A no-op if it's already enabled.

Returns:

True if we successfully requested updates; false if the compass sensor could not be enabled.

disableCompass

public void disableCompass()

Disable updates from the compass sensor.

isCompassEnabled

public boolean isCompassEnabled()

Checks whether the compass widget is displayed.

Returns:

True if the compass is displayed; false otherwise.

enableMyLocation

public boolean enableMyLocation()

Attempts to enable MyLocation, registering for updates from LocationManager.GPS_PROVIDER and LocationManager.NETWORK_PROVIDER.

Returns:

true if we found at least one provider to enable. False if every one we tried was unavailable.

disableMyLocation

public void disableMyLocation()

Stops location updates.

It is safe to call this method even if location updates are currently disabled.

onSensorChanged

public void onSensorChanged(int sensor,
                            float[] values)

Called by the SensorManager when the compass value changes.

Specified by:

onSensorChanged in interface android.hardware.SensorListener

onLocationChanged

public void onLocationChanged(android.location.Location location)

Listener to get location updates from LocationManagerService.

Specified by:

onLocationChanged in interface android.location.LocationListener

onStatusChanged

public void onStatusChanged(java.lang.String provider,
                            int status,
                            android.os.Bundle extras)

Specified by:

onStatusChanged in interface android.location.LocationListener

onProviderEnabled

public void onProviderEnabled(java.lang.String provider)

Specified by:

onProviderEnabled in interface android.location.LocationListener

onProviderDisabled

public void onProviderDisabled(java.lang.String provider)

Specified by:

onProviderDisabled in interface android.location.LocationListener

onSnapToItem

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

Description copied from interface: Overlay.Snappable

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.

onTap

public boolean onTap(GeoPoint p,
                     MapView map)

Checks whether the location of the tap is close enough to the current location (if it's known). If so, passes on to dispatchTap(); otherwise returns false. Handle a "tap" event. This can be either a touchscreen tap anywhere on the map, or a trackball click on the center of the map. By default does nothing and returns false.

Overrides:

onTap in class Overlay

Parameters:

p - The point that has been tapped.

map - the MapView that generated the tap event

Returns:

True if the tap was handled by this overlay.

dispatchTap

protected boolean dispatchTap()

Handle a tap on the "my location" point. Default behavior does nothing and returns false.

Returns:

True if this tap was processed; false if it should be sent to the other overlays.

draw

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

Draw method. Does nothing on the shadow pass. On the non-shadow pass, calls through to drawMyLocation(android.graphics.Canvas, com.google.android.maps.MapView, android.location.Location, com.google.android.maps.GeoPoint, long) if we have a location fix, and then to drawCompass(android.graphics.Canvas, float) if we have a compass reading. We return false since we don't require an immediate redraw; however, a delayed invalidate may be posted on the viewToInvalidate passed to this class's constructor in order to trigger the next phase in the animation of the blue location dot.

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.

when - The timestamp of the draw.

Returns:

True if you need to be drawn again right away; false otherwise. Default implementation returns false.

drawMyLocation

protected void drawMyLocation(android.graphics.Canvas canvas,
                              MapView mapView,
                              android.location.Location lastFix,
                              GeoPoint myLocation,
                              long when)

Draw the "my location" dot. By default, draws an animated "blue dot" asset, possibly surrounded by an outlining blue disk to represent accuracy. Also, if the user's position moves near the edge of the screen, and we've been given a MapController in our constructor, we'll scroll to recenter the new reading.

Parameters:

canvas - the Canvas to draw to.

mapView - the mapView calling the draw.

lastFix - the last location fix we received.

myLocation - the coordinates of the last fix, extracted into handy GeoPoint form.

when - the drawing time, in milliseconds

drawCompass

protected void drawCompass(android.graphics.Canvas canvas,
                           float bearing)

Draw the compass inset. By default, draws a compass base and an arrow in the upper-left corner.

Parameters:

canvas - The Canvas to draw to.

bearing - The estimated bearing of the phone, in degrees east of north.

getMyLocation

public GeoPoint getMyLocation()

Returns a GeoPoint corresponding to the most-recently-set user location.

Returns:

The GeoPoint, or null if none has been set.

getLastFix

public android.location.Location getLastFix()

Returns a Location corresponding to the most-recently-set user location.

Returns:

The Location, or null if none has been set.

getOrientation

public float getOrientation()

Returns the most-recently-set compass bearing.

Returns:

The bearing, in degrees east of north, or NaN if none has been set.

isMyLocationEnabled

public boolean isMyLocationEnabled()

Checks whether location awareness is enabled (via GPS or network).

Returns:

True if location awareness is enabled; false otherwise.

runOnFirstFix

public boolean runOnFirstFix(java.lang.Runnable runnable)

Queues a runnable to be executed as soon as we have a location fix. If we already have a fix, we'll execute the runnable immediately and return true. If not, we'll hang on to the runnable and return false; as soon as we get a location fix, we'll run it in in a new thread.

onAccuracyChanged

public void onAccuracyChanged(int sensor,
                              int accuracy)

Specified by:

onAccuracyChanged in interface android.hardware.SensorListener