Developers
Most visited
Recently visited
SharedPreferences
public
interface
SharedPreferences
| android.content.SharedPreferences |
Interface for accessing and modifying preference data returned by Context.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 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 provides strong consistency guarantees. It is using expensive operations
which might slow down an app. Frequently changing properties or properties where loss can be
tolerated should use other mechanisms. For more details read the comments on
Editor#commit() and Editor#apply().
Note: This class does not support use across multiple processes.
Developer Guides
For more information about using SharedPreferences, read the Data Storage developer guide.
Summary
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. |
Public methods
contains
public abstract 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. |
edit
public 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.
Note that you must call Editor#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 Editor interface, allowing
you to modify the values in this SharedPreferences object. |
getAll
public abstract 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 | |
|---|---|
|
java.lang.NullPointerException |
getBoolean
public abstract 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 | |
|---|---|
|
java.lang.ClassCastException |
getFloat
public abstract 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 | |
|---|---|
|
java.lang.ClassCastException |
getInt
public abstract 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 | |
|---|---|
|
java.lang.ClassCastException |
getLong
public abstract 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 | |
|---|---|
|
java.lang.ClassCastException |
getString
public abstract 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.
This value may be null. |
| 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.
This value may be null. |
| Throws | |
|---|---|
|
java.lang.ClassCastException |
getStringSet
public abstract 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.
This value may be null. |
| 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.
This value may be null. |
| Throws | |
|---|---|
|
java.lang.ClassCastException |
registerOnSharedPreferenceChangeListener
public abstract 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. |
unregisterOnSharedPreferenceChangeListener
public abstract void unregisterOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)
Unregisters a previous callback.
| Parameters | |
|---|---|
listener |
SharedPreferences.OnSharedPreferenceChangeListener: The callback that should be unregistered. |