blob: 2501f3840d428493a097011c1caf1ca9df012f07 [file] [log] [blame]
page.title=Starting an Activity
page.tags=activity lifecycle
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<li><a href="#lifecycle-states">Understand the Lifecycle Callbacks</a></li>
<li><a href="#launching-activity">Specify Your App's Launcher Activity</a></li>
<li><a href="#Create">Create a New Instance</a></li>
<li><a href="#Destroy">Destroy the Activity</a></li>
<h2>You should also read</h2>
<li><a href="{@docRoot}guide/components/activities.html">Activities</a></li>
<h2>Try it out</h2>
<div class="download-box">
<a href=""
class="button">Download the demo</a>
<p class="filename"></p>
<p>Unlike other programming paradigms in which apps are launched with a {@code main()} method, the
Android system initiates code in an {@link} instance by invoking specific
callback methods that correspond to specific stages of its
lifecycle. There is a sequence of callback methods that start up an activity and a sequence of
callback methods that tear down an activity.</p>
<p>This lesson provides an overview of the most important lifecycle methods and shows you how to
handle the first lifecycle callback that creates a new instance of your activity.</p>
<h2 id="lifecycle-states">Understand the Lifecycle Callbacks</h2>
<p>During the life of an activity, the system calls a core set of lifecycle methods in
a sequence similar to a step pyramid. That is, each stage of the
activity lifecycle is a separate step on the pyramid. As the system creates a new activity instance,
each callback method moves the activity state one step toward the top. The top of the pyramid is the
point at which the activity is running in the foreground and the user can interact with it.</p>
<p>As the user begins to leave the activity, the system calls other methods that move the activity
state back down the pyramid in order to dismantle the activity. In some cases, the activity will
move only part way down the pyramid and wait (such as when the user switches to another app), from
which point the activity can move back to the top (if the user returns to the activity) and
resume where the user left off.</p>
<img src="{@docRoot}images/training/basics/basic-lifecycle.png" />
<p class="img-caption"><strong>Figure 1.</strong> A simplified illustration of the Activity
lifecycle, expressed as a step pyramid. This shows how, for every callback used to take
the activity a step toward the Resumed state at the top, there's a callback method
that takes the activity a step down. The activity can also return to the resumed state from the
Paused and Stopped state.</p>
<p>Depending on the complexity of your activity, you probably don't need to implement all the
lifecycle methods. However, it's important that you understand each one and implement those that
ensure your app behaves the way users expect. Implementing your activity lifecycle methods properly
ensures your app behaves well in several ways, including that it:</p>
<li>Does not crash if the user receives a phone call or switches to another app
while using your app.</li>
<li>Does not consume valuable system resources when the user is not actively using
<li>Does not lose the user's progress if they leave your app and return to it at a
later time.</li>
<li>Does not crash or lose the user's progress when the screen rotates between
landscape and portrait orientation.</li>
<p class="table-caption"><strong>Table 1.</strong> Activity lifecycle state pairs and callback
<th scope="col">Lifecycle State</th>
<th scope="col">Startup Method</th>
<th scope="col">Teardown Method</th>
<td>Created / Destroyed</td>
<td>{@link onCreate()}</td>
<td>Started / Stopped</td>
<td>Resumed / Resumed</td>
<p>As you'll learn in the following lessons, there are several situations in which an activity
transitions between different states that are illustrated in figure 1. However, only three of
these states can be static. That is, the activity can exist in one of only three states for an
extended period of time:</p>
<dd>In this state, the activity is in the foreground and the user can interact with it.
(Also sometimes referred to as the "running" state.)</dd>
<dd>In this state, the activity is partially obscured by another activity&mdash;the
other activity that's in the foreground is semi-transparent or doesn't cover the entire screen. The
paused activity does not receive user input and cannot execute any code.
<dd>In this state, the activity is completely hidden and not visible to the user; it is
considered to be in the background. While stopped, the activity instance and all its state
information such as member variables is retained, but it cannot execute any code.</dd>
<p>The other states (Created and Started) are transient and the system quickly moves from them to
the next state by calling the next lifecycle callback method. That is, after the system calls
{@link onCreate()}, it quickly calls {@link}, which is quickly followed by {@link}.</p>
<p>That's it for the basic activity lifecycle. Now you'll start learning about some of the
specific lifecycle behaviors.</p>
<h2 id="launching-activity">Specify Your App's Launcher Activity</h2>
<p>When the user selects your app icon from the Home screen, the system calls the {@link onCreate()} method for the {@link} in your app
that you've declared to be the "launcher" (or "main") activity. This is the activity that serves as
the main entry point to your app's user interface.</p>
<p>You can define which activity to use as the main activity in the Android manifest file, <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">{@code AndroidManifest.xml}</a>, which is
at the root of your project directory.</p>
<p>The main activity for your app must be declared in the manifest with an <a
&lt;intent-filter>}</a> that includes the {@link
android.content.Intent#ACTION_MAIN MAIN} action and
{@link android.content.Intent#CATEGORY_LAUNCHER LAUNCHER} category. For example:</p>
&lt;activity android:name=".MainActivity" android:label="&#64;string/app_name">
&lt;action android:name="android.intent.action.MAIN" />
&lt;category android:name="android.intent.category.LAUNCHER" />
<p class="note"><strong>Note:</strong> When you create a new Android project with the Android SDK
tools, the default project files include an {@link} class that's declared in
the manifest with this filter.</p>
<p>If either the {@link android.content.Intent#ACTION_MAIN MAIN} action or
{@link android.content.Intent#CATEGORY_LAUNCHER LAUNCHER} category are not declared for one of your
activities, then your app icon will not appear in the Home screen's list of apps.</p>
<h2 id="Create">Create a New Instance</h2>
<p>Most apps include several different activities that allow the user to perform different actions.
Whether an activity is the main activity that's created when the user clicks your app icon or a
different activity that your app starts in response to a user action, the system creates
every new instance of {@link} by calling its {@link onCreate()} method.</p>
<p>You must implement the {@link onCreate()} method to perform basic
application startup logic that should happen only once for the entire life of the activity. For
example, your implementation of {@link onCreate()} should define the
user interface and possibly instantiate some class-scope variables.</p>
<p>For example, the following example of the {@link onCreate()}
method shows some code that performs some fundamental setup for the activity, such as
declaring the user interface (defined in an XML layout file), defining member variables,
and configuring some of the UI.</p>
TextView mTextView; // Member variable for text view in the layout
public void onCreate(Bundle savedInstanceState) {
// Set the user interface layout for this Activity
// The layout file is defined in the project res/layout/main_activity.xml file
// Initialize member TextView so we can manipulate it later
mTextView = (TextView) findViewById(;
// Make sure we're running on Honeycomb or higher to use ActionBar APIs
// For the main activity, make sure the app icon in the action bar
// does not behave as a button
ActionBar actionBar = getActionBar();
<p class="caution"><strong>Caution:</strong> Using the {@link android.os.Build.VERSION#SDK_INT} to
prevent older systems from executing new APIs works in this way on Android 2.0 (API level
5) and higher only. Older versions will encounter a runtime exception.</p>
<p>Once the {@link onCreate()} finishes execution, the system
calls the {@link} and {@link} methods
in quick succession. Your activity never resides in the Created or Started states. Technically, the
activity becomes visible to the user when {@link} is called, but
{@link} quickly follows and the activity remains in the Resumed
state until something occurs to change that, such as when a phone call is received, the user
navigates to another activity, or the device screen turns off.</p>
<p>In the other lessons that follow, you'll see how the other start up methods, {@link} and {@link}, are useful during your
activity's lifecycle when used to resume the activity from the Paused or Stopped states.</p>
<p class="note"><strong>Note:</strong> The {@link onCreate()}
method includes a parameter called <code>savedInstanceState</code> that's discussed in the
latter lesson about <a href="recreating.html">Recreating an Activity</a>.</p>
<img src="{@docRoot}images/training/basics/basic-lifecycle-create.png" />
<p class="img-caption"><strong>Figure 2.</strong> Another illustration of the activity lifecycle
structure with an emphasis on the three main callbacks that the system calls in sequence when
creating a new instance of the activity: {@link onCreate()}, {@link}, and {@link}. Once this sequence of
callbacks complete, the activity reaches the Resumed state where users can interact with the
activity until they switch to a different activity.</p>
<h2 id="Destroy">Destroy the Activity</h2>
<p>While the activity's first lifecycle callback is {@link
onCreate()}, its very last callback is {@link}. The system calls
this method on your activity as the final
signal that your activity instance is being completely removed from the system memory.</p>
<p>Most apps don't need to implement this method because local class references are destroyed
with the activity and your activity should perform most cleanup during {@link} and {@link}. However, if your
activity includes background threads that you created during {@link onCreate()} or other long-running resources that could
potentially leak memory if not properly closed, you should kill them during {@link}.</p>
public void onDestroy() {
super.onDestroy(); // Always call the superclass
// Stop method tracing that the activity started during onCreate()
<p class="note"><strong>Note:</strong> The system calls {@link}
after it has already called {@link} and {@link} in all situations except one: when you call {@link} from within the {@link onCreate()}
method. In some cases, such as when your activity operates as a temporary decision maker to
launch another activity, you might call {@link} from within {@link onCreate()} to destroy the activity. In this case, the system
immediately calls {@link} without calling any of the other
lifecycle methods.</p>