Android

com.google.android.maps.MyLocationOverlay

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

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 onResume() method, to enable the features of this overlay. Remember to call the corresponding disableMyLocation() and/or disableCompass() in your Activity's 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 postInvalidate() when location or orientation is changed.

Runnables can be provided in runOnFirstFix(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.)

Summary

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

Public Constructors

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

Public Methods

  synchronized        void  disableCompass()
Disable updates from the compass sensor.
  synchronized        void  disableMyLocation()
Stops location updates.
  synchronized        boolean  draw(Canvas canvas, MapView mapView, boolean shadow, long when)
Draw method.
  synchronized        boolean  enableCompass()
Enable updates from the compass sensor.
  synchronized        boolean  enableMyLocation()
Attempts to enable MyLocation, registering for updates from GPS_PROVIDER first and NETWORK_PROVIDER second.
          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  isMyLocationEnabled()
Checks whether location awareness is enabled (via GPS or network).
  synchronized        void  onLocationChanged(Location location)
Listener to get location updates from LocationManagerService.
          void  onProviderDisabled(String provider)
Called when the provider is disabled by the user.
          void  onProviderEnabled(String provider)
Called when the provider is enabled by the user.
  synchronized        void  onSensorChanged(int sensor, float[] values)
Called by the SensorManager when the compass value changes.
          void  onStatusChanged(String provider, int status)
          void  onStatusChanged(String provider, int status, Bundle extras)
Called when the provider status changes.
          boolean  onTap(GeoPoint p, MapView map)
Checks whether the location of the tap is close enough to the current location (if it's known).
  synchronized        boolean  runOnFirstFix(Runnable runnable)
Queues a runnable to be executed as soon as we have a location fix.

Protected Methods

          boolean  dispatchTap()
Handle a tap on the "my location" point.
          void  drawCompass(Canvas canvas, float bearing)
Draw the compass inset.
          void  drawMyLocation(Canvas canvas, MapView mapView, Location lastFix, GeoPoint myLocation, long when)
Draw the "my location" dot.
Methods inherited from class com.google.android.maps.Overlay
Methods inherited from class java.lang.Object
Methods inherited from interface android.hardware.SensorListener
Methods inherited from interface android.location.LocationListener

Details

Public Constructors

public MyLocationOverlay(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

IllegalArgumentException if mapView is null.

Public Methods

public synchronized void disableCompass()

Disable updates from the compass sensor.

public synchronized void disableMyLocation()

Stops location updates.

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

public synchronized boolean draw(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(Canvas, MapView, Location, GeoPoint, long) if we have a location fix, and then to drawCompass(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.

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.
when The timestamp of the draw.

Returns

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

public synchronized 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.

public synchronized boolean enableMyLocation()

Attempts to enable MyLocation, registering for updates from GPS_PROVIDER first and NETWORK_PROVIDER second. A no-op if MyLocation is already enabled.

Returns

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

public Location getLastFix()

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

Returns

  • The Location, or null if none has been set.

public GeoPoint getMyLocation()

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

Returns

  • The GeoPoint, or null if none has been set.

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.

public boolean isMyLocationEnabled()

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

Returns

  • True if location awareness is enabled; false otherwise.

public synchronized void onLocationChanged(Location location)

Listener to get location updates from LocationManagerService. Called when the location has changed.

There are no restrictions on the use of the supplied Location object.

public void onProviderDisabled(String provider)

Called when the provider is disabled by the user. If requestLocationUpdates is called on an already disabled provider, this method is called immediately.

public void onProviderEnabled(String provider)

Called when the provider is enabled by the user.

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

Called by the SensorManager when the compass value changes.

public void onStatusChanged(String provider, int status)

public void onStatusChanged(String provider, int status, Bundle extras)

Called when the provider status changes. This method is called when a provider is unable to fetch a location or if the provider has recently become available after a period of unavailability.

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.

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.

public synchronized boolean runOnFirstFix(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.

Protected Methods

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.

protected void drawCompass(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.

protected void drawMyLocation(Canvas canvas, MapView mapView, 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
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56