Enhances state management and navigation in Compose applications by integrating a port of the Flutter Bloc library with a modified Voyager navigation library, offering improved cross-platform capabilities.
A port for Compose of flutter bloc for better state management integrated with a navigation library (a fork of voyager library)
Add Maven Central to your repositories if needed
repositories {
mavenCentral()
}
Add the main library dependency to your module build.gradle.
// Bloc+Navigator core library
implementation "io.github.beyondeye:kbloc-navigator:$version"
For available versions look at compose_bloc releases the library is a multiplatform library that support Android and Desktop and Web compose.
State management in Compose as described in the compose documentation is basically relying on Android ViewModel This is very limiting in general and in particular if we want to develop for multiple platforms not only for Android.
A similar and connected problem is the way the official compose docs expect developers to handle navigation, relying on the Android specific Jetpack Navigation Library
Navigation is such a fundamental component of an app architecture that this makes porting to another platform very time consuming.
Flutter, also from Google, have a very similar architecture to Android Compose and has actually inspired a lot the development of Compose. Flutter is much more mature than Compose so we thought to look at how state management is handled there.
Flutter documentation has a list of the possible recommended ways to handle complex state management The list is quite impressive, with a lot of options that can fit the needs of any developer. By the ways almost all the options listed in the official Flutter docs are actually open source third party libraries. This is very typical of Flutter, which embrace open source and community developed library much more than Android.
Among all the options there, we were particular impressed by the BloC library by Felix Angelov. This is one of the most popular Flutter libraries with almost 10k stars on github, very mature (already version 8), and very well integrated with Flutter architecture (which as we said is very similar to Compose). So we decided to port it for Android Compose.
The result of this work is this library. Because state management is usually linked to specific app screens and their lifecycle, we found the need to integrate state management with navigation. So we have integrated our port of flutter_bloc with a fork of the Voyager navigation library for compose multiplatform, that is one of the most popular 3rd party navigation library for Compose.
Voyager is generally a very well designed library but is currently unmantained, with several outstanding issues and bugs, that we fixed in our fork of the library.
The original package for the code from the original library has been preserved, so switching
to kbloc in the dependencies should work seamlessy:
dependencies {
// Navigator: (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-navigator:$currentVersion"
implementation "io.github.beyondeye:kbloc-navigator:$currentVersion"
// BottomSheetNavigator (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-bottom-sheet-navigator:$currentVersion"
implementation "io.github.beyondeye:kbloc-bottom-sheet-navigator:$currentVersion"
// TabNavigator (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-tab-navigator:$currentVersion"
implementation "io.github.beyondeye:kbloc-tab-navigator:$currentVersion"
// Transitions (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-transitions:$currentVersion"
implementation "io.github.beyondeye:kbloc-transitions:$currentVersion"
// Android ViewModel integration (android library)
//implementation "cafe.adriel.voyager:voyager-androidx:$currentVersion"
implementation "io.github.beyondeye:kbloc-androidx:$currentVersion"
// Koin integration (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-koin:$currentVersion"
implementation "io.github.beyondeye:kbloc-koin:$currentVersion"
// Kodein integration ( (multiplatform library)
//implementation "cafe.adriel.voyager:voyager-kodein:$currentVersion"
implementation "io.github.beyondeye:kbloc-kodein:$currentVersion"
// Hilt integration (android library)
//implementation "cafe.adriel.voyager:voyager-hilt:$currentVersion"
implementation "io.github.beyondeye:kbloc-hilt:$currentVersion"
// RxJava integration (JVM library)
//implementation "cafe.adriel.voyager:voyager-rxjava:$currentVersion"
implementation "io.github.beyondeye:kbloc-rxjava:$currentVersion"
// LiveData integration (android library)
//implementation "cafe.adriel.voyager:voyager-livedata:$currentVersion"
implementation "io.github.beyondeye:kbloc-livedata:$currentVersion"
}
class MainScreen: Screen {
@Composable
override fun Content() {
}
}
: () {
{
.onCreate(savedInstanceState)
setContent {
RootNavigator(MainScreen())
}
}
}
Currently the original voyager library does not seems to be mantained any more. I will be quite happy to join forces with the original author(s), if they will decide that they are interested. The original library was well designed and I learned a lot about Compose and Multiplatform Kotlin while working on this fork.
Copyright 2022 by Dario Elyasy see details here
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//standard setContent to define UI for an activity with Compose
setContent {
//use RootNavigator to initialize compose_bloc navigator for activity
RootNavigator(MainScreen(userName="Albert Einstein"))
}
}
}
// A Screen is what the name suggests, and is the basic UI entity to which you can
// navigate to with a Navigator. Entities associated with a Screen like a ScreenModel
// or Bloc are automatically disposed when a Screen is disposed, for example when we
// receive an "onBackPressed" event in a Screen.
// Note that a Screen must be Serializable, so that its fields, that you can think as
// it "arguments" can be saved and restored when an Activity is paused and then restarted
// or when screen is rotated.
class MainScreen(val userName:String): Screen {
override fun Content() {
// the current navigator, in this case it is the root navigator.
// It is possible to define nested navigators
val navigator= LocalNavigator.currentOrThrow
Compose_blocTheme {
Scaffold(
topBar = { TopAppBar{ Text("Counter test app") } },
backgroundColor = MaterialTheme.colors.background,
Column {
Text("Hello $userName")
// when the user click the button we navigate to a new screen
Button(onClick={ navigator.push(CounterScreen())})
{ Text("click to open Counter Screen") }
}
}
)
}
}
}
// The idea behind the Bloc architecture, very similar to Redux, is that we
// don't modify directly the state of the application (the state associated to the Bloc)
// but instead we send events ("actions" in Redux) that are processed
// by the Bloc registered event handlers
// Here is the definition of the events CounterBloc can handle, all events
// must inherit to some base event type that the bloc is supposed to handle
interface CounterEvent
class AdditionEvent(val value:Int):CounterEvent
class SubtractionEvent(val value:Int):CounterEvent
// this is the state of the bloc. It should be an immutable object, that we don't
// update in-place. instead we create a new instance with the modified values.
// a data class is perfect for this purpose
data class CounterState(val counter:Int=0)
// here we define the Bloc itself. The bloc wrap together
// - some application state (CounterState)
// - associated event handlers to handle changes to the application state
// - a kotlin Flow with the current value of the bloc state, that we can transform to
// compose MutableState and listen to, for automatically updating the UI
// on state changes
class CounterBloc(cscope: CoroutineScope, startCounter:Int=0):
Bloc<CounterEvent, CounterState>(
// every bloc has an associated coroutineScope that is automatically cancelled
// when the bloc is disposed.
cscope, CounterState(startCounter),false)
{
// in the bloc constructor we define the bloc event handlers
init {
// each event handler define a function that is called when
// an event of the specified type is received. the function
// has two arguments
// - the received event
// - an "emit" method to call to emit the updated state according to
// the received event.
// Note that unlike Redux reducers, event handler are not necessarily pure
// function without side-effects. On the contrary there can be event handlers
// whose only purpose are their side effects, and that do not emit a new state
// at all. Use the coroutine scope associated to the bloc to run the side effects
on<AdditionEvent> { event, emit ->
val s=state
emit(s.copy(counter =s.counter+event.value ))
}
on<SubtractionEvent> { event, emit ->
val s=state
emit(s.copy(counter =s.counter-event.value ))
}
}
}
class CounterScreen: Screen {
override fun Content() {
Column(modifier=Modifier.fillMaxWidth(),
horizontalAlignment = Alignment.CenterHorizontally) {
// out of the BlocProvider composable subtree the bloc is not available
val bnull= rememberProvidedBlocOf<CounterBloc>()
Log.e(LOGTAG,"obtained bnull counter bloc: $bnull") //this must be null
// BlocProvider makes available the specified bloc (CounterBloc)
// to the associated composable subtree
BlocProvider(create = {cscope-> CounterBloc(cscope,1)} ) {
//rememberProvidedBlocOf is similar to dependency injection:
// it retrieves the specified bloc type as defined by the closest
// enclosing BlocProvider
val b= rememberProvidedBlocOf<CounterBloc>()?:return@BlocProvider
// define some callbacks to wrap sending events to the bloc so
// that the actual UI does need to know anything about the bloc
val onIncrement = { b.add(AdditionEvent(1)) }
val onDecrement = { b.add(SubtractionEvent(1) }
//BlocBuilder search for the specified bloc type as defined by
// the closest enclosing blocProvider and subscribes to its states
// updates, as a Composable mutableState that when changes trigger
// recomposition
BlocBuilder(b) { counterState->
//this is the actual ui composable
CounterControls(
"Counter display updated always",
counterState.counter,
onDecrement, onIncrement)
}
}
// out of the BlocProvider composable subtree the bloc is not available
val bnull2= rememberProvidedBlocOf<CounterBloc>()
Log.e(LOGTAG,"obtained bnull2 counter bloc: $bnull2") //this must be null
}
}
}
fun CounterControls(
explanatoryText:String,
counterValue: Int,
onDecrement: () -> Unit,
onIncrement: () -> Unit
) {
Text(explanatoryText)
Text("Counter value: ${counterValue}")
Row {
Button(
onClick = onDecrement,
modifier = Modifier.padding(horizontal = 8.dp)
) { Text(text = "-") }
Button(
onClick = onIncrement,
modifier = Modifier.padding(horizontal = 8.dp)
) { Text(text = "+") }
}
}
original voyager does not support Compose Web
original voyager does not support path-based navigation.
voyager-androidx now work differently: all lifecycle handling hooks from the original code have been removed
(AndroidScreenLifecycleOwner is not used anymore). This is because it caused many issues:
see for example issue 62.
But this does not mean that android lifecycle events are ignored. When an activity is destroyed
then all associated ScreenModels and Blocs are automatically disposed and the associated flows cancelled
Also flows associated to blocs of an Activity are automatically paused when the Activity is paused
Now Screen lifecycle is handled in the following way: A Screen (and associated screen model and blocs)
is disposed in the following cases
Screen is popped from the navigator stackActivity where the Screen composable was started is destroyedIn order to all this to work, now is required to declare the top level navigator in an
activity with RootNavigator:
Surfaced from shared tags and platforms — no rankings paid for.