From c7aab8d1a704b9bdf40ef6c56c75d0fd6bef5886 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adriel=20Caf=C3=A9?= Date: Fri, 30 Jul 2021 20:35:15 -0300 Subject: [PATCH] chore: update readme and bump version --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++------- gradle.properties | 2 +- 2 files changed, 56 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e1b52e3f..efed42cb 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Voyager: Compose on Warp Speed -**Voyager** is a pragmatic navigation library built for, and seamlessly integrated with, [Jetpack Compose](https://developer.android.com/jetpack/compose). +**Voyager** is a lightweight and pragmatic navigation library built for, and seamlessly integrated with, [Jetpack Compose](https://developer.android.com/jetpack/compose). Turn on the Warp Drive and enjoy the trek πŸ–– @@ -23,7 +23,9 @@ Turn on the Warp Drive and enjoy the trek πŸ–– - [x] [Lifecycle](#lifecycle) callbacks - [x] [Back press](#back-press) handling - [x] [Deep linking](#deep-links) support -- [ ] [Compose for Desktop](https://github.com/JetBrains/compose-jb) support (soonβ„’) +- [x] Built-in [transitions](#transitions) +- [ ] Multi-module support +- [ ] [Compose for Desktop](https://github.com/JetBrains/compose-jb) support ## Setup Add the desired dependencies to your module's build.gradle: @@ -31,6 +33,7 @@ Add the desired dependencies to your module's build.gradle: dependencies { implementation "cafe.adriel.voyager:voyager-navigator:$currentVersion" implementation "cafe.adriel.voyager:voyager-tab-navigator:$currentVersion" + implementation "cafe.adriel.voyager:voyager-transitions:$currentVersion" } ``` @@ -121,7 +124,7 @@ You will use it to navigate forward (`push`, `replace`, `replaceAll`) and backwa val stack = mutableStateStackOf("πŸ‡", "πŸ‰", "🍌", "🍐", "πŸ₯", "πŸ‹") // πŸ‡, πŸ‰, 🍌, 🍐, πŸ₯, πŸ‹ -stack.lastOrNull +stack.lastItemOrNull // πŸ‹ stack.push("🍍") @@ -142,6 +145,17 @@ stack.replaceAll("πŸ’") You can also create a `SnapshotStateStack` through `rememberStateStack()`, it will restore the values after [Activity recreation](#state-restoration). +#### StackEvent +Whenever the content changes, the `SnapshotStateStack` will emit a `StackEvent`, use the `stack.lastEvent` to get the most recent one. + +The available events are: +* `Push`: whenever `push` is called +* `Replace`: whenever `replace` and `replaceAll` are called +* `Pop`: whenever `pop` and `popAll` are called +* `Idle`: default event + +This is very useful for deciding which [transition](#transitions) to make. + ### State restoration The `Screen` interface is `Serializable`. Every param of your screens will be saved and restored automatically. @@ -265,29 +279,61 @@ setContent { ``` ### Transitions - -It's simple to add transition between screens: when initializing the `Navigator` you can override the default content. You can use, for example, the built-in [Crossfade](https://developer.android.com/reference/kotlin/androidx/compose/animation/package-summary#Crossfade(kotlin.Any,androidx.compose.ui.Modifier,androidx.compose.animation.core.FiniteAnimationSpec,kotlin.Function1)) animation. +Voyager has built-in transitions! When initializing the `Navigator` you can override the default content and use, for example, the `SlideTransition`. ```kotlin setContent { Navigator(HomeScreen) { navigator -> - Crossfade(navigator.last) { screen -> + SlideTransition(navigator) { screen -> screen.Content() } } } ``` -Want to use a custom animation? No problem, just follow the same principle. +It's simple to add your own transitions: call `ScreenTransition` with a custom `transitionModifier`. ```kotlin +@Composable +fun MyCustomTransition( + navigator: Navigator, + modifier: Modifier = Modifier, + content: ScreenTransitionContent +) { + ScreenTransition( + navigator = navigator, + modifier = modifier, + content = content, + transitionModifier = { screen, transition, event -> + // Animate values + val offset by transition.animateOffset { + when (event) { + StackEvent.Pop -> { /*...*/ } + else -> { /*...*/ } + } + } + + // Use any modifiers you need + modifier.offset(offset.x, offset.y) + } + ) +} + setContent { Navigator(HomeScreen) { navigator -> - MyCustomTransition { - CurrentScreen() + MyCustomTransition(navigator) { screen -> + screen.Content() } } } ``` +Take a look at the [source of the available transitions](https://github.com/adrielcafe/voyager/blob/main/voyager-transitions/src/main/java/cafe/adriel/voyager/transitions/) for working examples. + +#### Available transitions +| `FadeTransition()` | `ScaleTransition()` | `SlideTransition()` | +|-------|------------|----------| +| ![fade](https://user-images.githubusercontent.com/2512298/127704132-baeb8567-7a5a-4004-b445-770df0efab60.gif) | ![scale](https://user-images.githubusercontent.com/2512298/127704106-9c804ff9-e23a-4d13-85b2-9db2ae258556.gif) | ![slide](https://user-images.githubusercontent.com/2512298/127704049-f50e04eb-75fb-4687-88a3-21cce19ff12a.gif) | + + ### Tab navigation Voyager provides a handy abstraction over the `Navigator` and `Screen`: the `TabNavigator` and `Tab`. diff --git a/gradle.properties b/gradle.properties index 9d25bd3e..faf38b22 100644 --- a/gradle.properties +++ b/gradle.properties @@ -5,7 +5,7 @@ kotlin.code.style=official # Maven GROUP=cafe.adriel.voyager -VERSION_NAME=1.0.0-beta01 +VERSION_NAME=1.0.0-beta02 POM_DESCRIPTION=A pragmatic navigation library for Jetpack Compose POM_INCEPTION_YEAR=2021