Titanium Mobile API Guide

Titanium Mobile supports a number of key mobile specific features. Below is a high level set of those features and how they're used.

Geolocation

The Geolocation API provides relatively accurate location information for the phone device. The information is generally phone specific but each phone uses a set of different mechanisms to determine your location, usually including GPS, Wi-Fi and Cell Tower information.

Titanium provides a generalized API for accessing location information. Geolocation is an asynchronous API since retrieving position information can take up to 1-3 seconds depending on a number of factors. Additionally, for iPhone, the end-user must grant permission to the application before location information can be obtained.

Example usage:

var watchId = Titanium.Geolocation.watchPosition(function(pos) 
{
   var coords = pos.coords;
   var dlg = Titanium.UI.createAlertDialog({
    'title' : 'Location Identified',
    'message' : 'Your position is: '+coords.latitude+' latitude',
    'buttonNames' : [ 'OK' ]
   });
   dlg.show();
});

In the above example, as the position changes, the callback will be called with the updated location information. Generally, this is only useful for use cases where a constant stream of position updates might be required (such as turn-by-turn directions).

In most cases, you only want the position as it exists at the time needed. In this case, a more optimal usage would be:

var watchId = Titanium.Geolocation.getCurrentPosition(function(pos) 
{
   var coords = pos.coords;
   var dlg = Titanium.UI.createAlertDialog({
    'title' : 'Location Identified',
    'message' : 'Your position is: '+coords.latitude+' latitude',
    'buttonNames' : [ 'OK' ]
   });
   dlg.show();
});

This will only return the location information once. This API method is more optimal since it doesn't continually track position changes.

Accelerometer

Both iPhone and Android phones have a set of accelerometers (usually a three-axis accelerometer) in the phone that provide detailed set of information about the orientation and movement of the phone.

Titanium provides both a low-level API for detailed accelerometer changes as well as a high-level API for more generalized motions events.

The low-level API gives you the lowest level of detailed to give your application maximum flexibility of determining the mathematics required to drive you application. The high-level API attempts to implement the mathematics for your application for some of the more common accelerometer and motion events such as "shake".

Low-Level

The Accelerometer API is used for low-level API access. For example:

Titanium.Accelerometer.addEventListener('update',function(e)
{
   document.getElementById('x').innerHTML = e.x;
   document.getElementById('y').innerHTML = e.y;
   document.getElementById('z').innerHTML = e.z
});

The x value corresponds to the roll (or rotation) around the axis that runs from the main button to your earpiece.

The y value is the pitch of the device. The middle of the phone (looking directly at the device head-on) and it's the axis around which the Y value rotates.

The z value is the face up or face down value.

NOTE: these values usually need to be normalized with a high-pass or low-pass filter to filter out minor movements and sensitivity of the accelerometers.

A high-pass filter will remove the gravity component and gives you changes in the motion of the device. This is useful when you need to recognize major movements such as when the phone is being shaken.

A low-pass filter will remove the motion component and just keeps gravity. This is useful for finding how far the user has moved the device (such as a tilt) and essentially filters out noise from slight movements of the device.

For more information about iPhone accelerometer values, please see this article on iphone accelerometer positions.

High-Level

The high-level API provides some common event listeners that will fire when certain motion events happen, based on a per-configured set of mathematics. These APIs are part of the Titanium.Gesture namespace.

Example usage:

function onShake()
{
   document.getElementById("status").innerHTML = 'Stop Shaking me';   
}
var listenerId = Titanium.Gesture.addEventListener("shake", onShake);

The following events are currently supported:

  • shake - fires an event to gesture listeners when the phone is shaken more than 2-3 times (generally).
  • orientationchange - fires an event to gesture listener when the phone orientation changes.

Sometimes you need to determine the orientation programatically. You can use the Titanium.Gesture.isPortrait or Titanium.Gesture.isLandscape methods to determine the orientation of the device.

Example usage:

Titanium.Gesture.addEventListener('orientationchange',function(e)
{
   if (Titanium.Gesture.isLandscape(e.to))
   {
     // you're now in landscape
   } 
   else if (Titanium.Gesture.isPortrait(e.to)) 
   {
     // you're now in portrait
   }
});

Device Information

Titanium provides certain device information about the phone.

Phone / Platform info

The following common properties are available which:

Network info

The following common network properties are available:

Application info

The following common application methods are available:

Titanium info

Sometimes it's useful to determine which version of Titanium you're running. You can use the Titanium.version property for this.

Last Modified on July 7, 2009, 08:07 AM by Jeff Haynie Edit | History