PreferenceFragment::onPreferenceTreeClick return value - what does it do?

Question

It seems I can't find out how the return value of PreferenceFragment::onPreferenceTreeClick(...) is interpreted. In the docs there's not mentioned how the return value is used (Eclipse says "@inheritDoc" and the Android HTML reference has an empty body).

I tried looking it up in the deprecated API on PreferenceActivity::onPreferenceTreeClick(...) but all it says is, well, it is deprecated.

Additionally I tried returning true and false from the method, but it seemed to me as it had no effect on anything.

So - If anyone could please be so kind to tell me what the return value changes?

Answer 1

The code that calls this is in Preference#performClick(PreferenceScreen preferenceScreen) and it does the following:

PreferenceManager preferenceManager = getPreferenceManager();
if (preferenceManager != null) {
    PreferenceManager.OnPreferenceTreeClickListener listener = preferenceManager
            .getOnPreferenceTreeClickListener();
    if (preferenceScreen != null && listener != null
            && listener.onPreferenceTreeClick(preferenceScreen, this)) {
        return;
    }
}

if (mIntent != null) {
    Context context = getContext();
    context.startActivity(mIntent);
}

returning true will return immediately while returning false will check if there is an Intent set for this PreferenceScreen and start the specified Activity.

If you return super.onPreferenceTreeClick(preferenceScreen, preference) you will also cause the following piece of code from PreferenceFragment to run

if (preference.getFragment() != null &&
        getActivity() instanceof OnPreferenceStartFragmentCallback) {
    return ((OnPreferenceStartFragmentCallback)getActivity()).onPreferenceStartFragment(
            this, preference);
}
return false;

This one checks if there is a Fragment to be shown. If not Preference will then look for an Intent.

TLDR

Preferences can start either Intents or Fragments. The meaning of the return value is

• true : nothing happens, both fragments and intents are ignored
• false : fragments are ignored, intents are executed
• super.onPreference.. : tries fragment first, intent second

return false; or return super.onPreferenceTreeClick(...) should be usually the right thing to return. The meaning of the return value is roughly "Start Activity by intent if exist?". You should return true if you have specified an intent but don't want to start the activity. It does not matter in most other cases since you rarely handle clicks if you have that intent specified.