Android中的共享设置（SharedPreferences）

官方网址：http://developer.android.com/reference/android/content/SharedPreferences.html
源码路径：frameworks\base\core\java\android\content\SharedPreferences.java
/** * 访问和修改由getSharedPreferences返回的设置数据的接口。 * 对任意特定的设置集，只有一个该类的实例，所有客户共享。 * 修改设置，必须通过Editor对象，以此来确保设置的值是一致的和控制提交时存储； * 通过各种get方法返回的对象，在应用中必须视为不可变（immutable）的。 * 注：目前该类不支持跨进程使用，这个特性以后会添加的。 * * 更多使用SharedPreferences的信息，请阅读Data Storage的开发指南。 * 参见Context#getSharedPreferences */public interface SharedPreferences {    /**     * 定义一个回调的接口，当设置改变时被调用     */    public interface OnSharedPreferenceChangeListener {        /**         * 当设置被改变，添加，删除时，被调用。         * 甚至当设置项被设置了它的已经存在的值时，它可能也会被调用。         *         * 该回调只会在主线程里运行         *         * @param sharedPreferences 接收到改变消息的设置         * @param key 被改变，添加或删除的设置项的键值（key）         */        void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key);    }        /**     * 修改共享设置对象中的值的接口。     * 编辑器（editor）中所有的改变，是分批处理的；不会拷贝到原设置，直到你调用commit或apply     */    public interface Editor {        /**         * 在编辑器中，设置一个字符串；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param value 设置项的新值；该项置null等同于调用remove(String)         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor putString(String key, String value);                /**         * 在编辑器中，设置一组字符串；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param values 设置项的一组新值；该项置null等同于调用remove(String)         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor putStringSet(String key, Set<String> values);                /**         * 在编辑器中，设置一个整型值（int）；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param value 设置项的新值         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor putInt(String key, int value);                /**         * 在编辑器中，设置一个长整型（long）值；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param value 设置项的新值         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor putLong(String key, long value);                /**         * 在编辑器中，设置一个浮点（float）值；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param value 设置项的新值         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor putFloat(String key, float value);                /**         * 在编辑器中，设置一个布尔（boolean）值；当调用commit或apply后，才会写回。         * @param key 要修改的设置项的名称         * @param value 设置项的新值         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */         */        Editor putBoolean(String key, boolean value);        /**         * 在编辑器中，标记将要删除的设置项；当调用commit时，它才会实际完成。         * 注意：当提交给设置时，所有的删除操作会被首先执行；         * 而不会管你是在put操作的之前或之后调用remove。         * @param key 要删除的设置项的名称         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor remove(String key);        /**         * 在编辑器中，标记清空设置中的所有值。         * 调用commit后，在编辑器中，仅仅剩下你之前定义的一些项。         * 注意：当提交给设置时，所有的清空操作会被首先执行；         * 而不会管你是在put操作的之前或之后调用clear         * @return 返回一个设置项，给同一个编辑器，因此，可以链式调用。         */        Editor clear();        /**         * 将编辑器中的对设置项的修改，提交给正在修改的共享设置对象。         * 这个会自动执行修改或替换或其他任何请求。         * 注意：当两个编辑器，同时修改设置项时，最后提交的那个会胜出。         * 如果你不关心返回值，并且你在应用的主线程里使用它，建议你用apply来替代它。         * @return 如果新值被成功写入存储器中，返回true         */        boolean commit();        /**         * 将编辑器中的对设置项的修改，提交给正在修改的设置（SharedPreferences）对象。         * 这个会自动执行修改或替换或其他任何请求。         * 注意：当两个编辑器，同时修改设置项时，最后提交的那个会胜出。         * 不同于commit的同步向存储器写设置项，apply在内存中即时提交修改，         * 但往磁盘上提交却是异步的，并且任何失败都不会通知你。         * 如果当apply还未完成时，该共享设置的另一个编辑器执行了commit操作时，         * 该commit操作将被阻塞，直到所有异步的提交都完成，和它自身提交一样。         * 因为进程中的共享设置的实例是单一的，因此，用apply替代commit是安全的，         * 如果你不关心返回值的话。         * 你不用担心Android组件的生命周期和它们用apply写磁盘的相互影响         * 系统框架确保用apply在写磁盘完成后，才切换状态。          * 共享设置的编辑器接口(SharedPreferences.Editor)最好不要直接实现；         * 然后，如果你之前已经实现了它，并且现在因缺少apply而出错了，         * 你可以在apply中，简单的调用commit。         */        void apply();    }    /**     * 获取设置项的所有值。     * 注意：这个方法返回的集合，你不能修改它或者修改它的任何内容。     * 如果你修改了，就无法保证你存储的数据的一致性了。     * @return 返回一个包含键值对列表的MAP集合     * @throws 抛出NullPointerException异常     */    Map<String, ?> getAll();    /**     * 从设置项中获取字符串的值     * @param key 要获取值的设置项的名称     * @param defValue 当设置项不存在时的默认值     * @return 如果设置项存在，则返回其值，否则返回默认值。     * 如果同名的设置项不是字符串类型的，则抛出ClassCastException异常     */    String getString(String key, String defValue);        /**     * 从设置项中获取一组字符串的值     * 注意：你不能修改本次调用返回的集合实例。     * 如果你修改了，就无法保证你存储的数据的一致性了；你根本就没能力修改它。     * @param key 要获取值的设置项的名称     * @param defValues 当设置项不存在时的默认值     * @return 如果设置项存在，则返回其值，否则返回默认值。     * 如果同名的设置项不是集合，则抛出ClassCastException异常     */    Set<String> getStringSet(String key, Set<String> defValues);        /**     * 从设置项中获取整型值     * @param key 要获取值的设置项的名称     * @param defValues 当设置项不存在时的默认值     * @return 如果设置项存在，则返回其值，否则返回默认值。     * 如果同名的设置项不是整型，则抛出ClassCastException异常     */    int getInt(String key, int defValue);        /**     * 从设置项中获取长整型值     * @param key 要获取值的设置项的名称     * @param defValues 当设置项不存在时的默认值     * 如果同名的设置项不是长整型，则抛出ClassCastException异常     */    long getLong(String key, long defValue);        /**     * 从设置项中获取浮点型值     * @param key 要获取值的设置项的名称     * @param defValues 当设置项不存在时的默认值     * 如果同名的设置项不是浮点型，则抛出ClassCastException异常     */    float getFloat(String key, float defValue);        /**     * 从设置项中获取布尔型值     * @param key 要获取值的设置项的名称     * @param defValues 当设置项不存在时的默认值     * 如果同名的设置项不是布尔型，则抛出ClassCastException异常     */    boolean getBoolean(String key, boolean defValue);    /**     * 检查该设置是否包含设置项     * @param key 设置项的名称     * @return 如果存在，返回true；否则，返回false。     */    boolean contains(String key);        /**     * 为该设置创建一个新的编辑器，你可以通过它对设置中的数据做修改，     * 并且可以将这些修改，自动提交回共享设置对象。     * 注意：你务必调用Editor#commit，这样你在编辑器中的修改，才能在共享设置中生效     * @return 返回一个新的编辑器实例，它允许你修改共享设置对象中的值。     */    Editor edit();        /**     * 注册一个回调，但设置项改变时，会被调用到。     * @param listener 将会被执行的回调（监听器）     * @see #unregisterOnSharedPreferenceChangeListener     */    void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);        /**     * 注销之前的回调     * @param listener 将要被注销的回调     * @see #registerOnSharedPreferenceChangeListener     */    void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);}
更多相关文章

随机推荐
