Geolocation Classes

The flash.events.GeolocationEvent class is a new Event object that contains updated geolocation information. The new flash.sensors.Geolocation class is a subclass of the EventDispatcher class. It listens for and receives information from the device’s location sensor in the form of a GeolocationEvent.

To use the geolocation classes, first you must add the necessary permissions. In Flash Professional, enable ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION device permissions under File→AIR Android Settings→Permissions. In Flash Builder, select ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE under Mobile Settings→Permissions. To make changes, append your application manifest file as follows:

<uses-permission android:name=”android.permission.ACCESS_FINE_LOCATION” />
<uses-permission android:name=”android.permission.ACCESS_COARSE_LOCATION” />

Fine location refers to GPS communication, while coarse location refers to network communication.

During development and testing, you must select the checkboxes on your device in Android Settings→Location and Security→Use GPS satellites and Android Settings→Location and Security→Use wireless networks to enable both sensors, as shown in Figure 10-1.

Next, verify that the device running your application supports geolocation:

import flash.sensors.Geolocation;
import flash.events.GeolocationEvent;
if (Geolocation.isSupported) {
// geolocation supported
}

Now let’s write a simple application to listen to geolocation event updates. Make geolocation a class variable, not a local variable, to guarantee that it does not get out of scope:

import flash.sensors.Geolocation;
import flash.events.GeolocationEvent;
var geolocation:Geolocation;
if (Geolocation.isSupported) {
geolocation = new Geolocation();
geolocation.addEventListener(GeolocationEvent.UPDATE, onTravel);
}
function onTravel(event:GeolocationEvent):void {
trace(event.latitude);
trace(event.longitude);
}

You should see your current latitude and longitude in degrees as floating-point values. My home location, for instance, is latitude 40.74382781982420 and longitude 74.00146007537840.

The user has the ability to enable or disable access to the location sensor on the device. Check the geolocation muted boolean property when you first run your application to see its value. You should also create a listener to receive status updates in case the property changes while the application is running:

import flash.events.StatusEvent;
if (!geolocation.muted) {
geolocation.addEventListener(StatusEvent.STATUS, onStatusChange);
} else {
// inform the user to turn on the location sensor
}
function onStatusChange(event:StatusEvent):void {
trace(“status:” + event.code);
if (event.code == “Geolocation.Muted”) {
// inform the user to turn on the location sensor
}
}

If muted is true, or if event.code is equal to Geolocation.Muted, display a message to the user requesting the need for location data.

The GeolocationEvent Class

A GeolocationEvent.UPDATE event is delivered when the listener is first created. Then, it is delivered when a new location update is received from the device/platform. An event is also delivered if the application wakes up after being in the background.

Using the geolocation API drains the battery very quickly. In an effort to save battery life, control the frequency of updates by setting an update interval on the geoloca tion object. Unless you are moving very quickly and want to check your speed, you don’t need to check your location more than once every few seconds or minutes:

geolocation.setRequestedUpdateInterval(10000);

If not specified by you, the updates are based on the device/platform default interval. Look up the hardware documentation if you want to know the device default interval; this is not something you can get in the Android or AIR API.

The Earth is divided using a grid system with latitude from the equator toward the North and South Poles and longitude from Greenwich, England, to the international date line in the Pacific Ocean. Values are positive from the equator going north and from Greenwich going east. Values are negative from the equator going south and from Greenwich going west.

The GeolocationEvent properties are as follows:

• event.latitude ranges from ‒90 to 90 degrees and event.longitude ranges from ‒ 180 to 180 degrees. They are both of data type Number for greater precision.
• event.horizontalAccuracy and event.verticalAccuracy are in meters. This value comes back from the location service and represents how accurate the data is. A small number represents a better reading. Less than 60 meters is usually considered GPS accurate. This measurement may change as the technology improves.
• event.timeStamp is in milliseconds and starts counting from the moment the application initializes. If you need to get a regular update, use a timer instead of GeolocationEvent because it may not fire up at regular intervals.
• event.altitude is in meters and event.speed is in meters/second.
• event.heading, moving toward true north, is an integer. It is not supported on Android devices at the time of this writing, and it returns a value of NaN (Not a Number). However, you can calculate it by comparing longitude and latitude over time to determine a direction, assuming your device moves fast enough.

When your application moves to the background, the geolocation sensor remains active. If you want to overwrite the default behavior, listen to Native Application Event.DEACTIVATE to remove the event listener and Event.ACTIVATE to set it again.

When you first register for geolocation updates, AIR sets location listeners. It also queries for the LastKnownLocation and sends it as the first update. Because it is cached, the initial data may be incorrect until a first real location update is received.