blob: 51c95ea6c97be8588068453baadbb9ba868245b3 [file] [log] [blame]
page.title=Stopping and Restarting an Activity
page.tags=activity lifecycle
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<li><a href="#Stop">Stop Your Activity</a></li>
<li><a href="#Start">Start/Restart Your Activity</a></li>
<h2>You should also read</h2>
<li><a href="{@docRoot}guide/components/activities.html">Activities</a>
<h2>Try it out</h2>
<div class="download-box">
<a href=""
class="button">Download the demo</a>
<p class="filename"></p>
<p>Properly stopping and restarting your activity is an important process in the activity lifecycle
that ensures your users perceive that your app is always alive and doesn't lose their progress.
There are a few of key scenarios in which your activity is stopped and restarted:</p>
<li>The user opens the Recent Apps window and switches from your app to another app. The
activity in your app that's currently in the foreground is stopped. If the user returns to your
app from the Home screen launcher icon or the Recent Apps window, the activity restarts.</li>
<li>The user performs an action in your app that starts a new activity. The current activity
is stopped when the second activity is created. If the user then presses the <em>Back</em>
button, the first activity is restarted.</li>
<li>The user receives a phone call while using your app on his or her phone.</li>
<p>The {@link} class provides two lifecycle methods, {@link} and {@link}, which allow you to
specifically handle how your activity handles being stopped and restarted. Unlike the paused state,
which identifies a partial UI obstruction, the stopped state guarantees that the UI is no longer
visible and the user's focus is in a separate activity (or an entirely separate app).</p>
<p class="note"><strong>Note:</strong> Because the system retains your {@link}
instance in system memory when it is stopped, it's possible that you don't need to implement the
{@link} and {@link} (or even {@link} methods at all. For most activities that are relatively simple, the
activity will stop and restart just fine and you might only need to use {@link} to pause ongoing actions and disconnect from system resources.</p>
<img src="{@docRoot}images/training/basics/basic-lifecycle-stopped.png" />
<p class="img-caption"><strong>Figure 1.</strong> When the user leaves your activity, the system
calls {@link onStop()} to stop the activity (1). If the user returns
while the activity is stopped, the system calls {@link onRestart()}
(2), quickly followed by {@link onStart()} (3) and {@link} (4). Notice that no matter what scenario causes the activity to
stop, the system always calls {@link onPause()} before calling {@link onStop()}.</p>
<h2 id="Stop">Stop Your Activity</h2>
<p>When your activity receives a call to the {@link} method, it's no
longer visible and should release almost all resources that aren't needed while the user is not
using it. Once your activity is stopped, the system might destroy the instance if it needs to
recover system memory. In extreme cases, the system might simply kill your app process without
calling the activity's final {@link} callback, so it's important
you use {@link} to release resources that might leak memory.</p>
<p>Although the {@link onPause()} method is called before
{@link}, you should use {@link onStop()}
to perform larger, more CPU intensive shut-down operations, such as writing information to a
<p>For example, here's an implementation of {@link onStop()} that
saves the contents of a draft note to persistent storage:</p>
<!-- TODO: Find a better example for onStop, because this kind of thing should probably use a
separate thread but that's too complicated to show here. -->
protected void onStop() {
super.onStop(); // Always call the superclass method first
// Save the note's current draft, because the activity is stopping
// and we want to be sure the current note progress isn't lost.
ContentValues values = new ContentValues();
values.put(NotePad.Notes.COLUMN_NAME_NOTE, getCurrentNoteText());
values.put(NotePad.Notes.COLUMN_NAME_TITLE, getCurrentNoteTitle());
mUri, // The URI for the note to update.
values, // The map of column names and new values to apply to them.
null, // No SELECT criteria are used.
null // No WHERE columns are used.
<p>When your activity is stopped, the {@link} object is kept resident in memory
and is recalled when the activity resumes. You dont need to re-initialize components that were
created during any of the callback methods leading up to the Resumed state. The system also
keeps track of the current state for each {@link android.view.View} in the layout, so if the user
entered text into an {@link android.widget.EditText} widget, that content is retained so you don't
need to save and restore it.</p>
<p class="note"><strong>Note:</strong> Even if the system destroys your activity while it's stopped,
it still retains the state of the {@link android.view.View} objects (such as text in an {@link
android.widget.EditText}) in a {@link android.os.Bundle} (a blob of key-value pairs) and restores
them if the user navigates back to the same instance of the activity (the <a
href="recreating.html">next lesson</a> talks more about using a {@link android.os.Bundle} to save
other state data in case your activity is destroyed and recreated).</p>
<h2 id="Start">Start/Restart Your Activity</h2>
<p>When your activity comes back to the foreground from the stopped state, it receives a call to
{@link}. The system also calls the {@link} method, which happens every time your activity becomes visible
(whether being restarted or created for the first time). The {@link} method, however, is called only when the activity resumes from the
stopped state, so you can use it to perform special restoration work that might be necessary only if
the activity was previously stopped, but not destroyed.</p>
<p>It's uncommon that an app needs to use {@link} to restore
the activity's state, so there aren't any guidelines for this method that apply to
the general population of apps. However, because your {@link}
method should essentially clean up all your activity's resources, you'll need to re-instantiate them
when the activity restarts. Yet, you also need to instantiate them when your activity is created
for the first time (when there's no existing instance of the activity). For this reason, you
should usually use the {@link} callback method as the counterpart
to the {@link} method, because the system calls {@link} both when it creates your activity and when it restarts the
activity from the stopped state.</p>
<p>For example, because the user might have been away from your app for a long time before
coming back it, the {@link} method is a good place to verify that
required system features are enabled:</p>
protected void onStart() {
super.onStart(); // Always call the superclass method first
// The activity is either being restarted or started for the first time
// so this is where we should make sure that GPS is enabled
LocationManager locationManager =
(LocationManager) getSystemService(Context.LOCATION_SERVICE);
boolean gpsEnabled = locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER);
if (!gpsEnabled) {
// Create a dialog here that requests the user to enable GPS, and use an intent
// with the android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS action
// to take the user to the Settings screen to enable GPS when they click "OK"
protected void onRestart() {
super.onRestart(); // Always call the superclass method first
// Activity being restarted from stopped state
<p>When the system destroys your activity, it calls the {@link}
method for your {@link}. Because you should generally have released most of
your resources with {@link}, by the time you receive a call to {@link}, there's not much that most apps need to do. This method is your
last chance to clean out resources that could lead to a memory leak, so you should be sure that
additional threads are destroyed and other long-running actions like method tracing are also