Added in API level 11
Deprecated in API level 28

PreferenceFragment


abstract class PreferenceFragment : Fragment
kotlin.Any
   ↳ android.app.Fragment
   ↳ android.preference.PreferenceFragment

Shows a hierarchy of Preference objects as lists. These preferences will automatically save to SharedPreferences as the user interacts with them. To retrieve an instance of SharedPreferences that the preference hierarchy in this fragment will use, call PreferenceManager#getDefaultSharedPreferences(android.content.Context) with a context in the same package as this fragment.

Furthermore, the preferences shown will follow the visual style of system preferences. It is easy to create a hierarchy of preferences (that can be shown on multiple screens) via XML. For these reasons, it is recommended to use this fragment (as a superclass) to deal with preferences in applications.

A PreferenceScreen object should be at the top of the preference hierarchy. Furthermore, subsequent PreferenceScreen in the hierarchy denote a screen break--that is the preferences contained within subsequent PreferenceScreen should be shown on another screen. The preference framework handles showing these other screens from the preference hierarchy.

The preference hierarchy can be formed in multiple ways:

  • From an XML file specifying the hierarchy
  • From different Activities that each specify its own preferences in an XML file via Activity meta-data
  • From an object hierarchy rooted with PreferenceScreen

    To inflate from XML, use the addPreferencesFromResource(int). The root element should be a PreferenceScreen. Subsequent elements can point to actual Preference subclasses. As mentioned above, subsequent PreferenceScreen in the hierarchy will result in the screen break.

    To specify an Intent to query Activities that each have preferences, use addPreferencesFromIntent. Each Activity can specify meta-data in the manifest (via the key PreferenceManager#METADATA_KEY_PREFERENCES) that points to an XML resource. These XML resources will be inflated into a single preference hierarchy and shown by this fragment.

    To specify an object hierarchy rooted with PreferenceScreen, use setPreferenceScreen(android.preference.PreferenceScreen).

    As a convenience, this fragment implements a click listener for any preference in the current hierarchy, see onPreferenceTreeClick(android.preference.PreferenceScreen,android.preference.Preference).

  • Summary

    Nested classes
    abstract

    Interface that PreferenceFragment's containing activity should implement to be able to process preference items that wish to switch to a new fragment.

    Inherited constants
    Public constructors

    Public methods
    open Unit

    Adds preferences from activities that match the given Intent.

    open Unit
    addPreferencesFromResource(preferencesResId: Int)

    Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

    open Preference!

    Finds a Preference based on its key.

    open PreferenceManager!

    Returns the PreferenceManager used by this fragment.

    open PreferenceScreen!

    Gets the root of the preference hierarchy that this fragment is showing.

    open Unit
    onActivityCreated(savedInstanceState: Bundle?)

    Called when the fragment's activity has been created and this fragment's view hierarchy instantiated.

    open Unit
    onActivityResult(requestCode: Int, resultCode: Int, data: Intent!)

    open Unit
    onCreate(savedInstanceState: Bundle?)

    Called to do initial creation of a fragment.

    open View?
    onCreateView(inflater: LayoutInflater!, container: ViewGroup?, savedInstanceState: Bundle?)

    Called to have the fragment instantiate its user interface view.

    open Unit

    open Unit

    open Boolean
    onPreferenceTreeClick(preferenceScreen: PreferenceScreen!, preference: Preference!)

    open Unit

    open Unit

    open Unit

    open Unit
    onViewCreated(view: View!, savedInstanceState: Bundle?)

    Called immediately after onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle) has returned, but before any saved state has been restored in to the view.

    open Unit

    Sets the root of the preference hierarchy that this fragment is showing.

    Inherited functions

    Public constructors

    PreferenceFragment

    PreferenceFragment()

    Public methods

    addPreferencesFromIntent

    Added in API level 11
    open fun addPreferencesFromIntent(intent: Intent!): Unit

    Deprecated: Deprecated in Java.

    Adds preferences from activities that match the given Intent.

    Parameters
    intent Intent!: The Intent to query activities.

    addPreferencesFromResource

    Added in API level 11
    open fun addPreferencesFromResource(preferencesResId: Int): Unit

    Deprecated: Deprecated in Java.

    Inflates the given XML resource and adds the preference hierarchy to the current preference hierarchy.

    Parameters
    preferencesResId Int: The XML resource ID to inflate.

    findPreference

    Added in API level 11
    open fun findPreference(key: CharSequence!): Preference!

    Deprecated: Deprecated in Java.

    Finds a Preference based on its key.

    Parameters
    key CharSequence!: The key of the preference to retrieve.
    Return
    Preference! The Preference with the key, or null.

    getPreferenceManager

    Added in API level 11
    open fun getPreferenceManager(): PreferenceManager!

    Deprecated: Deprecated in Java.

    Returns the PreferenceManager used by this fragment.

    Return
    PreferenceManager! The PreferenceManager.

    getPreferenceScreen

    Added in API level 11
    open fun getPreferenceScreen(): PreferenceScreen!

    Deprecated: Deprecated in Java.

    Gets the root of the preference hierarchy that this fragment is showing.

    Return
    PreferenceScreen! The PreferenceScreen that is the root of the preference hierarchy.

    onActivityCreated

    Added in API level 11
    open fun onActivityCreated(savedInstanceState: Bundle?): Unit

    Deprecated: Deprecated in Java.

    Called when the fragment's activity has been created and this fragment's view hierarchy instantiated. It can be used to do final initialization once these pieces are in place, such as retrieving views or restoring state. It is also useful for fragments that use setRetainInstance(boolean) to retain their instance, as this callback tells the fragment when it is fully associated with the new activity instance. This is called after onCreateView and before onViewStateRestored(android.os.Bundle).
    If you override this method you must call through to the superclass implementation.

    Parameters
    savedInstanceState Bundle?: This value may be null.

    onActivityResult

    Added in API level 11
    open fun onActivityResult(
        requestCode: Int,
        resultCode: Int,
        data: Intent!
    ): Unit

    Deprecated: Deprecated in Java.

    Parameters
    requestCode Int: The integer request code originally supplied to startActivityForResult(), allowing you to identify who this result came from.
    resultCode Int: The integer result code returned by the child activity through its setResult().
    data Intent!: An Intent, which can return result data to the caller (various data can be attached to Intent "extras").

    onCreate

    Added in API level 11
    open fun onCreate(savedInstanceState: Bundle?): Unit

    Deprecated: Deprecated in Java.

    Called to do initial creation of a fragment. This is called after onAttach(android.app.Activity) and before onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle), but is not called if the fragment instance is retained across Activity re-creation (see setRetainInstance(boolean)).

    Note that this can be called while the fragment's activity is still in the process of being created. As such, you can not rely on things like the activity's content view hierarchy being initialized at this point. If you want to do work once the activity itself is created, see onActivityCreated(android.os.Bundle).

    If your app's targetSdkVersion is android.os.Build.VERSION_CODES#M or lower, child fragments being restored from the savedInstanceState are restored after onCreate returns. When targeting android.os.Build.VERSION_CODES#N or above and running on an N or newer platform version they are restored by Fragment.onCreate.


    If you override this method you must call through to the superclass implementation.
    Parameters
    savedInstanceState Bundle?: This value may be null.

    onCreateView

    Added in API level 11
    open fun onCreateView(
        inflater: LayoutInflater!,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View?

    Deprecated: Deprecated in Java.

    Called to have the fragment instantiate its user interface view. This is optional, and non-graphical fragments can return null (which is the default implementation). This will be called between onCreate(android.os.Bundle) and onActivityCreated(android.os.Bundle).

    If you return a View from here, you will later be called in onDestroyView when the view is being released.

    Parameters
    inflater LayoutInflater!: The LayoutInflater object that can be used to inflate any views in the fragment,
    container ViewGroup?: This value may be null.
    savedInstanceState Bundle?: This value may be null.
    Return
    View? Return the View for the fragment's UI, or null.

    onDestroy

    Added in API level 11
    open fun onDestroy(): Unit

    Deprecated: Deprecated in Java.

    onDestroyView

    Added in API level 11
    open fun onDestroyView(): Unit

    Deprecated: Deprecated in Java.

    onPreferenceTreeClick

    Added in API level 11
    open fun onPreferenceTreeClick(
        preferenceScreen: PreferenceScreen!,
        preference: Preference!
    ): Boolean

    Deprecated: Deprecated in Java.

    onSaveInstanceState

    Added in API level 11
    open fun onSaveInstanceState(outState: Bundle!): Unit

    Deprecated: Deprecated in Java.

    Parameters
    outState Bundle!: Bundle in which to place your saved state.

    onStart

    Added in API level 11
    open fun onStart(): Unit

    Deprecated: Deprecated in Java.

    onStop

    Added in API level 11
    open fun onStop(): Unit

    Deprecated: Deprecated in Java.

    onViewCreated

    Added in API level 13
    Deprecated in API level 28
    open fun onViewCreated(
        view: View!,
        savedInstanceState: Bundle?
    ): Unit

    Deprecated: Deprecated in Java.

    Called immediately after onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle) has returned, but before any saved state has been restored in to the view. This gives subclasses a chance to initialize themselves once they know their view hierarchy has been completely created. The fragment's view hierarchy is not however attached to its parent at this point.

    Parameters
    view View!: The View returned by onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle).
    savedInstanceState Bundle?: This value may be null.

    setPreferenceScreen

    Added in API level 11
    open fun setPreferenceScreen(preferenceScreen: PreferenceScreen!): Unit

    Deprecated: Deprecated in Java.

    Sets the root of the preference hierarchy that this fragment is showing.

    Parameters
    preferenceScreen PreferenceScreen!: The root PreferenceScreen of the preference hierarchy.