/* * Copyright (C) 2006 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.content; import java.util.Map; import java.util.Set; /** * Interface for accessing and modifying preference data returned by {@link * Context#getSharedPreferences}. 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 {@link Editor} object * to ensure the preference values remain in a consistent state and control * when they are committed to storage. * *
Note: currently this class does not support use across multiple * processes. This will be added later. * * @see Context#getSharedPreferences */ public interface SharedPreferences { /** * Interface definition for a callback to be invoked when a shared * preference is changed. */ public interface OnSharedPreferenceChangeListener { /** * Called when a shared preference is changed, added, or removed. This * may be called even if a preference is set to its existing value. * *
This callback will be run on your main thread.
*
* @param sharedPreferences The {@link SharedPreferences} that received
* the change.
* @param key The key of the preference that was changed, added, or
* removed.
*/
void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key);
}
/**
* Interface used for modifying values in a {@link SharedPreferences}
* object. All changes you make in an editor are batched, and not copied
* back to the original {@link SharedPreferences} until you call {@link #commit}
* or {@link #apply}
*/
public interface Editor {
/**
* Set a String value in the preferences editor, to be written back once
* {@link #commit} or {@link #apply} are called.
*
* @param key The name of the preference to modify.
* @param value The new value for the preference.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putString(String key, String value);
/**
* Set a set of String values in the preferences editor, to be written
* back once {@link #commit} is called.
*
* @param key The name of the preference to modify.
* @param values The new values for the preference.
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor putStringSet(String key, Set Note that when committing back to the preferences, all removals
* are done first, regardless of whether you called remove before
* or after put methods on this editor.
*
* @param key The name of the preference to remove.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor remove(String key);
/**
* Mark in the editor to remove all values from the
* preferences. Once commit is called, the only remaining preferences
* will be any that you have defined in this editor.
*
* Note that when committing back to the preferences, the clear
* is done first, regardless of whether you called clear before
* or after put methods on this editor.
*
* @return Returns a reference to the same Editor object, so you can
* chain put calls together.
*/
Editor clear();
/**
* Commit your preferences changes back from this Editor to the
* {@link SharedPreferences} object it is editing. This atomically
* performs the requested modifications, replacing whatever is currently
* in the SharedPreferences.
*
* Note that when two editors are modifying preferences at the same
* time, the last one to call commit wins.
*
* If you don't care about the return value and you're
* using this from your application's main thread, consider
* using {@link #apply} instead.
*
* @return Returns true if the new values were successfully written
* to persistent storage.
*/
boolean commit();
/**
* Commit your preferences changes back from this Editor to the
* {@link SharedPreferences} object it is editing. This atomically
* performs the requested modifications, replacing whatever is currently
* in the SharedPreferences.
*
* Note that when two editors are modifying preferences at the same
* time, the last one to call apply wins.
*
* Unlike {@link #commit}, which writes its preferences out
* to persistent storage synchronously, {@link #apply}
* commits its changes to the in-memory
* {@link SharedPreferences} immediately but starts an
* asynchronous commit to disk and you won't be notified of
* any failures. If another editor on this
* {@link SharedPreferences} does a regular {@link #commit}
* while a {@link #apply} is still outstanding, the
* {@link #commit} will block until all async commits are
* completed as well as the commit itself.
*
* As {@link SharedPreferences} instances are singletons within
* a process, it's safe to replace any instance of {@link #commit} with
* {@link #apply} if you were already ignoring the return value.
*
* You don't need to worry about Android component
* lifecycles and their interaction with The SharedPreferences.Editor interface
* isn't expected to be implemented directly. However, if you
* previously did implement it and are now getting errors
* about missing Note that you must call {@link Editor#commit} to have any
* changes you perform in the Editor actually show up in the
* SharedPreferences.
*
* @return Returns a new instance of the {@link Editor} interface, allowing
* you to modify the values in this SharedPreferences object.
*/
Editor edit();
/**
* Registers a callback to be invoked when a change happens to a preference.
*
* @param listener The callback that will run.
* @see #unregisterOnSharedPreferenceChangeListener
*/
void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
/**
* Unregisters a previous callback.
*
* @param listener The callback that should be unregistered.
* @see #registerOnSharedPreferenceChangeListener
*/
void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
}
apply()
* writing to disk. The framework makes sure in-flight disk
* writes from apply()
complete before switching
* states.
*
* apply()
, you can simply call
* {@link #commit} from apply()
.
*/
void apply();
}
/**
* Retrieve all values from the preferences.
*
* @return Returns a map containing a list of pairs key/value representing
* the preferences.
*
* @throws NullPointerException
*/
Map