diff options
Diffstat (limited to 'docs/html/training/basics/activity-lifecycle/pausing.jd')
| -rw-r--r-- | docs/html/training/basics/activity-lifecycle/pausing.jd | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/docs/html/training/basics/activity-lifecycle/pausing.jd b/docs/html/training/basics/activity-lifecycle/pausing.jd new file mode 100644 index 0000000..216d55e --- /dev/null +++ b/docs/html/training/basics/activity-lifecycle/pausing.jd @@ -0,0 +1,152 @@ +page.title=Pausing and Resuming an Activity +parent.title=Managing the Activity Lifecycle +parent.link=index.html + +trainingnavtop=true +previous.title=Starting an Activity +previous.link=starting.html +next.title=Stopping and Restarting an Activity +next.link=stopping.html + +@jd:body + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#Pause">Pause Your Activity</a></li> + <li><a href="#Resume">Resume Your Activity</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/topics/fundamentals/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>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 +android.app.Activity#onPause onPause()} method on your {@link android.app.Activity}, 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 android.app.Activity#onResume onResume()} method.</p> + +<p class="note"><strong>Note:</strong> When your activity receives a call to {@link +android.app.Activity#onPause()}, 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 android.app.Activity#onPause 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 android.app.Activity#onResume onResume()} (2).</p> + + +<h2 id="Pause">Pause Your Activity</h2> + +<p>When the system calls {@link android.app.Activity#onPause()} 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 android.app.Activity#onPause()} callback to:</p> + +<ul> + <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> +</ul> + +<p>For example, if your application uses the {@link android.hardware.Camera}, the +{@link android.app.Activity#onPause()} method is a good place to release it.</p> + +<pre> +@Override +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.release() + mCamera = null; + } +} +</pre> + +<p>Generally, you should <strong>not</strong> use {@link android.app.Activity#onPause()} 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 android.app.Activity#onPause()} +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 +android.app.Activity#onPause()}, 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 android.app.Activity#onStop onStop()}).</p> + +<p>You should keep the amount of operations done in the {@link android.app.Activity#onPause +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 +android.app.Activity} instance 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.</p> + + + +<h2 id="Resume">Resume Your Activity</h2> + +<p>When the user resumes your activity from the Paused state, the system calls the {@link +android.app.Activity#onResume()} 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 +android.app.Activity#onResume()} to initialize components that you release during {@link +android.app.Activity#onPause()} 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 actiivty has user focus).</p> + +<p>The following example of {@link android.app.Activity#onResume()} is the counterpart to +the {@link android.app.Activity#onPause()} example above, so it initializes the camera that's +released when the activity pauses.</p> + +<pre> +@Override +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 + } +} +</pre> + + + + + + + |