Personnaliser vos paramètres Inclus dans Android Jetpack.

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

Retrouver vos préférences

Pour accéder à un Preference individuel, par exemple lors de l'obtention ou de la configuration d'un Valeur : Preference, utiliser PreferenceFragmentCompat.findPreference() Cette méthode recherche un élément Preference dans l'ensemble de la hiérarchie avec la clé donnée.

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

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

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

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.
}

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

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

Pour n'afficher un Preference que lorsqu'une condition est remplie, commencez par définir l'Preference visibilité 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 le Preference lorsque les condition est remplie:

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

Mise à jour dynamique des résumés

Un élément Preference qui conserve les données doit afficher la valeur actuelle dans son summary pour aider l'utilisateur à mieux comprendre l'état actuel Preference Par exemple, un élément EditTextPreference doit afficher le texte enregistré et ListPreference doit afficher l'entrée de liste sélectionnée. Vous pourriez également disposent d'objets Preference qui doivent mettre à jour leur résumé en fonction d'une stratégie un état d'application externe (par exemple, un Preference qui affiche une version) numéro. Pour ce faire, vous pouvez utiliser un SummaryProvider

Utiliser un SimpleSummaryProvider

ListPreference et EditTextPreference incluez des implémentations SummaryProvider simples qui affichent automatiquement a enregistré la valeur Preference en tant que résumé. Si aucune valeur n'est enregistrée, la mention "Pas ensemble. »

Pour permettre ces implémentations à partir du code 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:

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

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. Pour Par exemple, l'élément EditTextPreference suivant affiche la longueur de son pour le résumé:

Par exemple, supposons le EditTextPreference suivant:

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

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

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

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écapitulatif Preference affiche la longueur de la valeur enregistrée ou de la valeur "Non définie". lorsqu'aucune valeur enregistrée n'existe.

Personnaliser une boîte de dialogue EditTextPreference

Dans une boîte de dialogue EditTextPreference, vous pouvez personnaliser le comportement du champ de texte en procédant comme suit : en renseignant 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 n'accepter que les chiffres. Tout d'abord, créez le EditTextPreference:

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

Ensuite, dans onCreatePreferences(), créez un OnBindEditTextListener et remplacer onBindEditText() pour personnaliser le EditText lorsqu'il est présenté aux utilisateur.

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

Désormais, lorsque la boîte de dialogue s'affiche, le clavier s'ouvre en mode numérique uniquement afin que l'utilisateur ne puisse saisir que des chiffres dans EditText.

Actions des préférences

Un Preference peut avoir une action spécifique lorsque l'utilisateur appuie dessus. Par exemple, un Preference peut servir de lien vers une partie distincte de votre application. Pour ajouter une action sur un Preference, vous pouvez définir un Intent directement sur le Preference ou vous pouvez définir une OnPreferenceClickListener pour une logique plus spécifique.

Définir un intent

Vous pouvez définir un Intent sur un Preference pour lancer un nouveau Fragment, Activity, ou séparer une appli chaque fois que l'utilisateur appuie sur Preference. Il s'agit de la identique à l'utilisation Context.startActivity() avec un Intent donné.

Vous pouvez définir un Intent en XML à l'aide d'une balise <intent> imbriquée. Les éléments suivants : L'exemple définit un Intent qui lance un 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:

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

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>

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

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

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

Écouteur de clics "OnPreferenceClickListener"

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

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

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

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