PreferenceActivity
  public
  
  
  abstract
  class
  PreferenceActivity
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
    extends ListActivity
  
  
  
  
  
      implements
      
        PreferenceFragment.OnPreferenceStartFragmentCallback
      
  
  
| java.lang.Object | ||||||
| ↳ | android.content.Context | |||||
| ↳ | android.content.ContextWrapper | |||||
| ↳ | android.view.ContextThemeWrapper | |||||
| ↳ | android.app.Activity | |||||
| ↳ | android.app.ListActivity | |||||
| ↳ | android.preference.PreferenceActivity | |||||
      This class was deprecated
      in API level 29.
    Use the AndroidX
      
      Preference Library for consistent behavior across all devices. For more information on
      using the AndroidX Preference Library see
      Settings.
  
This is the base class for an activity to show a hierarchy of preferences
 to the user.  Prior to 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(List) 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.
 
Developer Guides
For information about using PreferenceActivity,
 read the Settings
 guide.
Summary
| Nested classes | |
|---|---|
| 
        
        
        
        
        class | PreferenceActivity.HeaderThis class was deprecated in API level 29. Use the AndroidX Preference Library for consistent behavior across all devices. For more information on using the AndroidX Preference Library see Settings. | 
| Constants | |
|---|---|
| String | EXTRA_NO_HEADERSWhen starting this activity, the invoking Intent can contain this extra boolean that the header list should not be displayed. | 
| String | EXTRA_SHOW_FRAGMENTWhen starting this activity, the invoking Intent can contain this extra string to specify which fragment should be initially displayed. | 
| String | EXTRA_SHOW_FRAGMENT_ARGUMENTSWhen starting this activity and using  | 
| String | EXTRA_SHOW_FRAGMENT_SHORT_TITLEWhen starting this activity and using  | 
| String | EXTRA_SHOW_FRAGMENT_TITLEWhen starting this activity and using  | 
| long | HEADER_ID_UNDEFINEDDefault value for  | 
| Inherited constants | 
|---|
| Inherited fields | 
|---|
| Public constructors | |
|---|---|
| 
      PreferenceActivity()
       | |
| Public methods | |
|---|---|
| 
        
        
        
        
        
        void | 
      addPreferencesFromIntent(Intent intent)
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        void | 
      addPreferencesFromResource(int preferencesResId)
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        Preference | 
      findPreference(CharSequence key)
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        void | 
      finishPreferencePanel(Fragment caller, int resultCode, Intent resultData)
      Called by a preference panel fragment to finish itself. | 
| 
        
        
        
        
        
        PreferenceManager | 
      getPreferenceManager()
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        PreferenceScreen | 
      getPreferenceScreen()
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        boolean | 
      hasHeaders()
      Returns true if this activity is currently showing the header list. | 
| 
        
        
        
        
        
        void | 
      invalidateHeaders()
      Call when you need to change the headers being displayed. | 
| 
        
        
        
        
        
        boolean | 
      isMultiPane()
      Returns true if this activity is showing multiple panes -- the headers and a preference fragment. | 
| 
        
        
        
        
        
        void | 
      loadHeadersFromResource(int resid, List<PreferenceActivity.Header> target)
      Parse the given XML file as a header description, adding each parsed Header into the target list. | 
| 
        
        
        
        
        
        void | 
      onBackPressed()
      
      This method was deprecated
      in API level 29.
    Use  
 Starting from Android 13 (API level 33), back event handling is
 moving to an ahead-of-time model and  | 
| 
        
        
        
        
        
        void | 
      onBuildHeaders(List<PreferenceActivity.Header> target)
      Called when the activity needs its list of headers build. | 
| 
        
        
        
        
        
        Intent | 
      onBuildStartFragmentIntent(String fragmentName, Bundle args, int titleRes, int shortTitleRes)
      Called by  | 
| 
        
        
        
        
        
        void | 
      onContentChanged()
      Updates the screen state (current list and other views) when the content changes. | 
| 
        
        
        
        
        
        PreferenceActivity.Header | 
      onGetInitialHeader()
      Called to determine the initial header to be shown. | 
| 
        
        
        
        
        
        PreferenceActivity.Header | 
      onGetNewHeader()
      Called after the header list has been updated ( | 
| 
        
        
        
        
        
        void | 
      onHeaderClick(PreferenceActivity.Header header, int position)
      Called when the user selects an item in the header list. | 
| 
        
        
        
        
        
        boolean | 
      onIsHidingHeaders()
      Called to determine whether the header list should be hidden. | 
| 
        
        
        
        
        
        boolean | 
      onIsMultiPane()
      Called to determine if the activity should run in multi-pane mode. | 
| 
        
        
        
        
        
        boolean | 
      onOptionsItemSelected(MenuItem item)
      This hook is called whenever an item in your options menu is selected. | 
| 
        
        
        
        
        
        boolean | 
      onPreferenceStartFragment(PreferenceFragment caller, Preference pref)
      Called when the user has clicked on a Preference that has a fragment class name associated with it. | 
| 
        
        
        
        
        
        boolean | 
      onPreferenceTreeClick(PreferenceScreen preferenceScreen, Preference preference)
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        void | 
      setListFooter(View view)
      Set a footer that should be shown at the bottom of the header list. | 
| 
        
        
        
        
        
        void | 
      setParentTitle(CharSequence title, CharSequence shortTitle, View.OnClickListener listener)
      Should be called after onCreate to ensure that the breadcrumbs, if any, were created. | 
| 
        
        
        
        
        
        void | 
      setPreferenceScreen(PreferenceScreen preferenceScreen)
      This method was deprecated in API level 15. This function is not relevant for a modern fragment-based PreferenceActivity. | 
| 
        
        
        
        
        
        void | 
      showBreadCrumbs(CharSequence title, CharSequence shortTitle)
      Change the base title of the bread crumbs for the current preferences. | 
| 
        
        
        
        
        
        void | 
      startPreferenceFragment(Fragment fragment, boolean push)
      Start a new fragment. | 
| 
        
        
        
        
        
        void | 
      startPreferencePanel(String fragmentClass, Bundle args, int titleRes, CharSequence titleText, Fragment resultTo, int resultRequestCode)
      Start a new fragment containing a preference panel. | 
| 
        
        
        
        
        
        void | 
      startWithFragment(String fragmentName, Bundle args, Fragment resultTo, int resultRequestCode, int titleRes, int shortTitleRes)
      Start a new instance of this activity, showing only the given preference fragment. | 
| 
        
        
        
        
        
        void | 
      startWithFragment(String fragmentName, Bundle args, Fragment resultTo, int resultRequestCode)
      Like  | 
| 
        
        
        
        
        
        void | 
      switchToHeader(String fragmentName, Bundle args)
      When in two-pane mode, switch the fragment pane to show the given preference fragment. | 
| 
        
        
        
        
        
        void | 
      switchToHeader(PreferenceActivity.Header header)
      When in two-pane mode, switch to the fragment pane to show the given preference fragment. | 
| Protected methods | |
|---|---|
| 
        
        
        
        
        
        boolean | 
      isValidFragment(String fragmentName)
      Subclasses should override this method and verify that the given fragment is a valid type to be attached to this activity. | 
| 
        
        
        
        
        
        void | 
      onActivityResult(int requestCode, int resultCode, Intent data)
      Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it. | 
| 
        
        
        
        
        
        void | 
      onCreate(Bundle savedInstanceState)
      Called when the activity is starting. | 
| 
        
        
        
        
        
        void | 
      onDestroy()
      Perform any final cleanup before an activity is destroyed. | 
| 
        
        
        
        
        
        void | 
      onListItemClick(ListView l, View v, int position, long id)
      This method will be called when an item in the list is selected. | 
| 
        
        
        
        
        
        void | 
      onNewIntent(Intent intent)
      This is called for activities that set launchMode to "singleTop" in
 their package, or if a client used the  | 
| 
        
        
        
        
        
        void | 
      onRestoreInstanceState(Bundle state)
      Ensures the list view has been created before Activity restores all of the view states. | 
| 
        
        
        
        
        
        void | 
      onSaveInstanceState(Bundle outState)
      Called to retrieve per-instance state from an activity before being killed
 so that the state can be restored in  | 
| 
        
        
        
        
        
        void | 
      onStop()
      Called when you are no longer visible to the user. | 
| Inherited methods | |
|---|---|
Constants
EXTRA_NO_HEADERS
public static final String EXTRA_NO_HEADERS
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.
Constant Value: ":android:no_headers"
EXTRA_SHOW_FRAGMENT
public static final String EXTRA_SHOW_FRAGMENT
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.Constant Value: ":android:show_fragment"
EXTRA_SHOW_FRAGMENT_ARGUMENTS
public static final String EXTRA_SHOW_FRAGMENT_ARGUMENTS
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.
Constant Value: ":android:show_fragment_args"
EXTRA_SHOW_FRAGMENT_SHORT_TITLE
public static final String EXTRA_SHOW_FRAGMENT_SHORT_TITLE
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.
Constant Value: ":android:show_fragment_short_title"
EXTRA_SHOW_FRAGMENT_TITLE
public static final String EXTRA_SHOW_FRAGMENT_TITLE
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.
Constant Value: ":android:show_fragment_title"
HEADER_ID_UNDEFINED
public static final long HEADER_ID_UNDEFINED
Default value for Header.id indicating that no
 identifier value is set.  All other values (including those below -1)
 are valid.
Constant Value: -1 (0xffffffffffffffff)
Public constructors
PreferenceActivity
public PreferenceActivity ()
Public methods
addPreferencesFromIntent
public void addPreferencesFromIntent (Intent intent)
      This method was deprecated
      in API level 15.
    This function is not relevant for a modern fragment-based
 PreferenceActivity.
  
Adds preferences from activities that match the given Intent.
| Parameters | |
|---|---|
| intent | Intent: TheIntentto query activities. | 
addPreferencesFromResource
public void addPreferencesFromResource (int preferencesResId)
      This method was deprecated
      in API level 15.
    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
public Preference findPreference (CharSequence key)
      This method was deprecated
      in API level 15.
    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. | 
| Returns | |
|---|---|
| Preference | The Preferencewith the key, or null. | 
finishPreferencePanel
public void finishPreferencePanel (Fragment caller, int resultCode, Intent resultData)
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
public PreferenceManager getPreferenceManager ()
      This method was deprecated
      in API level 15.
    This function is not relevant for a modern fragment-based
 PreferenceActivity.
  
Returns the PreferenceManager used by this activity.
| Returns | |
|---|---|
| PreferenceManager | The PreferenceManager. | 
getPreferenceScreen
public PreferenceScreen getPreferenceScreen ()
      This method was deprecated
      in API level 15.
    This function is not relevant for a modern fragment-based
 PreferenceActivity.
  
Gets the root of the preference hierarchy that this activity is showing.
| Returns | |
|---|---|
| PreferenceScreen | The PreferenceScreenthat is the root of the preference
         hierarchy. | 
hasHeaders
public boolean hasHeaders ()
Returns true if this activity is currently showing the header list.
| Returns | |
|---|---|
| boolean | |
invalidateHeaders
public void invalidateHeaders ()
Call when you need to change the headers being displayed. Will result in onBuildHeaders() later being called to retrieve the new list.
isMultiPane
public boolean isMultiPane ()
Returns true if this activity is showing multiple panes -- the headers and a preference fragment.
| Returns | |
|---|---|
| boolean | |
loadHeadersFromResource
public void loadHeadersFromResource (int resid, 
                List<PreferenceActivity.Header> target)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 | List: The list in which the parsed headers should be placed. | 
onBackPressed
public void onBackPressed ()
      This method was deprecated
      in API level 29.
    Use OnBackInvokedCallback or
 androidx.activity.OnBackPressedCallback to handle back navigation instead.
 
 Starting from Android 13 (API level 33), back event handling is
 moving to an ahead-of-time model and Activity.onBackPressed() and
 KeyEvent.KEYCODE_BACK should not be used to handle back events (back gesture or
 back button click). Instead, an OnBackInvokedCallback should be registered using
 Activity.getOnBackInvokedDispatcher()
 .registerOnBackInvokedCallback(priority, callback).
  
Called when the activity has detected the user's press of the back key. The default implementation depends on the platform version:
- On platform versions prior to Build.VERSION_CODES.S, it finishes the current activity, but you can override this to do whatever you want.
- Starting with platform version - Build.VERSION_CODES.S, for activities that are the root activity of the task and also declare an- IntentFilterwith- Intent.ACTION_MAINand- Intent.CATEGORY_LAUNCHERin the manifest, the current activity and its task will be moved to the back of the activity stack instead of being finished. Other activities will simply be finished.
- If you target version - Build.VERSION_CODES.Sand override this method, we strongly recommend to call through to the superclass implementation after you finish handling navigation within the app.
- If you target version - Build.VERSION_CODES.TIRAMISUor later, you should not use this method but register an- OnBackInvokedCallbackon an- OnBackInvokedDispatcherthat you can retrieve using- getOnBackInvokedDispatcher(). You should also set- android:enableOnBackInvokedCallback="true"in the application manifest.- Alternatively, you can use - androidx.activity.ComponentActivity#getOnBackPressedDispatcher()for backward compatibility.
onBuildHeaders
public void onBuildHeaders (List<PreferenceActivity.Header> target)
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(int, List)
 to fill in the list from a resource.
| Parameters | |
|---|---|
| target | List: The list in which to place the headers. | 
onBuildStartFragmentIntent
public Intent onBuildStartFragmentIntent (String fragmentName, Bundle args, int titleRes, int shortTitleRes)
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. | 
| Returns | |
|---|---|
| Intent | Returns an Intent that can be launched to display the given fragment. | 
onContentChanged
public void onContentChanged ()
Updates the screen state (current list and other views) when the content changes.
onGetInitialHeader
public PreferenceActivity.Header onGetInitialHeader ()
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.
| Returns | |
|---|---|
| PreferenceActivity.Header | |
onGetNewHeader
public PreferenceActivity.Header onGetNewHeader ()
Called after the header list has been updated (onBuildHeaders(List)
 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.
| Returns | |
|---|---|
| PreferenceActivity.Header | |
onHeaderClick
public void onHeaderClick (PreferenceActivity.Header header, int position)
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
public boolean onIsHidingHeaders ()
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.
| Returns | |
|---|---|
| boolean | |
onIsMultiPane
public boolean onIsMultiPane ()
Called to determine if the activity should run in multi-pane mode. The default implementation returns true if the screen is large enough.
| Returns | |
|---|---|
| boolean | |
onOptionsItemSelected
public boolean onOptionsItemSelected (MenuItem item)
This hook is called whenever an item in your options menu is selected. The default implementation simply returns false to have the normal processing happen (calling the item's Runnable or sending a message to its Handler as appropriate). You can use this method for any items for which you would like to do processing without those other facilities.
Derived classes should call through to the base class for it to perform the default menu handling.
| Parameters | |
|---|---|
| item | MenuItem: The menu item that was selected.
 This value cannot benull. | 
| Returns | |
|---|---|
| boolean | boolean Return false to allow normal menu processing to proceed, true to consume it here. | 
onPreferenceStartFragment
public boolean onPreferenceStartFragment (PreferenceFragment caller, Preference pref)
Called when the user has clicked on a Preference that has a fragment class name associated with it. The implementation to should instantiate and switch to an instance of the given fragment.
| Parameters | |
|---|---|
| caller | PreferenceFragment | 
| pref | Preference | 
| Returns | |
|---|---|
| boolean | |
onPreferenceTreeClick
public boolean onPreferenceTreeClick (PreferenceScreen preferenceScreen, Preference preference)
      This method was deprecated
      in API level 15.
    This function is not relevant for a modern fragment-based
 PreferenceActivity.
  
| Parameters | |
|---|---|
| preferenceScreen | PreferenceScreen | 
| preference | Preference | 
| Returns | |
|---|---|
| boolean | |
setListFooter
public void setListFooter (View view)
Set a footer that should be shown at the bottom of the header list.
| Parameters | |
|---|---|
| view | View | 
setParentTitle
public void setParentTitle (CharSequence title, CharSequence shortTitle, View.OnClickListener listener)
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 | 
| listener | View.OnClickListener | 
setPreferenceScreen
public void setPreferenceScreen (PreferenceScreen preferenceScreen)
      This method was deprecated
      in API level 15.
    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 rootPreferenceScreenof the preference hierarchy. | 
showBreadCrumbs
public void showBreadCrumbs (CharSequence title, CharSequence shortTitle)
Change the base title of the bread crumbs for the current preferences.
 This will normally be called for you.  See
 FragmentBreadCrumbs for more information.
| Parameters | |
|---|---|
| title | CharSequence | 
| shortTitle | CharSequence | 
startPreferenceFragment
public void startPreferenceFragment (Fragment fragment, boolean push)
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
public void startPreferencePanel (String fragmentClass, Bundle args, int titleRes, CharSequence titleText, Fragment resultTo, int resultRequestCode)
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 usefinishPreferencePanel(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
public void startWithFragment (String fragmentName, Bundle args, Fragment resultTo, int resultRequestCode, int titleRes, int shortTitleRes)
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. | 
startWithFragment
public void startWithFragment (String fragmentName, Bundle args, Fragment resultTo, int resultRequestCode)
Like startWithFragment(java.lang.String, android.os.Bundle, android.app.Fragment, int, int, int)
 but uses a 0 titleRes.
| Parameters | |
|---|---|
| fragmentName | String | 
| args | Bundle | 
| resultTo | Fragment | 
| resultRequestCode | int | 
switchToHeader
public void switchToHeader (String fragmentName, Bundle args)
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
public void switchToHeader (PreferenceActivity.Header header)
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
protected boolean isValidFragment (String fragmentName)
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
 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. | 
| Returns | |
|---|---|
| boolean | true if the fragment class name is valid for this Activity and false otherwise. | 
onActivityResult
protected void onActivityResult (int requestCode, 
                int resultCode, 
                Intent data)Called when an activity you launched exits, giving you the requestCode
 you started it with, the resultCode it returned, and any additional
 data from it.  The resultCode will be
 RESULT_CANCELED if the activity explicitly returned that,
 didn't return any result, or crashed during its operation.
 
An activity can never receive a result in the resumed state. You can count on
 onResume() being called after this method, though not necessarily immediately after.
 If the activity was resumed, it will be paused and the result will be delivered, followed
 by onResume().  If the activity wasn't in the resumed state, then the result will
 be delivered, with onResume() called sometime later when the activity becomes active
 again.
 
This method is never invoked if your activity sets
 noHistory to
 true.
| 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
protected void onCreate (Bundle savedInstanceState)
Called when the activity is starting.  This is where most initialization
 should go: calling setContentView(int) to inflate the
 activity's UI, using findViewById(int) 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(Bundle) 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 benull. | 
onDestroy
protected void onDestroy ()
Perform any final cleanup before an activity is destroyed.  This can
 happen either because the activity is finishing (someone called
 finish() on it), or because the system is temporarily destroying
 this instance of the activity to save space.  You can distinguish
 between these two scenarios with the isFinishing() method.
 
Note: do not count on this method being called as a place for
 saving data! For example, if an activity is editing data in a content
 provider, those edits should be committed in either onPause() or
 onSaveInstanceState(Bundle), not here. This method is usually implemented to
 free resources like threads that are associated with an activity, so
 that a destroyed activity does not leave such things around while the
 rest of its application is still running.  There are situations where
 the system will simply kill the activity's hosting process without
 calling this method (or any others) in it, so it should not be used to
 do things that are intended to remain around after the process goes
 away.
 
Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.
If you override this method you must call through to the superclass implementation.
onListItemClick
protected void onListItemClick (ListView l, View v, int position, long id)
This method will be called when an item in the list is selected. Subclasses should override. Subclasses can call getListView().getItemAtPosition(position) if they need to access the data associated with the selected item.
| 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
protected void onNewIntent (Intent intent)
This is called for activities that set launchMode to "singleTop" in
 their package, or if a client used the Intent.FLAG_ACTIVITY_SINGLE_TOP
 flag when calling startActivity(Intent).  In either case, when the
 activity is re-launched while at the top of the activity stack instead
 of a new instance of the activity being started, onNewIntent() will be
 called on the existing instance with the Intent that was used to
 re-launch it.
 
An activity can never receive a new intent in the resumed state. You can count on
 onResume() being called after this method, though not necessarily immediately after
 the completion of this callback. If the activity was resumed, it will be paused and new
 intent will be delivered, followed by onResume(). If the activity wasn't in the
 resumed state, then new intent can be delivered immediately, with onResume() called
 sometime later when activity becomes active again.
 
Note that getIntent() still returns the original Intent.  You
 can use setIntent(android.content.Intent) to update it to this new Intent.
| Parameters | |
|---|---|
| intent | Intent: The new intent that was used to start the activity | 
onRestoreInstanceState
protected void onRestoreInstanceState (Bundle state)
Ensures the list view has been created before Activity restores all of the view states.
| Parameters | |
|---|---|
| state | Bundle: the data most recently supplied inonSaveInstanceState(Bundle).
 This value cannot benull. | 
onSaveInstanceState
protected void onSaveInstanceState (Bundle outState)
Called to retrieve per-instance state from an activity before being killed
 so that the state can be restored in onCreate(Bundle) or
 onRestoreInstanceState(Bundle) (the Bundle populated by this method
 will be passed to both).
 
This method is called before an activity may be killed so that when it
 comes back some time in the future it can restore its state.  For example,
 if activity B is launched in front of activity A, and at some point activity
 A is killed to reclaim resources, activity A will have a chance to save the
 current state of its user interface via this method so that when the user
 returns to activity A, the state of the user interface can be restored
 via onCreate(Bundle) or onRestoreInstanceState(Bundle).
 
Do not confuse this method with activity lifecycle callbacks such as onPause(),
 which is always called when the user no longer actively interacts with an activity, or
 onStop() which is called when activity becomes invisible. One example of when
 onPause() and onStop() is called and not this method is when a user navigates
 back from activity B to activity A: there is no need to call onSaveInstanceState(Bundle)
 on B because that particular instance will never be restored,
 so the system avoids calling it.  An example when onPause() is called and
 not onSaveInstanceState(Bundle) is when activity B is launched in front of activity A:
 the system may avoid calling onSaveInstanceState(Bundle) on activity A if it isn't
 killed during the lifetime of B since the state of the user interface of
 A will stay intact.
 
The default implementation takes care of most of the UI per-instance
 state for you by calling View.onSaveInstanceState() on each
 view in the hierarchy that has an id, and by saving the id of the currently
 focused view (all of which is restored by the default implementation of
 onRestoreInstanceState(Bundle)).  If you override this method to save additional
 information not captured by each individual view, you will likely want to
 call through to the default implementation, otherwise be prepared to save
 all of the state of each view yourself.
 
If called, this method will occur after onStop() for applications
 targeting platforms starting with Build.VERSION_CODES.P.
 For applications targeting earlier platform versions this method will occur
 before onStop() and there are no guarantees about whether it will
 occur before or after onPause().
| Parameters | |
|---|---|
| outState | Bundle: Bundle in which to place your saved state.
 This value cannot benull. | 
onStop
protected void onStop ()
Called when you are no longer visible to the user.  You will next
 receive either onRestart(), onDestroy(), or nothing,
 depending on later user activity. This is a good place to stop
 refreshing UI, running animations and other visual things.
 
Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.
If you override this method you must call through to the superclass implementation.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-09-17 UTC.
