Componentes e atributos de preferências Parte do Android Jetpack.

Este tópico descreve alguns dos componentes e atributos de Preference mais usados ao criar uma tela de configurações.

Componentes de preferências

Esta seção descreve componentes comuns de Preference. Para saber mais, consulte as páginas de referência correspondentes de cada componente.

Infraestrutura de preferências

PreferenceFragmentCompat: um Fragment que gerencia a exibição de uma hierarquia interativa de objetos Preference.

Contêineres de preferências

PreferenceScreen: um contêiner de nível superior que representa uma tela de configurações. Este é o componente raiz da hierarquia de Preference.

PreferenceCategory: um contêiner usado para agrupar Preferences semelhantes. Uma PreferenceCategory exibe o título de uma categoria e separa visualmente grupos de Preferences.

Preferências individuais

Preference: o elemento básico que representa uma configuração individual. Se uma Preference estiver definida para persistir, ela terá um par de chave-valor correspondente que manterá a escolha do usuário para a configuração que pode ser acessada em outro lugar no app.

EditTextPreference: uma Preference que manterá um valor de String. Os usuários podem tocar na Preference para acessar uma caixa de diálogo contendo o campo de texto que permite ao usuário mudar o valor mantido.

ListPreference: uma Preference que mantém um valor de string. Os usuários podem mudar esse valor em uma caixa de diálogo que contém uma lista de botões de opção com marcadores correspondentes.

MultiSelectListPreference: uma Preference que mantém um conjunto de strings. Os usuários podem mudar esses valores em uma caixa de diálogo que contém uma lista de caixas de seleção com marcadores correspondentes.

SeekBarPreference: uma Preference que mantém um valor inteiro. Esse valor pode ser mudado arrastando-se uma barra de pesquisa correspondente exibida no layout da Preference.

SwitchPreferenceCompat: uma Preference que mantém um valor booleano. Esse valor pode ser mudado interagindo com o widget de alternância correspondente ou tocando no layout da Preference.

CheckBoxPreference: uma Preference que mantém um valor booleano. Esse valor pode ser mudado interagindo com a caixa de seleção correspondente ou tocando no layout da Preference.

Atributos de preferências

Veja abaixo alguns dos atributos mais usados que configuram a aparência e o comportamento da Preference.

Atributos genéricos

title

Um valor String que representa o título da Preference.

Exemplo: app:title="Title"

summary

Um valor String que representa o resumo da Preference.

Exemplo: app:summary="Summary"

icon

Um Drawable que representa o ícone da Preference.

Exemplo: app:icon="@drawable/ic_camera"

key

Um valor String que representa a chave usada para manter o valor da Preference associada. Uma chave permite personalizar ainda mais a Preference durante o tempo de execução. Você precisa definir uma chave para cada Preference da hierarquia.

Exemplo: app:key="key"

enabled

Um valor booleano que indica se os usuários podem interagir com a Preference. Quando esse valor é false, a Preference aparece esmaecida, e os usuários não podem interagir com ela. O valor padrão é true.

Exemplo: app:enabled="false"

selectable

Um valor booleano que indica se os usuários podem interagir com a Preference. O valor padrão é true.

Exemplo: app:selectable="false"

isPreferenceVisible

Um valor booleano que indica se uma Preference ou uma categoria de Preference está visível. Isso é equivalente a chamar setVisible().

Exemplo: app:isPreferenceVisible="false"

defaultValue

Representa o valor padrão de uma Preference. Esse valor é definido e mantido quando nenhum outro valor mantido para essa Preference é encontrado. O tipo de valor depende da Preference associada.

Exemplo: app:defaultValue="true"

dependency

Representa a chave de uma SwitchPreferenceCompat que controla o estado dessa Preference. Quando o interruptor correspondente estiver desativado, a Preference será desativada e não poderá ser modificada.

Exemplo: app:dependency="parent"

Atributos de PreferenceCategory

initialExpandedChildrenCount

Um valor inteiro que ativa o comportamento expansível da Preference. Esse valor representa o número máximo de filhos a serem mostrados no PreferenceGroup. Todos os outros filhos são recolhidos e podem ser mostrados tocando no botão de expansão. Por padrão, esse valor é Integer.MAX_VALUE, e todos os filhos são mostrados.

Aviso: configure uma chave na PreferenceCategory se você estiver usando esse atributo para que o estado seja salvo e restaurado corretamente quando a configuração mudar (por exemplo, ao girar a tela).

Exemplo: app:initialExpandedChildrenCount="0"

Atributos ListPreference/MultiSelectListPreference

entries

Uma matriz de strings que corresponde às entradas da lista a serem exibidas ao usuário. Cada um desses valores corresponde por índice à matriz de valores internamente persistidos. Por exemplo, quando um usuário seleciona a primeira entrada da lista, o primeiro elemento na matriz de valores correspondente é mantido.

Exemplo: app:entries="@array/entries"

Aviso: verifique se o tamanho de ambas as matrizes é o mesmo e se os índices de cada matriz correspondem ao par entrada/valor correto.

entryValues

A matriz de entradas a serem mantidas. Cada um desses valores corresponde por índice à matriz de entradas de lista que são exibidas ao usuário.

Exemplo: app:entryValues="@array/values"