1 page.title=Configuraes 2 page.tags=preferncia,preferenceactivity,preferencefragment 3 4 @jd:body 5 6 7 <div id="qv-wrapper"> 8 <div id="qv"> 9 10 <h2>Neste documento</h2> 11 <ol> 12 <li><a href="#Overview">Viso geral</a> 13 <ol> 14 <li><a href="#SettingTypes">Preferncias</a></li> 15 </ol> 16 </li> 17 <li><a href="#DefiningPrefs">Definio de preferncias em XML</a> 18 <ol> 19 <li><a href="#Groups">Criao de grupos de configurao</a></li> 20 <li><a href="#Intents">Uso de intenes</a></li> 21 </ol> 22 </li> 23 <li><a href="#Activity">Criao de uma atividade de preferncia</a></li> 24 <li><a href="#Fragment">Uso de fragmentos de preferncia</a></li> 25 <li><a href="#Defaults">Configurao de valores padro</a></li> 26 <li><a href="#PreferenceHeaders">Uso de cabealhos de preferncia</a> 27 <ol> 28 <li><a href="#CreateHeaders">Criao do arquivo de cabealhos</a></li> 29 <li><a href="#DisplayHeaders">Exibio de cabealhos</a></li> 30 <li><a href="#BackCompatHeaders">Compatibilidade de verses mais antigas com cabealhos de preferncia</a></li> 31 </ol> 32 </li> 33 <li><a href="#ReadingPrefs">Leitura de preferncias</a> 34 <ol> 35 <li><a href="#Listening">Escuta de alteraes de preferncia</a></li> 36 </ol> 37 </li> 38 <li><a href="#NetworkUsage">Gerenciamento de uso de rede</a></li> 39 <li><a href="#Custom">Composio de uma preferncia personalizada</a> 40 <ol> 41 <li><a href="#CustomSelected">Especificao da interface do usurio</a></li> 42 <li><a href="#CustomSave">Salvamento do valor da configurao</a></li> 43 <li><a href="#CustomInitialize">Inicializao do valor atual</a></li> 44 <li><a href="#CustomDefault">Fornecimento de um valor padro</a></li> 45 <li><a href="#CustomSaveState">Salvamento e restaurao do estado da preferncia</a></li> 46 </ol> 47 </li> 48 </ol> 49 50 <h2>Classes principais</h2> 51 <ol> 52 <li>{@link android.preference.Preference}</li> 53 <li>{@link android.preference.PreferenceActivity}</li> 54 <li>{@link android.preference.PreferenceFragment}</li> 55 </ol> 56 57 58 <h2>Veja tambm</h2> 59 <ol> 60 <li><a href="{@docRoot}design/patterns/settings.html">Guia de projeto de configuraes</a></li> 61 </ol> 62 </div> 63 </div> 64 65 66 67 68 <p>Geralmente os aplicativos contm configuraes que permitem aos usurios modificar caractersticas e comportamentos do aplicativo. Por 69 exemplo: alguns aplicativos permitem aos usurios especificar se as notificaes esto ativadas ou especificar a frequncia 70 com que o aplicativo sincroniza dados com a nuvem.</p> 71 72 <p>Para fornecer configuraes ao aplicativo, preciso usar 73 as APIs {@link android.preference.Preference} do Android para programar uma interface coerente 74 com a experincia do usurio em outros aplicativos Android (inclusive as configuraes do sistema). Este documento descreve 75 como programar as configuraes do aplicativo por meio de APIs {@link android.preference.Preference}.</p> 76 77 <div class="note design"> 78 <p><strong>Projeto de configuraes</strong></p> 79 <p>Para obter mais informaes sobre o projeto de configuraes, leia o guia de projeto <a href="{@docRoot}design/patterns/settings.html">Configuraes</a>.</p> 80 </div> 81 82 83 <img src="{@docRoot}images/ui/settings/settings.png" alt="" width="435" /> 84 <p class="img-caption"><strong>Figura 1.</strong> Capturas de tela das configuraes do aplicativo Mensagens 85 do Android. A seleo de um item definido por uma {@link android.preference.Preference} 86 abre uma interface para alterar a configurao.</p> 87 88 89 90 91 <h2 id="Overview">Viso geral</h2> 92 93 <p>Em vez de usar objetos {@link android.view.View} para criar a interface do usurio, as configuraes 94 so criadas por meio de vrias subclasses da classe {@link android.preference.Preference} 95 declaradas em um arquivo XML.</p> 96 97 <p>Os objetos {@link android.preference.Preference} so as peas fundamentais de uma nica 98 configurao. Cada {@link android.preference.Preference} aparece como um item em uma lista e oferece a IU 99 adequada para que os usurios modifiquem a configurao. Por exemplo: uma {@link 100 android.preference.CheckBoxPreference} cria um item de lista que exibe uma caixa de seleo e uma {@link 101 android.preference.ListPreference} cria um item que abre uma caixa de dilogo com uma lista de opes.</p> 102 103 <p>Cada {@link android.preference.Preference} adicionada tem um par de valor-chave correspondente 104 que o sistema usa para salvar a configurao em um arquivo 105 {@link android.content.SharedPreferences} padro para as configuraes do aplicativo. Quando o usurio altera uma configurao, o sistema atualiza o valor 106 correspondente no arquivo {@link android.content.SharedPreferences}. O nico momento em que 107 se deve interagir diretamente com o arquivo {@link android.content.SharedPreferences} associado 108 no momento de ler o valor para determinar o comportamento do aplicativo com base na configurao do usurio.</p> 109 110 <p>O valor salvo em {@link android.content.SharedPreferences} para cada configurao pode ser 111 um dos seguintes tipos de dados:</p> 112 113 <ul> 114 <li>Boolean</li> 115 <li>Float</li> 116 <li>Int</li> 117 <li>Long</li> 118 <li>String</li> 119 <li>String {@link java.util.Set}</li> 120 </ul> 121 122 <p>Como a IU de configuraes do aplicativo criada com objetos {@link android.preference.Preference} 123 em vez de objetos 124 {@link android.view.View}, preciso usar uma subclasse {@link android.app.Activity} ou 125 {@link android.app.Fragment} especializada para exibir as configuraes de lista:</p> 126 127 <ul> 128 <li>Se o aplicativo for compatvel com verses do Android anteriores 3.0 (nvel da API 10 ou anterior), ser 129 necessrio criar a atividade como uma extenso da classe {@link android.preference.PreferenceActivity}.</li> 130 <li>No Android 3.0 ou verses posteriores, deve-se usar um {@link android.app.Activity} tradicional 131 que hospeda um {@link android.preference.PreferenceFragment} que exige as configuraes do aplicativo. 132 No entanto, pode-se tambm usar {@link android.preference.PreferenceActivity} para criar um layout de dois painis 133 para telas maiores quando h vrios grupos de configuraes.</li> 134 </ul> 135 136 <p>Veja como configurar a {@link android.preference.PreferenceActivity} e instncias de {@link 137 android.preference.PreferenceFragment} nas sees sobre a <a href="#Activity">Criao de uma atividade de preferncia</a> e <a href="#Fragment">Uso 138 de fragmentos de preferncia</a>.</p> 139 140 141 <h3 id="SettingTypes">Preferncias</h3> 142 143 <p>Toda configurao do aplicativo representada por uma subclasse especfica da classe {@link 144 android.preference.Preference}. Cada subclasse contm um conjunto de propriedades essenciais que permitem 145 especificar itens como o ttulo da configurao e o valor padro. Cada subclasse tambm oferece 146 suas propriedades e interface do usurio especializadas. Por exemplo: a figura 1 ilustra uma captura de tela 147 das configuraes do aplicativo Mensagens. Cada item de lista na tela de configuraes tem, como fundo, um objeto {@link 148 android.preference.Preference} diferente.</p> 149 150 <p>A seguir h algumas das preferncias mais comuns:</p> 151 152 <dl> 153 <dt>{@link android.preference.CheckBoxPreference}</dt> 154 <dd>Exibe um item com uma caixa de seleo para uma configurao que esteja ativada ou desativada. O valor 155 salvo um booleano (<code>true</code> se estiver selecionada).</dd> 156 157 <dt>{@link android.preference.ListPreference}</dt> 158 <dd>Abre uma caixa de dilogo com uma lista de botes de opo. O valor salvo 159 pode ser qualquer um dos tipos de valor compatveis (listados acima).</dd> 160 161 <dt>{@link android.preference.EditTextPreference}</dt> 162 <dd>Abre uma caixa de dilogo com um widget {@link android.widget.EditText}. O valor salvo um {@link 163 java.lang.String}.</dd> 164 </dl> 165 166 <p>Consulte a classe {@link android.preference.Preference} para ver uma lista de todas as outras subclasses e 167 as propriedades correspondentes.</p> 168 169 <p> claro que as classes embutidas no acomodam todas as necessidades e o aplicativo pode exigir 170 algo mais especializado. Por exemplo: a plataforma atualmente no fornece nenhuma classe {@link 171 android.preference.Preference} para selecionar um nmero ou data. Portanto, pode ser necessrio definir 172 a prpria subclasse {@link android.preference.Preference}. Veja mais informaes na seo sobre <a href="#Custom">Composio de uma preferncia personalizada</a>.</p> 173 174 175 176 <h2 id="DefiningPrefs">Definio de preferncias em XML</h2> 177 178 <p>Embora se possa instanciar novos objetos {@link android.preference.Preference} em tempo de execuo, 179 deve-se definir uma lista de configuraes no XML com uma hierarquia 180 de objetos {@link android.preference.Preference}. Recomenda-se o uso de um arquivo XML para definir a coleo de configuraes porque o arquivo 181 oferece uma estrutura fcil de ler e simples de atualizar. Alm disso, as configuraes do aplicativo 182 geralmente so predeterminadas, embora ainda seja possvel modificar a coleo em tempo de execuo.</p> 183 184 <p>Cada subclasse {@link android.preference.Preference} pode ser declarada com um elemento XML 185 correspondente ao nome da classe, como {@code <CheckBoxPreference>}.</p> 186 187 <p> preciso salvar o arquivo XML no diretrio {@code res/xml/}. Embora seja possvel nomear livremente 188 o arquivo, mais frequente v-lo com o nome {@code preferences.xml}. Geralmente s necessrio um arquivo 189 porque as ramificaes na hierarquia (que abrem sua prpria lista de configuraes) so declaradas 190 por meio de instncias aninhadas de {@link android.preference.PreferenceScreen}.</p> 191 192 <p class="note"><strong>Observao:</strong> se voc deseja criar um layout de vrios painis 193 para as configuraes, sero necessrios arquivos XML separados para cada fragmento.</p> 194 195 <p>O n raiz do arquivo XML deve ser um elemento {@link android.preference.PreferenceScreen 196 <PreferenceScreen>}. dentro desse elemento que se adiciona cada {@link 197 android.preference.Preference}. Cada filho adicionado dentro do elemento 198 {@link android.preference.PreferenceScreen <PreferenceScreen>} exibido com um item 199 nico na lista de configuraes.</p> 200 201 <p>Por exemplo:</p> 202 203 <pre> 204 <?xml version="1.0" encoding="utf-8"?> 205 <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> 206 <CheckBoxPreference 207 android:key="pref_sync" 208 android:title="@string/pref_sync" 209 android:summary="@string/pref_sync_summ" 210 android:defaultValue="true" /> 211 <ListPreference 212 android:dependency="pref_sync" 213 android:key="pref_syncConnectionType" 214 android:title="@string/pref_syncConnectionType" 215 android:dialogTitle="@string/pref_syncConnectionType" 216 android:entries="@array/pref_syncConnectionTypes_entries" 217 android:entryValues="@array/pref_syncConnectionTypes_values" 218 android:defaultValue="@string/pref_syncConnectionTypes_default" /> 219 </PreferenceScreen> 220 </pre> 221 222 <p>Nesse exemplo, existe um {@link android.preference.CheckBoxPreference} e um {@link 223 android.preference.ListPreference}. Os dois itens contm estes trs atributos:</p> 224 225 <dl> 226 <dt>{@code android:key}</dt> 227 <dd>Esse atributo necessrio para preferncias que persistem a um valor de dados. Ele especifica a chave 228 exclusiva (uma string) que o sistema usa ao salvar o valor dessa configurao em {@link 229 android.content.SharedPreferences}. 230 <p>As nicas instncias em que esse atributo <em>dispensvel</em> ocorrem quando a preferncia um 231 {@link android.preference.PreferenceCategory} ou {@link android.preference.PreferenceScreen}, 232 ou quando a preferncia especifica um {@link android.content.Intent} para invocar (com um elemento <a href="#Intents">{@code <intent>}</a>) ou um {@link android.app.Fragment} para exibir (com um atributo <a href="{@docRoot}reference/android/preference/Preference.html#attr_android:fragment">{@code 233 android:fragment}</a>).</p> 234 </dd> 235 <dt>{@code android:title}</dt> 236 <dd>Fornece configurao um nome visvel ao usurio.</dd> 237 <dt>{@code android:defaultValue}</dt> 238 <dd>Especifica o valor inicial que o sistema deve definir no arquivo {@link 239 android.content.SharedPreferences}. Deve-se fornecer um valor padro para 240 todas as configuraes.</dd> 241 </dl> 242 243 <p>Para mais informaes sobre todos os outros atributos compatveis, consulte a documentao {@link 244 android.preference.Preference} (e subclasse respectiva).</p> 245 246 247 <div class="figure" style="width:300px"> 248 <img src="{@docRoot}images/ui/settings/settings-titles.png" alt="" /> 249 <p class="img-caption"><strong>Figura 2.</strong> Definio de categorias 250 com ttulos. <br/><b>1.</b> A categoria especificada pelo elemento {@link 251 android.preference.PreferenceCategory <PreferenceCategory>}. <br/><b>2.</b> O ttulo 252 especificado com o atributo {@code android:title}.</p> 253 </div> 254 255 256 <p>Quando a lista de configuraes excede cerca de 10 itens, pode ser necessrio adicionar ttulos 257 para definir grupos de configuraes ou exibir esses grupos 258 em uma tela separada. Essas opes so descritas nas sees a seguir.</p> 259 260 261 <h3 id="Groups">Criao de grupos de configurao</h3> 262 263 <p>Se voc apresentar uma lista de 10 ou mais configuraes, 264 os usurios podem ter dificuldade de percorr-las, compreend-las e process-las. Para solucionar isso, 265 pode-se dividir algumas ou todas as configuraes em grupos, transformando uma longa lista 266 em vrias listas mais curtas. Um grupo de configuraes relacionadas pode ser apresentado de uma das seguintes formas:</p> 267 268 <ul> 269 <li><a href="#Titles">Uso de ttulos</a></li> 270 <li><a href="#Subscreens">Uso de subtelas</a></li> 271 </ul> 272 273 <p>Pode-se usar uma ou ambas as tcnicas de agrupamento para organizar as configuraes do aplicativo. Ao decidir 274 qual delas usar e como dividir as configuraes, deve-se seguir as diretrizes do guia 275 <a href="{@docRoot}design/patterns/settings.html">Configuraes</a> de Projeto do Android.</p> 276 277 278 <h4 id="Titles">Uso de ttulos</h4> 279 280 <p>Para usar divisores com cabealhos entre grupos de configuraes (como ilustrado na figura 2), 281 coloca-se cada grupo de objetos {@link android.preference.Preference} dentro de {@link 282 android.preference.PreferenceCategory}.</p> 283 284 <p>Por exemplo:</p> 285 286 <pre> 287 <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> 288 <PreferenceCategory 289 android:title="@string/pref_sms_storage_title" 290 android:key="pref_key_storage_settings"> 291 <CheckBoxPreference 292 android:key="pref_key_auto_delete" 293 android:summary="@string/pref_summary_auto_delete" 294 android:title="@string/pref_title_auto_delete" 295 android:defaultValue="false"... /> 296 <Preference 297 android:key="pref_key_sms_delete_limit" 298 android:dependency="pref_key_auto_delete" 299 android:summary="@string/pref_summary_delete_limit" 300 android:title="@string/pref_title_sms_delete"... /> 301 <Preference 302 android:key="pref_key_mms_delete_limit" 303 android:dependency="pref_key_auto_delete" 304 android:summary="@string/pref_summary_delete_limit" 305 android:title="@string/pref_title_mms_delete" ... /> 306 </PreferenceCategory> 307 ... 308 </PreferenceScreen> 309 </pre> 310 311 312 <h4 id="Subscreens">Uso de subtelas</h4> 313 314 <p>Para usar grupos de configuraes em uma subtela (como ilustrado na figura 3), coloque o grupo 315 de objetos {@link android.preference.Preference} dentro de {@link 316 android.preference.PreferenceScreen}.</p> 317 318 <img src="{@docRoot}images/ui/settings/settings-subscreen.png" alt="" /> 319 <p class="img-caption"><strong>Figura 3.</strong> Subtelas de configurao. O elemento {@code 320 <PreferenceScreen>} cria 321 um item que, quando selecionado, abre uma lista separada para exibir as configuraes aninhadas.</p> 322 323 <p>Por exemplo:</p> 324 325 <pre> 326 <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> 327 <!-- opens a subscreen of settings --> 328 <PreferenceScreen 329 android:key="button_voicemail_category_key" 330 android:title="@string/voicemail" 331 android:persistent="false"> 332 <ListPreference 333 android:key="button_voicemail_provider_key" 334 android:title="@string/voicemail_provider" ... /> 335 <!-- opens another nested subscreen --> 336 <PreferenceScreen 337 android:key="button_voicemail_setting_key" 338 android:title="@string/voicemail_settings" 339 android:persistent="false"> 340 ... 341 </PreferenceScreen> 342 <RingtonePreference 343 android:key="button_voicemail_ringtone_key" 344 android:title="@string/voicemail_ringtone_title" 345 android:ringtoneType="notification" ... /> 346 ... 347 </PreferenceScreen> 348 ... 349 </PreferenceScreen> 350 </pre> 351 352 353 <h3 id="Intents">Uso de intenes</h3> 354 355 <p>Em alguns casos, pode ser necessrio que um item de preferncia abra em um atividade diferente 356 e no na tela de configurao, como um navegador da web para exibir uma pgina da web. Para invocar um {@link 357 android.content.Intent} quando o usurio seleciona um item de preferncia, adicione um elemento {@code <intent>} 358 como filho do elemento {@code <Preference>} correspondente.</p> 359 360 <p>Por exemplo, a seguir apresenta-se como usar um item de preferncia para abrir uma pgina da web:</p> 361 362 <pre> 363 <Preference android:title="@string/prefs_web_page" > 364 <intent android:action="android.intent.action.VIEW" 365 android:data="http://www.example.com" /> 366 </Preference> 367 </pre> 368 369 <p> possvel criar intenes implcitas e explcitas usando os seguintes atributos:</p> 370 371 <dl> 372 <dt>{@code android:action}</dt> 373 <dd>A ao a atribuir, conforme o mtodo {@link android.content.Intent#setAction setAction()}. 374 </dd> 375 <dt>{@code android:data}</dt> 376 <dd>Os dados a atribuir, conforme o mtodo {@link android.content.Intent#setData setData()}.</dd> 377 <dt>{@code android:mimeType}</dt> 378 <dd>O tipo MIME atribuir, conforme o mtodo {@link android.content.Intent#setType setType()}. 379 </dd> 380 <dt>{@code android:targetClass}</dt> 381 <dd>A parte de classe do nome do componente, conforme o mtodo {@link android.content.Intent#setComponent 382 setComponent()}.</dd> 383 <dt>{@code android:targetPackage}</dt> 384 <dd>A parte de pacote do nome do componente, conforme o mtodo {@link 385 android.content.Intent#setComponent setComponent()}.</dd> 386 </dl> 387 388 389 390 <h2 id="Activity">Criao de uma atividade de preferncia</h2> 391 392 <p>Para exibir as configuraes em uma atividade, estenda a classe {@link 393 android.preference.PreferenceActivity}. uma extenso da classe tradicional {@link 394 android.app.Activity} que exibe uma lista de configuraes com base em uma hierarquia de objetos {@link 395 android.preference.Preference}. A {@link android.preference.PreferenceActivity} 396 automaticamente persiste s configuraes associadas a cada {@link 397 android.preference.Preference} quando o usurio faz uma alterao.</p> 398 399 <p class="note"><strong>Observao:</strong> ao desenvolver um aplicativo para Android 3.0 400 ou superior, deve-se usar o {@link android.preference.PreferenceFragment}. Consulte a prxima 401 seo sobre o <a href="#Fragment">Uso de fragmentos de preferncia</a>.</p> 402 403 <p>O mais importante no carregar um layout de vistas durante o retorno de chamada {@link 404 android.preference.PreferenceActivity#onCreate onCreate()}. Em vez disso, chama-se {@link 405 android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} 406 para adicionar atividade as preferncias declaradas em um arquivo XML. Por exemplo: abaixo h o cdigo mnimo 407 necessrio para um {@link android.preference.PreferenceActivity} funcional:</p> 408 409 <pre> 410 public class SettingsActivity extends PreferenceActivity { 411 @Override 412 public void onCreate(Bundle savedInstanceState) { 413 super.onCreate(savedInstanceState); 414 addPreferencesFromResource(R.xml.preferences); 415 } 416 } 417 </pre> 418 419 <p>Na verdade, esse cdigo suficiente para alguns aplicativos porque, assim que o usurio modifica uma preferncia, 420 o sistema salva as alteraes em um arquivo padro {@link android.content.SharedPreferences} 421 que os componentes do outro aplicativo poder ler quando for necessrio verificar as configuraes do usurio. No entanto, 422 muitos aplicativos exigem um pouco mais de cdigo para escutar as alteraes que ocorrem nas preferncias. 423 Para informaes sobre a escuda de alteraes no arquivo {@link android.content.SharedPreferences}, 424 consulte a seo sobre <a href="#ReadingPrefs">Leitura de preferncias</a>.</p> 425 426 427 428 429 <h2 id="Fragment">Uso de fragmentos de preferncia</h2> 430 431 <p>Ao desenvolver para Android 3.0 (nvel da API 11) ou verses posteriores, deve-se usar um {@link 432 android.preference.PreferenceFragment} para exibir a lista de objetos {@link android.preference.Preference}. 433 Pode-se adicionar um {@link android.preference.PreferenceFragment} a qualquer atividade — no 434 necessrio usar {@link android.preference.PreferenceActivity}.</p> 435 436 <p>Os <a href="{@docRoot}guide/components/fragments.html">fragmentos</a> permitem uma arquitetura 437 mais flexvel para o aplicativo em comparao com o uso de apenas atividades para qualquer 438 tipo de atividade criada. Assim, sugerimos usar {@link 439 android.preference.PreferenceFragment} para controlar a exibio das configuraes em vez de {@link 440 android.preference.PreferenceActivity} sempre que possvel.</p> 441 442 <p>A implementao de {@link android.preference.PreferenceFragment} pode ser to simples 443 quanto definir o mtodo {@link android.preference.PreferenceFragment#onCreate onCreate()} para carregar 444 um arquivo de preferncias com {@link android.preference.PreferenceFragment#addPreferencesFromResource 445 addPreferencesFromResource()}. Por exemplo:</p> 446 447 <pre> 448 public static class SettingsFragment extends PreferenceFragment { 449 @Override 450 public void onCreate(Bundle savedInstanceState) { 451 super.onCreate(savedInstanceState); 452 453 // Load the preferences from an XML resource 454 addPreferencesFromResource(R.xml.preferences); 455 } 456 ... 457 } 458 </pre> 459 460 <p> possvel adicionar esse fragmento a um {@link android.app.Activity} como se faria com qualquer outro 461 {@link android.app.Fragment}. Por exemplo:</p> 462 463 <pre> 464 public class SettingsActivity extends Activity { 465 @Override 466 protected void onCreate(Bundle savedInstanceState) { 467 super.onCreate(savedInstanceState); 468 469 // Display the fragment as the main content. 470 getFragmentManager().beginTransaction() 471 .replace(android.R.id.content, new SettingsFragment()) 472 .commit(); 473 } 474 } 475 </pre> 476 477 <p class="note"><strong>Observao:</strong> um {@link android.preference.PreferenceFragment} no tem 478 seu prprio objeto {@link android.content.Context}. Se for necessrio um objeto {@link android.content.Context} 479 , possvel chamar {@link android.app.Fragment#getActivity()}. No entanto, tome cuidado para chamar 480 {@link android.app.Fragment#getActivity()} somente quando o fragmento estiver anexado a uma atividade. Quando 481 o fragmento ainda no estiver anexado, ou tiver sido separado durante o fim do seu ciclo de vida, {@link 482 android.app.Fragment#getActivity()} retornar como nulo.</p> 483 484 485 <h2 id="Defaults">Configurao de valores padro</h2> 486 487 <p>As preferncias criadas provavelmente definem alguns comportamentos importantes do aplicativo, portanto 488 necessrio inicializar o arquivo {@link android.content.SharedPreferences} associado 489 com os valores padro de cada {@link android.preference.Preference} quando o usurio abre o aplicativo 490 pela primeira vez.</p> 491 492 <p>A primeira coisa a fazer especificar o valor padro de cada objeto {@link 493 android.preference.Preference} 494 no arquivo XML com o atributo {@code android:defaultValue}. O valor pode ser qualquer tipo de dados 495 apropriado para o objeto {@link android.preference.Preference} correspondente. Por 496 exemplo:</p> 497 498 <pre> 499 <!-- default value is a boolean --> 500 <CheckBoxPreference 501 android:defaultValue="true" 502 ... /> 503 504 <!-- default value is a string --> 505 <ListPreference 506 android:defaultValue="@string/pref_syncConnectionTypes_default" 507 ... /> 508 </pre> 509 510 <p>Em seguida, a partir do mtodo {@link android.app.Activity#onCreate onCreate()} na atividade principal 511 do aplicativo — e em qualquer outra atividade pela qual o usurio possa entrar no aplicativo pela 512 primeira vez —, chame {@link android.preference.PreferenceManager#setDefaultValues 513 setDefaultValues()}:</p> 514 515 <pre> 516 PreferenceManager.setDefaultValues(this, R.xml.advanced_preferences, false); 517 </pre> 518 519 <p>Essa chamada durante {@link android.app.Activity#onCreate onCreate()} garante que o aplicativo 520 seja adequadamente inicializado com as configuraes padro, que o aplicativo pode precisar ler 521 para determinar alguns comportamentos (se, por exemplo, baixar dados enquanto estiver 522 em uma rede de celular).</p> 523 524 <p>Esse mtodo usa trs argumentos:</p> 525 <ul> 526 <li>O {@link android.content.Context} do aplicativo.</li> 527 <li>O ID de recurso do arquivo XML de preferncias para o qual voc deseja definir os valores padro.</li> 528 <li>Booleano que indica se os valores padro devem ser definidos mais de uma vez. 529 <p>Quando <code>false</code>, o sistema define os valores paro somente se esse mtodo nunca tiver 530 sido chamado (ou se {@link android.preference.PreferenceManager#KEY_HAS_SET_DEFAULT_VALUES} 531 no arquivo de preferncias compartilhadas do valor padro for falso).</p></li> 532 </ul> 533 534 <p>Enquanto o terceiro argumento estiver definido como <code>false</code>, pode-se chamar esse mtodo com segurana 535 toda vez que a atividade iniciar sem substituir as preferncias salvas do usurio redefinindo-as 536 para os padres. No entanto, se ele for definido como <code>true</code>, todos os valores anteriores 537 sero substitudos pelos padres.</p> 538 539 540 541 <h2 id="PreferenceHeaders">Uso de cabealhos de preferncia</h2> 542 543 <p>Em casos raros, pode ser necessrio projetar as configuraes de forma que a primeira tela 544 exiba somente uma lista de <a href="#Subscreens">subtelas</a> (como as do aplicativo Configuraes 545 conforme ilustrado nas figuras 4 e 5). Ao desenvolver um projeto desse tipo para Android 3.0 ou verso posterior, 546 deve-se usar um novo recurso "cabealhos" no Android 3.0 em vez de criar subtelas com elementos 547 {@link android.preference.PreferenceScreen} aninhados.</p> 548 549 <p>Para criar as configuraes com cabealhos, preciso:</p> 550 <ol> 551 <li>Separar cada grupo de configuraes em instncias separadas de {@link 552 android.preference.PreferenceFragment}. Ou seja, cada grupo de configuraes precisa de um arquivo 553 XML separado.</li> 554 <li>Criar um arquivo XML de cabealhos que lista cada grupo de configuraes e declara que fragmento 555 contm a lista correspondente de configuraes.</li> 556 <li>Estender a classe {@link android.preference.PreferenceActivity} para hospedar as configuraes.</li> 557 <li>Implementar o retorno de chamada {@link 558 android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} para especificar 559 o arquivo de cabealhos.</li> 560 </ol> 561 562 <p>Um grande benefcio de usar esse modelo que {@link android.preference.PreferenceActivity} 563 automaticamente apresenta o layout de dois painis ilustrado na figura 4 ao executar em telas grandes.</p> 564 565 <p>Mesmo se o aplicativo for compatvel com verses de Android anteriores 3.0, possvel programar 566 o aplicativo para usar {@link android.preference.PreferenceFragment} para uma apresentao em dois painis 567 em dispositivos mais novos e ser compatvel com a hierarquia tradicional multitelas 568 em dispositivos mais antigos (veja a seo sobre <a href="#BackCompatHeaders">Compatibilidade de verses 569 mais antigas com cabealhos de preferncia</a>).</p> 570 571 <img src="{@docRoot}images/ui/settings/settings-headers-tablet.png" alt="" /> 572 <p class="img-caption"><strong>Figura 4.</strong> Layout de dois painis com cabealhos. <br/><b>1.</b> Os cabealhos 573 so definidos com um arquivo XML de cabealhos. <br/><b>2.</b> Cada grupo de configuraes definido por um 574 {@link android.preference.PreferenceFragment} especificado por um elemento {@code <header>} 575 no arquivo de cabealhos.</p> 576 577 <img src="{@docRoot}images/ui/settings/settings-headers-handset.png" alt="" /> 578 <p class="img-caption"><strong>Figura 5.</strong> Um dispositivo celular com cabealhos de configurao. Quando 579 um item selecionado o {@link android.preference.PreferenceFragment} associado substitui 580 os cabealhos.</p> 581 582 583 <h3 id="CreateHeaders" style="clear:left">Criao do arquivo de cabealhos</h3> 584 585 <p>Cada grupo de configuraes na lista de cabealhos especificado por um nico elemento {@code <header>} 586 dentro de um elemento raiz {@code <preference-headers>}. Por exemplo:</p> 587 588 <pre> 589 <?xml version="1.0" encoding="utf-8"?> 590 <preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> 591 <header 592 android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentOne" 593 android:title="@string/prefs_category_one" 594 android:summary="@string/prefs_summ_category_one" /> 595 <header 596 android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentTwo" 597 android:title="@string/prefs_category_two" 598 android:summary="@string/prefs_summ_category_two" > 599 <!-- key/value pairs can be included as arguments for the fragment. --> 600 <extra android:name="someKey" android:value="someHeaderValue" /> 601 </header> 602 </preference-headers> 603 </pre> 604 605 <p>Com o atributo {@code android:fragment}, cada cabealho declara uma instncia de {@link 606 android.preference.PreferenceFragment} que deve abrir quando o usurio selecionar o cabealho.</p> 607 608 <p>O elemento {@code <extras>} permite passar os pares de valores-chave para o fragmento em um {@link 609 android.os.Bundle}. O fragmento pode recuperar os argumentos chamando {@link 610 android.app.Fragment#getArguments()}. H vrios motivos para passar argumentos ao fragmento, 611 mas um bom motivo reutilizar a mesma subclasse de {@link 612 android.preference.PreferenceFragment} para cada grupo e usar o argumento para especificar 613 o arquivo XML de preferncias que o fragmento deve carregar.</p> 614 615 <p>Por exemplo, a seguir h um fragmento que pode ser reutilizado em vrios grupos de configuraes, quando 616 cada cabealho define um argumento {@code <extra>} com a chave {@code "settings"}:</p> 617 618 <pre> 619 public static class SettingsFragment extends PreferenceFragment { 620 @Override 621 public void onCreate(Bundle savedInstanceState) { 622 super.onCreate(savedInstanceState); 623 624 String settings = getArguments().getString("settings"); 625 if ("notifications".equals(settings)) { 626 addPreferencesFromResource(R.xml.settings_wifi); 627 } else if ("sync".equals(settings)) { 628 addPreferencesFromResource(R.xml.settings_sync); 629 } 630 } 631 } 632 </pre> 633 634 635 636 <h3 id="DisplayHeaders">Exibio de cabealhos</h3> 637 638 <p>Para exibir os cabealhos de preferncia, preciso implementar o mtodo de retorno de chamada {@link 639 android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} e chamar 640 {@link android.preference.PreferenceActivity#loadHeadersFromResource 641 loadHeadersFromResource()}. Por exemplo:</p> 642 643 <pre> 644 public class SettingsActivity extends PreferenceActivity { 645 @Override 646 public void onBuildHeaders(List<Header> target) { 647 loadHeadersFromResource(R.xml.preference_headers, target); 648 } 649 } 650 </pre> 651 652 <p>Quando o usurio seleciona um item de uma lista de cabealhos, o sistema abre o {@link 653 android.preference.PreferenceFragment} associado.</p> 654 655 <p class="note"><strong>Observao:</strong> ao usar cabealhos de preferncia, a subclasse de {@link 656 android.preference.PreferenceActivity} no precisa implementar o mtodo {@link 657 android.preference.PreferenceActivity#onCreate onCreate()} porque a nica tarefa 658 necessria para a atividade carregar os cabealhos.</p> 659 660 661 <h3 id="BackCompatHeaders">Compatibilidade de verses mais antigas com cabealhos de preferncia</h3> 662 663 <p>Se o aplicativo for compatvel com verses de Android anteriores 3.0, ainda ser possvel usar cabealhos 664 para fornecer um layout em dois painis ao executar no Android 3.0 e verses posteriores. Basta criar um arquivo XML de preferncias 665 adicional que usa elementos bsicos {@link android.preference.Preference 666 <Preference>} que se comportam como os itens de cabealho (para uso das verses mais antigas 667 do Android).</p> 668 669 <p>No entanto, em vez de abrir um novo {@link android.preference.PreferenceScreen}, cada elemento {@link 670 android.preference.Preference <Preference>} envia um {@link android.content.Intent} 671 ao {@link android.preference.PreferenceActivity} que especifica que arquivo XML de preferncia 672 carregar.</p> 673 674 <p>Por exemplo, abaixo h um arquivo XML de cabealhos de preferncia usado no Android 3.0 675 e posterior ({@code res/xml/preference_headers.xml}):</p> 676 677 <pre> 678 <preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> 679 <header 680 android:fragment="com.example.prefs.SettingsFragmentOne" 681 android:title="@string/prefs_category_one" 682 android:summary="@string/prefs_summ_category_one" /> 683 <header 684 android:fragment="com.example.prefs.SettingsFragmentTwo" 685 android:title="@string/prefs_category_two" 686 android:summary="@string/prefs_summ_category_two" /> 687 </preference-headers> 688 </pre> 689 690 <p>E apresenta-se tambm um arquivo de preferncias que fornece os mesmos cabealhos de verses de Android 691 mais antigas que a 3.0 ({@code res/xml/preference_headers_legacy.xml}):</p> 692 693 <pre> 694 <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> 695 <Preference 696 android:title="@string/prefs_category_one" 697 android:summary="@string/prefs_summ_category_one" > 698 <intent 699 android:targetPackage="com.example.prefs" 700 android:targetClass="com.example.prefs.SettingsActivity" 701 android:action="com.example.prefs.PREFS_ONE" /> 702 </Preference> 703 <Preference 704 android:title="@string/prefs_category_two" 705 android:summary="@string/prefs_summ_category_two" > 706 <intent 707 android:targetPackage="com.example.prefs" 708 android:targetClass="com.example.prefs.SettingsActivity" 709 android:action="com.example.prefs.PREFS_TWO" /> 710 </Preference> 711 </PreferenceScreen> 712 </pre> 713 714 <p>Como a compatibilidade com {@code <preference-headers>} foi adicionada no Android 3.0, o sistema chama 715 {@link android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} em seu {@link 716 android.preference.PreferenceActivity} somente ao executar em Androd 3.0 ou posterior. Para carregar 717 o arquivo de cabealhos de legado" ({@code preference_headers_legacy.xml}), preciso verificar a versodo Android 718 e, se a verso for mais antiga que o Android 3.0 ({@link 719 android.os.Build.VERSION_CODES#HONEYCOMB}), chama {@link 720 android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} 721 para carregar o arquivo de cabealho legado. Por exemplo:</p> 722 723 <pre> 724 @Override 725 public void onCreate(Bundle savedInstanceState) { 726 super.onCreate(savedInstanceState); 727 ... 728 729 if (Build.VERSION.SDK_INT < Build.VERSION_CODES.HONEYCOMB) { 730 // Load the legacy preferences headers 731 addPreferencesFromResource(R.xml.preference_headers_legacy); 732 } 733 } 734 735 // Called only on Honeycomb and later 736 @Override 737 public void onBuildHeaders(List<Header> target) { 738 loadHeadersFromResource(R.xml.preference_headers, target); 739 } 740 </pre> 741 742 <p>Depois s resta tratar o {@link android.content.Intent} passado para a atividade 743 para identificar que arquivo de preferncias carregar. Portanto, para recuperar a ao da inteno e compar-la 744 com strings de aes conhecidas usadas nas tags de {@code <intent>} do XML de preferncias:</p> 745 746 <pre> 747 final static String ACTION_PREFS_ONE = "com.example.prefs.PREFS_ONE"; 748 ... 749 750 @Override 751 public void onCreate(Bundle savedInstanceState) { 752 super.onCreate(savedInstanceState); 753 754 String action = getIntent().getAction(); 755 if (action != null && action.equals(ACTION_PREFS_ONE)) { 756 addPreferencesFromResource(R.xml.preferences); 757 } 758 ... 759 760 else if (Build.VERSION.SDK_INT < Build.VERSION_CODES.HONEYCOMB) { 761 // Load the legacy preferences headers 762 addPreferencesFromResource(R.xml.preference_headers_legacy); 763 } 764 } 765 </pre> 766 767 <p>Observe que chamadas consecutivas a {@link 768 android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} 769 empilharo todas as preferncias em uma nica lista, portanto certifique-se de que seja chamado somente uma vez, encadeando 770 as condies com declaraes else-if.</p> 771 772 773 774 775 776 <h2 id="ReadingPrefs">Leitura de preferncias</h2> 777 778 <p>Por padro, todas as preferncias do aplicativo so salvas em um arquivo acessvel de qualquer lugar 779 dentro do aplicativo chamando o mtodo esttico {@link 780 android.preference.PreferenceManager#getDefaultSharedPreferences 781 PreferenceManager.getDefaultSharedPreferences()}. Isso retorna o objeto {@link 782 android.content.SharedPreferences} que contm todos os pares de valores-chave associados 783 aos objetos {@link android.preference.Preference} usados em {@link 784 android.preference.PreferenceActivity}.</p> 785 786 <p>Por exemplo, abaixo apresenta-se como ler um dos valores de preferncia de outra atividade 787 no aplicativo:</p> 788 789 <pre> 790 SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(this); 791 String syncConnPref = sharedPref.getString(SettingsActivity.KEY_PREF_SYNC_CONN, ""); 792 </pre> 793 794 795 796 <h3 id="Listening">Escuta de alteraes de preferncia</h3> 797 798 <p>H alguns motivos pelos quais pode ser necessrio ser notificado assim que o usurio altera 799 uma das preferncias. Para receber um retorno de chamada quando acontece uma alterao em alguma das preferncias, 800 implemente a interface {@link android.content.SharedPreferences.OnSharedPreferenceChangeListener 801 SharedPreference.OnSharedPreferenceChangeListener} e registre a escuta 802 para o objeto {@link android.content.SharedPreferences} chamando {@link 803 android.content.SharedPreferences#registerOnSharedPreferenceChangeListener 804 registerOnSharedPreferenceChangeListener()}.</p> 805 806 <p>A interface tem somente um mtodo de retorno de chamada, {@link 807 android.content.SharedPreferences.OnSharedPreferenceChangeListener#onSharedPreferenceChanged 808 onSharedPreferenceChanged()}, e pode ser mais fcil implementar a interface como parte 809 da atividade. Por exemplo:</p> 810 811 <pre> 812 public class SettingsActivity extends PreferenceActivity 813 implements OnSharedPreferenceChangeListener { 814 public static final String KEY_PREF_SYNC_CONN = "pref_syncConnectionType"; 815 ... 816 817 public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, 818 String key) { 819 if (key.equals(KEY_PREF_SYNC_CONN)) { 820 Preference connectionPref = findPreference(key); 821 // Set summary to be the user-description for the selected value 822 connectionPref.setSummary(sharedPreferences.getString(key, "")); 823 } 824 } 825 } 826 </pre> 827 828 <p>Nesse exemplo, o mtodo verifica se a configurao alterada se destina a uma chave de preferncia conhecida. Ele 829 chama {@link android.preference.PreferenceActivity#findPreference findPreference()} para obter 830 o objeto {@link android.preference.Preference} alterado para que possa modificar o sumrio 831 do item como uma descrio da seleo do usurio. Ou seja, quando a configurao for uma {@link 832 android.preference.ListPreference} ou outra configurao de mltipla escolha, deve-se chamar {@link 833 android.preference.Preference#setSummary setSummary()} quando a configurao for alterada para exibir 834 o status atual (como a configurao Suspenso mostrada na figura 5).</p> 835 836 <p class="note"><strong>Observao:</strong> conforme descrito no documento do Projeto para Android sobre <a href="{@docRoot}design/patterns/settings.html">Configuraes</a>, recomendamos atualizar 837 o sumrio de {@link android.preference.ListPreference} a cada vez que o usurio alterar a preferncia 838 para descrever a configurao atual.</p> 839 840 <p>Para um gerenciamento adequado do ciclo de vida na atividade, recomendamos registrar e remover o registro 841 de {@link android.content.SharedPreferences.OnSharedPreferenceChangeListener} durante os retornos de chamada de {@link 842 android.app.Activity#onResume} e {@link android.app.Activity#onPause} respectivamente:</p> 843 844 <pre> 845 @Override 846 protected void onResume() { 847 super.onResume(); 848 getPreferenceScreen().getSharedPreferences() 849 .registerOnSharedPreferenceChangeListener(this); 850 } 851 852 @Override 853 protected void onPause() { 854 super.onPause(); 855 getPreferenceScreen().getSharedPreferences() 856 .unregisterOnSharedPreferenceChangeListener(this); 857 } 858 </pre> 859 860 <p class="caution"><strong>Ateno:</strong> ao chamar {@link 861 android.content.SharedPreferences#registerOnSharedPreferenceChangeListener 862 registerOnSharedPreferenceChangeListener()}, o gerenciador de preferncias 863 no armazena atualmente uma referncia escuta. preciso armazenar uma referncia 864 forte escuta, seno ela ser suscetvel coleta de lixo. Recomendamos 865 manter uma referncia escuta nos dados de instncia de um objeto 866 que existir enquanto a escuta for necessria.</p> 867 868 <p>Por exemplo: no cdigo a seguir, o autor da chamada no mantm nenhuma 869 referncia escuta. Como resultado, a escuta estar sujeita coleta de lixo 870 e falhar futuramente em algum momento indeterminado:</p> 871 872 <pre> 873 prefs.registerOnSharedPreferenceChangeListener( 874 // Bad! The listener is subject to garbage collection! 875 new SharedPreferences.OnSharedPreferenceChangeListener() { 876 public void onSharedPreferenceChanged(SharedPreferences prefs, String key) { 877 // listener implementation 878 } 879 }); 880 </pre> 881 882 <p>Em vez disso, armazene uma referncia escuta nos dados de instncia de um objeto 883 que existir enquanto a escuta for necessria:</p> 884 885 <pre> 886 SharedPreferences.OnSharedPreferenceChangeListener listener = 887 new SharedPreferences.OnSharedPreferenceChangeListener() { 888 public void onSharedPreferenceChanged(SharedPreferences prefs, String key) { 889 // listener implementation 890 } 891 }; 892 prefs.registerOnSharedPreferenceChangeListener(listener); 893 </pre> 894 895 <h2 id="NetworkUsage">Gerenciamento de uso de rede</h2> 896 897 898 <p>A partir do Android 4.0, o aplicativo Configuraes do sistema permite aos usurios ver o quanto 899 de dados de rede que os aplicativos usam em primeiro e segundo plano. Portanto, os usurios 900 podem desativar os dados em segundo plano de aplicativos individuais. Para evitar que os usurios desativem 901 o acesso do aplicativo a dados em segundo plano, deve-se usar a conexo de dados de forma eficiente 902 e permitir aos usurios refinar o uso de dados do aplicativo por meio das configuraes do aplicativo.<p> 903 904 <p>Por exemplo: deve-se permitir ao usurio controlar a frequncia de sincronizao dos dados do aplicativo para 905 uploads/downloads somente quando estiver em Wi-Fi, o aplicativo usar dados em deslocamento etc. Com esses 906 controles disponveis para eles, bem menos provvel que os usurios desativem o acesso do aplicativo a dados 907 quando eles se aproximam dos limites que definem nas Configuraes do sistema porque, em vez disso, podem controlar 908 precisamente a quantidade de dados que o aplicativo usa.</p> 909 910 <p>Depois de adicionadas as preferncias necessrias em {@link android.preference.PreferenceActivity} 911 para controlar os hbitos de dados do aplicativo, deve-se adicionar um filtro de intenes para {@link 912 android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} no arquivo de manifesto. Por exemplo:</p> 913 914 <pre> 915 <activity android:name="SettingsActivity" ... > 916 <intent-filter> 917 <action android:name="android.intent.action.MANAGE_NETWORK_USAGE" /> 918 <category android:name="android.intent.category.DEFAULT" /> 919 </intent-filter> 920 </activity> 921 </pre> 922 923 <p>Esse filtro de intenes indica ao sistema que se trata da atividade que controla 924 o uso de dados do aplicativo. Assim, quando o usurio inspeciona a quantidade de dados que o aplicativo est usando 925 no aplicativo Configuraes do sistema, um boto <em>Exibir configuraes de aplicativo</em> fica disponvel e inicia 926 {@link android.preference.PreferenceActivity} para que o usurio refine a quantidade de dados que 927 o aplicativo usa.</p> 928 929 930 931 932 933 934 935 <h2 id="Custom">Composio de uma preferncia personalizada</h2> 936 937 <p>A estrutura do Android contm uma variedade de subclasses {@link android.preference.Preference} que permitem 938 criar uma IU com diferentes tipos de configuraes. 939 No entanto, pode ser necessrio descobrir uma configurao pra a qual no h nenhuma soluo embutida, 940 como um seletor de nmeros ou seletor de datas. Nesse caso, ser preciso criar uma preferncia personalizada, estendendo 941 a classe {@link android.preference.Preference} ou uma das outras subclasses.</p> 942 943 <p>Ao estender a classe {@link android.preference.Preference}, h algumas coisas importantes 944 a fazer:</p> 945 946 <ul> 947 <li>Especificar a interface do usurio exibida quando o usurio seleciona as configuraes.</li> 948 <li>Salvar os valores da configurao conforme apropriado.</li> 949 <li>Inicializar {@link android.preference.Preference} com o valor atual (ou padro) 950 quando ela exibida.</li> 951 <li>Fornecer o valor padro quando solicitado pelo sistema.</li> 952 <li>Se {@link android.preference.Preference} fornece sua prpria IU (como uma caixa de dilogo, por exemplo), salve 953 e restaure o estado para tratar de alteraes de ciclo de vida (como quando o usurio gira a tela).</li> 954 </ul> 955 956 <p>As sees a seguir descrevem como executar cada uma dessas tarefas.</p> 957 958 959 960 <h3 id="CustomSelected">Especificao da interface do usurio</h3> 961 962 <p>Se a classe {@link android.preference.Preference} for estendida, ser preciso implementar 963 {@link android.preference.Preference#onClick()} para definir a ao que ocorre quando 964 o usurio a seleciona. No entanto, a maioria das configuraes personalizadas estendem {@link android.preference.DialogPreference} 965 para exibir uma caixa de dilogo, o que simplifica o procedimento. Quando se estende {@link 966 android.preference.DialogPreference}, preciso chamar {@link 967 android.preference.DialogPreference#setDialogLayoutResource setDialogLayoutResourcs()} na classe 968 do construtor para especificar o layout da caixa de dilogo.</p> 969 970 <p>Por exemplo, eis o construtor de um {@link 971 android.preference.DialogPreference} personalizado que declara o layout e especifica o texto dos botes padro 972 da caixa de dilogo positiva e negativa:</p> 973 974 <pre> 975 public class NumberPickerPreference extends DialogPreference { 976 public NumberPickerPreference(Context context, AttributeSet attrs) { 977 super(context, attrs); 978 979 setDialogLayoutResource(R.layout.numberpicker_dialog); 980 setPositiveButtonText(android.R.string.ok); 981 setNegativeButtonText(android.R.string.cancel); 982 983 setDialogIcon(null); 984 } 985 ... 986 } 987 </pre> 988 989 990 991 <h3 id="CustomSave">Salvamento do valor da configurao</h3> 992 993 <p>Para salvar um valor da configurao a qualquer momento, chame um dos mtodos {@code persist*()} da classe {@link 994 android.preference.Preference}, como {@link 995 android.preference.Preference#persistInt persistInt()} se o valor da configurao for um inteiro 996 ou {@link android.preference.Preference#persistBoolean persistBoolean()} para salvar um booleano.</p> 997 998 <p class="note"><strong>Observao:</strong> cada {@link android.preference.Preference} pode salvar somente 999 um tipo de dados, portanto preciso usar o mtodo {@code persist*()} adequado para o tipo de dados usado pela 1000 {@link android.preference.Preference} personalizada.</p> 1001 1002 <p>Quando se opta por persistir, a configurao pode depender da classe {@link 1003 android.preference.Preference} estendida. Se {@link 1004 android.preference.DialogPreference} for estendida, deve-se persistir o valor somente quando a caixa de dilogo 1005 fecha devido a um resultado positivo (o usurio seleciona o boto "OK").</p> 1006 1007 <p>Quando uma {@link android.preference.DialogPreference} fecha, o sistema chama o mtodo {@link 1008 android.preference.DialogPreference#onDialogClosed onDialogClosed()}. O mtodo contm um argumento 1009 booleano que especifica se o resultado do usurio "positivo" — se o valor 1010 <code>true</code> e, em seguida, o usurio selecionou o boto positivo e voc deve salvar o novo valor. Por 1011 exemplo:</p> 1012 1013 <pre> 1014 @Override 1015 protected void onDialogClosed(boolean positiveResult) { 1016 // When the user selects "OK", persist the new value 1017 if (positiveResult) { 1018 persistInt(mNewValue); 1019 } 1020 } 1021 </pre> 1022 1023 <p>Nesse exemplo, <code>mNewValue</code> um membro da classe que retm o valor atual 1024 da configurao. A chamada de {@link android.preference.Preference#persistInt persistInt()} salva o valor 1025 no arquivo {@link android.content.SharedPreferences} (usando automaticamente a chave 1026 especificada no arquivo XML dessa {@link android.preference.Preference}).</p> 1027 1028 1029 <h3 id="CustomInitialize">Inicializao do valor atual</h3> 1030 1031 <p>Quando o sistema adiciona o {@link android.preference.Preference} tela, ele chama 1032 {@link android.preference.Preference#onSetInitialValue onSetInitialValue()} para notificar 1033 se a configurao tem um valor persistido. Se no houver valor persistido, essa chamada fornece 1034 o valor padro.</p> 1035 1036 <p>O mtodo {@link android.preference.Preference#onSetInitialValue onSetInitialValue()} passa 1037 um booleano, <code>restorePersistedValue</code>, para indicar se um valor j foi persistido 1038 para a configurao. Se for <code>true</code>, deve-se recuperar o valor persistindo chamando-se 1039 um dos mtodos {@code getPersisted*()} da classe {@link 1040 android.preference.Preference}, como {@link 1041 android.preference.Preference#getPersistedInt getPersistedInt()} para um valor inteiro. Geralmente 1042 se recupera o valor persistido para atualizar adequadamente a IU de forma a refletir 1043 o valor salvo anteriormente.</p> 1044 1045 <p>Se <code>restorePersistedValue</code> for <code>false</code>, deve-se 1046 usar o valor padro passado no segundo argumento.</p> 1047 1048 <pre> 1049 @Override 1050 protected void onSetInitialValue(boolean restorePersistedValue, Object defaultValue) { 1051 if (restorePersistedValue) { 1052 // Restore existing state 1053 mCurrentValue = this.getPersistedInt(DEFAULT_VALUE); 1054 } else { 1055 // Set default state from the XML attribute 1056 mCurrentValue = (Integer) defaultValue; 1057 persistInt(mCurrentValue); 1058 } 1059 } 1060 </pre> 1061 1062 <p>Cada mtodo {@code getPersisted*()} pega um argumento que especifica o valor 1063 padro a usar caso no haja nenhum valor persistido ou se a chave no existir. No 1064 exemplo acima, uma constante local usada para especificar o valor padro se {@link 1065 android.preference.Preference#getPersistedInt getPersistedInt()} no puder retornar um valor persistido.</p> 1066 1067 <p class="caution"><strong>Ateno:</strong> <strong>no</strong> possvel usar 1068 <code>defaultValue</code> como valor padro no mtodo {@code getPersisted*()} porque 1069 seu valor sempre nulo quando <code>restorePersistedValue</code> <code>true</code>.</p> 1070 1071 1072 <h3 id="CustomDefault">Fornecimento de um valor padro</h3> 1073 1074 <p>Se a instncia da classe {@link android.preference.Preference} especificar um valor padro 1075 (com o atributo {@code android:defaultValue}), 1076 o sistema chama {@link android.preference.Preference#onGetDefaultValue 1077 onGetDefaultValue()} quando instancia o objeto para recuperar o valor. preciso 1078 implementar esse mtodo para que o sistema salve o valor padro em {@link 1079 android.content.SharedPreferences}. Por exemplo:</p> 1080 1081 <pre> 1082 @Override 1083 protected Object onGetDefaultValue(TypedArray a, int index) { 1084 return a.getInteger(index, DEFAULT_VALUE); 1085 } 1086 </pre> 1087 1088 <p>Os argumentos do mtodo oferecem todo o necessrio: a matriz de atributos e a posio 1089 do ndice do {@code android:defaultValue}, que preciso recuperar. preciso implementar esse mtodo 1090 para extrair o valor padro do atributo porque deve-se especificar um valor padro 1091 local para o atributo caso o valor seja indefinido.</p> 1092 1093 1094 1095 <h3 id="CustomSaveState">Salvamento e restaurao do estado da preferncia</h3> 1096 1097 <p>Como um {@link android.view.View} em um layout, a subclasse {@link android.preference.Preference} 1098 responsvel por salvar e restaurar seu estado caso a atividade ou fragmento seja 1099 reiniciado (como ocorre quando o usurio gira a tela). Para salvar e restaurar 1100 adequadamente o estado da classe {@link android.preference.Preference}, preciso implementar 1101 os mtodos de retorno de chamada do ciclo de vida {@link android.preference.Preference#onSaveInstanceState 1102 onSaveInstanceState()} e {@link 1103 android.preference.Preference#onRestoreInstanceState onRestoreInstanceState()}.</p> 1104 1105 <p>O estado de {@link android.preference.Preference} definido por um objeto que implementa 1106 a interface {@link android.os.Parcelable}. A estrutura do Android fornece esse objeto 1107 como um ponto inicial para definir o objeto de estado: a classe {@link 1108 android.preference.Preference.BaseSavedState}.</p> 1109 1110 <p>Para definir como a classe {@link android.preference.Preference} salva seu estado, deve-se estender 1111 a classe {@link android.preference.Preference.BaseSavedState}. preciso substituir 1112 alguns mtodos e definir o objeto {@link android.preference.Preference.BaseSavedState#CREATOR}. 1113 </p> 1114 1115 <p>Na maioria dos aplicativos, possvel copiar a implementao a seguir e simplesmente alterar as linhas 1116 que tratam o {@code value} se a subclasse {@link android.preference.Preference} salvar um tipo 1117 de dados que no seja um inteiro.</p> 1118 1119 <pre> 1120 private static class SavedState extends BaseSavedState { 1121 // Member that holds the setting's value 1122 // Change this data type to match the type saved by your Preference 1123 int value; 1124 1125 public SavedState(Parcelable superState) { 1126 super(superState); 1127 } 1128 1129 public SavedState(Parcel source) { 1130 super(source); 1131 // Get the current preference's value 1132 value = source.readInt(); // Change this to read the appropriate data type 1133 } 1134 1135 @Override 1136 public void writeToParcel(Parcel dest, int flags) { 1137 super.writeToParcel(dest, flags); 1138 // Write the preference's value 1139 dest.writeInt(value); // Change this to write the appropriate data type 1140 } 1141 1142 // Standard creator object using an instance of this class 1143 public static final Parcelable.Creator<SavedState> CREATOR = 1144 new Parcelable.Creator<SavedState>() { 1145 1146 public SavedState createFromParcel(Parcel in) { 1147 return new SavedState(in); 1148 } 1149 1150 public SavedState[] newArray(int size) { 1151 return new SavedState[size]; 1152 } 1153 }; 1154 } 1155 </pre> 1156 1157 <p>Com a implementao acima de {@link android.preference.Preference.BaseSavedState} adicionada 1158 ao aplicativo (geralmente como uma subclasse da subclasse {@link android.preference.Preference}), 1159 preciso implementar os mtodos {@link android.preference.Preference#onSaveInstanceState 1160 onSaveInstanceState()} e {@link 1161 android.preference.Preference#onRestoreInstanceState onRestoreInstanceState()} 1162 da subclasse {@link android.preference.Preference}.</p> 1163 1164 <p>Por exemplo:</p> 1165 1166 <pre> 1167 @Override 1168 protected Parcelable onSaveInstanceState() { 1169 final Parcelable superState = super.onSaveInstanceState(); 1170 // Check whether this Preference is persistent (continually saved) 1171 if (isPersistent()) { 1172 // No need to save instance state since it's persistent, 1173 // use superclass state 1174 return superState; 1175 } 1176 1177 // Create instance of custom BaseSavedState 1178 final SavedState myState = new SavedState(superState); 1179 // Set the state's value with the class member that holds current 1180 // setting value 1181 myState.value = mNewValue; 1182 return myState; 1183 } 1184 1185 @Override 1186 protected void onRestoreInstanceState(Parcelable state) { 1187 // Check whether we saved the state in onSaveInstanceState 1188 if (state == null || !state.getClass().equals(SavedState.class)) { 1189 // Didn't save the state, so call superclass 1190 super.onRestoreInstanceState(state); 1191 return; 1192 } 1193 1194 // Cast state to custom BaseSavedState and pass to superclass 1195 SavedState myState = (SavedState) state; 1196 super.onRestoreInstanceState(myState.getSuperState()); 1197 1198 // Set this Preference's widget to reflect the restored state 1199 mNumberPicker.setValue(myState.value); 1200 } 1201 </pre> 1202 1203
