# Titanium.Android.Activity

The Titanium binding of an Android Activity.

Availability

1.5

Extends

Titanium.Proxy

# Overview

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 (opens new window) 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:

• Titanium.Android.Activity.onCreate
• Titanium.Android.Activity.onStart
• Titanium.Android.Activity.onResume
• Titanium.Android.Activity.onPause
• Titanium.Android.Activity.onStop
• Titanium.Android.Activity.onDestroy
• Titanium.Android.Activity.onRestart

See also the "Understand the Lifecycle Callbacks" section in Android Developers: Activity Lifecycle (opens new window).

# 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 Titanium.UI.Window.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 (opens new window) to the root activity instead

<property name="ti.android.root.reappears.restart" type="bool">true</property>

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

# Examples

# Callback Example

The following example shows how to start an activity and retrieve a result code and optional data intent when the activity ends.

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 READONLY

Availability

1.5

actionBar :Titanium.Android.ActionBar

The action bar for this activity.

See also: Action Bar in the Android Developer Reference.

---

# 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

---

# intent READONLY

Availability

1.5

intent :Titanium.Android.Intent

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.

---

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

---

# onCreate

Availability

3.4.0

onCreate :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is created.

---

# onCreateOptionsMenu

Availability

1.5

onCreateOptionsMenu :Callback<OptionsMenuCallbackObject>

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.

See also: Creating an Options Menu in the Android Developer's Guide.

---

# onDestroy

Availability

3.4.0

onDestroy :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is destroyed.

---

# onPause

Availability

3.4.0

onPause :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is paused.

---

# onPrepareOptionsMenu

Availability

1.5

onPrepareOptionsMenu :Callback<OptionsMenuCallbackObject>

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.

See also: Creating an Options Menu in the Android Developer's Guide.

---

# onRestart

Availability

3.4.0

onRestart :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is restarted.

---

# onResume

Availability

3.4.0

onResume :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is resumed.

---

# onStart

Availability

3.4.0

onStart :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is started.

---

# onStop

Availability

3.4.0

onStop :Callback<ActivityLifecycleCallbackObject>

Callback function called when the Android activity is stopped.

---

# requestedOrientation

Availability

1.5

requestedOrientation :Number

Specifies a specific orientation for this activity.

This API can be assigned the following constants:

• 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

Availability

6.2.0

supportToolbar :Titanium.UI.Toolbar

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

# Methods

# 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

---

# 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

---

# finish

Availability

1.5

finish() → void

Closes this activity.

See also: finish in the Android API Reference.

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

---

# getString

Availability

1.5

getString(resourceId[, ...format]) → String

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:

<string name="greeting">"Hello %1$s, this is %2$s."</string>

You could call getString like this:

Ti.Android.currentActivity.getString(Ti.App.Android.R.string.greeting,  "Bob", "Doug" );

The resulting string is:

"Hello Bob, this is Doug."

See also:

• getString in the Android Developer Reference
• Formatter in the Android Developer Reference
• String Resources in the Android Developer Guide

Parameters

Name	Type	Description
resourceId	Number	Resource ID from the Application or Android.
format	any	Optional format arguments for the String resource. May be repeated.

Returns

Type

String

---

# invalidateOptionsMenu

Availability

3.0.0

invalidateOptionsMenu() → void

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 in the Android API Reference for more details.

Returns

Type

void

---

# openOptionsMenu

Availability

3.0.0

openOptionsMenu() → void

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.

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

---

# sendBroadcast

Availability

3.2.0

sendBroadcast(intent) → void

Broadcast the passed in Intent to all BroadcastReceivers.

Parameters

Name	Type	Description
intent	Titanium.Android.Intent	Description of the broadcast.

Returns

Type

void

---

# sendBroadcastWithPermission

Availability

3.2.0

sendBroadcastWithPermission(intent[, receiverPermission]) → void

Broadcast the passed in Intent to all BroadcastReceivers with an optional permission.

Parameters

Name	Type	Description
intent	Titanium.Android.Intent	Description of the broadcast.
receiverPermission	String	Name of the permission that the receiver should hold in order to receive the broadcast.

Returns

Type

void

---

# setRequestedOrientation DEPRECATED

Availability

1.5

setRequestedOrientation(orientation) → void

DEPRECATED SINCE 10.0.0

Use the <Titanium.Android.requestedOrientation> property instead

Sets the requested Activity orientation.

See also: setRequestedOrientation in the Android API Reference.

Parameters

Name	Type	Description
orientation	Number	Orientation mode for the activity.

Returns

Type

void

---

# setResult

Availability

1.5

setResult(resultCode[, intent]) → void

Sets the result of this activity using an Intent.

This method should only be used by rootActivity when launched by another app via startActivityForResult. After calling setResult(), you are expected to call the root activity's finish method afterwards to return the result to the calling app.

See Android's documentation for setResult.

Parameters

Name	Type	Description
resultCode	Number	Result code for this activity.
intent	Titanium.Android.Intent	An optional Intent with extra result data.

Returns

Type

void

---

# setSupportActionBar

Availability

6.2.0

setSupportActionBar(toolbar) → void

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 must be used.

Parameters

Name	Type	Description
toolbar	Titanium.UI.Toolbar	Instance of a toolbar to be used as an ActionBar

Returns

Type

void

---

# startActivity

Availability

1.5

startActivity(intent) → void

Starts a new activity, using the passed in Intent as the description.

See also: startActivity in the Android Developer Reference.

Parameters

Name	Type	Description
intent	Titanium.Android.Intent	Description of the activity to start.

Returns

Type

void

---

# startActivityForResult

Availability

1.5

startActivityForResult(intent, callback) → void

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

Name	Type	Description
intent	Titanium.Android.Intent	Description of the activity to start.
callback	Callback<ActivityResult>	Callback function to be executed when the activity sets result. See examples.

Returns

Type

void

# Events

# newintent

Availability

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 rootActivity, which is the splash screen activity. This event will never be fired by any of the child activities. The root activity' Titanium.Android.Intent property will be updated when to the new intent when fired.

See also: onNewIntent in the Android Developer Reference.

Properties

Name	Type	Description
intent	Titanium.Android.Intent	The Intent passed to the native onNewIntent method.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

---

# onIntent

Availability

6.0.0

Fired when the activity is launched.

Properties

Name	Type	Description
intent	Titanium.Android.Intent	The Intent used to launch the Activity.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

---

# userleavehint

Availability

3.2.0

Fired when the activity is about to go into the background as a result of user choice.

See also: onUserLeaveHint in the Android Developer Reference.

---

# userinteraction

Availability

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 in the Android Developer Reference.