Android Preferences: PreferenceScreen, PreferenceActivity, PreferenceFragment

Notes about building preferences in Android.  I'm trying to coalesce it into one place for the sake of remembering all the parts and how it all fits together.

Preferences are Androids encapsulation of behavior for setting and saving (exposed) global state for an application.  Here are the parts which are needed:

1. Preferences xml file
1. Located not in layouts, but in res/xml directory.
1. Preferences are contained within root node of PreferenceScreen type.
2. String resources
1. string
2. string-array
3. PreferenceFragment
4. PreferenceActivity
5. AndroidManifest
1. Add preferences activity
6. Initializing default values
1. Set in XML
1. android:defaultValue="value", where value is a string or @string/id
2. In main onCreate method and any other activity the user can enter into application

PreferenceActivity:  Post Android 3.0

The activity instantiating the PreferenceFragment has to use a PreferenceFragment, but it can be any Activity, not a PreferenceActivity.  The code below attaches a fragment, from Google's Android Docs:

public class SettingsActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Display the fragment as the main content.
        getFragmentManager().beginTransaction()
                .replace(android.R.id.content, new SettingsFragment())
                .commit();
    }
}

Version 3.0 and Older

Android docs show the following code to instantiate a PreferenceFragment before version 3.0, pay attention to which version you're developing for, because on version 3.0 and higher, addPreferences is deprecated.

public class SettingsActivity extends PreferenceActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        addPreferencesFromResource(R.xml.preferences); // DEPRECATED IN >= 3.0
    }
}

PreferenceFragment

addPreferencesFromResource in PreferenceFragment is not deprecated.

public static class SettingsFragment extends PreferenceFragment {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Load the preferences from an XML resource
        addPreferencesFromResource(R.xml.preferences);
    }
    ...
}

Initializing Default Values

Call the following from onCreate of main application activity to make sure default preferences are initialized.  Note, that passing false in the third argument prevents overwriting any modifications to preference values, so it's safe to call in onCreate every time the app starts:

PreferenceManager.setDefaultValues(this, R.xml.advanced_preferences, false);

Preferences XML

Types of preferences are:

1. Category
1. PreferenceScreen
1. Must be root category.
2. Subsequent declarations create a screen break.
2. PreferenceCategory
3. Preference
1. Creates subcategory
2. Types
1. CheckBoxPreference
2. ListPreference
3. EditTextPreference
4. Intent
5. RingtonePreference
3. headers
1. more detail coming