xref: /frameworks/base/docs/html-intl/intl/pt-br/guide/components/fragments.jd

page.title=Fragmentos
parent.title=Atividades
parent.link=activities.html
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>Neste documento</h2>
  <ol>
    <li><a href="#Design">Filosofia do projeto</a></li>
    <li><a href="#Creating">Criao de um fragmento</a>
      <ol>
        <li><a href="#UI">Adio de uma interface do usurio</a></li>
        <li><a href="#Adding">Adio de um fragmento a uma atividade</a></li>
      </ol>
    </li>
    <li><a href="#Managing">Gerenciamento de fragmentos</a></li>
    <li><a href="#Transactions">Realizao de operaes com fragmentos</a></li>
    <li><a href="#CommunicatingWithActivity">Comunicao com a atividade</a>
      <ol>
        <li><a href="#EventCallbacks">Criao de eventos de retornos de chamada para a atividade</a></li>
        <li><a href="#ActionBar">Adio de itens  barra de ao</a></li>
      </ol>
    </li>
    <li><a href="#Lifecycle">Tratamento do ciclo de vida dos fragmentos</a>
      <ol>
        <li><a href="#CoordinatingWithActivity">Coordenao com o ciclo de vida da atividade</a></li>
      </ol>
    </li>
    <li><a href="#Example">Exemplo</a></li>
  </ol>

  <h2>Classes principais</h2>
  <ol>
    <li>{@link android.app.Fragment}</li>
    <li>{@link android.app.FragmentManager}</li>
    <li>{@link android.app.FragmentTransaction}</li>
  </ol>
  
  <h2>Veja tambm</h2>
  <ol>
    <li><a href="{@docRoot}training/basics/fragments/index.html">Construo de uma IU dinmica com Fragmentos</a></li>
    <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Compatibilidade com
tablets e celulares</a></li>
  </ol>
</div>
</div>

<p>Um {@link android.app.Fragment} representa o comportamento ou uma parte da interface do usurio em um
{@link android.app.Activity}.  possvel combinar vrios fragmentos em uma nica atividade para compilar
uma IU de painis mltiplos e reutilizar um fragmento em diversas atividades. Um fragmento
 como uma seo modular de uma atividade, que tem o prprio ciclo de vida, recebe os prprios eventos de entrada
e que pode ser adicionado ou removido com a atividade em execuo (uma espcie de "sub-atividade"
que pode ser reutilizada em diferentes atividades).</p>

<p>Um fragmento deve sempre ser embutido em uma atividade e o ciclo de vida dele
 diretamente impactado pelo ciclo de vida da atividade do host. Por exemplo, quando a atividade  pausada, todos os fragmentos
tambm so e, quando a atividade  destruda, todos os fragmentos tambm so. No entanto, enquanto
uma atividade estiver em execuo (estiver no <em>estado do ciclo de vida</em> <a href="{@docRoot}guide/components/activities.html#Lifecycle">retomado</a>),  possvel
manipular cada fragmento independentemente, como adicionar ou remov-los. Ao realizar tal operao com fragmentos,
tambm  possvel adicion-los a uma pilha de retorno que  gerenciada pela
atividade &mdash; cada entrada da pilha de retorno na atividade  um registro da operao de fragmento
que ocorreu. A pilha de retorno permite que o usurio inverta uma operao de fragmento (navegue ao contrrio),
pressionando o boto <em>Voltar</em>.</p>

<p>Ao adicionar um fragmento como parte do layout da atividade, ele viver em um {@link
android.view.ViewGroup} dentro da hierarquia de vistas e o fragmento definir o prprio
layout da vista.
 possvel inserir um fragmento no layout, declarando-o no arquivo de layout
da atividade, como um elemento {@code &lt;fragment&gt;} ou a partir do cdigo do aplicativo adicionando-o
a um {@link android.view.ViewGroup} existente. No entanto, no  necessrio que um fragmento faa parte
do layout da atividade; tambm  possvel usar um fragmento sem a IU como um trabalhador invisvel
da atividade.</p>

<p>Este documento descreve como compilar o aplicativo para usar fragmentos,
incluindo como os fragmentos podem manter seu estado ao serem adicionados  pilha de retorno da atividade,
como compartilhar eventos com a atividade e com outros fragmentos da atividade, como contribuir para a barra de ao
da atividade e muito mais.</p>


<h2 id="Design">Filosofia do projeto</h2>

<p>O Android introduziu os fragmentos no Android 3.0 (API de nvel 11), principalmente para suportar
mais projetos de IU flexveis e dinmicos em telas grandes, como em tablets. Como a tela de um tablet
 muito maior que a de um celular, h mais espao para combinar
e alternar componentes da IU. Os fragmentos permitem tais projetos sem haver a necessidade de gerenciar
alteraes complexas na hierarquia de vistas. Ao dividir o layout de uma atividade em fragmentos,  possvel
modificar a aparncia da atividade em tempo de execuo e preservar essas alteraes na pilha de retorno,
que  gerenciada por esta atividade.</p>

<p>Por exemplo, um aplicativo de notcias pode usar um fragmento para exibir uma lista de artigos
na esquerda e outro fragmento para exibir um artigo na direita &mdash; ambos os fragmentos aparecem
em uma atividade, lado a lado, e cada fragmento possui o prprio conjunto de mtodos de retorno de chamada do ciclo de vida e lidam
com os prprios eventos de entrada do usurio. Portanto, em vez de usar uma atividade para selecionar um artigo
e outra atividade para l-lo, o usurio pode selecionar um artigo e l-lo por completo dentro
da mesma atividade, como ilustrado no layout do tablet na figura 1.</p>

<p>Voc deve projetar cada fragmento como um componente modular e reutilizvel da atividade. Ou seja, como cada fragmento
define seu prprio layout e comportamento com os prprios retornos de chamada do ciclo de vida,  possvel
incluir um fragmento em vrias atividades para poder projet-lo para reutilizao e evitar
a manipulao direta de um fragmento a partir de outro fragmento. Isto  especialmente importante porque
um fragmento modular permite alterar as combinaes de fragmentos para tamanhos de tela diferentes. Ao projetar o aplicativo
para ser compatvel com tablets e celulares, voc poder reutilizar os fragmentos em diferentes configuraes
de layout para otimizar a experincia do usurio com base no espao de tela disponvel. Por exemplo,
em um celular, talvez seja necessrio separar os fragmentos para fornecer uma IU de painel nico
quando mais de um no se encaixar dentro da mesma atividade.</p>

<img src="{@docRoot}images/fundamentals/fragments.png" alt="" />
<p class="img-caption"><strong>Figura 1.</strong> Um exemplo de como dois mdulos de IU definidos
pelos fragmentos podem ser combinados em uma atividade de um projeto para tablet mas separados
em um projeto para celular.</p>

<p>Por exemplo, &mdash; continuando com o exemplo do aplicativo de notcias &mdash; o aplicativo pode embutir
dois fragmentos na <em>atividade A</em>, quando executado em um dispositivo do tamanho de um tablet. No entanto,
em uma tela de tamanho de celular, no h espao suficiente para ambos os fragmentos, ento a <em>atividade A</em> inclui
somente o fragmento da lista de artigos e, quando o usurio seleciona um artigo, ele inicia
a <em>atividade B</em>, que inclui o segundo fragmento para ler o artigo. Portanto, o aplicativo
 compatvel com tablets e celulares atravs da reutilizao dos fragmentos em combinaes diferentes, como ilustrado
na figura 1.</p>

<p>Para obter mais informaes sobre o projeto de aplicativos com diferentes combinaes de fragmentos
para configuraes de tela diferentes, consulte o guia <a href="{@docRoot}guide/practices/tablets-and-handsets.html">Compatibilidade com tablets e celulares</a>.</p>



<h2 id="Creating">Criao de um fragmento</h2>

<div class="figure" style="width:327px">
<img src="{@docRoot}images/fragment_lifecycle.png" alt="" />
<p class="img-caption"><strong>Figura 2.</strong> O ciclo de vida de um fragmento
(enquanto sua atividade est em execuo).</p>
</div>

<p>Para criar um fragmento,  preciso criar uma subclasse de {@link android.app.Fragment} (ou uma respectiva
subclasse existente). A classe {@link android.app.Fragment} tem um cdigo que  muito parecido
com o de uma {@link android.app.Activity}. Ele contm mtodos de retorno de chamada semelhantes aos de uma atividade,
como {@link android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()},
{@link android.app.Fragment#onPause onPause()} e {@link android.app.Fragment#onStop onStop()}. Na verdade,
caso esteja convertendo um aplicativo do Android existente para usar os fragmentos, basta mover
o cdigo dos mtodos de retorno de chamada da atividade para os respectivos mtodos de retorno de chamada
do fragmento.</p>

<p>Geralmente, deve-se implementar pelo menos os seguintes mtodos de ciclo de vida:</p>

<dl>
  <dt>{@link android.app.Fragment#onCreate onCreate()}</dt>
  <dd>O sistema o chama ao criar o fragmento. Dentro da implementao,
deve-se inicializar os componentes essenciais do fragmento que deseja-se reter quando o fragmento
for pausado ou interrompido e, em seguida, retomado.</dd>
  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
  <dd>O sistema chama isto quando  o momento de o fragmento desenhar a interface do usurio
pela primeira vez. Para desenhar uma IU para o fragmento, voc deve retornar uma {@link android.view.View}
deste mtodo, que  a raiz do layout do fragmento.  possvel retornar como nulo se o fragmento
no fornecer uma IU.</dd>
  <dt>{@link android.app.Activity#onPause onPause()}</dt>
  <dd>O sistema chama esse mtodo como o primeiro indcio de que o usurio est saindo
do fragmento (embora no seja sempre uma indicao de que o fragmento est sendo destrudo).  quando geralmente
deve-se confirmar qualquer alterao que deva se manter alm da sesso atual do usurio (porque
o usurio pode no retornar).</dd>
</dl>

<p>A maioria dos aplicativos deve implementar pelo menos trs destes mtodos para cada fragmento,
mas h vrios outros mtodos de retorno de chamada que voc deve usar para lidar com diversos estgios
do ciclo de vida do fragmento. Todos os mtodos de retorno de chamada do ciclo de vida so abordados com mais detalhes na seo
<a href="#Lifecycle">Tratamento do ciclo de vida dos fragmentos</a>.</p>


<p>H tambm algumas subclasses que voc pode querer estender, em vez de a classe {@link
android.app.Fragment} de base:</p>

<dl>
  <dt>{@link android.app.DialogFragment}</dt>
  <dd>Exibe uma caixa de dilogo flutuante. Usar esta classe para criar uma caixa de dilogo  uma boa alternativa
para usar mtodos auxiliares das caixas de dilogo na classe {@link android.app.Activity},
pois  possvel incorporar uma caixa de dilogo de fragmento na pilha de retorno dos fragmentos gerenciados pela atividade,
permitindo que o usurio retorne a um fragmento dispensado.</dd>

  <dt>{@link android.app.ListFragment}</dt>
  <dd>Exibe uma lista de itens que so gerenciados por um adaptador (como um {@link
android.widget.SimpleCursorAdapter}), semelhante  {@link android.app.ListActivity}. Ele fornece vrios mtodos
para gerenciar uma vista de lista, como o retorno de chamada {@link
android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()}
para lidar com eventos de clique.</dd>

  <dt>{@link android.preference.PreferenceFragment}</dt>
  <dd>Exibe uma hierarquia de objetos {@link android.preference.Preference} como uma lista,
parecido com {@link android.preference.PreferenceActivity}. Isto  til ao criar uma atividade
de "configuraes" para o aplicativo.</dd>
</dl>


<h3 id="UI">Adio de uma interface do usurio</h3>

<p>Um fragmento  geralmente usado como parte de uma interface do usurio da atividade e contribui
para a atividade com seu prprio layout.</p>

<p>Para fornecer um layout para um fragmento, voc deve implementar o mtodo de retorno de chamada {@link
android.app.Fragment#onCreateView onCreateView()}, que o sistema Android chama
no momento em que o fragmento deve desenhar o layout. A implementao deste mtodo deve retornar
uma {@link android.view.View}, que  a raiz do layout do fragmento.</p>

<p class="note"><strong>Observao:</strong> se o fragmento for uma subclasse de {@link
android.app.ListFragment}, a implementao padro retornar uma {@link android.widget.ListView}
de {@link android.app.Fragment#onCreateView onCreateView()}, ento no ser necessrio implement-lo.</p>

<p>Para retornar um layout de {@link
android.app.Fragment#onCreateView onCreateView()},  possvel infl-lo a partir de um <a href="{@docRoot}guide/topics/resources/layout-resource.html">recurso de layout</a> definido no XML. Para ajudar
a fazer isto, o {@link android.app.Fragment#onCreateView onCreateView()} fornece
um objeto {@link android.view.LayoutInflater}.</p>

<p>Por exemplo, a seguir h uma subclasse de {@link android.app.Fragment} que carrega um layout
do arquivo {@code example_fragment.xml}:</p>

<pre>
public static class ExampleFragment extends Fragment {
    &#64;Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container,
                             Bundle savedInstanceState) {
        // Inflate the layout for this fragment
        return inflater.inflate(R.layout.example_fragment, container, false);
    }
}
</pre>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h3>Criao de um layout</h3>
  <p>No exemplo acima, {@code R.layout.example_fragment}  uma referncia para um recurso de layout
chamado {@code example_fragment.xml}, salvo nos recursos do aplicativo. Para obter informaes sobre
como criar um layout no XML, consulte a documentao <a href="{@docRoot}guide/topics/ui/index.html">Interface do usurio</a>
.</p>
</div>
</div>

<p>O parmetro {@code container} passado para {@link android.app.Fragment#onCreateView
onCreateView()}  o pai de {@link android.view.ViewGroup} (do layout da atividade)
em que o layout do fragmento
ser inserido. O parmetro {@code savedInstanceState}  um {@link android.os.Bundle}
que fornece dados sobre a instncia anterior do fragmento, se o fragmento estiver sendo retomado
(a restaurao de estado  abordada mais detalhadamente na seo <a href="#Lifecycle">Tratamento do ciclo
de vida dos fragmentos</a>).</p>

<p>O mtodo {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()}
usa trs argumentos:</p>
<ul>
  <li>O ID de recurso do layout que voc quer inflar.</li>
  <li>O {@link android.view.ViewGroup} que ser pai do layout inflado. Passar o {@code
container}  importante para que o sistema aplique os parmetros de layout  vista raiz
do layout inflado, especificado pela vista pai em que est ocorrendo.</li>
  <li>Um booleano que indica se o layout inflado deve ser anexado a {@link
android.view.ViewGroup} (o segundo parmetro) durante a inflao (neste caso,
isto  falso, pois o sistema j est inserindo o layout inflado no {@code
container} &mdash; retornar como verdadeiro criaria um grupo de vistas redundante no layout final).</li>
</ul>

<p>Este  o modo de criar um fragmento que fornece um layout. A seguir,
 preciso adicionar o fragmento  atividade.</p>



<h3 id="Adding">Adio de um fragmento a uma atividade</h3>

<p>Geralmente, um fragmento contribui com a atividade do host com uma parte da IU, que  embutida como parte
da hierarquia de vistas geral da atividade. H duas formas de adicionar um fragmento ao layout
da atividade:</p>

<ul>
  <li><b>Declarar o fragmento dentro do arquivo de layout da atividade.</b>
<p>Neste caso,
 possvel especificar as propriedades do layout para o fragmento como se fosse uma vista. Por exemplo, a seguir h o arquivo de layout
para uma atividade com dois fragmentos:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="horizontal"
    android:layout_width="match_parent"
    android:layout_height="match_parent"&gt;
    &lt;fragment android:name="com.example.news.ArticleListFragment"
            android:id="@+id/list"
            android:layout_weight="1"
            android:layout_width="0dp"
            android:layout_height="match_parent" /&gt;
    &lt;fragment android:name="com.example.news.ArticleReaderFragment"
            android:id="@+id/viewer"
            android:layout_weight="2"
            android:layout_width="0dp"
            android:layout_height="match_parent" /&gt;
&lt;/LinearLayout&gt;
</pre>
  <p>O atributo {@code android:name} em {@code &lt;fragment&gt;} especifica a classe {@link
android.app.Fragment} a instanciar no layout.</p>

<p>Quando o sistema cria este layout de atividade, ele instancia cada fragmento especificado
no layout e chama o mtodo {@link android.app.Fragment#onCreateView onCreateView()} para cada um
para recuperar o layout de cada fragmento. O sistema insere a {@link android.view.View} retornada
pelo fragmento diretamente no lugar do elemento {@code &lt;fragment&gt;}.</p>

<div class="note">
  <p><strong>Observao:</strong> cada fragmento requer um identificador nico
que o sistema possa usar para restaur-lo se a atividade for reiniciada (e que possa ser usado
para capturar o fragmento para realizar operaes, como a remoo). H trs maneiras de fornecer
um ID para um fragmento:</p>
  <ul>
    <li>Fornecer o atributo {@code android:id} com um ID nico.</li>
    <li>Fornecer o atributo {@code android:tag} com uma string nica.</li>
    <li>Caso no fornea nenhuma das alternativas anteriores, o sistema usar o ID da vista
do recipiente.</li>
  </ul>
</div>
  </li>

  <li><b>Ou adicionar programaticamente o fragmento a um {@link android.view.ViewGroup} existente.</b>
<p>A qualquer momento, enquanto a atividade est em execuo,  possvel adicionar fragmentos ao layout da atividade. Voc precisa
apenas especificar um {@link
android.view.ViewGroup} para posicionar o fragmento.</p>
  <p>Para realizar operaes de fragmentos na atividade (como adicionar, remover ou substituir
um fragmento), voc deve usar APIs de {@link android.app.FragmentTransaction}.  possvel adquirir
uma instncia de {@link android.app.FragmentTransaction} da {@link android.app.Activity} desta maneira:</p>

<pre>
FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()}
FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()};
</pre>

<p> possvel adicionar um fragmento usando o mtodo {@link
android.app.FragmentTransaction#add(int,Fragment) add()}, especificando o fragmento que ser adicionado
e a vista em que ser inserido. Por exemplo:</p>

<pre>
ExampleFragment fragment = new ExampleFragment();
fragmentTransaction.add(R.id.fragment_container, fragment);
fragmentTransaction.commit();
</pre>

  <p>O primeiro argumento passado para {@link android.app.FragmentTransaction#add(int,Fragment) add()}
 {@link android.view.ViewGroup}, onde o fragmento deve ser colocado, especificado
pelo ID de recurso e o segundo parmetro  o fragmento a ser adicionado.</p>
  <p>Ao realizar as alteraes
com {@link android.app.FragmentTransaction},
deve-se chamar{@link android.app.FragmentTransaction#commit} para que as alteraes entrem em vigor.</p>
  </li>
</ul>


<h4 id="AddingWithoutUI">Adio de um fragmento sem IU</h4>

<p>O exemplo acima mostra como adicionar um fragmento  atividade para fornecer uma IU. No entanto,
 possvel tambm usar um fragmento para fornecer o comportamento de segundo plano para a atividade sem apresentar
IU adicional.</p>

<p>Para adicionar um fragmento sem uma IU, adicione o fragmento da atividade usando {@link
android.app.FragmentTransaction#add(Fragment,String)} (fornecendo uma "tag" de string nica
para o fragmento, em vez de um ID de vista). Isto adiciona o fragmento, mas, como ele no est associado
a uma vista no layout da atividade, no recebe uma chamada de {@link
android.app.Fragment#onCreateView onCreateView()}. Portanto, no  necessrio implementar este mtodo.</p>

<p>Fornecer uma tag de string para o fragmento no  algo estrito para fragmentos que no sejam de IU &mdash;  possvel tambm
fornecer tags de string para fragmentos que possuam uma IU &mdash; mas, se o fragmento no possuir uma IU,
a tag de string  a nica maneira de identific-lo. Caso queira obter o fragmento da atividade posteriormente,
voc precisar usar {@link android.app.FragmentManager#findFragmentByTag
findFragmentByTag()}.</p>

<p>Para ver uma atividade de exemplo que usa um fragmento como um trabalhador de segundo plano, sem uma IU, consulte o exemplo de {@code
FragmentRetainInstance.java}, incluso nos exemplos do SDK (disponibilizados pelo 
Android SDK Manager) e localizado no sistema como 
<code>&lt;sdk_root&gt;/APIDemos/app/src/main/java/com/example/android/apis/app/FragmentRetainInstance.java</code>.</p>



<h2 id="Managing">Gerenciamento de fragmentos</h2>

<p>Para gerenciar os fragmentos na atividade, voc precisa usar {@link android.app.FragmentManager}. Para adquiri-lo,
chame {@link android.app.Activity#getFragmentManager()} a partir da atividade.</p>

<p>Algumas das coisas que voc pode fazer com {@link android.app.FragmentManager} incluem:</p>

<ul>
  <li>Adquirir fragmentos existentes na atividade, com {@link
android.app.FragmentManager#findFragmentById findFragmentById()} (para fragmentos que forneam uma IU
no layout da atividade) ou {@link android.app.FragmentManager#findFragmentByTag
findFragmentByTag()} (para fragmentos que forneam ou no uma IU).</li> 
  <li>Retire os fragmentos da pilha de retorno com {@link
android.app.FragmentManager#popBackStack()} (simulando um comando de <em>Voltar</em> do usurio).</li>
  <li>Registre uma escuta para as alteraes na pilha de retorno com {@link
android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li>
</ul>

<p>Para obter mais informaes sobre esses e outros mtodos, consulte a documentao da classe {@link
android.app.FragmentManager}.</p>

<p>Como demonstrado na seo anterior,  possvel usar o {@link android.app.FragmentManager}
para abrir uma {@link android.app.FragmentTransaction}, que permite realizar operaes,
como adicionar e remover fragmentos.</p>


<h2 id="Transactions">Realizao de operaes com fragmentos</h2>

<p>Um grande recurso fornecido por fragmentos em atividades  a possibilidade de adicionar, remover, substituir
e realizar outras aes com eles em resposta  interao do usurio. Cada conjunto de alteraes que forem realizadas
na atividade  chamado de operao e podem ser feitas usando APIs em {@link
android.app.FragmentTransaction}. Tambm  possvel salvar cada operao em uma pilha de retorno gerenciada pela atividade,
permitindo que o usurio navegue inversamente por meio de alteraes de fragmento (semelhante  navegao
inversa por meio de atividades).</p>

<p> possvel adquirir uma instncia de {@link android.app.FragmentTransaction} a partir do {@link
android.app.FragmentManager} da seguinte forma:</p>

<pre>
FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()};
FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()};
</pre>

<p>Cada operao  um conjunto de alteraes que voc deseja realizar ao mesmo tempo.  possvel definir
todas as alteraes desejadas para uma operao usando mtodos como {@link
android.app.FragmentTransaction#add add()}, {@link android.app.FragmentTransaction#remove remove()}
e {@link android.app.FragmentTransaction#replace replace()}. Em seguida, para aplicar a operao
 atividade, deve-se chamar {@link android.app.FragmentTransaction#commit()}.</p>
</dl>

<p>Antes de chamar {@link
android.app.FragmentTransaction#commit()}, no entanto, voc pode querer chamar {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()} para adicionar a operao
a uma pilha de retorno de operaes de fragmentos. A pilha de retorno  gerenciada pela atividade
e permite que o usurio retorne ao estado anterior do fragmento, ao pressionar o boto <em>Voltar</em>.</p>

<p>Por exemplo, a seguir  apresentado o modo de substituir um fragmento por outro e preservar
o estado anterior da pilha de retorno:</p>

<pre>
// Create new fragment and transaction
Fragment newFragment = new ExampleFragment();
FragmentTransaction transaction = getFragmentManager().beginTransaction();

// Replace whatever is in the fragment_container view with this fragment,
// and add the transaction to the back stack
transaction.replace(R.id.fragment_container, newFragment);
transaction.addToBackStack(null);

// Commit the transaction
transaction.commit();
</pre>

<p>Neste exemplo, {@code newFragment} substitui qualquer fragmento (se houver) que estiver
no recipiente do layout identificado pelo ID {@code R.id.fragment_container}. Ao chamar {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()}, a operao de substituio
 salva na pilha de retorno para que o usurio possa reverter a operao
e voltar ao fragmento anterior pressionando o boto <em>Voltar</em>.</p>

<p>Se voc adicionar vrias alteraes  operao (como outro {@link
android.app.FragmentTransaction#add add()} ou {@link android.app.FragmentTransaction#remove
remove()}) e chamar {@link
android.app.FragmentTransaction#addToBackStack addToBackStack()}, todas as alteraes aplicadas
antes de chamar {@link android.app.FragmentTransaction#commit commit()} sero adicionadas
 pilha de retorno como uma nica operao e o boto <em>Voltar</em> reverter todas elas juntas.</p>

<p>A ordem em que voc adicionar as alteraes em {@link android.app.FragmentTransaction} no importa,
exceto que:</p>
<ul>
  <li>Voc deve chamar {@link android.app.FragmentTransaction#commit()} por ltimo</li>
  <li>Caso esteja adicionando vrios fragmentos ao mesmo recipiente, a ordem em que
adicion-los determina a ordem em que eles aparecero na hierarquia de vistas</li>
</ul>

<p>Caso voc no chame {@link android.app.FragmentTransaction#addToBackStack(String)
addToBackStack()} ao realizar uma operao que remove um fragmento, este fragmento
ser destrudo quando a operao for realizada e o usurio no poder navegar de volta a ele. Considerando que,
se voc no chamar {@link android.app.FragmentTransaction#addToBackStack(String) addToBackStack()}
ao remover um fragmento, o fragmento ser <em>interrompido</em> e ser retomado se o usurio
navegar de volta.</p>

<p class="note"><strong>Dica:</strong> para cada operao de fragmento,  possvel aplicar uma animao
de transio, chamando {@link android.app.FragmentTransaction#setTransition setTransition()}
antes da realizao.</p>

<p>Chamar {@link android.app.FragmentTransaction#commit()} no realiza a operao
imediatamente. Em vez disso, o parmetro agenda a execuo no encadeamento da IU da atividade (o encadeamento main, ou principal)
assim que possvel. Se necessrio, no entanto,  possvel chamar {@link
android.app.FragmentManager#executePendingTransactions()} a partir do encadeamento da IU para executar imediatamente
as operaes enviadas por {@link android.app.FragmentTransaction#commit()}. Tal medida, geralmente,
no  necessria, a no ser que a operao represente uma dependncia para trabalhos em outros encadeamentos.</p>

<p class="caution"><strong>Ateno:</strong>  possvel realizar uma operao usando {@link
android.app.FragmentTransaction#commit commit()} somente antes da atividade <a href="{@docRoot}guide/components/activities.html#SavingActivityState">salvar
seu estado</a> (quando o usurio deixa a atividade). Caso tente efetivas as alteraes aps este ponto,
uma exceo ser lanada. Isto acontece porque o estado aps a efetivao pode ser perdido se a atividade
precisar ser restaurada. Para situaes em que no haja problema em perder a efetivao, use {@link
android.app.FragmentTransaction#commitAllowingStateLoss()}.</p>




<h2 id="CommunicatingWithActivity">Comunicao com a atividade</h2>

<p>Apesar de {@link android.app.Fragment} ser implementado como um objeto independente
de uma {@link android.app.Activity} e poder ser usado dentro de vrias atividades, uma dada instncia
de um fragmento  diretamente vinculada  atividade que o contm.</p>

<p>Especificamente, o fragmento pode acessar a instncia {@link android.app.Activity} com {@link
android.app.Fragment#getActivity()} e realizar facilmente tarefas como encontrar uma vista
no layout da atividade:</p>

<pre>
View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list);
</pre>

<p>Do mesmo modo, a atividade pode chamar mtodos no fragmento adquirindo uma referncia
para o {@link android.app.Fragment} a partir do {@link android.app.FragmentManager} usando {@link
android.app.FragmentManager#findFragmentById findFragmentById()} ou {@link
android.app.FragmentManager#findFragmentByTag findFragmentByTag()}. Por exemplo:</p>

<pre>
ExampleFragment fragment = (ExampleFragment) getFragmentManager().findFragmentById(R.id.example_fragment);
</pre>


<h3 id="EventCallbacks">Criao de retornos de chamada de evento para a atividade</h3>

<p>Em alguns casos, um fragmento que compartilhe eventos com a atividade pode ser necessrio. Uma boa maneira de fazer isto
 definir uma interface de retorno de chamada dentro do fragmento e solicitar que a atividade do host
implemente-a. Quando a atividade recebe um retorno de chamada por meio da interface, ela pode compartilhar as informaes
com outros fragmentos no layout conforme necessrio.</p>

<p>Por exemplo, se um aplicativo de notcias em uma atividade tiver dois fragmentos &mdash; um para exibir uma lista
de artigos (fragmento A) e outro para exibir um artigo (fragmento B) &mdash; ento o fragmento A
deve informar  atividade quando um item de lista  selecionado para que ela possa instruir o fragmento B a exibir o artigo. Neste caso,
 a interface {@code OnArticleSelectedListener}  declarada dentro do fragmento A:</p>

<pre>
public static class FragmentA extends ListFragment {
    ...
    // Container Activity must implement this interface
    public interface OnArticleSelectedListener {
        public void onArticleSelected(Uri articleUri);
    }
    ...
}
</pre>

<p>Portanto, a atividade que hospeda o fragmento implementa a interface {@code OnArticleSelectedListener}
e suspende
{@code onArticleSelected()} para notificar o fragmento B do evento do fragmento A. Para garantir
que a atividade do host implemente esta interface, o mtodo de retorno de chamada de {@link
android.app.Fragment#onAttach onAttach()} do fragmento A (que o sistema chama ao adicionar
o fragmento  atividade) instanciar {@code OnArticleSelectedListener}
lanando a {@link android.app.Activity}, que  passada para {@link android.app.Fragment#onAttach
onAttach()}:</p>

<pre>
public static class FragmentA extends ListFragment {
    OnArticleSelectedListener mListener;
    ...
    &#64;Override
    public void onAttach(Activity activity) {
        super.onAttach(activity);
        try {
            mListener = (OnArticleSelectedListener) activity;
        } catch (ClassCastException e) {
            throw new ClassCastException(activity.toString() + " must implement OnArticleSelectedListener");
        }
    }
    ...
}
</pre>

<p>Se a atividade no implementar a interface, o fragmento lanar
{@link java.lang.ClassCastException}.
Se for bem-sucedida, o membro {@code mListener} reter uma referncia da implementao da atividade
de {@code OnArticleSelectedListener}, para que o fragmento A possa compartilhar os eventos com a atividade
chamando mtodos definidos pela interface {@code OnArticleSelectedListener}. Por exemplo, se o fragmento A
for uma extenso de {@link android.app.ListFragment}, sempre
que o usurio clicar em um item de lista, o sistema chamar {@link android.app.ListFragment#onListItemClick
onListItemClick()} no fragmento que, em seguida, chamar {@code onArticleSelected()} para compartilhar
o evento com a atividade:</p>

<pre>
public static class FragmentA extends ListFragment {
    OnArticleSelectedListener mListener;
    ...
    &#64;Override
    public void onListItemClick(ListView l, View v, int position, long id) {
        // Append the clicked item's row ID with the content provider Uri
        Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id);
        // Send the event and Uri to the host activity
        mListener.onArticleSelected(noteUri);
    }
    ...
}
</pre>

<p>O parmetro {@code id} passado para {@link
android.app.ListFragment#onListItemClick onListItemClick()}  o ID da linha do item clicado
que a atividade (ou outro fragmento) usa para resgatar o artigo do {@link
android.content.ContentProvider} do aplicativo.</p>

<p><!--To see a complete implementation of this kind of callback interface, see the <a
href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->Mais informaes sobre
como usar o provedor de contedo esto disponveis na documentao <a href="{@docRoot}guide/topics/providers/content-providers.html">Provedores de contedo</a>.</p>



<h3 id="ActionBar">Adio de itens  barra de ao</h3>

<p>Os fragmentos podem contribuir com itens de menu para o <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">menu de opes</a> da atividade (e, consequentemente, para a <a href="{@docRoot}guide/topics/ui/actionbar.html">barra de ao</a>) implementando 
{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. Para que este mtodo
receba chamadas, no entanto, voc deve chamar {@link
android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} durante {@link
android.app.Fragment#onCreate(Bundle) onCreate()} para indicar que o fragmento
gostaria de adicionar itens ao menu de opes (caso contrrio, o fragmento no receber uma chamada
para {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}).</p>

<p>Quaisquer itens adicionados ao menu de opes do fragmento so anexados
aos itens de menu existentes. O fragmento tambm recebe retornos de chamada para {@link
android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} quando um item de menu
 selecionado.</p>

<p>Tambm  possvel registrar uma vista no layout do fragmento para fornecer um menu de contexto chamando {@link
android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. Quando o usurio
abre o menu de contexto, o fragmento recebe uma chamada de {@link
android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo)
onCreateContextMenu()}. Quando o usurio seleciona um item, o fragmento recebe uma chamada de {@link
android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>

<p class="note"><strong>Observao:</strong> apesar de o fragmento receber um retorno de chamada selecionado no item
para cada item de menu que adiciona, a atividade  a primeira a receber o respectivo retorno de chamada quando o usurio
seleciona um item de menu. Se a implementao da atividade do retorno de chamada selecionado no item no
lida com o item selecionado, o evento  passado para o retorno de chamada do fragmento. Isto  verdadeiro
para o menu de opes e os menus de contexto.</p>

<p>Para obter mais informaes sobre menus, consulte os guias do desenvolvedor <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> e <a href="{@docRoot}guide/topics/ui/actionbar.html">Barra de ao</a>.</p>




<h2 id="Lifecycle">Tratamento do ciclo de vida dos fragmentos</h2>

<div class="figure" style="width:350px">
<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt="" />
<p class="img-caption"><strong>Figura 3.</strong> O efeito do ciclo de vida da atividade no ciclo de vida
do fragmento.</p>
</div>

<p>Gerenciar o ciclo de vida de um fragmento  muito parecido com gerenciar o ciclo de vida de uma atividade. Como uma atividade,
um fragmento pode existir em trs estados:</p>

<dl>
  <dt><i>Retomado</i></dt>
    <dd>O fragmento  visvel na atividade em execuo.</dd>

  <dt><i>Pausado</i></dt>
    <dd>Outra atividade est em primeiro plano, mas a atividade em que este fragmento
vive ainda est visvel (a atividade de primeiro plano  parcialmente transparente
ou no cobre a tela inteira).</dd>

  <dt><i>Interrompido</i></dt>
    <dd>O fragmento no  visvel. A atividade do host foi interrompida
ou o fragmento foi removido da atividade mas adicionado  pilha de retorno. Um fragmento interrompido
ainda est vivo (todas as informaes do membro e de estado esto retidas no sistema). No entanto,
no est mais visvel e ser eliminado se a atividade tambm for.</dd>
</dl>

<p>Alm disso, como uma atividade,  possvel reter o estado de um fragmento usando um {@link
android.os.Bundle}, caso o processo da atividade seja eliminado e voc precise restaurar
o estado do fragmento quando a atividade for recriada.  possvel salvar o estado durante o retorno de chamada {@link
android.app.Fragment#onSaveInstanceState onSaveInstanceState()} do fragmento e restaur-lo
durante {@link android.app.Fragment#onCreate onCreate()}, {@link
android.app.Fragment#onCreateView onCreateView()} ou {@link
android.app.Fragment#onActivityCreated onActivityCreated()}. Para obter mais informaes sobre
como salvar o estado, consulte a documentao <a href="{@docRoot}guide/components/activities.html#SavingActivityState">Atividades</a>
.</p>

<p>A diferena mais significante entre o ciclo de vida de uma atividade e de um fragmento
 o armazenamento em suas respectivas pilhas de retorno. Por padro, uma atividade  colocada de volta na pilha de retorno de atividades,
que  gerenciada pelo sistema, quando interrompida (para que o usurio possa navegar
a ela com o boto <em>Voltar</em>, como discutido em <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tarefas e pilha de retorno</a>).
No entanto, um fragmento  posicionado em uma pilha de retorno gerenciada pela atividade do host somente
ao solicitar explicitamente que a instncia seja salva chamando {@link
android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} durante uma operao
que remove o fragmento.</p>

<p>Caso contrrio, gerenciar o ciclo de vida do fragmento  muito semelhante a gerenciar
o ciclo de vida da atividade. Portanto, as mesmas prticas para <a href="{@docRoot}guide/components/activities.html#Lifecycle">gerenciar o ciclo de vida
da atividade</a> aplicam-se aos fragmentos. O que voc tambm precisa entender, no entanto,  como a vida
da atividade afeta a vida do fragmento.</p>

<p class="caution"><strong>Ateno:</strong> caso precise de um objeto {@link android.content.Context}
dentro do {@link android.app.Fragment},  possvel chamar {@link android.app.Fragment#getActivity()}.
No entanto, tome cuidado para chamar {@link android.app.Fragment#getActivity()} somente quando o fragmento
estiver anexado a uma atividade. Quando o fragmento ainda no estiver anexado, ou tiver sido desvinculado durante o fim
do seu ciclo de vida, {@link android.app.Fragment#getActivity()} retornar como nulo.</p>


<h3 id="CoordinatingWithActivity">Coordenao do ciclo de vida da atividade</h3>

<p>O ciclo de vida da atividade em que o fragmento vive afeta diretamente o ciclo de vida
do fragmento, da mesma forma que um retorno de chamada de cada ciclo de vida da atividade resulta em um retorno de chamada semelhante
de cada fragmento. Por exemplo, quando a atividade receber {@link android.app.Activity#onPause},
cada fragmento na atividade receber {@link android.app.Fragment#onPause}.</p>

<p>Os fragmentos tm alguns retornos de chamada do ciclo de vida extras. No entanto, isto trata da interao nica
com a atividade para realizar aes como compilar e destruir a IU do fragmento. Esses
mtodos adicionais de retorno de chamada so:</p>

<dl>
  <dt>{@link android.app.Fragment#onAttach onAttach()}</dt>
    <dd>Chamado quando o fragmento tiver sido associado  atividade ({@link
android.app.Activity}  passado aqui).</dd>
  <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt>
    <dd>Chamado para criar a hierarquia de vistas associada ao fragmento.</dd>
  <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt>
    <dd>Chamado quando o mtodo {@link android.app.Activity#onCreate
onCreate()} da atividade tiver retornado.</dd>
  <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt>
    <dd>Chamado quando a hierarquia de vistas associada ao fragmento estiver sendo removida.</dd>
  <dt>{@link android.app.Fragment#onDetach onDetach()}</dt>
    <dd>Chamado quando o fragmento estiver sendo desassociado da atividade.</dd>
</dl>

<p>O fluxo do ciclo de vida do fragmento, afetado pela atividade do host, como ilustrado
pela figura 3. Nesta figura,  possvel ver como cada estado sucessivo da atividade determina
qual mtodo de retorno de chamada um fragmento pode receber. Por exemplo, quando a atividade recebe o retorno de chamada {@link
android.app.Activity#onCreate onCreate()}, um fragmento na atividade recebe nada mais
do que o retorno de chamada {@link android.app.Fragment#onActivityCreated onActivityCreated()}.</p>

<p>Quando a atividade atinge o estado retomado,  possvel adicionar e remover fragmentos
dela livremente. Portanto, somente quando a atividade estiver no estado retomado, o ciclo de vida
de um fragmento poder alterar-se de forma independente.</p>

<p>No entanto, quando a atividade deixa o estado retomado, o fragmento  novamente forado
a passar pelo ciclo de vida pela atividade.</p>




<h2 id="Example">Exemplo</h2>

<p>Para juntar tudo que foi discutido neste documento, abaixo h um exemplo de uma atividade
que usa dois fragmentos para criar um layout de dois painis. A atividade abaixo inclui um fragmento
para exibir uma lista de ttulos de peas de Shakespeare e outra para exibir um resumo da pea,
quando selecionada na lista. Ela tambm determina como fornecer diferentes configuraes de fragmentos,
com base na configurao da tela.</p>

<p class="note"><strong>Observao:</strong> O cdigo fonte completo desta atividade est disponvel em
<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.html">{@code
FragmentLayout.java}</a>.</p>

<p>A atividade principal aplica-se de maneira comum, durante {@link
android.app.Activity#onCreate onCreate()}:</p>

{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java main}

<p>O layout aplicado  {@code fragment_layout.xml}:</p>

{@sample development/samples/ApiDemos/res/layout-land/fragment_layout.xml layout}

<p>Usando este layout, o sistema instancia {@code TitlesFragment} (que lista os ttulos
das peas) assim que a atividade carrega o layout, enquanto que {@link android.widget.FrameLayout}
(onde o fragmento para exibir o resumo da pea aparecer) consome o espao do lado direito da tela,
 mas primeiramente permanece vazio. Como ver abaixo, ele no estar visvel at que o usurio selecione um item
na lista em que um fragmento esteja posicionado no {@link android.widget.FrameLayout}.</p>

<p>No entanto, nem todas as configuraes de tela so grandes o suficiente para exibir a lista
de peas e o resumo, lado a lado. Portanto, o layout acima  usado somente para configurao
de tela de paisagem, salvando-o em {@code res/layout-land/fragment_layout.xml}.</p>

<p>Por isso, quando a tela est na orientao de retrato, o sistema aplica o seguinte layout,
que  salvo em {@code res/layout/fragment_layout.xml}:</p>

{@sample development/samples/ApiDemos/res/layout/fragment_layout.xml layout}

<p>Este layout inclui somente {@code TitlesFragment}. Isto significa que, quando o dispositivo
est na orientao de retrato, somente a lista de ttulo das peas est disponvel. Portanto, quando o usurio clicar
em um item da lista nesta configurao, o aplicativo iniciar uma nova atividade para exibir o resumo,
em vez de carregar um segundo fragmento.</p>

<p>A seguir,  possvel ver como isto  realizado com classes de fragmento. Primeiro, {@code
TitlesFragment}, que exibe a lista de peas de Shakespeare. Este fragmento estende {@link
android.app.ListFragment} e confia nele para lidar com grande parte do trabalho da vista de lista.</p>

<p>Enquanto inspeciona este cdigo, observe que h dois possveis comportamentos quando um usurio
clica em um item de lista: dependendo de qual dos dois layouts est ativo, ele pode criar e exibir
um novo fragmento para exibir os detalhes na mesma atividade (adicionando o fragmento {@link
android.widget.FrameLayout}), ou iniciar uma nova atividade (onde o fragmento possa ser exibido).</p>

{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java titles}

<p>O segundo fragmento, {@code DetailsFragment}, exibe o resumo da pea para o item selecionado
na lista de {@code TitlesFragment}:</p>
 
{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details}

<p>Uma nova chamada da classe {@code TitlesFragment}, ou seja, se o usurio clicar em um item de lista
e o layout original <em>no</em> incluir a vista {@code R.id.details} (a que
{@code DetailsFragment} pertence), o aplicativo iniciar a atividade {@code DetailsActivity}
para exibir o contedo do item.</p>

<p>A seguir h {@code DetailsActivity}, que simplesmente embute {@code DetailsFragment} para exibir
o resumo da pea selecionada quando a tela est na orientao de retrato:</p>

{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java
details_activity}
 
<p>Observe que esta atividade finaliza-se se a configurao for de paisagem,
pois a atividade principal pode tomar o controle e exibir {@code DetailsFragment} juntamente com {@code TitlesFragment}.
Isto pode acontecer se o usurio iniciar {@code DetailsActivity} enquanto estiver na orientao de retrato,
mas alternar para orientao de paisagem (o que reinicia a atividade atual).</p>


<p>Para obter mais exemplos do uso de fragmentos (e arquivos fonte completos deste exemplo),
consulte o aplicativo de exemplo API Demos disponvel em <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
ApiDemos</a> (disponvel para download em <a href="{@docRoot}resources/samples/get.html">Exemplos de componentes do SDK</a>).</p>