Merge "DO NOT MERGE" into klp-modular-docs

created to handle a new intent.  However, if the target task already has an

existing instance of the activity at the top of its stack, that instance

will receive the new intent (in an

<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call);

{@link android.app.Activity#onNewIntent onNewIntent()} call);

a new instance is not created.

In other circumstances — for example, if an existing instance of the

"{@code singleTop}" activity is in the target task, but not at the top of

— a new instance would be created and pushed on the stack.

</p>

<p>Similarly, if you

<a href="{@docRoot}training/implementing-navigation/ancestral.html">navigate

up</a> to an activity on the current stack, the behavior is determined by the

parent activity's launch mode. If the parent activity has launch mode {@code

singleTop} (or the <code>up</code> intent contains {@link

android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the parent is brought to the

top of the stack, and its state is preserved. The navigation intent is received

by the parent activity's {@link android.app.Activity#onNewIntent onNewIntent()}

method.  If the parent activity has launch mode {@code standard} (and the

<code>up</code> intent does not contain {@link

android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the current activity and its

parent are both popped off the stack, and a new instance of the parent activity

is created to receive the navigation intent.

</p>

<p>

The "{@code singleTask}" and "{@code singleInstance}" modes also differ from

each other in only one respect:  A "{@code singleTask}" activity allows other

navigateUpFromSameTask()}. When you call this method, it finishes the current activity and

starts (or resumes) the appropriate parent activity.

If the target parent activity is in the task's back stack, it is brought

forward as defined by {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}.</p>

forward. The way it is brought forward depends on whether the parent activity

is able to handle an {@link

android.app.Activity#onNewIntent onNewIntent()} call:</p>

<ul>

    <li>If the parent activity has launch mode <a

    href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code

    &lt;singleTop>}</a>, or the <code>up</code> intent contains {@link

    android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}, the parent activity is

    brought to the top of the stack, and receives the intent through its

    {@link android.app.Activity#onNewIntent onNewIntent()} method.</li>

    <li>If the parent activity has launch mode <a

    href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code

    &lt;standard>}</a>, and the <code>up</code> intent does not contain

    {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}, the parent activity

    is popped off the stack, and a new instance of that activity is created on

    top of the stack to receive the intent.</li>

</ul>

<p>For example:</p>

navigating <em>Up</em> should create a new task that belongs to your app, which

requires that you create a new back stack.</p>

<h3 id="BuildBackStack">Navigate up with a new back stack</h3>

<p>If your activity provides any <a