Dialogs

 

A dialog is a small window that prompts the user to make a decision or enter additional information. A dialog does not fill the screen and is normally used for modal events that require users to take an action before they can proceed.

The Dialog class is the base class for dialogs, but you should avoid instantiating Dialog directly. Instead, use one of the following subclasses:

AlertDialog
A dialog that can show a title, up to three buttons, a list of selectable items, or a custom layout.
DatePickerDialog or TimePickerDialog

A dialog with a pre-defined UI that allows the user to select a date or time.

These classes define the style and structure for your dialog, but you should use a DialogFragment as a container for your dialog. The DialogFragment class provides all the controls you need to create your dialog and manage its appearance, instead of calling methods on the Dialog object.

Using DialogFragment to manage the dialog ensures that it correctly handles lifecycle events such as when the user presses the Back button or rotates the screen. The DialogFragment class also allows you to reuse the dialog’s UI as an embeddable component in a larger UI, just like a traditional Fragment (such as when you want the dialog UI to appear differently on large and small screens).

The following sections in this guide describe how to use a DialogFragment in combination with an AlertDialog object. If you’d like to create a date or time picker, you should instead read the Pickers guide.

 

Creating a Dialog Fragment

 

You can accomplish a wide variety of dialog designs—including custom layouts and those described in the Dialogs design guide—by extending DialogFragment and creating a AlertDialog in the onCreateDialog() callback method.

For example, here’s a basic AlertDialog that’s managed within a DialogFragment:

 code for java :

public class FireMissilesDialogFragment extends DialogFragment {
   
@Override
   
public Dialog onCreateDialog(Bundle savedInstanceState) {
       
// Use the Builder class for convenient dialog construction
       
AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
        builder
.setMessage(R.string.dialog_fire_missiles)
               
.setPositiveButton(R.string.fire, new DialogInterface.OnClickListener() {
                   
public void onClick(DialogInterface dialog, int id) {
                       
// FIRE ZE MISSILES!
                   
}
               
})
               
.setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() {
                   
public void onClick(DialogInterface dialog, int id) {
                       
// User cancelled the dialog
                   
}
               
});
       
// Create the AlertDialog object and return it
       
return builder.create();
   
}
}

 

 

Now, when you create an instance of this class and call show() on that object, the dialog appears as shown in figure 1.

The next section describes more about using the AlertDialog.Builder APIs to create the dialog.

Depending on how complex your dialog is, you can implement a variety of other callback methods in the DialogFragment, including all the basic fragment lifecycle methods.

Building an Alert Dialog

 

The AlertDialog class allows you to build a variety of dialog designs and is often the only dialog class you’ll need. As shown in figure 2, there are three regions of an alert dialog:

  1. Title

    This is optional and should be used only when the content area is occupied by a detailed message, a list, or custom layout. If you need to state a simple message or question (such as the dialog in figure 1), you don’t need a title.

  2. Content area

    This can display a message, a list, or other custom layout.

  3. Action buttons

    There should be no more than three action buttons in a dialog.

 

 

The AlertDialog.Builder class provides APIs that allow you to create an AlertDialog with these kinds of content, including a custom layout.

To build an AlertDialog:

// 1. Instantiate an <code><a href="/reference/android/app/AlertDialog.Builder.html">AlertDialog.Builder</a></code> with its constructor
AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());

 

// 2. Chain together various setter methods to set the dialog characteristics
builder
.setMessage(R.string.dialog_message)
       
.setTitle(R.string.dialog_title);

// 3. Get the <code><a href=”/reference/android/app/AlertDialog.html”>AlertDialog</a></code> from <code><a href=”/reference/android/app/AlertDialog.Builder.html#create()”>create()</a></code>
AlertDialog dialog = builder.create();

Adding buttons

 

To add action buttons like those in figure 2, call the setPositiveButton() and setNegativeButton() methods:

AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
// Add the buttons
builder
.setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() {
           
public void onClick(DialogInterface dialog, int id) {
               
// User clicked OK button
           
}
       
});
builder
.setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() {
           
public void onClick(DialogInterface dialog, int id) {
               
// User cancelled the dialog
           
}
       
});
// Set other dialog properties
...

 

// Create the AlertDialog
AlertDialog dialog = builder.create();

 

 

The set...Button() methods require a title for the button (supplied by a string resource) and a DialogInterface.OnClickListener that defines the action to take when the user presses the button.

There are three different action buttons you can add:

Positive
You should use this to accept and continue with the action (the “OK” action).
Negative
You should use this to cancel the action.
Neutral
You should use this when the user may not want to proceed with the action, but doesn’t necessarily want to cancel. It appears between the positive and negative buttons. For example, the action might be “Remind me later.”

You can add only one of each button type to an AlertDialog. That is, you cannot have more than one “positive” button.

 

 

 

Adding a list

 

There are three kinds of lists available with the AlertDialog APIs:

  • A traditional single-choice list
  • A persistent single-choice list (radio buttons)
  • A persistent multiple-choice list (checkboxes)

To create a single-choice list like the one in figure 3, use the setItems() method:

 

 

@Override
public Dialog onCreateDialog(Bundle savedInstanceState) {
   
AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
    builder
.setTitle(R.string.pick_color)
           
.setItems(R.array.colors_array, new DialogInterface.OnClickListener() {
               
public void onClick(DialogInterface dialog, int which) {
               
// The 'which' argument contains the index position
               
// of the selected item
           
}
   
});
   
return builder.create();
}

 

Because the list appears in the dialog’s content area, the dialog cannot show both a message and a list and you should set a title for the dialog with setTitle(). To specify the items for the list, call setItems(), passing an array. Alternatively, you can specify a list using setAdapter(). This allows you to back the list with dynamic data (such as from a database) using a ListAdapter.

If you choose to back your list with a ListAdapter, always use a Loader so that the content loads asynchronously. This is described further in Building Layouts with an Adapter and the Loaders guide.