BringIntoViewRequester.kt
/*
* Copyright 2021 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.relocation
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.relocation.BringIntoViewResponder.Companion.RootBringIntoViewResponder
import androidx.compose.foundation.relocation.BringIntoViewResponder.Companion.ModifierLocalBringIntoViewResponder
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.collection.MutableVector
import androidx.compose.runtime.collection.mutableVectorOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.composed
import androidx.compose.ui.geometry.Rect
import androidx.compose.ui.geometry.toRect
import androidx.compose.ui.layout.LayoutCoordinates
import androidx.compose.ui.layout.onGloballyPositioned
import androidx.compose.ui.modifier.ModifierLocalConsumer
import androidx.compose.ui.modifier.ModifierLocalReadScope
import androidx.compose.ui.platform.debugInspectorInfo
import androidx.compose.ui.unit.toSize
/**
* Can be used to send [bringIntoView] requests. Pass it as a parameter to
* [Modifier.bringIntoView()][bringIntoView].
*
* For instance, you can call [BringIntoViewRequester.bringIntoView][bringIntoView] to
* make all the scrollable parents scroll so that the specified item is brought into parent
* bounds. This sample demonstrates this use case:
*
* Here is a sample where a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringIntoViewSample
*
* Here is a sample where a part of a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringPartOfComposableIntoViewSample
*/
@ExperimentalFoundationApi
sealed interface BringIntoViewRequester {
/**
* Bring this item into bounds by making all the scrollable parents scroll appropriately.
*
* @param rect The rectangle (In local coordinates) that should be brought into view. If you
* don't specify the coordinates, the coordinates of the
* [Modifier.bringIntoViewRequester()][bringIntoViewRequester] associated with this
* [BringIntoViewRequester] will be used.
*
* Here is a sample where a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringIntoViewSample
*
* Here is a sample where a part of a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringPartOfComposableIntoViewSample
*/
suspend fun bringIntoView(rect: Rect? = null)
}
/**
* Create an instance of [BringIntoViewRequester] that can be used with
* [Modifier.bringIntoViewRequester][bringIntoViewRequester]. A child can then call
* [BringIntoViewRequester.bringIntoView] to send a request any scrollable parents so that they
* scroll to bring this item into view.
*
* Here is a sample where a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringIntoViewSample
*
* Here is a sample where a part of a composable is brought into view:
* @sample androidx.compose.foundation.samples.BringPartOfComposableIntoViewSample
*/
@ExperimentalFoundationApi
fun BringIntoViewRequester(): BringIntoViewRequester {
return BringIntoViewRequesterImpl()
}
/**
* This is a modifier that can be used to send bringIntoView requests.
*
* Here is an example where the a [bringIntoViewRequester] can be used to bring an item into parent
* bounds. It demonstrates how a composable can ask its parents to scroll so that the component
* using this modifier is brought into the bounds of all its parents.
* @sample androidx.compose.foundation.samples.BringIntoViewSample
*
* @param bringIntoViewRequester an instance of [BringIntoViewRequester]. This hoisted object can be
* used to send bringIntoView requests to parents of the current composable.
*/
@ExperimentalFoundationApi
fun Modifier.bringIntoViewRequester(
bringIntoViewRequester: BringIntoViewRequester
): Modifier = composed(
inspectorInfo = debugInspectorInfo {
name = "bringIntoViewRequester"
properties["bringIntoViewRequester"] = bringIntoViewRequester
}
) {
val bringIntoViewData = remember { BringIntoViewData(BringRectangleOnScreenRequester()) }
if (bringIntoViewRequester is BringIntoViewRequesterImpl) {
DisposableEffect(bringIntoViewRequester) {
bringIntoViewRequester.bringIntoViewUsages += bringIntoViewData
onDispose { bringIntoViewRequester.bringIntoViewUsages -= bringIntoViewData }
}
}
Modifier
.bringRectangleOnScreenRequester(bringIntoViewData.bringRectangleOnScreenRequester)
.onGloballyPositioned { bringIntoViewData.layoutCoordinates = it }
.then(
remember {
object : ModifierLocalConsumer {
override fun onModifierLocalsUpdated(scope: ModifierLocalReadScope) {
bringIntoViewData.parent = scope.run {
ModifierLocalBringIntoViewResponder.current
}
}
}
}
)
}
@ExperimentalFoundationApi
private class BringIntoViewRequesterImpl : BringIntoViewRequester {
val bringIntoViewUsages: MutableVector<BringIntoViewData> = mutableVectorOf()
override suspend fun bringIntoView(rect: Rect?) {
bringIntoViewUsages.forEach {
val layoutCoordinates = it.layoutCoordinates
if (layoutCoordinates == null || !layoutCoordinates.isAttached) return@forEach
// If the rect is not specified, use a rectangle representing the entire composable.
val sourceRect = rect ?: layoutCoordinates.size.toSize().toRect()
// Convert the rect into parent coordinates.
val rectInParentCoordinates = it.parent.toLocalRect(sourceRect, layoutCoordinates)
if (it.parent == RootBringIntoViewResponder) {
// Use the platform specific API to bring the rectangle on screen.
it.bringRectangleOnScreenRequester.bringRectangleOnScreen(rectInParentCoordinates)
} else {
it.parent.bringIntoView(rectInParentCoordinates)
}
}
}
}
@ExperimentalFoundationApi
private data class BringIntoViewData(
val bringRectangleOnScreenRequester: BringRectangleOnScreenRequester,
var parent: BringIntoViewResponder = RootBringIntoViewResponder,
var layoutCoordinates: LayoutCoordinates? = null
)