NavDisplayKt

Added in 1.0.0-alpha04

public final class NavDisplayKt


Summary

Public methods

static final void
@Composable
<T extends Object> NavDisplay(
    @NonNull List<@NonNull T> backStack,
    @NonNull Modifier modifier,
    @NonNull Alignment contentAlignment,
    @NonNull Function1<@NonNull IntegerUnit> onBack,
    @NonNull List<@NonNull NavEntryDecorator<@NonNull ?>> entryDecorators,
    @NonNull SceneStrategy<@NonNull T> sceneStrategy,
    SizeTransform sizeTransform,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> transitionSpec,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> popTransitionSpec,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> predictivePopTransitionSpec,
    @NonNull Function1<@NonNull key, @NonNull NavEntry<@NonNull T>> entryProvider
)

A nav display that renders and animates between different Scenes, each of which can render one or more NavEntrys.

Public methods

@Composable
public static final void <T extends Object> NavDisplay(
    @NonNull List<@NonNull T> backStack,
    @NonNull Modifier modifier,
    @NonNull Alignment contentAlignment,
    @NonNull Function1<@NonNull IntegerUnit> onBack,
    @NonNull List<@NonNull NavEntryDecorator<@NonNull ?>> entryDecorators,
    @NonNull SceneStrategy<@NonNull T> sceneStrategy,
    SizeTransform sizeTransform,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> transitionSpec,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> popTransitionSpec,
    @NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> predictivePopTransitionSpec,
    @NonNull Function1<@NonNull key, @NonNull NavEntry<@NonNull T>> entryProvider
)

A nav display that renders and animates between different Scenes, each of which can render one or more NavEntrys.

The Scenes are calculated with the given SceneStrategy, which may be an assembled delegated chain of SceneStrategys. If no Scene is calculated, the fallback will be to a SinglePaneSceneStrategy.

It is allowable for different Scenes to render the same NavEntrys, perhaps on some conditions as determined by the sceneStrategy based on window size, form factor, other arbitrary logic.

If this happens, and these Scenes are rendered at the same time due to animation or predictive back, then the content for the NavEntry will only be rendered in the most recent Scene that is the target for being the current scene as determined by sceneStrategy. This enforces a unique invocation of each NavEntry, even if it is displayable by two different Scenes.

import androidx.compose.animation.core.tween import androidx.compose.animation.slideInHorizontally import androidx.compose.animation.slideOutHorizontally import androidx.compose.animation.togetherWith import androidx.compose.material3.Text import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.lifecycle.viewmodel.compose.viewModel import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator import androidx.navigation3.runtime.NavEntry import androidx.navigation3.runtime.NavEntryDecorator import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator import androidx.navigation3.runtime.samples.Dashboard import androidx.navigation3.runtime.samples.DialogBase import androidx.navigation3.runtime.samples.DialogContent import androidx.navigation3.runtime.samples.Profile import androidx.navigation3.runtime.samples.ProfileViewModel import androidx.navigation3.runtime.samples.Scrollable import androidx.navigation3.ui.NavDisplay import androidx.navigation3.ui.Scene import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator val backStack = rememberNavBackStack(Profile) val showDialog = remember { mutableStateOf(false) } NavDisplay(  backStack = backStack,  entryDecorators =  listOf(  rememberSceneSetupNavEntryDecorator(),  rememberSavedStateNavEntryDecorator(),  rememberViewModelStoreNavEntryDecorator(),  ),  onBack = { backStack.removeAt(backStack.lastIndex) },  entryProvider =  entryProvider({ NavEntry(it) { Text(text = "Invalid Key") } }) {  entry<Profile> {  val viewModel = viewModel<ProfileViewModel>()  Profile(viewModel, { backStack.add(it) }) {  backStack.removeAt(backStack.lastIndex)  }  }  entry<Scrollable> {  Scrollable({ backStack.add(it) }) { backStack.removeAt(backStack.lastIndex) }  }  entry<DialogBase> {  DialogBase(onClick = { showDialog.value = true }) {  backStack.removeAt(backStack.lastIndex)  }  }  entry<Dashboard>(  metadata =  NavDisplay.predictivePopTransitionSpec {  slideInHorizontally(tween(700)) { it / 2 } togetherWith  slideOutHorizontally(tween(700)) { -it / 2 }  }  ) { dashboardArgs ->  val userId = dashboardArgs.userId  Dashboard(userId, onBack = { backStack.removeAt(backStack.lastIndex) })  }  }, ) if (showDialog.value) {  DialogContent(onDismissRequest = { showDialog.value = false }) }
import androidx.compose.animation.SharedTransitionLayout import androidx.compose.animation.SharedTransitionScope import androidx.compose.foundation.layout.Box import androidx.compose.runtime.CompositionLocalProvider import androidx.compose.runtime.ProvidableCompositionLocal import androidx.compose.runtime.compositionLocalOf import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.navigation3.runtime.NavEntry import androidx.navigation3.runtime.NavEntryDecorator import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.navEntryDecorator import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator import androidx.navigation3.ui.LocalNavAnimatedContentScope import androidx.navigation3.ui.NavDisplay import androidx.navigation3.ui.Scene import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator /** The [SharedTransitionScope] of the [NavDisplay]. */ val localNavSharedTransitionScope: ProvidableCompositionLocal<SharedTransitionScope> =  compositionLocalOf {  throw IllegalStateException(  "Unexpected access to LocalNavSharedTransitionScope. You must provide a " +  "SharedTransitionScope from a call to SharedTransitionLayout() or " +  "SharedTransitionScope()"  )  } /**  * A [NavEntryDecorator] that wraps each entry in a shared element that is controlled by the  * [Scene].  */ val sharedEntryInSceneNavEntryDecorator =  navEntryDecorator<Any> { entry ->  with(localNavSharedTransitionScope.current) {  Box(  Modifier.sharedElement(  rememberSharedContentState(entry.contentKey),  animatedVisibilityScope = LocalNavAnimatedContentScope.current,  )  ) {  entry.Content()  }  }  } val backStack = rememberNavBackStack(CatList) SharedTransitionLayout {  CompositionLocalProvider(localNavSharedTransitionScope provides this) {  NavDisplay(  backStack = backStack,  onBack = { backStack.removeAt(backStack.lastIndex) },  entryDecorators =  listOf(  sharedEntryInSceneNavEntryDecorator,  rememberSceneSetupNavEntryDecorator(),  rememberSavedStateNavEntryDecorator(),  ),  entryProvider =  entryProvider {  entry<CatList> {  CatList(this@SharedTransitionLayout) { cat ->  backStack.add(CatDetail(cat))  }  }  entry<CatDetail> { args ->  CatDetail(args.cat, this@SharedTransitionLayout) {  backStack.removeAt(backStack.lastIndex)  }  }  },  )  } }
import androidx.compose.animation.SharedTransitionLayout import androidx.compose.runtime.remember import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay val backStack = rememberNavBackStack(CatList) SharedTransitionLayout {  NavDisplay(  backStack = backStack,  onBack = { backStack.removeAt(backStack.lastIndex) },  entryProvider =  entryProvider {  entry<CatList> {  CatList(this@SharedTransitionLayout) { cat ->  backStack.add(CatDetail(cat))  }  }  entry<CatDetail> { args ->  CatDetail(args.cat, this@SharedTransitionLayout) {  backStack.removeAt(backStack.lastIndex)  }  }  },  ) }
Parameters
@NonNull List<@NonNull T> backStack

the collection of keys that represents the state that needs to be handled

@NonNull Modifier modifier

the modifier to be applied to the layout.

@NonNull Alignment contentAlignment

The Alignment of the AnimatedContent

@NonNull Function1<@NonNull IntegerUnit> onBack

a callback for handling system back press. The passed Int refers to the number of entries to pop from the end of the backstack, as calculated by the sceneStrategy.

@NonNull List<@NonNull NavEntryDecorator<@NonNull ?>> entryDecorators

list of NavEntryDecorator to add information to the entry content

@NonNull SceneStrategy<@NonNull T> sceneStrategy

the SceneStrategy to determine which scene to render a list of entries.

SizeTransform sizeTransform

the SizeTransform for the AnimatedContent.

@NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> transitionSpec

Default ContentTransform when navigating to NavEntrys.

@NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> popTransitionSpec

Default ContentTransform when popping NavEntrys.

@NonNull Function1<@NonNull AnimatedContentTransitionScope<@NonNull ?>, @NonNull ContentTransform> predictivePopTransitionSpec

Default ContentTransform when popping with predictive back NavEntrys.

@NonNull Function1<@NonNull key, @NonNull NavEntry<@NonNull T>> entryProvider

lambda used to construct each possible NavEntry