Android Development Manual
public interface SharedPreferences
| android.content.SharedPreferences |
Interface for accessing and modifying preference data returned by getSharedPreferences(String, int). For any particular set of preferences, there is a single instance of this class that all clients share. Modifications to the preferences must go through an SharedPreferences.Editor object to ensure the preference values remain in a consistent state and control when they are committed to storage. Objects that are returned from the various get methods must be treated as immutable by the application.
Note: This class does not support use across multiple processes.
For more information about using SharedPreferences, read the Data Storage developer guide.
See also:
Nested classes |
|
|---|---|
interface |
SharedPreferences.Editor Interface used for modifying values in a |
interface |
SharedPreferences.OnSharedPreferenceChangeListener Interface definition for a callback to be invoked when a shared preference is changed. |
Public methods |
|
|---|---|
abstract boolean |
contains(String key) Checks whether the preferences contains a preference. |
abstract SharedPreferences.Editor |
edit() Create a new Editor for these preferences, through which you can make modifications to the data in the preferences and atomically commit those changes back to the SharedPreferences object. |
abstract Map<String, ?> |
getAll() Retrieve all values from the preferences. |
abstract boolean |
getBoolean(String key, boolean defValue) Retrieve a boolean value from the preferences. |
abstract float |
getFloat(String key, float defValue) Retrieve a float value from the preferences. |
abstract int |
getInt(String key, int defValue) Retrieve an int value from the preferences. |
abstract long |
getLong(String key, long defValue) Retrieve a long value from the preferences. |
abstract String |
getString(String key, String defValue) Retrieve a String value from the preferences. |
abstract Set<String> |
getStringSet(String key, Set<String> defValues) Retrieve a set of String values from the preferences. |
abstract void |
registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Registers a callback to be invoked when a change happens to a preference. |
abstract void |
unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Unregisters a previous callback. |
boolean contains (String key)
Checks whether the preferences contains a preference.
| Parameters | |
|---|---|
key |
String: The name of the preference to check. |
| Returns | |
|---|---|
boolean |
Returns true if the preference exists in the preferences, otherwise false. |
SharedPreferences.Editor edit ()
Create a new Editor for these preferences, through which you can make modifications to the data in the preferences and atomically commit those changes back to the SharedPreferences object.
Note that you must call commit() to have any changes you perform in the Editor actually show up in the SharedPreferences.
| Returns | |
|---|---|
SharedPreferences.Editor |
Returns a new instance of the SharedPreferences.Editor interface, allowing you to modify the values in this SharedPreferences object. |
Map<String, ?> getAll ()
Retrieve all values from the preferences.
Note that you must not modify the collection returned by this method, or alter any of its contents. The consistency of your stored data is not guaranteed if you do.
| Returns | |
|---|---|
Map<String, ?> |
Returns a map containing a list of pairs key/value representing the preferences. |
| Throws | |
|---|---|
NullPointerException |
|
boolean getBoolean (String key, boolean defValue)
Retrieve a boolean value from the preferences.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValue |
boolean: Value to return if this preference does not exist. |
| Returns | |
|---|---|
boolean |
Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a boolean. |
| Throws | |
|---|---|
ClassCastException |
|
float getFloat (String key, float defValue)
Retrieve a float value from the preferences.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValue |
float: Value to return if this preference does not exist. |
| Returns | |
|---|---|
float |
Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a float. |
| Throws | |
|---|---|
ClassCastException |
|
int getInt (String key, int defValue)
Retrieve an int value from the preferences.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValue |
int: Value to return if this preference does not exist. |
| Returns | |
|---|---|
int |
Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not an int. |
| Throws | |
|---|---|
ClassCastException |
|
long getLong (String key, long defValue)
Retrieve a long value from the preferences.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValue |
long: Value to return if this preference does not exist. |
| Returns | |
|---|---|
long |
Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a long. |
| Throws | |
|---|---|
ClassCastException |
|
String getString (String key, String defValue)
Retrieve a String value from the preferences.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValue |
String: Value to return if this preference does not exist. |
| Returns | |
|---|---|
String |
Returns the preference value if it exists, or defValue. Throws ClassCastException if there is a preference with this name that is not a String. |
| Throws | |
|---|---|
ClassCastException |
|
Set<String> getStringSet (String key, Set<String> defValues)
Retrieve a set of String values from the preferences.
Note that you must not modify the set instance returned by this call. The consistency of the stored data is not guaranteed if you do, nor is your ability to modify the instance at all.
| Parameters | |
|---|---|
key |
String: The name of the preference to retrieve. |
defValues |
Set: Values to return if this preference does not exist. |
| Returns | |
|---|---|
Set<String> |
Returns the preference values if they exist, or defValues. Throws ClassCastException if there is a preference with this name that is not a Set. |
| Throws | |
|---|---|
ClassCastException |
|
void registerOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)
Registers a callback to be invoked when a change happens to a preference.
Caution: The preference manager does not currently store a strong reference to the listener. You must store a strong reference to the listener, or it will be susceptible to garbage collection. We recommend you keep a reference to the listener in the instance data of an object that will exist as long as you need the listener.
| Parameters | |
|---|---|
listener |
SharedPreferences.OnSharedPreferenceChangeListener: The callback that will run. |
void unregisterOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)
Unregisters a previous callback.
| Parameters | |
|---|---|
listener |
SharedPreferences.OnSharedPreferenceChangeListener: The callback that should be unregistered. |