android.location
public class
public class
android.location.Location
| java.lang.Object | ||
| android.location.Location | 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. Some common keys are:
- "satellites" - returns the number of satellites used to obtain the fix
Summary
Constants
| Value | ||||
|---|---|---|---|---|
| Creator | CREATOR | |||
| int | FORMAT_DEGREES | Constant used to specify formatting of a latitude or longitude in the form "[[]+-]DDD.DDDDD where D indicates degrees. | 0 | 0x00000000 |
| 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). | 1 | 0x00000001 |
| 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 dgeree, 1 second = 1/3600th of a degree). | 2 | 0x00000002 |
Public Constructors
| Location() | |||||
| Constructs a new Location. | |||||
| Location(Location l) | |||||
| Constructs a new Location object that is a copy of the given location. | |||||
Public Methods
| 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. | |||||
| float | distanceTo(Location dest) | ||||
| Returns the approximate distance in meters between this location and the given location. | |||||
| 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 | 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 | removeAltitude() | ||||
| Clears the altitude of this fix. | |||||
| void | removeBearing() | ||||
| Clears the bearing of this fix. | |||||
| void | removeSpeed() | ||||
| Clears the speed 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() | ||||
| Answers a string containing a concise, human-readable description of the receiver. | |||||
| void | writeToParcel(Parcel parcel) | ||||
Methods inherited
from class
java.lang.Object
Methods inherited
from interface
android.os.Parcelable
Details
Constants
public static final Creator CREATOR
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.
Constant Value:
0
(0x00000000)
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).
Constant Value:
1
(0x00000001)
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 dgeree, 1 second = 1/3600th of a degree).
Constant Value:
2
(0x00000002)
Public Constructors
public Location()
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.
public Location(Location l)
Constructs a new Location object that is a copy of the given
location.
Public Methods
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
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. |
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. |
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
public double getAltitude()
Returns the altitude of this fix. If mHasAltitude is false,
0.0f is returned.
public float getBearing()
Returns the direction of travel in degrees East of true
North. If hasBearing() is false, 0.0 is returned.
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.
- accuracy - estimated accuracy in meters
- satellites - the number of satellites used to derive the fix
public double getLatitude()
Returns the latitude of this fix.
public double getLongitude()
Returns the longitude of this fix.
public String getProvider()
Returns the name of the provider that generated this fix,
or null if it is not associated with a provider.
public float getSpeed()
Returns the speed of the device over ground in meters/second.
If hasSpeed() is false, 0.0f is returned.
public long getTime()
Returns the UTC time of this fix, in milliseconds since January 1,
1970.
public boolean hasAltitude()
Returns true if this fix contains altitude information, false
otherwise.
public boolean hasBearing()
Returns true if the provider is able to report bearing information,
false otherwise. The default implementation returns false.
public boolean hasSpeed()
Returns true if this fix contains speed information, false
otherwise. The default implementation returns false.
public void removeAltitude()
Clears the altitude of this fix. Following this call,
hasAltitude() will return false.
public void removeBearing()
Clears the bearing of this fix. Following this call, hasBearing()
will return false.
public void removeSpeed()
Clears the speed of this fix. Following this call, hasSpeed()
will return false.
public void setAltitude(double altitude)
Sets the altitude of this fix. Following this call,
hasAltitude() will return true.
public void setBearing(float bearing)
Sets the bearing of this fix. Following this call, hasBearing()
will return true.
public void setExtras(Bundle extras)
Sets the extra information associated with this fix to the
given Bundle.
public void setLatitude(double latitude)
Sets the latitude of this fix.
public void setLongitude(double longitude)
Sets the longitude of this fix.
public void setProvider(String provider)
Sets the name of the provider that generated this fix.
public void setSpeed(float speed)
Sets the speed of this fix, in meters/second. Following this
call, hasSpeed() will return true.
public void setTime(long time)
Sets the UTC time of this fix, in milliseconds since January 1,
1970.
public String toString()
Answers a string containing a concise, human-readable description of the
receiver.