Build 1.0_r1(from source)

android.location
Class Location

java.lang.Object
  extended by android.location.Location
All Implemented Interfaces:
Parcelable

public class Location
extends Object
implements Parcelable

A class representing a geographic location sensed at a particular time (a "fix"). A location consists of a latitude and longitude, a UTC timestamp. and optionally information on altitude, speed, and bearing.

Information specific to a particular provider or class of providers may be communicated to the application using getExtras, which returns a Bundle of key/value pairs. Each provider will only provide those entries for which information is available.


Nested Class Summary
 
Nested classes/interfaces inherited from interface android.os.Parcelable
Parcelable.Creator<T>
 
Field Summary
static Parcelable.Creator<Location> CREATOR
           
static int FORMAT_DEGREES
          Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD.DDDDD where D indicates degrees.
static int FORMAT_MINUTES
          Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and M indicates minutes of arc (1 minute = 1/60th of a degree).
static int FORMAT_SECONDS
          Constant used to specify formatting of a latitude or longitude in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M indicates minutes of arc, and S indicates seconds of arc (1 minute = 1/60th of a degree, 1 second = 1/3600th of a degree).
 
Fields inherited from interface android.os.Parcelable
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
 
Constructor Summary
Location(Location l)
          Constructs a new Location object that is a copy of the given location.
Location(String provider)
          Constructs a new Location.
 
Method Summary
 float bearingTo(Location dest)
          Returns the approximate initial bearing in degrees East of true North when traveling along the shortest path between this location and the given location.
static String convert(double coordinate, int outputType)
          Converts a coordinate to a String representation.
static double convert(String coordinate)
          Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double.
 int describeContents()
          Describe the kinds of special objects contained in this Parcelable's marshalled representation.
static void distanceBetween(double startLatitude, double startLongitude, double endLatitude, double endLongitude, float[] results)
          Computes the approximate distance in meters between two locations, and optionally the initial and final bearings of the shortest path between them.
 float distanceTo(Location dest)
          Returns the approximate distance in meters between this location and the given location.
 float getAccuracy()
          Returns the accuracy of the fix in meters.
 double getAltitude()
          Returns the altitude of this fix.
 float getBearing()
          Returns the direction of travel in degrees East of true North.
 Bundle getExtras()
          Returns additional provider-specific information about the location fix as a Bundle.
 double getLatitude()
          Returns the latitude of this fix.
 double getLongitude()
          Returns the longitude of this fix.
 String getProvider()
          Returns the name of the provider that generated this fix, or null if it is not associated with a provider.
 float getSpeed()
          Returns the speed of the device over ground in meters/second.
 long getTime()
          Returns the UTC time of this fix, in milliseconds since January 1, 1970.
 boolean hasAccuracy()
          Returns true if the provider is able to report accuracy information, false otherwise.
 boolean hasAltitude()
          Returns true if this fix contains altitude information, false otherwise.
 boolean hasBearing()
          Returns true if the provider is able to report bearing information, false otherwise.
 boolean hasSpeed()
          Returns true if this fix contains speed information, false otherwise.
 void removeAccuracy()
          Clears the accuracy of this fix.
 void removeAltitude()
          Clears the altitude of this fix.
 void removeBearing()
          Clears the bearing of this fix.
 void removeSpeed()
          Clears the speed of this fix.
 void reset()
          Clears the contents of the location.
 void set(Location l)
          Sets the contents of the location to the values from the given location.
 void setAccuracy(float accuracy)
          Sets the accuracy of this fix.
 void setAltitude(double altitude)
          Sets the altitude of this fix.
 void setBearing(float bearing)
          Sets the bearing of this fix.
 void setExtras(Bundle extras)
          Sets the extra information associated with this fix to the given Bundle.
 void setLatitude(double latitude)
          Sets the latitude of this fix.
 void setLongitude(double longitude)
          Sets the longitude of this fix.
 void setProvider(String provider)
          Sets the name of the provider that generated this fix.
 void setSpeed(float speed)
          Sets the speed of this fix, in meters/second.
 void setTime(long time)
          Sets the UTC time of this fix, in milliseconds since January 1, 1970.
 String toString()
          Returns a string containing a concise, human-readable description of the receiver.
 void writeToParcel(Parcel parcel, int flags)
          Flatten this object in to a Parcel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

FORMAT_DEGREES

public static final int FORMAT_DEGREES
Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD.DDDDD where D indicates degrees.

See Also:
Constant Field Values

FORMAT_MINUTES

public static final int FORMAT_MINUTES
Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and M indicates minutes of arc (1 minute = 1/60th of a degree).

See Also:
Constant Field Values

FORMAT_SECONDS

public static final int FORMAT_SECONDS
Constant used to specify formatting of a latitude or longitude in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M indicates minutes of arc, and S indicates seconds of arc (1 minute = 1/60th of a degree, 1 second = 1/3600th of a degree).

See Also:
Constant Field Values

CREATOR

public static final Parcelable.Creator<Location> CREATOR
Constructor Detail

Location

public Location(String provider)
Constructs a new Location. By default, time, latitude, longitude, and numSatellites are 0; hasAltitude, hasSpeed, and hasBearing are false; and there is no extra information.

Parameters:
provider - the name of the location provider that generated this location fix.

Location

public Location(Location l)
Constructs a new Location object that is a copy of the given location.

Method Detail

set

public void set(Location l)
Sets the contents of the location to the values from the given location.


reset

public void reset()
Clears the contents of the location.


convert

public static String convert(double coordinate,
                             int outputType)
Converts a coordinate to a String representation. The outputType may be one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS. The coordinate must be a valid double between -180.0 and 180.0.

Throws:
IllegalArgumentException - if coordinate is less than -180.0, greater than 180.0, or is not a number.
IllegalArgumentException - if outputType is not one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS.

convert

public static double convert(String coordinate)
Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double.

Throws:
NullPointerException - if coordinate is null
IllegalArgumentException - if the coordinate is not in one of the valid formats.

distanceBetween

public static void distanceBetween(double startLatitude,
                                   double startLongitude,
                                   double endLatitude,
                                   double endLongitude,
                                   float[] results)
Computes the approximate distance in meters between two locations, and optionally the initial and final bearings of the shortest path between them. Distance and bearing are defined using the WGS84 ellipsoid.

The computed distance is stored in results[0]. If results has length 2 or greater, the initial bearing is stored in results[1]. If results has length 3 or greater, the final bearing is stored in results[2].

Parameters:
startLatitude - the starting latitude
startLongitude - the starting longitude
endLatitude - the ending latitude
endLongitude - the ending longitude
results - an array of floats to hold the results
Throws:
IllegalArgumentException - if results is null or has length <>

distanceTo

public float distanceTo(Location dest)
Returns the approximate distance in meters between this location and the given location. Distance is defined using the WGS84 ellipsoid.

Parameters:
dest - the destination location
Returns:
the approximate distance in meters

bearingTo

public float bearingTo(Location dest)
Returns the approximate initial bearing in degrees East of true North when traveling along the shortest path between this location and the given location. The shortest path is defined using the WGS84 ellipsoid. Locations that are (nearly) antipodal may produce meaningless results.

Parameters:
dest - the destination location
Returns:
the initial bearing in degrees

getProvider

public String getProvider()
Returns the name of the provider that generated this fix, or null if it is not associated with a provider.


setProvider

public void setProvider(String provider)
Sets the name of the provider that generated this fix.


getTime

public long getTime()
Returns the UTC time of this fix, in milliseconds since January 1, 1970.


setTime

public void setTime(long time)
Sets the UTC time of this fix, in milliseconds since January 1, 1970.


getLatitude

public double getLatitude()
Returns the latitude of this fix.


setLatitude

public void setLatitude(double latitude)
Sets the latitude of this fix.


getLongitude

public double getLongitude()
Returns the longitude of this fix.


setLongitude

public void setLongitude(double longitude)
Sets the longitude of this fix.


hasAltitude

public boolean hasAltitude()
Returns true if this fix contains altitude information, false otherwise.


getAltitude

public double getAltitude()
Returns the altitude of this fix. If hasAltitude() is false, 0.0f is returned.


setAltitude

public void setAltitude(double altitude)
Sets the altitude of this fix. Following this call, hasAltitude() will return true.


removeAltitude

public void removeAltitude()
Clears the altitude of this fix. Following this call, hasAltitude() will return false.


hasSpeed

public boolean hasSpeed()
Returns true if this fix contains speed information, false otherwise. The default implementation returns false.


getSpeed

public float getSpeed()
Returns the speed of the device over ground in meters/second. If hasSpeed() is false, 0.0f is returned.


setSpeed

public void setSpeed(float speed)
Sets the speed of this fix, in meters/second. Following this call, hasSpeed() will return true.


removeSpeed

public void removeSpeed()
Clears the speed of this fix. Following this call, hasSpeed() will return false.


hasBearing

public boolean hasBearing()
Returns true if the provider is able to report bearing information, false otherwise. The default implementation returns false.


getBearing

public float getBearing()
Returns the direction of travel in degrees East of true North. If hasBearing() is false, 0.0 is returned.


setBearing

public void setBearing(float bearing)
Sets the bearing of this fix. Following this call, hasBearing() will return true.


removeBearing

public void removeBearing()
Clears the bearing of this fix. Following this call, hasBearing() will return false.


hasAccuracy

public boolean hasAccuracy()
Returns true if the provider is able to report accuracy information, false otherwise. The default implementation returns false.


getAccuracy

public float getAccuracy()
Returns the accuracy of the fix in meters. If hasAccuracy() is false, 0.0 is returned.


setAccuracy

public void setAccuracy(float accuracy)
Sets the accuracy of this fix. Following this call, hasAccuracy() will return true.


removeAccuracy

public void removeAccuracy()
Clears the accuracy of this fix. Following this call, hasAccuracy() will return false.


getExtras

public Bundle getExtras()
Returns additional provider-specific information about the location fix as a Bundle. The keys and values are determined by the provider. If no additional information is available, null is returned.

A number of common key/value pairs are listed below. Providers that use any of the keys on this list must provide the corresponding value as described below.


setExtras

public void setExtras(Bundle extras)
Sets the extra information associated with this fix to the given Bundle.


toString

public String toString()
Description copied from class: Object
Returns a string containing a concise, human-readable description of the receiver.

Overrides:
toString in class Object
Returns:
String a printable representation for the receiver.

describeContents

public int describeContents()
Description copied from interface: Parcelable
Describe the kinds of special objects contained in this Parcelable's marshalled representation.

Specified by:
describeContents in interface Parcelable
Returns:
a bitmask indicating the set of special object types marshalled by the Parcelable.

writeToParcel

public void writeToParcel(Parcel parcel,
                          int flags)
Description copied from interface: Parcelable
Flatten this object in to a Parcel.

Specified by:
writeToParcel in interface Parcelable
Parameters:
parcel - The Parcel in which the object should be written.
flags - Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature