1page.title=Pausing and Resuming 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="#Pause">Pause Your Activity</a></li>
15      <li><a href="#Resume">Resume 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>During normal app use, the foreground activity is sometimes obstructed by other
36visual components that cause the activity to <em>pause</em>.  For example, when a semi-transparent
37activity opens (such as one in the style of a dialog), the previous activity pauses. As long as the
38activity is still partially visible but currently not the activity in focus, it remains paused.</p>
39
40<p>However, once the activity is fully-obstructed and not visible, it <em>stops</em> (which is
41discussed in the next lesson).</p>
42
43<p>As your activity enters the paused state, the system calls the {@link
44android.app.Activity#onPause onPause()} method on your {@link android.app.Activity}, which allows
45you to stop ongoing actions that should not continue while paused (such as a video) or persist
46any information that should be permanently saved in case the user continues to leave your app. If
47the user returns to your activity from the paused state, the system resumes it and calls the
48{@link android.app.Activity#onResume onResume()} method.</p>
49
50<p class="note"><strong>Note:</strong> When your activity receives a call to {@link
51android.app.Activity#onPause()}, it may be an indication that the activity will be paused for a
52moment and the user may return focus to your activity. However, it's usually the first indication
53that the user is leaving your activity.</p>
54
55<img src="{@docRoot}images/training/basics/basic-lifecycle-paused.png" />
56<p class="img-caption"><strong>Figure 1.</strong> When a semi-transparent activity obscures
57your activity, the system calls {@link android.app.Activity#onPause onPause()} and the activity
58waits in the Paused state (1). If the user returns to the activity while it's still paused, the
59system calls {@link android.app.Activity#onResume onResume()} (2).</p>
60
61
62<h2 id="Pause">Pause Your Activity</h2>
63
64<p>When the system calls {@link android.app.Activity#onPause()} for your activity, it
65technically means your activity is still partially visible, but most often is an indication that
66the user is leaving the activity and it will soon enter the Stopped state.  You should usually use
67the {@link android.app.Activity#onPause()} callback to:</p>
68
69<ul>
70  <li>Stop animations or other ongoing actions that could consume CPU.</li>
71  <li>Commit unsaved changes, but only if users expect such changes to be permanently saved when
72they leave (such as a draft email).</li>
73  <li>Release system resources, such as broadcast receivers, handles to sensors (like
74GPS), or any resources that may affect battery life while your activity is paused and the user
75does not need them.</li>
76</ul>
77
78<p>For example, if your application uses the {@link android.hardware.Camera}, the
79{@link android.app.Activity#onPause()} method is a good place to release it.</p>
80
81<pre>
82&#64;Override
83public void onPause() {
84    super.onPause();  // Always call the superclass method first
85
86    // Release the Camera because we don't need it when paused
87    // and other activities might need to use it.
88    if (mCamera != null) {
89        mCamera.release()
90        mCamera = null;
91    }
92}
93</pre>
94
95<p>Generally, you should <strong>not</strong> use {@link android.app.Activity#onPause()} to store
96user changes (such as personal information entered into a form) to permanent storage. The only time
97you should persist user changes to permanent storage within {@link android.app.Activity#onPause()}
98is when you're certain users expect the changes to be auto-saved (such as when drafting an email).
99However, you should avoid performing CPU-intensive work during {@link
100android.app.Activity#onPause()}, such as writing to a database, because it can slow the visible
101transition to the next activity (you should instead perform heavy-load shutdown operations during
102{@link android.app.Activity#onStop onStop()}).</p>
103
104<p>You should keep the amount of operations done in the {@link android.app.Activity#onPause
105onPause()} method relatively simple in order to allow for a speedy transition to the user's next
106destination if your activity is actually being stopped.</p>
107
108<p class="note"><strong>Note:</strong> When your activity is paused, the {@link
109android.app.Activity} instance is kept resident in memory and is recalled when the activity resumes.
110You don’t need to re-initialize components that were created during any of the callback methods
111leading up to the Resumed state.</p>
112
113
114
115<h2 id="Resume">Resume Your Activity</h2>
116
117<p>When the user resumes your activity from the Paused state, the system calls the {@link
118android.app.Activity#onResume()} method.</p>
119
120<p>Be aware that the system calls this method every time your activity comes into the foreground,
121including when it's created for the first time. As such, you should implement {@link
122android.app.Activity#onResume()} to initialize components that you release during {@link
123android.app.Activity#onPause()} and perform any other initializations that must occur each time the
124activity enters the Resumed state (such as begin animations and initialize components only used
125while the activity has user focus).</p>
126
127<p>The following example of {@link android.app.Activity#onResume()} is the counterpart to
128the {@link android.app.Activity#onPause()} example above, so it initializes the camera that's
129released when the activity pauses.</p>
130
131<pre>
132&#64;Override
133public void onResume() {
134    super.onResume();  // Always call the superclass method first
135
136    // Get the Camera instance as the activity achieves full user focus
137    if (mCamera == null) {
138        initializeCamera(); // Local method to handle camera init
139    }
140}
141</pre>
142
143
144
145
146
147
148
149