Personalizar as configurações   Parte do Android Jetpack.

Este tópico descreve como personalizar Preferences na sua hierarquia.

Como encontrar preferências

Para acessar uma Preference individual, por exemplo, ao consultar ou definir um valor de Preference, use PreferenceFragmentCompat.findPreference(). Esse método pesquisa toda a hierarquia em busca de uma Preference com a chave fornecida.

Por exemplo, considerando EditTextPreference com uma chave de "assinatura":

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

Podemos recuperar essa Preference usando o seguinte código:

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    val signaturePreference: EditTextPreference? = findPreference("signature")
    // do something with this preference
}

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    EditTextPreference signaturePreference = findPreference("signature");
    // do something with this preference
}

Controlar a visibilidade das preferências

Você pode controlar quais Preferences ficam visíveis para o usuário quando ele navega até uma tela de configurações. Por exemplo, se uma determinada Preference for significativa somente quando um recurso correspondente estiver ativado, convém ocultar essa Preference quando o recurso estiver desativado.

Para mostrar um Preference somente quando uma condição for atendida, primeiro defina a visibilidade da Preference como falsa no XML, conforme mostrado no exemplo abaixo:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"
        app:isPreferenceVisible="false"/>

Em seguida, em onCreatePreferences(), mostre o Preference quando a condição correspondente for atendida:

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    if(/*some feature*/) {
        val signaturePreference: EditTextPreference? = findPreference("signature")
        signaturePreference?.isVisible = true
    }
}

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    if(/*some feature*/) {
        EditTextPreference signaturePreference = findPreference("signature");
        if (signaturePreference != null) {
            signaturePreference.setVisible(true);
        }
    }
}

Atualizar resumos de forma dinâmica

Uma Preference que mantém dados precisa exibir o valor atual no resumo para ajudar o usuário a entender melhor o estado atual da Preference. Por exemplo, um EditTextPreference deve mostrar o valor de texto salvo no momento, e um ListPreference deve mostrar a entrada da lista selecionada no momento. Talvez você também tenha Preferences que precisem atualizar o resumo correspondente com base no estado interno ou externo do app, por exemplo, uma Preference que exibe um número de versão. Isso pode ser feito usando um SummaryProvider.

Usar um SimpleSummaryProvider

ListPreference e EditTextPreference incluem implementações simples de SummaryProvider que exibem automaticamente o valor salvo de Preference como o resumo. Se nenhum valor tiver sido salvo, "Não definido" será exibido.

É possível ativar essas implementações a partir do XML, definindo app:useSimpleSummaryProvider="true".

Como alternativa, no código, é possível usar ListPreference.SimpleSummaryProvider.getInstance() e EditTextPreference.SimpleSummaryProvider.getInstance() para acessar a instância simples de SummaryProvider e, em seguida, defini-la no Preference, conforme mostrado no exemplo a seguir:

listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance()
editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()

listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance());
editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());

Usar um SummaryProvider personalizado

Você pode criar seu próprio SummaryProvider e substituir provideSummary() para personalizar o resumo sempre que ele for solicitado pela Preference. Por exemplo, o EditTextPreference abaixo exibe o comprimento do valor salvo como resumo:

Como exemplo, considere o seguinte EditTextPreference:

<EditTextPreference
        app:key="counting"
        app:title="Counting preference"/>

Em onCreatePreferences(), crie um novo SummaryProvider e modifique provideSummary() para retornar o resumo que será exibido:

val countingPreference: EditTextPreference? = findPreference("counting")

countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference ->
    val text = preference.text
    if (TextUtils.isEmpty(text)) {
        "Not set"
    } else {
        "Length of saved value: " + text.length
    }
}

EditTextPreference countingPreference = findPreference("counting");

if (countingPreference != null) {
    countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() {
        @Override
        public CharSequence provideSummary(EditTextPreference preference) {
            String text = preference.getText();
            if (TextUtils.isEmpty(text)){
                return "Not set";
            }
            return "Length of saved value: " + text.length();
        }
    });
}

O resumo de Preference agora exibe o comprimento do valor salvo ou "Não definido", quando nenhum valor foi salvo.

Personalizar uma caixa de diálogo EditTextPreference

Em uma caixa de diálogo EditTextPreference, é possível personalizar o comportamento do campo de texto anexando um OnBindEditTextListener. Esse listener é invocado quando a caixa de diálogo é mostrada ao usuário.

Como exemplo, você pode personalizar uma caixa de diálogo para aceitar apenas números. Primeiro, crie a EditTextPreference:

<EditTextPreference
        app:key="number"
        app:title="Numbers only preference"/>

Em seguida, em onCreatePreferences(), crie um novo OnBindEditTextListener e substitua onBindEditText() para personalizar o EditText quando ele for exibido para o usuário.

val numberPreference: EditTextPreference? = findPreference("number")

numberPreference?.setOnBindEditTextListener { editText ->
    editText.inputType = InputType.TYPE_CLASS_NUMBER
}

EditTextPreference numberPreference = findPreference("number");

if (numberPreference != null) {
    numberPreference.setOnBindEditTextListener(
            new EditTextPreference.OnBindEditTextListener() {
                @Override
                public void onBindEditText(@NonNull EditText editText) {
                    editText.setInputType(InputType.TYPE_CLASS_NUMBER);
                }
            });
}

Agora, quando a caixa de diálogo é exibida para o usuário, o teclado é aberto apenas no modo numérico, para que o usuário possa inserir somente números no EditText.

Ações de preferência

Uma Preference pode ter uma ação específica quando tocada. Por exemplo, uma Preference pode atuar como um link para uma parte separada do seu app. Para adicionar uma ação a uma Preference, defina uma Intent na Preference diretamente ou um OnPreferenceClickListener para uma lógica mais específica.

Definir uma intent

É possível definir uma Intent em uma Preference para iniciar uma nova Activity, ou um novo Fragment ou app separados sempre que a Preference for tocada. Isso é igual a usar Context.startActivity() com uma determinada Intent.

Você pode definir uma Intent em XML usando uma tag <intent>. O exemplo abaixo define uma Intent que inicia uma Activity:

<Preference
        app:key=”activity”
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity"/>
</Preference>

Como alternativa, use setIntent() diretamente em uma Preference, conforme mostrado abaixo:

val intent = Intent(context, ExampleActivity::class.java)
activityPreference.setIntent(intent)

Intent intent = new Intent(getContext(), ExampleActivity.class);
activityPreference.setIntent(intent);

Você também pode incluir extras com uma Intent via XML:

<Preference
        app:key=”activity”
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity">
        <extra
                android:name="example_key"
                android:value="example_value"/>
    </intent>
</Preference>

Veja um exemplo de uma Preference com uma Intent que inicia uma página da Web:

<Preference
        app:key=”webpage”
        app:title="View webpage">
    <intent
            android:action="android.intent.action.VIEW"
            android:data="http://www.google.com" />
</Preference>

val intent = Intent(Intent.ACTION_VIEW)
intent.data = Uri.parse("http://www.google.com")
webpagePreference.setIntent(intent)

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("http://www.google.com"));
webpagePreference.setIntent(intent);

OnPreferenceClickListener

É possível definir um OnPreferenceClickListener em uma Preference, que adiciona um callback a onPreferenceClick() quando a Preference é tocada. Por exemplo, você poderá usar o listener para navegar até outro Fragment ou Activity, se tiver uma lógica mais complexa para lidar com a navegação.

Para definir um OnPreferenceClickListener, use um código semelhante ao seguinte:

onClickPreference.setOnPreferenceClickListener({
    // do something
    true
})

onClickPreference.setOnPreferenceClickListener(preference -> {
    // do something
    return true;
});