Spotlight¶

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¶

enum class State {
    INACTIVE_BEFORE, ACTIVE, INACTIVE_AFTER;
}

Constructing spotlight¶

Requires defining items and an active index.

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.

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.

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.

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.