Merge "Update Activity lifecycle documentation"

 * creating a window for you in which you can place your UI with

 * {@link #setContentView}.  While activities are often presented to the user

 * as full-screen windows, they can also be used in other ways: as floating

 * windows (via a theme with {@link android.R.attr#windowIsFloating} set)

 * or embedded inside of another activity (using {@link ActivityGroup}).

 * windows (via a theme with {@link android.R.attr#windowIsFloating} set),

 * <a href="https://developer.android.com/guide/topics/ui/multi-window">

 * Multi-Window mode</a> or embedded into other windows.

 *

 * There are two methods almost all subclasses of Activity will implement:

 *

 *     to retrieve the widgets in that UI that you need to interact with

 *     programmatically.

 *

 *     <li> {@link #onPause} is where you deal with the user leaving your

 *     activity.  Most importantly, any changes made by the user should at this

 *     point be committed (usually to the

 *     {@link android.content.ContentProvider} holding the data).

 *     <li> {@link #onPause} is where you deal with the user pausing active

 *     interaction with the activity. Any changes made by the user should at

 *     this point be committed (usually to the

 *     {@link android.content.ContentProvider} holding the data). In this

 *     state the activity is still visible on screen.

 * </ul>

 *

 * <p>To be of use with {@link android.content.Context#startActivity Context.startActivity()}, all

 * <a name="ActivityLifecycle"></a>

 * <h3>Activity Lifecycle</h3>

 *

 * <p>Activities in the system are managed as an <em>activity stack</em>.

 * When a new activity is started, it is placed on the top of the stack

 * and becomes the running activity -- the previous activity always remains

 * <p>Activities in the system are managed as

 * <a href="https://developer.android.com/guide/components/activities/tasks-and-back-stack">

 * activity stacks</a>. When a new activity is started, it is usually placed on the top of the

 * current stack and becomes the running activity -- the previous activity always remains

 * below it in the stack, and will not come to the foreground again until

 * the new activity exits.</p>

 * the new activity exits. There can be one or multiple activity stacks visible

 * on screen.</p>

 *

 * <p>An activity has essentially four states:</p>

 * <ul>

 *     <li> If an activity is in the foreground of the screen (at the top of

 *         the stack),

 *         it is <em>active</em> or  <em>running</em>. </li>

 *     <li>If an activity has lost focus but is still visible (that is, a new non-full-sized

 *         or transparent activity has focus on top of your activity), it

 *         is <em>paused</em>. A paused activity is completely alive (it

 *         maintains all state and member information and remains attached to

 *         the window manager), but can be killed by the system in extreme

 *         low memory situations.

 *     <li>If an activity is in the foreground of the screen (at the highest position of the topmost

 *         stack), it is <em>active</em> or <em>running</em>. This is usually the activity that the

 *         user is currently interacting with.</li>

 *     <li>If an activity has lost focus but is still presented to the user, it is <em>visible</em>.

 *         It is possible if a new non-full-sized or transparent activity has focus on top of your

 *         activity, another activity has higher position in multi-window mode, or the activity

 *         itself is not focusable in current windowing mode. Such activity is completely alive (it

 *         maintains all state and member information and remains attached to the window manager).

 *     <li>If an activity is completely obscured by another activity,

 *         it is <em>stopped</em>. It still retains all state and member information,

 *         however, it is no longer visible to the user so its window is hidden

 *         and it will often be killed by the system when memory is needed

 *         elsewhere.</li>

 *     <li>If an activity is paused or stopped, the system can drop the activity

 *         from memory by either asking it to finish, or simply killing its

 *         process.  When it is displayed again to the user, it must be

 *         completely restarted and restored to its previous state.</li>

 *         it is <em>stopped</em> or <em>hidden</em>. It still retains all state and member

 *         information, however, it is no longer visible to the user so its window is hidden

 *         and it will often be killed by the system when memory is needed elsewhere.</li>

 *     <li>The system can drop the activity from memory by either asking it to finish,

 *         or simply killing its process, making it <em>destroyed</em>. When it is displayed again

 *         to the user, it must be completely restarted and restored to its previous state.</li>

 * </ul>

 *

 * <p>The following diagram shows the important state paths of an Activity.

 * <li>The <b>foreground lifetime</b> of an activity happens between a call to

 * {@link android.app.Activity#onResume} until a corresponding call to

 * {@link android.app.Activity#onPause}.  During this time the activity is

 * in front of all other activities and interacting with the user.  An activity

 * in visible, active and interacting with the user.  An activity

 * can frequently go between the resumed and paused states -- for example when

 * the device goes to sleep, when an activity result is delivered, when a new

 * intent is delivered -- so the code in these methods should be fairly

 * activities will implement {@link android.app.Activity#onCreate}

 * to do their initial setup; many will also implement

 * {@link android.app.Activity#onPause} to commit changes to data and

 * otherwise prepare to stop interacting with the user.  You should always

 * prepare to pause interacting with the user, and {@link android.app.Activity#onStop}

 * to handle no longer being visible on screen. You should always

 * call up to your superclass when implementing these methods.</p>

 *

 * </p>

 *         <td align="left" border="0">{@link android.app.Activity#onResume onResume()}</td>

 *         <td>Called when the activity will start

 *             interacting with the user.  At this point your activity is at

 *             the top of the activity stack, with user input going to it.

 *             the top of its activity stack, with user input going to it.

 *             <p>Always followed by <code>onPause()</code>.</td>

 *         <td align="center">No</td>

 *         <td align="center"><code>onPause()</code></td>

 *     </tr>

 *

 *     <tr><td align="left" border="0">{@link android.app.Activity#onPause onPause()}</td>

 *         <td>Called when the system is about to start resuming a previous

 *             activity.  This is typically used to commit unsaved changes to

 *             persistent data, stop animations and other things that may be consuming

 *             CPU, etc.  Implementations of this method must be very quick because

 *         <td>Called when the activity loses foreground state, is no longer focusable or before

 *             transition to stopped/hidden or destroyed state. The activity is still visible to

 *             user, so it's recommended to keep it visually active and continue updating the UI.

 *             Implementations of this method must be very quick because

 *             the next activity will not be resumed until this method returns.

 *             <p>Followed by either <code>onResume()</code> if the activity

 *             returns back to the front, or <code>onStop()</code> if it becomes

 *     </tr>

 *

 *     <tr><td colspan="2" align="left" border="0">{@link android.app.Activity#onStop onStop()}</td>

 *         <td>Called when the activity is no longer visible to the user, because

 *             another activity has been resumed and is covering this one.  This

 *             may happen either because a new activity is being started, an existing

 *             one is being brought in front of this one, or this one is being

 *             destroyed.

 *         <td>Called when the activity is no longer visible to the user.  This may happen either

 *             because a new activity is being started on top, an existing one is being brought in

 *             front of this one, or this one is being destroyed. This is typically used to stop

 *             animations and refreshing the UI, etc.

 *             <p>Followed by either <code>onRestart()</code> if

 *             this activity is coming back to interact with the user, or

 *             <code>onDestroy()</code> if this activity is going away.</td>

 * <p>For those methods that are not marked as being killable, the activity's

 * process will not be killed by the system starting from the time the method

 * is called and continuing after it returns.  Thus an activity is in the killable

 * state, for example, between after <code>onPause()</code> to the start of

 * <code>onResume()</code>.</p>

 * state, for example, between after <code>onStop()</code> to the start of

 * <code>onResume()</code>. Keep in mind that under extreme memory pressure the

 * system can kill the application process at any time.</p>

 *

 * <a name="ConfigurationChanges"></a>

 * <h3>Configuration Changes</h3>

 * <p>This model is designed to prevent data loss when a user is navigating

 * between activities, and allows the system to safely kill an activity (because

 * system resources are needed somewhere else) at any time after it has been

 * paused.  Note this implies

 * that the user pressing BACK from your activity does <em>not</em>

 * stopped (or paused on platform versions before {@link android.os.Build.VERSION_CODES#HONEYCOMB}).

 * Note this implies that the user pressing BACK from your activity does <em>not</em>

 * mean "cancel" -- it means to leave the activity with its current contents

 * saved away.  Canceling edits in an activity must be provided through

 * some other mechanism, such as an explicit "revert" or "undo" option.</p>

 * reached a memory paging state, so this is required in order to keep the user

 * interface responsive.

 * <li> <p>A <b>visible activity</b> (an activity that is visible to the user

 * but not in the foreground, such as one sitting behind a foreground dialog)

 * but not in the foreground, such as one sitting behind a foreground dialog

 * or next to other activities in multi-window mode)

 * is considered extremely important and will not be killed unless that is

 * required to keep the foreground activity running.

 * <li> <p>A <b>background activity</b> (an activity that is not visible to

 * the user and has been paused) is no longer critical, so the system may

 * the user and has been stopped) is no longer critical, so the system may

 * safely kill its process to reclaim memory for other foreground or

 * visible processes.  If its process needs to be killed, when the user navigates

 * back to the activity (making it visible on the screen again), its

    /**

     * Called after {@link #onCreate} — or after {@link #onRestart} when

     * the activity had been stopped, but is now again being displayed to the

     * user.  It will be followed by {@link #onResume}.

     * user. It will usually be followed by {@link #onResume}. This is a good place to begin

     * drawing visual elements, running animations, etc.

     *

     * <p>You can call {@link #finish} from within this function, in

     * which case {@link #onStop} will be immediately called after {@link #onStart} without the

     * lifecycle transitions in-between ({@link #onResume}, {@link #onPause}, etc) executing.

     *

     * <p><em>Derived classes must call through to the super class's

     * implementation of this method.  If they do not, an exception will be

    /**

     * Called after {@link #onRestoreInstanceState}, {@link #onRestart}, or

     * {@link #onPause}, for your activity to start interacting with the user.

     * This is a good place to begin animations, open exclusive-access devices

     * (such as the camera), etc.

     * {@link #onPause}, for your activity to start interacting with the user. This is an indicator

     * that the activity became active and ready to receive input. It is on top of an activity stack

     * and visible to user.

     *

     * <p>Keep in mind that onResume is not the best indicator that your activity

     * is visible to the user; a system window such as the keyguard may be in

     * front.  Use {@link #onWindowFocusChanged} to know for certain that your

     * activity is visible to the user (for example, to resume a game).

     * <p>On platform versions prior to {@link android.os.Build.VERSION_CODES#Q} this is also a good

     * place to try to open exclusive-access devices or to get access to singleton resources.

     * Starting  with {@link android.os.Build.VERSION_CODES#Q} there can be multiple resumed

     * activities in the system simultaneously, so {@link #onTopResumedActivityChanged(boolean)}

     * should be used for that purpose instead.

     *

     * <p><em>Derived classes must call through to the super class's

     * implementation of this method.  If they do not, an exception will be

     * @see #onRestart

     * @see #onPostResume

     * @see #onPause

     * @see #onTopResumedActivityChanged(boolean)

     */

    @CallSuper

    protected void onResume() {

    }

    /**

     * Called when activity gets or looses the top resumed position in the system.

     * Called when activity gets or loses the top resumed position in the system.

     *

     * <p>Starting with {@link android.os.Build.VERSION_CODES#Q} multiple activities can be resumed

     * at the same time in multi-window and multi-display modes. This callback should be used

     * called on the existing instance with the Intent that was used to

     * re-launch it.

     *

     * <p>An activity will always be paused before receiving a new intent, so

     * you can count on {@link #onResume} being called after this method.

     * <p>An activity can never receive a new intent in the resumed state. You can count on

     * {@link #onResume} being called after this method, though not necessarily immediately after

     * the completion this callback. If the activity was resumed, it will be paused and new intent

     * will be delivered, followed by {@link #onResume}. If the activity wasn't in the resumed

     * state, then new intent can be delivered immediately, with {@link #onResume()} called

     * sometime later when activity becomes active again.

     *

     * <p>Note that {@link #getIntent} still returns the original Intent.  You

     * can use {@link #setIntent} to update it to this new Intent.

     * returns to activity A, the state of the user interface can be restored

     * via {@link #onCreate} or {@link #onRestoreInstanceState}.

     *

     * <p>Do not confuse this method with activity lifecycle callbacks such as

     * {@link #onPause}, which is always called when an activity is being placed

     * in the background or on its way to destruction, or {@link #onStop} which

     * is called before destruction.  One example of when {@link #onPause} and

     * {@link #onStop} is called and not this method is when a user navigates back

     * from activity B to activity A: there is no need to call {@link #onSaveInstanceState}

     * on B because that particular instance will never be restored, so the

     * system avoids calling it.  An example when {@link #onPause} is called and

     * <p>Do not confuse this method with activity lifecycle callbacks such as {@link #onPause},

     * which is always called when the user no longer actively interacts with an activity, or

     * {@link #onStop} which is called when activity becomes invisible. One example of when

     * {@link #onPause} and {@link #onStop} is called and not this method is when a user navigates

     * back from activity B to activity A: there is no need to call {@link #onSaveInstanceState}

     * on B because that particular instance will never be restored,

     * so the system avoids calling it.  An example when {@link #onPause} is called and

     * not {@link #onSaveInstanceState} is when activity B is launched in front of activity A:

     * the system may avoid calling {@link #onSaveInstanceState} on activity A if it isn't

     * killed during the lifetime of B since the state of the user interface of

    /**

     * Called as part of the activity lifecycle when an activity is going into

     * the background, but has not (yet) been killed.  The counterpart to

     * {@link #onResume}.

     * Called as part of the activity lifecycle when the user no longer actively interacts with the

     * activity, but it is still visible on screen. The counterpart to {@link #onResume}.

     *

     * <p>When activity B is launched in front of activity A, this callback will

     * be invoked on A.  B will not be created until A's {@link #onPause} returns,

     * activity is editing, to present a "edit in place" model to the user and

     * making sure nothing is lost if there are not enough resources to start

     * the new activity without first killing this one.  This is also a good

     * place to do things like stop animations and other things that consume a

     * noticeable amount of CPU in order to make the switch to the next activity

     * as fast as possible, or to close resources that are exclusive access

     * such as the camera.

     *

     * <p>In situations where the system needs more memory it may kill paused

     * processes to reclaim resources.  Because of this, you should be sure

     * that all of your state is saved by the time you return from

     * this function.  In general {@link #onSaveInstanceState} is used to save

     * per-instance state in the activity and this method is used to store

     * global persistent data (in content providers, files, etc.)

     *

     * <p>After receiving this call you will usually receive a following call

     * to {@link #onStop} (after the next activity has been resumed and

     * displayed), however in some cases there will be a direct call back to

     * {@link #onResume} without going through the stopped state.

     * place to stop things that consume a noticeable amount of CPU in order to

     * make the switch to the next activity as fast as possible.

     *

     * <p>On platform versions prior to {@link android.os.Build.VERSION_CODES#Q} this is also a good

     * place to try to close exclusive-access devices or to release access to singleton resources.

     * Starting with {@link android.os.Build.VERSION_CODES#Q} there can be multiple resumed

     * activities in the system at the same time, so {@link #onTopResumedActivityChanged(boolean)}

     * should be used for that purpose instead.

     *

     * <p>If an activity is launched on top, after receiving this call you will usually receive a

     * following call to {@link #onStop} (after the next activity has been resumed and displayed

     * above). However in some cases there will be a direct call back to {@link #onResume} without

     * going through the stopped state. An activity can also rest in paused state in some cases when

     * in multi-window mode, still visible to user.

     *

     * <p><em>Derived classes must call through to the super class's

     * implementation of this method.  If they do not, an exception will be

    /**

     * Called when you are no longer visible to the user.  You will next

     * receive either {@link #onRestart}, {@link #onDestroy}, or nothing,

     * depending on later user activity.

     * depending on later user activity. This is a good place to stop

     * refreshing UI, running animations and other visual things.

     *

     * <p><em>Derived classes must call through to the super class's

     * implementation of this method.  If they do not, an exception will be

    /**

     * Called when the current {@link Window} of the activity gains or loses

     * focus.  This is the best indicator of whether this activity is visible

     * to the user.  The default implementation clears the key tracking

     * state, so should always be called.

     * focus. This is the best indicator of whether this activity is the entity

     * with which the user actively interacts. The default implementation

     * clears the key tracking state, so should always be called.

     *

     * <p>Note that this provides information about global focus state, which

     * is managed independently of activity lifecycles.  As such, while focus

     * is managed independently of activity lifecycle.  As such, while focus

     * changes will generally have some relation to lifecycle changes (an

     * activity that is stopped will not generally get window focus), you

     * should not rely on any particular order between the callbacks here and

     * those in the other lifecycle methods such as {@link #onResume}.

     *

     * <p>As a general rule, however, a resumed activity will have window

     * <p>As a general rule, however, a foreground activity will have window

     * focus...  unless it has displayed other dialogs or popups that take

     * input focus, in which case the activity itself will not have focus

     * when the other windows have it.  Likewise, the system may display

     * a system alert) which will temporarily take window input focus without

     * pausing the foreground activity.

     *

     * <p>Starting with {@link android.os.Build.VERSION_CODES#Q} there can be

     * multiple resumed activities at the same time in multi-window mode, so

     * resumed state does not guarantee window focus even if there are no

     * overlays above.

     *

     * <p>If the intent is to know when an activity is the topmost active, the

     * one the user interacted with last among all activities but not including

     * non-activity windows like dialogs and popups, then

     * {@link #onTopResumedActivityChanged(boolean)} should be used. On platform

     * versions prior to {@link android.os.Build.VERSION_CODES#Q},

     * {@link #onResume} is the best indicator.

     *

     * @param hasFocus Whether the window of this activity has focus.

     *

     * @see #hasWindowFocus()

     * @see #onResume

     * @see View#onWindowFocusChanged(boolean)

     * @see #onTopResumedActivityChanged(boolean)

     */

    public void onWindowFocusChanged(boolean hasFocus) {

    }