1page.title=Saving Key-Value Sets
2page.tags=data storage
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9
10<div id="tb-wrapper">
11<div id="tb">
12
13<h2>This lesson teaches you to</h2>
14<ol>
15  <li><a href="#GetSharedPreferences">Get a Handle to a SharedPreferences</a></li>
16  <li><a href="#WriteSharedPreference">Write to Shared Preferences</a></li>
17  <li><a href="#ReadSharedPreference">Read from Shared Preferences</a></li>
18</ol>
19
20<h2>You should also read</h2>
21<ul>
22  <li><a href="{@docRoot}guide/topics/data/data-storage.html#pref">Using Shared Preferences</a></li>
23</ul>
24
25</div>
26</div>
27
28
29<p>If you have a relatively small collection of key-values that you'd like to save,
30you should use the {@link android.content.SharedPreferences} APIs.
31A {@link android.content.SharedPreferences} object points to a file containing
32key-value pairs and provides simple methods to read and write them. Each
33{@link android.content.SharedPreferences} file is
34managed by the framework and can be private or shared.</p>
35
36<p>This class shows you how to use the {@link android.content.SharedPreferences} APIs to store and
37retrieve simple values.</p>
38
39<p class="note"><strong>Note:</strong> The {@link android.content.SharedPreferences} APIs are
40only for reading and writing key-value pairs and you should not confuse them with the
41{@link android.preference.Preference} APIs, which help you build a user interface
42for your app settings (although they use {@link android.content.SharedPreferences} as their
43implementation to save the app settings). For information about using the {@link
44android.preference.Preference} APIs, see the <a href="{@docRoot}guide/topics/ui/settings.html"
45>Settings</a> guide.</p>
46
47<h2 id="GetSharedPreferences">Get a Handle to a SharedPreferences</h2>
48
49<p>You can create a new shared preference file or access an existing
50one by calling one of two methods:</p>
51<ul>
52  <li>{@link android.content.Context#getSharedPreferences(String,int)
53getSharedPreferences()} &mdash; Use this if you need multiple shared preference files identified
54by name, which you specify with the first parameter. You can call this from any
55{@link android.content.Context} in your app.</li>
56  <li>{@link android.app.Activity#getPreferences(int) getPreferences()} &mdash; Use this from an
57{@link android.app.Activity} if you need
58to use only one shared preference file for the activity. Because this retrieves a default shared
59preference file that belongs to the activity, you don't need to supply a name.</li>
60</ul>
61
62<p>For example, the following code is executed inside a {@link android.app.Fragment}.
63It accesses the shared preferences file that's
64identified by the resource string {@code R.string.preference_file_key} and opens it using
65the private mode so the file is accessible by only your app.</p>
66
67<pre>
68Context context = getActivity();
69SharedPreferences sharedPref = context.getSharedPreferences(
70        getString(R.string.preference_file_key), Context.MODE_PRIVATE);
71</pre>
72
73<p>When naming your shared preference files, you should use a name that's uniquely identifiable
74to your app, such as {@code "com.example.myapp.PREFERENCE_FILE_KEY"}</p>
75
76<p>Alternatively, if you need just one shared preference file for your activity, you can use the
77{@link android.app.Activity#getPreferences(int) getPreferences()} method:</p>
78
79<pre>
80SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
81</pre>
82
83<p class="caution"><strong>Caution:</strong> If you create a shared preferences file
84with {@link android.content.Context#MODE_WORLD_READABLE} or {@link
85android.content.Context#MODE_WORLD_WRITEABLE}, then any other apps that know the file identifier
86can access your data.</p>
87
88
89<h2 id="WriteSharedPreference">Write to Shared Preferences</h2>
90
91<p>To write to a shared preferences file, create a {@link
92android.content.SharedPreferences.Editor} by calling {@link
93android.content.SharedPreferences#edit} on your {@link android.content.SharedPreferences}.</p>
94
95<p>Pass the keys and values you want to write with methods such as {@link
96android.content.SharedPreferences.Editor#putInt putInt()} and {@link
97android.content.SharedPreferences.Editor#putString putString()}. Then call {@link
98android.content.SharedPreferences.Editor#commit} to save the changes. For example:</p>
99
100<pre>
101SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
102SharedPreferences.Editor editor = sharedPref.edit();
103editor.putInt(getString(R.string.saved_high_score), newHighScore);
104editor.commit();
105</pre>
106
107
108<h2 id="ReadSharedPreference">Read from Shared Preferences</h2>
109
110<p>To retrieve values from a shared preferences file, call methods such as {@link
111android.content.SharedPreferences#getInt getInt()} and {@link
112android.content.SharedPreferences#getString getString()}, providing the key for the value
113you want, and optionally a default value to return if the key isn't
114present. For example:</p>
115
116<pre>
117SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
118int defaultValue = getResources().getInteger(R.string.saved_high_score_default);
119long highScore = sharedPref.getInt(getString(R.string.saved_high_score), defaultValue);
120</pre>
121
122