Essenty
The most essential libraries for Kotlin Multiplatform development.
Supported targets:
androidjvmjs(IRandLEGACY)iosArm64,iosX64watchosArm32,watchosArm64,watchosX64tvosArm64,tvosX64macosX64linuxX64
Lifecyle
When writing Kotlin Multiplatform (common) code we often need to handle lifecycle events of a screen. For example, to stop background operations when the screen is destroyed, or to reload some data when the screen is activated. Essenty provides the Lifecycle API to help with lifecycle handling in the common code. It is very similar to Android Activity lifecycle.
Setup
Groovy:
// Add the dependency, typically under the commonMain source set
implementation "com.arkivanov.essenty:lifecycle:<essenty_version>"
Kotlin:
// Add the dependency, typically under the commonMain source set
implementation("com.arkivanov.essenty:lifecycle:<essenty_version>")
Lifecycle state transitions
Content
The main Lifecycle interface provides ability to observe the lifecycle state changes.
The LifecycleRegistry interface extends both the Lifecycle and the Lifecycle.Callbacks at the same time. It can be used to manually control the lifecycle, for example in tests.
The LifecycleOwner just holds the Lifecyle. It may be implemented by an arbitrary class, to provide convenient API.
Android extensions
From Android, the Lifecycle can be obtained by using special functions, can be found here.
Usage example
The lifecycle can be observed using its subscribe/unsubscribe methods:
import com.arkivanov.essenty.lifecycle.Lifecycle
class SomeLogic(lifecycle: Lifecycle) {
init {
lifecycle.subscribe(
object : Lifecycle.Callbacks {
override fun onCreate() {
// Handle lifecycle created
}
// onStart, onResume, onPause, onStop are also available
override fun onDestroy() {
// Handle lifecycle destroyed
}
}
)
}
}
Or using the extension functions:
import com.arkivanov.essenty.lifecycle.Lifecycle
import com.arkivanov.essenty.lifecycle.doOnCreate
import com.arkivanov.essenty.lifecycle.doOnDestroy
import com.arkivanov.essenty.lifecycle.subscribe
class SomeLogic(lifecycle: Lifecycle) {
init {
lifecycle.subscribe(
onCreate = { /* Handle lifecycle created */ },
// onStart, onResume, onPause, onStop are also available
onDestroy = { /* Handle lifecycle destroyed */ }
)
lifecycle.doOnCreate {
// Handle lifecycle created
}
// doOnStart, doOnResume, doOnPause, doOnStop are also available
lifecycle.doOnDestroy {
// Handle lifecycle destroyed
}
}
}
Parcelable and Parcelize
Essenty brings both Android Parcelable interface and the @Parcelize annotation from kotlin-parcelize compiler plugin to Kotlin Multiplatform, so they both can be used in common code. This is typically used for state/data preservation over Android configuration changes, when writing common code targeting Android.
Setup
Groovy:
plugins {
id "kotlin-parcelize" // Apply the plugin for Android
}
// Add the dependency, typically under the commonMain source set
implementation "com.arkivanov.essenty:parcelable:<essenty_version>"
Kotlin:
plugins {
id("kotlin-parcelize") // Apply the plugin for Android
}
// Add the dependency, typically under the commonMain source set
implementation("com.arkivanov.essenty:parcelable:<essenty_version>")
Usage example
Once the dependency is added and the plugin is applied, we can use it as follows:
import com.arkivanov.essenty.parcelable.Parcelable
import com.arkivanov.essenty.parcelable.Parcelize
@Parcelize
data class User(
val id: Long,
val name: String
) : Parcelable
When compiled for Android, the Parcelable implementation will be generated automatically. When compiled for other targets, it will be just a regular class without any extra generated code.
Parcelize for Darwin/Apple targets
Currently there is no extra code generated when compiled for Darwin/Apple targets. However I made a proof of concept: kotlin-parcelize-darwin compiler plugin. It is not used yet by Essenty, and the applicabilty is being considered. Please raise a Discussion if you are interested.
StateKeeper
When writing common code targetting Android, it might be required to preserve some data over Android configuration changes or process death. For this purpose, Essenty provides the StateKeeper API, which is inspired by the AndroidX SavedStateHandle. The StateKeeper API relies on the Parcelable interface provided by the parcelable module described above.
Setup
Groovy:
// Add the dependency, typically under the commonMain source set
implementation "com.arkivanov.essenty:state-keeper:<essenty_version>"
Kotlin:
// Add the dependency, typically under the commonMain source set
implementation("com.arkivanov.essenty:state-keeper:<essenty_version>")
Content
The main StateKeeper interface provides ability to register/unregister state suppliers, and also to consume any previously saved state.
The StateKeeperDispatcher interface extens StateKeeper and allows state saving, by calling all registered state providers.
The StateKeeperOwner interface is just a holder of StateKeeper. It may be implemented by an arbitrary class, to provide convenient API.
Android extensions
From Android side, StateKeeper can be obtained by using special functions, can be found here.
Usage example
import com.arkivanov.essenty.parcelable.Parcelable
import com.arkivanov.essenty.parcelable.Parcelize
import com.arkivanov.essenty.statekeeper.StateKeeper
import com.arkivanov.essenty.statekeeper.consume
class SomeLogic(stateKeeper: StateKeeper) {
// Use the saved State if any, otherwise create a new State
private var state: State = stateKeeper.consume("SAVED_STATE") ?: State()
init {
// Register the State supplier
stateKeeper.register("SAVED_STATE") { state }
}
@Parcelize
private class State(
val someValue: Int = 0
) : Parcelable
}
InstanceKeeper
When writing common code targetting Android, it might be required to retain objects over Android configuration changes. This use case is covered by the InstanceKeeper API, which is similar to the AndroidX ViewModel.
Setup
Groovy:
// Add the dependency, typically under the commonMain source set
implementation "com.arkivanov.essenty:instance-keeper:<essenty_version>"
Kotlin:
// Add the dependency, typically under the commonMain source set
implementation("com.arkivanov.essenty:instance-keeper:<essenty_version>")
Content
The main InstanceKeeper interface is responsible for storing object instances, represented by the [InstanceKeeper.Instance] interface. Instances of the InstanceKeeper.Instance interface survive Android Configuration changes, the InstanceKeeper.Instance.onDestroy() method is called when InstanceKeeper goes out of scope (e.g. the screen is finished).
The InstanceKeeperDispatcher interface extens InstanceKeeper and adds ability to destroy all registered instances.
The InstanceKeeperOwner interface is just a holder of InstanceKeeper. It may be implemented by an arbitrary class, to provide convenient API.
Android extensions
From Android side, InstanceKeeper can be obtained by using special functions, can be found here.
Usage example
import com.arkivanov.essenty.instancekeeper.InstanceKeeper
import com.arkivanov.essenty.instancekeeper.getOrCreate
class SomeLogic(instanceKeeper: InstanceKeeper) {
// Get the existing instance or create a new one
private val thing: RetainedThing = instanceKeeper.getOrCreate { RetainedThing() }
}
/*
* Survives Android configuration changes.
* ⚠️ Pay attention to not leak any dependencies.
*/
class RetainedThing : InstanceKeeper.Instance {
override fun onDestroy() {
// Called when the screen is finished
}
}
BackPressedDispatcher
The BackPressedDispatcher API provides ability to handle back button clicks (e.g. an Android device's back button), in common code. This API is similar to AndroidX OnBackPressedDispatcher.
Setup
Groovy:
// Add the dependency, typically under the commonMain source set
implementation "com.arkivanov.essenty:back-pressed:<essenty_version>"
Kotlin:
// Add the dependency, typically under the commonMain source set
implementation("com.arkivanov.essenty:back-pressed:<essenty_version>")
Content
The BackPressedHandler interface provides ability to register/unregister back button handlers. When the device's back button is clicked, all registered handlers are called in reverse order. If a handler returns true then the event is considered as handled and the handling process stops, the remaining handlers are not called. If none of the handlers returned true then the event is considered as unhandled.
The BackPressedDispatcher interface extends BackPressedHandler and is responsible for triggering the registered handlers. The BackPressedDispatcher.onBackPressed() triggers all registered handlers in reverse order, returns true if the event is handled, and false if the event is unhandled.
Android extensions
From Android side, BackPressedDispatcher can be obtained by using special functions, can be found here.
Usage example
TBD
Author
Twitter: @arkann1985
If you like this project you can always 
56 Dec 15, 2022
3 Aug 31, 2022
3 Aug 31, 2022
112 Dec 9, 2022
36 Aug 25, 2022
32 Aug 26, 2022
1 Feb 11, 2022
362 Dec 29, 2022
15 Oct 3, 2022
2 Apr 5, 2022
1.5k Dec 30, 2022
0 Jan 7, 2022
2 Mar 31, 2022
994 Dec 28, 2022
25 Aug 11, 2022
0 May 24, 2022
3 Dec 6, 2022
6 Oct 12, 2022
2 Nov 10, 2022