# Titanium.Android.Intent

Message objects passed between Android application components.

Availability

1.5

Extends

Titanium.Proxy

# Overview

In Android, applications and application components cannot directly communicate with each other. In order to communicate with another application, use an intent. An intent is a message sent to the Android OS. Android directs the message to an application or application component based on the intent's settings.

To receive an intent, an application needs to declare an Intent Filter. An intent filter indicates to the Android OS that your application can handle certain data types or URIs. For details on using Intent Filters, see the Android Intent Filters guide (opens new window).

Intents can be used to start an activity, start a service or start a broadcast.

• To create an intent to start an Activity, use the Titanium.Android.createIntent method.
• To create an intent to start a Broadcast, use the Titanium.Android.createBroadcastIntent method.
• To create an intent to start a Service, use the Titanium.Android.createServiceIntent method.

You can create either an implicit intent or an explicit intent.

An explicit intent specifies the application or application component to launch. To create an explicit intent, specify the Intent's className and packageName properties to specify the application component to launch or the url property to specify a JavaScript file to handle the data.

An implicit intent does not specify a particular application. Android will present the options to the user of which applications to launch if a default application was not selected to handle a particular data type or content URI. To create an implicit intent, do not specify the className, packageName or url properties.

Note that the parameters to create a Service Intent are different than the ones used to create an Activity or Broadcast. The properties and methods listed below are used for Activity and Broadcast Intents. See the Titanium.Android.createServiceIntent method for the parameters to create a Service Intent.

# Action

The action property specifies the action you want the activity to perform, or in the case of broadcasts, the action that just completed you want to report.

Titanium exposes some of the Android Intent actions as the Titanium.Android.ACTION_* constants. Note that some of these actions are for system-level broadcasts that only Android can send. If Titanium has not exposed a particular constant, you can pass the string value listed in the Android API reference guide instead.

You can also define your own custom action names. Use a reverse domain scheme to name the action to avoid potential conflicts, for example, com.appcelerator.action.LINT. Custom actions are only useful to communicate between your applications and application activities using intents.

# Data

The Titanium.Android.Intent.data property specifies a content URI you want the activity to handle.

The Titanium.Android.Intent.type property specifies a MIME type the activity can handle.

For Broadcast Intents, do not use the data or type properties. Use extras to pass data. See the Extras section below.

# Category

Add a category to your Intent by invoking the Titanium.Android.Intent.addCategory method on it. A category provides additional details about the purpose of the intent. Note that most categories are only useful for intent filters.

Titanium exposes some of the Android Intent categories as the Titanium.Android.CATEGORY_* constants. Note that some of these categories are for Notifications. If Titanium has not exposed a particular constant, you can pass the string value listed in the Android API reference instead.

You can also define your own custom category names. Use a reverse domain scheme to name the category to avoid potential conflicts, for example, org.foo.category.SUPER. Custom categories are only useful to communicate between your applications and application activities using intents.

# Flags

Bitwise-OR flags with the Intent's Titanium.Android.Intent.flags property or pass a flag to the Titanium.Android.Intent.addFlags method. Flags modify the behavior of the intent.

Titanium exposes some of the Android Intent flags as the Titanium.Android.FLAG_* constants. If Titanium has not exposed a particular constant, you can pass the constant value listed in the Android API reference instead.

# Extras

Extras are key-value pairs that are useful to pass on extra data with the Intent that can be used by another application component.

• Use one of the get*Extra() methods to retrieve the data. Pass the method the extra key.
• Use the Titanium.Android.Intent.hasExtra method to check if the intent contains an extra. Pass the method the key of the extra.
• Use the Titanium.Android.Intent.putExtra method to add data to the intent. Pass the method the extra key and data.

Titanium exposes the Android-defined extra keys as the Titanium.Android.EXTRA_* constants. You can also define your own custom extra keys to use between your applications and application components.

# Further Reading

• Android Intents guide (opens new window)
• Android Developer: Intent (opens new window)

# Examples

# Create an Intent for Launching an Activity

This example creates an intent and uses it to launch a new activity.

var intent = Ti.Android.createIntent({
    action: Ti.Android.ACTION_MAIN,
    url: 'activity1.js'
});
intent.addCategory(Ti.Android.CATEGORY_LAUNCHER);
Ti.Android.currentActivity.startActivity(intent);

# Create an Intent to get a Contact URI

This example creates an intent to retrieve contact information from the user's contacts.

var intent = Ti.Android.createIntent({
    action: Ti.Android.ACTION_GET_CONTENT,
    type: "vnd.android.cursor.item/phone"
});

# Pick a Photo from the Photo Gallery

This example creates an intent to pick an image from the photo gallery.

var intent = Ti.Android.createIntent({
    action: Ti.Android.ACTION_PICK,
    type: "image/*"
});
intent.addCategory(Ti.Android.CATEGORY_DEFAULT);

# Create an ImageView from an Image Send Intent

This example requires that an intent filter be set up in the project's tiapp.xml file. After copying the default root activity of your application from the AndroidManifest.xml file to the Android manifest section of the tiapp.xml file, add an intent filter. For detailed instructions, refer to the Android Intent Filters guide (opens new window).

You can trigger this intent filter by long pressing on an image in the Android gallery and selecting "share".

tiapp.xml:

<ti:app>
    <android>
        <manifest>
            <application>
                <activity android:name=".YourapplicationnameActivity">
                    <intent-filter>
                        <data android:mimeType="image/*"/>
                        <action android:name="android.intent.action.SEND"/>
                        <category android:name="android.intent.category.DEFAULT"/>
                    </intent-filter>
                </activity>
            </application>
        </manifest>
    </android>
</ti:app>

app.js:

var win = Ti.UI.createWindow({
      backgroundColor: '#fff',
      fullscreen: false,
      exitOnClose: true
  });
  win.addEventListener('open', function(e) {
      var intent = Ti.Android.currentActivity.getIntent();
      var iname = Ti.Android.EXTRA_STREAM;
      if (intent && intent.hasExtra(iname)) {
          // Create ImageView from TiBlob
          var blob = intent.getBlobExtra(iname);
          win.add(Ti.UI.createImageView({
              image: blob,
              height: 300,
              width: 300,
              left: 0,
              top: 0
          }));
      } else {
          Ti.API.info('No extra named "' + iname + '" found in Intent');
      }
  });
  win.open();

# Properties

# action CREATION ONLY

Availability

1.5

action :String

The action associated with this intent.

Specify one of the ACTION constants from Titanium.Android, or an application-specific custom action string.

---

# 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

---

# className CREATION ONLY

Availability

1.5

className :String

The Java class name of the activity associated with this intent (packageName must also be set).

---

# data READONLYCREATION ONLY

Availability

1.5

data :String

The Intent's Data URI.

The data URI can be set when the intent is created. It is read-only after the intent is created.

For more information on data URIs, see: Intent.setData in the Android API Reference

---

# flags

Availability

1.5

flags :Number

Intent flags.

This API can be assigned the following constants:

• Titanium.Android.FLAG_ACTIVITY_BROUGHT_TO_FRONT
• Titanium.Android.FLAG_ACTIVITY_CLEAR_TOP
• Titanium.Android.FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET
• Titanium.Android.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS
• Titanium.Android.FLAG_ACTIVITY_FORWARD_RESULT
• Titanium.Android.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY
• Titanium.Android.FLAG_ACTIVITY_MULTIPLE_TASK
• Titanium.Android.FLAG_ACTIVITY_NEW_TASK
• Titanium.Android.FLAG_ACTIVITY_NO_ANIMATION
• Titanium.Android.FLAG_ACTIVITY_NO_HISTORY
• Titanium.Android.FLAG_ACTIVITY_NO_USER_ACTION
• Titanium.Android.FLAG_ACTIVITY_PREVIOUS_IS_TOP
• Titanium.Android.FLAG_ACTIVITY_REORDER_TO_FRONT
• Titanium.Android.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
• Titanium.Android.FLAG_ACTIVITY_SINGLE_TOP
• Titanium.Android.FLAG_DEBUG_LOG_RESOLUTION
• Titanium.Android.FLAG_FROM_BACKGROUND
• Titanium.Android.FLAG_GRANT_READ_URI_PERMISSION
• Titanium.Android.FLAG_GRANT_WRITE_URI_PERMISSION
• Titanium.Android.FLAG_RECEIVER_REGISTERED_ONLY
• Titanium.Android.FLAG_CANCEL_CURRENT
• Titanium.Android.FLAG_IMMUTABLE
• Titanium.Android.FLAG_MUTABLE
• Titanium.Android.FLAG_NO_CREATE
• Titanium.Android.FLAG_ONE_SHOT
• Titanium.Android.FLAG_UPDATE_CURRENT
• Titanium.Android.FLAG_AUTO_CANCEL
• Titanium.Android.FLAG_INSISTENT
• Titanium.Android.FLAG_NO_CLEAR
• Titanium.Android.FLAG_ONGOING_EVENT
• Titanium.Android.FLAG_ONLY_ALERT_ONCE
• Titanium.Android.FLAG_SHOW_LIGHTS

---

# 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.

---

# packageName CREATION ONLY

Availability

1.5

packageName :String

The fully-qualified Java package name of the activity.

---

# type READONLYCREATION ONLY

Availability

1.5

type :String

The MIME type for this Intent.

The MIME type can be set when the intent is created. It is read-only after the intent is created.

For information on MIME types and intents, see: Intent.setType in the Android API Reference.

---

# url CREATION ONLY

Availability

1.5

url :String

The URL to a Titanium JavaScript Activity.

# Methods

# addCategory

Availability

1.5

addCategory(name) → void

Adds a category to this Intent.

Parameters

Name	Type	Description
name	String	The category name.

Returns

Type

void

---

# addEventListener

Availability

1.5

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

---

# addFlags

Availability

1.5

addFlags(flags) → void

Adds to the existing flags on the Intent.

The specified flag are combined with the existing flags using a bitwise OR.

Parameters

Name	Type	Description
flags	Number	Bitwise OR of the flags to add to the existing set.

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

---

# fireEvent

Availability

1.5

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

---

# getBlobExtra

Availability

2.1.0

getBlobExtra(name) → Titanium.Blob

Get a Titanium.Blob property from this Intent.

Parameters

Name	Type	Description
name	String	The Titanium.Blob extra to get, most commonly EXTRA_STREAM.

Returns

Type

Titanium.Blob

---

# getBooleanExtra

Availability

1.5

getBooleanExtra(name, default) → Boolean

Get a boolean property from this Intent.

Parameters

Name	Type	Description
name	String	Property to get.
default	Boolean	Default value to return if property does not exist or is of a different type.

Returns

Type

Boolean

---

# getData DEPRECATED

Availability

1.5

getData() → String

DEPRECATED SINCE 10.0.0

Use the data property instead.

Get the Data URI from this Intent.

Returns

Type

String

---

# getDoubleExtra

Availability

1.5

getDoubleExtra(name, default) → Number

Get a double property from this Intent.

Parameters

Name	Type	Description
name	String	Property to get.
default	Number	Default value to return if property does not exist or is of a different type.

Returns

Type

Number

---

# getIntExtra

Availability

1.5

getIntExtra(name, default) → Number

Get an integer property from this Intent.

Parameters

Name	Type	Description
name	String	Property to get.
default	Number	Default value to return if property does not exist or is of a different type.

Returns

Type

Number

---

# getLongExtra

Availability

1.5

getLongExtra(name, default) → Number

Get a long property from this Intent.

Parameters

Name	Type	Description
name	String	Property to get.
default	Number	Default value to return if property does not exist or is of a different type.

Returns

Type

Number

---

# getStringExtra

Availability

1.5

getStringExtra(name) → String

Get a string property from this Intent.

Can also be used to get the string representation of a property that's stored as an Android Parcel, such as a URI.

Titanium does not support getParcelableExtra due to the inability to translate all of its possible return types to JavaScript.

See also: [getParcelableExtra](https://developer.android.com/reference/android/content/Intent.html#getParcelableExtra(java.lang.String) in the Android Developer Reference.

Parameters

Name	Type	Description
name	String	Property to get.

Returns

Type

String

---

# hasExtra

Availability

1.5

hasExtra(name) → Boolean

Returns true if this Intent has the specified property.

Parameters

Name	Type	Description
name	String	Property name to check for.

Returns

Type

Boolean

---

# putExtra

Availability

1.5

putExtra(name, value) → void

Puts an extra property on this Intent.

Parameters

Name	Type	Description
name	String	Name of the property to add.
value	any	Property value to set.

Returns

Type

void

---

# putExtraUri

Availability

1.5

putExtraUri(name, value) → void

Put a URI property on this Intent (useful for EXTRA_STREAM).

Parameters

Name	Type	Description
name	String	The property name.
value	String | Array<String>	The URI, as a string or a string array.

Returns

Type

void

---

# removeEventListener

Availability

1.5

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