1page.title=Handling Runtime Changes
2page.tags=activity,lifecycle
3@jd:body
4
5<div id="qv-wrapper">
6<div id="qv">
7
8  <h2>In this document</h2>
9  <ol>
10    <li><a href="#RetainingAnObject">Retaining an Object During a Configuration Change</a></li>
11    <li><a href="#HandlingTheChange">Handling the Configuration Change Yourself</a>
12  </ol>
13
14  <h2>See also</h2>
15  <ol>
16    <li><a href="providing-resources.html">Providing Resources</a></li>
17    <li><a href="accessing-resources.html">Accessing Resources</a></li>
18    <li><a href="http://android-developers.blogspot.com/2009/02/faster-screen-orientation-change.html">Faster
19        Screen Orientation Change</a></li>
20  </ol>
21</div>
22</div>
23
24<p>Some device configurations can change during runtime
25(such as screen orientation, keyboard availability, and language). When such a change occurs,
26Android restarts the running
27{@link android.app.Activity} ({@link android.app.Activity#onDestroy()} is called, followed by {@link
28android.app.Activity#onCreate(Bundle) onCreate()}). The restart behavior is designed to help your
29application adapt to new configurations by automatically reloading your application with
30alternative resources that match the new device configuration.</p>
31
32<p>To properly handle a restart, it is important that your activity restores its previous
33state through the normal <a
34href="{@docRoot}guide/components/activities.html#Lifecycle">Activity
35lifecycle</a>, in which Android calls
36{@link android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} before it destroys
37your activity so that you can save data about the application state. You can then restore the state
38during {@link android.app.Activity#onCreate(Bundle) onCreate()} or {@link
39android.app.Activity#onRestoreInstanceState(Bundle) onRestoreInstanceState()}.</p>
40
41<p>To test that your application restarts itself with the application state intact, you should
42invoke configuration changes (such as changing the screen orientation) while performing various
43tasks in your application. Your application should be able to restart at any time without loss of
44user data or state in order to handle events such as configuration changes or when the user receives
45an incoming phone call and then returns to your application much later after your application
46process may have been destroyed. To learn how you can restore your activity state, read about the <a
47href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>.</p>
48
49<p>However, you might encounter a situation in which restarting your application and
50restoring significant amounts of data can be costly and create a poor user experience. In such a
51situation, you have two other options:</p>
52
53<ol type="a">
54  <li><a href="#RetainingAnObject">Retain an object during a configuration change</a>
55  <p>Allow your activity to restart when a configuration changes, but carry a stateful
56object to the new instance of your activity.</p>
57
58  </li>
59  <li><a href="#HandlingTheChange">Handle the configuration change yourself</a>
60  <p>Prevent the system from restarting your activity during certain configuration
61changes, but receive a callback when the configurations do change, so that you can manually update
62your activity as necessary.</p>
63  </li>
64</ol>
65
66
67<h2 id="RetainingAnObject">Retaining an Object During a Configuration Change</h2>
68
69<p>If restarting your activity requires that you recover large sets of data, re-establish a network
70connection, or perform other intensive operations, then a full restart due to a configuration change
71might be a slow user experience. Also, it might not be possible for you to completely restore your
72activity state with the {@link android.os.Bundle} that the system saves for you with the {@link
73android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} callback&mdash;it is not
74designed to carry large objects (such as bitmaps) and the data within it must be serialized then
75deserialized, which can consume a lot of memory and make the configuration change slow. In such a
76situation, you can alleviate the burden of reinitializing your activity by retaining a {@link
77android.app.Fragment} when your activity is restarted due to a configuration change. This fragment
78can contain references to stateful objects that you want to retain.</p>
79
80<p>When the Android system shuts down your activity due to a configuration change, the fragments
81of your activity that you have marked to retain are not destroyed. You can add such fragments to
82your activity to preserve stateful objects.</p>
83
84<p>To retain stateful objects in a fragment during a runtime configuration change:</p>
85
86<ol>
87  <li>Extend the {@link android.app.Fragment} class and declare references to your stateful
88      objects.</li>
89  <li>Call {@link android.app.Fragment#setRetainInstance(boolean)} when the fragment is created.
90      </li>
91  <li>Add the fragment to your activity.</li>
92  <li>Use {@link android.app.FragmentManager} to retrieve the fragment when the activity is
93      restarted.</li>
94</ol>
95
96<p>For example, define your fragment as follows:</p>
97
98<pre>
99public class RetainedFragment extends Fragment {
100
101    // data object we want to retain
102    private MyDataObject data;
103
104    // this method is only called once for this fragment
105    &#64;Override
106    public void onCreate(Bundle savedInstanceState) {
107        super.onCreate(savedInstanceState);
108        // retain this fragment
109        setRetainInstance(true);
110    }
111
112    public void setData(MyDataObject data) {
113        this.data = data;
114    }
115
116    public MyDataObject getData() {
117        return data;
118    }
119}
120</pre>
121
122<p class="caution"><strong>Caution:</strong> While you can store any object, you
123should never pass an object that is tied to the {@link android.app.Activity}, such as a {@link
124android.graphics.drawable.Drawable}, an {@link android.widget.Adapter}, a {@link android.view.View}
125or any other object that's associated with a {@link android.content.Context}. If you do, it will
126leak all the views and resources of the original activity instance. (Leaking resources
127means that your application maintains a hold on them and they cannot be garbage-collected, so
128lots of memory can be lost.)</p>
129
130<p>Then use {@link android.app.FragmentManager} to add the fragment to the activity.
131You can obtain the data object from the fragment when the activity starts again during runtime
132configuration changes. For example, define your activity as follows:</p>
133
134<pre>
135public class MyActivity extends Activity {
136
137    private RetainedFragment dataFragment;
138
139    &#64;Override
140    public void onCreate(Bundle savedInstanceState) {
141        super.onCreate(savedInstanceState);
142        setContentView(R.layout.main);
143
144        // find the retained fragment on activity restarts
145        FragmentManager fm = getFragmentManager();
146        dataFragment = (DataFragment) fm.findFragmentByTag(“data”);
147
148        // create the fragment and data the first time
149        if (dataFragment == null) {
150            // add the fragment
151            dataFragment = new DataFragment();
152            fm.beginTransaction().add(dataFragment, “data”).commit();
153            // load the data from the web
154            dataFragment.setData(loadMyData());
155        }
156
157        // the data is available in dataFragment.getData()
158        ...
159    }
160
161    &#64;Override
162    public void onDestroy() {
163        super.onDestroy();
164        // store the data in the fragment
165        dataFragment.setData(collectMyLoadedData());
166    }
167}
168</pre>
169
170<p>In this example, {@link android.app.Activity#onCreate(Bundle) onCreate()} adds a fragment
171or restores a reference to it. {@link android.app.Activity#onCreate(Bundle) onCreate()} also
172stores the stateful object inside the fragment instance.
173{@link android.app.Activity#onDestroy() onDestroy()} updates the stateful object inside the
174retained fragment instance.</p>
175
176
177
178
179
180<h2 id="HandlingTheChange">Handling the Configuration Change Yourself</h2>
181
182<p>If your application doesn't need to update resources during a specific configuration
183change <em>and</em> you have a performance limitation that requires you to
184avoid the activity restart, then you can declare that your activity handles the configuration change
185itself, which prevents the system from restarting your activity.</p>
186
187<p class="note"><strong>Note:</strong> Handling the configuration change yourself can make it much
188more difficult to use alternative resources, because the system does not automatically apply them
189for you. This technique should be considered a last resort when you must avoid restarts due to a
190configuration change and is not recommended for most applications.</p>
191
192<p>To declare that your activity handles a configuration change, edit the appropriate <a
193href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element in
194your manifest file to include the <a
195href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
196android:configChanges}</a> attribute with a value that represents the configuration you want to
197handle. Possible values are listed in the documentation for the <a
198href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
199android:configChanges}</a> attribute (the most commonly used values are {@code "orientation"} to
200prevent restarts when the screen orientation changes and {@code "keyboardHidden"} to prevent
201restarts when the keyboard availability changes).  You can declare multiple configuration values in
202the attribute by separating them with a pipe {@code |} character.</p>
203
204<p>For example, the following manifest code declares an activity that handles both the
205screen orientation change and keyboard availability change:</p>
206
207<pre>
208&lt;activity android:name=".MyActivity"
209          android:configChanges="orientation|keyboardHidden"
210          android:label="@string/app_name">
211</pre>
212
213<p>Now, when one of these configurations change, {@code MyActivity} does not restart.
214Instead, the {@code MyActivity} receives a call to {@link
215android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. This method
216is passed a {@link android.content.res.Configuration} object that specifies
217the new device configuration. By reading fields in the {@link android.content.res.Configuration},
218you can determine the new configuration and make appropriate changes by updating
219the resources used in your interface. At the
220time this method is called, your activity's {@link android.content.res.Resources} object is updated
221to return resources based on the new configuration, so you can easily
222reset elements of your UI without the system restarting your activity.</p>
223
224<p class="caution"><strong>Caution:</strong> Beginning with Android 3.2 (API level 13), <strong>the
225"screen size" also changes</strong> when the device switches between portrait and landscape
226orientation. Thus, if you want to prevent runtime restarts due to orientation change when developing
227for API level 13 or higher (as declared by the <a
228href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> and <a
229href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
230attributes), you must include the {@code "screenSize"} value in addition to the {@code
231"orientation"} value. That is, you must decalare {@code
232android:configChanges="orientation|screenSize"}. However, if your application targets API level
23312 or lower, then your activity always handles this configuration change itself (this configuration
234change does not restart your activity, even when running on an Android 3.2 or higher device).</p>
235
236<p>For example, the following {@link
237android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()} implementation
238checks the current device orientation:</p>
239
240<pre>
241&#64;Override
242public void onConfigurationChanged(Configuration newConfig) {
243    super.onConfigurationChanged(newConfig);
244
245    // Checks the orientation of the screen
246    if (newConfig.orientation == Configuration.ORIENTATION_LANDSCAPE) {
247        Toast.makeText(this, "landscape", Toast.LENGTH_SHORT).show();
248    } else if (newConfig.orientation == Configuration.ORIENTATION_PORTRAIT){
249        Toast.makeText(this, "portrait", Toast.LENGTH_SHORT).show();
250    }
251}
252</pre>
253
254<p>The {@link android.content.res.Configuration} object represents all of the current
255configurations, not just the ones that have changed. Most of the time, you won't care exactly how
256the configuration has changed and can simply re-assign all your resources that provide alternatives
257to the configuration that you're handling. For example, because the {@link
258android.content.res.Resources} object is now updated, you can reset
259any {@link android.widget.ImageView}s with {@link android.widget.ImageView#setImageResource(int)
260setImageResource()}
261and the appropriate resource for the new configuration is used (as described in <a
262href="providing-resources.html#AlternateResources">Providing Resources</a>).</p>
263
264<p>Notice that the values from the {@link
265android.content.res.Configuration} fields are integers that are matched to specific constants
266from the {@link android.content.res.Configuration} class. For documentation about which constants
267to use with each field, refer to the appropriate field in the {@link
268android.content.res.Configuration} reference.</p>
269
270<p class="note"><strong>Remember:</strong> When you declare your activity to handle a configuration
271change, you are responsible for resetting any elements for which you provide alternatives. If you
272declare your activity to handle the orientation change and have images that should change
273between landscape and portrait, you must re-assign each resource to each element during {@link
274android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}.</p>
275
276<p>If you don't need to update your application based on these configuration
277changes, you can instead <em>not</em> implement {@link
278android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. In
279which case, all of the resources used before the configuration change are still used
280and you've only avoided the restart of your activity. However, your application should always be
281able to shutdown and restart with its previous state intact, so you should not consider this
282technique an escape from retaining your state during normal activity lifecycle. Not only because
283there are other configuration changes that you cannot prevent from restarting your application, but
284also because you should handle events such as when the user leaves your application and it gets
285destroyed before the user returns to it.</p>
286
287<p>For more about which configuration changes you can handle in your activity, see the <a
288href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code
289android:configChanges}</a> documentation and the {@link android.content.res.Configuration}
290class.</p>
291