1 page.title=Activities 2 page.tags="activity","intent" 3 @jd:body 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>Quickview</h2> 8 <ul> 9 <li>An activity provides a user interface for a single screen in your application</li> 10 <li>Activities can move into the background and then be resumed with their state restored</li> 11 </ul> 12 13 <h2>In this document</h2> 14 <ol> 15 <li><a href="#Creating">Creating an Activity</a> 16 <ol> 17 <li><a href="#UI">Implementing a user interface</a></li> 18 <li><a href="#Declaring">Declaring the activity in the manifest</a></li> 19 </ol> 20 </li> 21 <li><a href="#StartingAnActivity">Starting an Activity</a> 22 <ol> 23 <li><a href="#StartingAnActivityForResult">Starting an activity for a result</a></li> 24 </ol> 25 </li> 26 <li><a href="#ShuttingDown">Shutting Down an Activity</a></li> 27 <li><a href="#Lifecycle">Managing the Activity Lifecycle</a> 28 <ol> 29 <li><a href="#ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</a></li> 30 <li><a href="#SavingActivityState">Saving activity state</a></li> 31 <li><a href="#ConfigurationChanges">Handling configuration changes</a></li> 32 <li><a href="#CoordinatingActivities">Coordinating activities</a></li> 33 </ol> 34 </li> 35 </ol> 36 37 <h2>Key classes</h2> 38 <ol> 39 <li>{@link android.app.Activity}</li> 40 </ol> 41 42 <h2>See also</h2> 43 <ol> 44 <li><a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back 45 Stack</a></li> 46 </ol> 47 48 </div> 49 </div> 50 51 52 53 <p>An {@link android.app.Activity} is an application component that provides a screen with which 54 users can interact in order to do something, such as dial the phone, take a photo, send an email, or 55 view a map. Each activity is given a window in which to draw its user interface. The window 56 typically fills the screen, but may be smaller than the screen and float on top of other 57 windows.</p> 58 59 <p> An application usually consists of multiple activities that are loosely bound 60 to each other. Typically, one activity in an application is specified as the "main" activity, which 61 is presented to the user when launching the application for the first time. Each 62 activity can then start another activity in order to perform different actions. Each time a new 63 activity starts, the previous activity is stopped, but the system preserves the activity 64 in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and 65 takes user focus. The back stack abides to the basic "last in, first out" stack mechanism, 66 so, when the user is done with the current activity and presses the <em>Back</em> button, it 67 is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is 68 discussed more in the <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks 69 and Back Stack</a> document.)</p> 70 71 <p>When an activity is stopped because a new activity starts, it is notified of this change in state 72 through the activity's lifecycle callback methods. 73 There are several callback methods that an activity might receive, due to a change in its 74 state—whether the system is creating it, stopping it, resuming it, or destroying it—and 75 each callback provides you the opportunity to perform specific work that's 76 appropriate to that state change. For instance, when stopped, your activity should release any 77 large objects, such as network or database connections. When the activity resumes, you can 78 reacquire the necessary resources and resume actions that were interrupted. These state transitions 79 are all part of the activity lifecycle.</p> 80 81 <p>The rest of this document discusses the basics of how to build and use an activity, 82 including a complete discussion of how the activity lifecycle works, so you can properly manage 83 the transition between various activity states.</p> 84 85 86 87 <h2 id="Creating">Creating an Activity</h2> 88 89 <p>To create an activity, you must create a subclass of {@link android.app.Activity} (or 90 an existing subclass of it). In your subclass, you need to implement callback methods that the 91 system calls when the activity transitions between various states of its lifecycle, such as when 92 the activity is being created, stopped, resumed, or destroyed. The two most important callback 93 methods are:</p> 94 95 <dl> 96 <dt>{@link android.app.Activity#onCreate onCreate()}</dt> 97 <dd>You must implement this method. The system calls this when creating your 98 activity. Within your implementation, you should initialize the essential components of your 99 activity. 100 Most importantly, this is where you must call {@link android.app.Activity#setContentView 101 setContentView()} to define the layout for the activity's user interface.</dd> 102 <dt>{@link android.app.Activity#onPause onPause()}</dt> 103 <dd>The system calls this method as the first indication that the user is leaving your 104 activity (though it does not always mean the activity is being destroyed). This is usually where you 105 should commit any changes that should be persisted beyond the current user session (because 106 the user might not come back).</dd> 107 </dl> 108 109 <p>There are several other lifecycle callback methods that you should use in order to provide a 110 fluid user experience between activities and handle unexpected interuptions that cause your activity 111 to be stopped and even destroyed. All of the lifecycle callback methods are discussed later, in 112 the section about <a href="#Lifecycle">Managing the Activity Lifecycle</a>.</p> 113 114 115 116 <h3 id="UI">Implementing a user interface</h3> 117 118 <p> The user interface for an activity is provided by a hierarchy of views—objects derived 119 from the {@link android.view.View} class. Each view controls a particular rectangular space 120 within the activity's window and can respond to user interaction. For example, a view might be a 121 button that initiates an action when the user touches it.</p> 122 123 <p>Android provides a number of ready-made views that you can use to design and organize your 124 layout. "Widgets" are views that provide a visual (and interactive) elements for the screen, such 125 as a button, text field, checkbox, or just an image. "Layouts" are views derived from {@link 126 android.view.ViewGroup} that provide a unique layout model for its child views, such as a linear 127 layout, a grid layout, or relative layout. You can also subclass the {@link android.view.View} and 128 {@link android.view.ViewGroup} classes (or existing subclasses) to create your own widgets and 129 layouts and apply them to your activity layout.</p> 130 131 <p>The most common way to define a layout using views is with an XML layout file saved in your 132 application resources. This way, you can maintain the design of your user interface separately from 133 the source code that defines the activity's behavior. You can set the layout as the UI for your 134 activity with {@link android.app.Activity#setContentView(int) setContentView()}, passing the 135 resource ID for the layout. However, you can also create new {@link android.view.View}s in your 136 activity code and build a view hierarchy by inserting new {@link 137 android.view.View}s into a {@link android.view.ViewGroup}, then use that layout by passing the root 138 {@link android.view.ViewGroup} to {@link android.app.Activity#setContentView(View) 139 setContentView()}.</p> 140 141 <p>For information about creating a user interface, see the <a 142 href="{@docRoot}guide/topics/ui/index.html">User Interface</a> documentation.</p> 143 144 145 146 <h3 id="Declaring">Declaring the activity in the manifest</h3> 147 148 <p>You must declare your activity in the manifest file in order for it to 149 be accessible to the system. To declare your activity, open your manifest file and add an <a 150 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element 151 as a child of the <a 152 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 153 element. For example:</p> 154 155 <pre> 156 <manifest ... > 157 <application ... > 158 <activity android:name=".ExampleActivity" /> 159 ... 160 </application ... > 161 ... 162 </manifest > 163 </pre> 164 165 <p>There are several other attributes that you can include in this element, to define properties 166 such as the label for the activity, an icon for the activity, or a theme to style the activity's 167 UI. The <a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">{@code android:name}</a> 168 attribute is the only required attribute—it specifies the class name of the activity. Once 169 you publish your application, you should not change this name, because if you do, you might break 170 some functionality, such as application shortcuts (read the blog post, <a 171 href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things 172 That Cannot Change</a>).</p> 173 174 <p>See the <a 175 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element 176 reference for more information about declaring your activity in the manifest.</p> 177 178 179 <h4>Using intent filters</h4> 180 181 <p>An <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 182 <activity>}</a> element can also specify various intent filters—using the <a 183 href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code 184 <intent-filter>}</a> element—in order to declare how other application components may 185 activate it.</p> 186 187 <p>When you create a new application using the Android SDK tools, the stub activity 188 that's created for you automatically includes an intent filter that declares the activity 189 responds to the "main" action and should be placed in the "launcher" category. The intent filter 190 looks like this:</p> 191 192 <pre> 193 <activity android:name=".ExampleActivity" android:icon="@drawable/app_icon"> 194 <intent-filter> 195 <action android:name="android.intent.action.MAIN" /> 196 <category android:name="android.intent.category.LAUNCHER" /> 197 </intent-filter> 198 </activity> 199 </pre> 200 201 <p>The <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code 202 <action>}</a> element specifies that this is the "main" entry point to the application. The <a 203 href="{@docRoot}guide/topics/manifest/category-element.html">{@code 204 <category>}</a> element specifies that this activity should be listed in the 205 system's application launcher (to allow users to launch this activity).</p> 206 207 <p>If you intend for your application to be self-contained and not allow other applications to 208 activate its activities, then you don't need any other intent filters. Only one activity should 209 have the "main" action and "launcher" category, as in the previous example. Activities that 210 you don't want to make available to other applications should have no intent filters and you can 211 start them yourself using explicit intents (as discussed in the following section).</p> 212 213 <p>However, if you want your activity to respond to implicit intents that are delivered from 214 other applications (and your own), then you must define additional intent filters for your 215 activity. For each type of intent to which you want to respond, you must include an <a 216 href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code 217 <intent-filter>}</a> that includes an 218 <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code 219 <action>}</a> element and, optionally, a <a 220 href="{@docRoot}guide/topics/manifest/category-element.html">{@code 221 <category>}</a> element and/or a <a 222 href="{@docRoot}guide/topics/manifest/data-element.html">{@code 223 <data>}</a> element. These elements specify the type of intent to which your activity can 224 respond.</p> 225 226 <p>For more information about how your activities can respond to intents, see the <a 227 href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> 228 document.</p> 229 230 231 232 <h2 id="StartingAnActivity">Starting an Activity</h2> 233 234 <p>You can start another activity by calling {@link android.app.Activity#startActivity 235 startActivity()}, passing it an {@link android.content.Intent} that describes the activity you 236 want to start. The intent specifies either the exact activity you want to start or describes the 237 type of action you want to perform (and the system selects the appropriate activity for you, 238 which 239 can even be from a different application). An intent can also carry small amounts of data to be 240 used by the activity that is started.</p> 241 242 <p>When working within your own application, you'll often need to simply launch a known activity. 243 You can do so by creating an intent that explicitly defines the activity you want to start, 244 using the class name. For example, here's how one activity starts another activity named {@code 245 SignInActivity}:</p> 246 247 <pre> 248 Intent intent = new Intent(this, SignInActivity.class); 249 startActivity(intent); 250 </pre> 251 252 <p>However, your application might also want to perform some action, such as send an email, text 253 message, or status update, using data from your activity. In this case, your application might 254 not have its own activities to perform such actions, so you can instead leverage the activities 255 provided by other applications on the device, which can perform the actions for you. This is where 256 intents are really valuable—you can create an intent that describes an action you want to 257 perform and the system 258 launches the appropriate activity from another application. If there are 259 multiple activities that can handle the intent, then the user can select which one to use. For 260 example, if you want to allow the user to send an email message, you can create the 261 following intent:</p> 262 263 <pre> 264 Intent intent = new Intent(Intent.ACTION_SEND); 265 intent.putExtra(Intent.EXTRA_EMAIL, recipientArray); 266 startActivity(intent); 267 </pre> 268 269 <p>The {@link android.content.Intent#EXTRA_EMAIL} extra added to the intent is a string array of 270 email addresses to which the email should be sent. When an email application responds to this 271 intent, it reads the string array provided in the extra and places them in the "to" field of the 272 email composition form. In this situation, the email application's activity starts and when the 273 user is done, your activity resumes.</p> 274 275 276 277 278 <h3 id="StartingAnActivityForResult">Starting an activity for a result</h3> 279 280 <p>Sometimes, you might want to receive a result from the activity that you start. In that case, 281 start the activity by calling {@link android.app.Activity#startActivityForResult 282 startActivityForResult()} (instead of {@link android.app.Activity#startActivity 283 startActivity()}). To then receive the result from the subsequent 284 activity, implement the {@link android.app.Activity#onActivityResult onActivityResult()} callback 285 method. When the subsequent activity is done, it returns a result in an {@link 286 android.content.Intent} to your {@link android.app.Activity#onActivityResult onActivityResult()} 287 method.</p> 288 289 <p>For example, perhaps you want the user to pick one of their contacts, so your activity can 290 do something with the information in that contact. Here's how you can create such an intent and 291 handle the result:</p> 292 293 <pre> 294 private void pickContact() { 295 // Create an intent to "pick" a contact, as defined by the content provider URI 296 Intent intent = new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI); 297 startActivityForResult(intent, PICK_CONTACT_REQUEST); 298 } 299 300 @Override 301 protected void onActivityResult(int requestCode, int resultCode, Intent data) { 302 // If the request went well (OK) and the request was PICK_CONTACT_REQUEST 303 if (resultCode == Activity.RESULT_OK && requestCode == PICK_CONTACT_REQUEST) { 304 // Perform a query to the contact's content provider for the contact's name 305 Cursor cursor = getContentResolver().query(data.getData(), 306 new String[] {Contacts.DISPLAY_NAME}, null, null, null); 307 if (cursor.moveToFirst()) { // True if the cursor is not empty 308 int columnIndex = cursor.getColumnIndex(Contacts.DISPLAY_NAME); 309 String name = cursor.getString(columnIndex); 310 // Do something with the selected contact's name... 311 } 312 } 313 } 314 </pre> 315 316 <p>This example shows the basic logic you should use in your {@link 317 android.app.Activity#onActivityResult onActivityResult()} method in order to handle an 318 activity result. The first condition checks whether the request was successful—if it was, then 319 the {@code resultCode} will be {@link android.app.Activity#RESULT_OK}—and whether the request 320 to which this result is responding is known—in this case, the {@code requestCode} matches the 321 second parameter sent with {@link android.app.Activity#startActivityForResult 322 startActivityForResult()}. From there, the code handles the activity result by querying the 323 data returned in an {@link android.content.Intent} (the {@code data} parameter).</p> 324 325 <p>What happens is, a {@link 326 android.content.ContentResolver} performs a query against a content provider, which returns a 327 {@link android.database.Cursor} that allows the queried data to be read. For more information, see 328 the <a 329 href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> document.</p> 330 331 <p>For more information about using intents, see the <a 332 href="{@docRoot}guide/components/intents-filters.html">Intents and Intent 333 Filters</a> document.</p> 334 335 336 <h2 id="ShuttingDown">Shutting Down an Activity</h2> 337 338 <p>You can shut down an activity by calling its {@link android.app.Activity#finish 339 finish()} method. You can also shut down a separate activity that you previously started by calling 340 {@link android.app.Activity#finishActivity finishActivity()}.</p> 341 342 <p class="note"><strong>Note:</strong> In most cases, you should not explicitly finish an activity 343 using these methods. As discussed in the following section about the activity lifecycle, the 344 Android system manages the life of an activity for you, so you do not need to finish your own 345 activities. Calling these methods could adversely affect the expected user 346 experience and should only be used when you absolutely do not want the user to return to this 347 instance of the activity.</p> 348 349 350 <h2 id="Lifecycle">Managing the Activity Lifecycle</h2> 351 352 <p>Managing the lifecycle of your activities by implementing callback methods is 353 crucial to developing a strong 354 and flexible application. The lifecycle of an activity is directly affected by its association with 355 other activities, its task and back stack.</p> 356 357 <p>An activity can exist in essentially three states:</p> 358 359 <dl> 360 <dt><i>Resumed</i></dt> 361 <dd>The activity is in the foreground of the screen and has user focus. (This state is 362 also sometimes referred to as "running".)</dd> 363 364 <dt><i>Paused</i></dt> 365 <dd>Another activity is in the foreground and has focus, but this one is still visible. That is, 366 another activity is visible on top of this one and that activity is partially transparent or doesn't 367 cover the entire screen. A paused activity is completely alive (the {@link android.app.Activity} 368 object is retained in memory, it maintains all state and member information, and remains attached to 369 the window manager), but can be killed by the system in extremely low memory situations.</dd> 370 371 <dt><i>Stopped</i></dt> 372 <dd>The activity is completely obscured by another activity (the activity is now in the 373 "background"). A stopped activity is also still alive (the {@link android.app.Activity} 374 object is retained in memory, it maintains all state and member information, but is <em>not</em> 375 attached to the window manager). However, it is no longer visible to the user and it 376 can be killed by the system when memory is needed elsewhere.</dd> 377 </dl> 378 379 <p>If an activity is paused or stopped, the system can drop it from memory either by asking it to 380 finish (calling its {@link android.app.Activity#finish finish()} method), or simply killing its 381 process. When the activity is opened again (after being finished or killed), it must be created all 382 over.</p> 383 384 385 386 <h3 id="ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</h3> 387 388 <p>When an activity transitions into and out of the different states described above, it is notified 389 through various callback methods. All of the callback methods are hooks that you 390 can override to do appropriate work when the state of your activity changes. The following skeleton 391 activity includes each of the fundamental lifecycle methods:</p> 392 393 394 <pre> 395 public class ExampleActivity extends Activity { 396 @Override 397 public void {@link android.app.Activity#onCreate onCreate}(Bundle savedInstanceState) { 398 super.onCreate(savedInstanceState); 399 // The activity is being created. 400 } 401 @Override 402 protected void {@link android.app.Activity#onStart onStart()} { 403 super.onStart(); 404 // The activity is about to become visible. 405 } 406 @Override 407 protected void {@link android.app.Activity#onResume onResume()} { 408 super.onResume(); 409 // The activity has become visible (it is now "resumed"). 410 } 411 @Override 412 protected void {@link android.app.Activity#onPause onPause()} { 413 super.onPause(); 414 // Another activity is taking focus (this activity is about to be "paused"). 415 } 416 @Override 417 protected void {@link android.app.Activity#onStop onStop()} { 418 super.onStop(); 419 // The activity is no longer visible (it is now "stopped") 420 } 421 @Override 422 protected void {@link android.app.Activity#onDestroy onDestroy()} { 423 super.onDestroy(); 424 // The activity is about to be destroyed. 425 } 426 } 427 </pre> 428 429 <p class="note"><strong>Note:</strong> Your implementation of these lifecycle methods must 430 always call the superclass implementation before doing any work, as shown in the examples above.</p> 431 432 <p>Taken together, these methods define the entire lifecycle of an activity. By implementing these 433 methods, you can monitor three nested loops in the activity lifecycle: </p> 434 435 <ul> 436 <li>The <b>entire lifetime</b> of an activity happens between the call to {@link 437 android.app.Activity#onCreate onCreate()} and the call to {@link 438 android.app.Activity#onDestroy}. Your activity should perform setup of 439 "global" state (such as defining layout) in {@link android.app.Activity#onCreate onCreate()}, and 440 release all remaining resources in {@link android.app.Activity#onDestroy}. For example, if your 441 activity has a thread running in the background to download data from the network, it might create 442 that thread in {@link android.app.Activity#onCreate onCreate()} and then stop the thread in {@link 443 android.app.Activity#onDestroy}.</li> 444 445 <li><p>The <b>visible lifetime</b> of an activity happens between the call to {@link 446 android.app.Activity#onStart onStart()} and the call to {@link 447 android.app.Activity#onStop onStop()}. During this time, the user can see the activity 448 on-screen and interact with it. For example, {@link android.app.Activity#onStop onStop()} is called 449 when a new activity starts and this one is no longer visible. Between these two methods, you can 450 maintain resources that are needed to show the activity to the user. For example, you can register a 451 {@link android.content.BroadcastReceiver} in {@link 452 android.app.Activity#onStart onStart()} to monitor changes that impact your UI, and unregister 453 it in {@link android.app.Activity#onStop onStop()} when the user can no longer see what you are 454 displaying. The system might call {@link android.app.Activity#onStart onStart()} and {@link 455 android.app.Activity#onStop onStop()} multiple times during the entire lifetime of the activity, as 456 the activity alternates between being visible and hidden to the user.</p></li> 457 458 <li><p>The <b>foreground lifetime</b> of an activity happens between the call to {@link 459 android.app.Activity#onResume onResume()} and the call to {@link android.app.Activity#onPause 460 onPause()}. During this time, the activity is in front of all other activities on screen and has 461 user input focus. An activity can frequently transition in and out of the foreground—for 462 example, {@link android.app.Activity#onPause onPause()} is called when the device goes to sleep or 463 when a dialog appears. Because this state can transition often, the code in these two methods should 464 be fairly lightweight in order to avoid slow transitions that make the user wait.</p></li> 465 </ul> 466 467 <p>Figure 1 illustrates these loops and the paths an activity might take between states. 468 The rectangles represent the callback methods you can implement to perform operations when 469 the activity transitions between states. <p> 470 471 <img src="{@docRoot}images/activity_lifecycle.png" alt="" /> 472 <p class="img-caption"><strong>Figure 1.</strong> The activity lifecycle.</p> 473 474 <p>The same lifecycle callback methods are listed in table 1, which describes each of the callback 475 methods in more detail and locates each one within the 476 activity's overall lifecycle, including whether the system can kill the activity after the 477 callback method completes.</p> 478 479 <p class="table-caption"><strong>Table 1.</strong> A summary of the activity lifecycle's 480 callback methods.</p> 481 482 <table border="2" width="85%" frame="hsides" rules="rows"> 483 <colgroup align="left" span="3"></colgroup> 484 <colgroup align="left"></colgroup> 485 <colgroup align="center"></colgroup> 486 <colgroup align="center"></colgroup> 487 488 <thead> 489 <tr><th colspan="3">Method</th> <th>Description</th> <th>Killable after?</th> <th>Next</th></tr> 490 </thead> 491 492 <tbody> 493 <tr> 494 <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td> 495 <td>Called when the activity is first created. 496 This is where you should do all of your normal static set up — 497 create views, bind data to lists, and so on. This method is passed 498 a Bundle object containing the activity's previous state, if that 499 state was captured (see <a href="#actstate">Saving Activity State</a>, 500 later). 501 <p>Always followed by {@code onStart()}.</p></td> 502 <td align="center">No</td> 503 <td align="center">{@code onStart()}</td> 504 </tr> 505 506 <tr> 507 <td rowspan="5" style="border-left: none; border-right: none;"> </td> 508 <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart 509 onRestart()}</code></td> 510 <td>Called after the activity has been stopped, just prior to it being 511 started again. 512 <p>Always followed by {@code onStart()}</p></td> 513 <td align="center">No</td> 514 <td align="center">{@code onStart()}</td> 515 </tr> 516 517 <tr> 518 <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td> 519 <td>Called just before the activity becomes visible to the user. 520 <p>Followed by {@code onResume()} if the activity comes 521 to the foreground, or {@code onStop()} if it becomes hidden.</p></td> 522 <td align="center">No</td> 523 <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> 524 </tr> 525 526 <tr> 527 <td rowspan="2" style="border-left: none;"> </td> 528 <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td> 529 <td>Called just before the activity starts 530 interacting with the user. At this point the activity is at 531 the top of the activity stack, with user input going to it. 532 <p>Always followed by {@code onPause()}.</p></td> 533 <td align="center">No</td> 534 <td align="center">{@code onPause()}</td> 535 </tr> 536 537 <tr> 538 <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td> 539 <td>Called when the system is about to start resuming another 540 activity. This method is typically used to commit unsaved changes to 541 persistent data, stop animations and other things that may be consuming 542 CPU, and so on. It should do whatever it does very quickly, because 543 the next activity will not be resumed until it returns. 544 <p>Followed either by {@code onResume()} if the activity 545 returns back to the front, or by {@code onStop()} if it becomes 546 invisible to the user.</td> 547 <td align="center"><strong style="color:#800000">Yes</strong></td> 548 <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> 549 </tr> 550 551 <tr> 552 <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td> 553 <td>Called when the activity is no longer visible to the user. This 554 may happen because it is being destroyed, or because another activity 555 (either an existing one or a new one) has been resumed and is covering it. 556 <p>Followed either by {@code onRestart()} if 557 the activity is coming back to interact with the user, or by 558 {@code onDestroy()} if this activity is going away.</p></td> 559 <td align="center"><strong style="color:#800000">Yes</strong></td> 560 <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td> 561 </tr> 562 563 <tr> 564 <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy 565 onDestroy()}</code></td> 566 <td>Called before the activity is destroyed. This is the final call 567 that the activity will receive. It could be called either because the 568 activity is finishing (someone called <code>{@link android.app.Activity#finish 569 finish()}</code> on it), or because the system is temporarily destroying this 570 instance of the activity to save space. You can distinguish 571 between these two scenarios with the <code>{@link 572 android.app.Activity#isFinishing isFinishing()}</code> method.</td> 573 <td align="center"><strong style="color:#800000">Yes</strong></td> 574 <td align="center"><em>nothing</em></td> 575 </tr> 576 </tbody> 577 </table> 578 579 <p>The column labeled "Killable after?" indicates whether or not the system can 580 kill the process hosting the activity at any time <em>after the method returns</em>, without 581 executing another line of the activity's code. Three methods are marked "yes": ({@link 582 android.app.Activity#onPause 583 onPause()}, {@link android.app.Activity#onStop onStop()}, and {@link android.app.Activity#onDestroy 584 onDestroy()}). Because {@link android.app.Activity#onPause onPause()} is the first 585 of the three, once the activity is created, {@link android.app.Activity#onPause onPause()} is the 586 last method that's guaranteed to be called before the process <em>can</em> be killed—if 587 the system must recover memory in an emergency, then {@link 588 android.app.Activity#onStop onStop()} and {@link android.app.Activity#onDestroy onDestroy()} might 589 not be called. Therefore, you should use {@link android.app.Activity#onPause onPause()} to write 590 crucial persistent data (such as user edits) to storage. However, you should be selective about 591 what information must be retained during {@link android.app.Activity#onPause onPause()}, because any 592 blocking procedures in this method block the transition to the next activity and slow the user 593 experience.</p> 594 595 <p> Methods that are marked "No" in the <b>Killable</b> column protect the process hosting the 596 activity from being killed from the moment they are called. Thus, an activity is killable 597 from the time {@link android.app.Activity#onPause onPause()} returns to the time 598 {@link android.app.Activity#onResume onResume()} is called. It will not again be killable until 599 {@link android.app.Activity#onPause onPause()} is again called and returns. </p> 600 601 <p class="note"><strong>Note:</strong> An activity that's not technically "killable" by this 602 definition in table 1 might still be killed by the system—but that would happen only in 603 extreme circumstances when there is no other recourse. When an activity might be killed is 604 discussed more in the <a 605 href="{@docRoot}guide/components/processes-and-threads.html">Processes and 606 Threading</a> document.</p> 607 608 609 <h3 id="SavingActivityState">Saving activity state</h3> 610 611 <p>The introduction to <a href="#Lifecycle">Managing the Activity Lifecycle</a> briefly mentions 612 that 613 when an activity is paused or stopped, the state of the activity is retained. This is true because 614 the {@link android.app.Activity} object is still held in memory when it is paused or 615 stopped—all information about its members and current state is still alive. Thus, any changes 616 the user made within the activity are retained so that when the activity returns to the 617 foreground (when it "resumes"), those changes are still there.</p> 618 619 <p>However, when the system destroys an activity in order to recover memory, the {@link 620 android.app.Activity} object is destroyed, so the system cannot simply resume it with its state 621 intact. Instead, the system must recreate the {@link android.app.Activity} object if the user 622 navigates back to it. Yet, the user is unaware 623 that the system destroyed the activity and recreated it and, thus, probably 624 expects the activity to be exactly as it was. In this situation, you can ensure that 625 important information about the activity state is preserved by implementing an additional 626 callback method that allows you to save information about the state of your activity: {@link 627 android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> 628 629 <p>The system calls {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} 630 before making the activity vulnerable to destruction. The system passes this method 631 a {@link android.os.Bundle} in which you can save 632 state information about the activity as name-value pairs, using methods such as {@link 633 android.os.Bundle#putString putString()} and {@link 634 android.os.Bundle#putInt putInt()}. Then, if the system kills your application 635 process and the user navigates back to your activity, the system recreates the activity and passes 636 the {@link android.os.Bundle} to both {@link android.app.Activity#onCreate onCreate()} and {@link 637 android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}. Using either of these 638 methods, you can extract your saved state from the {@link android.os.Bundle} and restore the 639 activity state. If there is no state information to restore, then the {@link 640 android.os.Bundle} passed to you is null (which is the case when the activity is created for 641 the first time).</p> 642 643 <img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> 644 <p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user 645 focus with its state intact: either the activity is destroyed, then recreated and the activity must restore 646 the previously saved state, or the activity is stopped, then resumed and the activity state 647 remains intact.</p> 648 649 <p class="note"><strong>Note:</strong> There's no guarantee that {@link 650 android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your 651 activity is destroyed, because there are cases in which it won't be necessary to save the state 652 (such as when the user leaves your activity using the <em>Back</em> button, because the user is 653 explicitly 654 closing the activity). If the system calls {@link android.app.Activity#onSaveInstanceState 655 onSaveInstanceState()}, it does so before {@link 656 android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause 657 onPause()}.</p> 658 659 <p>However, even if you do nothing and do not implement {@link 660 android.app.Activity#onSaveInstanceState onSaveInstanceState()}, some of the activity state is 661 restored by the {@link android.app.Activity} class's default implementation of {@link 662 android.app.Activity#onSaveInstanceState onSaveInstanceState()}. Specifically, the default 663 implementation calls the corresponding {@link 664 android.view.View#onSaveInstanceState onSaveInstanceState()} method for every {@link 665 android.view.View} in the layout, which allows each view to provide information about itself 666 that should be saved. Almost every widget in the Android framework implements this method as 667 appropriate, such that any visible changes to the UI are automatically saved and restored when your 668 activity is recreated. For example, the {@link android.widget.EditText} widget saves any text 669 entered by the user and the {@link android.widget.CheckBox} widget saves whether it's checked or 670 not. The only work required by you is to provide a unique ID (with the <a 671 href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> 672 attribute) for each widget you want to save its state. If a widget does not have an ID, then the 673 system cannot save its state.</p> 674 675 <div class="sidebox-wrapper"> 676 <div class="sidebox"> 677 <p>You can also explicitly stop a view in your layout from saving its state by setting the 678 {@link android.R.attr#saveEnabled android:saveEnabled} attribute to {@code "false"} or by calling 679 the {@link android.view.View#setSaveEnabled setSaveEnabled()} method. Usually, you should not 680 disable this, but you might if you want to restore the state of the activity UI differently.</p> 681 </div> 682 </div> 683 684 <p>Although the default implementation of {@link 685 android.app.Activity#onSaveInstanceState onSaveInstanceState()} saves useful information about 686 your activity's UI, you still might need to override it to save additional information. 687 For example, you might need to save member values that changed during the activity's life (which 688 might correlate to values restored in the UI, but the members that hold those UI values are not 689 restored, by default).</p> 690 691 <p>Because the default implementation of {@link 692 android.app.Activity#onSaveInstanceState onSaveInstanceState()} helps save the state of the UI, if 693 you override the method in order to save additional state information, you should always call the 694 superclass implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} 695 before doing any work. Likewise, you should also call the superclass implementation of {@link 696 android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} if you override it, so the 697 default implementation can restore view states.</p> 698 699 <p class="note"><strong>Note:</strong> Because {@link android.app.Activity#onSaveInstanceState 700 onSaveInstanceState()} is not guaranteed 701 to be called, you should use it only to record the transient state of the activity (the state of 702 the UI)—you should never use it to store persistent data. Instead, you should use {@link 703 android.app.Activity#onPause onPause()} to store persistent data (such as data that should be saved 704 to a database) when the user leaves the activity.</p> 705 706 <p>A good way to test your application's ability to restore its state is to simply rotate the 707 device so that the screen orientation changes. When the screen orientation changes, the system 708 destroys and recreates the activity in order to apply alternative resources that might be available 709 for the new screen configuration. For this reason alone, it's very important that your activity 710 completely restores its state when it is recreated, because users regularly rotate the screen while 711 using applications.</p> 712 713 714 <h3 id="ConfigurationChanges">Handling configuration changes</h3> 715 716 <p>Some device configurations can change during runtime (such as screen orientation, keyboard 717 availability, and language). When such a change occurs, Android recreates the running activity 718 (the system calls {@link android.app.Activity#onDestroy}, then immediately calls {@link 719 android.app.Activity#onCreate onCreate()}). This behavior is 720 designed to help your application adapt to new configurations by automatically reloading your 721 application with alternative resources that you've provided (such as different layouts for 722 different screen orientations and sizes).</p> 723 724 <p>If you properly design your activity to handle a restart due to a screen orientation change and 725 restore the activity state as described above, your application will be more resilient to other 726 unexpected events in the activity lifecycle.</p> 727 728 <p>The best way to handle such a restart is 729 to save and restore the state of your activity using {@link 730 android.app.Activity#onSaveInstanceState onSaveInstanceState()} and {@link 731 android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (or {@link 732 android.app.Activity#onCreate onCreate()}), as discussed in the previous section.</p> 733 734 <p>For more information about configuration changes that happen at runtime and how you can handle 735 them, read the guide to <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling 736 Runtime Changes</a>.</p> 737 738 739 740 <h3 id="CoordinatingActivities">Coordinating activities</h3> 741 742 <p>When one activity starts another, they both experience lifecycle transitions. The first activity 743 pauses and stops (though, it won't stop if it's still visible in the background), while the other 744 activity is created. In case these activities share data saved to disc or elsewhere, it's important 745 to understand that the first activity is not completely stopped before the second one is created. 746 Rather, the process of starting the second one overlaps with the process of stopping the first 747 one.</p> 748 749 <p>The order of lifecycle callbacks is well defined, particularly when the two activities are in the 750 same process and one is starting the other. Here's the order of operations that occur when Activity 751 A starts Acivity B: </p> 752 753 <ol> 754 <li>Activity A's {@link android.app.Activity#onPause onPause()} method executes.</li> 755 756 <li>Activity B's {@link android.app.Activity#onCreate onCreate()}, {@link 757 android.app.Activity#onStart onStart()}, and {@link android.app.Activity#onResume onResume()} 758 methods execute in sequence. (Activity B now has user focus.)</li> 759 760 <li>Then, if Activity A is no longer visible on screen, its {@link 761 android.app.Activity#onStop onStop()} method executes.</li> 762 </ol> 763 764 <p>This predictable sequence of lifecycle callbacks allows you to manage the transition of 765 information from one activity to another. For example, if you must write to a database when the 766 first activity stops so that the following activity can read it, then you should write to the 767 database during {@link android.app.Activity#onPause onPause()} instead of during {@link 768 android.app.Activity#onStop onStop()}.</p> 769 770 <!-- 771 <h2>Beginner's Path</h2> 772 773 <p>For more information about how Android maintains a history of activities and 774 enables user multitasking, continue with the <b><a 775 href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back 776 Stack</a></b> document.</p> 777 --> 778