Add recipes for returning navigation results

app/src/main/AndroidManifest.xml

@@ -94,6 +94,16 @@
             android:exported="true"
             android:label="@string/app_name"
             android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".results.event.ResultEventActivity"
+            android:exported="true"
+            android:label="@string/app_name"
+            android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".results.state.ResultStateActivity"
+            android:exported="true"
+            android:label="@string/app_name"
+            android:theme="@style/Theme.Nav3Recipes"/>
     </application>
 
 </manifest>

app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt

@@ -35,6 +35,8 @@ import com.example.nav3recipes.dialog.DialogActivity
 import com.example.nav3recipes.modular.hilt.ModularActivity
 import com.example.nav3recipes.passingarguments.basicviewmodels.BasicViewModelsActivity
 import com.example.nav3recipes.passingarguments.injectedviewmodels.InjectedViewModelsActivity
+import com.example.nav3recipes.results.event.ResultEventActivity
+import com.example.nav3recipes.results.state.ResultStateActivity
 import com.example.nav3recipes.scenes.materiallistdetail.MaterialListDetailActivity
 import com.example.nav3recipes.scenes.twopane.TwoPaneActivity
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
@@ -71,6 +73,10 @@ private val recipes = listOf(
     Heading("Passing navigation arguments"),
     Recipe("Argument passing to basic ViewModel", BasicViewModelsActivity::class.java),
     Recipe("Argument passing to injected ViewModel", InjectedViewModelsActivity::class.java),
+
+    Heading("Returning Results"),
+    Recipe("Return result as Event", ResultEventActivity::class.java),
+    Recipe("Return result as State", ResultStateActivity::class.java),
 )
 
 class RecipePickerActivity : ComponentActivity() {

app/src/main/java/com/example/nav3recipes/results/event/ResultEffect.kt

@@ -0,0 +1,26 @@
+package com.example.nav3recipes.results.event
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+
+/**
+ * An Effect to provide a result even between different screens
+ *
+ * The trailing lambda provides the result from a flow of results.
+ *
+ * @param resultEventBus the ResultEventBus to retrieve the result from
+ * @param resultKey the key that should be associated with this effect
+ * @param onResult the callback to invoke when a result is received
+ */
+@Composable
+inline fun <reified T> ResultEffect(
+    resultEventBus: ResultEventBus = LocalResultEventBus.current,
+    resultKey: String = T::class.toString(),
+    crossinline onResult: suspend (T) -> Unit
+) {
+    LaunchedEffect(resultKey, resultEventBus.channelMap[resultKey]) {
+        resultEventBus.getResultFlow<T>()?.collect { result ->
+            onResult.invoke(result as T)
+        }
+    }
+}

app/src/main/java/com/example/nav3recipes/results/event/ResultEventActivity.kt

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.nav3recipes.results.event
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.input.rememberTextFieldState
+import androidx.compose.material3.Button
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewmodel.compose.viewModel
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import kotlinx.serialization.Serializable
+
+/**
+ * This recipe demonstrates passing an event result to a previous screen. It does this by:
+ *
+ * - Providing a [ResultEventBus]
+ * - Implementing a [ResultEffect] in the receiving screen
+ * - Calling [ResultEventBus.sendResult] from the sending screen.
+ */
+
+
+@Serializable
+data object Home : NavKey
+
+@Serializable
+class ResultPage : NavKey
+
+class ResultEventActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            val resultBus = remember { ResultEventBus() }
+            CompositionLocalProvider(LocalResultEventBus.provides(resultBus)) {
+                Scaffold { paddingValues ->
+
+                    val backStack = rememberNavBackStack(Home)
+
+                    NavDisplay(
+                        backStack = backStack,
+                        modifier = Modifier.padding(paddingValues),
+                        onBack = { backStack.removeLastOrNull() },
+                        entryProvider = { key ->
+                            when (key) {
+                                is Home -> NavEntry(key) {
+                                    val viewModel = viewModel<HomeViewModel>(key = Home.toString())
+                                    ResultEffect<Name> { name ->
+                                        viewModel.name = name
+                                    }
+
+                                    Column {
+                                        Text("Welcome to Nav3")
+                                        Button(onClick = {
+                                            backStack.add(ResultPage())
+                                        }) {
+                                            Text("Click to provide a name")
+                                        }
+                                        if (viewModel.name == null) {
+                                            Text("I don't know who you are")
+                                        } else {
+                                            Text("Hi, ${viewModel.name}")
+                                        }
+                                    }
+                                }
+
+                                is ResultPage -> NavEntry(key) {
+                                    Column {
+
+                                        val state = rememberTextFieldState()
+                                        OutlinedTextField(
+                                            state = state,
+                                            label = { Text("Please enter a name") }
+                                        )
+                                        Button(onClick = {
+                                            resultBus.sendResult<Name>(result = state.text.toString())
+                                            backStack.removeLastOrNull()
+                                        }) {
+                                            Text("Return name")
+                                        }
+                                    }
+                                }
+                                else -> NavEntry(key) { Text("Unknown route") }
+                            }
+                        }
+                    )
+                }
+            }
+        }
+    }
+}
+
+class HomeViewModel : ViewModel() {
+    var name by mutableStateOf<String?>(null)
+}
+
+typealias Name = String

app/src/main/java/com/example/nav3recipes/results/event/ResultEventBus.kt

@@ -0,0 +1,68 @@
+package com.example.nav3recipes.results.event
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.ProvidableCompositionLocal
+import androidx.compose.runtime.ProvidedValue
+import androidx.compose.runtime.compositionLocalOf
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.channels.Channel.Factory.BUFFERED
+import kotlinx.coroutines.flow.receiveAsFlow
+
+/**
+ * Local for receiving results in a [ResultEventBus]
+ */
+object LocalResultEventBus {
+    private val LocalResultEventBus: ProvidableCompositionLocal<ResultEventBus?> =
+        compositionLocalOf { null }
+
+    /**
+     * The current [ResultEventBus]
+     */
+    val current: ResultEventBus
+        @Composable
+        get() = LocalResultEventBus.current ?: error("No ResultStore has been provided")
+
+    /**
+     * Provides a [ResultEventBus] to the composition
+     */
+    infix fun provides(
+        bus: ResultEventBus
+    ): ProvidedValue<ResultEventBus?> {
+        return LocalResultEventBus.provides(bus)
+    }
+}
+/**
+ * An EventBus for passing results between multiple sets of screens.
+ *
+ * It provides a solution for event based results.
+ */
+class ResultEventBus {
+    /**
+     * Map from the result key to a channel of results.
+     */
+    val channelMap: MutableMap<String, Channel<Any?>> = mutableMapOf()
+
+    /**
+     * Provides a flow for the given resultKey.
+     */
+    inline fun <reified T> getResultFlow(resultKey: String = T::class.toString()) =
+        channelMap[resultKey]?.receiveAsFlow()
+
+    /**
+     * Sends a result into the channel associated with the given resultKey.
+     */
+    inline fun <reified T> sendResult(resultKey: String = T::class.toString(), result: T) {
+        if (!channelMap.contains(resultKey)) {
+            channelMap.put(resultKey, Channel(capacity = BUFFERED, onBufferOverflow = BufferOverflow.SUSPEND))
+        }
+        channelMap[resultKey]?.trySend(result)
+    }
+
+    /**
+     * Removes all results associated with the given key from the store.
+     */
+    inline fun <reified T> removeResult(resultKey: String = T::class.toString()) {
+        channelMap.remove(resultKey)
+    }
+}

app/src/main/java/com/example/nav3recipes/results/state/ResultStateActivity.kt

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.nav3recipes.results.state
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.input.rememberTextFieldState
+import androidx.compose.material3.Button
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import kotlinx.serialization.Serializable
+
+/**
+ * This recipe demonstrates passing an state result to a previous screen. It does this by:
+ *
+ * - Providing a [ResultStore]
+ * - Calling [ResultStore.getResultState] in the receiving screen
+ * - Calling [ResultStore.setResult] from the sending screen.
+ */
+
+@Serializable
+data object Home : NavKey
+
+@Serializable
+class ResultPage : NavKey
+
+class ResultStateActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            val resultStore = remember { ResultStore() }
+            CompositionLocalProvider(LocalResultStore.provides(resultStore)) {
+            Scaffold { paddingValues ->
+                val backStack = rememberNavBackStack(Home)
+
+                NavDisplay(
+                    backStack = backStack,
+                    modifier = Modifier.padding(paddingValues),
+                    onBack = { backStack.removeLastOrNull() },
+                    entryProvider = { key ->
+                        when (key) {
+                            is Home -> NavEntry(key) {
+                                val name = resultStore.getResultState<Name?>()
+
+                                Column {
+                                    Text("Welcome to Nav3")
+                                    Button(onClick = {
+                                        backStack.add(ResultPage())
+                                    }) {
+                                        Text("Click to provide a name")
+                                    }
+                                    if (name == null) {
+                                        Text("I don't know who you are")
+                                    } else {
+                                        Text("Hi, $name")
+                                    }
+                                }
+
+
+                            }
+                            is ResultPage -> NavEntry(key) {
+                                Column {
+
+                                    val state = rememberTextFieldState()
+                                    OutlinedTextField(
+                                        state = state,
+                                        label = { Text("Please enter a name") }
+                                    )
+
+                                    Button(onClick = {
+                                        resultStore.setResult<Name>(result = state.text.toString())
+                                        backStack.removeLastOrNull()
+                                    }) {
+                                        Text("Return name")
+                                    }
+                                }
+                            }
+                            else -> NavEntry(key) { Text("Unknown route") }
+                        }
+                    }
+                )
+            }
+                }
+        }
+    }
+}
+
+typealias Name = String