Personnaliser vos paramètres Fait partie d'Android Jetpack.

Ce document explique comment personnaliser des objets Preference dans votre hiérarchie.

Rechercher vos préférences

Pour accéder à un Preference individuel, par exemple pour obtenir ou définir une valeur Preference, utilisez PreferenceFragmentCompat.findPreference(). Cette méthode recherche un Preference dans l'ensemble de la hiérarchie à l'aide de la clé donnée.

Par exemple, pour accéder à un EditTextPreference avec une clé de "signature", procédez comme suit:

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

Récupérez ce Preference à l'aide du code suivant:

Kotlin

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

Java

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

Contrôler la visibilité des préférences

Vous pouvez contrôler les objets Preference visibles par l'utilisateur lorsqu'il accède à un écran de paramètres. Par exemple, si une Preference spécifique n'est pertinente que lorsqu'une fonctionnalité correspondante est activée, vous pouvez masquer cette Preference lorsque la fonctionnalité est désactivée.

Pour afficher une Preference uniquement lorsqu'une condition est remplie, définissez d'abord la visibilité Preference sur "false" dans le fichier XML, comme illustré dans l'exemple suivant:

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

Dans onCreatePreferences(), affichez Preference lorsque la condition correspondante est remplie:

Kotlin

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

Java

@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);
        }
    }
}

Mise à jour dynamique des résumés

Un Preference qui conserve les données doit afficher la valeur actuelle dans son récapitulatif pour aider l'utilisateur à mieux comprendre l'état actuel de l'Preference. Par exemple, un EditTextPreference doit afficher la valeur de texte enregistrée, et un ListPreference doit afficher l'entrée de liste sélectionnée. Vous pouvez également avoir des objets Preference qui doivent mettre à jour leur résumé en fonction de l'état interne ou externe de l'application, par exemple un Preference qui affiche un numéro de version. Pour ce faire, utilisez un SummaryProvider.

Utiliser un SimpleSummaryProvider

ListPreference et EditTextPreference incluent des implémentations SummaryProvider simples qui affichent automatiquement la valeur Preference enregistrée en tant que résumé. Si aucune valeur n'est enregistrée, la mention "Non défini" s'affiche.

Pour activer ces implémentations à partir d'un fichier XML, définissez app:useSimpleSummaryProvider="true".

Dans le code, vous pouvez également utiliser ListPreference.SimpleSummaryProvider.getInstance() et EditTextPreference.SimpleSummaryProvider.getInstance() pour obtenir l'instance SummaryProvider simple, puis la définir sur Preference, comme illustré dans l'exemple suivant:

Kotlin

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

Java

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

Utiliser un SummaryProvider personnalisé

Vous pouvez créer votre propre SummaryProvider et remplacer provideSummary() pour personnaliser le résumé chaque fois qu'il est demandé par Preference. Par exemple, l'élément EditTextPreference suivant affiche la longueur de sa valeur enregistrée sous forme de résumé:

Image montrant un exemple d&#39;élément EditTextPreference
Figure 1 : Exemple de EditTextPreference.

Par exemple, supposons que l'élément EditTextPreference suivant s'affiche:

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

Dans onCreatePreferences(), vous pouvez créer un nouveau SummaryProvider et remplacer provideSummary() pour renvoyer le résumé à afficher:

Kotlin

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

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

Java

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) || text == null){
                return "Not set";
            }
            return "Length of saved value: " + text.length();
        }
    });
}

Le résumé Preference affiche la longueur de la valeur enregistrée ou "Non défini" s'il n'existe aucune valeur enregistrée.

Personnaliser une boîte de dialogue EditTextPreference

Dans une boîte de dialogue EditTextPreference, vous pouvez personnaliser le comportement des champs de texte en associant un OnBindEditTextListener. Cet écouteur est appelé lorsque l'utilisateur voit la boîte de dialogue.

Par exemple, vous pouvez personnaliser une boîte de dialogue pour qu'elle n'accepte que des chiffres. Commencez par créer le EditTextPreference:

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

Ensuite, dans onCreatePreferences(), créez un objet OnBindEditTextListener et remplacez onBindEditText() pour personnaliser l'élément EditText lorsqu'il est présenté à l'utilisateur.

Kotlin

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

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

Java

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);
                }
            });
}

Désormais, lorsque la boîte de dialogue est présentée à l'utilisateur, le clavier s'ouvre en mode numérique uniquement. L'utilisateur ne peut donc saisir que des chiffres dans EditText.

Actions souhaitées

Lorsqu'un utilisateur appuie sur un Preference, il peut effectuer une action spécifique. Par exemple, un élément Preference peut servir de lien vers une partie distincte de votre application. Pour ajouter une action à un élément Preference, vous pouvez définir un élément Intent directement sur l'élément Preference ou définir un élément OnPreferenceClickListener pour une logique plus spécifique.

Définir un intent

Vous pouvez définir un Intent sur une Preference pour lancer une nouvelle Fragment, une nouvelle Activity ou une application distincte chaque fois que l'utilisateur appuie sur Preference. Cela revient à utiliser Context.startActivity() avec un Intent donné.

Vous pouvez définir un Intent en XML à l'aide d'une balise <intent> imbriquée. L'exemple suivant définit une Intent qui lance une Activity:

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

Vous pouvez également utiliser setIntent() directement sur un Preference, comme suit:

Kotlin

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

Java

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

Vous pouvez également inclure des extras avec un Intent au format 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>

Voici un exemple de Preference avec un Intent qui lance une page Web:

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

Kotlin

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

val webpagePreference = findPreference("webpage")
webpagePreference?.intent = intent

Java

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

OnPreferenceClickListener

Vous pouvez définir un OnPreferenceClickListener sur un Preference, ce qui ajoute un rappel à onPreferenceClick() lorsque l'utilisateur appuie sur l'Preference. Par exemple, vous pouvez utiliser l'écouteur pour accéder à un autre élément Fragment ou Activity si vous disposez d'une logique plus complexe pour gérer la navigation.

Pour définir un élément OnPreferenceClickListener, utilisez un code semblable à celui-ci:

Kotlin

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

Java

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