# Titanium.Android
The top-level Android module.
# Overview
The Android module allows the application to manage various Android components.
# Action Bar
An action bar is a UI feature that identifies the application and user location, and provides user actions and navigation modes.
The Titanium SDK lets you customize the look of the action bar and add action items. Action items are added using the Titanium.Android.Menu API.
For more information about the action bar, see the Titanium.Android.ActionBar.
# Activities
An Android application is made up of one or more activities. Each activity represents a single screen with a user interface.
In Titanium, each Window
or TabGroup
has its own activity. The application
can access the activity of a Window
and TabGroup
object and monitor its lifecycle events.
Titanium also lets you launch new activities by creating intents to launch them.
See the "Intents" section below.
For more information about activities, see the Titanium.Android.Activity.
# Broadcast Intents and Receivers
Broadcast Intents allow your application to send out a message to any application that sets up a Broadcast Receiver to listen to it. Your application can also register Broadcast Receivers to listen to system events sent by the Android OS, such as low battery warnings or airplane mode changes.
For more information about broadcasts, see the Android Broadcast Intents and Receivers guide (opens new window) and Titanium.Android.BroadcastReceiver.
# Intents
Intents are message objects that specify actions to perform which can start either activities, broadcasts or services.
For more information about intents, see the Titanium.Android.Intent.
# Intent Filters
Intent Filters advertise to the Android OS that your application handles certain actions and data types. For example, when another application wants to share an image or text, your application can define intent filters to let Android know your application can handle those data types.
For more information about intent filters, see the Android Intent Filters guide (opens new window).
# Notifications
Notifications alert the user that something is happening to your application while it is in the background. Notifications appear in the notification drawer until the user clears them and on the lock screen for devices running Android 5.0 or greater. Note that the user can filter or turn notifications on and off from Settings. For more information about notifications, see the Titanium.Android.Notification.
For Android toast notifications (pop-up notifications sent while the application is in the foreground), see Titanium.UI.Notification.
# Options Menu
The options menu is a feature of older Android devices (prior to Android 3.0 (API 11)), and has been replaced by the action bar. The options menu is accessed by pressing the Menu and presents a pop-up menu of options the user can execute.
The Titanium.Android.Menu
API is used to construct both the options menu and action items for
the action bar.
For more information about the options menu, see the Titanium.Android.Menu.
# Services
A service is a component started by an application that runs in the background. The service does not have any application UI associated with it, so the user does not directly interact with it, only your application.
The Titanium SDK gives you the ability to write your own Android Services using JavaScript.
The service executes your JavaScript code at intervals you specify. Note that the service
will stop running when you back out of the app. So, if you want the service to continue running,
then it's recommended that you set the root window's Titanium.UI.Window.exitOnClose
property to false
so that the window will persist in the background like iOS.
For more information about services, see the Titanium.Android.Service.
# Permissions
Starting from Android 6.0 (API level 23), users need to grant certain permissions to apps while the
app is running. You can read it more here (opens new window).
Starting with Android 13 you have to use more granular media permissions. Check the official documentation (opens new window).
Make sure to add e.g. <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
to your tiapp.xml too.
In Titanium SDK, to support this, we have the Titanium.Android.requestPermissions method. It is used to request any permission you may need. An example of using it is shown below:
var permissions = [ 'android.permission.CAMERA', 'android.permission.READ_EXTERNAL_STORAGE', 'android.permission.WRITE_EXTERNAL_STORAGE' ];
if (Ti.Platform.versionMajor >= 13) {
// example for camera and image permission on Android 13
permissions = [ 'android.permission.CAMERA', 'android.permission.READ_MEDIA_IMAGES' ]
}
Ti.Android.requestPermissions(permissions, function (e) {
if (e.success) {
Ti.API.info('SUCCESS');
} else {
Ti.API.info('ERROR: ' + e.error);
}
});
# Properties
# apiName READONLY
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
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
# currentActivity READONLY
References the top-most window's activity.
# lifecycleContainer
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.
# rootActivity READONLY
The first activity launched by the application.
This is the main launcher activity defined in the "AndroidManifest.xml" which shows the splash screen. All windows opened are child activities below this root activity.
Closing this root activity via its finish method will close all of its child activity windows as well and exit out of the app.
When resuming the app via a data intent such as a URL, notification, shortcut, etc. the root activity will fire a "newintent" event and update its intent property with the newly received intent.
# Methods
# addEventListener
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
# applyProperties
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
# createBigPictureStyle
Creates and returns an instance of Titanium.Android.BigPictureStyle.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.BigPictureStyle> | Properties to set on a new object, including any defined by Titanium.Android.BigPictureStyle except those marked not-creation or read-only. |
Returns
# createBigTextStyle
Creates and returns an instance of Titanium.Android.BigTextStyle.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.BigTextStyle> | Properties to set on a new object, including any defined by Titanium.Android.BigTextStyle except those marked not-creation or read-only. |
Returns
# createBroadcastIntent
Create an Intent
to be used in a broadcast.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.Intent> | Properties to set on the new object, including any defined by Titanium.Android.Intent, except those marked not-creation or read-only. |
Returns
# createBroadcastReceiver
Creates and returns an instance of Titanium.Android.BroadcastReceiver.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.BroadcastReceiver> | Properties to set on a new object, including any defined by Titanium.Android.BroadcastReceiver except those marked not-creation or read-only. |
Returns
# createIntent
Creates and returns an instance of Titanium.Android.Intent.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.Intent> | Properties to set on a new object, including any defined by Titanium.Android.Intent except those marked not-creation or read-only. |
Returns
# createIntentChooser
Creates an activity chooser intent, used to allow the user to select a target activity for an intent.
Use this method when the user wants to take an action that could use any one of a number of applications. For example, when sending a plain text message, the user may choose to send a text message, send an email, or post to a social network.
You pass in an Titanium.Android.Intent representing the action being taken, and a title for the chooser.
The method returns another intent, representing the chooser, which can be used to start an activity. See the code example for details on how to display the chooser.
For more information, see the official Android documentation for Intent.ACTION_CHOOSER
Parameters
Name | Type | Description |
---|---|---|
intent | Titanium.Android.Intent | The intent to display a chooser for. |
title | String | Title to display on the chooser. |
Returns
# createNotification
Creates and returns an instance of Titanium.Android.Notification.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.Notification> | Properties to set on a new object, including any defined by Titanium.Android.Notification except those marked not-creation or read-only. |
Returns
# createNotificationChannel
Creates and returns an instance of Titanium.Android.NotificationChannel.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.NotificationChannel> | Properties to set on a new object, including any defined by Titanium.Android.NotificationChannel except those marked not-creation or read-only. |
Returns
# createPendingIntent
Creates a Titanium.Android.PendingIntent to be used inside a Titanium.Android.Notification.
If FLAG_NO_CREATE
is specified and no matching pending intent exists, returns
null
.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.PendingIntent> | Properties to set on the new object, including any defined by Titanium.Android.PendingIntent, except those marked not-creation or read-only. |
Returns
# createQuickSettingsService
Creates and returns an instance of Titanium.Android.QuickSettingsService.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.QuickSettingsService> | Properties to set on a new object, including any defined by Titanium.Android.QuickSettingsService except those marked not-creation or read-only. |
Returns
# createRemoteViews
Creates and returns an instance of Titanium.Android.RemoteViews.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Titanium.Android.RemoteViews> | Properties to set on a new object, including any defined by Titanium.Android.RemoteViews except those marked not-creation or read-only. |
Returns
# createService
Create a Titanium.Android.Service so you can start/stop it and listen for events from it.
Parameters
Name | Type | Description |
---|---|---|
intent | Titanium.Android.Intent | An |
Returns
# createServiceIntent
Create an Intent
to be used to start a service.
Parameters
Name | Type | Description |
---|---|---|
options | ServiceIntentOptions | Options for the Service. |
Returns
# fireEvent
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
# hasPermission
Returns true
if the app has permission access.
Parameters
Name | Type | Description |
---|---|---|
permission | String | Array<String> | The permission to check for access. This can be any of the constants listed here
with dangerous protection level here.
For example, Since Titanium 6.1.0, the method will also accept |
Returns
- Type
- Boolean
# isServiceRunning
Check on state of Service.
Parameters
Name | Type | Description |
---|---|---|
intent | Titanium.Android.Intent | An |
Returns
- Type
- Boolean
# registerBroadcastReceiver
Registers broadcast receiver for the given actions.
Parameters
Name | Type | Description |
---|---|---|
broadcastReceiver | Titanium.Android.BroadcastReceiver | The broadcast receiver to register and handle the broadcast. |
actions | Array<String> | The actions that the broadcast reciever will handle |
Returns
- Type
- void
# removeEventListener
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 |
Returns
- Type
- void
# requestPermissions
Request for permission access.
Parameters
Name | Type | Description |
---|---|---|
permissions | String | Array<String> | The permission(s) to request for access. This can be any of the constants listed here
with dangerous protection level here.
Normal protection permissions are automatically enabled if they are included in the manifest. An example of a
dangerous protection permission would be Besides this, there are also requestPermission methods that are ready for commonly used situations. These methods are requestCalendarPermissions, requestContactsPermissions, requestStoragePermissions, requestLocationPermissions and requestCameraPermissions. Since Titanium 6.1.0, the method will also accept a String. Any requests where permissions are already granted will yield a successful callback. |
callback | Callback<RequestPermissionAccessResult> | Function to call upon user decision to grant access.
Optional on SDK 10, as this method will return a |
Returns
On SDK 10+, this method will return a Promise
whose resolved value is equivalent to that passed to the optional callback argument.
- Type
- Promise<RequestPermissionAccessResult>
# startService
Starts a simple service.
Parameters
Name | Type | Description |
---|---|---|
intent | Titanium.Android.Intent | An |
Returns
- Type
- void
# stopService
Stop a simple service that was started with startService
.
Parameters
Name | Type | Description |
---|---|---|
intent | Titanium.Android.Intent | An |
Returns
- Type
- void
# unregisterBroadcastReceiver
Unregisters a broadcast receiver.
Parameters
Name | Type | Description |
---|---|---|
broadcastReceiver | Titanium.Android.BroadcastReceiver | The broadcast receiver to unregister. |
Returns
- Type
- void
# Constants
# ACTION_AIRPLANE_MODE_CHANGED
User switched airplane mode on or off.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_AIRPLANE_MODE_CHANGED in the Android API Reference.
# ACTION_ALL_APPS
List all applications.
Use with the action property to create an Activity Intent.
See Intent.ACTION_ALL_APPS in the Android API Reference.
# ACTION_ANSWER
Handle an incoming phone call.
Use with the action property to create an Activity Intent.
See Intent.ACTION_ANSWER in the Android API Reference.
# ACTION_ATTACH_DATA
Used to indicate that the data is an attachment.
Use with the action property to create an Activity Intent.
See Intent.ACTION_ATTACH_DATA in the Android API Reference.
# ACTION_BATTERY_CHANGED
Listen to battery state change status.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
Note that Titanium exposes battery monitoring using the Titanium.Platform API.
See Intent.ACTION_BATTERY_CHANGED in the Android API Reference.
# ACTION_BATTERY_LOW
Indicates low battery condition on the device.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
Note that Titanium exposes battery monitoring using the Titanium.Platform API.
See Intent.ACTION_BATTERY_LOW in the Android API Reference.
# ACTION_BATTERY_OKAY
Inidicates the battery is now okay after being low.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
Note that Titanium exposes battery monitoring using the Titanium.Platform API.
See Intent.ACTION_BATTERY_OKAY in the Android API Reference.
# ACTION_BOOT_COMPLETED
Indicates the system has finished booting.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
The application needs to also set the android.permission.RECEIVE_BOOT_COMPLETED
permission
in the Android manifest section of the tiapp.xml
file.
<ti:app>
<android>
<manifest>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
</manifest>
</android>
</ti:app>
See Intent.ACTION_BOOT_COMPLETED in the Android API Reference.
# ACTION_BUG_REPORT
Show activity for reporting a bug.
Use with the action property to create an Activity Intent.
See Intent.ACTION_BUG_REPORT in the Android API Reference.
# ACTION_CALL
Perform a call to someone specified by the data
property.
Use with the action property to create an Activity Intent.
See Intent.ACTION_CALL in the Android API Reference.
# ACTION_CALL_BUTTON
User pressed the call button.
Use with the action property to create an Activity Intent.
See Intent.ACTION_CALL_BUTTON in the Android API Reference.
# ACTION_CAMERA_BUTTON
The camera button was pressed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_CAMERA_BUTTON in the Android API Reference.
# ACTION_CHOOSER
Display an activity chooser.
Use with the action property to create an Activity Chooser.
You can also create an activity chooser using the createIntentChooser method.
See Intent.ACTION_CHOOSER in the Android API Reference.
# ACTION_CLOSE_SYSTEM_DIALOGS
User dismissed a temporary system dialog, such as the notification drawer or recent-app drawer.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_CLOSE_SYSTEM_DIALOGS in the Android API Reference.
# ACTION_CONFIGURATION_CHANGED
The device's configuration changed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_CONFIGURATION_CHANGED in the Android API Reference.
# ACTION_CREATE_SHORTCUT
Create a shortcut.
Use with the action property to create an Activity Intent.
See Intent.ACTION_CREATE_SHORTCUT in the Android API Reference.
# ACTION_DATE_CHANGED
Date changed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_DATE_CHANGED in the Android API Reference.
# ACTION_DEFAULT
Default action, which is Titanium.Android.ACTION_VIEW
Use with the action property to create an Activity Intent.
See Intent.ACTION_DEFAULT in the Android API Reference.
# ACTION_DELETE
Delete the data specified by the Intent's data
property.
Use with the action property to create an Activity Intent.
See Intent.ACTION_DELETE in the Android API Reference.
# ACTION_DEVICE_STORAGE_LOW
Indicates a low memory condition on the device.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_DEVICE_STORAGE_LOW in the Android API Reference.
# ACTION_DIAL
Dial a number specified by the Intent's data
property.
Use with the action property to create an Activity Intent.
See Intent.ACTION_DIAL in the Android API Reference.
# ACTION_EDIT
Provide editable access to the data specified by the Intent's data
property.
Use with the action property to create an Activity Intent.
See Intent.ACTION_EDIT in the Android API Reference.
# ACTION_GET_CONTENT
Allow the user to select a particular kind of data specified by the Intent's type
property.
Use with the action property to create an Activity Intent.
See Intent.ACTION_GET_CONTENT in the Android API Reference.
# ACTION_GTALK_SERVICE_CONNECTED
GTalk connection has been established.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_GTALK_SERVICE_CONNECTED in the Android API Reference.
# ACTION_GTALK_SERVICE_DISCONNECTED
GTalk connection has been disconnected.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_GTALK_SERVICE_DISCONNECTED in the Android API Reference.
# ACTION_HEADSET_PLUG
A wired headset has been plugged in or unplugged.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_HEADSET_PLUG in the Android API Reference.
# ACTION_INPUT_METHOD_CHANGED
An input method has been changed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_INPUT_METHOD_CHANGED in the Android API Reference.
# ACTION_INSERT
Insert an empty item into the given container.
Use with the action property to create an Activity Intent.
See Intent.ACTION_INSERT in the Android API Reference.
# ACTION_INSERT_OR_EDIT
Pick an existing item or insert an empty item, then edit it.
Use with the action property to create an Activity Intent.
See Intent.ACTION_INSERT_OR_EDIT in the Android API Reference.
# ACTION_MAIN
Start as the main entry point.
Use with the action property to create an Activity Intent.
See Intent.ACTION_MAIN in the Android API Reference.
# ACTION_MANAGE_PACKAGE_STORAGE
Indicates low memory condition notification acknowledged by user and package management should be started.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MANAGE_PACKAGE_STORAGE in the Android API Reference.
# ACTION_MEDIA_BAD_REMOVAL
External media was removed from SD card slot, but mount point was not unmounted.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_BAD_REMOVAL in the Android API Reference.
# ACTION_MEDIA_BUTTON
The media button was pressed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_BUTTON in the Android API Reference.
# ACTION_MEDIA_CHECKING
External media is present and being disk-checked.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_CHECKING in the Android API Reference.
# ACTION_MEDIA_EJECT
User has expressed the desire to remove the external storage media.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
Applications should close all files they have open within the mount point when they receive this intent.
See Intent.ACTION_MEDIA_EJECT in the Android API Reference.
# ACTION_MEDIA_MOUNTED
External media is present and mounted at its mount point.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_MOUNTED in the Android API Reference.
# ACTION_MEDIA_NOFS
External media is present, but is using an incompatible filesystem or is blank.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_NOFS in the Android API Reference.
# ACTION_MEDIA_REMOVED
External media has been removed.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_REMOVED in the Android API Reference.
# ACTION_MEDIA_SCANNER_FINISHED
The media scanner has finished scanning a directory.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_SCANNER_FINISHED in the Android API Reference.
# ACTION_MEDIA_SCANNER_SCAN_FILE
Request the media scanner to scan a file and add it to the media database.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_SCANNER_SCAN_FILE in the Android API Reference.
# ACTION_MEDIA_SCANNER_STARTED
The media scanner has started scanning a directory.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_SCANNER_STARTED in the Android API Reference.
# ACTION_MEDIA_SHARED
External media is unmounted because it is being shared via USB mass storage.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_SHARED in the Android API Reference.
# ACTION_MEDIA_UNMOUNTABLE
Corresponds to the Android Intent.ACTION_MEDIA_UNMOUNTABLE
constant.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_UNMOUNTABLE in the Android API Reference.
# ACTION_MEDIA_UNMOUNTED
External media is present, but not mounted at its mount point.
Pass to the registerBroadcastReceiver method to listen to the system broadcast.
See Intent.ACTION_MEDIA_UNMOUNTED in the Android API Reference.