android.preference
Class PreferenceManager

java.lang.Object
  android.preference.PreferenceManager

public class PreferenceManager
extends Object

The PreferenceManager is used to help create preference hierarchies from activities or XML.

In most cases, clients should use PreferenceActivity.addPreferencesFromIntent(android.content.Intent) or PreferenceActivity.addPreferencesFromResource(int).

See Also:

PreferenceActivity

Nested Class Summary

static interface	PreferenceManager.OnActivityDestroyListener Interface definition for a class that will be called when the container's activity is destroyed.
static interface	PreferenceManager.OnActivityResultListener Interface definition for a class that will be called when the container's activity receives an activity result.
static interface	PreferenceManager.OnActivityStopListener Interface definition for a class that will be called when the container's activity is stopped.
(package private) static interface	PreferenceManager.OnPreferenceTreeClickListener Interface definition for a callback to be invoked when a Preference in the hierarchy rooted at this PreferenceScreen is clicked.

Field Summary

static String	KEY_HAS_SET_DEFAULT_VALUES
static String	METADATA_KEY_PREFERENCES The Activity meta-data key for its XML preference hierarchy.

Constructor Summary

PreferenceManager(Activity activity, int firstRequestCode)

Method Summary

(package private) void	addPreferencesScreen(DialogInterface screen)
PreferenceScreen	createPreferenceScreen(Context context)
(package private) void	dispatchActivityDestroy() Called by the PreferenceManager to dispatch the activity destroy event.
(package private) void	dispatchActivityResult(int requestCode, int resultCode, Intent data) Called by the PreferenceManager to dispatch a subactivity result.
(package private) void	dispatchActivityStop() Called by the PreferenceManager to dispatch the activity stop event.
(package private) void	dispatchNewIntent(Intent intent) Called by PreferenceActivity to dispatch the new Intent event.
Preference	findPreference(CharSequence key) Finds a Preference based on its key.
(package private) Activity	getActivity() Returns the activity that shows the preferences.
(package private) Context	getContext() Returns the context.
static SharedPreferences	getDefaultSharedPreferences(Context context) Gets a SharedPreferences instance that points to the default file that is used by the preference framework in the given context.
(package private) SharedPreferences.Editor	getEditor() Returns an editor to use when modifying the shared preferences.
(package private) long	getNextId() Called by a preference to get a unique ID in its hierarchy.
(package private) int	getNextRequestCode() Returns a request code that is unique for the activity.
(package private) PreferenceManager.OnPreferenceTreeClickListener	getOnPreferenceTreeClickListener()
(package private) PreferenceScreen	getPreferenceScreen() Returns the root of the preference hierarchy managed by this class.
SharedPreferences	getSharedPreferences() Gets a SharedPreferences instance that preferences managed by this will use.
int	getSharedPreferencesMode() Returns the current mode of the SharedPreferences file that preferences managed by this will use.
String	getSharedPreferencesName() Returns the current name of the SharedPreferences file that preferences managed by this will use.
(package private) PreferenceScreen	inflateFromIntent(Intent queryIntent, PreferenceScreen rootPreferences) Inflates a preference hierarchy from the preference hierarchies of Activities that match the given Intent.
(package private) PreferenceScreen	inflateFromResource(Context context, int resId, PreferenceScreen rootPreferences) Inflates a preference hierarchy from XML.
(package private) void	registerOnActivityDestroyListener(PreferenceManager.OnActivityDestroyListener listener) Registers a listener.
(package private) void	registerOnActivityResultListener(PreferenceManager.OnActivityResultListener listener) Registers a listener.
(package private) void	registerOnActivityStopListener(PreferenceManager.OnActivityStopListener listener) Registers a listener.
(package private) void	removePreferencesScreen(DialogInterface screen)
static void	setDefaultValues(Context context, int resId, boolean readAgain) Sets the default values from a preference hierarchy in XML.
static void	setDefaultValues(Context context, String sharedPreferencesName, int sharedPreferencesMode, int resId, boolean readAgain) Similar to setDefaultValues(Context, int, boolean) but allows the client to provide the filename and mode of the shared preferences file.
(package private) void	setOnPreferenceTreeClickListener(PreferenceManager.OnPreferenceTreeClickListener listener) Sets the callback to be invoked when a Preference in the hierarchy rooted at this PreferenceManager is clicked.
(package private) boolean	setPreferences(PreferenceScreen preferenceScreen) Sets the root of the preference hierarchy.
void	setSharedPreferencesMode(int sharedPreferencesMode) Sets the mode of the SharedPreferences file that preferences managed by this will use.
void	setSharedPreferencesName(String sharedPreferencesName) Sets the name of the SharedPreferences file that preferences managed by this will use.
(package private) boolean	shouldCommit() Whether it is the client's responsibility to commit on the getEditor().
(package private) void	unregisterOnActivityDestroyListener(PreferenceManager.OnActivityDestroyListener listener) Unregisters a listener.
(package private) void	unregisterOnActivityResultListener(PreferenceManager.OnActivityResultListener listener) Unregisters a listener.
(package private) void	unregisterOnActivityStopListener(PreferenceManager.OnActivityStopListener listener) Unregisters a listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

METADATA_KEY_PREFERENCES

public static final String METADATA_KEY_PREFERENCES

The Activity meta-data key for its XML preference hierarchy.

See Also:

Constant Field Values

KEY_HAS_SET_DEFAULT_VALUES

public static final String KEY_HAS_SET_DEFAULT_VALUES

See Also:

Constant Field Values

Constructor Detail

PreferenceManager

PreferenceManager(Activity activity,
                  int firstRequestCode)

Method Detail

inflateFromIntent

PreferenceScreen inflateFromIntent(Intent queryIntent,
                                   PreferenceScreen rootPreferences)

Inflates a preference hierarchy from the preference hierarchies of Activities that match the given Intent. An Activity defines its preference hierarchy with meta-data using the METADATA_KEY_PREFERENCES key.

If a preference hierarchy is given, the new preference hierarchies will be merged in.

Parameters:

queryIntent - The intent to match activities.

rootPreferences - Optional existing hierarchy to merge the new hierarchies into.

Returns:

The root hierarchy (if one was not provided, the new hierarchy's root).

inflateFromResource

PreferenceScreen inflateFromResource(Context context,
                                     int resId,
                                     PreferenceScreen rootPreferences)

Inflates a preference hierarchy from XML. If a preference hierarchy is given, the new preference hierarchies will be merged in.

Parameters:

context - The context of the resource.

resId - The resource ID of the XML to inflate.

rootPreferences - Optional existing hierarchy to merge the new hierarchies into.

Returns:

The root hierarchy (if one was not provided, the new hierarchy's root).

createPreferenceScreen

public PreferenceScreen createPreferenceScreen(Context context)

getNextId

long getNextId()

Called by a preference to get a unique ID in its hierarchy.

Returns:

A unique ID.

getSharedPreferencesName

public String getSharedPreferencesName()

Returns the current name of the SharedPreferences file that preferences managed by this will use.

Returns:

The name that can be passed to Context.getSharedPreferences(String, int).

See Also:

Context.getSharedPreferences(String, int)

setSharedPreferencesName

public void setSharedPreferencesName(String sharedPreferencesName)

Sets the name of the SharedPreferences file that preferences managed by this will use.

Parameters:

sharedPreferencesName - The name of the SharedPreferences file.

See Also:

Context.getSharedPreferences(String, int)

getSharedPreferencesMode

public int getSharedPreferencesMode()

Returns the current mode of the SharedPreferences file that preferences managed by this will use.

Returns:

The mode that can be passed to Context.getSharedPreferences(String, int).

See Also:

Context.getSharedPreferences(String, int)

setSharedPreferencesMode

public void setSharedPreferencesMode(int sharedPreferencesMode)

Sets the mode of the SharedPreferences file that preferences managed by this will use.

Parameters:

sharedPreferencesMode - The mode of the SharedPreferences file.

See Also:

Context.getSharedPreferences(String, int)

getSharedPreferences

public SharedPreferences getSharedPreferences()

Gets a SharedPreferences instance that preferences managed by this will use.

Returns:

A SharedPreferences instance pointing to the file that contains the values of preferences that are managed by this.

getDefaultSharedPreferences

public static SharedPreferences getDefaultSharedPreferences(Context context)

Gets a SharedPreferences instance that points to the default file that is used by the preference framework in the given context.

Parameters:

context - The context of the preferences whose values are wanted.

Returns:

A SharedPreferences instance that can be used to retrieve and listen to values of the preferences.

getPreferenceScreen

PreferenceScreen getPreferenceScreen()

Returns the root of the preference hierarchy managed by this class.

Returns:

The PreferenceScreen object that is at the root of the hierarchy.

setPreferences

boolean setPreferences(PreferenceScreen preferenceScreen)

Sets the root of the preference hierarchy.

Parameters:

preferenceScreen - The root PreferenceScreen of the preference hierarchy.

Returns:

Whether the PreferenceScreen given is different than the previous.

findPreference

public Preference findPreference(CharSequence key)

Finds a Preference based on its key.

Parameters:

key - The key of the preference to retrieve.

Returns:

The Preference with the key, or null.

See Also:

PreferenceGroup.findPreference(CharSequence)

setDefaultValues

public static void setDefaultValues(Context context,
                                    int resId,
                                    boolean readAgain)

Sets the default values from a preference hierarchy in XML. This should be called by the application's main activity.

If readAgain is false, this will only set the default values if this method has never been called in the past (or the KEY_HAS_SET_DEFAULT_VALUES in the default value shared preferences file is false). To attempt to set the default values again bypassing this check, set readAgain to true.

Parameters:

context - The context of the shared preferences.

resId - The resource ID of the preference hierarchy XML file.

readAgain - Whether to re-read the default values.

Note: this will NOT reset preferences back to their default values. For that functionality, use getDefaultSharedPreferences(Context) and clear it followed by a call to this method with this parameter set to true.

setDefaultValues

public static void setDefaultValues(Context context,
                                    String sharedPreferencesName,
                                    int sharedPreferencesMode,
                                    int resId,
                                    boolean readAgain)

Similar to setDefaultValues(Context, int, boolean) but allows the client to provide the filename and mode of the shared preferences file.

See Also:

setDefaultValues(Context, int, boolean), setSharedPreferencesName(String), setSharedPreferencesMode(int)

getEditor

SharedPreferences.Editor getEditor()

Returns an editor to use when modifying the shared preferences.

Do NOT commit unless shouldCommit() returns true.

Returns:

An editor to use to write to shared preferences.

See Also:

shouldCommit()

shouldCommit

boolean shouldCommit()

Whether it is the client's responsibility to commit on the getEditor(). This will return false in cases where the writes should be batched, for example when inflating preferences from XML.

Returns:

Whether the client should commit.

getActivity

Activity getActivity()

Returns the activity that shows the preferences. This is useful for doing managed queries, but in most cases the use of getContext() is preferred.

This will return null if this class was instantiated with a Context instead of Activity. For example, when setting the default values.

Returns:

The activity that shows the preferences.

See Also:

mContext

getContext

Context getContext()

Returns the context. This is preferred over getActivity() when possible.

Returns:

The context.

registerOnActivityResultListener

void registerOnActivityResultListener(PreferenceManager.OnActivityResultListener listener)

Registers a listener.

See Also:

PreferenceManager.OnActivityResultListener

unregisterOnActivityResultListener

void unregisterOnActivityResultListener(PreferenceManager.OnActivityResultListener listener)

Unregisters a listener.

See Also:

PreferenceManager.OnActivityResultListener

dispatchActivityResult

void dispatchActivityResult(int requestCode,
                            int resultCode,
                            Intent data)

Called by the PreferenceManager to dispatch a subactivity result.

registerOnActivityStopListener

void registerOnActivityStopListener(PreferenceManager.OnActivityStopListener listener)

Registers a listener.

See Also:

PreferenceManager.OnActivityStopListener

unregisterOnActivityStopListener

void unregisterOnActivityStopListener(PreferenceManager.OnActivityStopListener listener)

Unregisters a listener.

See Also:

PreferenceManager.OnActivityStopListener

dispatchActivityStop

void dispatchActivityStop()

Called by the PreferenceManager to dispatch the activity stop event.

registerOnActivityDestroyListener

void registerOnActivityDestroyListener(PreferenceManager.OnActivityDestroyListener listener)

Registers a listener.

See Also:

PreferenceManager.OnActivityDestroyListener

unregisterOnActivityDestroyListener

void unregisterOnActivityDestroyListener(PreferenceManager.OnActivityDestroyListener listener)

Unregisters a listener.

See Also:

PreferenceManager.OnActivityDestroyListener

dispatchActivityDestroy

void dispatchActivityDestroy()

Called by the PreferenceManager to dispatch the activity destroy event.

getNextRequestCode

int getNextRequestCode()

Returns a request code that is unique for the activity. Each subsequent call to this method should return another unique request code.

Returns:

A unique request code that will never be used by anyone other than the caller of this method.

addPreferencesScreen

void addPreferencesScreen(DialogInterface screen)

removePreferencesScreen

void removePreferencesScreen(DialogInterface screen)

dispatchNewIntent

void dispatchNewIntent(Intent intent)

Called by PreferenceActivity to dispatch the new Intent event.

Parameters:

intent - The new Intent.

setOnPreferenceTreeClickListener

void setOnPreferenceTreeClickListener(PreferenceManager.OnPreferenceTreeClickListener listener)

Sets the callback to be invoked when a Preference in the hierarchy rooted at this PreferenceManager is clicked.

Parameters:

listener - The callback to be invoked.

getOnPreferenceTreeClickListener

PreferenceManager.OnPreferenceTreeClickListener getOnPreferenceTreeClickListener()