Atributos e componentes de Preference   Part of Android Jetpack.

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

Componentes de Preference

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

Infraestrutura de Preference

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

Contêineres de Preference

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

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

Preferences individuais

Preference: é o bloco fundamental para representar uma configuração individual. Se a Preference for configurada para persistir, ela terá um par de chave-valor correspondente que salva a configuração escolhida pelo usuário que pode ser acessada em outros locais no aplicativo.

EditTextPreference: é uma Preference que mantém um valor de String. Os usuários podem tocar em Preference para iniciar uma caixa de diálogo com o campo de texto que permite alterar o valor mantido.

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

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

SeekBarPreference: é uma Preference que mantém um número inteiro. Para alterar esse valor, basta arrastar a barra de pesquisa correspondente no layout de Preference.

SwitchPreferenceCompat: é uma Preference que mantém um valor booleano. Para alterar esse valor, basta interagir com o widget de alteração correspondente ou tocar no layout da Preference.

CheckBoxPreference: é uma Preference que mantém um valor booleano. Para alterar esse valor, basta interagir com a caixa de seleção correspondente ou tocar no layout da Preference .

Atributos de Preference

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

Atributos genéricos

title

É um valor de String que representa o título da Preference.

Exemplo: app:title="Title"

summary

É um valor de 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 de String que representa a chave usada a fim de manter o valor para a Preference associada. Uma chave permite personalizar mais a Preference durante o tempo de execução. É preciso definir uma chave para cada Preference na sua 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 é exibida em cinza, 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 a Preference ou a categoria da Preference é 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 não for encontrado outro valor mantido para a Preference. O tipo de valor depende da Preference associada.

Exemplo: app:defaultValue="true"

dependency

Representa a chave de um SwitchPreferenceCompat que controla o estado da Preference. Se a chave correspondente for desligada, a Preference será desativada e não poderá ser modificada.

Exemplo: app:dependency="parent"

Atributos de PreferenceCategory

initialExpandedChildrenCount

É um valor inteiro que permite o comportamento expansível de Preference . Esse valor representa o número máximo de elementos filhos que serão exibidos em PreferenceGroup. Os elementos filhos adicionais serão recolhidos. Para exibi-los, toque no botão para expandir. Por padrão, esse valor é Integer.MAX_VALUE, e todos os elementos filhos são exibidos.

Aviso: é preciso definir uma chave em PreferenceCategory ao usar esse atributo, para que o estado seja salvo e restaurado corretamente quando a configuração for alterada (por exemplo, ao girar a tela).

Exemplo: app:initialExpandedChildrenCount="0"

Atributos de ListPreference / MultiSelectListPreference

entries

É uma matriz de strings que corresponde às entradas da lista que serão exibidas ao usuário. Cada valor corresponde no índice à matriz de valores mantidos internamente. Por exemplo, quando o usuário seleciona a primeira entrada da lista, o primeiro elemento na matriz de valores correspondente é mantido.

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

Aviso: o tamanho das duas matrizes precisa ser igual, e os índices delas devem ser correspondentes ao par de entrada/valor correto.

entryValues

É a matriz de entradas que serão mantidas. Cada um desses valores corresponde no índice à matriz de entradas da lista que são exibidas para o usuário.

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