# Titanium.Android.Intent

> Message objects passed between Android application components.

- Source: https://titaniumsdk.com/docs/sdk/12.8.0/Titanium.Android.Intent
- Titanium SDK version: 12.8.0
- Kind: proxy
- Platforms: Android
- Since: Titanium SDK 1.5
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

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](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/Platform_API_Deep_Dives/Android_API_Deep_Dives/Android_Intent_Filters.html).

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](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#createIntent) method.
  * To create an intent to start a **Broadcast**, use the [Titanium.Android.createBroadcastIntent](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#createBroadcastIntent) method.
  * To create an intent to start a **Service**, use the [Titanium.Android.createServiceIntent](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#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 [data](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#data) property specifies a content URI you want the activity to handle.

The [type](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#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 [addCategory()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#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 [flags](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#flags) property
or pass a flag to the [addFlags()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#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 [hasExtra()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#hasExtra) method to check if the intent contains an extra.
    Pass the method the key of the extra.
  * Use the [putExtra()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#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](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/Platform_API_Deep_Dives/Android_API_Deep_Dives/Android_Intent_Filters.html)
  * [Android Developer: Intent](https://developer.android.com/reference/android/content/Intent.html)

## Example: Create an Intent for Launching an Activity

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

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

## Example: Create an Intent to get a Contact URI

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

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

## Example: Pick a Photo from the Photo Gallery

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

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

## Example: 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](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/Platform_API_Deep_Dives/Android_API_Deep_Dives/Android_Intent_Filters.html).

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

`tiapp.xml`:
``` 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`:
``` 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

- Type: String
- Platforms: Android

The action associated with this intent.

Specify one of the `ACTION` constants from [Titanium.Android](https://titaniumsdk.com/docs/sdk/Titanium.Android.md), or an application-specific custom action string.

### className

- Type: String
- Platforms: Android

The Java class name of the activity associated with this intent
([packageName](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md#packageName) must also be set).

### data

- Type: String
- Platforms: Android
- Permission: read-only

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](https://developer.android.com/reference/android/content/Intent.html#setData(android.net.Uri))

### flags

- Type: Number
- Platforms: Android

Intent flags.

Accepts: `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_AUTO_CANCEL`, `Titanium.Android.FLAG_CANCEL_CURRENT`, `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_IMMUTABLE`, `Titanium.Android.FLAG_INSISTENT`, `Titanium.Android.FLAG_MUTABLE`, `Titanium.Android.FLAG_NO_CLEAR`, `Titanium.Android.FLAG_NO_CREATE`, `Titanium.Android.FLAG_ONE_SHOT`, `Titanium.Android.FLAG_ONGOING_EVENT`, `Titanium.Android.FLAG_ONLY_ALERT_ONCE`, `Titanium.Android.FLAG_RECEIVER_REGISTERED_ONLY`, `Titanium.Android.FLAG_SHOW_LIGHTS`, `Titanium.Android.FLAG_UPDATE_CURRENT`

### packageName

- Type: String
- Platforms: Android

The fully-qualified Java package name of the activity.

### type

- Type: String
- Platforms: Android
- Permission: read-only

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](https://developer.android.com/reference/android/content/Intent.html#setType(java.lang.String)).

### url

- Type: String
- Platforms: Android

The URL to a Titanium JavaScript Activity.

## Methods

### addCategory

- Platforms: Android

Adds a category to this Intent.

Parameters:

- `name` (String): The category name.

### addFlags

- Platforms: Android

Adds to the existing flags on the `Intent`.

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

Parameters:

- `flags` (Number): Bitwise OR of the flags to add to the existing set.

### getBlobExtra

- Platforms: Android
- Since: Titanium SDK 2.1.0

Get a [Titanium.Blob](https://titaniumsdk.com/docs/sdk/Titanium.Blob.md) property from this `Intent`.

Parameters:

- `name` (String): The [Titanium.Blob](https://titaniumsdk.com/docs/sdk/Titanium.Blob.md) extra to get, most commonly [Titanium.Android.EXTRA_STREAM](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#EXTRA_STREAM).

Returns: Titanium.Blob

### getBooleanExtra

- Platforms: Android

Get a boolean property from this Intent.

Parameters:

- `name` (String): Property to get.
- `default` (Boolean): Default value to return if property does not exist or is of a different type.

Returns: Boolean

### getData

- Platforms: Android
- DEPRECATED since 10.0.0, removed in 10.0.0. Use the <Titanium.Android.Intent.data> property instead.

Get the Data URI from this `Intent`.

Returns: String

### getDoubleExtra

- Platforms: Android

Get a double property from this `Intent`.

Parameters:

- `name` (String): Property to get.
- `default` (Number): Default value to return if property does not exist or is of a different type.

Returns: Number

### getIntExtra

- Platforms: Android

Get an integer property from this `Intent`.

Parameters:

- `name` (String): Property to get.
- `default` (Number): Default value to return if property does not exist or is of a different type.

Returns: Number

### getLongExtra

- Platforms: Android

Get a long property from this `Intent`.

Parameters:

- `name` (String): Property to get.
- `default` (Number): Default value to return if property does not exist or is of a different type.

Returns: Number

### getStringExtra

- Platforms: Android

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` (String): Property to get.

Returns: String

### hasExtra

- Platforms: Android

Returns `true` if this `Intent` has the specified property.

Parameters:

- `name` (String): Property name to check for.

Returns: Boolean

### putExtra

- Platforms: Android

Puts an extra property on this `Intent`.

Parameters:

- `name` (String): Name of the property to add.
- `value` (any): Property value to set.

### putExtraUri

- Platforms: Android

Put a URI property on this `Intent` (useful for [Titanium.Android.EXTRA_STREAM](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#EXTRA_STREAM)).

Parameters:

- `name` (String): The property name.
- `value` (String | Array<String>): The URI, as a string or a string array.

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.8.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.