circuit-foundation/com.slack.circuit.foundation

Package-level declarations

Types

Circuit adapts presenter factories to their corresponding ui factories using screens. Create instances using the Builder and create new CircuitContent with it to run presenter/UI pairings.

DelicateCircuitFoundationApi

@Target(allowedTargets = [AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY])

annotation class DelicateCircuitFoundationApi

Indicates that the annotated foundation API is delicate and should be used carefully.

interface EventListener

A listener for tracking the state changes of a given Screen. This can be used for instrumentation and other telemetry.

sealed interface NavEvent : CircuitUiEvent

A sealed navigation interface intended to be used when making a navigation callback.

NavigatorDefaults

object NavigatorDefaults

Default values and common alternatives used by navigable composables.

NonPausablePresenter

interface NonPausablePresenter<UiState : CircuitUiState> : Presenter<UiState>

By default CircuitContent will wrap presenters so that the last emitted CircuitUiState is replayed when the presenter is paused. If this behavior is not wanted, the Presenter should implement this interface to disable the behavior.

RecordContentProvider

class RecordContentProvider<R : BackStack.Record>(val record: R, content: @Composable (R) -> Unit)

A simple holder class for a record and its associated content.

RecordLifecycle

interface RecordLifecycle

Represents the lifecycle of a navigation record in a NavigableCircuitContent. Will typically be stored in the LocalRecordLifecycle composition local, allowing presenters and UIs to observe whether the navigation record is active.

Properties

var CircuitContext.circuit: Circuit

The Circuit used in this context.

val LocalBackStack: ProvidableCompositionLocal<BackStack<out BackStack.Record>?>

Delicate API to access the BackStack from within a CircuitContent or rememberAnsweringNavigator composable, useful for cases where we create nested nav handling.

val LocalCircuit: ProvidableCompositionLocal<Circuit?>

CompositionLocal with a current Circuit instance.

LocalRecordLifecycle

val LocalRecordLifecycle: ProvidableCompositionLocal<RecordLifecycle>

Holds the current lifecycle for a record in a NavigableCircuitContent.

Functions

answeringNavigationAvailable

fun answeringNavigationAvailable(): Boolean

Returns whether or not answering navigation is available. This is essentially a proxy for whether or not this composition is running within a NavigableCircuitContent.

CircuitCompositionLocals

fun CircuitCompositionLocals(circuit: Circuit, retainedStateRegistry: RetainedStateRegistry = continuityRetainedStateRegistry(), content: @Composable () -> Unit)

Provides the given circuit as a CompositionLocal to all composables within content. Also adds any other composition locals that Circuit needs.

fun CircuitContent(screen: Screen, modifier: Modifier = Modifier, circuit: Circuit = requireNotNull(LocalCircuit.current), unavailableContent: @Composable (screen: Screen, modifier: Modifier) -> Unit = circuit.onUnavailableContent, key: Any? = screen)

fun CircuitContent(screen: Screen, modifier: Modifier = Modifier, onNavEvent: (event: NavEvent) -> Unit, circuit: Circuit = requireNotNull(LocalCircuit.current), unavailableContent: @Composable (screen: Screen, modifier: Modifier) -> Unit = circuit.onUnavailableContent, key: Any? = screen)

fun CircuitContent(screen: Screen, navigator: Navigator, modifier: Modifier = Modifier, circuit: Circuit = requireNotNull(LocalCircuit.current), unavailableContent: @Composable (screen: Screen, modifier: Modifier) -> Unit = circuit.onUnavailableContent, key: Any? = screen)

fun <UiState : CircuitUiState> CircuitContent(screen: Screen, presenter: Presenter<UiState>, ui: Ui<UiState>, modifier: Modifier = Modifier, eventListener: EventListener = EventListener.NONE, key: Any? = screen, presentWithLifecycle: Boolean = LocalCircuit.current?.presentWithLifecycle == true)

fun CircuitPreview(content: @Composable () -> Unit)

A composable function that provides no-op/empty Circuit composition locals that can be safely used within a @Preview composable.

NavigableCircuitContent

fun <R : BackStack.Record> NavigableCircuitContent(navigator: Navigator, backStack: BackStack<R>, modifier: Modifier = Modifier, circuit: Circuit = requireNotNull(LocalCircuit.current), providedValues: ImmutableMap<out BackStack.Record, ProvidedValues> = providedValuesForBackStack(backStack), decoration: NavDecoration = circuit.defaultNavDecoration, unavailableRoute: @Composable (screen: Screen, modifier: Modifier) -> Unit = circuit.onUnavailableContent)

fun Navigator(backStack: BackStack<out BackStack.Record>, onRootPop: (result: PopResult?) -> Unit): Navigator

Creates a new Navigator.

fun Navigator.onNavEvent(event: NavEvent)

A Circuit call back to help navigate to different screens. Intended to be used when forwarding NavEvents from nested Presenters.

fun <T> pausableState(key: String? = null, isActive: Boolean = LocalRecordLifecycle.current.isActive, produceState: @Composable () -> T): T

Wraps a composable state producer, which will replay the last emitted state instance when isActive is false.

presentWithLifecycle

inline fun <UiState : CircuitUiState> Presenter<UiState>.presentWithLifecycle(key: String? = null, isActive: Boolean = LocalRecordLifecycle.current.isActive): UiState

Presents the UI state when the lifecycle is resumed, otherwise will replay the last emitted UI state.

rememberAnsweringNavigator

inline fun <T : PopResult> rememberAnsweringNavigator(backStack: BackStack<out BackStack.Record>, noinline block: suspend CoroutineScope.(result: T) -> Unit): GoToNavigator

inline fun <T : PopResult> rememberAnsweringNavigator(fallbackNavigator: Navigator, noinline block: suspend CoroutineScope.(result: T) -> Unit): GoToNavigator

A reified version of rememberAnsweringNavigator. See documented overloads of this function for more information.

fun <T : PopResult> rememberAnsweringNavigator(backStack: BackStack<out BackStack.Record>, resultType: KClass<T>, block: suspend CoroutineScope.(result: T) -> Unit): GoToNavigator

Returns a GoToNavigator that answers with the given resultType using the given backStack.

fun <T : PopResult> rememberAnsweringNavigator(fallbackNavigator: Navigator, resultType: KClass<T>, block: suspend CoroutineScope.(result: T) -> Unit): GoToNavigator

Returns a GoToNavigator that answers with the given resultType or defaults to fallbackNavigator if no back stack is available to pass results through.

rememberCircuitNavigator

fun rememberCircuitNavigator(backStack: BackStack<out BackStack.Record>, enableBackHandler: Boolean = true): Navigator

Returns a new Navigator for navigating within CircuitContents. Delegates onRootPop to the LocalOnBackPressedDispatcherOwner.

fun rememberCircuitNavigator(backStack: BackStack<out BackStack.Record>, onRootPop: (result: PopResult?) -> Unit): Navigator

Creates and remembers a new Navigator for navigating within CircuitContents.

rememberEventListener

inline fun rememberEventListener(screen: Screen, context: CircuitContext = CircuitContext.EMPTY, startOnInit: Boolean = true, factory: EventListener.Factory? = null): EventListener

Remembers a new EventListener instance for the given screen and context.

rememberPresenter

inline fun rememberPresenter(screen: Screen, navigator: Navigator = Navigator.NoOp, context: CircuitContext = CircuitContext.EMPTY, eventListener: EventListener = EventListener.NONE, factory: Presenter.Factory): Presenter<CircuitUiState>?

Remembers a new Presenter instance for the given screen, navigator, context, and eventListener.

inline fun rememberUi(screen: Screen, context: CircuitContext = CircuitContext.EMPTY, eventListener: EventListener = EventListener.NONE, factory: Ui.Factory): Ui<CircuitUiState>?

Remembers a new Ui instance for the given screen, context, and eventListener.