# Titanium.Geolocation.Android

Module for Android-specific geolocation functionality.

Availability

2.0.0

Extends

# Overview

This module is used for manually configuring geolocation settings on Android.

Manual configuration is recommended for applications that have more demanding geolocation needs (for example, driving directions). However, for basic geolocation information, simple mode geolocation may be sufficient. For information on simple mode, see Titanium.Geolocation.

Manual configuration involves managing providers and rules:

Location providers, such as GPS, provide location updates.
Location rules filter the results returned by location providers.

Configuring geolocation manually involves three steps:

Enabling manual mode.
Enabling location providers.
Adding location rules (optional).

As with the other modes, you register for location updates using the main Titanium.Geolocation module. Location updates are generated as long as an event listener is registered for the location event. When you are not using location updates, you should remove any registered event listeners.

In manual mode, the application is responsible for dynamically updating the settings to acheive its required accuracy while limiting battery usage. For example, an application might do any of the following:

If the application isn't getting updates frequently enough, it can adjust its provider settings to provide more updates, or relax its location rules to allow less accurate updates through.
If the application isn't receiving accurate enough updates from one provider, it can add another provider to try to improve results.
If the application is getting sufficiently accurate results from the network provider, it can disable the GPS provider to save power.

# Enabling Manual Configuration Mode

To enable manual configuration mode, set the Titanium.Geolocation.Android.manualMode property to true. In manual configuration mode, the location providers and location rules set through this module control the generation of location updates.

When manualMode is true, the following configuration settings in the Titanium.Geolocation module are ignored:

When manualMode is false, the accuracy, frequency and preferredProvider settings from Titanium.Geolocation are used to configure location updates. Any location providers and location rules set in Titanium.Geolocation.Android are retained, but they have no effect.

# Location Providers

Android supports three kinds of location providers: GPS, network, and the "passive" location provider, which provides only cached information.

Each location provider represents a different tradeoff between accuracy and battery power. For most accurate results, you can use a combination of location providers. Your application can also dynamically change providers to optimize battery life (for example, if the network provider is providing good enough location updates, you can disable the GPS provider).

Location providers are represented by the Titanium.Geolocation.Android.LocationProvider object. To specify a location provider, create a new provider object, then register it with Titanium.Geolocation.Android.createLocationProvider:

var gpsProvider = Ti.Geolocation.Android.createLocationProvider({
    name: Ti.Geolocation.Android.PROVIDER_GPS,
    minUpdateTime: 60, 
    minUpdateDistance: 100
});
Ti.Geolocation.Android.addLocationProvider(gpsProvider);

As shown above, when you create a location provider, you can specify two properties to limit update frequency:

minUpdateTime. Limits the frequency of location updates to no more than one per minUpdateTime seconds.
minUpdateDistance. Don't send location updates until the location changes at least minUpdateDistance meters.

Only one provider of each type (GPS, network, passive) can be registered at a time. Adding a new location provider with the same name value replaces any existing provider with the same name.

Once a location provider is added, changes made to the location provider object itself (such as changing its minUpdateTime value) change the active configuration of the location system.

# Location Rules

Location Rules filter the results returned by location providers. You use location rules to reduce the number of location update events, and ensure that the events you do receive are as accurate and recent as your application requires.

You are not required to set any location rules. However, by reducing the number of location events that are passed from the native code to the JavaScript layer, location rules can improve both performance and battery life.

Location rules are represented by the Titanium.Geolocation.Android.LocationProvider object. To specify a location rule, create a new rule object, then register it with Titanium.Geolocation.Android.createLocationProvider:

var gpsRule = Ti.Geolocation.Android.createLocationRule({
    provider: Ti.Geolocation.PROVIDER_GPS,
    // Updates should be accurate to 100m
    accuracy: 100,
    // Updates should be no older than 5m
    maxAge: 300000
    // But  no more frequent than once per 10 seconds
    minAge: 10000
});
Ti.Geolocation.Android.addLocationRule(gpsRule);

Each rule can specify any combination of the following criteria:

provider. If specified, this rule only applies to updates generated by the specified provider. If not specified, this rule applies to all updates.
accuracy. Minimum accuracy required for a location update. Accuracy is expressed as the maximum allowable error, in meters. Updates with reported accuracy values greater than this are filtered out.
minAge. Controls the frequency of location updates. Do not forward an update unless at least minAge milliseconds have passed since the last good location update.
maxAge. Controls the freshness of location updates. Do not forward an update unless it is newer than maxAge milliseconds.

You can specify as many location rules as you like. The order in which location rules are added is not significant. For a location event to be generated, the location update must pass all of the active rules.

Note that some combinations of rules may make it very difficult to get location updates. In particular, very low values for either accuracy or maxAge may prevent results from getting through.

# Properties

# apiName READONLY

Availability

3.2.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability

3.0.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# lifecycleContainer

Availability

3.6.0

lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# manualMode

Availability

2.0.0

manualMode :Boolean

Set to true to enable manual configuration of location updates through this module.

If true, location updates are controlled by the location providers and location rules configured in this module.

If false, location updates are configured using the accuracy, frequency and preferredProvider properties in the Titanium.Geolocation module.

Default: false

# Methods

# addEventListener

Availability

2.0.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type: void

# addLocationProvider

Availability

2.0.0

addLocationProvider(provider) → void

Adds and enables the specified location provider, possibly replacing an existing one.

If another location provider with the same name value is already active, the new location provider replaces the exiting one.

Parameters

Name	Type	Description
`provider`	Titanium.Geolocation.Android.LocationProvider	The location provider to add.

Returns

Type: void

# addLocationRule

Availability

2.0.0

addLocationRule(rule) → void

Adds and enables the specified location rule.

Only location updates that pass all of the active rules are passed on to the application.

Parameters

Name	Type	Description
`rule`	Titanium.Geolocation.Android.LocationRule	The location rule to add.

Returns

Type: void

# applyProperties

Availability

3.0.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
`props`	Dictionary	A dictionary of properties to apply.

Returns

Type: void

# createLocationProvider

Availability

2.0.0

createLocationProvider([parameters]) → Titanium.Geolocation.Android.LocationProvider

Creates and returns an instance of Titanium.Geolocation.Android.LocationProvider.

Parameters

Name	Type	Description
`parameters`	Dictionary<Titanium.Geolocation.Android.LocationProvider>	Properties to set on a new object, including any defined by Titanium.Geolocation.Android.LocationProvider except those marked not-creation or read-only.

Returns

Type: Titanium.Geolocation.Android.LocationProvider

# createLocationRule

Availability

2.0.0

createLocationRule([parameters]) → Titanium.Geolocation.Android.LocationRule

Creates and returns an instance of Titanium.Geolocation.Android.LocationRule.

Parameters

Name	Type	Description
`parameters`	Dictionary<Titanium.Geolocation.Android.LocationRule>	Properties to set on a new object, including any defined by Titanium.Geolocation.Android.LocationRule except those marked not-creation or read-only.

Returns

Type: Titanium.Geolocation.Android.LocationRule

# fireEvent

Availability

2.0.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`event`	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type: void

# removeEventListener

Availability

2.0.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`.

Returns

Type: void

# removeLocationProvider

Availability

2.0.0

removeLocationProvider(provider) → void

Disables and removes the specified location provider.

Parameters

Name	Type	Description
`provider`	Titanium.Geolocation.Android.LocationProvider	The location provider to remove.

Returns

Type: void

# removeLocationRule

Availability

2.0.0

removeLocationRule(rule) → void

Disables and removes the specified location rule.

Parameters

Name	Type	Description
`rule`	Titanium.Geolocation.Android.LocationRule	The location rule to remove.

Returns

Type: void

# Constants

# PROVIDER_GPS

Availability

2.0.0

PROVIDER_GPS :String

Specifies the GPS location provider.

Used with Titanium.Geolocation.Android.LocationProvider, Titanium.Geolocation.Android.LocationRule. In general, the GPS provider has the highest power consumption and the highest accuracy, but this may vary. In some circumstances, the network provider may be more reliable.

# PROVIDER_NETWORK

Availability

2.0.0

PROVIDER_NETWORK :String

Specifies the network location provider.

Used with Titanium.Geolocation.Android.LocationProvider, Titanium.Geolocation.Android.LocationRule. Generally requires less power than the GPS provider and provides less accurate results, but may produce very accurate results in densely-populated areas with many cell towers and WiFi networks.

# PROVIDER_PASSIVE

Availability

2.0.0

PROVIDER_PASSIVE :String

Specifies the passive location provider.

Used with Titanium.Geolocation.Android.LocationProvider, Titanium.Geolocation.Android.LocationRule. This provider only uses cached location information, so it does not use any power, but makes no guarantee that the location results are recent.