1page.title=Stopping and Restarting an Activity
2page.tags=activity lifecycle
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9<div id="tb-wrapper">
10  <div id="tb">
11
12    <h2>This lesson teaches you to</h2>
13    <ol>
14      <li><a href="#Stop">Stop Your Activity</a></li>
15      <li><a href="#Start">Start/Restart Your Activity</a></li>
16    </ol>
17
18    <h2>You should also read</h2>
19    <ul>
20      <li><a href="{@docRoot}guide/components/activities.html">Activities</a>
21      </li>
22    </ul>
23
24<h2>Try it out</h2>
25
26<div class="download-box">
27 <a href="http://developer.android.com/shareables/training/ActivityLifecycle.zip"
28class="button">Download the demo</a>
29 <p class="filename">ActivityLifecycle.zip</p>
30</div>
31
32  </div>
33</div>
34
35<p>Properly stopping and restarting your activity is an important process in the activity lifecycle
36that ensures your users perceive that your app is always alive and doesn't lose their progress.
37There are a few of key scenarios in which your activity is stopped and restarted:</p>
38
39<ul>
40  <li>The user opens the Recent Apps window and switches from your app to another app. The
41activity in your app that's currently in the foreground is stopped. If the user returns to your
42app from the Home screen launcher icon or the Recent Apps window, the activity restarts.</li>
43  <li>The user performs an action in your app that starts a new activity. The current activity
44is stopped when the second activity is created. If the user then presses the <em>Back</em>
45button, the first activity is restarted.</li>
46  <li>The user receives a phone call while using your app on his or her phone.</li>
47</ul>
48
49<p>The {@link android.app.Activity} class provides two lifecycle methods, {@link
50android.app.Activity#onStop()} and {@link android.app.Activity#onRestart()}, which allow you to
51specifically handle how your activity handles being stopped and restarted. Unlike the paused state,
52which identifies a partial UI obstruction, the stopped state guarantees that the UI is no longer
53visible and the user's focus is in a separate activity (or an entirely separate app).</p>
54
55<p class="note"><strong>Note:</strong> Because the system retains your {@link android.app.Activity}
56instance in system memory when it is stopped, it's possible that you don't need to implement the
57{@link android.app.Activity#onStop()} and {@link android.app.Activity#onRestart()} (or even {@link
58android.app.Activity#onStart()} methods at all. For most activities that are relatively simple, the
59activity will stop and restart just fine and you might only need to use {@link
60android.app.Activity#onPause()} to pause ongoing actions and disconnect from system resources.</p>
61
62<img src="{@docRoot}images/training/basics/basic-lifecycle-stopped.png" />
63<p class="img-caption"><strong>Figure 1.</strong> When the user leaves your activity, the system
64calls {@link android.app.Activity#onStop onStop()} to stop the activity (1). If the user returns
65while the activity is stopped, the system calls {@link android.app.Activity#onRestart onRestart()}
66(2), quickly followed by {@link android.app.Activity#onStart onStart()} (3) and {@link
67android.app.Activity#onResume()} (4). Notice that no matter what scenario causes the activity to
68stop, the system always calls {@link android.app.Activity#onPause onPause()} before calling {@link
69android.app.Activity#onStop onStop()}.</p>
70
71
72
73<h2 id="Stop">Stop Your Activity</h2>
74
75<p>When your activity receives a call to the {@link android.app.Activity#onStop()} method, it's no
76longer visible and should release almost all resources that aren't needed while the user is not
77using it. Once your activity is stopped, the system might destroy the instance if it needs to
78recover system memory. In extreme cases, the system might simply kill your app process without
79calling the activity's final {@link android.app.Activity#onDestroy()} callback, so it's important
80you use {@link android.app.Activity#onStop()} to release resources that might leak memory.</p>
81
82<p>Although the {@link android.app.Activity#onPause onPause()} method is called before
83{@link android.app.Activity#onStop()}, you should use {@link android.app.Activity#onStop onStop()}
84to perform larger, more CPU intensive shut-down operations, such as writing information to a
85database.</p>
86
87<p>For example, here's an implementation of {@link android.app.Activity#onStop onStop()} that
88saves the contents of a draft note to persistent storage:</p>
89
90<!-- TODO: Find a better example for onStop, because this kind of thing should probably use a
91separate thread but that's too complicated to show here. -->
92<pre>
93&#64;Override
94protected void onStop() {
95    super.onStop();  // Always call the superclass method first
96
97    // Save the note's current draft, because the activity is stopping
98    // and we want to be sure the current note progress isn't lost.
99    ContentValues values = new ContentValues();
100    values.put(NotePad.Notes.COLUMN_NAME_NOTE, getCurrentNoteText());
101    values.put(NotePad.Notes.COLUMN_NAME_TITLE, getCurrentNoteTitle());
102
103    getContentResolver().update(
104            mUri,    // The URI for the note to update.
105            values,  // The map of column names and new values to apply to them.
106            null,    // No SELECT criteria are used.
107            null     // No WHERE columns are used.
108            );
109}
110</pre>
111
112<p>When your activity is stopped, the {@link android.app.Activity} object is kept resident in memory
113and is recalled when the activity resumes. You don’t need to re-initialize components that were
114created during any of the callback methods leading up to the Resumed state. The system also
115keeps track of the current state for each {@link android.view.View} in the layout, so if the user
116entered text into an {@link android.widget.EditText} widget, that content is retained so you don't
117need to save and restore it.</p>
118
119<p class="note"><strong>Note:</strong> Even if the system destroys your activity while it's stopped,
120it still retains the state of the {@link android.view.View} objects (such as text in an {@link
121android.widget.EditText}) in a {@link android.os.Bundle} (a blob of key-value pairs) and restores
122them if the user navigates back to the same instance of the activity (the <a
123href="recreating.html">next lesson</a> talks more about using a {@link android.os.Bundle} to save
124other state data in case your activity is destroyed and recreated).</p>
125
126
127
128<h2 id="Start">Start/Restart Your Activity</h2>
129
130<p>When your activity comes back to the foreground from the stopped state, it receives a call to
131{@link android.app.Activity#onRestart()}. The system also calls the {@link
132android.app.Activity#onStart()} method, which happens every time your activity becomes visible
133(whether being restarted or created for the first time). The {@link
134android.app.Activity#onRestart()} method, however, is called only when the activity resumes from the
135stopped state, so you can use it to perform special restoration work that might be necessary only if
136the activity was previously stopped, but not destroyed.</p>
137
138<p>It's uncommon that an app needs to use {@link android.app.Activity#onRestart()} to restore
139the activity's state, so there aren't any guidelines for this method that apply to
140the general population of apps. However, because your {@link android.app.Activity#onStop()}
141method should essentially clean up all your activity's resources, you'll need to re-instantiate them
142when the activity restarts. Yet, you also need to instantiate them when your activity is created
143for the first time (when there's no existing instance of the activity). For this reason, you
144should usually use the {@link android.app.Activity#onStart()} callback method as the counterpart
145to the {@link android.app.Activity#onStop()} method, because the system calls {@link
146android.app.Activity#onStart()} both when it creates your activity and when it restarts the
147activity from the stopped state.</p>
148
149<p>For example, because the user might have been away from your app for a long time before
150coming back it, the {@link android.app.Activity#onStart()} method is a good place to verify that
151required system features are enabled:</p>
152
153<pre>
154&#64;Override
155protected void onStart() {
156    super.onStart();  // Always call the superclass method first
157
158    // The activity is either being restarted or started for the first time
159    // so this is where we should make sure that GPS is enabled
160    LocationManager locationManager =
161            (LocationManager) getSystemService(Context.LOCATION_SERVICE);
162    boolean gpsEnabled = locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER);
163
164    if (!gpsEnabled) {
165        // Create a dialog here that requests the user to enable GPS, and use an intent
166        // with the android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS action
167        // to take the user to the Settings screen to enable GPS when they click "OK"
168    }
169}
170
171&#64;Override
172protected void onRestart() {
173    super.onRestart();  // Always call the superclass method first
174
175    // Activity being restarted from stopped state
176}
177</pre>
178
179
180
181
182<p>When the system destroys your activity, it calls the {@link android.app.Activity#onDestroy()}
183method for your {@link android.app.Activity}. Because you should generally have released most of
184your resources with {@link android.app.Activity#onStop()}, by the time you receive a call to {@link
185android.app.Activity#onDestroy()}, there's not much that most apps need to do. This method is your
186last chance to clean out resources that could lead to a memory leak, so you should be sure that
187additional threads are destroyed and other long-running actions like method tracing are also
188stopped.</p>
189
190