Added in API level 1
Deprecated in API level 29

PreferenceActivity


abstract class PreferenceActivity : ListActivity, PreferenceFragment.OnPreferenceStartFragmentCallback
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.view.ContextThemeWrapper
   ↳ android.app.Activity
   ↳ android.app.ListActivity
   ↳ android.preference.PreferenceActivity

This is the base class for an activity to show a hierarchy of preferences to the user. Prior to android.os.Build.VERSION_CODES#HONEYCOMB this class only allowed the display of a single set of preference; this functionality should now be found in the new PreferenceFragment class. If you are using PreferenceActivity in its old mode, the documentation there applies to the deprecated APIs here.

This activity shows one or more headers of preferences, each of which is associated with a PreferenceFragment to display the preferences of that header. The actual layout and display of these associations can however vary; currently there are two major approaches it may take:

  • On a small screen it may display only the headers as a single list when first launched. Selecting one of the header items will only show the PreferenceFragment of that header (on Android N and lower a new Activity is launched).
  • On a large screen it may display both the headers and current PreferenceFragment together as panes. Selecting a header item switches to showing the correct PreferenceFragment for that item.

Subclasses of PreferenceActivity should implement onBuildHeaders to populate the header list with the desired items. Doing this implicitly switches the class into its new "headers + fragments" mode rather than the old style of just showing a single preferences list.

Summary

Nested classes

Description of a single Header item that the user can select.

Constants
static String

When starting this activity, the invoking Intent can contain this extra boolean that the header list should not be displayed.

static String

When starting this activity, the invoking Intent can contain this extra string to specify which fragment should be initially displayed.

static String

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specified to supply a Bundle of arguments to pass to that fragment when it is instantiated during the initial creation of PreferenceActivity.

static String

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specify to supply the short title to be shown for that fragment.

static String

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specify to supply the title to be shown for that fragment.

static Long

Default value for Header.id indicating that no identifier value is set.

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 Unit
finishPreferencePanel(caller: Fragment!, resultCode: Int, resultData: Intent!)

Called by a preference panel fragment to finish itself.

open PreferenceManager!

Returns the PreferenceManager used by this activity.

open PreferenceScreen!

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

open Boolean

Returns true if this activity is currently showing the header list.

open Unit

Call when you need to change the headers being displayed.

open Boolean

Returns true if this activity is showing multiple panes -- the headers and a preference fragment.

open Unit

Parse the given XML file as a header description, adding each parsed Header into the target list.

open Unit

open Unit

Called when the activity needs its list of headers build.

open Intent!
onBuildStartFragmentIntent(fragmentName: String!, args: Bundle!, titleRes: Int, shortTitleRes: Int)

Called by startWithFragment(java.lang.String,android.os.Bundle,android.app.Fragment,int,int,int) when in single-pane mode, to build an Intent to launch a new activity showing the selected fragment.

open Unit

open PreferenceActivity.Header!

Called to determine the initial header to be shown.

open PreferenceActivity.Header!

Called after the header list has been updated (onBuildHeaders has been called and returned due to invalidateHeaders()) to specify the header that should now be selected.

open Unit

Called when the user selects an item in the header list.

open Boolean

Called to determine whether the header list should be hidden.

open Boolean

Called to determine if the activity should run in multi-pane mode.

open Boolean

open Boolean

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

open Unit

Set a footer that should be shown at the bottom of the header list.

open Unit
setParentTitle(title: CharSequence!, shortTitle: CharSequence!, listener: View.OnClickListener!)

Should be called after onCreate to ensure that the breadcrumbs, if any, were created.

open Unit

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

open Unit
showBreadCrumbs(title: CharSequence!, shortTitle: CharSequence!)

Change the base title of the bread crumbs for the current preferences.

open Unit

Start a new fragment.

open Unit
startPreferencePanel(fragmentClass: String!, args: Bundle!, titleRes: Int, titleText: CharSequence!, resultTo: Fragment!, resultRequestCode: Int)

Start a new fragment containing a preference panel.

open Unit
startWithFragment(fragmentName: String!, args: Bundle!, resultTo: Fragment!, resultRequestCode: Int)

Like startWithFragment(java.lang.String,android.os.Bundle,android.app.Fragment,int,int,int) but uses a 0 titleRes.

open Unit
startWithFragment(fragmentName: String!, args: Bundle!, resultTo: Fragment!, resultRequestCode: Int, titleRes: Int, shortTitleRes: Int)

Start a new instance of this activity, showing only the given preference fragment.

open Unit
switchToHeader(fragmentName: String!, args: Bundle!)

When in two-pane mode, switch the fragment pane to show the given preference fragment.

open Unit

When in two-pane mode, switch to the fragment pane to show the given preference fragment.

Protected methods
open Boolean
isValidFragment(fragmentName: String!)

Subclasses should override this method and verify that the given fragment is a valid type to be attached to this activity.

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

open Unit
onCreate(savedInstanceState: Bundle?)

Called when the activity is starting.

open Unit

open Unit
onListItemClick(l: ListView!, v: View!, position: Int, id: Long)

open Unit
onNewIntent(intent: Intent!)

open Unit

open Unit

open Unit

Inherited functions
Inherited properties

Constants

EXTRA_NO_HEADERS

Added in API level 11
Deprecated in API level 29
static val EXTRA_NO_HEADERS: String

Deprecated: Deprecated in Java.

When starting this activity, the invoking Intent can contain this extra boolean that the header list should not be displayed. This is most often used in conjunction with EXTRA_SHOW_FRAGMENT to launch the activity to display a specific fragment that the user has navigated to.

Value: ":android:no_headers"

EXTRA_SHOW_FRAGMENT

Added in API level 11
Deprecated in API level 29
static val EXTRA_SHOW_FRAGMENT: String

Deprecated: Deprecated in Java.

When starting this activity, the invoking Intent can contain this extra string to specify which fragment should be initially displayed.

Starting from Key Lime Pie, when this argument is passed in, the PreferenceActivity will call isValidFragment() to confirm that the fragment class name is valid for this activity.
Value: ":android:show_fragment"

EXTRA_SHOW_FRAGMENT_ARGUMENTS

Added in API level 11
Deprecated in API level 29
static val EXTRA_SHOW_FRAGMENT_ARGUMENTS: String

Deprecated: Deprecated in Java.

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specified to supply a Bundle of arguments to pass to that fragment when it is instantiated during the initial creation of PreferenceActivity.

Value: ":android:show_fragment_args"

EXTRA_SHOW_FRAGMENT_SHORT_TITLE

Added in API level 14
Deprecated in API level 29
static val EXTRA_SHOW_FRAGMENT_SHORT_TITLE: String

Deprecated: Deprecated in Java.

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specify to supply the short title to be shown for that fragment.

Value: ":android:show_fragment_short_title"

EXTRA_SHOW_FRAGMENT_TITLE

Added in API level 14
Deprecated in API level 29
static val EXTRA_SHOW_FRAGMENT_TITLE: String

Deprecated: Deprecated in Java.

When starting this activity and using EXTRA_SHOW_FRAGMENT, this extra can also be specify to supply the title to be shown for that fragment.

Value: ":android:show_fragment_title"

HEADER_ID_UNDEFINED

Added in API level 11
Deprecated in API level 29
static val HEADER_ID_UNDEFINED: Long

Deprecated: Deprecated in Java.

Default value for Header.id indicating that no identifier value is set. All other values (including those below -1) are valid.

Value: -1L

Public constructors

PreferenceActivity

PreferenceActivity()

Public methods

addPreferencesFromIntent

Added in API level 1
Deprecated in API level 15
open fun addPreferencesFromIntent(intent: Intent!): Unit

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

Adds preferences from activities that match the given Intent.

Parameters
intent Intent!: The Intent to query activities.

addPreferencesFromResource

Added in API level 1
Deprecated in API level 15
open fun addPreferencesFromResource(preferencesResId: Int): Unit

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

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 1
Deprecated in API level 15
open fun findPreference(key: CharSequence!): Preference!

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

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.

finishPreferencePanel

Added in API level 11
Deprecated in API level 29
open fun finishPreferencePanel(
    caller: Fragment!,
    resultCode: Int,
    resultData: Intent!
): Unit

Deprecated: Deprecated in Java.

Called by a preference panel fragment to finish itself.

Parameters
caller Fragment!: The fragment that is asking to be finished.
resultCode Int: Optional result code to send back to the original launching fragment.
resultData Intent!: Optional result data to send back to the original launching fragment.

getPreferenceManager

Added in API level 1
Deprecated in API level 15
open fun getPreferenceManager(): PreferenceManager!

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

Returns the PreferenceManager used by this activity.

Return
PreferenceManager! The PreferenceManager.

getPreferenceScreen

Added in API level 1
Deprecated in API level 15
open fun getPreferenceScreen(): PreferenceScreen!

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

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

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

hasHeaders

Added in API level 11
Deprecated in API level 29
open fun hasHeaders(): Boolean

Deprecated: Deprecated in Java.

Returns true if this activity is currently showing the header list.

invalidateHeaders

Added in API level 11
Deprecated in API level 29
open fun invalidateHeaders(): Unit

Deprecated: Deprecated in Java.

Call when you need to change the headers being displayed. Will result in onBuildHeaders() later being called to retrieve the new list.

isMultiPane

Added in API level 11
Deprecated in API level 29
open fun isMultiPane(): Boolean

Deprecated: Deprecated in Java.

Returns true if this activity is showing multiple panes -- the headers and a preference fragment.

loadHeadersFromResource

Added in API level 11
Deprecated in API level 29
open fun loadHeadersFromResource(
    resid: Int,
    target: MutableList<PreferenceActivity.Header!>!
): Unit

Deprecated: Deprecated in Java.

Parse the given XML file as a header description, adding each parsed Header into the target list.

Parameters
resid Int: The XML resource to load and parse.
target MutableList<PreferenceActivity.Header!>!: The list in which the parsed headers should be placed.

onBackPressed

Added in API level 5
Deprecated in API level 29
open fun onBackPressed(): Unit

Deprecated: Deprecated in Java.

onBuildHeaders

Added in API level 11
Deprecated in API level 29
open fun onBuildHeaders(target: MutableList<PreferenceActivity.Header!>!): Unit

Deprecated: Deprecated in Java.

Called when the activity needs its list of headers build. By implementing this and adding at least one item to the list, you will cause the activity to run in its modern fragment mode. Note that this function may not always be called; for example, if the activity has been asked to display a particular fragment without the header list, there is no need to build the headers.

Typical implementations will use loadHeadersFromResource to fill in the list from a resource.

Parameters
target MutableList<PreferenceActivity.Header!>!: The list in which to place the headers.

onBuildStartFragmentIntent

Added in API level 14
Deprecated in API level 29
open fun onBuildStartFragmentIntent(
    fragmentName: String!,
    args: Bundle!,
    titleRes: Int,
    shortTitleRes: Int
): Intent!

Deprecated: Deprecated in Java.

Called by startWithFragment(java.lang.String,android.os.Bundle,android.app.Fragment,int,int,int) when in single-pane mode, to build an Intent to launch a new activity showing the selected fragment. The default implementation constructs an Intent that re-launches the current activity with the appropriate arguments to display the fragment.

Parameters
fragmentName String!: The name of the fragment to display.
args Bundle!: Optional arguments to supply to the fragment.
titleRes Int: Optional resource ID of title to show for this item.
shortTitleRes Int: Optional resource ID of short title to show for this item.
Return
Intent! Returns an Intent that can be launched to display the given fragment.

onContentChanged

Added in API level 1
open fun onContentChanged(): Unit

Deprecated: Deprecated in Java.

onGetInitialHeader

Added in API level 11
Deprecated in API level 29
open fun onGetInitialHeader(): PreferenceActivity.Header!

Deprecated: Deprecated in Java.

Called to determine the initial header to be shown. The default implementation simply returns the fragment of the first header. Note that the returned Header object does not actually need to exist in your header list -- whatever its fragment is will simply be used to show for the initial UI.

onGetNewHeader

Added in API level 11
Deprecated in API level 29
open fun onGetNewHeader(): PreferenceActivity.Header!

Deprecated: Deprecated in Java.

Called after the header list has been updated (onBuildHeaders has been called and returned due to invalidateHeaders()) to specify the header that should now be selected. The default implementation returns null to keep whatever header is currently selected.

onHeaderClick

Added in API level 11
Deprecated in API level 29
open fun onHeaderClick(
    header: PreferenceActivity.Header!,
    position: Int
): Unit

Deprecated: Deprecated in Java.

Called when the user selects an item in the header list. The default implementation will call either startWithFragment(java.lang.String,android.os.Bundle,android.app.Fragment,int,int,int) or switchToHeader(android.preference.PreferenceActivity.Header) as appropriate.

Parameters
header PreferenceActivity.Header!: The header that was selected.
position Int: The header's position in the list.

onIsHidingHeaders

Added in API level 11
Deprecated in API level 29
open fun onIsHidingHeaders(): Boolean

Deprecated: Deprecated in Java.

Called to determine whether the header list should be hidden. The default implementation returns the value given in EXTRA_NO_HEADERS or false if it is not supplied. This is set to false, for example, when the activity is being re-launched to show a particular preference activity.

onIsMultiPane

Added in API level 11
Deprecated in API level 29
open fun onIsMultiPane(): Boolean

Deprecated: Deprecated in Java.

Called to determine if the activity should run in multi-pane mode. The default implementation returns true if the screen is large enough.

onOptionsItemSelected

Added in API level 1
open fun onOptionsItemSelected(item: MenuItem): Boolean

Deprecated: Deprecated in Java.

Parameters
item MenuItem: The menu item that was selected. This value cannot be null.
Return
Boolean boolean Return false to allow normal menu processing to proceed, true to consume it here.

onPreferenceStartFragment

Added in API level 11
Deprecated in API level 29
open fun onPreferenceStartFragment(
    caller: PreferenceFragment!,
    pref: Preference!
): Boolean

Deprecated: Deprecated in Java.

onPreferenceTreeClick

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

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

setListFooter

Added in API level 11
Deprecated in API level 29
open fun setListFooter(view: View!): Unit

Deprecated: Deprecated in Java.

Set a footer that should be shown at the bottom of the header list.

setParentTitle

Added in API level 11
Deprecated in API level 29
open fun setParentTitle(
    title: CharSequence!,
    shortTitle: CharSequence!,
    listener: View.OnClickListener!
): Unit

Deprecated: Deprecated in Java.

Should be called after onCreate to ensure that the breadcrumbs, if any, were created. This prepends a title to the fragment breadcrumbs and attaches a listener to any clicks on the parent entry.

Parameters
title CharSequence!: the title for the breadcrumb
shortTitle CharSequence!: the short title for the breadcrumb

setPreferenceScreen

Added in API level 1
Deprecated in API level 15
open fun setPreferenceScreen(preferenceScreen: PreferenceScreen!): Unit

Deprecated: This function is not relevant for a modern fragment-based PreferenceActivity.

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

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

showBreadCrumbs

Added in API level 11
Deprecated in API level 29
open fun showBreadCrumbs(
    title: CharSequence!,
    shortTitle: CharSequence!
): Unit

Deprecated: Deprecated in Java.

Change the base title of the bread crumbs for the current preferences. This will normally be called for you. See android.app.FragmentBreadCrumbs for more information.

startPreferenceFragment

Added in API level 11
Deprecated in API level 29
open fun startPreferenceFragment(
    fragment: Fragment!,
    push: Boolean
): Unit

Deprecated: Deprecated in Java.

Start a new fragment.

Parameters
fragment Fragment!: The fragment to start
push Boolean: If true, the current fragment will be pushed onto the back stack. If false, the current fragment will be replaced.

startPreferencePanel

Added in API level 11
Deprecated in API level 29
open fun startPreferencePanel(
    fragmentClass: String!,
    args: Bundle!,
    titleRes: Int,
    titleText: CharSequence!,
    resultTo: Fragment!,
    resultRequestCode: Int
): Unit

Deprecated: Deprecated in Java.

Start a new fragment containing a preference panel. If the preferences are being displayed in multi-pane mode, the given fragment class will be instantiated and placed in the appropriate pane. If running in single-pane mode, a new activity will be launched in which to show the fragment.

Parameters
fragmentClass String!: Full name of the class implementing the fragment.
args Bundle!: Any desired arguments to supply to the fragment.
titleRes Int: Optional resource identifier of the title of this fragment.
titleText CharSequence!: Optional text of the title of this fragment.
resultTo Fragment!: Optional fragment that result data should be sent to. If non-null, resultTo.onActivityResult() will be called when this preference panel is done. The launched panel must use finishPreferencePanel(android.app.Fragment,int,android.content.Intent) when done.
resultRequestCode Int: If resultTo is non-null, this is the caller's request code to be received with the result.

startWithFragment

Added in API level 11
Deprecated in API level 29
open fun startWithFragment(
    fragmentName: String!,
    args: Bundle!,
    resultTo: Fragment!,
    resultRequestCode: Int
): Unit

Deprecated: Deprecated in Java.

Like startWithFragment(java.lang.String,android.os.Bundle,android.app.Fragment,int,int,int) but uses a 0 titleRes.

startWithFragment

Added in API level 14
Deprecated in API level 29
open fun startWithFragment(
    fragmentName: String!,
    args: Bundle!,
    resultTo: Fragment!,
    resultRequestCode: Int,
    titleRes: Int,
    shortTitleRes: Int
): Unit

Deprecated: Deprecated in Java.

Start a new instance of this activity, showing only the given preference fragment. When launched in this mode, the header list will be hidden and the given preference fragment will be instantiated and fill the entire activity.

Parameters
fragmentName String!: The name of the fragment to display.
args Bundle!: Optional arguments to supply to the fragment.
resultTo Fragment!: Option fragment that should receive the result of the activity launch.
resultRequestCode Int: If resultTo is non-null, this is the request code in which to report the result.
titleRes Int: Resource ID of string to display for the title of this set of preferences.
shortTitleRes Int: Resource ID of string to display for the short title of this set of preferences.

switchToHeader

Added in API level 11
Deprecated in API level 29
open fun switchToHeader(
    fragmentName: String!,
    args: Bundle!
): Unit

Deprecated: Deprecated in Java.

When in two-pane mode, switch the fragment pane to show the given preference fragment.

Parameters
fragmentName String!: The name of the fragment to display.
args Bundle!: Optional arguments to supply to the fragment.

switchToHeader

Added in API level 11
Deprecated in API level 29
open fun switchToHeader(header: PreferenceActivity.Header!): Unit

Deprecated: Deprecated in Java.

When in two-pane mode, switch to the fragment pane to show the given preference fragment.

Parameters
header PreferenceActivity.Header!: The new header to display.

Protected methods

isValidFragment

Added in API level 19
Deprecated in API level 29
protected open fun isValidFragment(fragmentName: String!): Boolean

Deprecated: Deprecated in Java.

Subclasses should override this method and verify that the given fragment is a valid type to be attached to this activity. The default implementation returns true for apps built for android:targetSdkVersion older than android.os.Build.VERSION_CODES#KITKAT. For later versions, it will throw an exception.

Parameters
fragmentName String!: the class name of the Fragment about to be attached to this activity.
Return
Boolean true if the fragment class name is valid for this Activity and false otherwise.

onActivityResult

Added in API level 1
protected 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 1
protected open fun onCreate(savedInstanceState: Bundle?): Unit

Deprecated: Deprecated in Java.

Called when the activity is starting. This is where most initialization should go: calling setContentView(int) to inflate the activity's UI, using findViewById to programmatically interact with widgets in the UI, calling managedQuery(android.net.Uri,java.lang.String[],java.lang.String,java.lang.String[],java.lang.String) to retrieve cursors for data being displayed, etc.

You can call finish from within this function, in which case onDestroy() will be immediately called after #onCreate without any of the rest of the activity lifecycle (onStart, onResume, onPause, etc) executing.

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.


This method must be called from the main thread of your app.
If you override this method you must call through to the superclass implementation.
Parameters
savedInstanceState Bundle?: This value may be null.

onDestroy

Added in API level 1
protected open fun onDestroy(): Unit

Deprecated: Deprecated in Java.

onListItemClick

Added in API level 1
protected open fun onListItemClick(
    l: ListView!,
    v: View!,
    position: Int,
    id: Long
): Unit

Deprecated: Deprecated in Java.

Parameters
l ListView!: The ListView where the click happened
v View!: The view that was clicked within the ListView
position Int: The position of the view in the list
id Long: The row id of the item that was clicked

onNewIntent

Added in API level 1
protected open fun onNewIntent(intent: Intent!): Unit

Deprecated: Deprecated in Java.

Parameters
intent Intent!: The new intent that was used to start the activity

onRestoreInstanceState

Added in API level 1
protected open fun onRestoreInstanceState(state: Bundle): Unit

Deprecated: Deprecated in Java.

Parameters
savedInstanceState the data most recently supplied in #onSaveInstanceState. This value cannot be null.

onSaveInstanceState

Added in API level 1
protected open fun onSaveInstanceState(outState: Bundle): Unit

Deprecated: Deprecated in Java.

Parameters
outState Bundle: Bundle in which to place your saved state. This value cannot be null.

onStop

Added in API level 1
protected open fun onStop(): Unit

Deprecated: Deprecated in Java.