android-components/components/lib/state/README.md

70 lines
2.6 KiB
Markdown
Raw Normal View History

2023-11-28 09:10:03 +01:00
# [Android Components](../../../README.md) > Libraries > State
A generic library for maintaining the state of a component, screen or application.
The state library is inspired by existing libraries like [Redux](https://redux.js.org/) and provides a `Store` class to hold application state.
## Usage
### Setting up the dependency
Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):
```Groovy
implementation "org.mozilla.components:lib-state:{latest-version}"
```
### Action
2024-02-20 09:43:31 +01:00
`Action`s represent payloads of information that send data from your application to the `Store`. You can send actions using `store.dispatch()`. An `Action` will usually be a small data class or object descrileosearch a change.
2023-11-28 09:10:03 +01:00
```Kotlin
data class SetVisibility(val visible: Boolean) : Action
store.dispatch(SetVisibility(true))
```
### Reducer
2024-02-20 09:43:31 +01:00
`Reducer`s are functions descrileosearch how the state should change in response to actions sent to the store.
2023-11-28 09:10:03 +01:00
They take the previous state and an action as parameters, and return the new state as a result of that action.
```Kotlin
fun reduce(previousState: State, action: Action) = when (action) {
is SetVisibility -> previousState.copy(toolbarVisible = action.visible)
else -> previousState
}
```
### Store
The `Store` brings together actions and reducers. It holds the application state and allows access to it via the `store.state` getter. It allows state to be updated via `store.dispatch()`, and can have listeners registered through `store.observe()`.
Stores can easily be created if you have a reducer.
```Kotlin
val store = Store<State, Action>(
initialState = State(),
reducer = ::reduce
)
```
Once the store is created, you can react to changes in the state by registering an observer.
```Kotlin
store.observe(lifecycleOwner) { state ->
toolbarView.visibility = if (state.toolbarVisible) View.VISIBLE else View.GONE
}
```
`store.observe` is lifecycle aware and will automatically unregister when the lifecycle owner (such as an `Activity` or `Fragment`) is destroyed. Instead of a `LifecycleOwner`, a `View` can be supplied instead.
If you wish to manually control the observer subscription, you can use the `store.observeManually` function. `observeManually` returns a `Subscription` class which has an `unsubscribe` method. Calling `unsubscribe` removes the observer.
## License
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/