coco
130 lines
3.2 KiB
Markdown
130 lines
3.2 KiB
Markdown
# Spotlight
|
|
|
|
<img src="https://i.imgur.com/xtPRfij.gif" width="200">
|
|
|
|
Implements a mechanism analogous to a view pager; has a single active element ("it's in the spotlight", hence the name), but unlike the back stack, it does not remove other elements.
|
|
|
|
It's great for flows or tabbed containers.
|
|
|
|
## States
|
|
|
|
```kotlin
|
|
enum class State {
|
|
INACTIVE_BEFORE, ACTIVE, INACTIVE_AFTER;
|
|
}
|
|
```
|
|
|
|
## Constructing spotlight
|
|
|
|
Requires defining items and an active index.
|
|
|
|
```kotlin
|
|
class Spotlight<NavTarget : Any>(
|
|
items: List<NavTarget>,
|
|
initialActiveIndex: Int = 0,
|
|
savedStateMap: SavedStateMap?,
|
|
// Optional parameters are omitted
|
|
)
|
|
```
|
|
|
|
## Default on screen resolution
|
|
|
|
As a default, only the active element is considered on screen.
|
|
|
|
```kotlin
|
|
object SpotlightOnScreenResolver : OnScreenStateResolver<Spotlight.State> {
|
|
override fun isOnScreen(state: Spotlight.State): Boolean =
|
|
when (state) {
|
|
Spotlight.State.INACTIVE_BEFORE,
|
|
Spotlight.State.INACTIVE_AFTER -> false
|
|
Spotlight.State.ACTIVE -> true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Default transition handlers
|
|
|
|
#### SpotlightFader
|
|
|
|
`rememberSpotlightFader()`
|
|
|
|
Adds simple cross-fading transitions
|
|
|
|
|
|
#### SpotlightSlider
|
|
|
|
`rememberSpotlightSlider()`
|
|
|
|
Adds horizontal sliding transitions so that the `ACTIVE` element is in the center; other states are animated from / to the left or the right edge of the screen, depending on the order of them in the `items` property.
|
|
|
|
|
|
## Operations
|
|
|
|
#### Activate
|
|
|
|
`spotlight.activate(navTarget)`
|
|
|
|
Transitions the element to `ACTIVE`. Transitions other elements to `INACTIVE_BEFORE` or `INACTIVE_AFTER` depending on their relative position to the activated element.
|
|
|
|
|
|
#### Next
|
|
|
|
`spotlight.next()`
|
|
|
|
Transitions the currently active element to `INACTIVE_BEFORE`.
|
|
Transitions the element after the currently active one to `ACTIVE`.
|
|
|
|
|
|
#### Previous
|
|
|
|
`spotlight.previous()`
|
|
|
|
Transitions the currently active element to `INACTIVE_AFTER`.
|
|
Transitions the element before the currently active one to `ACTIVE`.
|
|
|
|
|
|
#### Update elements
|
|
|
|
`spotlight.updateElements(items, activeIndex)`
|
|
|
|
Replaces elements held by the spotlight instance with a new list. Transitions new elements to `INACTIVE_BEFORE`, `ACTIVE`, or `INACTIVE_AFTER` depending on their position in the provided list relative to `activeIndex`.
|
|
|
|
|
|
## Back press strategy
|
|
|
|
You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
|
|
|
|
```kotlin
|
|
class Spotlight<NavTarget : Any>(
|
|
/* ... */
|
|
backPressHandler: BackPressHandlerStrategy<NavTarget, State> = GoToDefault(
|
|
initialActiveIndex
|
|
)
|
|
/* ... */
|
|
)
|
|
```
|
|
|
|
#### GoToDefault
|
|
|
|
The default back press handling strategy. Activates the default index.
|
|
|
|
#### GoToPrevious
|
|
|
|
Runs a `Previous` operation.
|
|
|
|
|
|
## Operation strategy
|
|
|
|
You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
|
|
|
|
```kotlin
|
|
class Spotlight<NavTarget : Any>(
|
|
/* ... */
|
|
operationStrategy: OperationStrategy<NavTarget, State> = ExecuteImmediately(),
|
|
/* ... */
|
|
)
|
|
```
|
|
|
|
#### ExecuteImmediately
|
|
The default strategy. New operations are executed without any questions, regardless of any already running transitions.
|