Indication.kt

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.compose.foundation

import androidx.compose.runtime.Composable
import androidx.compose.runtime.RememberObserver
import androidx.compose.runtime.Stable
import androidx.compose.runtime.remember
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.graphics.drawscope.ContentDrawScope
import androidx.compose.ui.draw.DrawModifier
import androidx.compose.ui.Modifier
import androidx.compose.ui.composed
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.debugInspectorInfo

/**
 * Indication represents visual effects that occur when certain interactions happens. For
 * example: showing a ripple effect when a component is touched, or a highlight when a component
 * is focused.
 *
 * An instance of Indication is a factory that is required to produce [IndicationInstance]s on
 * demand for each component that uses an [indication] modifier using [createInstance].
 *
 * Indication is typically provided throughout the hierarchy through [LocalIndication] - you can
 * provide a custom Indication to [LocalIndication] to change the default [Indication] used for
 * components such as [clickable].
 */
@Stable
interface Indication {

    /**
     * Creates a new [IndicationInstance]. Typically this will be called by [indication],
     * so one [IndicationInstance] will be used for one component that draws [Indication],
     * such as a button.
     */
    @Composable
    fun createInstance(): IndicationInstance
}

/**
 * IndicationInstance is a specific instance of an [Indication] that draws visual effects on
 * certain interactions, such as press or focus.
 *
 * IndicationInstances can be stateful or stateless, and are created by
 * [Indication.createInstance] - they should be used in-place and not re-used between different
 * [indication] modifiers.
 */
interface IndicationInstance {

    /**
     * Draws visual effects based on [InteractionState].
     *
     * Usually, in this method indication reads [InteractionState] to observe its value and draw
     * any visuals to reflect this state. Refer to the [Interaction] to see what states are
     * possible and draw visual effects when [InteractionState] contains them.
     *
     * This method MUST call [ContentDrawScope.drawContent] at some point in order to draw the
     * component itself underneath any indication. Typically this is called at the beginning, so
     * that indication can be drawn as an overlay on top.
     *
     * @param interactionState [InteractionState] representing the combined state of interactions
     * occurring on the component the indication is drawn for.
     */
    fun ContentDrawScope.drawIndication(interactionState: InteractionState)

    /**
     * Callback which is invoked when this [IndicationInstance] is removed from composition. Use
     * this callback to free up any allocated resources, stop on-going animations, and other
     * related cleanup.
     */
    fun onDispose() {}
}

/**
 * Draws visual effects for this component when interactions occur.
 *
 * @sample androidx.compose.foundation.samples.IndicationSample
 *
 * @param interactionState [InteractionState] that will be used by [indication] to draw visual
 * effects - this [InteractionState] represents the combined state of all interactions currently
 * present on this component.
 * @param indication [Indication] used to draw visual effects. If `null`, no visual effects will
 * be shown for this component.
 */
fun Modifier.indication(
    interactionState: InteractionState,
    indication: Indication? = null
) = composed(
    factory = {
        val resolvedIndication = indication ?: NoIndication
        val instance = resolvedIndication.createInstance()
        remember(interactionState, instance) {
            IndicationModifier(interactionState, instance)
        }
    },
    inspectorInfo = debugInspectorInfo {
        name = "indication"
        properties["indication"] = indication
        properties["interactionState"] = interactionState
    }
)

/**
 * CompositionLocal that provides an [IndicationInstance] to draw visual indication for press and
 * other events.
 *
 * By default this will provide [DefaultDebugIndication].
 */
@Deprecated(
    "Renamed to LocalIndication",
    replaceWith = ReplaceWith(
        "LocalIndication",
        "androidx.compose.foundation.LocalIndication"
    )
)
val AmbientIndication get() = LocalIndication

/**
 * CompositionLocal that provides an [Indication] through the hierarchy. This [Indication] will
 * be used by default to draw visual effects for interactions such as press and drag in components
 * such as [clickable].
 *
 * By default this will provide [DefaultDebugIndication].
 */
val LocalIndication = staticCompositionLocalOf<Indication> {
    DefaultDebugIndication
}

private object NoIndication : Indication {
    private object NoIndicationInstance : IndicationInstance {
        override fun ContentDrawScope.drawIndication(interactionState: InteractionState) {
            drawContent()
        }
    }

    @Composable
    override fun createInstance(): IndicationInstance = NoIndicationInstance
}

/**
 * Simple default [Indication] that draws a rectangular overlay when pressed.
 */
private object DefaultDebugIndication : Indication {

    private object DefaultDebugIndicationInstance : IndicationInstance {
        override fun ContentDrawScope.drawIndication(interactionState: InteractionState) {
            drawContent()
            if (interactionState.contains(Interaction.Pressed)) {
                drawRect(color = Color.Black.copy(alpha = 0.3f), size = size)
            }
        }
    }

    @Composable
    override fun createInstance(): IndicationInstance {
        return DefaultDebugIndicationInstance
    }
}

private class IndicationModifier(
    val interactionState: InteractionState,
    val indicationInstance: IndicationInstance
) : RememberObserver, DrawModifier {

    override fun ContentDrawScope.draw() {
        with(indicationInstance) {
            drawIndication(interactionState)
        }
    }

    override fun onRemembered() { }

    override fun onForgotten() {
        indicationInstance.onDispose()
    }

    override fun onAbandoned() {
        indicationInstance.onDispose()
    }
}