| page.title=Stopping and Restarting an Activity |
| page.tags=activity lifecycle |
| helpoutsWidget=true |
| |
| trainingnavtop=true |
| |
| @jd:body |
| |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| |
| <h2>This lesson teaches you to</h2> |
| <ol> |
| <li><a href="#Stop">Stop Your Activity</a></li> |
| <li><a href="#Start">Start/Restart Your Activity</a></li> |
| </ol> |
| |
| <h2>You should also read</h2> |
| <ul> |
| <li><a href="{@docRoot}guide/components/activities.html">Activities</a> |
| </li> |
| </ul> |
| |
| <h2>Try it out</h2> |
| |
| <div class="download-box"> |
| <a href="http://developer.android.com/shareables/training/ActivityLifecycle.zip" |
| class="button">Download the demo</a> |
| <p class="filename">ActivityLifecycle.zip</p> |
| </div> |
| |
| </div> |
| </div> |
| |
| <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> |
| |
| <ul> |
| <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> |
| </ul> |
| |
| <p>The {@link android.app.Activity} class provides two lifecycle methods, {@link |
| android.app.Activity#onStop()} and {@link android.app.Activity#onRestart()}, 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 android.app.Activity} |
| instance in system memory when it is stopped, it's possible that you don't need to implement the |
| {@link android.app.Activity#onStop()} and {@link android.app.Activity#onRestart()} (or even {@link |
| android.app.Activity#onStart()} 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 |
| android.app.Activity#onPause()} 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 android.app.Activity#onStop onStop()} to stop the activity (1). If the user returns |
| while the activity is stopped, the system calls {@link android.app.Activity#onRestart onRestart()} |
| (2), quickly followed by {@link android.app.Activity#onStart onStart()} (3) and {@link |
| android.app.Activity#onResume()} (4). Notice that no matter what scenario causes the activity to |
| stop, the system always calls {@link android.app.Activity#onPause onPause()} before calling {@link |
| android.app.Activity#onStop onStop()}.</p> |
| |
| |
| |
| <h2 id="Stop">Stop Your Activity</h2> |
| |
| <p>When your activity receives a call to the {@link android.app.Activity#onStop()} 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 android.app.Activity#onDestroy()} callback, so it's important |
| you use {@link android.app.Activity#onStop()} to release resources that might leak memory.</p> |
| |
| <p>Although the {@link android.app.Activity#onPause onPause()} method is called before |
| {@link android.app.Activity#onStop()}, you should use {@link android.app.Activity#onStop onStop()} |
| to perform larger, more CPU intensive shut-down operations, such as writing information to a |
| database.</p> |
| |
| <p>For example, here's an implementation of {@link android.app.Activity#onStop 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. --> |
| <pre> |
| @Override |
| 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()); |
| |
| getContentResolver().update( |
| 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. |
| ); |
| } |
| </pre> |
| |
| <p>When your activity is stopped, the {@link android.app.Activity} object is kept resident in memory |
| and is recalled when the activity resumes. You don’t 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 android.app.Activity#onRestart()}. The system also calls the {@link |
| android.app.Activity#onStart()} method, which happens every time your activity becomes visible |
| (whether being restarted or created for the first time). The {@link |
| android.app.Activity#onRestart()} 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 android.app.Activity#onRestart()} 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 android.app.Activity#onStop()} |
| 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 android.app.Activity#onStart()} callback method as the counterpart |
| to the {@link android.app.Activity#onStop()} method, because the system calls {@link |
| android.app.Activity#onStart()} 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 android.app.Activity#onStart()} method is a good place to verify that |
| required system features are enabled:</p> |
| |
| <pre> |
| @Override |
| 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" |
| } |
| } |
| |
| @Override |
| protected void onRestart() { |
| super.onRestart(); // Always call the superclass method first |
| |
| // Activity being restarted from stopped state |
| } |
| </pre> |
| |
| |
| |
| |
| <p>When the system destroys your activity, it calls the {@link android.app.Activity#onDestroy()} |
| method for your {@link android.app.Activity}. Because you should generally have released most of |
| your resources with {@link android.app.Activity#onStop()}, by the time you receive a call to {@link |
| android.app.Activity#onDestroy()}, 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 |
| stopped.</p> |
| |