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.
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.
Every Android application has a root activity that starts the application. For Titanium applications, the root activity displays the splash screen. When a backgrounded application is left inactive (for about 30 minutes or so), upon reopening the app Android kills off activities above the root activity. This reveals the splash screen activity, making it appear as if the application is hung. There are two ways to handle this scenario:
Add the following to the root <ti:app> element in your project's tiapp.xml:
<property name="ti.android.root.reappears.restart" type="bool">true</property>
Create an event listener for the "resume" event on the current Android activity that
re-intiializes the application. The benefit to this approach is that it avoids a full
application restart, which occurs with the first option.
if(Ti.Platform.osname == "android") {
var initialLaunchPerformed = false;
Ti.Android.currentActivity.onResume = function() {
if (!initialLaunchPerformed) {
initialLaunchPerformed = true;
return;
}
// If we reach this point the root activity is being resumed for the second (or greater time).
// Re-run the application-specific start-up code again.
runApplication();
};
}
function runApplication() {
// Start-up code here...
}
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.
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.
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
// (http://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;
});
The action bar for this activity.
The action bar for this activity.
See also: Action Bar in the Android Developer Reference.
The name of the API that this proxy corresponds to.
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.
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
The Intent that was used to start this Activity.
The Intent that was used to start this Activity.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
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.
Callback function called when the Android activity is created.
Callback function called when the Android activity is created.
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.
Callback function called when the Android activity is destroyed.
Callback function called when the Android activity is destroyed.
Callback function called when the Android activity is paused.
Callback function called when the Android activity is paused.
Callback function called to prepare an options menu for display when the user presses the Menu button.
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.
Callback function called when the Android activity is restarted.
Callback function called when the Android activity is restarted.
Callback function called when the Android activity is resumed.
Callback function called when the Android activity is resumed.
Callback function called when the Android activity is started.
Callback function called when the Android activity is started.
Callback function called when the Android activity is stopped.
Callback function called when the Android activity is stopped.
Specifies a specific orientation for this activity.
This API can be assigned the following constants:
Toolbar instance that serves as ActionBar
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.
Adds the specified callback as an event listener for the named event.
Name of the event.
Callback function to invoke when the event is fired.
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.
A dictionary of properties to apply.
Fires a synthesized event to any registered listeners.
Name of the event.
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
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
Resource ID from the Application or Android.
Optional format arguments for the String resource. May be repeated.
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.
Programmatically opens the options menu.
See also: onMenuOpened in the Android API Reference.
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 of the event.
Callback function to remove. Must be the same function passed to addEventListener.
Broadcast the passed in Intent to all BroadcastReceivers.
Description of the broadcast.
Broadcast the passed in Intent to all BroadcastReceivers with an optional permission.
Description of the broadcast.
Name of the permission that the receiver should hold in order to receive the broadcast.
Sets the value of the bubbleParent property.
New value for the property.
Sets the value of the lifecycleContainer property.
New value for the property.
Sets the value of the onCreate property.
New value for the property.
Sets the value of the onCreateOptionsMenu property.
New value for the property.
Sets the value of the onDestroy property.
New value for the property.
Sets the value of the onPause property.
New value for the property.
Sets the value of the onPrepareOptionsMenu property.
New value for the property.
Sets the value of the onRestart property.
New value for the property.
Sets the value of the onResume property.
New value for the property.
Sets the value of the onStart property.
New value for the property.
Sets the value of the onStop property.
New value for the property.
Sets the value of the requestedOrientation property.
New value for the property.
Sets the result of this activity using an Intent.
This should be used in the case when the Activity responds to startActivityForResult.
Also see Android's documentation for setResult.
Result code for this activity.
This API can be assigned the following constants:
An optional Intent with extra result data.
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.
Instance of a toolbar to be used as an ActionBar
Sets the value of the supportToolbar property.
New value for the property.
Starts a new activity, using the passed in Intent as the description.
See also: startActivity in the Android Developer Reference.
Description of the activity to start.
The same as startActivity, but also accepts a callback function for handling the result of the started Activity.
See also: startActivityForResult in the Android Developer Reference.
Description of the activity to start.
Callback function to be executed when the activity sets result. See examples.
Fired from the activity's onCreate method.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onCreate> instead.
See also: onCreate in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired from the activity's onDestroy method.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onDestroy> instead.
See also: onDestroy in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is already running and certain flags are set in its intent.
deprecated since 3.0.0
Use <Titanium.Android.Activity.newintent> instead.
See also: onNewIntent in the Android Developer Reference.
The Intent passed to the native onNewIntent method.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is already running and certain flags are set in its intent.
See also: onNewIntent in the Android Developer Reference.
The Intent passed to the native onNewIntent method.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is launched.
The Intent used to launch the Activity.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is paused.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onPause> instead.
See also: onPause in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is resumed.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onResume> instead.
See also: onResume in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is started.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onStart> instead.
See also: onStart in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is stopped.
deprecated since 3.4.0
Use <Titanium.Android.Activity.onStop> instead.
See also: onStop in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.
Fired when the activity is about to go into the background as a result of user choice.
See also: onPause in the Android Developer Reference.
Source object that fired the event.
Name of the event fired.
True if the event will try to bubble up if possible.
Set to true to stop the event from bubbling.