Add NavOptions for saving and restoring the back stack

When navigating with the NavController, the primary
mechanism is via calls to navigate(), which simply
adds the new destination to the back stack. NavOptions
are the existing mechanism for modifying that default
behavior (e.g., using launchSingleTop to ensure only
one copy of the destination is on the top of the
back stack).

Therefore NavOptions is one of the surfaces that needs
to be updated to support multiple back stacks in two ways:
- the restoreState boolean controls whether any previously
saved back stack and destination states associated with
the destination you're navigating to should be restored
- the popUpToSaveState boolean controls whether the back
stack and destination states between the current destination
and your popUpTo destination (inclusive or not) should be
saved for later restoration

Note: these APIs are not currently plugged into the
NavController or Navigators. That will be done in
follow up CLs.

Relnote: N/A
Test: Updated tests pass
BUG: 80029773
Change-Id: I7f4db810f027dd83f34c4906d4d21e73e051b35c

diff --git a/navigation/navigation-common/api/restricted_current.txt b/navigation/navigation-common/api/restricted_current.txt
index 9a70668..1901865 100644
--- a/navigation/navigation-common/api/restricted_current.txt
+++ b/navigation/navigation-common/api/restricted_current.txt

@@ -283,6 +283,8 @@
     method @IdRes public int getPopUpTo();
     method public boolean isPopUpToInclusive();
     method public boolean shouldLaunchSingleTop();
+    method public boolean shouldPopUpToSaveState();
+    method public boolean shouldRestoreState();
     property @AnimRes @AnimatorRes public final int enterAnim;
     property @AnimRes @AnimatorRes public final int exitAnim;
     property @AnimRes @AnimatorRes public final int popEnterAnim;
@@ -298,7 +300,9 @@
     method public androidx.navigation.NavOptions.Builder setLaunchSingleTop(boolean singleTop);
     method public androidx.navigation.NavOptions.Builder setPopEnterAnim(@AnimRes @AnimatorRes int popEnterAnim);
     method public androidx.navigation.NavOptions.Builder setPopExitAnim(@AnimRes @AnimatorRes int popExitAnim);
+    method public androidx.navigation.NavOptions.Builder setPopUpTo(@IdRes int destinationId, boolean inclusive, optional boolean saveState);
     method public androidx.navigation.NavOptions.Builder setPopUpTo(@IdRes int destinationId, boolean inclusive);
+    method public androidx.navigation.NavOptions.Builder setRestoreState(boolean restoreState);
   }
 
   @androidx.navigation.NavOptionsDsl public final class NavOptionsBuilder {
@@ -306,11 +310,14 @@
     method public void anim(kotlin.jvm.functions.Function1<? super androidx.navigation.AnimBuilder,kotlin.Unit> animBuilder);
     method public boolean getLaunchSingleTop();
     method public int getPopUpTo();
+    method public boolean getRestoreState();
     method public void popUpTo(@IdRes int id, kotlin.jvm.functions.Function1<? super androidx.navigation.PopUpToBuilder,kotlin.Unit> popUpToBuilder);
     method public void setLaunchSingleTop(boolean p);
     method public void setPopUpTo(int value);
+    method public void setRestoreState(boolean p);
     property public final boolean launchSingleTop;
     property public final int popUpTo;
+    property public final boolean restoreState;
   }
 
   public final class NavOptionsBuilderKt {
@@ -423,8 +430,11 @@
   @androidx.navigation.NavOptionsDsl public final class PopUpToBuilder {
     ctor public PopUpToBuilder();
     method public boolean getInclusive();
+    method public boolean getSaveState();
     method public void setInclusive(boolean p);
+    method public void setSaveState(boolean p);
     property public final boolean inclusive;
+    property public final boolean saveState;
   }
 
 }