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 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport java.util.Map; 20212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powellimport java.util.Set; 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface for accessing and modifying preference data returned by {@link 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Context#getSharedPreferences}. For any particular set of preferences, 259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * there is a single instance of this class that all clients share. 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Modifications to the preferences must go through an {@link Editor} object 279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to ensure the preference values remain in a consistent state and control 289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * when they are committed to storage. 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p><em>Note: currently this class does not support use across multiple 319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * processes. This will be added later.</em> 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3361fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <div class="special reference"> 3461fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <h3>Developer Guides</h3> 3561fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <p>For more information about using SharedPreferences, read the 3661fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Data Storage</a> 3761fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * developer guide.</p></div> 3861fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * 399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see Context#getSharedPreferences 409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic interface SharedPreferences { 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface definition for a callback to be invoked when a shared 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preference is changed. 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public interface OnSharedPreferenceChangeListener { 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Called when a shared preference is changed, added, or removed. This 499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * may be called even if a preference is set to its existing value. 50333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * 51333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * <p>This callback will be run on your main thread. 52333b8cba996c8ebb8ca55ebfc5cc536bdd64af94Brad Fitzpatrick * 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param sharedPreferences The {@link SharedPreferences} that received 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the change. 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The key of the preference that was changed, added, or 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * removed. 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key); 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Interface used for modifying values in a {@link SharedPreferences} 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * object. All changes you make in an editor are batched, and not copied 6466fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * back to the original {@link SharedPreferences} until you call {@link #commit} 6566fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * or {@link #apply} 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public interface Editor { 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a String value in the preferences editor, to be written back once 7066fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putString(String key, String value); 799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 81212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Set a set of String values in the preferences editor, to be written 82212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * back once {@link #commit} is called. 83212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 84212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param key The name of the preference to modify. 85212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param values The new values for the preference. 86212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @return Returns a reference to the same Editor object, so you can 87212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * chain put calls together. 88212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell */ 89212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell Editor putStringSet(String key, Set<String> values); 90212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell 91212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell /** 929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set an int value in the preferences editor, to be written back once 9366fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putInt(String key, int value); 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a long value in the preferences editor, to be written back once 10566fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 1069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putLong(String key, long value); 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a float value in the preferences editor, to be written back once 11766fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * {@link #commit} or {@link #apply} are called. 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putFloat(String key, float value); 1269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Set a boolean value in the preferences editor, to be written back 12966fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * once {@link #commit} or {@link #apply} are called. 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to modify. 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param value The new value for the preference. 1339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor putBoolean(String key, boolean value); 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Mark in the editor that a preference value should be removed, which 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be done in the actual preferences once {@link #commit} is 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * called. 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when committing back to the preferences, all removals 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * are done first, regardless of whether you called remove before 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or after put methods on this editor. 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to remove. 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor remove(String key); 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Mark in the editor to remove <em>all</em> values from the 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * preferences. Once commit is called, the only remaining preferences 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * will be any that you have defined in this editor. 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when committing back to the preferences, the clear 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * is done first, regardless of whether you called clear before 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or after put methods on this editor. 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a reference to the same Editor object, so you can 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * chain put calls together. 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor clear(); 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Commit your preferences changes back from this Editor to the 1719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link SharedPreferences} object it is editing. This atomically 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * performs the requested modifications, replacing whatever is currently 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * in the SharedPreferences. 174edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that when two editors are modifying preferences at the same 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * time, the last one to call commit wins. 177edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 178edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>If you don't care about the return value and you're 179edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * using this from your application's main thread, consider 18066fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * using {@link #apply} instead. 181edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the new values were successfully written 1839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * to persistent storage. 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean commit(); 186edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick 187edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick /** 188edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * Commit your preferences changes back from this Editor to the 189edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} object it is editing. This atomically 190edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * performs the requested modifications, replacing whatever is currently 191edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * in the SharedPreferences. 192edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 193edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>Note that when two editors are modifying preferences at the same 19466fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * time, the last one to call apply wins. 195edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 196edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * <p>Unlike {@link #commit}, which writes its preferences out 19766fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * to persistent storage synchronously, {@link #apply} 198edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * commits its changes to the in-memory 199edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} immediately but starts an 200edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * asynchronous commit to disk and you won't be notified of 201edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * any failures. If another editor on this 202edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link SharedPreferences} does a regular {@link #commit} 20366fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick * while a {@link #apply} is still outstanding, the 204edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * {@link #commit} will block until all async commits are 205edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * completed as well as the commit itself. 206edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick * 207dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p>As {@link SharedPreferences} instances are singletons within 208dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * a process, it's safe to replace any instance of {@link #commit} with 209dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * {@link #apply} if you were already ignoring the return value. 210dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * 211dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p>You don't need to worry about Android component 212dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * lifecycles and their interaction with <code>apply()</code> 213dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * writing to disk. The framework makes sure in-flight disk 214dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * writes from <code>apply()</code> complete before switching 215dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * states. 216dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * 217dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * <p class='note'>The SharedPreferences.Editor interface 218dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * isn't expected to be implemented directly. However, if you 219dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * previously did implement it and are now getting errors 220dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * about missing <code>apply()</code>, you can simply call 221dd644c179c1bf47d82d776d7f644e4fc1467159dBrad Fitzpatrick * {@link #commit} from <code>apply()</code>. 222edf32d01316bd3432c023f17747461b08ae36375Brad Fitzpatrick */ 22366fce5068a8a3aeb28aaf713843891b286a75280Brad Fitzpatrick void apply(); 2249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 2259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve all values from the preferences. 2289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a map containing a list of pairs key/value representing 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the preferences. 2319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws NullPointerException 2339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Map<String, ?> getAll(); 2359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a String value from the preferences. 2389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a String. 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 2479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project String getString(String key, String defValue); 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 251212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Retrieve a set of String values from the preferences. 252212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 253212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param key The name of the preference to retrieve. 254212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @param defValues Values to return if this preference does not exist. 255212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 256212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @return Returns the preference values if they exist, or defValues. 257212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * Throws ClassCastException if there is a preference with this name 258212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * that is not a Set. 259212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * 260212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell * @throws ClassCastException 261212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell */ 262212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell Set<String> getStringSet(String key, Set<String> defValues); 263212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell 264212db7d3f8ce5297f4a556234a9c0675c697f1cfAdam Powell /** 2659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve an int value from the preferences. 2669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 2729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * an int. 2739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 2759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project int getInt(String key, int defValue); 2779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a long value from the preferences. 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a long. 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project long getLong(String key, long defValue); 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 2939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a float value from the preferences. 2949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 2969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 2979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 2989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 2999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 3009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a float. 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 3039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project float getFloat(String key, float defValue); 3059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Retrieve a boolean value from the preferences. 3089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to retrieve. 3109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param defValue Value to return if this preference does not exist. 3119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns the preference value if it exists, or defValue. Throws 3139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * ClassCastException if there is a preference with this name that is not 3149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a boolean. 3159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws ClassCastException 3179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean getBoolean(String key, boolean defValue); 3199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Checks whether the preferences contains a preference. 3229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param key The name of the preference to check. 3249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns true if the preference exists in the preferences, 3259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * otherwise false. 3269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project boolean contains(String key); 3289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Create a new Editor for these preferences, through which you can make 3319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * modifications to the data in the preferences and atomically commit those 3329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * changes back to the SharedPreferences object. 3339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p>Note that you <em>must</em> call {@link Editor#commit} to have any 3359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * changes you perform in the Editor actually show up in the 3369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * SharedPreferences. 3379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return Returns a new instance of the {@link Editor} interface, allowing 3399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you to modify the values in this SharedPreferences object. 3409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Editor edit(); 3429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Registers a callback to be invoked when a change happens to a preference. 3459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param listener The callback that will run. 3479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #unregisterOnSharedPreferenceChangeListener 3489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 3509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 3529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unregisters a previous callback. 3539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 3549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param listener The callback that should be unregistered. 3559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see #registerOnSharedPreferenceChangeListener 3569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener); 3589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 359