topics/resources/runtime-changes.jd

page.title=Tratar alteraes no tempo de execuo
page.tags=atividade,ciclo de vida
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>Neste documento</h2>
  <ol>
    <li><a href="#RetainingAnObject">Reteno de um objeto durante uma alterao de configurao</a></li>
    <li><a href="#HandlingTheChange">Tratar voc mesmo da alterao de configurao</a>
  </ol>

  <h2>Veja tambm</h2>
  <ol>
    <li><a href="providing-resources.html">Fornecimento de recursos</a></li>
    <li><a href="accessing-resources.html">Acesso aos recursos</a></li>
    <li><a href="http://android-developers.blogspot.com/2009/02/faster-screen-orientation-change.html">Alterao
mais rpida da orientao da tela</a></li>
  </ol>
</div>
</div>

<p>Algumas configuraes do dispositivo podem mudar durante o tempo de execuo
(como orientao de tela, disponibilidade do teclado e idioma). Quando ocorre uma alterao,
o Android precisa reiniciar a execuo
de {@link android.app.Activity} ({@link android.app.Activity#onDestroy()}  chamado, seguido de {@link
android.app.Activity#onCreate(Bundle) onCreate()}). O comportamento de reincio foi projetado para ajudar
o aplicativo a se adaptar a novas configuraes recarregando automaticamente o aplicativo
com recursos alternativos que correspondam com a configurao do dispositivo.</p>

<p>Para tratar adequadamente um reincio,  importante que a atividade se restaure
ao estado anterior por meio do <a href="{@docRoot}guide/components/activities.html#Lifecycle">ciclo de vida
da atividade</a>, no qual o Android chama
{@link android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} antes de destruir
a atividade para que seja possvel salvar os dados acerca do estado do aplicativo. Em seguida,  possvel restaurar o estado
durante {@link android.app.Activity#onCreate(Bundle) onCreate()} ou {@link
android.app.Activity#onRestoreInstanceState(Bundle) onRestoreInstanceState()}.</p>

<p>Para testar se o aplicativo se reinicia com o estado de aplicativo intacto, deve-se
invocar as alteraes de configurao (como alteraes na orientao da tela) enquanto executa diversas
tarefas no aplicativo. O aplicativo deve ser capaz de reiniciar a qualquer momento sem perda
de dados do usurio ou estado para tratar eventos como alteraes de configurao ou quando o usurio recebe
uma chamada telefnica e, em seguida, retorna ao aplicativo bem depois
de destrudo o processo do aplicativo. Para ver como restaurar o estado da atividade, leia sobre o <a href="{@docRoot}guide/components/activities.html#Lifecycle">Ciclo de vida da atividade</a>.</p>

<p>No entanto, pode-se encontrar uma situao em que o reincio do aplicativo
e a restaurao representem quantidades significativas de dados que podem ser custosos e prejudicar a experincia do usurio. Nessa situao,
temos duas opes:</p>

<ol type="a">
  <li><a href="#RetainingAnObject">Reter um objeto durante uma alterao de configurao</a>
  <p>Permita que a atividade reinicie quando uma configurao muda, mas transporte um objeto
de estado para a nova instncia da atividade.</p>

  </li>
  <li><a href="#HandlingTheChange">Tratar voc mesmo da alterao de configurao</a>
  <p>Evite que o sistema reinicie a atividade durante certas alteraes
de configurao, mas receba um retorno de chamada quando as configuraes se alteram, para que voc atualize manualmente
a atividade conforme necessrio.</p>
  </li>
</ol>


<h2 id="RetainingAnObject">Reteno de um objeto durante uma alterao de configurao</h2>

<p>Se a reteno da atividade exigir a recuperao de grandes conjuntos de dados, restabelecer uma conexo
de rede ou executar outras operaes intensivas, um reincio completo devido a uma alterao
de configurao pode prejudicar a experincia do usurio. Alm disso, pode no ser possvel restaurar completamente
o estado da atividade com o {@link android.os.Bundle} que o sistema salva com o retorno de chamada {@link
android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} &mdash; ele
no foi projetado para transportar objetos grandes (como bitmaps) e os dados contidos devem ser serializados
e, em seguida, desserializados, o que pode consumir muita memria e retardar a alterao de configurao. Nesse caso,
para aliviar o peso de reinicializar a atividade, pode-se reter um {@link
android.app.Fragment} quando a atividade for reiniciada devido a uma alterao de configurao. Esse fragmento
pode conter referncias a objetos com estado que seja preciso reter.</p>

<p>Quando o sistema Android encerra a atividade devido a uma alterao de configurao, os fragmentos
da atividade marcados para serem retidos no so destrudos.  possvel adicionar esses fragmentos
 atividade para preservar objetos de estado.</p>

<p>Para reter objetos de estado em um fragmento durante uma alterao de configurao em tempo de execuo:</p>

<ol>
  <li>Estenda a classe {@link android.app.Fragment} e declare referncias aos objetos
de estado.</li>
  <li>Chame {@link android.app.Fragment#setRetainInstance(boolean)} quando o fragmento for criado.
      </li>
  <li>Acrescente o fragmento  atividade.</li>
  <li>Use {@link android.app.FragmentManager} para recuperar o fragmento quando a atividade for
reiniciada.</li>
</ol>

<p>Por exemplo: defina o fragmento da seguinte forma:</p>

<pre>
public class RetainedFragment extends Fragment {

    // data object we want to retain
    private MyDataObject data;

    // this method is only called once for this fragment
    &#64;Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // retain this fragment
        setRetainInstance(true);
    }

    public void setData(MyDataObject data) {
        this.data = data;
    }

    public MyDataObject getData() {
        return data;
    }
}
</pre>

<p class="caution"><strong>Ateno:</strong> ao restaurar qualquer objeto,
no se deve nunca passar um objeto vinculado a {@link android.app.Activity}, como um {@link
android.graphics.drawable.Drawable}, um {@link android.widget.Adapter}, um {@link android.view.View}
ou qualquer outro objeto associado a um {@link android.content.Context}. Se o fizer,
ele vazar todas as vistas e recursos da instncia da atividade original (vazar recursos
significa que o aplicativo mantm a reteno deles, que no podem ser recolhidos, o que
causa perda de memria).</p>

<p>Em seguida, use {@link android.app.FragmentManager} para adicionar o fragmento  atividade.
 possvel obter o objeto de dados do fragmento quando a atividade reiniciar durante as alteraes
de configurao em tempo de execuo. Por exemplo: defina a atividade da seguinte forma:</p>

<pre>
public class MyActivity extends Activity {

    private RetainedFragment dataFragment;

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

        // find the retained fragment on activity restarts
        FragmentManager fm = getFragmentManager();
        dataFragment = (DataFragment) fm.findFragmentByTag(data);

        // create the fragment and data the first time
        if (dataFragment == null) {
            // add the fragment
            dataFragment = new DataFragment();
            fm.beginTransaction().add(dataFragment, data).commit();
            // load the data from the web
            dataFragment.setData(loadMyData());
        }

        // the data is available in dataFragment.getData()
        ...
    }

    &#64;Override
    public void onDestroy() {
        super.onDestroy();
        // store the data in the fragment
        dataFragment.setData(collectMyLoadedData());
    }
}
</pre>

<p>Nesse exemplo, {@link android.app.Activity#onCreate(Bundle) onCreate()} adiciona um fragmento
ou restaura uma referncia a ele. {@link android.app.Activity#onCreate(Bundle) onCreate()} tambm
armazena o objeto de estado dentro da instncia de fragmento.
{@link android.app.Activity#onDestroy() onDestroy()} atualiza o objeto de estado dentro
da instncia de fragmento retida.</p>


<h2 id="HandlingTheChange">Tratar voc mesmo da alterao de configurao</h2>

<p>Se o aplicativo no tiver que atualizar recursos durante uma alterao de configurao especfica
<em>e</em> se houver alguma limitao de desempenho que
impea a atividade de reiniciar, pode-se declarar que a atividade trata ela mesma da alterao de configurao,
o que evita que o sistema reinicie a atividade.</p>

<p class="note"><strong>Observao:</strong> Tratar voc mesmo da alterao de configurao
pode dificultar muito o uso de recursos alternativos, pois o sistema no os aplicar
automaticamente. Esta tcnica deve ser considerada um ltimo recurso, quando  preciso evitar reincios
devido a uma alterao de configurao e no  recomendada para a maioria dos aplicativos.</p>

<p>Para declarar que a atividade manipula uma alterao de configurao, edite o elemento <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
apropriado no arquivo de manifesto para que inclua o atributo <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
android:configChanges}</a> com um valor que represente a configurao
a tratar. Os valores possveis esto listados na documentao do atributo <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
android:configChanges}</a> (os valores mais comumente usados so {@code "orientation"}, para
impedir reincios durante alteraes na orientao da tela, e {@code "keyboardHidden"} para impedir
reincios quando a disponibilidade do teclado muda).  Para declarar vrios valores de configurao
no atributo, usa-se um separador na forma de caractere barra reta {@code |}.</p>

<p>Por exemplo: o cdigo de manifesto a seguir declara uma atividade que trata tanto
da alterao de orientao da tela quanto da disponibilidade do teclado:</p>

<pre>
&lt;activity android:name=".MyActivity"
          android:configChanges="orientation|keyboardHidden"
          android:label="@string/app_name">
</pre>

<p>Agora, quando uma dessas configuraes mudar, {@code MyActivity} no reiniciar.
Em vez disso, a {@code MyActivity} recebe uma chamada para {@link
android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. Um objeto
{@link android.content.res.Configuration}  passado a esse mtodo e especifica
a nova configurao do dispositivo. Ao ler os campos em {@link android.content.res.Configuration},
pode-se determinar a nova configurao e atualizar os recursos na interface para fazer
as alteraes adequadas. No momento
em que o mtodo  chamado, o objeto {@link android.content.res.Resources} da atividade  atualizado
para retornar recursos com base na nova configurao, o que facilita
a redefinio de elementos da IU sem que o sistema reinicie a atividade.</p>

<p class="caution"><strong>Ateno:</strong> a partir do Android 3.2 (nvel da API 13), <strong>o "tamanho
da tela" tambm muda</strong> quando o dispositivo alterna entre as orientaes retrato
e paisagem. Assim, se voc deseja evitar que o tempo de execuo reinicie devido a uma mudana da orientao
ao desenvolver uma API nvel 13 ou posterior (conforme declarado pelos atributos <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> e <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>),
 preciso incluir o valor {@code "screenSize"} alm do valor {@code
"orientation"}. Ou seja,  preciso declarar {@code
android:configChanges="orientation|screenSize"}. No entanto, se o aplicativo tem como alvo uma API nvel
12 ou inferior, a atividade sempre trata ela mesma a alterao de configurao (essa mudana
de configurao no reinicia a atividade, mesmo em execuo em Android 3.2 ou dispositivo posterior).</p>

<p>Por exemplo: a implementao a seguir {@link
android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()} verifica
a orientao de dispositivo atual:</p>

<pre>
&#64;Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);

    // Checks the orientation of the screen
    if (newConfig.orientation == Configuration.ORIENTATION_LANDSCAPE) {
        Toast.makeText(this, "landscape", Toast.LENGTH_SHORT).show();
    } else if (newConfig.orientation == Configuration.ORIENTATION_PORTRAIT){
        Toast.makeText(this, "portrait", Toast.LENGTH_SHORT).show();
    }
}
</pre>

<p>O objeto {@link android.content.res.Configuration} representa todas as configuraes
atuais, no somente as que foram alteradas. Na maior parte do tempo, no importa como
a configurao foi alterada; basta reatribuir todos os recursos que apresentam alternativas
 configurao que esto sendo tratadas. Por exemplo: como o objeto {@link
android.content.res.Resources} est atualizado, pode-se redefinir
qualquer {@link android.widget.ImageView} com {@link android.widget.ImageView#setImageResource(int)
setImageResource()}
e ser usado o recurso adequado  nova configurao (conforme descrito em <a href="providing-resources.html#AlternateResources">Como fornecer recursos</a>).</p>

<p>Observe que os valores dos campos de {@link
android.content.res.Configuration} so inteiros que correspondem a constantes especficas
da classe {@link android.content.res.Configuration}. Para ver a documentao sobre as constantes
a usar em cada campo, consulte o campo em questo na referncia sobre {@link
android.content.res.Configuration}.</p>

<p class="note"><strong>Lembre-se:</strong> ao declarar a atividade para tratar uma alterao
de configurao, voc  responsvel por redefinir todos os elementos que fornecem alternativas. Se voc
declarar a atividade para tratar a alterao de orientao e tiver imagens que alterariam
entre paisagem e retrato,  preciso reatribuir cada recurso a cada elemento durante {@link
android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}.</p>

<p>Se no for necessrio atualizar o aplicativo com base nessas alteraes
de configurao, pode-se <em>no</em> implementar {@link
android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. Nesse
caso, todos os recursos usados antes da alterao de configurao ainda so usados
e somente o reincio da atividade  evitado. No entanto, o aplicativo deve sempre ser capaz
de se encerrar e reiniciar com seu estado anterior intacto, portanto essa tcnica no deve
ser considerada uma fuga da reteno do estado durante o ciclo de vida normal da atividade, No somente porque
h outras alteraes de configurao impossveis de evitar que reiniciem o aplicativo,
mas tambm porque devem-se tratar eventos como o do usurio que sai do aplicativo e ele  destrudo
antes de o usurio voltar a ele.</p>

<p>Para obter mais informaes sobre as alteraes de configurao que devem ser tratadas na atividade, consulte a documentao sobre <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
android:configChanges}</a> e a classe
{@link android.content.res.Configuration}.</p>