flash.sensors

# Geolocation - AS3

Package | flash.sensors
Class | public class Geolocation
Inheritance | Geolocation EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

The Geolocation class dispatches events in response to the device's location sensor.

If a device supports geolocation, you can use this class to obtain the current geographical location of the device. The geographical location is displayed on the device in the form of latitudinal and longitudinal coordinates (in WGS-84 standard format). When the location of the device changes, you can receive updates about the changes. If the device supports this feature, you will be able to obtain information about the altitude, accuracy, heading, speed, and timestamp of the latest change in the location.

AIR profile support: This feature is supported only on mobile devices. It is not supported on desktop or AIR for TV devices. You can test for support at run time using the `Geolocation.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

Note: To enable Geolocation in iOS, ensure that you add a key-value pair to the `infoAdditions` element in the application xml file.See iOS Settings for more information on the `infoAdditions` element.

View the examples

More examples

Detecting geolocation changes

Learn more

Cristophe Coenraets: Mulit-user Google Maps Collaboration

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | isSupported : Boolean [static] [read-only] Whether a location sensor is available on the device (true); otherwise false. | Geolocation
|  | muted : Boolean [read-only] Specifies whether the user has denied access to the geolocation (true) or allowed access (false). | Geolocation
|  | permissionStatus : String [static] [read-only] | Geolocation

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Geolocation() Creates a new Geolocation instance. | Geolocation
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | requestPermission():void | Geolocation
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | setRequestedUpdateInterval(interval:Number):void Used to set the time interval for updates, in milliseconds. | Geolocation
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | permissionStatus |  | Geolocation
|  | status | The Geolocation object dispatches status events when the user changes access to the location sensor. | Geolocation
|  | update | The update event is dispatched in response to updates from the location sensor. | Geolocation

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Whether a location sensor is available on the device (`true`); otherwise `false`.

Implementation
`public static function get isSupported():Boolean`

More examples

Checking geolocation support

### muted

property

`muted:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Specifies whether the user has denied access to the geolocation (`true`) or allowed access (`false`). When this value changes, a `status` event is dispatched.

Implementation
`public function get muted():Boolean`

Related API Elements

status

### permissionStatus

property

`permissionStatus:String` [read-only]

Implementation
`public static function get permissionStatus():String`
Constructor Detail

### Geolocation

()
Constructor

`public function Geolocation()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Creates a new Geolocation instance.

Method Detail

### requestPermission

()
method

`public function requestPermission():void`

### setRequestedUpdateInterval

()
method

`public function setRequestedUpdateInterval(interval:Number):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Used to set the time interval for updates, in milliseconds. The update interval is only used as a hint to conserve the battery power. The actual time between location updates may be greater or lesser than this value.Any change in the update interval using this method affects all registered `update` event listeners. The Geolocation class can be used without calling the `setRequestedUpdateInterval` method. In this case, the platform will return updates based on its default interval.

Note: First-generation iPhones, which do not include a GPS unit, dispatch `update` events only occasionally. On these devices, a Geolocation object initially dispatches one or two `update` events. It then dispatches `update` events when information changes noticeably.

Parameters

| `interval:Number` — requested update interval. If `interval` <= 0, then any call to this method has no effect.

Throws

| `ArgumentError` — The specified `interval` is less than zero.

Event Detail

### permissionStatus

Event

Event Object Type: `flash.events.PermissionEvent`

### status

Event

Event Object Type: `flash.events.StatusEvent`
property StatusEvent.type = `flash.events.StatusEvent.STATUS`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

The Geolocation object dispatches `status` events when the user changes access to the location sensor. For example, if, in response to a device prompt, the user prevents the application from accessing location data, the Geolcation object dispatches a `status` event. When the status changes to a state where the location sensor is not available, the `muted` property of the Geolocation instance is `true`.

Defines the value of the `type` property of a `status` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`code` | A description of the object's status.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`level` | The category of the message, such as `"status"`, `"warning"` or `"error"`.
`target` | The object reporting its status.

Related API Elements

muted

### update

Event

Event Object Type: `flash.events.GeolocationEvent`
property GeolocationEvent.type = `flash.events.GeolocationEvent.UPDATE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

The `update` event is dispatched in response to updates from the location sensor. The event is dispatched under the following circumstances:

- When a new listener function is attached through `addEventListener()`, this event is delivered once to all the registered listeners to provide the current value of the location. Note: AIR dispatches the first event immediately if the device has a last known location; your code must be aware that the initially dispatched event may not contain the current location.
- Whenever location updates are obtained from the platform at device determined intervals.
- Whenever the application misses a change in the location (for example, the application is waking up after being asleep).

Note: First-generation iPhones, which do not include a GPS unit, dispatch `update` events only occasionally. On these devices, a Geolocation object initially dispatches one or two `update` events. It then dispatches `update` events when information changes noticeably.

Defines the value of the `type` property of a `GeolocationEvent` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The Geolocation object receiving data.

Examples How to use this example
GeolocationExample.as
In the following example, the application displays the latitude, longitude, and horizontal accuracy of geolocation `update` events as they are received.
Copy

    package
    {
        import flash.display.Sprite;
        import flash.display.StageAlign;
        import flash.display.StageScaleMode;
        import flash.events.GeolocationEvent;
        import flash.events.MouseEvent;
        import flash.events.StatusEvent;
        import flash.sensors.Geolocation;
        import flash.text.TextField;
        import flash.text.TextFormat;

        public class GeolocationTest extends Sprite
        {

            private var geo:Geolocation;
            private var log:TextField;

            public function GeolocationTest()
            {
                super();
                stage.align = StageAlign.TOP_LEFT;
                stage.scaleMode = StageScaleMode.NO_SCALE;
                setUpTextField();

                if (Geolocation.isSupported)
                {
                    geo = new Geolocation();
                    if (!geo.muted)
                    {
                        geo.addEventListener(GeolocationEvent.UPDATE, geoUpdateHandler);
                    }
                    geo.addEventListener(StatusEvent.STATUS, geoStatusHandler);
                }
                else
                {
                    log.text = "Geolocation not supported";
                }
            }

            public function geoUpdateHandler(event:GeolocationEvent):void
            {
                log.text = "latitude : " + event.latitude.toString() + "\n";
                log.appendText("longitude : " + event.longitude.toString() + "\n");
            }

            public function geoStatusHandler(event:StatusEvent):void
            {
                if (geo.muted)
                    geo.removeEventListener(GeolocationEvent.UPDATE, geoUpdateHandler);
                else
                    geo.addEventListener(GeolocationEvent.UPDATE, geoUpdateHandler);
            }

            private function setUpTextField():void
            {
                log = new TextField();
                var format:TextFormat = new TextFormat("_sans", 24);
                log.defaultTextFormat = format;
                log.border = true;
                log.wordWrap = true;
                log.multiline = true;
                log.x = 10;
                log.y = 10;
                log.height = stage.stageHeight - 20;
                log.width = stage.stageWidth - 20;
                log.addEventListener(MouseEvent.CLICK, clearLog);
                addChild(log);
            }
            private function clearLog(event:MouseEvent):void
            {
                log.text = "";
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00