Titanium.Geolocation.Android

Module for Android-specific geolocation functionality.

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 achieve 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 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 LocationProvider object. To specify a location provider, create a new provider object, then register it with addLocationProvider:

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 LocationRule object. To specify a location rule, create a new rule object, then register it with addLocationRule:

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.

Extends: Titanium.Module · Since: 2.0.0 · Platforms: android

Properties #

apiName#

extended

Type: 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, Button
returns Ti.UI.Button.

bubbleParent#

extended

Type: 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.

lifecycleContainer#

extended

Type: 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#

Type: 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.

PROVIDER_GPS#

Type: String

Specifies the GPS location provider.

Used with LocationProvider.name,
LocationRule.provider.
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#

Type: String

Specifies the network location provider.

Used with LocationProvider.name,
LocationRule.provider.
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#

Type: String

Specifies the passive location provider.

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

Methods #

addEventListener #

extended

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

Parameters:

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

addLocationProvider #

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	Summary	Optional
`provider`	`Titanium.Geolocation.Android.LocationProvider`	The location provider to add.	No

addLocationRule #

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	Summary	Optional
`rule`	`Titanium.Geolocation.Android.LocationRule`	The location rule to add.	No

applyProperties #

extended

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	Summary	Optional
`props`	`Dictionary`	A dictionary of properties to apply.	No

fireEvent #

extended

Fires a synthesized event to any registered listeners.

Parameters:

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

removeEventListener #

extended

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	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to remove. Must be the same function passed to `addEventListener`.	No

removeLocationProvider #

Disables and removes the specified location provider.

Parameters:

Name	Type	Summary	Optional
`provider`	`Titanium.Geolocation.Android.LocationProvider`	The location provider to remove.	No

removeLocationRule #

Disables and removes the specified location rule.

Parameters:

Name	Type	Summary	Optional
`rule`	`Titanium.Geolocation.Android.LocationRule`	The location rule to remove.	No

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.Geolocation.Android ​

Enabling Manual Configuration Mode ​

Location Providers ​

Location Rules ​

Properties #

apiName#

bubbleParent#

lifecycleContainer#

manualMode#

PROVIDER_GPS#

PROVIDER_NETWORK#

PROVIDER_PASSIVE#

Methods #

addEventListener #

addLocationProvider #

addLocationRule #

applyProperties #

fireEvent #

removeEventListener #

removeLocationProvider #

removeLocationRule #

Titanium.Geolocation.Android

Enabling Manual Configuration Mode

Location Providers

Location Rules