topics/ui/dialogs.jd

page.title=Caixas de dilogo
page.tags=dilogodealerta,fragmentodedilogo

@jd:body


<div id="qv-wrapper">
  <div id="qv">
    <h2>Neste documento</h2>
<ol>
  <li><a href="#DialogFragment">Criao de um fragmento de caixa de dilogo</a></li>
  <li><a href="#AlertDialog">Construo de uma caixa de dilogo de alerta</a>
    <ol>
      <li><a href="#AddingButtons">Adio de botes</a></li>
      <li><a href="#AddingAList">Adio de listas</a></li>
      <li><a href="#CustomLayout">Criao de layout personalizado</a></li>
    </ol>
  </li>
  <li><a href="#PassingEvents">Direcionamento de eventos de volta ao host da caixa de dilogo</a></li>
  <li><a href="#ShowingADialog">Exibio de uma caixa de dilogo</a></li>
  <li><a href="#FullscreenDialog">Exibio de uma caixa de dilogo em tela cheia ou como um fragmento incorporado</a>
    <ol>
      <li><a href="#ActivityAsDialog">Exibio de uma atividade como uma caixa de dilogo em telas grandes</a></li>
    </ol>
  </li>
  <li><a href="#DismissingADialog">Dispensa de uma caixa de dilogo</a></li>
</ol>

    <h2>Classes principais</h2>
    <ol>
      <li>{@link android.app.DialogFragment}</li>
      <li>{@link android.app.AlertDialog}</li>
    </ol>

    <h2>Veja tambm</h2>
    <ol>
      <li><a href="{@docRoot}design/building-blocks/dialogs.html">Guia de projeto de caixas de dilogo</a></li>
      <li><a href="{@docRoot}guide/topics/ui/controls/pickers.html">Seletores</a> (caixas de dilogo de data e hora)</li>
    </ol>
  </div>
</div>

<p>As caixas de dilogo so pequenas janelas que levam o usurio
a tomar uma deciso ou inserir informaes adicionais. Elas no ocupam toda a tela e so
normalmente susada para eventos modais que exijam que usurios realizem uma ao antes de continuar.</p>

<div class="note design">
<p><strong>Projeto de caixas de dilogo</strong></p>
  <p>Para obter mais informaes sobre como projetar caixas de dilogo, inclusive sobre recomendaes
  de idioma, leia o guia de projeto <a href="{@docRoot}design/building-blocks/dialogs.html">Caixas de dilogo</a>.</p>
</div>

<img src="{@docRoot}images/ui/dialogs.png" />

<p>A classe {@link android.app.Dialog}  a classe de base para caixas de dilogo, mas
deve-se evitar instanciar {@link android.app.Dialog} diretamente.
Em vez disso, use uma das subclasses a seguir:</p>
<dl>
  <dt>{@link android.app.AlertDialog}</dt>
  <dd>Caixa de dilogo que pode exibir um ttulo, at trs botes, uma lista
    de itens selecionveis ou um layout personalizado.</dd>
  <dt>{@link android.app.DatePickerDialog} ou {@link android.app.TimePickerDialog}</dt>
  <dd>Caixa de dilogo com uma IU predefinida que permite ao usurio selecionar uma data ou hora.</dd>
</dl>

<div class="sidebox">
<h2>Evite ProgressDialog</h2>
<p>O Android tem outra classe de caixa de dilogo chamada
{@link android.app.ProgressDialog}, que exibe uma caixa de dilogo com uma barra de andamento. Entretanto, se for
necessrio indicar carregamento ou andamento indeterminado, deve-se seguir as orientaes
de projeto de <a href="{@docRoot}design/building-blocks/progress.html">Progresso e
atividade</a> e usar uma {@link android.widget.ProgressBar} no layout.</p>
</div>

<p>Essas classes definem o estilo e a estrutura da caixa de dilogo, mas deve-se
usar um {@link android.support.v4.app.DialogFragment} como um continer para a caixa de dilogo.
A classe {@link android.support.v4.app.DialogFragment} fornece todos os controles
necessrios para criar uma caixa de dilogo e gerenciar sua aparncia em vez de chamar mtodos
no objeto {@link android.app.Dialog}.</p>

<p>O uso de {@link android.support.v4.app.DialogFragment} para gerenciar a caixa de dilogo
garante que ela trate corretamente os eventos de ciclos de vida,
como quando o usurio pressiona o boto <em>Voltar</em> ou gira a tela. A classe {@link
android.support.v4.app.DialogFragment} tambm permite a reutilizao da IU da caixa de dilogo como
um componente incorporvel em uma IU maior, assim como um {@link
android.support.v4.app.Fragment} tradicional (como nas vezes em que se deseja que a IU da caixa de dilogo aparea de modos diferentes
em telas grandes e pequenas).</p>

<p>As sees a seguir neste guia descrevem como usar um {@link
android.support.v4.app.DialogFragment} combinado com um objeto
{@link android.app.AlertDialog}. Se voc quiser criar um seletor de data ou hora, leia o guia
<a href="{@docRoot}guide/topics/ui/controls/pickers.html">Seletores</a>.</p>

<p class="note"><strong>Observao:</strong>
como a classe {@link android.app.DialogFragment} foi adicionada originalmente com
o Android 3.0 (API de nvel 11), este documento descreve como usar a classe {@link
android.support.v4.app.DialogFragment} fornecida com a <a href="{@docRoot}tools/support-library/index.html">Biblioteca de Suporte</a>. Ao adicionar essa biblioteca
ao aplicativo, pode-se usar {@link android.support.v4.app.DialogFragment} e uma variedade de outras
APIs em dispositivos que executam o Android 1.6 ou verso posterior. Se a verso mais antiga com a qual seu aplicativo  compatvel
for a API de nvel 11 ou posterior,  possvel usar a verso de estrutura de {@link
android.app.DialogFragment}, mas esteja ciente de que os links neste documento so para APIs
de biblioteca de suporte. Ao usar a biblioteca de suporte,
certifique-se de importar a classe <code>android.support.v4.app.DialogFragment</code>
e <em>no</em> a <code>android.app.DialogFragment</code>.</p>


<h2 id="DialogFragment">Criao de um fragmento de caixa de dilogo</h2>

<p> possvel realizar uma grande variedade de projetos de caixas de dilogo &mdash; inclusive
layouts personalizados e outros descritos no guia de projeto <a href="{@docRoot}design/building-blocks/dialogs.html">Caixas de dilogo</a>
 &mdash;, estendendo
{@link android.support.v4.app.DialogFragment} e criando uma{@link android.app.AlertDialog}
no mtodo de retorno de chamada {@link android.support.v4.app.DialogFragment#onCreateDialog
onCreateDialog()}.</p>

<p>Por exemplo, a seguir h um {@link android.app.AlertDialog} bsico gerenciado dentro
de um {@link android.support.v4.app.DialogFragment}:</p>

<pre>
public class FireMissilesDialogFragment extends DialogFragment {
    &#64;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();
    }
}
</pre>

<div class="figure" style="width:290px;margin:0 0 0 20px">
<img src="{@docRoot}images/ui/dialog_buttons.png" alt="" />
<p class="img-caption"><strong>Figura 1.</strong>
Caixa de dilogo com uma mensagem e dois botes de ao.</p>
</div>

<p>Ao criar uma instncia dessa classe e chamar {@link
android.support.v4.app.DialogFragment#show show()} nesse objeto, a caixa de dilogo ser exibida como
ilustrado na figura 1.</p>

<p>A prxima seo descreve em mais detalhes o uso das APIs{@link android.app.AlertDialog.Builder}
para a criao de uma caixa de dilogo.</p>

<p>Conforme o nvel de complexidade da caixa de dilogo,  possvel implementar diversos outros mtodos
de retorno de chamada no {@link android.support.v4.app.DialogFragment}, inclusive todos os
<a href="{@docRoot}guide/components/fragments.html#Lifecycle">mtodos de ciclo de vida de fragmentos</a> bsicos.


<h2 id="AlertDialog">Construo de uma caixa de dilogo de alerta</h2>


<p>A classe {@link android.app.AlertDialog} permite a criao de diversos projetos de caixa de dilogo
e normalmente  a nica classe de caixa de dilogo necessria.
Como ilustrado na figura 2, h trs regies de uma caixa de dilogo de alerta:</p>

<div class="figure" style="width:311px;margin-top:0">
<img src="{@docRoot}images/ui/dialogs_regions.png" alt="" style="margin-bottom:0" />
<p class="img-caption"><strong>Figura 2.</strong> Layout de uma caixa de dilogo.</p>
</div>

<ol>
<li><b>Ttulo</b>
  <p> opcional e deve ser usado somente quando a rea do contedo
  estiver ocupada por uma mensagem detalhada, uma lista ou layout personalizado. Se for necessrio declarar
  uma mensagem ou pergunta simples (como a caixa de dilogo na figura 1), o ttulo no  necessrio.</li>
<li><b>rea do contedo</b>
  <p>Pode exibir uma mensagem, uma lista ou outro layout personalizado.</p></li>
<li><b>Botes de ao</b>
  <p>No deve haver mais de trs botes em uma caixa de dilogo.</p></li>
</ol>

<p>A classe {@link android.app.AlertDialog.Builder}
 fornece APIs que permitem a criao de uma {@link android.app.AlertDialog}
 com esses tipos de contedo, inclusive um layout personalizado.</p>

<p>Para criar uma {@link android.app.AlertDialog}:</p>

<pre>
<b>// 1. Instantiate an {@link android.app.AlertDialog.Builder} with its constructor</b>
AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());

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

<b>// 3. Get the {@link android.app.AlertDialog} from {@link android.app.AlertDialog.Builder#create()}</b>
AlertDialog dialog = builder.create();
</pre>

<p>Os tpicos a seguir mostram como definir diversos atributos de caixas de dilogo
com a classe {@link android.app.AlertDialog.Builder}.</p>


<h3 id="AddingButtons">Adio de botes</h3>

<p>Para adicionar botes de ao como os da figura 2,
chame os mtodos {@link android.app.AlertDialog.Builder#setPositiveButton setPositiveButton()} e
{@link android.app.AlertDialog.Builder#setNegativeButton setNegativeButton()}:</p>

<pre style="clear:right">
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();
</pre>

<p>Os mtodos <code>set...Button()</code> exigem um ttulo para o boto (fornecido
por um <a href="{@docRoot}guide/topics/resources/string-resource.html">recurso de string</a>) e um
{@link android.content.DialogInterface.OnClickListener} que defina a ao a realizar
quando o usurio pressionar o boto.</p>

<p>H trs botes de ao diferente que podem ser adicionados:</p>
<dl>
  <dt>Positivo</dt>
  <dd> o que se deve usar para aceitar e continuar a ao (a ao "OK").</dd>
  <dt>Negativo</dt>
  <dd> o que se deve usar para cancelar a ao.</dd>
  <dt>Neutro</dt>
  <dd> o que se deve usar quando houver a opo de o usurio no querer continuar a ao,
  mas no necessariamente cancel-la. Ele aparece entre os botes positivo
  e negativo. Por exemplo: a ao pode ser "Notifique-me mais tarde".</dd>
</dl>

<p> possvel adicionar somente um de cada tipo de boto a uma {@link
android.app.AlertDialog}, ou seja, no  possvel ter mais de um boto "positivo".</p>


<div class="figure" style="width:290px;margin:0 0 0 40px">
<img src="{@docRoot}images/ui/dialog_list.png" alt="" />
<p class="img-caption"><strong>Figura 3.</strong>
Caixa de dilogo com um ttulo e uma lista.</p>
</div>

<h3 id="AddingAList">Adio de listas</h3>

<p>H trs tipos de listas disponveis nas APIs {@link android.app.AlertDialog}:</p>
<ul>
<li>Lista de escolha nica tradicional</li>
<li>Lista de escolha nica persistente (botes de opo)</li>
<li>Lista de escolhas mltiplas persistentes (caixas de seleo)</li>
</ul>

<p>Para criar uma lista de escolha nica como a da figura 3,
use o mtodo {@link android.app.AlertDialog.Builder#setItems setItems()}:</p>

<pre style="clear:right">
&#64;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();
}
</pre>

<p>Como a lista aparece na rea do contedo da caixa de dilogo,
a caixa no pode exibir uma mensagem e uma lista, e ser preciso definir um ttulo
para ela com {@link android.app.AlertDialog.Builder#setTitle setTitle()}.
Para especificar os itens da lista, chame {@link
android.app.AlertDialog.Builder#setItems setItems()} passando uma matriz.
Alternativamente,  possvel especificar uma lista com {@link
android.app.AlertDialog.Builder#setAdapter setAdapter()}. Isso permite retroceder a lista
com dados dinmicos (como os de um banco de dados) com um {@link android.widget.ListAdapter}.</p>

<p>Se voc optar por retroceder a lista com um {@link android.widget.ListAdapter},
sempre use um {@link android.support.v4.content.Loader} para que o contedo carregue
assincronamente. Veja mais detalhes sobre isso nos guias
<a href="{@docRoot}guide/topics/ui/declaring-layout.html#AdapterViews">Criao de layouts
com um adaptador</a> e
<a href="{@docRoot}guide/components/loaders.html">Carregadores</a>.</p>

<p class="note"><strong>Observao:</strong> por padro, o toque em um item de lista dispensa a caixa de dilogo
a menos que voc esteja usando uma das listas de escolha persistentes a seguir.</p>

<div class="figure" style="width:290px;margin:-30px 0 0 40px">
<img src="{@docRoot}images/ui/dialog_checkboxes.png" />
<p class="img-caption"><strong>Figura 4.</strong>
Lista de itens de mltipla escolha.</p>
</div>


<h4 id="Checkboxes">Adio de uma lista de escolha nica ou de mltipla escolha persistente</h4>

<p>Para adicionar uma lista de itens de mltipla escolha (caixas de seleo)
ou itens de escolha nica (botes de rdio), use os mtodos
{@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String,
DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} ou
{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener)
setSingleChoiceItems()} respectivamente.</p>

<p>Por exemplo, a seguir apresenta-se como criar uma lista de mltipla escolha como
a ilustrada na figura 4, que salva os itens
selecionados em uma {@link java.util.ArrayList}:</p>

<pre style="clear:right">
&#64;Override
public Dialog onCreateDialog(Bundle savedInstanceState) {
    mSelectedItems = new ArrayList();  // Where we track the selected items
    AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
    // Set the dialog title
    builder.setTitle(R.string.pick_toppings)
    // Specify the list array, the items to be selected by default (null for none),
    // and the listener through which to receive callbacks when items are selected
           .setMultiChoiceItems(R.array.toppings, null,
                      new DialogInterface.OnMultiChoiceClickListener() {
               &#64;Override
               public void onClick(DialogInterface dialog, int which,
                       boolean isChecked) {
                   if (isChecked) {
                       // If the user checked the item, add it to the selected items
                       mSelectedItems.add(which);
                   } else if (mSelectedItems.contains(which)) {
                       // Else, if the item is already in the array, remove it
                       mSelectedItems.remove(Integer.valueOf(which));
                   }
               }
           })
    // Set the action buttons
           .setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() {
               &#64;Override
               public void onClick(DialogInterface dialog, int id) {
                   // User clicked OK, so save the mSelectedItems results somewhere
                   // or return them to the component that opened the dialog
                   ...
               }
           })
           .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() {
               &#64;Override
               public void onClick(DialogInterface dialog, int id) {
                   ...
               }
           });

    return builder.create();
}
</pre>

<p>Embora a lista tradicional e uma lista com botes de opo
forneam uma ao de "escolha nica", deve-se usar {@link
android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener)
setSingleChoiceItems()} se voc desejar manter a escolha do usurio.
Ou seja, se a caixa de dilogo abrir novamente mais tarde, deve indicar qual  a escolha atual do usurio,
portanto deve-se criar uma lista com botes de opo.</p>


<h3 id="CustomLayout">Criao de layout personalizado</h3>

<div class="figure" style="width:290px;margin:-30px 0 0 40px">
<img src="{@docRoot}images/ui/dialog_custom.png" alt="" />
<p class="img-caption"><strong>Figura 5.</strong> Layout personalizado da caixa de dilogo.</p>
</div>

<p>Se voc deseja um layout personalizado em uma caixa de dilogo, crie um layout e adicione-o a uma
{@link android.app.AlertDialog} chamando {@link
android.app.AlertDialog.Builder#setView setView()} no objeto {@link
android.app.AlertDialog.Builder}.</p>

<p>Por padro, o layout personalizado preenche a janela da caixa de dilogo, mas ainda  possvel
usar mtodos {@link android.app.AlertDialog.Builder} para adicionar botes e um ttulo.</p>

<p>Por exemplo, a seguir h o arquivo de layout para a caixa de dilogo na figura 5:</p>

<p style="clear:right" class="code-caption">res/layout/dialog_signin.xml</p>
<pre>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content">
    &lt;ImageView
        android:src="@drawable/header_logo"
        android:layout_width="match_parent"
        android:layout_height="64dp"
        android:scaleType="center"
        android:background="#FFFFBB33"
        android:contentDescription="@string/app_name" />
    &lt;EditText
        android:id="@+id/username"
        android:inputType="textEmailAddress"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginTop="16dp"
        android:layout_marginLeft="4dp"
        android:layout_marginRight="4dp"
        android:layout_marginBottom="4dp"
        android:hint="@string/username" />
    &lt;EditText
        android:id="@+id/password"
        android:inputType="textPassword"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginTop="4dp"
        android:layout_marginLeft="4dp"
        android:layout_marginRight="4dp"
        android:layout_marginBottom="16dp"
        android:fontFamily="sans-serif"
        android:hint="@string/password"/>
&lt;/LinearLayout>
</pre>

<p class="note"><strong>Dica:</strong> por padro, ao definir um elemento
{@link android.widget.EditText} para usar o tipo de entrada {@code "textPassword"}, a famlia da fonte  definida como de espao nico, portanto
deve-se alterar a famlia da fonte para {@code "sans-serif"} para que os campos de texto usem
um estilo de fonte compatvel.</p>

<p>Para inflar o layout no {@link android.support.v4.app.DialogFragment},
obtenha um {@link android.view.LayoutInflater} com
{@link android.app.Activity#getLayoutInflater()} e chame
{@link android.view.LayoutInflater#inflate inflate()}, em que o primeiro parmetro
 o ID de recurso do layout e o segundo  uma vista pai do layout.
Em seguida, pode-se chamar {@link android.app.AlertDialog#setView setView()}
para posicionar o layout na caixa de dilogo.</p>

<pre>
&#64;Override
public Dialog onCreateDialog(Bundle savedInstanceState) {
    AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
    // Get the layout inflater
    LayoutInflater inflater = getActivity().getLayoutInflater();

    // Inflate and set the layout for the dialog
    // Pass null as the parent view because its going in the dialog layout
    builder.setView(inflater.inflate(R.layout.dialog_signin, null))
    // Add action buttons
           .setPositiveButton(R.string.signin, new DialogInterface.OnClickListener() {
               &#64;Override
               public void onClick(DialogInterface dialog, int id) {
                   // sign in the user ...
               }
           })
           .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() {
               public void onClick(DialogInterface dialog, int id) {
                   LoginDialogFragment.this.getDialog().cancel();
               }
           });
    return builder.create();
}
</pre>

<div class="note">
<p><strong>Dica:</strong> se voc deseja uma caixa de dilogo personalizada,
pode exibir uma {@link android.app.Activity} como uma caixa de dilogo
em vez de usar as APIs {@link android.app.Dialog}. Basta criar uma atividade e definir seu tema como
{@link android.R.style#Theme_Holo_Dialog Theme.Holo.Dialog}
no elemento <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
&lt;activity&gt;}</a> do manifesto:</p>

<pre>
&lt;activity android:theme="&#64;android:style/Theme.Holo.Dialog" >
</pre>
<p>Pronto. Agora a atividade  exibida em uma janela da caixa de dilogo em vez de tela cheia.</p>
</div>


<h2 id="PassingEvents">Direcionamento de eventos de volta ao host da caixa de dilogo</h2>

<p>Quando o usurio toca em um dos botes de ao da caixa de dilogo ou seleciona um item de sua lista,
o {@link android.support.v4.app.DialogFragment} pode realizar a ao
necessria sozinho, mas normalmente ser necessrio fornecer o evento  atividade ou ao fragmento
que abriu a caixa de dilogo. Para isso, defina uma interface com um mtodo para cada tipo de evento de clique.
Em seguida, implemente essa interface no componente do host
que receber os eventos de ao da caixa de dilogo.</p>

<p>Por exemplo, a seguir h um {@link android.support.v4.app.DialogFragment} que define
uma interface por meio da qual entrega os eventos de volta  atividade do host:</p>

<pre>
public class NoticeDialogFragment extends DialogFragment {

    /* The activity that creates an instance of this dialog fragment must
     * implement this interface in order to receive event callbacks.
     * Each method passes the DialogFragment in case the host needs to query it. */
    public interface NoticeDialogListener {
        public void onDialogPositiveClick(DialogFragment dialog);
        public void onDialogNegativeClick(DialogFragment dialog);
    }

    // Use this instance of the interface to deliver action events
    NoticeDialogListener mListener;

    // Override the Fragment.onAttach() method to instantiate the NoticeDialogListener
    &#64;Override
    public void onAttach(Activity activity) {
        super.onAttach(activity);
        // Verify that the host activity implements the callback interface
        try {
            // Instantiate the NoticeDialogListener so we can send events to the host
            mListener = (NoticeDialogListener) activity;
        } catch (ClassCastException e) {
            // The activity doesn't implement the interface, throw exception
            throw new ClassCastException(activity.toString()
                    + " must implement NoticeDialogListener");
        }
    }
    ...
}
</pre>

<p>A atividade que hospeda a caixa de dilogo cria uma instncia da caixa
com o construtor do fragmento da caixa de dilogo e recebe os eventos
dela por meio de uma implementao da interface {@code NoticeDialogListener}:</p>

<pre>
public class MainActivity extends FragmentActivity
                          implements NoticeDialogFragment.NoticeDialogListener{
    ...

    public void showNoticeDialog() {
        // Create an instance of the dialog fragment and show it
        DialogFragment dialog = new NoticeDialogFragment();
        dialog.show(getSupportFragmentManager(), "NoticeDialogFragment");
    }

    // The dialog fragment receives a reference to this Activity through the
    // Fragment.onAttach() callback, which it uses to call the following methods
    // defined by the NoticeDialogFragment.NoticeDialogListener interface
    &#64;Override
    public void onDialogPositiveClick(DialogFragment dialog) {
        // User touched the dialog's positive button
        ...
    }

    &#64;Override
    public void onDialogNegativeClick(DialogFragment dialog) {
        // User touched the dialog's negative button
        ...
    }
}
</pre>

<p>Como a atividade do host implementa o {@code NoticeDialogListener} &mdash; que
forado pelo mtodo de retorno de chamada {@link android.support.v4.app.Fragment#onAttach onAttach()}
exibido acima &mdash;, o fragmento da caixa de dilogo pode usar
os mtodos de retorno de chamada da interface para entregar eventos de clique  atividade:</p>

<pre>
public class NoticeDialogFragment extends DialogFragment {
    ...

    &#64;Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Build the dialog and set up the button click handlers
        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) {
                       // Send the positive button event back to the host activity
                       mListener.onDialogPositiveClick(NoticeDialogFragment.this);
                   }
               })
               .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() {
                   public void onClick(DialogInterface dialog, int id) {
                       // Send the negative button event back to the host activity
                       mListener.onDialogNegativeClick(NoticeDialogFragment.this);
                   }
               });
        return builder.create();
    }
}
</pre>


<h2 id="ShowingADialog">Exibio de uma caixa de dilogo</h2>

<p>Para exibir a caixa de dilogo, crie uma instncia do {@link
android.support.v4.app.DialogFragment} e chame {@link android.support.v4.app.DialogFragment#show
show()} passando o {@link android.support.v4.app.FragmentManager} e um nome de tag
para o fragmento da caixa de dilogo.</p>

<p>Para obter o {@link android.support.v4.app.FragmentManager}, chama-se
{@link android.support.v4.app.FragmentActivity#getSupportFragmentManager()}
da {@link android.support.v4.app.FragmentActivity} ou {@link
android.support.v4.app.Fragment#getFragmentManager()} de um {@link
android.support.v4.app.Fragment}. Por exemplo:</p>

<pre>
public void confirmFireMissiles() {
    DialogFragment newFragment = new FireMissilesDialogFragment();
    newFragment.show(getSupportFragmentManager(), "missiles");
}
</pre>

<p>O segundo argumento, {@code "missiles"},  um nome de tag exclusivo que o sistema usa para salvar
e restaurar o estado do fragmento quando necessrio. Para que a tag obtenha um identificador
do fragmento, chama-se {@link android.support.v4.app.FragmentManager#findFragmentByTag
findFragmentByTag()}.</p>


<h2 id="FullscreenDialog">Exibio de uma caixa de dilogo em tela cheia ou como um fragmento incorporado</h2>

<p>Pode-se ter um projeto de IU em que uma parte da IU aparea como uma caixa de dilogo em determinadas
situaes, mas como tela cheia ou fragmento incorporado em outras (dependendo, talvez,
do tamanho da tela do dispositivo). A classe {@link android.support.v4.app.DialogFragment}
oferece esta flexibilidade porque ainda pode comportar-se como um {@link
android.support.v4.app.Fragment} incorporvel.</p>

<p>Contudo, no  possvel usar {@link android.app.AlertDialog.Builder AlertDialog.Builder}
nem outros objetos {@link android.app.Dialog} para criar a caixa de dilogo nesse caso. Se
voc deseja que {@link android.support.v4.app.DialogFragment} seja
incorporvel, defina a IU da caixa de dilogo em um layout e carregue ou layout no retorno de chamada
{@link android.support.v4.app.DialogFragment#onCreateView
onCreateView()}.</p>

<p>A seguir h um exemplo de {@link android.support.v4.app.DialogFragment} que pode aparecer tanto como
caixa de dilogo quanto como fragmento incorporvel (usando um layout chamado <code>purchase_items.xml</code>):</p>

<pre>
public class CustomDialogFragment extends DialogFragment {
    /** The system calls this to get the DialogFragment's layout, regardless
        of whether it's being displayed as a dialog or an embedded fragment. */
    &#64;Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container,
            Bundle savedInstanceState) {
        // Inflate the layout to use as dialog or embedded fragment
        return inflater.inflate(R.layout.purchase_items, container, false);
    }

    /** The system calls this only when creating the layout in a dialog. */
    &#64;Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // The only reason you might override this method when using onCreateView() is
        // to modify any dialog characteristics. For example, the dialog includes a
        // title by default, but your custom layout might not need it. So here you can
        // remove the dialog title, but you must call the superclass to get the Dialog.
        Dialog dialog = super.onCreateDialog(savedInstanceState);
        dialog.requestWindowFeature(Window.FEATURE_NO_TITLE);
        return dialog;
    }
}
</pre>

<p>A seguir, veja alguns cdigos que decidem por exibir o fragmento como uma caixa de dilogo
ou como uma IU de tela cheia com base no tamanho da tela:</p>

<pre>
public void showDialog() {
    FragmentManager fragmentManager = getSupportFragmentManager();
    CustomDialogFragment newFragment = new CustomDialogFragment();

    if (mIsLargeLayout) {
        // The device is using a large layout, so show the fragment as a dialog
        newFragment.show(fragmentManager, "dialog");
    } else {
        // The device is smaller, so show the fragment fullscreen
        FragmentTransaction transaction = fragmentManager.beginTransaction();
        // For a little polish, specify a transition animation
        transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN);
        // To make it fullscreen, use the 'content' root view as the container
        // for the fragment, which is always the root view for the activity
        transaction.add(android.R.id.content, newFragment)
                   .addToBackStack(null).commit();
    }
}
</pre>

<p>Para obter mais informaes sobre a realizao de operaes de fragmentos, consulte o guia
<a href="{@docRoot}guide/components/fragments.html">Fragmentos</a>.</p>

<p>Nesse exemplo, o booleano <code>mIsLargeLayout</code> especifica se o dispositivo atual
deve usar o projeto de layout grande do aplicativo (e, portanto, exibir esse fragmento como uma caixa de dilogo em
vez de tela cheia). O melhor modo de definir esse tipo de booleano  declarar
um <a href="{@docRoot}guide/topics/resources/more-resources.html#Bool">valor de recurso bool</a>
com um valor de <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">recurso alternativo</a> para diferentes tamanhos de tela. Por exemplo, a seguir h duas
verses de recurso bool para diferentes tamanhos de tela:</p>

<p class="code-caption">res/values/bools.xml</p>
<pre>
&lt;!-- Default boolean values -->
&lt;resources>
    &lt;bool name="large_layout">false&lt;/bool>
&lt;/resources>
</pre>

<p class="code-caption">res/values-large/bools.xml</p>
<pre>
&lt;!-- Large screen boolean values -->
&lt;resources>
    &lt;bool name="large_layout">true&lt;/bool>
&lt;/resources>
</pre>

<p>Assim,  possvel inicializar o valor {@code mIsLargeLayout} durante o mtodo
{@link android.app.Activity#onCreate onCreate()} da atividade:</p>

<pre>
boolean mIsLargeLayout;

&#64;Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mIsLargeLayout = getResources().getBoolean(R.bool.large_layout);
}
</pre>


<h3 id="ActivityAsDialog">Exibio de uma atividade como uma caixa de dilogo em telas grandes</h3>

<p>Em vez de exibir uma caixa de dilogo como uma IU de tela cheia em telas pequenas,  possvel obter
o mesmo resultado exibindo uma {@link android.app.Activity} como uma caixa de dilogo
em telas grandes. A abordagem escolhida depende do projeto do aplicativo,
mas a exibio de uma atividade como caixa de dilogo normalmente  til quando o aplicativo j est projetado
para telas pequenas e  preciso melhorar a experincia em tablets exibindo uma atividade de vida curta
como uma caixa de dilogo.</p>

<p>Para exibir uma atividade como uma caixa de dilogo somente em telas grandes,
aplique o tema {@link android.R.style#Theme_Holo_DialogWhenLarge Theme.Holo.DialogWhenLarge}
no elemento <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
&lt;activity&gt;}</a> do manifesto:</p>

<pre>
&lt;activity android:theme="&#64;android:style/Theme.Holo.DialogWhenLarge" >
</pre>

<p>Para obter mais informaes sobre estilizar as atividades com temas, consulte o guia <a href="{@docRoot}guide/topics/ui/themes.html">Estilos e temas</a>.</p>


<h2 id="DismissingADialog">Dispensa de uma caixa de dilogo</h2>

<p>Quando o usurio toca em qualquer boto de ao criado
com um {@link android.app.AlertDialog.Builder}, o sistema dispensa a caixa de dilogo.</p>

<p>O sistema tambm dispensa a caixa de dilogo quando o usurio toca em um item em uma lista da caixa de dilogo, exceto
quanto a lista usa botes de opo ou caixas de seleo. Caso contrrio,  possvel dispens-la manualmente
chamando {@link android.support.v4.app.DialogFragment#dismiss()} no {@link
android.support.v4.app.DialogFragment}.</p>

<p>Se for necessrio realizar determinadas
aes quando a caixa de dilogo  dispensada,  possvel implementar o mtodo {@link
android.support.v4.app.DialogFragment#onDismiss onDismiss()} no {@link
android.support.v4.app.DialogFragment}.</p>

<p>Tambm  possvel <em>cancelar</em> uma caixa de dilogo. Trata-se de um evento especial que indica que o usurio
se retirou explicitamente da caixa de dilogo sem concluir a tarefa. Isso ocorre se o usurio pressionar o boto
<em>Voltar</em>, tocar na tela fora da rea da caixa de dilogo
ou se voc chamar {@link android.app.Dialog#cancel()} explicitamente no {@link
android.app.Dialog} (como em resposta a um boto "Cancelar" na caixa de dilogo).</p>

<p>Como mostrado no exemplo acima,  possvel responder ao evento de cancelamento implementando
{@link android.support.v4.app.DialogFragment#onCancel onCancel()} na classe {@link
android.support.v4.app.DialogFragment}.</p>

<p class="note"><strong>Observao:</strong> o sistema chama
{@link android.support.v4.app.DialogFragment#onDismiss onDismiss()} para cada evento que
chama o retorno de chamada {@link android.support.v4.app.DialogFragment#onCancel onCancel()}. Entretanto,
se voc chamar {@link android.app.Dialog#dismiss Dialog.dismiss()} ou  {@link
android.support.v4.app.DialogFragment#dismiss DialogFragment.dismiss()},
 o sistema chamar {@link android.support.v4.app.DialogFragment#onDismiss onDismiss()}, <em>mas
no</em> {@link android.support.v4.app.DialogFragment#onCancel onCancel()}. Portanto, geralmente, deve-se
chamar {@link android.support.v4.app.DialogFragment#dismiss dismiss()} quando o usurio pressiona
o boto <em>positivo</em> na caixa de dilogo para remov-la da vista.</p>