blob: de2c92a4aa8932aa5c56881617d329af4590aec9 [file] [log] [blame]
page.title=Pausing and Resuming an Activity
page.tags=activity lifecycle
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<li><a href="#Pause">Pause Your Activity</a></li>
<li><a href="#Resume">Resume 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>During normal app use, the foreground activity is sometimes obstructed by other
visual components that cause the activity to <em>pause</em>. For example, when a semi-transparent
activity opens (such as one in the style of a dialog), the previous activity pauses. As long as the
activity is still partially visible but currently not the activity in focus, it remains paused.</p>
<p>However, once the activity is fully-obstructed and not visible, it <em>stops</em> (which is
discussed in the next lesson).</p>
<p>As your activity enters the paused state, the system calls the {@link onPause()} method on your {@link}, which allows
you to stop ongoing actions that should not continue while paused (such as a video) or persist
any information that should be permanently saved in case the user continues to leave your app. If
the user returns to your activity from the paused state, the system resumes it and calls the
{@link onResume()} method.</p>
<p class="note"><strong>Note:</strong> When your activity receives a call to {@link}, it may be an indication that the activity will be paused for a
moment and the user may return focus to your activity. However, it's usually the first indication
that the user is leaving your activity.</p>
<img src="{@docRoot}images/training/basics/basic-lifecycle-paused.png" />
<p class="img-caption"><strong>Figure 1.</strong> When a semi-transparent activity obscures
your activity, the system calls {@link onPause()} and the activity
waits in the Paused state (1). If the user returns to the activity while it's still paused, the
system calls {@link onResume()} (2).</p>
<h2 id="Pause">Pause Your Activity</h2>
<p>When the system calls {@link} for your activity, it
technically means your activity is still partially visible, but most often is an indication that
the user is leaving the activity and it will soon enter the Stopped state. You should usually use
the {@link} callback to:</p>
<li>Stop animations or other ongoing actions that could consume CPU.</li>
<li>Commit unsaved changes, but only if users expect such changes to be permanently saved when
they leave (such as a draft email).</li>
<li>Release system resources, such as broadcast receivers, handles to sensors (like
GPS), or any resources that may affect battery life while your activity is paused and the user
does not need them.</li>
<p>For example, if your application uses the {@link android.hardware.Camera}, the
{@link} method is a good place to release it.</p>
public void onPause() {
super.onPause(); // Always call the superclass method first
// Release the Camera because we don't need it when paused
// and other activities might need to use it.
if (mCamera != null) {
mCamera = null;
<p>Generally, you should <strong>not</strong> use {@link} to store
user changes (such as personal information entered into a form) to permanent storage. The only time
you should persist user changes to permanent storage within {@link}
is when you're certain users expect the changes to be auto-saved (such as when drafting an email).
However, you should avoid performing CPU-intensive work during {@link}, such as writing to a database, because it can slow the visible
transition to the next activity (you should instead perform heavy-load shutdown operations during
{@link onStop()}).</p>
<p>You should keep the amount of operations done in the {@link
onPause()} method relatively simple in order to allow for a speedy transition to the user's next
destination if your activity is actually being stopped.</p>
<p class="note"><strong>Note:</strong> When your activity is paused, the {@link} instance 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.</p>
<h2 id="Resume">Resume Your Activity</h2>
<p>When the user resumes your activity from the Paused state, the system calls the {@link} method.</p>
<p>Be aware that the system calls this method every time your activity comes into the foreground,
including when it's created for the first time. As such, you should implement {@link} to initialize components that you release during {@link} and perform any other initializations that must occur each time the
activity enters the Resumed state (such as begin animations and initialize components only used
while the activity has user focus).</p>
<p>The following example of {@link} is the counterpart to
the {@link} example above, so it initializes the camera that's
released when the activity pauses.</p>
public void onResume() {
super.onResume(); // Always call the superclass method first
// Get the Camera instance as the activity achieves full user focus
if (mCamera == null) {
initializeCamera(); // Local method to handle camera init