1 page.title=Dialogs 2 @jd:body 3 4 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#DialogFragment">Creating a Dialog Fragment</a></li> 11 <li><a href="#AlertDialog">Building an Alert Dialog</a> 12 <ol> 13 <li><a href="#AddingButtons">Adding buttons</a></li> 14 <li><a href="#AddingAList">Adding a list</a></li> 15 <li><a href="#CustomLayout">Creating a Custom Layout</a></li> 16 </ol> 17 </li> 18 <li><a href="#PassingEvents">Passing Events Back to the Dialog's Host</a></li> 19 <li><a href="#ShowingADialog">Showing a Dialog</a></li> 20 <li><a href="#FullscreenDialog">Showing a Dialog Fullscreen or as an Embedded Fragment</a> 21 <ol> 22 <li><a href="#ActivityAsDialog">Showing an activity as a dialog on large screens</a></li> 23 </ol> 24 </li> 25 <li><a href="#DismissingADialog">Dismissing a Dialog</a></li> 26 </ol> 27 28 <h2>Key classes</h2> 29 <ol> 30 <li>{@link android.app.DialogFragment}</li> 31 <li>{@link android.app.AlertDialog}</li> 32 </ol> 33 34 <h2>See also</h2> 35 <ol> 36 <li><a href="{@docRoot}design/building-blocks/dialogs.html">Dialogs design guide</a></li> 37 <li><a href="{@docRoot}guide/topics/ui/controls/pickers.html">Pickers</a> (Date/Time dialogs)</li> 38 </ol> 39 </div> 40 </div> 41 42 <p>A dialog is a small window that prompts the user to 43 make a decision or enter additional information. A dialog does not fill the screen and is 44 normally used for modal events that require users to take an action before they can proceed.</p> 45 46 <div class="note design"> 47 <p><strong>Dialog Design</strong></p> 48 <p>For information about how to design your dialogs, including recommendations 49 for language, read the <a 50 href="{@docRoot}design/building-blocks/dialogs.html">Dialogs</a> design guide.</p> 51 </div> 52 53 <img src="{@docRoot}images/ui/dialogs.png" /> 54 55 <p>The {@link android.app.Dialog} class is the base class for dialogs, but you 56 should avoid instantiating {@link android.app.Dialog} directly. 57 Instead, use one of the following subclasses:</p> 58 <dl> 59 <dt>{@link android.app.AlertDialog}</dt> 60 <dd>A dialog that can show a title, up to three buttons, a list of 61 selectable items, or a custom layout.</dd> 62 <dt>{@link android.app.DatePickerDialog} or {@link android.app.TimePickerDialog}</dt> 63 <dd>A dialog with a pre-defined UI that allows the user to select a date or time.</dd> 64 </dl> 65 66 <div class="sidebox"> 67 <h2>Avoid ProgressDialog</h2> 68 <p>Android includes another dialog class called 69 {@link android.app.ProgressDialog} that shows a dialog with a progress bar. However, if you 70 need to indicate loading or indeterminate progress, you should instead follow the design 71 guidelines for <a href="{@docRoot}design/building-blocks/progress.html">Progress & 72 Activity</a> and use a {@link android.widget.ProgressBar} in your layout.</p> 73 </div> 74 75 <p>These classes define the style and structure for your dialog, but you should 76 use a {@link android.support.v4.app.DialogFragment} as a container for your dialog. 77 The {@link android.support.v4.app.DialogFragment} class provides all the controls you 78 need to create your dialog and manage its appearance, instead of calling methods 79 on the {@link android.app.Dialog} object.</p> 80 81 <p>Using {@link android.support.v4.app.DialogFragment} to manage the dialog 82 ensures that it correctly handles lifecycle events 83 such as when the user presses the <em>Back</em> button or rotates the screen. The {@link 84 android.support.v4.app.DialogFragment} class also allows you to reuse the dialog's UI as an 85 embeddable component in a larger UI, just like a traditional {@link 86 android.support.v4.app.Fragment} (such as when you want the dialog UI to appear differently 87 on large and small screens).</p> 88 89 <p>The following sections in this guide describe how to use a {@link 90 android.support.v4.app.DialogFragment} in combination with an {@link android.app.AlertDialog} 91 object. If you'd like to create a date or time picker, you should instead read the 92 <a href="{@docRoot}guide/topics/ui/controls/pickers.html">Pickers</a> guide.</p> 93 94 <p class="note"><strong>Note:</strong> 95 Because the {@link android.app.DialogFragment} class was originally added with 96 Android 3.0 (API level 11), this document describes how to use the {@link 97 android.support.v4.app.DialogFragment} class that's provided with the <a 98 href="{@docRoot}tools/extras/support-library.html">Support Library</a>. By adding this library 99 to your app, you can use {@link android.support.v4.app.DialogFragment} and a variety of other 100 APIs on devices running Android 1.6 or higher. If the minimum version your app supports 101 is API level 11 or higher, then you can use the framework version of {@link 102 android.app.DialogFragment}, but be aware that the links in this document are for the support 103 library APIs. When using the support library, 104 be sure that you import <code>android.support.v4.app.DialogFragment</code> 105 class and <em>not</em> <code>android.app.DialogFragment</code>.</p> 106 107 108 <h2 id="DialogFragment">Creating a Dialog Fragment</h2> 109 110 <p>You can accomplish a wide variety of dialog designs—including 111 custom layouts and those described in the <a 112 href="{@docRoot}design/building-blocks/dialogs.html">Dialogs</a> 113 design guide—by extending 114 {@link android.support.v4.app.DialogFragment} and creating a {@link android.app.AlertDialog} 115 in the {@link android.support.v4.app.DialogFragment#onCreateDialog 116 onCreateDialog()} callback method.</p> 117 118 <p>For example, here's a basic {@link android.app.AlertDialog} that's managed within 119 a {@link android.support.v4.app.DialogFragment}:</p> 120 121 <pre> 122 public class FireMissilesDialogFragment extends DialogFragment { 123 @Override 124 public Dialog onCreateDialog(Bundle savedInstanceState) { 125 // Use the Builder class for convenient dialog construction 126 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 127 builder.setMessage(R.string.dialog_fire_missiles) 128 .setPositiveButton(R.string.fire, new DialogInterface.OnClickListener() { 129 public void onClick(DialogInterface dialog, int id) { 130 // FIRE ZE MISSILES! 131 } 132 }) 133 .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { 134 public void onClick(DialogInterface dialog, int id) { 135 // User cancelled the dialog 136 } 137 }); 138 // Create the AlertDialog object and return it 139 return builder.create(); 140 } 141 } 142 </pre> 143 144 <div class="figure" style="width:290px;margin:0 0 0 20px"> 145 <img src="{@docRoot}images/ui/dialog_buttons.png" alt="" /> 146 <p class="img-caption"><strong>Figure 1.</strong> 147 A dialog with a message and two action buttons.</p> 148 </div> 149 150 <p>Now, when you create an instance of this class and call {@link 151 android.support.v4.app.DialogFragment#show show()} on that object, the dialog appears as 152 shown in figure 1.</p> 153 154 <p>The next section describes more about using the {@link android.app.AlertDialog.Builder} 155 APIs to create the dialog.</p> 156 157 <p>Depending on how complex your dialog is, you can implement a variety of other callback 158 methods in the {@link android.support.v4.app.DialogFragment}, including all the basic 159 <a href="{@docRoot}guide/components/fragments.html#Lifecycle">fragment lifecycle methods</a>. 160 161 162 163 164 165 <h2 id="AlertDialog">Building an Alert Dialog</h2> 166 167 168 <p>The {@link android.app.AlertDialog} class allows you to build a variety of dialog designs and 169 is often the only dialog class you'll need. 170 As shown in figure 2, there are three regions of an alert dialog:</p> 171 172 <div class="figure" style="width:311px;margin-top:0"> 173 <img src="{@docRoot}images/ui/dialogs_regions.png" alt="" style="margin-bottom:0"/> 174 <p class="img-caption"><strong>Figure 2.</strong> The layout of a dialog.</p> 175 </div> 176 177 <ol> 178 <li><b>Title</b> 179 <p>This is optional and should be used only when the content area 180 is occupied by a detailed message, a list, or custom layout. If you need to state 181 a simple message or question (such as the dialog in figure 1), you don't need a title.</li> 182 <li><b>Content area</b> 183 <p>This can display a message, a list, or other custom layout.</p></li> 184 <li><b>Action buttons</b> 185 <p>There should be no more than three action buttons in a dialog.</p></li> 186 </ol> 187 188 <p>The {@link android.app.AlertDialog.Builder} 189 class provides APIs that allow you to create an {@link android.app.AlertDialog} 190 with these kinds of content, including a custom layout.</p> 191 192 <p>To build an {@link android.app.AlertDialog}:</p> 193 194 <pre> 195 <b>// 1. Instantiate an {@link android.app.AlertDialog.Builder} with its constructor</b> 196 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 197 198 <b>// 2. Chain together various setter methods to set the dialog characteristics</b> 199 builder.setMessage(R.string.dialog_message) 200 .setTitle(R.string.dialog_title); 201 202 <b>// 3. Get the {@link android.app.AlertDialog} from {@link android.app.AlertDialog.Builder#create()}</b> 203 AlertDialog dialog = builder.create(); 204 </pre> 205 206 <p>The following topics show how to define various dialog attributes using the 207 {@link android.app.AlertDialog.Builder} class.</p> 208 209 210 211 212 <h3 id="AddingButtons">Adding buttons</h3> 213 214 <p>To add action buttons like those in figure 2, 215 call the {@link android.app.AlertDialog.Builder#setPositiveButton setPositiveButton()} and 216 {@link android.app.AlertDialog.Builder#setNegativeButton setNegativeButton()} methods:</p> 217 218 <pre style="clear:right"> 219 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 220 // Add the buttons 221 builder.setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() { 222 public void onClick(DialogInterface dialog, int id) { 223 // User clicked OK button 224 } 225 }); 226 builder.setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { 227 public void onClick(DialogInterface dialog, int id) { 228 // User cancelled the dialog 229 } 230 }); 231 // Set other dialog properties 232 ... 233 234 // Create the AlertDialog 235 AlertDialog dialog = builder.create(); 236 </pre> 237 238 <p>The <code>set...Button()</code> methods require a title for the button (supplied 239 by a <a href="{@docRoot}guide/topics/resources/string-resource.html">string resource</a>) and a 240 {@link android.content.DialogInterface.OnClickListener} that defines the action to take 241 when the user presses the button.</p> 242 243 <p>There are three different action buttons you can add:</p> 244 <dl> 245 <dt>Positive</dt> 246 <dd>You should use this to accept and continue with the action (the "OK" action).</dd> 247 <dt>Negative</dt> 248 <dd>You should use this to cancel the action.</dd> 249 <dt>Neutral</dt> 250 <dd>You should use this when the user may not want to proceed with the action, 251 but doesn't necessarily want to cancel. It appears between the positive and negative 252 buttons. For example, the action might be "Remind me later."</dd> 253 </dl> 254 255 <p>You can add only one of each button type to an {@link 256 android.app.AlertDialog}. That is, you cannot have more than one "positive" button.</p> 257 258 259 260 <div class="figure" style="width:290px;margin:0 0 0 40px"> 261 <img src="{@docRoot}images/ui/dialog_list.png" alt="" /> 262 <p class="img-caption"><strong>Figure 3.</strong> 263 A dialog with a title and list.</p> 264 </div> 265 266 <h3 id="AddingAList">Adding a list</h3> 267 268 <p>There are three kinds of lists available with the {@link android.app.AlertDialog} APIs:</p> 269 <ul> 270 <li>A traditional single-choice list</li> 271 <li>A persistent single-choice list (radio buttons)</li> 272 <li>A persistent multiple-choice list (checkboxes)</li> 273 </ul> 274 275 <p>To create a single-choice list like the one in figure 3, 276 use the {@link android.app.AlertDialog.Builder#setItems setItems()} method:</p> 277 278 <pre style="clear:right"> 279 @Override 280 public Dialog onCreateDialog(Bundle savedInstanceState) { 281 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 282 builder.setTitle(R.string.pick_color); 283 .setItems(R.array.colors_array, new DialogInterface.OnClickListener() { 284 public void onClick(DialogInterface dialog, int which) { 285 // The 'which' argument contains the index position 286 // of the selected item 287 } 288 }); 289 return builder.create(); 290 } 291 </pre> 292 293 <p>Because the list appears in the dialog's content area, 294 the dialog cannot show both a message and a list and you should set a title for the 295 dialog with {@link android.app.AlertDialog.Builder#setTitle setTitle()}. 296 To specify the items for the list, call {@link 297 android.app.AlertDialog.Builder#setItems setItems()}, passing an array. 298 Alternatively, you can specify a list using {@link 299 android.app.AlertDialog.Builder#setAdapter setAdapter()}. This allows you to back the list 300 with dynamic data (such as from a database) using a {@link android.widget.ListAdapter}.</p> 301 302 <p>If you choose to back your list with a {@link android.widget.ListAdapter}, 303 always use a {@link android.support.v4.content.Loader} so that the content loads 304 asynchronously. This is described further in 305 <a href="{@docRoot}guide/topics/ui/declaring-layout.html#AdapterViews">Building Layouts 306 with an Adapter</a> and the <a href="{@docRoot}guide/components/loaders.html">Loaders</a> 307 guide.</p> 308 309 <p class="note"><strong>Note:</strong> By default, touching a list item dismisses the dialog, 310 unless you're using one of the following persistent choice lists.</p> 311 312 <div class="figure" style="width:290px;margin:-30px 0 0 40px"> 313 <img src="{@docRoot}images/ui/dialog_checkboxes.png" /> 314 <p class="img-caption"><strong>Figure 4.</strong> 315 A list of multiple-choice items.</p> 316 </div> 317 318 319 <h4 id="Checkboxes">Adding a persistent multiple-choice or single-choice list</h4> 320 321 <p>To add a list of multiple-choice items (checkboxes) or 322 single-choice items (radio buttons), use the 323 {@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String, 324 DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} or 325 {@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) 326 setSingleChoiceItems()} methods, respectively.</p> 327 328 <p>For example, here's how you can create a multiple-choice list like the 329 one shown in figure 4 that saves the selected 330 items in an {@link java.util.ArrayList}:</p> 331 332 <pre style="clear:right"> 333 @Override 334 public Dialog onCreateDialog(Bundle savedInstanceState) { 335 mSelectedItems = new ArrayList(); // Where we track the selected items 336 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 337 // Set the dialog title 338 builder.setTitle(R.string.pick_toppings) 339 // Specify the list array, the items to be selected by default (null for none), 340 // and the listener through which to receive callbacks when items are selected 341 .setMultiChoiceItems(R.array.toppings, null, 342 new DialogInterface.OnMultiChoiceClickListener() { 343 @Override 344 public void onClick(DialogInterface dialog, int which, 345 boolean isChecked) { 346 if (isChecked) { 347 // If the user checked the item, add it to the selected items 348 mSelectedItems.add(which); 349 } else if (mSelectedItems.contains(which)) { 350 // Else, if the item is already in the array, remove it 351 mSelectedItems.remove(Integer.valueOf(which)); 352 } 353 } 354 }) 355 // Set the action buttons 356 .setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() { 357 @Override 358 public void onClick(DialogInterface dialog, int id) { 359 // User clicked OK, so save the mSelectedItems results somewhere 360 // or return them to the component that opened the dialog 361 ... 362 } 363 }) 364 .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { 365 @Override 366 public void onClick(DialogInterface dialog, int id) { 367 ... 368 } 369 }); 370 371 return builder.create(); 372 } 373 </pre> 374 375 <p>Although both a traditional list and a list with radio buttons 376 provide a "single choice" action, you should use {@link 377 android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) 378 setSingleChoiceItems()} if you want to persist the user's choice. 379 That is, if opening the dialog again later should indicate what the user's current choice is, 380 then you create a list with radio buttons.</p> 381 382 383 384 385 386 <h3 id="CustomLayout">Creating a Custom Layout</h3> 387 388 <div class="figure" style="width:290px;margin:-30px 0 0 40px"> 389 <img src="{@docRoot}images/ui/dialog_custom.png" alt="" /> 390 <p class="img-caption"><strong>Figure 5.</strong> A custom dialog layout.</p> 391 </div> 392 393 <p>If you want a custom layout in a dialog, create a layout and add it to an 394 {@link android.app.AlertDialog} by calling {@link 395 android.app.AlertDialog.Builder#setView setView()} on your {@link 396 android.app.AlertDialog.Builder} object.</p> 397 398 <p>By default, the custom layout fills the dialog window, but you can still 399 use {@link android.app.AlertDialog.Builder} methods to add buttons and a title.</p> 400 401 <p>For example, here's the layout file for the dialog in Figure 5:</p> 402 403 <p style="clear:right" class="code-caption">res/layout/dialog_signin.xml</p> 404 <pre> 405 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 406 android:orientation="vertical" 407 android:layout_width="wrap_content" 408 android:layout_height="wrap_content"> 409 <ImageView 410 android:src="@drawable/header_logo" 411 android:layout_width="match_parent" 412 android:layout_height="64dp" 413 android:scaleType="center" 414 android:background="#FFFFBB33" 415 android:contentDescription="@string/app_name" /> 416 <EditText 417 android:id="@+id/username" 418 android:inputType="textEmailAddress" 419 android:layout_width="match_parent" 420 android:layout_height="wrap_content" 421 android:layout_marginTop="16dp" 422 android:layout_marginLeft="4dp" 423 android:layout_marginRight="4dp" 424 android:layout_marginBottom="4dp" 425 android:hint="@string/username" /> 426 <EditText 427 android:id="@+id/password" 428 android:inputType="textPassword" 429 android:layout_width="match_parent" 430 android:layout_height="wrap_content" 431 android:layout_marginTop="4dp" 432 android:layout_marginLeft="4dp" 433 android:layout_marginRight="4dp" 434 android:layout_marginBottom="16dp" 435 android:fontFamily="sans-serif" 436 android:hint="@string/password"/> 437 </LinearLayout> 438 </pre> 439 440 <p class="note"><strong>Tip:</strong> By default, when you set an {@link android.widget.EditText} 441 element to use the {@code "textPassword"} input type, the font family is set to monospace, so 442 you should change its font family to {@code "sans-serif"} so that both text fields use 443 a matching font style.</p> 444 445 <p>To inflate the layout in your {@link android.support.v4.app.DialogFragment}, 446 get a {@link android.view.LayoutInflater} with 447 {@link android.app.Activity#getLayoutInflater()} and call 448 {@link android.view.LayoutInflater#inflate inflate()}, where the first parameter 449 is the layout resource ID and the second parameter is a parent view for the layout. 450 You can then call {@link android.app.AlertDialog#setView setView()} 451 to place the layout in the dialog.</p> 452 453 <pre> 454 @Override 455 public Dialog onCreateDialog(Bundle savedInstanceState) { 456 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 457 // Get the layout inflater 458 LayoutInflater inflater = getActivity().getLayoutInflater(); 459 460 // Inflate and set the layout for the dialog 461 // Pass null as the parent view because its going in the dialog layout 462 builder.setView(inflater.inflate(R.layout.dialog_signin, null)) 463 // Add action buttons 464 .setPositiveButton(R.string.signin, new DialogInterface.OnClickListener() { 465 @Override 466 public void onClick(DialogInterface dialog, int id) { 467 // sign in the user ... 468 } 469 }) 470 .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { 471 public void onClick(DialogInterface dialog, int id) { 472 LoginDialogFragment.this.getDialog().cancel(); 473 } 474 }); 475 return builder.create(); 476 } 477 </pre> 478 479 <div class="note"> 480 <p><strong>Tip:</strong> If you want a custom dialog, 481 you can instead display an {@link android.app.Activity} as a dialog 482 instead of using the {@link android.app.Dialog} APIs. Simply create an activity and set its theme to 483 {@link android.R.style#Theme_Holo_Dialog Theme.Holo.Dialog} 484 in the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 485 <activity>}</a> manifest element:</p> 486 487 <pre> 488 <activity android:theme="@android:style/Theme.Holo.Dialog" > 489 </pre> 490 <p>That's it. The activity now displays in a dialog window instead of fullscreen.</p> 491 </div> 492 493 494 495 <h2 id="PassingEvents">Passing Events Back to the Dialog's Host</h2> 496 497 <p>When the user touches one of the dialog's action buttons or selects an item from its list, 498 your {@link android.support.v4.app.DialogFragment} might perform the necessary 499 action itself, but often you'll want to deliver the event to the activity or fragment that 500 opened the dialog. To do this, define an interface with a method for each type of click event. 501 Then implement that interface in the host component that will 502 receive the action events from the dialog.</p> 503 504 <p>For example, here's a {@link android.support.v4.app.DialogFragment} that defines an 505 interface through which it delivers the events back to the host activity:</p> 506 507 <pre> 508 public class NoticeDialogFragment extends DialogFragment { 509 510 /* The activity that creates an instance of this dialog fragment must 511 * implement this interface in order to receive event callbacks. 512 * Each method passes the DialogFragment in case the host needs to query it. */ 513 public interface NoticeDialogListener { 514 public void onDialogPositiveClick(DialogFragment dialog); 515 public void onDialogNegativeClick(DialogFragment dialog); 516 } 517 518 // Use this instance of the interface to deliver action events 519 NoticeDialogListener mListener; 520 521 // Override the Fragment.onAttach() method to instantiate the NoticeDialogListener 522 @Override 523 public void onAttach(Activity activity) { 524 super.onAttach(activity); 525 // Verify that the host activity implements the callback interface 526 try { 527 // Instantiate the NoticeDialogListener so we can send events to the host 528 mListener = (NoticeDialogListener) activity; 529 } catch (ClassCastException e) { 530 // The activity doesn't implement the interface, throw exception 531 throw new ClassCastException(activity.toString() 532 + " must implement NoticeDialogListener"); 533 } 534 } 535 ... 536 } 537 </pre> 538 539 <p>The activity hosting the dialog creates an instance of the dialog 540 with the dialog fragment's constructor and receives the dialog's 541 events through an implementation of the {@code NoticeDialogListener} interface:</p> 542 543 <pre> 544 public class MainActivity extends FragmentActivity 545 implements NoticeDialogFragment.NoticeDialogListener{ 546 ... 547 548 public void showNoticeDialog() { 549 // Create an instance of the dialog fragment and show it 550 DialogFragment dialog = new NoticeDialogFragment(); 551 dialog.show(getSupportFragmentManager(), "NoticeDialogFragment"); 552 } 553 554 // The dialog fragment receives a reference to this Activity through the 555 // Fragment.onAttach() callback, which it uses to call the following methods 556 // defined by the NoticeDialogFragment.NoticeDialogListener interface 557 @Override 558 public void onDialogPositiveClick(DialogFragment dialog) { 559 // User touched the dialog's positive button 560 ... 561 } 562 563 @Override 564 public void onDialogNegativeClick(DialogFragment dialog) { 565 // User touched the dialog's negative button 566 ... 567 } 568 } 569 </pre> 570 571 <p>Because the host activity implements the {@code NoticeDialogListener}—which is 572 enforced by the {@link android.support.v4.app.Fragment#onAttach onAttach()} 573 callback method shown above—the dialog fragment can use the 574 interface callback methods to deliver click events to the activity:</p> 575 576 <pre> 577 public class NoticeDialogFragment extends DialogFragment { 578 ... 579 580 @Override 581 public Dialog onCreateDialog(Bundle savedInstanceState) { 582 // Build the dialog and set up the button click handlers 583 AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); 584 builder.setMessage(R.string.dialog_fire_missiles) 585 .setPositiveButton(R.string.fire, new DialogInterface.OnClickListener() { 586 public void onClick(DialogInterface dialog, int id) { 587 // Send the positive button event back to the host activity 588 mListener.onDialogPositiveClick(NoticeDialogFragment.this); 589 } 590 }) 591 .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { 592 public void onClick(DialogInterface dialog, int id) { 593 // Send the negative button event back to the host activity 594 mListener.onDialogPositiveClick(NoticeDialogFragment.this); 595 } 596 }); 597 return builder.create(); 598 } 599 } 600 </pre> 601 602 603 604 <h2 id="ShowingADialog">Showing a Dialog</h2> 605 606 <p>When you want to show your dialog, create an instance of your {@link 607 android.support.v4.app.DialogFragment} and call {@link android.support.v4.app.DialogFragment#show 608 show()}, passing the {@link android.support.v4.app.FragmentManager} and a tag name 609 for the dialog fragment.</p> 610 611 <p>You can get the {@link android.support.v4.app.FragmentManager} by calling 612 {@link android.support.v4.app.FragmentActivity#getSupportFragmentManager()} from 613 the {@link android.support.v4.app.FragmentActivity} or {@link 614 android.support.v4.app.Fragment#getFragmentManager()} from a {@link 615 android.support.v4.app.Fragment}. For example:</p> 616 617 <pre> 618 public void confirmFireMissiles() { 619 DialogFragment newFragment = new FireMissilesDialogFragment(); 620 newFragment.show(getSupportFragmentManager(), "missiles"); 621 } 622 </pre> 623 624 <p>The second argument, {@code "missiles"}, is a unique tag name that the system uses to save 625 and restore the fragment state when necessary. The tag also allows you to get a handle to 626 the fragment by calling {@link android.support.v4.app.FragmentManager#findFragmentByTag 627 findFragmentByTag()}.</p> 628 629 630 631 632 <h2 id="FullscreenDialog">Showing a Dialog Fullscreen or as an Embedded Fragment</h2> 633 634 <p>You might have a UI design in which you want a piece of the UI to appear as a dialog in some 635 situations, but as a full screen or embedded fragment in others (perhaps depending on whether 636 the device is a large screen or small screen). The {@link android.support.v4.app.DialogFragment} 637 class offers you this flexibility because it can still behave as an embeddable {@link 638 android.support.v4.app.Fragment}.</p> 639 640 <p>However, you cannot use {@link android.app.AlertDialog.Builder AlertDialog.Builder} 641 or other {@link android.app.Dialog} objects to build the dialog in this case. If 642 you want the {@link android.support.v4.app.DialogFragment} to be 643 embeddable, you must define the dialog's UI in a layout, then load the layout in the 644 {@link android.support.v4.app.DialogFragment#onCreateView 645 onCreateView()} callback.</p> 646 647 <p>Here's an example {@link android.support.v4.app.DialogFragment} that can appear as either a 648 dialog or an embeddable fragment (using a layout named <code>purchase_items.xml</code>):</p> 649 650 <pre> 651 public class CustomDialogFragment extends DialogFragment { 652 /** The system calls this to get the DialogFragment's layout, regardless 653 of whether it's being displayed as a dialog or an embedded fragment. */ 654 @Override 655 public View onCreateView(LayoutInflater inflater, ViewGroup container, 656 Bundle savedInstanceState) { 657 // Inflate the layout to use as dialog or embedded fragment 658 return inflater.inflate(R.layout.purchase_items, container, false); 659 } 660 661 /** The system calls this only when creating the layout in a dialog. */ 662 @Override 663 public Dialog onCreateDialog(Bundle savedInstanceState) { 664 // The only reason you might override this method when using onCreateView() is 665 // to modify any dialog characteristics. For example, the dialog includes a 666 // title by default, but your custom layout might not need it. So here you can 667 // remove the dialog title, but you must call the superclass to get the Dialog. 668 Dialog dialog = super.onCreateDialog(savedInstanceState); 669 dialog.requestWindowFeature(Window.FEATURE_NO_TITLE); 670 return dialog; 671 } 672 } 673 </pre> 674 675 <p>And here's some code that decides whether to show the fragment as a dialog 676 or a fullscreen UI, based on the screen size:</p> 677 678 <pre> 679 public void showDialog() { 680 FragmentManager fragmentManager = getSupportFragmentManager(); 681 CustomDialogFragment newFragment = new CustomDialogFragment(); 682 683 if (mIsLargeLayout) { 684 // The device is using a large layout, so show the fragment as a dialog 685 newFragment.show(fragmentManager, "dialog"); 686 } else { 687 // The device is smaller, so show the fragment fullscreen 688 FragmentTransaction transaction = fragmentManager.beginTransaction(); 689 // For a little polish, specify a transition animation 690 transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN); 691 // To make it fullscreen, use the 'content' root view as the container 692 // for the fragment, which is always the root view for the activity 693 transaction.add(android.R.id.content, newFragment) 694 .addToBackStack(null).commit(); 695 } 696 } 697 </pre> 698 699 <p>For more information about performing fragment transactions, see the 700 <a href="{@docRoot}guide/components/fragments.html">Fragments</a> guide.</p> 701 702 <p>In this example, the <code>mIsLargeLayout</code> boolean specifies whether the current device 703 should use the app's large layout design (and thus show this fragment as a dialog, rather 704 than fullscreen). The best way to set this kind of boolean is to declare a 705 <a href="{@docRoot}guide/topics/resources/more-resources.html#Bool">bool resource value</a> 706 with an <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources" 707 >alternative resource</a> value for different screen sizes. For example, here are two 708 versions of the bool resource for different screen sizes:</p> 709 710 <p class="code-caption">res/values/bools.xml</p> 711 <pre> 712 <!-- Default boolean values --> 713 <resources> 714 <bool name="large_layout">false</bool> 715 </resources> 716 </pre> 717 718 <p class="code-caption">res/values-large/bools.xml</p> 719 <pre> 720 <!-- Large screen boolean values --> 721 <resources> 722 <bool name="large_layout">true</bool> 723 </resources> 724 </pre> 725 726 <p>Then you can initialize the {@code mIsLargeLayout} value during the activity's 727 {@link android.app.Activity#onCreate onCreate()} method:</p> 728 729 <pre> 730 boolean mIsLargeLayout; 731 732 @Override 733 public void onCreate(Bundle savedInstanceState) { 734 super.onCreate(savedInstanceState); 735 setContentView(R.layout.activity_main); 736 737 mIsLargeLayout = getResources().getBoolean(R.bool.large_layout); 738 } 739 </pre> 740 741 742 743 <h3 id="ActivityAsDialog">Showing an activity as a dialog on large screens</h3> 744 745 <p>Instead of showing a dialog as a fullscreen UI when on small screens, you can accomplish 746 the same result by showing an {@link android.app.Activity} as a dialog when on 747 large screens. Which approach you choose depends on your app design, but 748 showing an activity as a dialog is often useful when your app is already designed for small 749 screens and you'd like to improve the experience on tablets by showing a short-lived activity 750 as a dialog.</p> 751 752 <p>To show an activity as a dialog only when on large screens, 753 apply the {@link android.R.style#Theme_Holo_DialogWhenLarge Theme.Holo.DialogWhenLarge} 754 theme to the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 755 <activity>}</a> manifest element:</p> 756 757 <pre> 758 <activity android:theme="@android:style/Theme.Holo.DialogWhenLarge" > 759 </pre> 760 761 <p>For more information about styling your activities with themes, see the <a 762 href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</p> 763 764 765 766 <h2 id="DismissingADialog">Dismissing a Dialog</h2> 767 768 <p>When the user touches any of the action buttons created with an 769 {@link android.app.AlertDialog.Builder}, the system dismisses the dialog for you.</p> 770 771 <p>The system also dismisses the dialog when the user touches an item in a dialog list, except 772 when the list uses radio buttons or checkboxes. Otherwise, you can manually dismiss your dialog 773 by calling {@link android.support.v4.app.DialogFragment#dismiss()} on your {@link 774 android.support.v4.app.DialogFragment}.</p> 775 776 <p>In case you need to perform certain 777 actions when the dialog goes away, you can implement the {@link 778 android.support.v4.app.DialogFragment#onDismiss onDismiss()} method in your {@link 779 android.support.v4.app.DialogFragment}.</p> 780 781 <p>You can also <em>cancel</em> a dialog. This is a special event that indicates the user 782 explicitly left the dialog without completing the task. This occurs if the user presses the 783 <em>Back</em> button, touches the screen outside the dialog area, 784 or if you explicitly call {@link android.app.Dialog#cancel()} on the {@link 785 android.app.Dialog} (such as in response to a "Cancel" button in the dialog).</p> 786 787 <p>As shown in the example above, you can respond to the cancel event by implementing 788 {@link android.support.v4.app.DialogFragment#onCancel onCancel()} in your {@link 789 android.support.v4.app.DialogFragment} class.</p> 790 791 <p class="note"><strong>Note:</strong> The system calls 792 {@link android.support.v4.app.DialogFragment#onDismiss onDismiss()} upon each event that 793 invokes the {@link android.support.v4.app.DialogFragment#onCancel onCancel()} callback. However, 794 if you call {@link android.app.Dialog#dismiss Dialog.dismiss()} or {@link 795 android.support.v4.app.DialogFragment#dismiss DialogFragment.dismiss()}, 796 the system calls {@link android.support.v4.app.DialogFragment#onDismiss onDismiss()} <em>but 797 not</em> {@link android.support.v4.app.DialogFragment#onCancel onCancel()}. So you should generally 798 call {@link android.support.v4.app.DialogFragment#dismiss dismiss()} when the user presses the 799 <em>positive</em> button in your dialog in order to remove the dialog from view.</p> 800 801 802