# Titanium.Android.Activity
> The Titanium binding of an Android Activity.
- Source: https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.Android.Activity
- Titanium SDK version: 13.2.0
- Kind: proxy
- Platforms: Android
- Since: Titanium SDK 1.5
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy
According to the Android API Reference, an activity is "a single, focused thing that a
user can do."
In almost all cases, an activity is associated with a window. Activities are central
to the Android **Back** button navigation -- the **Back** button closes the current
activity and returns to whatever activity was open previously.
In Titanium, the Android Activity is not created until a window or tab group is opened.
After a Window or TabGroup object is created but before it is opened, its `activity` property
refers to an empty JavaScript object. You can use it to set properties on the activity, such as
the `onCreateOptionsMenu` property, but you cannot invoke any Activity methods.
After the window or tab group opens, a real Activity object is created and the properties from
the JavaScript object are copied over. The `activity` property now refers to this real Activity object,
which you can use to call the various Activity methods. For example, to use the
`invalidateOptionsMenu` method, you need to get the activity after the window or tab group opens.
See also [android.app.Activity](https://developer.android.com/reference/android/app/Activity.html)
in the Android API Reference.
#### Activity Lifecycle
In Android, activities are created, started, resumed, paused, stopped, destroyed and restarted.
Titanium generates lifecycle events for activities but does not generate application-level events.
To be notified when an activity's lifecycle event is triggered, assign callbacks to the following activity
properties:
* [onCreate](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onCreate)
* [onStart](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onStart)
* [onResume](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onResume)
* [onPause](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onPause)
* [onStop](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onStop)
* [onDestroy](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onDestroy)
* [onRestart](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onRestart)
See also the "Understand the Lifecycle Callbacks" section in
[Android Developers: Activity Lifecycle](https://developer.android.com/training/basics/activity-lifecycle/starting.html).
#### Don't keep activities option
Android 4.0 and greater devices have an option called **Don't keep activities** under the **Developer
Options** menu. When this option is enabled, the Android OS will destroy an activity as soon as it
is stopped. It is intended to help developers debug their apps. For example, it can simulate the
case that Android will kill an activity in the background due to memory pressure. In
normal use, it is not recommended to turn this option on because this may lead to unexpected issues
on the apps, such as freezes, force closes and reboots.
When the **Don't keep activities** option is enabled, the lifecycle of the activity is different
from the normal case. Whenever the user leaves an activity, such as backgrounding the app using the
HOME button, this activity is destroyed by Android, which calls `onDestroy`. In the normal case, `onStop`
would be called and the activity would not be destroyed. Later, when the user goes back to that activity, this
activity will be recreated, which calls `onCreate`. In the normal case, since the activity is not destroyed,
`onRestart` would be called instead. Therefore, some events, such as the open and close events on the Window
or TabGroup, will be fired differently from the normal case, and the root window of the app must set
[exitOnClose](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#exitOnClose) to true; otherwise, the app will be unable to back out, that is,
hitting the BACK button in the root window will not allow the application to exit.
#### Deprecated Behavior
Prior to Release 8.0.0, you would set the below "tiapp.xml" property to `true` to handle the case
where the Android OS would automatically close all child activity windows after the app has been backgrounded
for about 30 minutes, bringing the app back to the root splash screen activity window. The below property
would restart your app's UI in this case. This is no longer needed in 8.0.0 since Titanium now sets the
"AndroidManifest.xml" setting
[android:alwaysRetainTaskState](https://developer.android.com/guide/topics/manifest/activity-element#always)
to the root activity instead
``` xml
true
```
Prior to Release 3.4.0, to monitor lifecycle events, use the activity's events, `create`, `destroy`,
`pause`, `resume`, `start` and `stop`, to be notified when an activity is created, destroyed, paused,
resumed, started and stopped, respectively.
You can only set Activity properties from a TabGroup object after the tab group opens.
Prior to Release 3.2.0, you can create either a "lightweight" or "heavyweight" window, as
described on the [Titanium.UI.Window](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md) reference page. A *heavyweight* window creates a
new `Activity`. A *lightweight* window runs inside the same activity as the code that
created it. If you try to reference the activity of lightweight window, it returns undefined.
## Example: Callback Example
The following example shows how to start an activity and retrieve a result code
and optional data intent when the activity ends.
``` js
activity.startActivityForResult(intent, function(e) {
// The request code used to start this Activity
var requestCode = e.requestCode;
// The result code returned from the activity
// (https://developer.android.com/reference/android/app/Activity.html#StartingActivities)
var resultCode = e.resultCode;
// A Titanium.Android.Intent filled with data returned from the Activity
var intent = e.intent;
// The Activity the received the result
var source = e.source;
});
```
## Properties
### actionBar
- Type: Titanium.Android.ActionBar
- Platforms: Android
- Permission: read-only
The action bar for this activity.
See also: [Action Bar](https://developer.android.com/guide/topics/ui/actionbar.html) in
the Android Developer Reference.
### intent
- Type: Titanium.Android.Intent
- Platforms: Android
- Permission: read-only
The last `Intent` received by this activity.
Will initially be set to the intent that created/launched the activity. If this is the app's root activity,
then this intent will change when a "newintent" event has been fired.
### onCreate
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is created.
### onCreateOptionsMenu
- Type: Callback
- Platforms: Android
Callback function called to initially create an Android options menu
for this Activity when the user presses the **Menu** button.
See the menu examples in [Titanium.Android.Menu](https://titaniumsdk.com/docs/sdk/Titanium.Android.Menu.md).
See also:
[Creating an Options Menu](https://developer.android.com/guide/topics/ui/menus.html#options-menu)
in the Android Developer's Guide.
### onDestroy
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is destroyed.
### onPause
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is paused.
### onPrepareOptionsMenu
- Type: Callback
- Platforms: Android
Callback function called to prepare an options menu for display when the user presses
the **Menu** button.
See the menu examples in [Titanium.Android.Menu](https://titaniumsdk.com/docs/sdk/Titanium.Android.Menu.md).
See also:
[Creating an Options Menu](https://developer.android.com/guide/topics/ui/menus.html#options-menu)
in the Android Developer's Guide.
### onRestart
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is restarted.
### onResume
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is resumed.
### onStart
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is started.
### onStop
- Type: Callback
- Platforms: Android
- Since: Titanium SDK 3.4.0
Callback function called when the Android activity is stopped.
### requestedOrientation
- Type: Number
- Platforms: Android
- Permission: write-only
Specifies a specific orientation for this activity.
Accepts: `Titanium.Android.SCREEN_ORIENTATION_BEHIND`, `Titanium.Android.SCREEN_ORIENTATION_LANDSCAPE`, `Titanium.Android.SCREEN_ORIENTATION_NOSENSOR`, `Titanium.Android.SCREEN_ORIENTATION_PORTRAIT`, `Titanium.Android.SCREEN_ORIENTATION_SENSOR`, `Titanium.Android.SCREEN_ORIENTATION_UNSPECIFIED`, `Titanium.Android.SCREEN_ORIENTATION_USER`
### supportToolbar
- Type: Titanium.UI.Toolbar
- Platforms: Android
- Since: Titanium SDK 6.2.0
Toolbar instance that serves as ActionBar
This property is used to set a toolbar as an ActionBar prior to the actual activity creation.
After the activity is created that must be done through the [setSupportActionBar()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#setSupportActionBar) method.
## Methods
### finish
- Platforms: Android
Closes this activity.
See also:
[finish](https://developer.android.com/reference/android/app/Activity.html#finish())
in the Android API Reference.
### getString
- Platforms: Android
Gets an Android or Application string using the specified Resource ID and optional format arguments.
If the optional format arguments are supplied, these are substituted for the
corresponding format specifiers in the string. For example, given the following
string resource:
``` xml
"Hello %1$s, this is %2$s."
```
You could call `getString` like this:
``` js
Ti.Android.currentActivity.getString(Ti.App.Android.R.string.greeting, "Bob", "Doug" );
```
The resulting string is:
```
"Hello Bob, this is Doug."
```
See also:
* [getString](https://developer.android.com/reference/android/content/Context.html#getString(int))
in the Android Developer Reference
* [Formatter](https://developer.android.com/reference/java/util/Formatter.html)
in the Android Developer Reference
* [String Resources](https://developer.android.com/guide/topics/resources/string-resource.html#String)
in the Android Developer Guide
Parameters:
- `resourceId` (Number): Resource ID from the Application or Android.
- `format` (any, optional, repeatable): Optional format arguments for the String resource. May be repeated.
Returns: String
### invalidateOptionsMenu
- Platforms: Android
- Since: Titanium SDK 3.0.0
Declares that the option menu has changed and should be recreated.
This method needs to be used in Android 3.0 and above when changing menus at runtime. See
[changingTheMenu](https://developer.android.com/guide/topics/ui/menus.html#ChangingTheMenu) in
the Android API Reference for more details.
### openOptionsMenu
- Platforms: Android
- Since: Titanium SDK 3.0.0
Programmatically opens the options menu.
See also: [onMenuOpened](https://developer.android.com/reference/android/app/Activity.html#onMenuOpened(int, android.view.Menu))
in the Android API Reference.
### sendBroadcast
- Platforms: Android
- Since: Titanium SDK 3.2.0
Broadcast the passed in `Intent` to all `BroadcastReceiver`s.
Parameters:
- `intent` (Titanium.Android.Intent): Description of the broadcast.
### sendBroadcastWithPermission
- Platforms: Android
- Since: Titanium SDK 3.2.0
Broadcast the passed in `Intent` to all `BroadcastReceiver`s with an optional permission.
Parameters:
- `intent` (Titanium.Android.Intent): Description of the broadcast.
- `receiverPermission` (String, optional): Name of the permission that the receiver should hold in order to receive the broadcast.
### setRequestedOrientation
- Platforms: Android
- DEPRECATED since 10.0.0, removed in 10.0.0. Use the property instead
Sets the requested Activity orientation.
See also:
[setRequestedOrientation](https://developer.android.com/reference/android/app/Activity.html#setRequestedOrientation(int))
in the Android API Reference.
Parameters:
- `orientation` (Number): Orientation mode for the activity.
### setResult
- Platforms: Android
Sets the result of this activity using an `Intent`.
This method should only be used by [Ti.Android.rootActivity](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#rootActivity) when launched
by another app via [startActivityForResult](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#startActivityForResult). After calling
`setResult()`, you are expected to call the root activity's [finish](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#finish)
method afterwards to return the result to the calling app.
See Android's documentation for
[setResult](https://developer.android.com/reference/android/app/Activity.html#setResult(int)).
Parameters:
- `resultCode` (Number): Result code for this activity.
- `intent` (Titanium.Android.Intent, optional): An optional `Intent` with extra result data.
### setSupportActionBar
- Platforms: Android
- Since: Titanium SDK 6.2.0
Sets a toolbar instance to be used as an ActionBar.
This method is used if you want to add a Toolbar as an ActionBar after the Activity has been created.
If you want to set it up before that [supportToolbar](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#supportToolbar) must be used.
Parameters:
- `toolbar` (Titanium.UI.Toolbar): Instance of a toolbar to be used as an ActionBar
### startActivity
- Platforms: Android
Starts a new activity, using the passed in `Intent` as the description.
See also: [startActivity](https://developer.android.com/reference/android/app/Activity.html#startActivity(android.content.Intent))
in the Android Developer Reference.
Parameters:
- `intent` (Titanium.Android.Intent): Description of the activity to start.
### startActivityForResult
- Platforms: Android
The same as `startActivity`, but also accepts a callback function for handling the result of the started Activity.
See also:
[startActivityForResult](https://developer.android.com/reference/android/app/Activity.html#startActivityForResult(android.content.Intent, int))
in the Android Developer Reference.
Parameters:
- `intent` (Titanium.Android.Intent): Description of the activity to start.
- `callback` (Callback): Callback function to be executed when the activity sets result. See examples.
## Events
### newintent
- Platforms: Android
- Since: Titanium SDK 3.0.0
Fired when the activity is already running and an intent different than the one that launched it was received.
This event will only be fired by [Ti.Android.rootActivity](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#rootActivity), which is
the splash screen activity. This event will never be fired by any of the child activities. The root
activity' [intent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Intent.md) property will be updated when to the new intent when fired.
See also:
[onNewIntent](https://developer.android.com/reference/android/app/Activity.html#onNewIntent(android.content.Intent))
in the Android Developer Reference.
Event properties:
- `intent` (Titanium.Android.Intent): The `Intent` passed to the native `onNewIntent` method.
### onIntent
- Platforms: Android
- Since: Titanium SDK 6.0.0
Fired when the activity is launched.
Event properties:
- `intent` (Titanium.Android.Intent): The `Intent` used to launch the Activity.
### userinteraction
- Platforms: Android
- Since: Titanium SDK 7.5.0
Called whenever a key, touch, or trackball event is dispatched to the activity.
Implement this method if you wish to know that the user has interacted with the device in some
way while your activity is running. This event and `userleavehint` are intended to help activities
manage status bar notifications intelligently; specifically, for helping activities determine the
proper time to cancel a notfication.
All calls to your activity's "userleavehint" event will be accompanied by calls to "userinteraction".
This ensures that your activity will be told of relevant user activity such as pulling down the
notification pane and touching an item there.
Note that this callback will be invoked for the touch down action that begins a touch gesture,
but may not be invoked for the touch-moved and touch-up actions that follow.
See also:
[onUserInteraction](https://developer.android.com/reference/android/app/Activity.html#onUserInteraction())
in the Android Developer Reference.
### userleavehint
- Platforms: Android
- Since: Titanium SDK 3.2.0
Fired when the activity is about to go into the background as a result of user choice.
See also:
[onUserLeaveHint](https://developer.android.com/reference/android/app/Activity.html#onUserLeaveHint())
in the Android Developer Reference.
## Inherited members
7 members are inherited. Each is documented on the type that declares it.
- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.2.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`.