Titanium Mobile

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

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.

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

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

# 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

# finish

Availability
1.5
finish() → void

Closes this activity.

See also: finish in the Android API Reference.

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:

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

# 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

# create DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onCreate callback property instead.

Fired from the activity's onCreate method.

See also: onCreate in the Android Developer Reference.

# destroy DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onDestroy callback property instead.

Fired from the activity's onDestroy method.

See also: onDestroy in the Android Developer Reference.

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

# pause DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onPause callback property instead.

Fired when the activity is paused.

See also: onPause in the Android Developer Reference.

# restart DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onRestart callback property instead.

Fired when the activity is restarted.

See also: onRestart in the Android Developer Reference.

# resume DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onResume callback property instead.

Fired when the activity is resumed.

See also: onResume in the Android Developer Reference.

# start DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onStart callback property instead.

Fired when the activity is started.

See also: onStart in the Android Developer Reference.

# stop DEPRECATED

Availability
1.5

DEPRECATED SINCE 3.4.0

Use the onStop callback property instead.

Fired when the activity is stopped.

See also: onStop in the Android Developer Reference.

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

Contents