magnifier

Modifier in Compose Foundation

Shows a [Magnifier] widget that shows an enlarged version of the content at [sourceCenter] relative to the current layout node.

This function returns a no-op modifier on API levels below P (28), since the framework does not support the [Magnifier] widget on those levels. However, even on higher API levels, not all magnifier features are supported on all platforms. Please refer to parameter explanations below to learn more about supported features on different platform versions.

This function does not allow configuration of [source bounds][Magnifier.Builder.setSourceBounds] since the magnifier widget does not support constraining to the bounds of composables.

Last updated: 2024-09-07 14:23

Installation

dependencies {
   implementation("androidx.compose.foundation:foundation:1.8.0-alpha01")
}

Overloads

fun Modifier.magnifier(
    sourceCenter: Density.() -> Offset,
    magnifierCenter: (Density.() -> Offset)? = null,
    onSizeChanged: ((DpSize) -> Unit)? = null,
    zoom: Float = Float.NaN,
    size: DpSize = DpSize.Unspecified,
    cornerRadius: Dp = Dp.Unspecified,
    elevation: Dp = Dp.Unspecified,
    clip: Boolean = true
): Modifier

Parameters

name	description
sourceCenter	The offset of the center of the magnified content. Measured in pixels from the top-left of the layout node this modifier is applied to. This offset is passed to [Magnifier.show].
magnifierCenter	The offset of the magnifier widget itself, where the magnified content is rendered over the original content. Measured in density-independent pixels from the top-left of the layout node this modifier is applied to. If left null or returns an [unspecified][DpOffset.Unspecified] value, the magnifier widget will be placed at a default offset relative to [sourceCenter]. The value of that offset is specified by the system.
onSizeChanged	An optional callback that will be invoked when the magnifier widget is initialized to report on its actual size. This can be useful when [size] parameter is left unspecified.
zoom	See [Magnifier.setZoom]. Only supported on API 29+.
size	See [Magnifier.Builder.setSize]. Only supported on API 29+.
cornerRadius	See [Magnifier.Builder.setCornerRadius]. Only supported on API 29+.
elevation	See [Magnifier.Builder.setElevation]. Only supported on API 29+.
clip	See [Magnifier.Builder.setClippingEnabled]. Only supported on API 29+.

Code Example

MagnifierSample

@Composable
fun MagnifierSample() {
    // When the magnifier center position is Unspecified, it is hidden.
    // Hide the magnifier until a drag starts.
    var magnifierCenter by remember { mutableStateOf(Offset.Unspecified) }

    if (Build.VERSION.SDK_INT < 28) {
        Text("Magnifier is not supported on this platform.")
    } else {
        Box(
            Modifier.magnifier(sourceCenter = { magnifierCenter }, zoom = 2f)
                .pointerInput(Unit) {
                    detectDragGestures(
                        // Show the magnifier at the original pointer position.
                        onDragStart = { magnifierCenter = it },
                        // Make the magnifier follow the finger while dragging.
                        onDrag = { _, delta -> magnifierCenter += delta },
                        // Hide the magnifier when the finger lifts.
                        onDragEnd = { magnifierCenter = Offset.Unspecified },
                        onDragCancel = { magnifierCenter = Offset.Unspecified }
                    )
                }
                .drawBehind {
                    // Some concentric circles to zoom in on.
                    for (diameter in 2 until size.maxDimension.toInt() step 10) {
                        drawCircle(color = Color.Black, radius = diameter / 2f, style = Stroke())
                    }
                }
        )
    }
}