Activity.OnRetainNonConfigurationInstance Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Called by the system, as part of destroying an activity due to a configuration change, when it is known that a new instance will immediately be created for the new configuration.
[Android.Runtime.Register("onRetainNonConfigurationInstance", "()Ljava/lang/Object;", "GetOnRetainNonConfigurationInstanceHandler")]
public virtual Java.Lang.Object? OnRetainNonConfigurationInstance ();[<Android.Runtime.Register("onRetainNonConfigurationInstance", "()Ljava/lang/Object;", "GetOnRetainNonConfigurationInstanceHandler")>]
abstract member OnRetainNonConfigurationInstance : unit -> Java.Lang.Object
override this.OnRetainNonConfigurationInstance : unit -> Java.Lang.ObjectReturns
any Object holding the desired state to propagate to the next activity instance
- Attributes
Remarks
Called by the system, as part of destroying an activity due to a configuration change, when it is known that a new instance will immediately be created for the new configuration. You can return any object you like here, including the activity instance itself, which can later be retrieved by calling #getLastNonConfigurationInstance() in the new activity instance.
<em>If you are targeting android.os.Build.VERSION_CODES#HONEYCOMB or later, consider instead using a Fragment with Fragment#setRetainInstance(boolean) Fragment.setRetainInstance(boolean.</em>
This function is called purely as an optimization, and you must not rely on it being called. When it is called, a number of guarantees will be made to help optimize configuration switching: <ul> <li> The function will be called between #onStop and #onDestroy. <li> A new instance of the activity will <em>always</em> be immediately created after this one's #onDestroy() is called. In particular, <em>no</em> messages will be dispatched during this time (when the returned object does not have an activity to be associated with). <li> The object you return here will <em>always</em> be available from the #getLastNonConfigurationInstance() method of the following activity instance as described there. </ul>
These guarantees are designed so that an activity can use this API to propagate extensive state from the old to new activity instance, from loaded bitmaps, to network connections, to evenly actively running threads. Note that you should <em>not</em> propagate any data that may change based on the configuration, including any data loaded from resources such as strings, layouts, or drawables.
The guarantee of no message handling during the switch to the next activity simplifies use with active objects. For example if your retained state is an android.os.AsyncTask you are guaranteed that its call back functions (like android.os.AsyncTask#onPostExecute) will not be called from the call here until you execute the next instance's #onCreate(Bundle). (Note however that there is of course no such guarantee for android.os.AsyncTask#doInBackground since that is running in a separate thread.)
<strong>Note:</strong> For most cases you should use the Fragment API Fragment#setRetainInstance(boolean) instead; this is also available on older platforms through the Android support libraries.
Java documentation for android.app.Activity.onRetainNonConfigurationInstance().
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.