19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2006 The Android Open Source Project 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you may not use this file except in compliance with the License. 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * You may obtain a copy of the License at 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * See the License for the specific language governing permissions and 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * limitations under the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.content; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 192333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedyimport android.annotation.Nullable; 202333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport java.util.Map; 22212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powellimport java.util.Set; 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface for accessing and modifying preference data returned by {@link 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context#getSharedPreferences}. For any particular set of preferences, 279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * there is a single instance of this class that all clients share. 289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Modifications to the preferences must go through an {@link Editor} object 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to ensure the preference values remain in a consistent state and control 3001ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * when they are committed to storage. Objects that are returned from the 3101ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * various <code>get</code> methods must be treated as immutable by the application. 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 33868ed48c1342425921b807ffc4446a369cd95f45Ryan Lothian * <p><em>Note: This class does not support use across multiple processes.</em> 349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3561fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <div class="special reference"> 3661fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <h3>Developer Guides</h3> 3761fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <p>For more information about using SharedPreferences, read the 3861fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Data Storage</a> 3961fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * developer guide.</p></div> 4061fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see Context#getSharedPreferences 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic interface SharedPreferences { 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface definition for a callback to be invoked when a shared 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preference is changed. 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public interface OnSharedPreferenceChangeListener { 499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when a shared preference is changed, added, or removed. This 519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * may be called even if a preference is set to its existing value. 52333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * 53333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * <p>This callback will be run on your main thread. 54333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param sharedPreferences The {@link SharedPreferences} that received 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the change. 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The key of the preference that was changed, added, or 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * removed. 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key); 619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface used for modifying values in a {@link SharedPreferences} 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * object. All changes you make in an editor are batched, and not copied 6666fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * back to the original {@link SharedPreferences} until you call {@link #commit} 6766fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * or {@link #apply} 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public interface Editor { 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a String value in the preferences editor, to be written back once 7266fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 75fb48521f41ef780bb305bf2f9819e7e018885197Mark Lu * @param value The new value for the preference. Passing {@code null} 76fb48521f41ef780bb305bf2f9819e7e018885197Mark Lu * for this argument is equivalent to calling {@link #remove(String)} with 77fb48521f41ef780bb305bf2f9819e7e018885197Mark Lu * this key. 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 822333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy Editor putString(String key, @Nullable String value); 839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 85212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Set a set of String values in the preferences editor, to be written 86c8b055aa8b406a4f10e1962ec0ec7d4131fe9d7dBrian Williammee * back once {@link #commit} or {@link #apply} is called. 87212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 88212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param key The name of the preference to modify. 899a413f8ffa74bf00333a9ace75b890bdeb7a8c2dChristopher Tate * @param values The set of new values for the preference. Passing {@code null} 909a413f8ffa74bf00333a9ace75b890bdeb7a8c2dChristopher Tate * for this argument is equivalent to calling {@link #remove(String)} with 919a413f8ffa74bf00333a9ace75b890bdeb7a8c2dChristopher Tate * this key. 92212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @return Returns a reference to the same Editor object, so you can 93212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * chain put calls together. 94212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell */ 952333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy Editor putStringSet(String key, @Nullable Set<String> values); 96212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell 97212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell /** 989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set an int value in the preferences editor, to be written back once 9966fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putInt(String key, int value); 1089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a long value in the preferences editor, to be written back once 11166fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putLong(String key, long value); 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a float value in the preferences editor, to be written back once 12366fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 1249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putFloat(String key, float value); 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a boolean value in the preferences editor, to be written back 13566fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * once {@link #commit} or {@link #apply} are called. 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putBoolean(String key, boolean value); 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Mark in the editor that a preference value should be removed, which 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be done in the actual preferences once {@link #commit} is 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * called. 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when committing back to the preferences, all removals 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * are done first, regardless of whether you called remove before 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or after put methods on this editor. 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to remove. 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor remove(String key); 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Mark in the editor to remove <em>all</em> values from the 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preferences. Once commit is called, the only remaining preferences 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be any that you have defined in this editor. 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when committing back to the preferences, the clear 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * is done first, regardless of whether you called clear before 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or after put methods on this editor. 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor clear(); 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Commit your preferences changes back from this Editor to the 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SharedPreferences} object it is editing. This atomically 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * performs the requested modifications, replacing whatever is currently 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in the SharedPreferences. 180edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when two editors are modifying preferences at the same 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * time, the last one to call commit wins. 183edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 184edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>If you don't care about the return value and you're 185edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * using this from your application's main thread, consider 18666fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * using {@link #apply} instead. 187edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the new values were successfully written 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to persistent storage. 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean commit(); 192edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick 193edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick /** 194edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * Commit your preferences changes back from this Editor to the 195edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} object it is editing. This atomically 196edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * performs the requested modifications, replacing whatever is currently 197edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * in the SharedPreferences. 198edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 199edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>Note that when two editors are modifying preferences at the same 20066fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * time, the last one to call apply wins. 201edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 202edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>Unlike {@link #commit}, which writes its preferences out 20366fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * to persistent storage synchronously, {@link #apply} 204edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * commits its changes to the in-memory 205edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} immediately but starts an 206edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * asynchronous commit to disk and you won't be notified of 207edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * any failures. If another editor on this 208edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} does a regular {@link #commit} 20966fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * while a {@link #apply} is still outstanding, the 210edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link #commit} will block until all async commits are 211edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * completed as well as the commit itself. 212edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 213dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p>As {@link SharedPreferences} instances are singletons within 214dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * a process, it's safe to replace any instance of {@link #commit} with 215dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * {@link #apply} if you were already ignoring the return value. 216dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * 217dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p>You don't need to worry about Android component 218dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * lifecycles and their interaction with <code>apply()</code> 219dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * writing to disk. The framework makes sure in-flight disk 220dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * writes from <code>apply()</code> complete before switching 221dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * states. 222dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * 223dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p class='note'>The SharedPreferences.Editor interface 224dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * isn't expected to be implemented directly. However, if you 225dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * previously did implement it and are now getting errors 226dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * about missing <code>apply()</code>, you can simply call 227dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * {@link #commit} from <code>apply()</code>. 228edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick */ 22966fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick void apply(); 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve all values from the preferences. 2349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 23501ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * <p>Note that you <em>must not</em> modify the collection returned 23601ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * by this method, or alter any of its contents. The consistency of your 23701ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * stored data is not guaranteed if you do. 23801ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * 2399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a map containing a list of pairs key/value representing 2409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the preferences. 2419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws NullPointerException 2439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Map<String, ?> getAll(); 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a String value from the preferences. 2489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 2549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a String. 2559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 2579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2582333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy @Nullable 2592333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy String getString(String key, @Nullable String defValue); 2609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 262212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Retrieve a set of String values from the preferences. 263212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 26401ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * <p>Note that you <em>must not</em> modify the set instance returned 26501ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * by this call. The consistency of the stored data is not guaranteed 26601ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * if you do, nor is your ability to modify the instance at all. 26701ed79c5786c527628544828abf8b70d02b989cdChristopher Tate * 268212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param key The name of the preference to retrieve. 269212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param defValues Values to return if this preference does not exist. 270212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 271212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @return Returns the preference values if they exist, or defValues. 272212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Throws ClassCastException if there is a preference with this name 273212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * that is not a Set. 274212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 275212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @throws ClassCastException 276212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell */ 2772333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy @Nullable 2782333e3406c1742d0755b4a80daaf717aa50cd1e5Scott Kennedy Set<String> getStringSet(String key, @Nullable Set<String> defValues); 279212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell 280212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell /** 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve an int value from the preferences. 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * an int. 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project int getInt(String key, int defValue); 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a long value from the preferences. 2969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 3029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a long. 3039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 3059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project long getLong(String key, long defValue); 3079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a float value from the preferences. 3109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 3129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 3139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 3159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 3169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a float. 3179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 3199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project float getFloat(String key, float defValue); 3219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a boolean value from the preferences. 3249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 3269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 3279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 3299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 3309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a boolean. 3319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 3339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean getBoolean(String key, boolean defValue); 3359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Checks whether the preferences contains a preference. 3389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to check. 3409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the preference exists in the preferences, 3419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * otherwise false. 3429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean contains(String key); 3449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Create a new Editor for these preferences, through which you can make 3479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * modifications to the data in the preferences and atomically commit those 3489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * changes back to the SharedPreferences object. 3499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that you <em>must</em> call {@link Editor#commit} to have any 3519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * changes you perform in the Editor actually show up in the 3529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * SharedPreferences. 3539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a new instance of the {@link Editor} interface, allowing 3559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you to modify the values in this SharedPreferences object. 3569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor edit(); 3589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Registers a callback to be invoked when a change happens to a preference. 361de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * 362de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * <p class="caution"><strong>Caution:</strong> The preference manager does 363de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * not currently store a strong reference to the listener. You must store a 364de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * strong reference to the listener, or it will be susceptible to garbage 365de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * collection. We recommend you keep a reference to the listener in the 366de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * instance data of an object that will exist as long as you need the 367de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * listener.</p> 368de0c99e89bfe2df43e363f2521c55d5da166ddadAndrew Solovay * 3699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param listener The callback that will run. 3709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #unregisterOnSharedPreferenceChangeListener 3719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 3739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unregisters a previous callback. 3769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param listener The callback that should be unregistered. 3789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #registerOnSharedPreferenceChangeListener 3799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 3819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 382