Titanium.Android.Activity
The Titanium binding of an Android Activity.
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 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.
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 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 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.
Extends: Titanium.Proxy · Since: 1.5 · Platforms: android
Properties #
actionBar#
Type: Titanium.Android.ActionBar
The action bar for this activity.
See also: Action Bar in
the Android Developer Reference.
apiName#
Type: 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, Button
returns Ti.UI.Button.
bubbleParent#
Type: 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.
intent#
Type: 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#
Type: 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#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is created.
onCreateOptionsMenu#
Type: 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#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is destroyed.
onPause#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is paused.
onPrepareOptionsMenu#
Type: 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#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is restarted.
onResume#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is resumed.
onStart#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is started.
onStop#
Type: Callback<ActivityLifecycleCallbackObject>
Callback function called when the Android activity is stopped.
supportToolbar#
Type: 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 #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
getString #
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
| Name | Type | Summary | Optional |
|---|---|---|---|
resourceId | Number | Resource ID from the Application or Android. | No |
format | any | Optional format arguments for the String resource. May be repeated. | Yes |
Returns: String
invalidateOptionsMenu #
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.
openOptionsMenu #
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.
removeEventListener #
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);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
sendBroadcast #
Broadcast the passed in Intent to all BroadcastReceivers.
| Name | Type | Summary | Optional |
|---|---|---|---|
intent | Titanium.Android.Intent | Description of the broadcast. | No |
sendBroadcastWithPermission #
Broadcast the passed in Intent to all BroadcastReceivers with an optional permission.
| Name | Type | Summary | Optional |
|---|---|---|---|
intent | Titanium.Android.Intent | Description of the broadcast. | No |
receiverPermission | String | Name of the permission that the receiver should hold in order to receive the broadcast. | Yes |
setRequestedOrientation #
Sets the requested Activity orientation.
See also:
setRequestedOrientation
in the Android API Reference.
| Name | Type | Summary | Optional |
|---|---|---|---|
orientation | Number | Orientation mode for the activity. | No |
setResult #
Sets the result of this activity using an Intent.
This method should only be used by Ti.Android.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.
| Name | Type | Summary | Optional |
|---|---|---|---|
resultCode | Number | Result code for this activity. | No |
intent | Titanium.Android.Intent | An optional Intent with extra result data. | Yes |
setSupportActionBar #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
toolbar | Titanium.UI.Toolbar | Instance of a toolbar to be used as an ActionBar | No |
startActivity #
Starts a new activity, using the passed in Intent as the description.
See also: startActivity
in the Android Developer Reference.
| Name | Type | Summary | Optional |
|---|---|---|---|
intent | Titanium.Android.Intent | Description of the activity to start. | No |
startActivityForResult #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
intent | Titanium.Android.Intent | Description of the activity to start. | No |
callback | Callback<ActivityResult> | Callback function to be executed when the activity sets result. See examples. | No |
Events #
newintent #
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, which is
the splash screen activity. This event will never be fired by any of the child activities. The root
activity' intent property will be updated when to the new intent when fired.
See also:
onNewIntent
in the Android Developer Reference.
| Name | Type | Summary |
|---|---|---|
intent | Titanium.Android.Intent | The Intent passed to the native onNewIntent method. |
onIntent #
Fired when the activity is launched.
| Name | Type | Summary |
|---|---|---|
intent | Titanium.Android.Intent | The Intent used to launch the Activity. |
userinteraction #
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.
userleavehint #
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.
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;
});