FragmentNavigator

public class FragmentNavigator extends Navigator

Object
   ↳ Navigator
     ↳ FragmentNavigator
Known direct subclasses
DynamicFragmentNavigator

The Navigator that enables navigating to destinations within dynamic feature modules.


Navigator that navigates through FragmentTransaction. Every destination using this Navigator must set a valid Fragment class name with android:name or Destination.setClassName.

The current Fragment from FragmentNavigator's perspective can be retrieved by calling FragmentManager.getPrimaryNavigationFragment with the FragmentManager passed to this FragmentNavigator.

Note that the default implementation does Fragment transactions asynchronously, so the current Fragment will not be available immediately (i.e., in callbacks to NavController.OnDestinationChangedListener).

Summary

Nested types

FragmentNavigator.Destination

NavDestination specific to FragmentNavigator

FragmentNavigator.Extras

Extras that can be passed to FragmentNavigator to enable Fragment specific behavior

FragmentNavigator.Extras.Builder

Builder for constructing new Extras instances.

Public fields

final boolean

Whether this Navigator is actively being used by a NavController.

Public constructors

FragmentNavigator(
    @NonNull Context context,
    @NonNull FragmentManager fragmentManager,
    int containerId
)

Public methods

@NonNull FragmentNavigator.Destination

Construct a new NavDestination associated with this Navigator.

@NonNull Fragment
instantiateFragment(
    @NonNull Context context,
    @NonNull FragmentManager fragmentManager,
    @NonNull String className,
    @Nullable Bundle args
)

This method is deprecated. Set a custom {@link androidx.fragment.app.FragmentFactory} via {@link FragmentManager#setFragmentFactory(FragmentFactory)} to control instantiation of Fragments.

void
navigate(
    @NonNull List<@NonNull NavBackStackEntry> entries,
    @Nullable NavOptions navOptions,
    @Nullable Navigator.Extras navigatorExtras
)

{@inheritDoc}

void

Restore any state previously saved in onSaveState.

@Nullable Bundle

Called to ask for a Bundle representing the Navigator's state.

void
popBackStack(@NonNull NavBackStackEntry popUpTo, boolean savedState)

{@inheritDoc}

Inherited methods

From class Navigator
@Nullable NavDestination
navigate(
    @NonNull FragmentNavigator.Destination destination,
    @Nullable Bundle args,
    @Nullable NavOptions navOptions,
    @Nullable Navigator.Extras navigatorExtras
)

Navigate to a destination.

@CallSuper void

Indicator that this Navigator is actively being used by a NavController.

void

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.

boolean

Attempt to pop this navigator's back stack, performing the appropriate navigation.

Public fields

isAttached

@NonNull
public final boolean isAttached

Whether this Navigator is actively being used by a NavController.

This is set to true when onAttach is called.

Public constructors

FragmentNavigator

public final FragmentNavigator(
    @NonNull Context context,
    @NonNull FragmentManager fragmentManager,
    int containerId
)

Public methods

createDestination

@NonNull
public FragmentNavigator.Destination createDestination()

Construct a new NavDestination associated with this Navigator.

Any initialization of the destination should be done in the destination's constructor as it is not guaranteed that every destination will be created through this method.

Returns
FragmentNavigator.Destination

a new NavDestination

instantiateFragment

@NonNull
public Fragment instantiateFragment(
    @NonNull Context context,
    @NonNull FragmentManager fragmentManager,
    @NonNull String className,
    @Nullable Bundle args
)

Instantiates the Fragment via the FragmentManager's androidx.fragment.app.FragmentFactory.

Note that this method is not responsible for calling Fragment.setArguments on the returned Fragment instance.

Parameters
@NonNull Context context

Context providing the correct ClassLoader

@NonNull FragmentManager fragmentManager

FragmentManager the Fragment will be added to

@NonNull String className

The Fragment to instantiate

@Nullable Bundle args

The Fragment's arguments, if any

Returns
Fragment

A new fragment instance.

@NonNull
public void navigate(
    @NonNull List<@NonNull NavBackStackEntry> entries,
    @Nullable NavOptions navOptions,
    @Nullable Navigator.Extras navigatorExtras
)

{@inheritDoc}

This method should always call FragmentTransaction.setPrimaryNavigationFragment so that the Fragment associated with the new destination can be retrieved with FragmentManager.getPrimaryNavigationFragment.

Note that the default implementation commits the new Fragment asynchronously, so the new Fragment is not instantly available after this call completes.

onRestoreState

@NonNull
public void onRestoreState(@NonNull Bundle savedState)

Restore any state previously saved in onSaveState. This will be called before any calls to navigate or popBackStack.

Calls to createDestination should not be dependent on any state restored here as createDestination can be called before the state is restored.

Parameters
@NonNull Bundle savedState

The state previously saved

onSaveState

@Nullable
public Bundle onSaveState()

Called to ask for a Bundle representing the Navigator's state. This will be restored in onRestoreState.

popBackStack

@NonNull
public void popBackStack(@NonNull NavBackStackEntry popUpTo, boolean savedState)

{@inheritDoc}

This method must call FragmentTransaction.setPrimaryNavigationFragment if the pop succeeded so that the newly visible Fragment can be retrieved with FragmentManager.getPrimaryNavigationFragment.

Note that the default implementation pops the Fragment asynchronously, so the newly visible Fragment from the back stack is not instantly available after this call completes.